@skydiveai/pi-server 0.1.0-beta.165

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Create, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# @skydiveai/pi-server
+
+Serve a [pi coding agent](https://github.com/earendil-works) over standard
+LLM API protocols. Platform-agnostic: you supply a `SessionFactory` that
+builds the pi session per request, and compose the handlers into your own
+HTTP server.
+
+Protocols:
+
+- OpenAI Chat Completions (`POST /v1/chat/completions`, plus mid-turn
+  steering via `POST /v1/chat/completions/{id}/steer`)
+- OpenAI Responses (`POST /v1/responses`)
+- Anthropic Messages (`POST /v1/messages`)
+- Google A2A (executor + request-origin-derived agent card)
+
+All handlers are web-standard `(Request) => Response | null` functions —
+null means "not mine", so they compose. `webHandlerToMiddleware` /
+`mountAt` / `chainMiddleware` bridge them onto node:http or express
+servers without this package depending on either.
+
+Configuration is injection-only: session construction (`createSession`),
+per-turn hooks (`onSessionSetup`, `postPrompt`), forwarded header
+prefixes, and prewarm paths are all options with no platform defaults.
+`@earendil-works/pi-coding-agent` is an exact-pinned peer dependency.
+
+See `src/protocols/PROTOCOL.md` for the wire-format reference.

package/dist/index.d.mts

@@ -0,0 +1,545 @@
+import { Logger, Logger as Logger$1 } from "pino";
+import { Api, KnownProvider, Model } from "@earendil-works/pi-ai";
+import { z } from "zod";
+import { SessionManager, ToolDefinition, createAgentSession } from "@earendil-works/pi-coding-agent";
+import { AgentExecutor } from "@a2a-js/sdk/server";
+import { AgentCard } from "@a2a-js/sdk";
+import { IncomingMessage, ServerResponse } from "node:http";
+
+//#region src/constants.d.ts
+declare const DEFAULT_PROVIDER = "anthropic";
+declare const DEFAULT_MODEL = "claude-opus-4-7";
+declare const DEFAULT_THINKING_LEVEL = "medium";
+declare const VALID_THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh"];
+declare const PI_AGENT_DIR: string;
+//#endregion
+//#region src/logger.d.ts
+declare const logger: Logger;
+type TraceContext = {
+  traceId: string;
+  spanId: string;
+  parentSpanId: string | null;
+  flags: string; /** Full `traceparent` header value to forward to downstreams. */
+  traceparent: string;
+};
+declare function newTraceContext(): TraceContext;
+/**
+ * Parse an incoming `traceparent` and mint a child span id under the same
+ * trace id. The parent span id is preserved so logs can stitch caller and
+ * callee. Returns a fresh root context if the header is missing or malformed.
+ */
+declare function deriveTraceContext(headerValue: unknown): TraceContext;
+/**
+ * Build a per-request child logger pre-bound with trace context. Every event
+ * emitted from `req` should go through this logger so it auto-inherits
+ * `trace_id`/`span_id`/`parent_span_id`.
+ */
+declare function requestLogger(request: Request): {
+  log: Logger;
+  trace: TraceContext;
+};
+//#endregion
+//#region src/session-registry.d.ts
+type SessionRegistry = {
+  get(id: string): AssistantSession | null;
+  set(id: string, session: AssistantSession): void;
+  delete(id: string): void;
+};
+declare function createMapSessionRegistry(): SessionRegistry;
+//#endregion
+//#region src/protocols/shared.d.ts
+type AssistantSession = Awaited<ReturnType<typeof createAgentSession>>['session'];
+type PostPromptCallback = (args: {
+  session: AssistantSession;
+  log: Logger$1;
+}) => Promise<void>;
+/**
+ * Synchronous hook invoked once per chat request, immediately after
+ * `createAgentSession` and before the first `session.prompt(...)` call.
+ * Used to install agent-loop callbacks (e.g. `shouldStopAfterTurn`) that
+ * pi-coding-agent's `AgentSession` does not surface directly.
+ */
+type SessionSetupCallback = (args: {
+  session: AssistantSession;
+  log: Logger$1;
+}) => void;
+type AgentSessionOptions = NonNullable<Parameters<typeof createAgentSession>[0]>;
+/**
+ * Everything a session build needs, resolved by the protocol handlers
+ * from the incoming request. The factory implementation lives in the
+ * agent's harness workspace (their index.ts) so session policy — skills
+ * paths, system prompt handling, steering modes — is theirs to edit.
+ */
+type CreateSessionArgs = {
+  cwd: string;
+  sessionId: string;
+  perRequestApiKeys: Partial<Record<KnownProvider, string>>;
+  systemPromptOverride: (() => string | undefined) | null; /** Per-request env from the x-shell-env header, if present. */
+  shellEnv: Record<string, string> | null;
+  model: AgentSessionOptions['model'];
+  thinkingLevel: AgentSessionOptions['thinkingLevel'] | null;
+  log: Logger$1;
+  /**
+   * Platform hook (tool-update auto-stop) — call with the created
+   * session BEFORE session.bindExtensions().
+   */
+  onSessionSetup: SessionSetupCallback;
+  /**
+   * Protocol-supplied work that needs the session manager before the
+   * agent session exists (preloading conversation history). Run it
+   * concurrently with resource loading.
+   */
+  prepare: ((args: {
+    sessionManager: SessionManager;
+  }) => Promise<void>) | null;
+};
+type SessionFactory = (args: CreateSessionArgs) => Promise<{
+  session: AssistantSession;
+  sessionManager: SessionManager;
+}>;
+type SharedHandlerOptions = {
+  cwd?: string;
+  createSession: SessionFactory;
+  onSessionSetup?: SessionSetupCallback;
+  postPrompt?: PostPromptCallback;
+  passthroughHeaderPrefixes?: string[];
+};
+//#endregion
+//#region src/protocols/a2a.d.ts
+type A2AOptions = SharedHandlerOptions & {
+  agentCard?: Partial<{
+    name: string;
+    description: string;
+    version: string;
+    /**
+     * Fixed public endpoint URL for the card. When unset, the served
+     * card derives it from each request's origin (x-forwarded-* aware),
+     * so the card advertises whatever public host reached it.
+     */
+    url: string;
+    skills: Array<{
+      id: string;
+      name: string;
+      description: string;
+    }>;
+  }>;
+};
+declare function createAgentExecutor(options: A2AOptions): AgentExecutor;
+declare function buildAgentCard(baseUrl: string, overrides: A2AOptions['agentCard']): AgentCard;
+//#endregion
+//#region src/protocols/anthropic-messages.d.ts
+type AnthropicMessagesOptions = SharedHandlerOptions & {
+  defaultModel?: string;
+  sessionRegistry?: SessionRegistry;
+};
+//#endregion
+//#region src/protocols/chat-completions.d.ts
+type ChatCompletionsOptions = SharedHandlerOptions & {
+  getTools?: (request: Request) => Promise<ToolDefinition[]> | ToolDefinition[];
+  defaultModel?: string;
+  sessionRegistry?: SessionRegistry;
+};
+//#endregion
+//#region src/protocols/responses.d.ts
+type ResponsesOptions = SharedHandlerOptions & {
+  defaultModel?: string;
+  sessionRegistry?: SessionRegistry;
+};
+//#endregion
+//#region src/protocols/index.d.ts
+type ProtocolName = 'chat-completions' | 'messages' | 'responses';
+type ProtocolHandler = (request: Request) => Promise<Response | null>;
+type ProtocolsOptions = {
+  cwd?: string;
+  /**
+   * Builds the pi agent session for every request. The implementation
+   * lives in the agent's harness workspace — session policy (skills
+   * paths, system prompt handling, steering modes) is theirs to edit.
+   */
+  createSession: SessionFactory;
+  onSessionSetup?: SessionSetupCallback;
+  postPrompt?: PostPromptCallback;
+  /**
+   * Incoming request header prefixes forwarded to the upstream model
+   * call (e.g. for proxy routing hints). None by default.
+   */
+  passthroughHeaderPrefixes?: string[];
+  /**
+   * Paths served by the prewarm handler (runs a 1-token chat completion
+   * in-process so first real requests skip cold-start). Disabled when
+   * empty.
+   */
+  prewarmPaths?: string[];
+  only?: ProtocolName[];
+  exclude?: ProtocolName[];
+  chatCompletions?: Partial<ChatCompletionsOptions>;
+  messages?: Partial<AnthropicMessagesOptions>;
+  responses?: Partial<ResponsesOptions>;
+};
+/**
+ * Build the individual protocol handlers, each returning null for
+ * requests it doesn't recognize. An in-memory session registry backs
+ * chat-completions steering unless deliberately overridden.
+ */
+declare function createProtocolHandlers(options: ProtocolsOptions): {
+  prewarm: (request: Request) => Promise<Response | null>;
+  chatCompletions: (request: Request) => Promise<Response | null>;
+  messages: (request: Request) => Promise<Response | null>;
+  responses: (request: Request) => Promise<Response | null>;
+};
+/** Chain handlers; null when none matched. */
+declare function composeHandlers(handlers: ProtocolHandler[]): ProtocolHandler;
+declare function createProtocols(options: ProtocolsOptions): (request: Request) => Promise<Response>;
+//#endregion
+//#region src/protocols/prewarm.d.ts
+declare function createPrewarm({
+  paths,
+  chatCompletions
+}: {
+  paths: string[];
+  chatCompletions: (request: Request) => Promise<Response | null>;
+}): (request: Request) => Promise<Response | null>;
+//#endregion
+//#region src/model-spec.d.ts
+/**
+ * Runtime mirror of pi-ai's `KnownProvider` union (which is type-only). The
+ * `satisfies` keeps every member valid against the type; new pi-ai providers
+ * are admitted by adding them here.
+ */
+declare const KNOWN_PI_PROVIDERS: readonly ["amazon-bedrock", "anthropic", "google", "google-vertex", "openai", "azure-openai-responses", "openai-codex", "deepseek", "github-copilot", "xai", "groq", "cerebras", "openrouter", "vercel-ai-gateway", "zai", "mistral", "minimax", "minimax-cn", "moonshotai", "moonshotai-cn", "huggingface", "fireworks", "opencode", "opencode-go", "kimi-coding", "cloudflare-workers-ai", "cloudflare-ai-gateway", "xiaomi", "xiaomi-token-plan-cn", "xiaomi-token-plan-ams", "xiaomi-token-plan-sgp"];
+declare const modelSpecSchema: z.ZodDiscriminatedUnion<"api", [z.ZodObject<{
+  api: z.ZodLiteral<"openai-completions">;
+  compat: z.ZodOptional<z.ZodObject<{
+    supportsReasoningEffort: z.ZodOptional<z.ZodBoolean>;
+    requiresThinkingAsText: z.ZodOptional<z.ZodBoolean>;
+    thinkingFormat: z.ZodOptional<z.ZodEnum<["openai", "openrouter", "deepseek", "zai", "qwen", "qwen-chat-template"]>>;
+    supportsStrictMode: z.ZodOptional<z.ZodBoolean>;
+    maxTokensField: z.ZodOptional<z.ZodEnum<["max_completion_tokens", "max_tokens"]>>;
+    cacheControlFormat: z.ZodOptional<z.ZodLiteral<"anthropic">>;
+  }, "strip", z.ZodTypeAny, {
+    supportsReasoningEffort?: boolean | undefined;
+    requiresThinkingAsText?: boolean | undefined;
+    thinkingFormat?: "openai" | "deepseek" | "openrouter" | "zai" | "qwen" | "qwen-chat-template" | undefined;
+    supportsStrictMode?: boolean | undefined;
+    maxTokensField?: "max_completion_tokens" | "max_tokens" | undefined;
+    cacheControlFormat?: "anthropic" | undefined;
+  }, {
+    supportsReasoningEffort?: boolean | undefined;
+    requiresThinkingAsText?: boolean | undefined;
+    thinkingFormat?: "openai" | "deepseek" | "openrouter" | "zai" | "qwen" | "qwen-chat-template" | undefined;
+    supportsStrictMode?: boolean | undefined;
+    maxTokensField?: "max_completion_tokens" | "max_tokens" | undefined;
+    cacheControlFormat?: "anthropic" | undefined;
+  }>>; /** Exact model id the serving endpoint expects. */
+  id: z.ZodString; /** Display name shown in pi surfaces and session logs. */
+  name: z.ZodString; /** pi-ai provider key — also the auth-storage key for `apiKey`. */
+  provider: z.ZodEnum<["amazon-bedrock", "anthropic", "google", "google-vertex", "openai", "azure-openai-responses", "openai-codex", "deepseek", "github-copilot", "xai", "groq", "cerebras", "openrouter", "vercel-ai-gateway", "zai", "mistral", "minimax", "minimax-cn", "moonshotai", "moonshotai-cn", "huggingface", "fireworks", "opencode", "opencode-go", "kimi-coding", "cloudflare-workers-ai", "cloudflare-ai-gateway", "xiaomi", "xiaomi-token-plan-cn", "xiaomi-token-plan-ams", "xiaomi-token-plan-sgp"]>; /** Provider API root, e.g. "https://openrouter.ai/api/v1". */
+  baseUrl: z.ZodString;
+  reasoning: z.ZodBoolean;
+  thinkingLevelMap: z.ZodOptional<z.ZodObject<{
+    off: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    minimal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    low: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    medium: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    high: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    xhigh: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  }, "strip", z.ZodTypeAny, {
+    medium?: string | null | undefined;
+    off?: string | null | undefined;
+    minimal?: string | null | undefined;
+    low?: string | null | undefined;
+    high?: string | null | undefined;
+    xhigh?: string | null | undefined;
+  }, {
+    medium?: string | null | undefined;
+    off?: string | null | undefined;
+    minimal?: string | null | undefined;
+    low?: string | null | undefined;
+    high?: string | null | undefined;
+    xhigh?: string | null | undefined;
+  }>>;
+  input: z.ZodArray<z.ZodEnum<["text", "image"]>, "atleastone">;
+  contextWindow: z.ZodNumber;
+  maxTokens: z.ZodNumber;
+  /**
+   * Optional runtime API key for `provider`, installed as a per-request key
+   * so the model registry's auth lookup succeeds. Deployments that resolve
+   * real credentials elsewhere (e.g. at an egress proxy) can pass whatever
+   * placeholder that layer recognizes — the value is opaque to this server.
+   */
+  apiKey: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+  api: "openai-completions";
+  id: string;
+  name: string;
+  provider: "anthropic" | "amazon-bedrock" | "google" | "google-vertex" | "openai" | "azure-openai-responses" | "openai-codex" | "deepseek" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "zai" | "mistral" | "minimax" | "minimax-cn" | "moonshotai" | "moonshotai-cn" | "huggingface" | "fireworks" | "opencode" | "opencode-go" | "kimi-coding" | "cloudflare-workers-ai" | "cloudflare-ai-gateway" | "xiaomi" | "xiaomi-token-plan-cn" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-sgp";
+  baseUrl: string;
+  reasoning: boolean;
+  input: ["text" | "image", ...("text" | "image")[]];
+  contextWindow: number;
+  maxTokens: number;
+  compat?: {
+    supportsReasoningEffort?: boolean | undefined;
+    requiresThinkingAsText?: boolean | undefined;
+    thinkingFormat?: "openai" | "deepseek" | "openrouter" | "zai" | "qwen" | "qwen-chat-template" | undefined;
+    supportsStrictMode?: boolean | undefined;
+    maxTokensField?: "max_completion_tokens" | "max_tokens" | undefined;
+    cacheControlFormat?: "anthropic" | undefined;
+  } | undefined;
+  thinkingLevelMap?: {
+    medium?: string | null | undefined;
+    off?: string | null | undefined;
+    minimal?: string | null | undefined;
+    low?: string | null | undefined;
+    high?: string | null | undefined;
+    xhigh?: string | null | undefined;
+  } | undefined;
+  apiKey?: string | undefined;
+}, {
+  api: "openai-completions";
+  id: string;
+  name: string;
+  provider: "anthropic" | "amazon-bedrock" | "google" | "google-vertex" | "openai" | "azure-openai-responses" | "openai-codex" | "deepseek" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "zai" | "mistral" | "minimax" | "minimax-cn" | "moonshotai" | "moonshotai-cn" | "huggingface" | "fireworks" | "opencode" | "opencode-go" | "kimi-coding" | "cloudflare-workers-ai" | "cloudflare-ai-gateway" | "xiaomi" | "xiaomi-token-plan-cn" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-sgp";
+  baseUrl: string;
+  reasoning: boolean;
+  input: ["text" | "image", ...("text" | "image")[]];
+  contextWindow: number;
+  maxTokens: number;
+  compat?: {
+    supportsReasoningEffort?: boolean | undefined;
+    requiresThinkingAsText?: boolean | undefined;
+    thinkingFormat?: "openai" | "deepseek" | "openrouter" | "zai" | "qwen" | "qwen-chat-template" | undefined;
+    supportsStrictMode?: boolean | undefined;
+    maxTokensField?: "max_completion_tokens" | "max_tokens" | undefined;
+    cacheControlFormat?: "anthropic" | undefined;
+  } | undefined;
+  thinkingLevelMap?: {
+    medium?: string | null | undefined;
+    off?: string | null | undefined;
+    minimal?: string | null | undefined;
+    low?: string | null | undefined;
+    high?: string | null | undefined;
+    xhigh?: string | null | undefined;
+  } | undefined;
+  apiKey?: string | undefined;
+}>, z.ZodObject<{
+  api: z.ZodLiteral<"anthropic-messages">;
+  compat: z.ZodOptional<z.ZodObject<{
+    supportsEagerToolInputStreaming: z.ZodOptional<z.ZodBoolean>;
+    supportsLongCacheRetention: z.ZodOptional<z.ZodBoolean>;
+  }, "strip", z.ZodTypeAny, {
+    supportsEagerToolInputStreaming?: boolean | undefined;
+    supportsLongCacheRetention?: boolean | undefined;
+  }, {
+    supportsEagerToolInputStreaming?: boolean | undefined;
+    supportsLongCacheRetention?: boolean | undefined;
+  }>>; /** Exact model id the serving endpoint expects. */
+  id: z.ZodString; /** Display name shown in pi surfaces and session logs. */
+  name: z.ZodString; /** pi-ai provider key — also the auth-storage key for `apiKey`. */
+  provider: z.ZodEnum<["amazon-bedrock", "anthropic", "google", "google-vertex", "openai", "azure-openai-responses", "openai-codex", "deepseek", "github-copilot", "xai", "groq", "cerebras", "openrouter", "vercel-ai-gateway", "zai", "mistral", "minimax", "minimax-cn", "moonshotai", "moonshotai-cn", "huggingface", "fireworks", "opencode", "opencode-go", "kimi-coding", "cloudflare-workers-ai", "cloudflare-ai-gateway", "xiaomi", "xiaomi-token-plan-cn", "xiaomi-token-plan-ams", "xiaomi-token-plan-sgp"]>; /** Provider API root, e.g. "https://openrouter.ai/api/v1". */
+  baseUrl: z.ZodString;
+  reasoning: z.ZodBoolean;
+  thinkingLevelMap: z.ZodOptional<z.ZodObject<{
+    off: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    minimal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    low: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    medium: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    high: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    xhigh: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  }, "strip", z.ZodTypeAny, {
+    medium?: string | null | undefined;
+    off?: string | null | undefined;
+    minimal?: string | null | undefined;
+    low?: string | null | undefined;
+    high?: string | null | undefined;
+    xhigh?: string | null | undefined;
+  }, {
+    medium?: string | null | undefined;
+    off?: string | null | undefined;
+    minimal?: string | null | undefined;
+    low?: string | null | undefined;
+    high?: string | null | undefined;
+    xhigh?: string | null | undefined;
+  }>>;
+  input: z.ZodArray<z.ZodEnum<["text", "image"]>, "atleastone">;
+  contextWindow: z.ZodNumber;
+  maxTokens: z.ZodNumber;
+  /**
+   * Optional runtime API key for `provider`, installed as a per-request key
+   * so the model registry's auth lookup succeeds. Deployments that resolve
+   * real credentials elsewhere (e.g. at an egress proxy) can pass whatever
+   * placeholder that layer recognizes — the value is opaque to this server.
+   */
+  apiKey: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+  api: "anthropic-messages";
+  id: string;
+  name: string;
+  provider: "anthropic" | "amazon-bedrock" | "google" | "google-vertex" | "openai" | "azure-openai-responses" | "openai-codex" | "deepseek" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "zai" | "mistral" | "minimax" | "minimax-cn" | "moonshotai" | "moonshotai-cn" | "huggingface" | "fireworks" | "opencode" | "opencode-go" | "kimi-coding" | "cloudflare-workers-ai" | "cloudflare-ai-gateway" | "xiaomi" | "xiaomi-token-plan-cn" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-sgp";
+  baseUrl: string;
+  reasoning: boolean;
+  input: ["text" | "image", ...("text" | "image")[]];
+  contextWindow: number;
+  maxTokens: number;
+  compat?: {
+    supportsEagerToolInputStreaming?: boolean | undefined;
+    supportsLongCacheRetention?: boolean | undefined;
+  } | undefined;
+  thinkingLevelMap?: {
+    medium?: string | null | undefined;
+    off?: string | null | undefined;
+    minimal?: string | null | undefined;
+    low?: string | null | undefined;
+    high?: string | null | undefined;
+    xhigh?: string | null | undefined;
+  } | undefined;
+  apiKey?: string | undefined;
+}, {
+  api: "anthropic-messages";
+  id: string;
+  name: string;
+  provider: "anthropic" | "amazon-bedrock" | "google" | "google-vertex" | "openai" | "azure-openai-responses" | "openai-codex" | "deepseek" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "zai" | "mistral" | "minimax" | "minimax-cn" | "moonshotai" | "moonshotai-cn" | "huggingface" | "fireworks" | "opencode" | "opencode-go" | "kimi-coding" | "cloudflare-workers-ai" | "cloudflare-ai-gateway" | "xiaomi" | "xiaomi-token-plan-cn" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-sgp";
+  baseUrl: string;
+  reasoning: boolean;
+  input: ["text" | "image", ...("text" | "image")[]];
+  contextWindow: number;
+  maxTokens: number;
+  compat?: {
+    supportsEagerToolInputStreaming?: boolean | undefined;
+    supportsLongCacheRetention?: boolean | undefined;
+  } | undefined;
+  thinkingLevelMap?: {
+    medium?: string | null | undefined;
+    off?: string | null | undefined;
+    minimal?: string | null | undefined;
+    low?: string | null | undefined;
+    high?: string | null | undefined;
+    xhigh?: string | null | undefined;
+  } | undefined;
+  apiKey?: string | undefined;
+}>]>;
+type ModelSpec = z.infer<typeof modelSpecSchema>;
+/**
+ * Parse a request-body `x_model`. Null when absent or invalid — never a
+ * request rejection, so a malformed spec degrades to the legacy body-model
+ * resolution instead of failing the turn.
+ */
+declare function parseModelSpec(input: unknown, log: Logger): ModelSpec | null;
+declare function buildModelFromSpec(spec: ModelSpec): {
+  compat?: {
+    supportsReasoningEffort?: boolean | undefined;
+    requiresThinkingAsText?: boolean | undefined;
+    thinkingFormat?: "openai" | "deepseek" | "openrouter" | "zai" | "qwen" | "qwen-chat-template" | undefined;
+    supportsStrictMode?: boolean | undefined;
+    maxTokensField?: "max_completion_tokens" | "max_tokens" | undefined;
+    cacheControlFormat?: "anthropic" | undefined;
+  } | undefined;
+  api: "openai-completions";
+  input: ["text" | "image", ...("text" | "image")[]];
+  cost: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+  };
+  contextWindow: number;
+  maxTokens: number;
+  thinkingLevelMap?: {
+    medium?: string | null | undefined;
+    off?: string | null | undefined;
+    minimal?: string | null | undefined;
+    low?: string | null | undefined;
+    high?: string | null | undefined;
+    xhigh?: string | null | undefined;
+  } | undefined;
+  id: string;
+  name: string;
+  provider: "anthropic" | "amazon-bedrock" | "google" | "google-vertex" | "openai" | "azure-openai-responses" | "openai-codex" | "deepseek" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "zai" | "mistral" | "minimax" | "minimax-cn" | "moonshotai" | "moonshotai-cn" | "huggingface" | "fireworks" | "opencode" | "opencode-go" | "kimi-coding" | "cloudflare-workers-ai" | "cloudflare-ai-gateway" | "xiaomi" | "xiaomi-token-plan-cn" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-sgp";
+  baseUrl: string;
+  reasoning: boolean;
+} | {
+  compat?: {
+    supportsEagerToolInputStreaming?: boolean | undefined;
+    supportsLongCacheRetention?: boolean | undefined;
+  } | undefined;
+  api: "anthropic-messages";
+  input: ["text" | "image", ...("text" | "image")[]];
+  cost: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+  };
+  contextWindow: number;
+  maxTokens: number;
+  thinkingLevelMap?: {
+    medium?: string | null | undefined;
+    off?: string | null | undefined;
+    minimal?: string | null | undefined;
+    low?: string | null | undefined;
+    high?: string | null | undefined;
+    xhigh?: string | null | undefined;
+  } | undefined;
+  id: string;
+  name: string;
+  provider: "anthropic" | "amazon-bedrock" | "google" | "google-vertex" | "openai" | "azure-openai-responses" | "openai-codex" | "deepseek" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "zai" | "mistral" | "minimax" | "minimax-cn" | "moonshotai" | "moonshotai-cn" | "huggingface" | "fireworks" | "opencode" | "opencode-go" | "kimi-coding" | "cloudflare-workers-ai" | "cloudflare-ai-gateway" | "xiaomi" | "xiaomi-token-plan-cn" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-sgp";
+  baseUrl: string;
+  reasoning: boolean;
+};
+/**
+ * Resolve the model a request should run on: a valid `x_model` wins,
+ * anything else falls back to registry resolution of the body model. Shared
+ * by every transport so they honor the spec identically.
+ */
+declare function resolveRequestModel({
+  modelInput,
+  modelSpecInput,
+  defaultModel,
+  log
+}: {
+  modelInput: unknown;
+  modelSpecInput: unknown;
+  defaultModel: string | undefined;
+  log: Logger;
+}): {
+  model: Model<Api>;
+  modelSpec: ModelSpec | null;
+};
+/**
+ * Install the spec's runtime API key as the per-request key for its
+ * provider. A caller-supplied key for the same provider (request headers)
+ * always wins.
+ */
+declare function withSpecApiKey(keys: Partial<Record<KnownProvider, string>>, modelSpec: ModelSpec | null): Partial<Record<KnownProvider, string>>;
+//#endregion
+//#region src/express.d.ts
+type WebHandler = (request: Request) => Promise<Response | null>;
+type Middleware = (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;
+declare function requestUrl(req: IncomingMessage): string;
+declare function requestHeaders(req: IncomingMessage): Headers;
+/**
+ * Mountable middleware for a web-standard handler. A null result calls
+ * next() so unmatched requests fall through to whatever the caller
+ * mounts after it.
+ */
+declare function webHandlerToMiddleware(handler: WebHandler): Middleware;
+/**
+ * Path-scope a middleware the way express mounting does: skip (next())
+ * unless the request path matches the prefix, and present a
+ * mount-relative req.url to the inner middleware. Lets express-style
+ * handlers that expect `app.use('/a2a', h)` participate in a composed
+ * catch-all.
+ */
+declare function mountAt(prefix: string, middleware: Middleware): Middleware;
+/** Run middlewares in order; each next() advances to the following one. */
+declare function chainMiddleware(middlewares: Middleware[]): Middleware;
+//#endregion
+//#region src/trace-context.d.ts
+declare function runInTraceContext<T>(fn: () => T): T;
+/** No-op when called outside `runInTraceContext`. */
+declare function setCurrentTraceparent(tp: string): void;
+declare function getCurrentTraceparent(): string | null;
+/** Extract the trace id (second segment) from a `traceparent` value. */
+declare function parseTraceId(traceparent: string | null): string | null;
+//#endregion
+export { type A2AOptions, type AnthropicMessagesOptions, type ChatCompletionsOptions, type CreateSessionArgs, DEFAULT_MODEL, DEFAULT_PROVIDER, DEFAULT_THINKING_LEVEL, KNOWN_PI_PROVIDERS, type Middleware, type ModelSpec, PI_AGENT_DIR, type PostPromptCallback, type ProtocolHandler, type ProtocolsOptions, type ResponsesOptions, type SessionFactory, type SessionSetupCallback, type TraceContext, VALID_THINKING_LEVELS, type WebHandler, buildAgentCard, buildModelFromSpec, chainMiddleware, composeHandlers, createAgentExecutor, createMapSessionRegistry, createPrewarm, createProtocolHandlers, createProtocols, deriveTraceContext, getCurrentTraceparent, logger, modelSpecSchema, mountAt, newTraceContext, parseModelSpec, parseTraceId, requestHeaders, requestLogger, requestUrl, resolveRequestModel, runInTraceContext, setCurrentTraceparent, webHandlerToMiddleware, withSpecApiKey };