@cuylabs/agent-foundry-agentserver-responses 4.9.0

package/dist/store/index.d.ts

@@ -0,0 +1,134 @@
+import { AgentIsolationContext } from '@cuylabs/agent-foundry-agentserver-core';
+import { p as ResponseProvider, b as ResponseObject, O as OutputItem, s as ResponseStreamProvider, r as ResponseStreamEvent } from '../types-Dvs2F85g.js';
+import 'node:http';
+import 'express';
+
+declare class FoundryStorageError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly responseBody?: unknown | undefined;
+    constructor(message: string, status: number, code?: string, responseBody?: unknown | undefined);
+}
+declare class FoundryStorageNotFoundError extends FoundryStorageError {
+    constructor(message: string, responseBody?: unknown);
+}
+
+interface FoundryStorageSettingsOptions {
+    projectEndpoint?: string;
+    storageBaseUrl?: string;
+    env?: NodeJS.ProcessEnv;
+}
+declare class FoundryStorageSettings {
+    readonly storageBaseUrl: string;
+    constructor(options: {
+        storageBaseUrl: string;
+    });
+    static fromEnv(env?: NodeJS.ProcessEnv): FoundryStorageSettings;
+    static fromEndpoint(endpoint: string): FoundryStorageSettings;
+    static resolve(options?: FoundryStorageSettingsOptions): FoundryStorageSettings;
+    buildUrl(path: string, query?: Record<string, string | undefined>): string;
+}
+
+interface AccessToken {
+    token: string;
+    expiresOnTimestamp?: number;
+}
+interface TokenCredential {
+    getToken(scopes: string | string[], options?: Record<string, unknown>): Promise<AccessToken | null>;
+}
+interface FoundryStorageProviderOptions extends FoundryStorageSettingsOptions {
+    credential: TokenCredential;
+    fetch?: typeof fetch;
+    getServerVersion?: () => string;
+}
+declare class FoundryStorageProvider implements ResponseProvider {
+    private readonly credential;
+    private readonly fetchImpl;
+    private readonly settings;
+    private readonly getServerVersion?;
+    constructor(options: FoundryStorageProviderOptions);
+    createResponse(response: ResponseObject, inputItems: OutputItem[], options?: {
+        historyItemIds?: readonly string[];
+        isolation?: AgentIsolationContext;
+    }): Promise<void>;
+    getResponse(responseId: string, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<ResponseObject | undefined>;
+    updateResponse(response: ResponseObject, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<void>;
+    deleteResponse(responseId: string, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<boolean>;
+    getInputItems(responseId: string, options?: {
+        after?: string;
+        ascending?: boolean;
+        before?: string;
+        isolation?: AgentIsolationContext;
+        limit?: number;
+    }): Promise<OutputItem[] | undefined>;
+    getItems(itemIds: readonly string[], options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<Array<OutputItem | undefined>>;
+    getHistoryItemIds(previousResponseId: string | undefined, conversationId: string | undefined, limit: number, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<string[]>;
+    private request;
+    private headers;
+}
+
+declare class InMemoryResponseProvider implements ResponseProvider, ResponseStreamProvider {
+    private readonly responses;
+    private readonly inputItems;
+    private readonly historyItemIds;
+    private readonly items;
+    private readonly streamEvents;
+    private readonly conversationResponses;
+    private readonly deleted;
+    createResponse(response: ResponseObject, inputItems: OutputItem[], options?: {
+        historyItemIds?: readonly string[];
+        isolation?: AgentIsolationContext;
+    }): Promise<void>;
+    getResponse(responseId: string, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<ResponseObject | undefined>;
+    updateResponse(response: ResponseObject, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<void>;
+    deleteResponse(responseId: string, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<boolean>;
+    getItems(itemIds: readonly string[], options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<Array<OutputItem | undefined>>;
+    getInputItems(responseId: string, options?: {
+        after?: string;
+        ascending?: boolean;
+        before?: string;
+        isolation?: AgentIsolationContext;
+        limit?: number;
+    }): Promise<OutputItem[] | undefined>;
+    getHistoryItemIds(previousResponseId: string | undefined, conversationId: string | undefined, limit: number, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<string[]>;
+    getHistoryItems(previousResponseId: string | undefined, conversationId: string | undefined, limit: number, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<OutputItem[]>;
+    appendStreamEvent(responseId: string, event: ResponseStreamEvent, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<void>;
+    getStreamEvents(responseId: string, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<ResponseStreamEvent[] | undefined>;
+    saveStreamEvents(responseId: string, events: ResponseStreamEvent[], options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<void>;
+    deleteStreamEvents(responseId: string, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<void>;
+    isDeleted(responseId: string, isolation?: AgentIsolationContext): boolean;
+    private collectPreviousResponseHistoryItemIds;
+    private collectResponseItemIds;
+}
+
+export { type AccessToken, FoundryStorageError, FoundryStorageNotFoundError, FoundryStorageProvider, type FoundryStorageProviderOptions, FoundryStorageSettings, type FoundryStorageSettingsOptions, InMemoryResponseProvider, type TokenCredential };

package/dist/store/index.js

@@ -0,0 +1,14 @@
+import {
+  FoundryStorageError,
+  FoundryStorageNotFoundError,
+  FoundryStorageProvider,
+  FoundryStorageSettings,
+  InMemoryResponseProvider
+} from "../chunk-DGMWFFNQ.js";
+export {
+  FoundryStorageError,
+  FoundryStorageNotFoundError,
+  FoundryStorageProvider,
+  FoundryStorageSettings,
+  InMemoryResponseProvider
+};

package/dist/streaming/index.d.ts

@@ -0,0 +1,27 @@
+import { Response } from 'express';
+import { r as ResponseStreamEvent, j as ResponseContext, C as CreateResponse, b as ResponseObject } from '../types-Dvs2F85g.js';
+import 'node:http';
+import '@cuylabs/agent-foundry-agentserver-core';
+
+interface SseEncoderState {
+    sequenceNumber: number;
+}
+declare function startResponsesSseResponse(res: Response): void;
+declare function createSseEncoderState(): SseEncoderState;
+declare function encodeSseEvent(event: ResponseStreamEvent, state?: SseEncoderState): string;
+declare function encodeKeepAliveComment(comment?: string): string;
+
+type TextSource = string | (() => string | Promise<string>) | AsyncIterable<string> | Iterable<string>;
+declare class TextResponse implements AsyncIterable<ResponseStreamEvent> {
+    private readonly context;
+    private readonly request;
+    private readonly options;
+    constructor(context: ResponseContext, request: CreateResponse, options: {
+        text: TextSource;
+        configure?: (response: ResponseObject) => void;
+    });
+    [Symbol.asyncIterator](): AsyncIterator<ResponseStreamEvent>;
+    private generate;
+}
+
+export { type SseEncoderState, TextResponse, type TextSource, createSseEncoderState, encodeKeepAliveComment, encodeSseEvent, startResponsesSseResponse };

package/dist/streaming/index.js

@@ -0,0 +1,14 @@
+import {
+  TextResponse,
+  createSseEncoderState,
+  encodeKeepAliveComment,
+  encodeSseEvent,
+  startResponsesSseResponse
+} from "../chunk-24VMS6GY.js";
+export {
+  TextResponse,
+  createSseEncoderState,
+  encodeKeepAliveComment,
+  encodeSseEvent,
+  startResponsesSseResponse
+};

package/dist/types-Dvs2F85g.d.ts

@@ -0,0 +1,254 @@
+import * as node_http from 'node:http';
+import * as express from 'express';
+import { Response, Request } from 'express';
+import { AgentIsolationContext } from '@cuylabs/agent-foundry-agentserver-core';
+
+declare class ResponseContext {
+    readonly responseId: string;
+    readonly request: CreateResponse;
+    readonly createdAt: number;
+    readonly modeFlags: ResponseModeFlags;
+    readonly sessionId: string;
+    readonly previousResponseId?: string;
+    readonly conversationId?: string;
+    readonly clientHeaders: Record<string, string>;
+    readonly queryParameters: Record<string, string>;
+    readonly isolation: AgentIsolationContext;
+    isShutdownRequested: boolean;
+    private readonly provider?;
+    private readonly historyLimit;
+    private readonly inputItems;
+    private resolvedInputCache?;
+    private historyCache?;
+    constructor(options: {
+        responseId: string;
+        request: CreateResponse;
+        modeFlags: ResponseModeFlags;
+        sessionId?: string;
+        provider?: ResponseProvider;
+        inputItems?: OutputItem[];
+        previousResponseId?: string;
+        conversationId?: string;
+        historyLimit?: number;
+        clientHeaders?: Record<string, string>;
+        queryParameters?: Record<string, string>;
+        isolation?: AgentIsolationContext;
+        createdAt?: number;
+    });
+    getInputItems(options?: {
+        resolveReferences?: boolean;
+    }): Promise<readonly OutputItem[]>;
+    getInputText(options?: {
+        resolveReferences?: boolean;
+    }): Promise<string>;
+    getHistory(): Promise<readonly OutputItem[]>;
+    getInputItemsForPersistence(): Promise<OutputItem[]>;
+}
+
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+interface AgentReference {
+    type: "agent_reference";
+    name: string;
+    version?: string;
+    id?: string;
+}
+interface ConversationReference {
+    id: string;
+}
+interface CreateResponse {
+    input?: ResponseInput;
+    model?: string;
+    stream?: boolean;
+    background?: boolean;
+    store?: boolean;
+    previous_response_id?: string | null;
+    conversation?: string | ConversationReference | null;
+    metadata?: Record<string, unknown> | null;
+    response_id?: string;
+    agent_session_id?: string;
+    agent_reference?: AgentReference;
+    [key: string]: unknown;
+}
+type ResponseInput = string | InputItem | InputItem[];
+type InputItem = ItemMessage | ItemReference | FunctionCallOutputItem | Record<string, unknown>;
+interface ItemMessage {
+    id?: string;
+    type: "message";
+    role: "user" | "assistant" | "system" | "developer";
+    content: string | MessageContent[];
+}
+interface ItemReference {
+    type: "item_reference";
+    id: string;
+}
+interface FunctionCallOutputItem {
+    id?: string;
+    type: "function_call_output";
+    call_id: string;
+    output: string;
+}
+type MessageContent = MessageContentInputText | MessageContentOutputText | MessageContentRefusal | Record<string, unknown>;
+interface MessageContentInputText {
+    type: "input_text";
+    text: string;
+}
+interface MessageContentOutputText {
+    type: "output_text";
+    text: string;
+    annotations?: unknown[];
+}
+interface MessageContentRefusal {
+    type: "refusal";
+    refusal: string;
+}
+interface OutputItem {
+    id: string;
+    type: string;
+    status?: string;
+    role?: string;
+    content?: MessageContent[];
+    [key: string]: unknown;
+}
+type ResponseStatus = "queued" | "in_progress" | "completed" | "failed" | "cancelled" | "incomplete";
+interface ResponseError {
+    code: string;
+    message: string;
+    type?: string;
+}
+interface ResponseUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    total_tokens?: number;
+    [key: string]: unknown;
+}
+interface ResponseObject {
+    id: string;
+    object: "response";
+    created_at: number;
+    status: ResponseStatus;
+    model?: string;
+    stream?: boolean;
+    background?: boolean;
+    store?: boolean;
+    output: OutputItem[];
+    error?: ResponseError | null;
+    previous_response_id?: string | null;
+    conversation?: ConversationReference;
+    metadata?: Record<string, unknown> | null;
+    usage?: ResponseUsage | null;
+    [key: string]: unknown;
+}
+interface ResponseStreamEvent {
+    type: string;
+    sequence_number?: number;
+    response?: ResponseObject;
+    item?: OutputItem;
+    item_id?: string;
+    output_index?: number;
+    content_index?: number;
+    part?: MessageContent;
+    delta?: string;
+    text?: string;
+    error?: ResponseError;
+    [key: string]: unknown;
+}
+interface ResponseModeFlags {
+    stream: boolean;
+    background: boolean;
+    store: boolean;
+}
+interface ResponseHandlerContext {
+    request: CreateResponse;
+    context: ResponseContext;
+    signal: AbortSignal;
+}
+type ResponseHandlerResult = AsyncIterable<ResponseStreamEvent | Record<string, unknown>> | Iterable<ResponseStreamEvent | Record<string, unknown>>;
+type ResponseHandler = (request: CreateResponse, context: ResponseContext, signal: AbortSignal) => ResponseHandlerResult | Promise<ResponseHandlerResult>;
+declare abstract class ResponsesHandler {
+    abstract handle(request: CreateResponse, context: ResponseContext, signal: AbortSignal): ResponseHandlerResult | Promise<ResponseHandlerResult>;
+    getOpenApi?(): unknown;
+    close?(): Promise<void> | void;
+}
+type ResponsesHandlerFactory = () => ResponsesHandler;
+type ResponsesHandlerInput = ResponsesHandler | ResponsesHandlerFactory | ResponseHandler;
+interface ResponseProvider {
+    createResponse(response: ResponseObject, inputItems: OutputItem[], options?: {
+        historyItemIds?: readonly string[];
+        isolation?: AgentIsolationContext;
+    }): Promise<void>;
+    getResponse(responseId: string, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<ResponseObject | undefined>;
+    updateResponse(response: ResponseObject, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<void>;
+    deleteResponse(responseId: string, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<boolean>;
+    getItems(itemIds: readonly string[], options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<Array<OutputItem | undefined>>;
+    getInputItems(responseId: string, options?: {
+        after?: string;
+        ascending?: boolean;
+        before?: string;
+        isolation?: AgentIsolationContext;
+        limit?: number;
+    }): Promise<OutputItem[] | undefined>;
+    getHistoryItemIds(previousResponseId: string | undefined, conversationId: string | undefined, limit: number, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<string[]>;
+    getHistoryItems?(previousResponseId: string | undefined, conversationId: string | undefined, limit: number, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<OutputItem[]>;
+}
+interface ResponseStreamProvider {
+    appendStreamEvent(responseId: string, event: ResponseStreamEvent, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<void>;
+    saveStreamEvents?(responseId: string, events: ResponseStreamEvent[], options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<void>;
+    getStreamEvents(responseId: string, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<ResponseStreamEvent[] | undefined>;
+    deleteStreamEvents(responseId: string, options?: {
+        isolation?: AgentIsolationContext;
+    }): Promise<void>;
+}
+interface ResponsesServerLogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    debug?(message: string, meta?: Record<string, unknown>): void;
+}
+interface ResponsesServer {
+    readonly app: express.Express;
+    readonly server: node_http.Server;
+    readonly port: number;
+    readonly host: string;
+    close(): Promise<void>;
+}
+interface ResponsesServerOptions {
+    handler: ResponsesHandlerInput;
+    port?: number;
+    host?: string;
+    appName?: string;
+    bodyLimit?: string;
+    requestLogging?: boolean;
+    trustProxy?: boolean | number | string;
+    gracefulShutdownTimeoutSeconds?: number;
+    configureObservability?: boolean;
+    logger?: ResponsesServerLogger;
+    store?: ResponseProvider & Partial<ResponseStreamProvider>;
+    defaultModel?: string;
+    defaultFetchHistoryCount?: number;
+}
+interface ResponsesRequest extends Request {
+    body: CreateResponse;
+}
+type ExpressResponse = Response;
+
+export { type AgentReference as A, type CreateResponse as C, type ExpressResponse as E, type FunctionCallOutputItem as F, type InputItem as I, type JsonValue as J, type MessageContent as M, type OutputItem as O, type ResponsesServerOptions as R, type ResponsesServer as a, type ResponseObject as b, type ResponseInput as c, type ConversationReference as d, type ItemMessage as e, type ItemReference as f, type MessageContentInputText as g, type MessageContentOutputText as h, type MessageContentRefusal as i, ResponseContext as j, type ResponseError as k, type ResponseHandler as l, type ResponseHandlerContext as m, type ResponseHandlerResult as n, type ResponseModeFlags as o, type ResponseProvider as p, type ResponseStatus as q, type ResponseStreamEvent as r, type ResponseStreamProvider as s, type ResponseUsage as t, ResponsesHandler as u, type ResponsesHandlerFactory as v, type ResponsesHandlerInput as w, type ResponsesRequest as x, type ResponsesServerLogger as y };

package/docs/README.md

@@ -0,0 +1,72 @@
+# 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";
+```

package/docs/agent-core-bridge.md

@@ -0,0 +1,48 @@
+# Agent-Core Bridge
+
+This package is protocol-level and agent-agnostic. It exposes
+`ResponsesHandler` and the HTTP host, but it does not depend on
+`@cuylabs/agent-core`.
+
+Use `@cuylabs/agent-foundry-hosting/responses` when an `agent-core` agent needs
+to run behind the Responses protocol.
+
+```ts
+import { runResponsesServer } from "@cuylabs/agent-foundry-agentserver-responses";
+import { createResponsesHandlerForAgent } from "@cuylabs/agent-foundry-hosting/responses";
+import {
+  createAgentServerAdapter,
+  InProcessAgentServer,
+} from "@cuylabs/agent-server";
+
+const server = new InProcessAgentServer(createAgentServerAdapter(myAgent));
+
+await runResponsesServer({
+  handler: createResponsesHandlerForAgent(server),
+  port: 8088,
+});
+```
+
+## Responsibilities
+
+The bridge owns agent runtime translation:
+
+- starts an `agent-server` turn for each create-response request
+- sends the normalized user input into the turn
+- maps `agent-core` events to Responses stream events
+- forwards cancellation to `interruptTurn`
+- closes the wrapped server when the handler closes
+
+The responses package still owns protocol concerns:
+
+- Express routing
+- SSE framing
+- response IDs and session IDs
+- `ResponseContext`
+- response snapshots
+- storage and stream replay
+- platform headers and tracing
+
+Keep this split intact. New protocol behavior belongs in
+`agent-foundry-agentserver-responses`. New agent-runtime mapping behavior
+belongs in `agent-foundry-hosting/responses`.

package/docs/hosting.md

@@ -0,0 +1,72 @@
+# Hosting
+
+The public host entry points are `createResponsesApp` and
+`runResponsesServer` from `src/host.ts`.
+
+`createResponsesApp` builds an Express app and wires the shared Agent Server
+core middleware:
+
+- request IDs and protected platform headers
+- JSON body parsing
+- observability initialization
+- optional request logging
+- Responses route registration
+- not-found and error middleware
+
+`runResponsesServer` wraps `createResponsesApp`, starts the HTTP server, logs
+startup configuration, and handles graceful shutdown.
+
+## Internal Layout
+
+The host is split so protocol behavior is not trapped in one large file:
+
+| Path | Responsibility |
+| --- | --- |
+| `src/host.ts` | Public Express/server bootstrap |
+| `src/hosting/routes.ts` | Route registration and method guards |
+| `src/hosting/routes/*.ts` | Endpoint-specific request handlers |
+| `src/hosting/execution.ts` | Handler execution loop and response event application |
+| `src/hosting/tracing.ts` | Responses request span creation and response lifecycle binding |
+| `src/hosting/http-utils.ts` | Query parsing, active key scoping, JSON parse errors |
+| `src/hosting/validation.ts` | Server-boundary semantic validation |
+| `src/streaming/` | SSE encoding and streaming response helpers used by route handlers |
+| `src/store/` | Response persistence providers used by the host |
+
+## Response Execution
+
+`POST /responses` normalizes the create request, resolves IDs and isolation,
+creates a `ResponseContext`, starts a request span, and invokes the configured
+`ResponsesHandler`.
+
+The handler returns an iterable or async iterable of `ResponseStreamEvent`
+objects. The execution loop applies each event to the in-flight
+`ResponseObject`, persists the response and stream events when `store` is
+enabled, and emits terminal events for completed, failed, or cancelled
+responses.
+
+For non-streaming requests, the HTTP response is sent after execution finishes.
+For streaming requests, the host starts Server-Sent Events immediately and
+writes each normalized response event as it arrives. For background requests,
+the initial queued response can return before the handler finishes.
+
+## Handler Input
+
+The host accepts any of these handler shapes:
+
+```ts
+new MyResponsesHandler()
+```
+
+```ts
+() => new MyResponsesHandler()
+```
+
+```ts
+async function* handler(request, context, signal) {
+  yield /* ResponseStreamEvent */;
+}
+```
+
+The factory form is useful when each request needs an isolated handler
+instance. A single handler instance is useful when it owns shared resources and
+implements `close()`.