@jrkropp/codex-js 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @jrkropp/codex-js
 
+## 0.3.0
+
+### Minor Changes
+
+- Add high-level app-server helpers, dynamic tool definition helpers, connection
+  snapshot support, and pending server-request persistence contracts.
+- Align public server terminology around app-server, connection, thread, turn,
+  dynamic tool, server request, server notification, and transport concepts.
+- Replace the placeholder Cloudflare example with a deployable Worker + Durable
+  Object + Vite React example.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -1,99 +1,148 @@
 # @jrkropp/codex-js
 
-Core TypeScript runtime, browser client, server adapters, and test utilities for building Codex-backed apps.
+Core TypeScript SDK for building Codex-backed applications. It includes the browser app-server client, platform-neutral server helpers, Codex-aligned runtime contracts, stores, model transport, and test utilities.
 
 ## Install
 
 ```sh
-pnpm add @jrkropp/codex-js
+npm install @jrkropp/codex-js
 ```
 
 Requirements:
 
 - Node.js 20 or newer.
-- ESM projects only. This package does not ship CommonJS.
-- React is not a dependency of this package. Install `@jrkropp/codex-js-react` only when you need the packaged UI.
+- ESM only. CommonJS output is not shipped.
+- React is not a dependency. Install `@jrkropp/codex-js-react` only when you need packaged UI components.
 
-## Stable Imports
+## Public Imports
 
 ```ts
 import { createCodexAppServerClient } from "@jrkropp/codex-js/client";
-import { createCodexAppServerRuntime } from "@jrkropp/codex-js/server";
+import { createCodexAppServer } from "@jrkropp/codex-js/server";
 import { InMemoryThreadStore } from "@jrkropp/codex-js/testing";
 ```
 
-The published core package exposes only:
+The core package exposes only:
 
 - `@jrkropp/codex-js`
 - `@jrkropp/codex-js/client`
 - `@jrkropp/codex-js/server`
 - `@jrkropp/codex-js/testing`
 
-There are no public upstream mirror or unstable import paths.
+There are no public mirror or unstable imports.
 
-## Browser Client
+## Server Quick Start
 
 ```ts
-import { createCodexAppServerClient } from "@jrkropp/codex-js/client";
+import {
+	createCodexAppServer,
+	createModelClient,
+	defineDynamicTool,
+	dynamicToolResponse,
+} from "@jrkropp/codex-js/server";
+import { InMemoryThreadStore } from "@jrkropp/codex-js/testing";
 
-const appServer = createCodexAppServerClient({
-	url: () => "ws://localhost:1466/api/codex/app-server",
+const lookupStatus = defineDynamicTool({
+	name: "lookup_status",
+	description: "Look up the current deployment status.",
+	inputSchema: {
+		type: "object",
+		properties: { name: { type: "string" } },
+		required: ["name"],
+		additionalProperties: false,
+	},
+	async execute(args) {
+		return dynamicToolResponse.text(`${args.name} is healthy.`);
+	},
 });
 
-await appServer.requestTyped("thread/start", {
-	threadId: "00000000-0000-4000-8000-000000000001",
+const appServer = createCodexAppServer({
+	threadStore: new InMemoryThreadStore(),
+	dynamicTools: [lookupStatus],
+	defaults: {
+		cwd: "/workspace",
+		model: "gpt-5-mini",
+		modelProvider: "openai",
+	},
+	createModelClient({ session, threadId }) {
+		return createModelClient({
+			apiKey: process.env.OPENAI_API_KEY!,
+			installationId: "my-app",
+			sessionId: session.id,
+			threadId,
+		});
+	},
 });
 ```
 
-## Server Runtime
+Create one app-server connection per WebSocket:
 
 ```ts
-import {
-	CodexAppServerMessageProcessor,
-	createCodexAppServerRuntime,
-} from "@jrkropp/codex-js/server";
-import { InMemoryThreadStore } from "@jrkropp/codex-js/testing";
+const connection = appServer.createConnection({
+	send(message) {
+		webSocket.send(message);
+	},
+});
 
-const runtime = createCodexAppServerRuntime({
-	threadStore: new InMemoryThreadStore(),
+webSocket.addEventListener("message", (event) => {
+	void connection.accept(event.data);
 });
 
-const processor = new CodexAppServerMessageProcessor({
-	runtime,
-	send: (message) => {
-		// Write the serialized app-server event to your WebSocket.
-		console.log(message);
-	},
+webSocket.addEventListener("close", () => {
+	void connection.close();
 });
 ```
 
-Create one message processor per WebSocket connection. The package does not own your HTTP server, credential handling, persistence backend, or product-specific tools.
+`createCodexAppServerRuntime` is still exported for advanced hosts that need to own message processing directly, but most applications should start with `createCodexAppServer`.
 
-## React UI
+## Dynamic Tools
 
-The UI package is separate:
+Use `defineDynamicTool` for server-executed tools. Use a namespace when a tool is deferred and loaded through Codex tool search.
 
-```sh
-pnpm add @jrkropp/codex-js @jrkropp/codex-js-react react react-dom
+```ts
+const lookupInvoice = defineDynamicTool({
+	namespace: "billing",
+	name: "lookup_invoice",
+	description: "Look up an invoice by id.",
+	deferLoading: true,
+	inputSchema: {
+		type: "object",
+		properties: { invoiceId: { type: "string" } },
+		required: ["invoiceId"],
+		additionalProperties: false,
+	},
+	async execute(args) {
+		return dynamicToolResponse.text(`Invoice ${args.invoiceId} is paid.`);
+	},
+});
 ```
 
-```tsx
-import { CodexChat } from "@jrkropp/codex-js-react";
-import "@jrkropp/codex-js-react/styles.css";
+Tools with `execute` are resolved by the server. Tools without `execute` are surfaced as app-server requests so the client can resolve them.
+
+## Browser Client
+
+```ts
+import { createCodexAppServerClient } from "@jrkropp/codex-js/client";
+
+const appServer = createCodexAppServerClient({
+	url: async () => {
+		const session = await fetch("/api/codex/session", { method: "POST" });
+		const { webSocketUrl } = await session.json();
+		return webSocketUrl;
+	},
+});
 ```
 
-## Examples
+The browser never needs an OpenAI API key. Host applications should issue a short-lived app-server WebSocket URL from their backend.
+
+## Cloudflare
 
-From the repository root:
+The repository includes a deployable Cloudflare Worker + Durable Object + Vite React example:
 
 ```sh
-pnpm dev:minimal
-pnpm dev:vite-react
+pnpm dev:node-local
 pnpm dev:cloudflare-example
+pnpm --filter @jrkropp/codex-js-cloudflare-example deploy:dry-run
 ```
 
-The examples use local source aliases during development and packed-package tests verify the npm tarballs.
-
-## Architecture
-
-`@jrkropp/codex-js` is the non-React package. It owns the transport protocol, app-server client, server runtime helpers, stores, serializers, and testing primitives. UI components, shadcn exports, Tailwind output, and React-only dependencies live in `@jrkropp/codex-js-react`.
+Use `examples/node-local` for the smallest local Node/Vite integration. Use `examples/cloudflare` for a deployable Worker + Durable Object integration with one-time WebSocket tickets, Durable Object SQLite storage, hibernating WebSockets, server-executed dynamic tools, and a deferred namespaced tool.

package/dist/internal/codex/app-server/src/{bespoke_event_handling.d.ts → app_server_event_mapping.d.ts}

@@ -1,5 +1,5 @@
 import type { EventMsg } from "../../core/src/protocol.js";
 import { serverRequestResolvedNotification, type AppServerProtocolEvent, type EventMappingContext, type ServerRequestCoreTarget } from "../../app-server-protocol/src/protocol/event-mapping.js";
 export type { AppServerProtocolEvent, EventMappingContext, ServerRequestCoreTarget, };
-export declare function apply_bespoke_event_handling(msg: EventMsg, context: EventMappingContext): AppServerProtocolEvent[];
+export declare function mapCoreEventToAppServerEvents(msg: EventMsg, context: EventMappingContext): AppServerProtocolEvent[];
 export { serverRequestResolvedNotification };

package/dist/internal/codex/app-server/src/message_processor.d.ts

@@ -36,6 +36,15 @@ export type InitializedConnectionSessionState = {
     experimentalApiEnabled: boolean;
     optedOutNotificationMethods: ReadonlySet<string>;
 };
+export type CodexAppServerConnectionSnapshot = {
+    initialized: InitializedConnectionSessionSnapshot | null;
+};
+export type InitializedConnectionSessionSnapshot = {
+    appServerClientName: string;
+    clientVersion: string;
+    experimentalApiEnabled: boolean;
+    optedOutNotificationMethods: string[];
+};
 export declare class CodexAppServerConnectionSessionState {
     readonly rpcGate: ConnectionRpcGate;
     private initializedState;
@@ -46,6 +55,8 @@ export declare class CodexAppServerConnectionSessionState {
     optedOutNotificationMethods(): ReadonlySet<string>;
     appServerClientName(): string | null;
     clientVersion(): string | null;
+    snapshot(): CodexAppServerConnectionSnapshot;
+    static fromSnapshot(snapshot?: CodexAppServerConnectionSnapshot | null): CodexAppServerConnectionSessionState;
 }
 export type CodexAppServerMessageProcessorOptions<Context = unknown> = {
     connectionId?: ConnectionId;

package/dist/internal/codex/codex-api/src/endpoint/responses_websocket.d.ts

@@ -3,7 +3,7 @@ import type { ResponseStream, ResponsesWsRequest, TurnState } from "../common.js
 type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 type WorkerWebSocket = WebSocket & {
     accept?: (options?: unknown) => void;
-    binaryType?: BinaryType;
+    binaryType?: "arraybuffer" | "blob";
 };
 export type ResponsesWebsocketClientInput = {
     api_key: string;

package/dist/runtime/index.d.ts

@@ -15,12 +15,12 @@ export { CodexAppServerClientTransportError, createCodexAppServerClient, parseCo
 export { jsonRpcInternalError, jsonRpcInvalidRequestError, jsonRpcParseError, parseClientTransportPayload, parseJsonRpcMessage, parseJsonRpcTransportPayload, parseServerTransportPayload, queuedOutgoingMessage, serializeJsonRpcError, serializeJsonRpcResponse, serializeOutgoingMessage, type ConnectionOrigin, type JSONRPCError, type JSONRPCMessage, type JSONRPCNotification, type JSONRPCRequest, type JSONRPCResponse, type ParsedClientTransportMessage, type ParsedServerTransportMessage, type ParsedTransportPayload, type TransportEvent, } from "../internal/codex/app-server-transport/src/transport/mod.js";
 export { OutgoingMessageSender, ThreadScopedOutgoingMessageSender, outgoingMessageToAppServerEvent, type ConnectionId, type ConnectionRequestId, type OutgoingError, type OutgoingMessage, type OutgoingResponse, type QueuedOutgoingMessage, type RequestContext, } from "../internal/codex/app-server/src/outgoing_message.js";
 export { CodexAppServerRequestError } from "../internal/codex/app-server/src/request_processors/request_errors.js";
-export { codexAppServerDeferredResponse, CodexAppServerConnectionSessionState, CodexAppServerMessageProcessor, type CodexAppServerMethodHandlers, type CodexAppServerRequestContext, type CodexAppServerDeferredResponse, type CodexAppServerConnectionRequestOutcome, type CodexAppServerMessageProcessorOptions, type InitializedConnectionSessionState, } from "../internal/codex/app-server/src/message_processor.js";
+export { codexAppServerDeferredResponse, CodexAppServerConnectionSessionState, CodexAppServerMessageProcessor, type CodexAppServerMethodHandlers, type CodexAppServerRequestContext, type CodexAppServerDeferredResponse, type CodexAppServerConnectionSnapshot, type CodexAppServerConnectionRequestOutcome, type CodexAppServerMessageProcessorOptions, type InitializedConnectionSessionSnapshot, type InitializedConnectionSessionState, } from "../internal/codex/app-server/src/message_processor.js";
 export { ConnectionRpcGate, ConnectionRpcGateClosedError, } from "../internal/codex/app-server/src/connection_rpc_gate.js";
 export { RequestSerializationQueues, requestSerializationQueueKeyFromScope, type RequestSerializationQueueKey, } from "../internal/codex/app-server/src/request_serialization.js";
 export { McpRequestProcessor, ThreadRequestProcessor, TurnRequestProcessor, type RuntimeSession, } from "../internal/codex/app-server/src/request_processors.js";
 export { createCodexAppServerRuntime, type CodexAppServerEventSink, type CodexAppServerOutgoingSink, type CodexAppServerRuntime, type CodexAppServerRuntimeContext, type CodexAppServerRuntimeOptions, } from "../internal/codex/app-server/src/runtime.js";
-export { AppServerSession, type CodexAppServer } from "../internal/codex/app-server-client/src/session.js";
+export { AppServerSession, type CodexAppServer, } from "../internal/codex/app-server-client/src/session.js";
 export { serverNotificationThreadTarget, serverRequestThreadId, threadEventSnapshotHasStarted, ThreadEventStore, type ServerNotificationThreadTarget, type ThreadBufferedEvent, type ThreadEventSnapshot, type ThreadTokenUsageSnapshot, } from "../internal/codex/app-server-client/src/thread_event_store.js";
 export { PendingAppServerRequests, type AppServerRequestResolution, type ResolvedAppServerRequest, type UnsupportedAppServerRequest, } from "../internal/codex/app-server-client/src/pending_requests.js";
 export { deniedRequestPermissionsResponse } from "../internal/codex/core/src/request_permissions.js";
@@ -36,7 +36,7 @@ export { ThreadHistoryBuilder } from "../internal/codex/core/src/thread-history-
 export type { Turn as ThreadHistoryTurn, TurnStatus as ThreadHistoryTurnStatus, } from "../internal/codex/core/src/thread-history-builder.js";
 export type { TextElement as CoreTextElement, UserInput as CoreUserInputItem, } from "../internal/codex/core/src/protocol/user_input.js";
 export type { TurnItem as CoreTurnItem, UserMessageTurnItem as CoreUserMessageTurnItem, } from "../internal/codex/core/src/items.js";
-export type { Model, ModelPreset } from "../internal/codex/core/src/model-provider.js";
+export type { Model, ModelPreset, } from "../internal/codex/core/src/model-provider.js";
 export { createModelClient, defaultModelsManager, ModelClientSession, ResponsesClient, ResponsesWebsocketClient, ResponsesWebsocketConnection, resolveReasoningEffortForModel, } from "../internal/codex/core/src/index.js";
 export type { CreateModelClientInput, ModelClient, ModelClientSessionHandle, Prompt, ResponseEvent, ResponseStream, ResponsesApiRequest, ResponsesClientInput, ResponseCreateWsRequest, ResponseProcessedWsRequest, ResponsesWsRequest, } from "../internal/codex/core/src/index.js";
 export { ThreadMemoryMode } from "../internal/codex/core/src/memory.js";

package/dist/server/app-server.d.ts

@@ -0,0 +1,60 @@
+import { type CodexAppServerRuntime, type CodexAppServerRuntimeContext, type CodexAppServerRuntimeOptions, type CodexAppServerConnectionSnapshot, type ConnectionId, type JSONRPCErrorError, type RequestId, type ServerRequest, type ThreadStore } from "../runtime/index.js";
+import { type DefinedDynamicTool } from "./dynamic-tools.js";
+export type PendingServerRequestRecord = {
+    createdAt: number;
+    request: ServerRequest;
+    requestId: RequestId;
+    threadId: string;
+};
+export type PendingServerRequestStore = {
+    delete(requestId: RequestId): Promise<void> | void;
+    get(requestId: RequestId): Promise<PendingServerRequestRecord | null> | PendingServerRequestRecord | null;
+    list(): Promise<PendingServerRequestRecord[]> | PendingServerRequestRecord[];
+    put(record: PendingServerRequestRecord): Promise<void> | void;
+    take(requestId: RequestId): Promise<PendingServerRequestRecord | null> | PendingServerRequestRecord | null;
+};
+export type CodexAppServerDefaults = {
+    baseInstructions?: string;
+    cwd?: string;
+    model?: string;
+    modelProvider?: string;
+    source?: string;
+    threadSource?: string | null;
+};
+export type CreateCodexAppServerOptions<Context = CodexAppServerRuntimeContext> = Omit<CodexAppServerRuntimeOptions<Context>, "sendOutgoingTransportMessage" | "store"> & {
+    defaults?: CodexAppServerDefaults;
+    dynamicTools?: readonly DefinedDynamicTool<Context>[];
+    pendingServerRequests?: PendingServerRequestStore;
+    /** @deprecated Use threadStore. */
+    store?: ThreadStore;
+    threadStore?: ThreadStore;
+};
+export type CodexAppServerConnection<Context = CodexAppServerRuntimeContext> = {
+    accept(message: unknown): Promise<void>;
+    close(): Promise<void>;
+    connectionId: ConnectionId;
+    processor: ReturnType<CodexAppServerRuntime<Context>["createMessageProcessor"]>;
+    snapshot(): CodexAppServerConnectionSnapshot;
+};
+export type CreateCodexAppServerConnectionOptions<Context = CodexAppServerRuntimeContext> = {
+    connectionId?: ConnectionId;
+    context?: Context;
+    onSnapshot?: (snapshot: CodexAppServerConnectionSnapshot) => void | Promise<void>;
+    send(message: string): void | Promise<void>;
+    snapshot?: CodexAppServerConnectionSnapshot | null;
+};
+export type CreatedCodexAppServer<Context = CodexAppServerRuntimeContext> = CodexAppServerRuntime<Context> & {
+    createConnection(options: CreateCodexAppServerConnectionOptions<Context>): CodexAppServerConnection<Context>;
+    pendingServerRequests: PendingServerRequestStore;
+};
+export declare class InMemoryPendingServerRequestStore implements PendingServerRequestStore {
+    private readonly records;
+    delete(requestId: RequestId): void;
+    get(requestId: RequestId): PendingServerRequestRecord | null;
+    list(): PendingServerRequestRecord[];
+    put(record: PendingServerRequestRecord): void;
+    take(requestId: RequestId): PendingServerRequestRecord | null;
+}
+export declare function createCodexAppServer<Context = CodexAppServerRuntimeContext>(options: CreateCodexAppServerOptions<Context>): CreatedCodexAppServer<Context>;
+export declare function createCodexAppServerConnection<Context = CodexAppServerRuntimeContext>(appServer: CreatedCodexAppServer<Context>, options: CreateCodexAppServerConnectionOptions<Context>): CodexAppServerConnection<Context>;
+export declare function jsonRpcErrorFromUnknown(error: unknown): JSONRPCErrorError;

package/dist/server/dynamic-tools.d.ts

@@ -0,0 +1,40 @@
+import type { DynamicToolCallParams, DynamicToolCallResponse, DynamicToolSpec } from "../runtime/index.js";
+export type DynamicToolExecutionContext<Context = unknown> = {
+    callId: string;
+    context?: Context;
+    namespace: string | null;
+    params: DynamicToolCallParams;
+    threadId: string;
+    tool: string;
+    turnId: string;
+};
+export type DynamicToolExecute<Context = unknown, Args = unknown> = (args: Args, context: DynamicToolExecutionContext<Context>) => DynamicToolCallResponse | Promise<DynamicToolCallResponse>;
+export type DynamicToolDefinition<Context = unknown, Args = unknown> = {
+    deferLoading?: boolean;
+    description: string;
+    execute?: DynamicToolExecute<Context, Args>;
+    inputSchema: unknown;
+    name: string;
+    namespace?: string | null;
+};
+export type DefinedDynamicTool<Context = unknown, Args = unknown> = Readonly<DynamicToolDefinition<Context, Args>>;
+export type DefinedDynamicToolset<Context = unknown> = readonly DefinedDynamicTool<Context>[];
+type DynamicToolDefinitionForValidation = {
+    deferLoading?: boolean;
+    description: string;
+    inputSchema: unknown;
+    name: string;
+    namespace?: string | null;
+};
+export declare const dynamicToolResponse: {
+    text(text: string): DynamicToolCallResponse;
+    image(imageUrl: string): DynamicToolCallResponse;
+    error(message: string): DynamicToolCallResponse;
+};
+export declare function defineDynamicTool<Context = unknown, Args = unknown>(definition: DynamicToolDefinition<Context, Args>): DefinedDynamicTool<Context, Args>;
+export declare function defineDynamicToolset<Context = unknown>(definitions: readonly DynamicToolDefinition<Context>[]): DefinedDynamicToolset<Context>;
+export declare function dynamicToolSpecFromDefinition(tool: DynamicToolDefinitionForValidation): DynamicToolSpec;
+export declare function dynamicToolSpecsFromDefinitions(tools: readonly DefinedDynamicTool[]): DynamicToolSpec[];
+export declare function findDynamicTool<Context>(tools: readonly DefinedDynamicTool<Context>[], params: DynamicToolCallParams): DefinedDynamicTool<Context> | null;
+export declare function validateDynamicToolDefinitions(tools: readonly DynamicToolDefinitionForValidation[]): void;
+export {};

package/dist/server/index.d.ts

@@ -1,2 +1,7 @@
 export { AppServerSession, asThreadId, BaseInstructions, CodexAppServerClientTransportError, CodexAppServerConnectionSessionState, codexAppServerDeferredResponse, CodexAppServerMessageProcessor, CodexAppServerRequestError, CodexMcpConnectionManagerAdapter, ConnectionRpcGate, ConnectionRpcGateClosedError, createCodexAppServerClient, createCodexAppServerRuntime, createModelClient, deniedRequestPermissionsResponse, EmptyMcpConnectionManager, InMemoryThreadStore, jsonRpcInternalError, jsonRpcInvalidRequestError, jsonRpcParseError, LiveThread, LocalThreadStore, McpRequestProcessor, ModelClientSession, OutgoingMessageSender, outgoingMessageToAppServerEvent, parseClientTransportPayload, parseCodexAppServerEvent, parseJsonRpcMessage, parseJsonRpcTransportPayload, parseServerTransportPayload, PendingAppServerRequests, queuedOutgoingMessage, requestMethodName, RequestSerializationQueues, requestSerializationQueueKeyFromScope, requestTyped, ResponsesClient, ResponsesWebsocketClient, ResponsesWebsocketConnection, serializeJsonRpcError, serializeJsonRpcResponse, serializeOutgoingMessage, serverNotificationRequiresDelivery, serverNotificationThreadTarget, serverRequestThreadId, setRenderedThreadConnectionStatus, SortDirection, StaticMcpConnectionManager, ThreadEventPersistenceMode, threadEventSnapshotHasStarted, ThreadEventStore, ThreadHistoryBuilder, ThreadMemoryMode, ThreadRequestProcessor, ThreadScopedOutgoingMessageSender, ThreadSortKey, TurnRequestProcessor, } from "../runtime/index.js";
-export type { AppendThreadItemsParams, AppServerEvent, AppServerRequestHandle, ClientRequest, ClientRequestSerializationScope, CodexAppServer, CodexAppServerClientConnectionStatus, CodexAppServerClientOptions, CodexAppServerDeferredResponse, CodexAppServerEventSink, CodexAppServerMethodHandlers, CodexAppServerOutgoingSink, CodexAppServerRequestContext, CodexAppServerRuntime, CodexAppServerRuntimeContext, CodexAppServerRuntimeOptions, CodexAppServerRuntimeOptions as CreateCodexAppServerRuntimeOptions, CodexAppServerRuntime as CreatedCodexAppServerRuntime, CollaborationMode, CollaborationModeListParams, CollaborationModeListResponse, CommandExecutionRequestApprovalResponse, ConnectionId, ConnectionOrigin, ConnectionRequestId, CreateModelClientInput, CreateThreadParams, DynamicToolCallParams, DynamicToolCallResponse, DynamicToolSpec, DynamicToolSpecWire, FileChangeRequestApprovalResponse, InitializedConnectionSessionState, InMemoryThreadStoreCalls, JSONRPCError, JSONRPCErrorError, JSONRPCMessage, JSONRPCNotification, JSONRPCRequest, JSONRPCResponse, ListMcpServerStatusParams, ListMcpServerStatusResponse, LocalThreadStoreConfig, McpConnectionManager, McpResourceInfo, McpResourceReadParams, McpResourceReadResponse, McpResourceTemplateInfo, McpRuntimeEnvironment, McpServerElicitationRequestResponse, McpServerOauthLoginParams, McpServerOauthLoginResponse, McpServerRefreshConfig, McpServerRefreshResponse, McpServerStatus, McpServerStatusListOptions, McpServerToolCallParams, McpServerToolCallResponse, McpToolInfo, Model, ModelClient, ModelClientSessionHandle, ModelPreset, OutgoingError, OutgoingMessage, OutgoingResponse, ParsedClientTransportMessage, ParsedServerTransportMessage, ParsedTransportPayload, PermissionsRequestApprovalResponse, Prompt, QueuedOutgoingMessage, RequestContext, RequestId, RequestSerializationQueueKey, ResponseCreateWsRequest, ResponseEvent, ResponseProcessedWsRequest, ResponseStream, ResponsesApiRequest, ResponsesClientInput, ResponsesWsRequest, Result, RuntimeSession, SandboxPolicy, ServerNotification, ServerNotificationThreadTarget, ServerRequest, StoredThread, StoredThreadHistory, Thread, ThreadArchiveParams, ThreadArchiveResponse, ThreadBufferedEvent, ThreadCompactStartParams, ThreadCompactStartResponse, ThreadEventSnapshot, ThreadId, ThreadItem, ThreadListParams, ThreadListResponse, ThreadMetadataPatch, ThreadMetadataUpdateParams, ThreadMetadataUpdateResponse, ThreadPage, ThreadPersistenceMetadata, ThreadReadParams, ThreadReadResponse, ThreadResumeParams, ThreadResumeResponse, ThreadSetNameParams, ThreadSetNameResponse, ThreadStartParams, ThreadStartResponse, ThreadStore, ThreadTokenUsageSnapshot, ThreadUnarchiveParams, ThreadUnarchiveResponse, ToolRequestUserInputResponse, TransportEvent, Turn, TurnInterruptParams, TurnInterruptResponse, TurnStartParams, TurnStartResponse, TurnSteerParams, TurnSteerResponse, TypedRequestError, UserInput, } from "../runtime/index.js";
+export { createCodexAppServer, createCodexAppServerConnection, InMemoryPendingServerRequestStore, jsonRpcErrorFromUnknown, } from "./app-server.js";
+export { dynamicToolResponse, defineDynamicTool, defineDynamicToolset, dynamicToolSpecFromDefinition, dynamicToolSpecsFromDefinitions, findDynamicTool, validateDynamicToolDefinitions, } from "./dynamic-tools.js";
+export { dynamicToolResponse as codexDynamicToolResponse, defineDynamicTool as defineCodexDynamicTool, defineDynamicToolset as defineCodexDynamicToolset, } from "./dynamic-tools.js";
+export type { AppendThreadItemsParams, AppServerEvent, AppServerRequestHandle, ArchiveThreadParams, ClientRequest, ClientRequestSerializationScope, CodexAppServer, CodexAppServerClientConnectionStatus, CodexAppServerClientOptions, CodexAppServerDeferredResponse, CodexAppServerEventSink, CodexAppServerMethodHandlers, CodexAppServerOutgoingSink, CodexAppServerRequestContext, CodexAppServerRuntime, CodexAppServerRuntimeContext, CodexAppServerRuntimeOptions, CodexAppServerConnectionSnapshot, CodexAppServerRuntimeOptions as CreateCodexAppServerRuntimeOptions, CodexAppServerRuntime as CreatedCodexAppServerRuntime, CollaborationMode, CollaborationModeListParams, CollaborationModeListResponse, CommandExecutionRequestApprovalResponse, ConnectionId, ConnectionOrigin, ConnectionRequestId, CreateModelClientInput, CreateThreadParams, DynamicToolCallParams, DynamicToolCallResponse, DynamicToolSpec, DynamicToolSpecWire, FileChangeRequestApprovalResponse, InitializedConnectionSessionState, InMemoryThreadStoreCalls, JSONRPCError, JSONRPCErrorError, JSONRPCMessage, JSONRPCNotification, JSONRPCRequest, JSONRPCResponse, ListMcpServerStatusParams, ListMcpServerStatusResponse, ListThreadsParams, LocalThreadStoreConfig, LoadThreadHistoryParams, McpConnectionManager, McpResourceInfo, McpResourceReadParams, McpResourceReadResponse, McpResourceTemplateInfo, McpRuntimeEnvironment, McpServerElicitationRequestResponse, McpServerOauthLoginParams, McpServerOauthLoginResponse, McpServerRefreshConfig, McpServerRefreshResponse, McpServerStatus, McpServerStatusListOptions, McpServerToolCallParams, McpServerToolCallResponse, McpToolInfo, Model, ModelClient, ModelClientSessionHandle, ModelPreset, OutgoingError, OutgoingMessage, OutgoingResponse, ParsedClientTransportMessage, ParsedServerTransportMessage, ParsedTransportPayload, PermissionsRequestApprovalResponse, Prompt, QueuedOutgoingMessage, RequestContext, RequestId, RequestSerializationQueueKey, ReadThreadByRolloutPathParams, ReadThreadParams, ResumeThreadParams, ResponseCreateWsRequest, ResponseEvent, ResponseProcessedWsRequest, ResponseStream, ResponsesApiRequest, ResponsesClientInput, ResponsesWsRequest, Result, RolloutItem, RuntimeSession, SandboxPolicy, ServerNotification, ServerNotificationThreadTarget, ServerRequest, StoredThread, StoredThreadHistory, Thread, ThreadArchiveParams, ThreadArchiveResponse, ThreadBufferedEvent, ThreadCompactStartParams, ThreadCompactStartResponse, ThreadEventSnapshot, ThreadId, ThreadItem, ThreadListParams, ThreadListResponse, ThreadMetadataPatch, ThreadMetadataUpdateParams, ThreadMetadataUpdateResponse, ThreadPage, ThreadPersistenceMetadata, UpdateThreadMetadataParams, ThreadReadParams, ThreadReadResponse, ThreadResumeParams, ThreadResumeResponse, ThreadSetNameParams, ThreadSetNameResponse, ThreadStartParams, ThreadStartResponse, ThreadStore, ThreadTokenUsageSnapshot, ThreadUnarchiveParams, ThreadUnarchiveResponse, ToolRequestUserInputResponse, TransportEvent, Turn, TurnInterruptParams, TurnInterruptResponse, TurnStartParams, TurnStartResponse, TurnSteerParams, TurnSteerResponse, TypedRequestError, UserInput, } from "../runtime/index.js";
+export type { CodexAppServerConnection, CodexAppServerDefaults, CreateCodexAppServerConnectionOptions, CreateCodexAppServerOptions, CreatedCodexAppServer, PendingServerRequestRecord, PendingServerRequestStore, } from "./app-server.js";
+export type { DefinedDynamicTool, DefinedDynamicToolset, DynamicToolDefinition, DynamicToolExecute, DynamicToolExecutionContext, } from "./dynamic-tools.js";

package/dist/server/index.js

@@ -4006,7 +4006,7 @@ function requestSerializationQueueKeyFromScope(connectionId, scope) {
 }
 
 // src/internal/codex/app-server/src/message_processor.ts
-var CodexAppServerConnectionSessionState = class {
+var CodexAppServerConnectionSessionState = class _CodexAppServerConnectionSessionState {
   rpcGate = new ConnectionRpcGate();
   initializedState = null;
   constructor(initializedState) {
@@ -4033,6 +4033,31 @@ var CodexAppServerConnectionSessionState = class {
   clientVersion() {
     return this.initializedState?.clientVersion ?? null;
   }
+  snapshot() {
+    return {
+      initialized: this.initializedState ? {
+        appServerClientName: this.initializedState.appServerClientName,
+        clientVersion: this.initializedState.clientVersion,
+        experimentalApiEnabled: this.initializedState.experimentalApiEnabled,
+        optedOutNotificationMethods: Array.from(
+          this.initializedState.optedOutNotificationMethods
+        )
+      } : null
+    };
+  }
+  static fromSnapshot(snapshot) {
+    if (!snapshot?.initialized) {
+      return new _CodexAppServerConnectionSessionState();
+    }
+    return new _CodexAppServerConnectionSessionState({
+      appServerClientName: snapshot.initialized.appServerClientName,
+      clientVersion: snapshot.initialized.clientVersion,
+      experimentalApiEnabled: snapshot.initialized.experimentalApiEnabled,
+      optedOutNotificationMethods: new Set(
+        snapshot.initialized.optedOutNotificationMethods
+      )
+    });
+  }
 };
 var CODEX_APP_SERVER_DEFERRED_RESPONSE = {
   __codexAppServerDeferredResponse: true
@@ -6477,8 +6502,7 @@ var WsStream = class {
   waiters = [];
   closed = false;
   is_closed() {
-    const closedState = typeof WebSocket !== "undefined" ? WebSocket.CLOSED : this.socket.CLOSED;
-    return this.closed || this.socket.readyState === (closedState ?? 3);
+    return this.closed || this.socket.readyState === 3;
   }
   send(message) {
     if (this.is_closed()) {
@@ -6504,9 +6528,11 @@ var WsStream = class {
     let timeout = null;
     try {
       return await Promise.race([
-        new Promise((resolve, reject) => {
-          this.waiters.push({ resolve, reject });
-        }),
+        new Promise(
+          (resolve, reject) => {
+            this.waiters.push({ resolve, reject });
+          }
+        ),
         new Promise((_, reject) => {
           if (timeoutMs && timeoutMs > 0) {
             timeout = setTimeout(
@@ -6760,7 +6786,11 @@ function closeLikeEvent() {
       reason: "websocket closed"
     });
   }
-  return { type: "close", code: 1006, reason: "websocket closed" };
+  return {
+    type: "close",
+    code: 1006,
+    reason: "websocket closed"
+  };
 }
 function isCloseEvent(event) {
   return event.type === "close";
@@ -19851,8 +19881,8 @@ var ThreadStateManager = class {
   }
 };
 
-// src/internal/codex/app-server/src/bespoke_event_handling.ts
-function apply_bespoke_event_handling(msg, context) {
+// src/internal/codex/app-server/src/app_server_event_mapping.ts
+function mapCoreEventToAppServerEvents(msg, context) {
   return eventMsgToAppServerEvents(msg, context);
 }
 
@@ -19884,7 +19914,11 @@ function createCodexAppServerRuntime(options) {
   });
   async function emit(threadId, event, context) {
     if (event.type === "server_notification") {
-      await outgoing.sendServerNotification(event.notification, context, threadId);
+      await outgoing.sendServerNotification(
+        event.notification,
+        context,
+        threadId
+      );
       return;
     }
     if (event.type === "server_request") {
@@ -19913,7 +19947,7 @@ function createCodexAppServerRuntime(options) {
     }
     const threadState = threadStateManager.threadState(threadId);
     const tracked = threadState.trackCurrentTurnEvent(event.id, event.msg);
-    const protocolEvents = apply_bespoke_event_handling(event.msg, {
+    const protocolEvents = mapCoreEventToAppServerEvents(event.msg, {
       activeTurn: tracked.activeTurn,
       terminalTurn: tracked.terminalTurn,
       threadId,
@@ -19992,9 +20026,7 @@ function createCodexAppServerRuntime(options) {
   async function resolveServerRequest(params) {
     const threadId = asThreadId(String(params.threadId));
     const targetKey = serverRequestTargetKey(threadId, params.requestId);
-    const request2 = outgoing.pendingRequestsForThread(threadId).find(
-      (candidate) => candidate.id === params.requestId
-    ) ?? null;
+    const request2 = outgoing.pendingRequestsForThread(threadId).find((candidate) => candidate.id === params.requestId) ?? null;
     if (!request2) {
       serverRequestTargets.delete(targetKey);
     }
@@ -20008,10 +20040,13 @@ function createCodexAppServerRuntime(options) {
     await submitServerRequestResponse(threadId, submission);
     serverRequestTargets.delete(targetKey);
     await outgoing.notifyClientResponse(params.requestId, params.result);
-    await emit(threadId, serverRequestResolvedNotification({
-      requestId: params.requestId,
-      threadId
-    }));
+    await emit(
+      threadId,
+      serverRequestResolvedNotification({
+        requestId: params.requestId,
+        threadId
+      })
+    );
   }
   async function connectionClosed(connectionId) {
     const emptyThreadIds = threadStateManager.removeConnection(connectionId);
@@ -20026,9 +20061,7 @@ function createCodexAppServerRuntime(options) {
   async function rejectServerRequest(params) {
     const threadId = asThreadId(String(params.threadId));
     const targetKey = serverRequestTargetKey(threadId, params.requestId);
-    const request2 = outgoing.pendingRequestsForThread(threadId).find(
-      (candidate) => candidate.id === params.requestId
-    ) ?? null;
+    const request2 = outgoing.pendingRequestsForThread(threadId).find((candidate) => candidate.id === params.requestId) ?? null;
     if (!request2) {
       serverRequestTargets.delete(targetKey);
     }
@@ -20042,18 +20075,25 @@ function createCodexAppServerRuntime(options) {
     await submitServerRequestResponse(threadId, submission);
     serverRequestTargets.delete(targetKey);
     await outgoing.notifyClientError(params.requestId, params.error);
-    await emit(threadId, serverRequestResolvedNotification({
-      requestId: params.requestId,
-      threadId
-    }));
+    await emit(
+      threadId,
+      serverRequestResolvedNotification({
+        requestId: params.requestId,
+        threadId
+      })
+    );
   }
   async function submitServerRequestResponse(threadId, submission) {
     if (!isServerRequestResponseSubmission(submission)) {
-      throw new Error("Only server-request response submissions can be routed through CodexAppServerRuntime.");
+      throw new Error(
+        "Only server-request response submissions can be routed through CodexAppServerRuntime."
+      );
     }
     const runtimeSession = sessions.get(threadId);
     if (!runtimeSession) {
-      throw new Error("Codex thread has no active turn for this server request response.");
+      throw new Error(
+        "Codex thread has no active turn for this server request response."
+      );
     }
     await runtimeSession.session.submit_with_id(submission);
   }
@@ -20485,4 +20525,437 @@ function dirname(path) {
   return separatorIndex <= 0 ? "/" : normalized.slice(0, separatorIndex);
 }
 
-export { AppServerSession, BaseInstructions, CodexAppServerClientTransportError, CodexAppServerConnectionSessionState, CodexAppServerMessageProcessor, CodexAppServerRequestError, CodexMcpConnectionManagerAdapter, ConnectionRpcGate, ConnectionRpcGateClosedError, EmptyMcpConnectionManager, InMemoryThreadStore, LiveThread, LocalThreadStore, McpRequestProcessor, ModelClientSession, OutgoingMessageSender, PendingAppServerRequests, RequestSerializationQueues, ResponsesClient, ResponsesWebsocketClient, ResponsesWebsocketConnection, SortDirection, StaticMcpConnectionManager, ThreadEventPersistenceMode, ThreadEventStore, ThreadHistoryBuilder, ThreadMemoryMode, ThreadRequestProcessor, ThreadScopedOutgoingMessageSender, ThreadSortKey, TurnRequestProcessor, asThreadId, codexAppServerDeferredResponse, createCodexAppServerClient, createCodexAppServerRuntime, createModelClient, deniedRequestPermissionsResponse, jsonRpcInternalError, jsonRpcInvalidRequestError, jsonRpcParseError, outgoingMessageToAppServerEvent, parseClientTransportPayload, parseCodexAppServerEvent, parseJsonRpcMessage, parseJsonRpcTransportPayload, parseServerTransportPayload, queuedOutgoingMessage, requestMethodName, requestSerializationQueueKeyFromScope, requestTyped, serializeJsonRpcError, serializeJsonRpcResponse, serializeOutgoingMessage, serverNotificationRequiresDelivery, serverNotificationThreadTarget, serverRequestThreadId, setRenderedThreadConnectionStatus, threadEventSnapshotHasStarted };
+// src/server/dynamic-tools.ts
+var RESPONSES_API_TOOL_NAME = /^[A-Za-z0-9_-]+$/u;
+var RESPONSES_API_TOOL_NAME_MAX_LENGTH = 64;
+var dynamicToolResponse = {
+  text(text) {
+    return {
+      contentItems: [{ text, type: "inputText" }],
+      success: true
+    };
+  },
+  image(imageUrl) {
+    return {
+      contentItems: [{ imageUrl, type: "inputImage" }],
+      success: true
+    };
+  },
+  error(message) {
+    return {
+      contentItems: [{ text: message, type: "inputText" }],
+      success: false
+    };
+  }
+};
+function defineDynamicTool(definition) {
+  const tool = Object.freeze({
+    ...definition,
+    deferLoading: definition.deferLoading ?? false,
+    namespace: definition.namespace ?? null
+  });
+  validateDynamicToolDefinitions([tool]);
+  return tool;
+}
+function defineDynamicToolset(definitions) {
+  const tools = definitions.map(
+    (definition) => Object.freeze({
+      ...definition,
+      deferLoading: definition.deferLoading ?? false,
+      namespace: definition.namespace ?? null
+    })
+  );
+  validateDynamicToolDefinitions(tools);
+  return Object.freeze(tools);
+}
+function dynamicToolSpecFromDefinition(tool) {
+  return {
+    defer_loading: tool.deferLoading ?? false,
+    description: tool.description,
+    input_schema: tool.inputSchema,
+    name: tool.name,
+    namespace: tool.namespace ?? null
+  };
+}
+function dynamicToolSpecsFromDefinitions(tools) {
+  return tools.map(dynamicToolSpecFromDefinition);
+}
+function findDynamicTool(tools, params) {
+  const namespace = params.namespace ?? null;
+  return tools.find(
+    (tool) => (tool.namespace ?? null) === namespace && tool.name === params.tool
+  ) ?? null;
+}
+function validateDynamicToolDefinitions(tools) {
+  const names = /* @__PURE__ */ new Set();
+  for (const tool of tools) {
+    validateResponsesApiName(tool.name, "name");
+    if (tool.namespace) {
+      validateResponsesApiName(tool.namespace, "namespace");
+    }
+    if ((tool.deferLoading ?? false) && !tool.namespace) {
+      throw new Error(
+        `Dynamic tool ${tool.name} uses deferLoading and must include a namespace.`
+      );
+    }
+    validateInputSchema(tool.name, tool.inputSchema);
+    const key = `${tool.namespace ?? ""}:${tool.name}`;
+    if (names.has(key)) {
+      throw new Error(
+        `Duplicate dynamic tool registration for ${tool.namespace ? `${tool.namespace}/` : ""}${tool.name}.`
+      );
+    }
+    names.add(key);
+  }
+}
+function validateResponsesApiName(value, label) {
+  if (value.length === 0 || value.length > RESPONSES_API_TOOL_NAME_MAX_LENGTH || !RESPONSES_API_TOOL_NAME.test(value)) {
+    throw new Error(
+      `Dynamic tool ${label} ${value} is not supported by the Responses API. Tool names and namespaces may only contain letters, numbers, underscores, and hyphens.`
+    );
+  }
+}
+function validateInputSchema(toolName, schema) {
+  if (!isRecord15(schema)) {
+    throw new Error(
+      `Dynamic tool ${toolName} inputSchema must be a JSON Schema object.`
+    );
+  }
+  if (schema.type !== "object") {
+    throw new Error(
+      `Dynamic tool ${toolName} inputSchema must use type "object".`
+    );
+  }
+  if ("properties" in schema && !isRecord15(schema.properties)) {
+    throw new Error(
+      `Dynamic tool ${toolName} inputSchema.properties must be an object when present.`
+    );
+  }
+  if ("required" in schema && !isStringArray(schema.required)) {
+    throw new Error(
+      `Dynamic tool ${toolName} inputSchema.required must be a string array when present.`
+    );
+  }
+}
+function isRecord15(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+// src/server/app-server.ts
+var nextConnectionId = 1;
+var InMemoryPendingServerRequestStore = class {
+  records = /* @__PURE__ */ new Map();
+  delete(requestId) {
+    this.records.delete(requestId);
+  }
+  get(requestId) {
+    return this.records.get(requestId) ?? null;
+  }
+  list() {
+    return Array.from(this.records.values());
+  }
+  put(record) {
+    this.records.set(record.requestId, record);
+  }
+  take(requestId) {
+    const record = this.get(requestId);
+    this.delete(requestId);
+    return record;
+  }
+};
+function createCodexAppServer(options) {
+  const threadStore = options.threadStore ?? options.store;
+  if (!threadStore) {
+    throw new Error("createCodexAppServer requires threadStore.");
+  }
+  const dynamicTools = [...options.dynamicTools ?? []];
+  const pendingServerRequests = options.pendingServerRequests ?? new InMemoryPendingServerRequestStore();
+  const connections = /* @__PURE__ */ new Map();
+  const subscriptions = /* @__PURE__ */ new Map();
+  const runtime = createCodexAppServerRuntime({
+    ...options,
+    store: threadStore,
+    buildCreateThreadParams: async (input) => {
+      const base = options.buildCreateThreadParams ? await options.buildCreateThreadParams(input) : {
+        base_instructions: {
+          text: input.params.baseInstructions ?? options.defaults?.baseInstructions ?? BaseInstructions.default().text
+        },
+        dynamic_tools: [],
+        event_persistence_mode: ThreadEventPersistenceMode.Limited,
+        metadata: {
+          cwd: input.params.cwd ?? options.defaults?.cwd ?? "/",
+          memory_mode: ThreadMemoryMode.Disabled,
+          model: input.params.model ?? options.defaults?.model ?? "gpt-5-mini",
+          model_provider: input.params.modelProvider ?? options.defaults?.modelProvider ?? "openai"
+        },
+        source: options.defaults?.source ?? "appServer",
+        thread_id: input.threadId,
+        thread_source: typeof input.params.threadSource === "string" ? input.params.threadSource : options.defaults?.threadSource ?? null
+      };
+      const resolvedTools = (await options.resolveDynamicTools?.(input))?.map((tool) => tool) ?? [];
+      return {
+        ...base,
+        dynamic_tools: [
+          ...base.dynamic_tools ?? [],
+          ...resolvedTools,
+          ...dynamicTools.map(dynamicToolSpecFromDefinition)
+        ]
+      };
+    },
+    buildSessionConfiguration: async (input) => {
+      const config = await options.buildSessionConfiguration?.(input) ?? {};
+      return {
+        ...config,
+        dynamic_tools: [
+          ...config.dynamic_tools ?? [],
+          ...dynamicTools.map(dynamicToolSpecFromDefinition)
+        ]
+      };
+    },
+    sendOutgoingTransportMessage: async (message, messageContext) => {
+      const handled = await maybeExecuteDynamicTool({
+        context: messageContext.context,
+        dynamicTools,
+        message,
+        runtime,
+        threadId: messageContext.threadId
+      });
+      if (handled) {
+        return;
+      }
+      if (isServerRequest2(message)) {
+        const threadId = messageContext.threadId ?? serverRequestThreadId(message);
+        if (threadId) {
+          await pendingServerRequests.put({
+            createdAt: Date.now(),
+            request: message,
+            requestId: message.id,
+            threadId: String(threadId)
+          });
+        }
+      }
+      await sendToConnections({
+        connectionIds: messageContext.connectionIds,
+        connections,
+        message,
+        subscriptions,
+        threadId: messageContext.threadId
+      });
+    }
+  });
+  function createConnection(connectionOptions) {
+    const connectionId = connectionOptions.connectionId ?? nextConnectionId++;
+    const session = CodexAppServerConnectionSessionState.fromSnapshot(
+      connectionOptions.snapshot
+    );
+    const processor = runtime.createMessageProcessor({
+      connectionId,
+      session
+    });
+    connections.set(connectionId, {
+      context: connectionOptions.context,
+      send: connectionOptions.send
+    });
+    if (session.initialized()) {
+      runtime.connectionInitialized(connectionId);
+    }
+    async function persistSnapshot() {
+      await connectionOptions.onSnapshot?.(processor.session.snapshot());
+    }
+    return {
+      async accept(message) {
+        const parsed = parseServerTransportPayload(message);
+        if (parsed.type === "invalid") {
+          await connectionOptions.send(
+            serializeJsonRpcError(parsed.id, parsed.error)
+          );
+          return;
+        }
+        switch (parsed.message.type) {
+          case "client_request": {
+            subscribeFromClientRequest(
+              subscriptions,
+              connectionId,
+              parsed.message.request
+            );
+            const outcome = await processor.processConnectionRequest(
+              parsed.message.request,
+              connectionOptions.context
+            );
+            if (parsed.message.request.method === "initialize") {
+              runtime.connectionInitialized(connectionId);
+            }
+            if (outcome.type === "response") {
+              subscribeFromResult(subscriptions, connectionId, outcome.result);
+            }
+            await persistSnapshot();
+            return;
+          }
+          case "response": {
+            const pending = await pendingServerRequests.take(
+              parsed.message.response.id
+            );
+            if (pending) {
+              await runtime.resolveServerRequest(
+                {
+                  requestId: parsed.message.response.id,
+                  result: parsed.message.response.result,
+                  threadId: pending.threadId
+                },
+                connectionOptions.context
+              );
+            }
+            await persistSnapshot();
+            return;
+          }
+          case "error": {
+            if (parsed.message.error.id !== null) {
+              const pending = await pendingServerRequests.take(
+                parsed.message.error.id
+              );
+              if (pending) {
+                await runtime.rejectServerRequest(
+                  {
+                    error: parsed.message.error.error,
+                    requestId: parsed.message.error.id,
+                    threadId: pending.threadId
+                  },
+                  connectionOptions.context
+                );
+              }
+            }
+            await persistSnapshot();
+            return;
+          }
+          case "client_notification":
+            await persistSnapshot();
+            return;
+        }
+      },
+      async close() {
+        connections.delete(connectionId);
+        for (const connectionIds of subscriptions.values()) {
+          connectionIds.delete(connectionId);
+        }
+        await processor.connectionClosed();
+        await runtime.connectionClosed(connectionId);
+      },
+      connectionId,
+      processor,
+      snapshot() {
+        return processor.session.snapshot();
+      }
+    };
+  }
+  return Object.assign(runtime, {
+    createConnection,
+    pendingServerRequests
+  });
+}
+function createCodexAppServerConnection(appServer, options) {
+  return appServer.createConnection(options);
+}
+async function maybeExecuteDynamicTool(input) {
+  if (!isDynamicToolCallRequest(input.message) || !input.threadId) {
+    return false;
+  }
+  const params = input.message.params;
+  const tool = findDynamicTool(input.dynamicTools, params);
+  if (!tool?.execute) {
+    return false;
+  }
+  try {
+    const result = await tool.execute(params.arguments, {
+      callId: params.callId,
+      context: input.context,
+      namespace: params.namespace ?? null,
+      params,
+      threadId: params.threadId,
+      tool: params.tool,
+      turnId: params.turnId
+    });
+    await input.runtime.resolveServerRequest(
+      {
+        requestId: input.message.id,
+        result,
+        threadId: input.threadId
+      },
+      input.context
+    );
+  } catch (error) {
+    await input.runtime.resolveServerRequest(
+      {
+        requestId: input.message.id,
+        result: dynamicToolResponse.error(
+          error instanceof Error ? error.message : "Dynamic tool failed."
+        ),
+        threadId: input.threadId
+      },
+      input.context
+    );
+  }
+  return true;
+}
+async function sendToConnections(input) {
+  const payload = serializeOutgoingMessage(input.message);
+  const recipients = recipientConnectionIds(input);
+  await Promise.all(
+    recipients.map(async (connectionId) => {
+      const connection = input.connections.get(connectionId);
+      if (connection) {
+        await connection.send(payload);
+      }
+    })
+  );
+}
+function recipientConnectionIds(input) {
+  if (input.connectionIds?.length) {
+    return input.connectionIds;
+  }
+  if (input.threadId) {
+    return Array.from(input.subscriptions.get(String(input.threadId)) ?? []);
+  }
+  return Array.from(input.connections.keys());
+}
+function subscribeFromClientRequest(subscriptions, connectionId, request2) {
+  const params = request2.params;
+  const threadId = typeof params?.threadId === "string" ? params.threadId : typeof params?.thread_id === "string" ? params.thread_id : null;
+  if (threadId) {
+    subscribe(subscriptions, connectionId, threadId);
+  }
+}
+function subscribeFromResult(subscriptions, connectionId, result) {
+  const threadId = result?.thread?.id;
+  if (typeof threadId === "string") {
+    subscribe(subscriptions, connectionId, threadId);
+  }
+}
+function subscribe(subscriptions, connectionId, threadId) {
+  const connectionIds = subscriptions.get(threadId) ?? /* @__PURE__ */ new Set();
+  connectionIds.add(connectionId);
+  subscriptions.set(threadId, connectionIds);
+}
+function isServerRequest2(message) {
+  return "method" in message && "id" in message;
+}
+function isDynamicToolCallRequest(message) {
+  return isServerRequest2(message) && message.method === "item/tool/call";
+}
+function jsonRpcErrorFromUnknown2(error) {
+  if (typeof error === "object" && error !== null && "code" in error && "message" in error && typeof error.code === "number" && typeof error.message === "string") {
+    return error;
+  }
+  const nested = error?.error;
+  if (typeof nested === "object" && nested !== null && "code" in nested && "message" in nested && typeof nested.code === "number" && typeof nested.message === "string") {
+    return nested;
+  }
+  return {
+    code: error instanceof CodexAppServerRequestError ? error.error.code : -32e3,
+    message: error instanceof Error ? error.message : "Codex request failed."
+  };
+}
+
+export { AppServerSession, BaseInstructions, CodexAppServerClientTransportError, CodexAppServerConnectionSessionState, CodexAppServerMessageProcessor, CodexAppServerRequestError, CodexMcpConnectionManagerAdapter, ConnectionRpcGate, ConnectionRpcGateClosedError, EmptyMcpConnectionManager, InMemoryPendingServerRequestStore, InMemoryThreadStore, LiveThread, LocalThreadStore, McpRequestProcessor, ModelClientSession, OutgoingMessageSender, PendingAppServerRequests, RequestSerializationQueues, ResponsesClient, ResponsesWebsocketClient, ResponsesWebsocketConnection, SortDirection, StaticMcpConnectionManager, ThreadEventPersistenceMode, ThreadEventStore, ThreadHistoryBuilder, ThreadMemoryMode, ThreadRequestProcessor, ThreadScopedOutgoingMessageSender, ThreadSortKey, TurnRequestProcessor, asThreadId, codexAppServerDeferredResponse, dynamicToolResponse as codexDynamicToolResponse, createCodexAppServer, createCodexAppServerClient, createCodexAppServerConnection, createCodexAppServerRuntime, createModelClient, defineDynamicTool as defineCodexDynamicTool, defineDynamicToolset as defineCodexDynamicToolset, defineDynamicTool, defineDynamicToolset, deniedRequestPermissionsResponse, dynamicToolResponse, dynamicToolSpecFromDefinition, dynamicToolSpecsFromDefinitions, findDynamicTool, jsonRpcErrorFromUnknown2 as jsonRpcErrorFromUnknown, jsonRpcInternalError, jsonRpcInvalidRequestError, jsonRpcParseError, outgoingMessageToAppServerEvent, parseClientTransportPayload, parseCodexAppServerEvent, parseJsonRpcMessage, parseJsonRpcTransportPayload, parseServerTransportPayload, queuedOutgoingMessage, requestMethodName, requestSerializationQueueKeyFromScope, requestTyped, serializeJsonRpcError, serializeJsonRpcResponse, serializeOutgoingMessage, serverNotificationRequiresDelivery, serverNotificationThreadTarget, serverRequestThreadId, setRenderedThreadConnectionStatus, threadEventSnapshotHasStarted, validateDynamicToolDefinitions };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrkropp/codex-js",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Unofficial TypeScript Codex runtime for building Codex-backed web apps.",
   "license": "Apache-2.0",
   "type": "module",