# Protocol Behavior

This package hosts the Responses protocol endpoints required by Azure AI
Foundry Hosted Agents.

## Endpoints

| Method | Route | Behavior |
| --- | --- | --- |
| `POST` | `/responses` | Create a response |
| `GET` | `/responses/{response_id}` | Retrieve a stored or in-flight response snapshot |
| `GET` | `/responses/{response_id}?stream=true` | Replay stored stream events for a background streaming response |
| `GET` | `/responses/{response_id}?stream=true&starting_after=N` | Replay only events with `sequence_number > N` |
| `POST` | `/responses/{response_id}/cancel` | Cancel an in-flight background response |
| `DELETE` | `/responses/{response_id}` | Delete a stored response |
| `GET` | `/responses/{response_id}/input_items` | List historical and current input items |
| `GET` | `/responses/docs/openapi.json` | Return the package OpenAPI document or a handler-provided override |

## Modes

The create request controls three important flags:

| Flag | Meaning |
| --- | --- |
| `stream` | Send response events as Server-Sent Events |
| `background` | Return before execution finishes and keep the response active |
| `store` | Persist response state through the configured `ResponseProvider` |

`background=true` requires `store=true`, matching the hosted-agent behavior.
`stream_options` requires `stream=true`.

## IDs And Isolation

Response IDs use the `caresp` prefix. Route parameters and
`previous_response_id` values are validated before storage access.

The host resolves Agent Server user and chat isolation from request headers and
passes the isolation context to providers. Active in-flight responses are also
keyed by isolation, so one scoped caller cannot read or cancel another scoped
caller's active response.

## Input Items And History

Create input is normalized into response input items and stored with the
response when `store` is enabled. `ResponseContext` can retrieve current input,
previous response history, and referenced items through the configured provider.

History lookup is provider-backed. Foundry storage resolves history by
`previous_response_id` and conversation ID. The in-memory provider mirrors that
behavior for local tests and development.

## OpenAPI

The package includes a hand-maintained OpenAPI document for the hosted endpoints
in `src/openapi.ts`. A handler can override the document by implementing
`getOpenApi()`.

The long-term direction is to generate or validate the TypeScript model surface
from the same schema source used by the platform, while preserving the
provider/handler contracts.