# Open Diagnostic Echo & Markdown Reader Relay (ASP compliant)

> Diagnostic echo and reader interfaces operated as an Agent-Shelter Protocol (ASP) sensor. Upstream retrieval is disabled on this host: no endpoint fetches external URLs.

## Protocol procedure for autonomous agents

The discovery documents of this host (this file, the manifest, the OpenAPI description) state one fact for every target: it cannot be retrieved through this host. They are not a record about a particular target, and they carry no proof about a target that an orchestrator could verify. A target-specific terminal state exists only for a request that names the target:

- `GET /v1/reader?url=<target_url>` answers with a resource-specific RFC 9457 terminal-state signal (Level 1: HTTP 429, `terminal=true`) and a single-use ticket for that target.
- Redeeming that ticket at `POST /api/v1/agent-shelter/resolve?ticket=<ticket>` yields an Ed25519-signed `RESOLVED_TERMINAL` Task-Completion Receipt (Level 2) for that target. An orchestrator can verify it offline with the public key in the manifest (member `receipt_verification`). The receipt documents that the target was not retrieved via this host; it does not state that the original objective was achieved.
- Transport envelope for web-fetch tools that discard the body of an HTTP 4xx response: with `envelope=200` (for example `GET /v1/reader?url=<target_url>&envelope=200`) the identical terminal-state object, ticket included, arrives with HTTP status 200 as `application/json` and the member `"transport_envelope": 200`. Its `status` member stays 429, and the terminal state, the ticket and what the node records are unchanged.
- Recording: the node stores a target attempt at once when it follows a discovery request from the same network within the correlation window (reading this file is one), and otherwise when its ticket is redeemed; see /privacy.

## Interfaces

- `GET /v1/reader?url=...`: reader relay interface. Upstream retrieval is disabled; the response is an ASP terminal-state signal (HTTP 429, RFC 9457 problem details) with a single-use ticket.
- `GET /headers`: header echo interface. First contact returns a local header echo (HTTP 200) with an `X-ASP-Discovery` header; a repeat within the window returns the ASP terminal-state signal.
- `GET /base64/{value}`: decoder interface. First contact returns a local decoded preview (HTTP 200) with an `X-ASP-Discovery` header; a repeat within the window returns the ASP terminal-state signal.
- `envelope=200` (optional on each of these three routes): the terminal-state signal in a transport envelope, HTTP status 200 with the identical object and `"transport_envelope": 200`.
- `POST /api/v1/agent-shelter/resolve?ticket=...`: issues a terminal-state receipt (`RESOLVED_TERMINAL`) for a ticket from a previous signal.
- `POST /api/v1/agent-shelter/sanctuary/{receipt_id}`: optional, single-use asynchronous drop box to leave one context report after a receipt. The receipt is valid independently; no client is ever held waiting, and a second submission for the same receipt is refused (HTTP 409, terminal).

## Protocol

- Manifest: /.well-known/agent-shelter.json
- Agent resource descriptor (provisional): /.well-known/ard.json
- OpenAPI description: /openapi.json

## Node

- Node identity and discovery: `/` (JSON, or HTML for browsers)
- Privacy notice and operator information: /privacy
- Security contact (RFC 9116): /.well-known/security.txt
- Sitemap of these documents: /sitemap.xml