@cuylabs/agent-foundry-agentserver-responses 4.9.0

package/docs/protocol.md

@@ -0,0 +1,60 @@
+# 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.

package/docs/python-parity.md

@@ -0,0 +1,106 @@
+# Python Parity And Production Readiness
+
+This package tracks Python `azure-ai-agentserver-responses`, but the Python
+package is currently more mature. Use this document as the working parity map.
+
+## Comparison Scope
+
+Use the Python packages as responsibility references, not as file-layout
+templates:
+
+| TypeScript | Python | Status |
+| --- | --- | --- |
+| `@cuylabs/agent-foundry-agentserver-core` | `azure-ai-agentserver-core` | Same host-foundation role, but Express/Node instead of ASGI/Starlette/Hypercorn |
+| `@cuylabs/agent-foundry-agentserver-responses` | `azure-ai-agentserver-responses` | Same Responses protocol role and depends on the TS core package |
+| `@cuylabs/agent-foundry-hosting/responses` | No direct Python package peer | agents-ts bridge that maps local `agent-core` events into Responses events |
+
+This means `agent-foundry-hosting/responses` should be compared against
+`agent-core` and `agent-server` behavior, while protocol correctness should be
+checked in `agent-foundry-agentserver-responses`.
+
+## Source Of Truth
+
+The Python package points at the Azure REST API specs TypeSpec source through
+`type_spec/tsp-location.yaml`:
+
+```yaml
+directory: specification/ai-foundry/data-plane/Foundry/src/sdk-service-agentserver-contracts
+entrypointFile: client.tsp
+additionalDirectories:
+  - specification/ai-foundry/data-plane/Foundry/src/openai-responses
+  - specification/ai-foundry/data-plane/Foundry/src/openai-conversations
+  - specification/ai-foundry/data-plane/Foundry/src/tools
+  - specification/ai-foundry/data-plane/Foundry/src/common
+  - specification/ai-foundry/data-plane/Foundry/src/memory-stores
+```
+
+For production parity, TypeScript should eventually generate or validate its
+protocol models from the same TypeSpec/OpenAPI source instead of relying only on
+hand-written structural interfaces.
+
+## Current TS Coverage
+
+| Area | TS status |
+| --- | --- |
+| Express host and route surface | Implemented |
+| Create, get, delete, cancel, input-items endpoints | Implemented |
+| SSE response framing | Implemented |
+| Replay cursor `starting_after` | Implemented |
+| `TextResponse` convenience helper | Implemented |
+| `ResponseContext` input text, input items, history | Implemented |
+| `ResponseProvider` and `ResponseStreamProvider` contracts | Implemented |
+| Foundry HTTP storage provider | Implemented |
+| In-memory provider for dev/test | Implemented |
+| Agent Server headers, isolation, tracing hook-up | Implemented foundation through core; responses-specific contract coverage still partial |
+| `agent-core` bridge | Implemented in `@cuylabs/agent-foundry-hosting/responses` |
+| TypeSpec-generated request/response models | Not implemented |
+| Generated schema validation | Not implemented |
+| Full `ResponseEventStream` builder API | Not implemented |
+| SSE keep-alive option | Not implemented |
+| Python contract-suite parity | Partial |
+
+## Important Gaps Before Calling This Fully Production-Equivalent
+
+The TS source now follows the same broad domains as Python:
+`hosting`, `store`, and `streaming`. It intentionally does not copy Python's
+private module names one-for-one, and the model layer remains hand-written until
+the TypeSpec generation work is added.
+
+The current TS implementation is a good protocol host foundation, but it is not
+yet as hardened as the Python SDK.
+
+First, request validation is still mostly structural and semantic. Python
+generates validators from the TypeSpec/OpenAPI model and rejects malformed
+payloads earlier and with richer details.
+
+Second, Python has a full lifecycle/state-machine layer around emitted events.
+It validates first-event rules, output item event shape, terminal transitions,
+and output manipulation invariants. TS currently normalizes only the minimum
+needed event shape.
+
+Third, Python has a broad contract suite covering mode matrices, stream replay,
+disconnect behavior, cancellation consistency, persistence failure behavior,
+chat isolation, eager eviction, and OpenAI wire compliance. TS has focused unit
+and host tests, but not yet the equivalent contract matrix.
+
+Fourth, Python exposes richer handler ergonomics through `ResponseEventStream`
+and builder helpers for messages, function calls, reasoning items, annotations,
+images, and structured outputs. TS currently supports raw events and
+`TextResponse`.
+
+Fifth, Python's Foundry storage provider is layered on the Azure SDK pipeline,
+including retry, request logging, tracing, and storage-specific serialization.
+The TS provider follows the same HTTP endpoint shape, but it currently uses a
+direct `fetch` implementation and needs the same production transport hardening.
+
+## Recommended Next Work
+
+1. Add TypeSpec/OpenAPI-based model generation or runtime validation for
+   `CreateResponse`, response items, and stream events.
+2. Port the Python mode matrix and cross-API contract tests into TS.
+3. Add a TS `ResponseEventStream` builder API instead of expecting raw events
+   for non-text outputs.
+4. Add lifecycle validation for handler-emitted events.
+5. Add persistence-failure tests and storage error mapping parity.
+6. Add SSE keep-alive support if hosted Foundry requires long-lived streams
+   through infrastructure that closes idle connections.

package/docs/store.md

@@ -0,0 +1,88 @@
+# 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.

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@cuylabs/agent-foundry-agentserver-responses",
+  "version": "4.9.0",
+  "description": "TypeScript Foundry Agent Server Responses-protocol host (mirrors azure-ai-agentserver-responses)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./store": {
+      "types": "./dist/store/index.d.ts",
+      "import": "./dist/store/index.js",
+      "default": "./dist/store/index.js"
+    },
+    "./streaming": {
+      "types": "./dist/streaming/index.d.ts",
+      "import": "./dist/streaming/index.js",
+      "default": "./dist/streaming/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "samples",
+    "README.md"
+  ],
+  "dependencies": {
+    "express": "^5.0.0",
+    "@cuylabs/agent-foundry-agentserver-core": "^4.9.0"
+  },
+  "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  },
+  "keywords": [
+    "agent",
+    "azure",
+    "foundry",
+    "hosted-agent",
+    "responses-protocol",
+    "agentserver",
+    "express",
+    "sse"
+  ],
+  "author": "cuylabs",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cuylabs-ai/agents-ts.git",
+    "directory": "packages/agent-foundry-agentserver-responses"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/store/index.ts src/streaming/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts src/store/index.ts src/streaming/index.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}

package/samples/README.md

@@ -0,0 +1,30 @@
+# Agent Server Responses Samples
+
+These samples mirror the most important Python `azure-ai-agentserver-responses`
+patterns in TypeScript.
+
+## Samples
+
+| Sample | Pattern | Purpose |
+| --- | --- | --- |
+| [sample_01_getting_started.ts](./sample_01_getting_started.ts) | `TextResponse` | Minimal echo server |
+| [sample_02_streaming_text.ts](./sample_02_streaming_text.ts) | `TextResponse` + async iterable | Token-style streaming |
+| [sample_03_raw_events.ts](./sample_03_raw_events.ts) | Raw `ResponseStreamEvent` | Function-call style event control |
+| [sample_04_foundry_storage.ts](./sample_04_foundry_storage.ts) | `FoundryStorageProvider` | Durable Foundry response storage |
+| [sample_05_agent_core_bridge.ts](./sample_05_agent_core_bridge.ts) | `agent-foundry-hosting/responses` | Bridge an `agent-core` agent into this protocol host |
+
+## Running Locally
+
+Build the workspace first, then run a sample with a TypeScript runner such as
+`tsx` from the workspace root:
+
+```bash
+pnpm --filter @cuylabs/agent-foundry-agentserver-responses build
+pnpm exec tsx packages/agent-foundry-agentserver-responses/samples/sample_01_getting_started.ts
+```
+
+The Foundry storage sample expects Azure credentials and
+`FOUNDRY_PROJECT_ENDPOINT`.
+
+The agent-core bridge sample includes a placeholder `myAgent` import. Replace
+that import with the local agent you want to host.

package/samples/sample_01_getting_started.ts

@@ -0,0 +1,16 @@
+import {
+  ResponseContext,
+  TextResponse,
+  runResponsesServer,
+  type CreateResponse,
+} from "@cuylabs/agent-foundry-agentserver-responses";
+
+await runResponsesServer({
+  port: Number.parseInt(process.env.PORT ?? "8088", 10),
+  async handler(request: CreateResponse, context: ResponseContext) {
+    const text = await context.getInputText();
+    return new TextResponse(context, request, {
+      text: `Echo: ${text}`,
+    });
+  },
+});

package/samples/sample_02_streaming_text.ts

@@ -0,0 +1,23 @@
+import {
+  ResponseContext,
+  TextResponse,
+  runResponsesServer,
+  type CreateResponse,
+} from "@cuylabs/agent-foundry-agentserver-responses";
+
+await runResponsesServer({
+  port: Number.parseInt(process.env.PORT ?? "8088", 10),
+  async handler(request: CreateResponse, context: ResponseContext) {
+    const text = await context.getInputText();
+    return new TextResponse(context, request, {
+      text: streamTokens(`Streaming echo: ${text}`),
+    });
+  },
+});
+
+async function* streamTokens(text: string): AsyncGenerator<string> {
+  for (const token of text.split(/(\s+)/u)) {
+    await new Promise((resolve) => setTimeout(resolve, 25));
+    yield token;
+  }
+}

package/samples/sample_03_raw_events.ts

@@ -0,0 +1,58 @@
+import {
+  ResponseContext,
+  createResponseObject,
+  newOutputMessageItemId,
+  runResponsesServer,
+  type CreateResponse,
+  type OutputItem,
+  type ResponseStreamEvent,
+} from "@cuylabs/agent-foundry-agentserver-responses";
+
+await runResponsesServer({
+  port: Number.parseInt(process.env.PORT ?? "8088", 10),
+  async handler(request: CreateResponse, context: ResponseContext) {
+    return emitFunctionCall(request, context);
+  },
+});
+
+async function* emitFunctionCall(
+  request: CreateResponse,
+  context: ResponseContext,
+): AsyncGenerator<ResponseStreamEvent> {
+  const response = createResponseObject({
+    id: context.responseId,
+    request,
+    status: "in_progress",
+    createdAt: context.createdAt,
+  });
+  yield { type: "response.created", response };
+  yield { type: "response.in_progress", response };
+
+  const item: OutputItem = {
+    id: newOutputMessageItemId(context.responseId),
+    type: "function_call",
+    status: "completed",
+    name: "get_weather",
+    call_id: "call_001",
+    arguments: JSON.stringify({ location: "Seattle", unit: "fahrenheit" }),
+  };
+  yield {
+    type: "response.output_item.added",
+    output_index: 0,
+    item,
+  };
+  yield {
+    type: "response.output_item.done",
+    output_index: 0,
+    item,
+  };
+
+  yield {
+    type: "response.completed",
+    response: {
+      ...response,
+      status: "completed",
+      output: [item],
+    },
+  };
+}

package/samples/sample_04_foundry_storage.ts

@@ -0,0 +1,26 @@
+import { DefaultAzureCredential } from "@azure/identity";
+import {
+  ResponseContext,
+  TextResponse,
+  runResponsesServer,
+  type CreateResponse,
+} from "@cuylabs/agent-foundry-agentserver-responses";
+import {
+  FoundryStorageProvider,
+} from "@cuylabs/agent-foundry-agentserver-responses/store";
+
+const credential = new DefaultAzureCredential();
+
+await runResponsesServer({
+  port: Number.parseInt(process.env.PORT ?? "8088", 10),
+  store: new FoundryStorageProvider({
+    credential,
+  }),
+  async handler(request: CreateResponse, context: ResponseContext) {
+    const text = await context.getInputText();
+    const history = await context.getHistory();
+    return new TextResponse(context, request, {
+      text: `Echo: ${text}\nHistory items available: ${history.length}`,
+    });
+  },
+});

package/samples/sample_05_agent_core_bridge.ts

@@ -0,0 +1,15 @@
+import { runResponsesServer } from "@cuylabs/agent-foundry-agentserver-responses";
+import { createResponsesHandlerForAgent } from "@cuylabs/agent-foundry-hosting/responses";
+import {
+  InProcessAgentServer,
+  createAgentServerAdapter,
+} from "@cuylabs/agent-server";
+
+import { myAgent } from "./shared/my-agent.js";
+
+const server = new InProcessAgentServer(createAgentServerAdapter(myAgent));
+
+await runResponsesServer({
+  port: Number.parseInt(process.env.PORT ?? "8088", 10),
+  handler: createResponsesHandlerForAgent(server),
+});