# Storage

Durable storage is the persistence layer behind the Responses protocol. It is
used for response snapshots, input items, history item lookup, and response
retrieval after the current request finishes.

## Default Storage

If no `store` is provided, the host uses `InMemoryResponseProvider`.

This is useful for local development and tests, but it is not durable. State is
lost when the process exits and it is not shared across replicas.

```ts
await runResponsesServer({
  handler,
});
```

## Foundry Storage

For Foundry-hosted production, use `FoundryStorageProvider`. It is an
HTTP-backed provider for the Azure AI Foundry storage API. The provider derives
its storage URL from `FOUNDRY_PROJECT_ENDPOINT` by appending `/storage/`.

```ts
import { DefaultAzureCredential } from "@azure/identity";
import { runResponsesServer } from "@cuylabs/agent-foundry-agentserver-responses";
import {
  FoundryStorageProvider,
} from "@cuylabs/agent-foundry-agentserver-responses/store";

await runResponsesServer({
  handler,
  store: new FoundryStorageProvider({
    credential: new DefaultAzureCredential(),
  }),
});
```

You can also pass `projectEndpoint` or `storageBaseUrl` explicitly:

```ts
new FoundryStorageProvider({
  credential,
  projectEndpoint: "https://example.services.ai.azure.com/projects/my-project",
});
```

## Foundry Storage Endpoints

The provider uses the same storage API shape as the Python SDK:

| Operation | Storage endpoint |
| --- | --- |
| Create response | `POST /storage/responses` |
| Get response | `GET /storage/responses/{response_id}` |
| Update response | `POST /storage/responses/{response_id}` |
| Delete response | `DELETE /storage/responses/{response_id}` |
| List input items | `GET /storage/responses/{response_id}/input_items` |
| Batch item lookup | `POST /storage/items/batch/retrieve` |
| History item IDs | `GET /storage/history/item_ids` |

The provider also forwards Agent Server isolation headers so scoped user/chat
state is resolved by Foundry storage.

## Stream Replay Storage

`ResponseProvider` handles response snapshots and item history.
`ResponseStreamProvider` is a separate optional capability for persisted SSE
event replay.

If the configured durable provider does not implement `ResponseStreamProvider`,
the host creates an in-memory stream provider fallback. That means the response
snapshot can be durable while replay of already-emitted SSE events is only
available inside the current process.

Implement `ResponseStreamProvider` when durable stream replay matters across
container restarts or replicas.

## Custom Storage

You only need your own database when Foundry storage is not available or when
you need custom retention, compliance, auditing, or placement requirements.

Implement `ResponseProvider` for response snapshots and history. Implement
`ResponseStreamProvider` too if you need durable `GET /responses/{id}?stream=true`
replay.