# Agent Server Responses Docs

This package is the TypeScript implementation of the Azure AI Foundry Hosted
Agents Responses protocol host. It mirrors the shape of Python
`azure-ai-agentserver-responses` while fitting the `agents-ts` package layout.

Use the package README for a quick start. Use these docs when working on the
host internals, storage providers, protocol behavior, or the bridge from
`@cuylabs/agent-core`.

## Documents

| Document | Purpose |
| --- | --- |
| [hosting.md](./hosting.md) | Express host lifecycle, route layout, response execution, and tracing |
| [store.md](./store.md) | Durable storage options, Foundry storage, in-memory storage, and custom providers |
| [protocol.md](./protocol.md) | Responses endpoint behavior, IDs, validation, streaming, and replay |
| [agent-core-bridge.md](./agent-core-bridge.md) | How `@cuylabs/agent-foundry-hosting/responses` adapts `agent-core` turns |
| [python-parity.md](./python-parity.md) | Current parity against Python, TypeSpec, and production-readiness gaps |

## Package Layers

```text
@cuylabs/agent-foundry-agentserver-core
  Express/Node equivalent of Python azure-ai-agentserver-core:
  identity, headers, config, health, observability, request tracing

@cuylabs/agent-foundry-agentserver-responses
  TypeScript equivalent of Python azure-ai-agentserver-responses:
  Responses routes, SSE framing, IDs, models, storage provider contracts

@cuylabs/agent-foundry-hosting/responses
  agents-ts bridge only: adapts agent-core / agent-server turns into Responses stream events
```

The responses package is intentionally agent-agnostic. It knows how to host the
Responses protocol and persist protocol state. It does not know how a specific
agent reasons, calls tools, or stores its own runtime memory.

## Comparison Targets

When checking parity against Python, compare packages by responsibility rather
than by framework or private file names:

| TypeScript package | Python package | Compare for |
| --- | --- | --- |
| `@cuylabs/agent-foundry-agentserver-core` | `azure-ai-agentserver-core` | Protocol-agnostic host behavior: config, health/readiness, protected headers, request IDs, request logging, tracing, graceful shutdown |
| `@cuylabs/agent-foundry-agentserver-responses` | `azure-ai-agentserver-responses` | Responses protocol behavior: create/get/delete/cancel/input-items, stream/replay, storage, response context, model validation, event lifecycle |
| `@cuylabs/agent-foundry-hosting/responses` | No direct Python peer | TypeScript-specific bridge from `agent-core`/`agent-server` events into the Responses protocol |

Python uses ASGI, Starlette, and Hypercorn. TypeScript uses Express and Node's
HTTP server. That framework difference is expected; the parity target is the
hosted-agent contract and observable protocol behavior.

## Source Layout

The TypeScript source follows the same conceptual domains as the Python package
without copying Python private module names directly:

| TS path | Python peer | Responsibility |
| --- | --- | --- |
| `src/hosting/` | `responses/hosting/` | Express routes, request parsing, execution, tracing, validation |
| `src/store/` | `responses/store/` | In-memory and Foundry-backed response providers |
| `src/streaming/` | `responses/streaming/` | SSE encoding and text-response streaming helpers |
| `src/types.ts`, `src/model-helpers.ts`, `src/ids.ts` | `responses/models/` plus root helpers | Hand-written protocol types and model helpers until TypeSpec-generated models are added |

The `store` and `streaming` domains are also package subpath exports:

```ts
import { FoundryStorageProvider } from "@cuylabs/agent-foundry-agentserver-responses/store";
import { TextResponse } from "@cuylabs/agent-foundry-agentserver-responses/streaming";
```