@gajae-code/ai 0.1.1

package/dist/types/utils/schema/normalize.d.ts

@@ -0,0 +1,93 @@
+import { type DescriptionSpillFormat } from "./spill";
+import { type JsonObject } from "./types";
+export type ResidualSchemaIncompatibility = "type-array" | "type-null" | "nullable" | "combiners";
+export interface NormalizeSchemaOptions {
+    unsupportedFields: (key: string) => boolean;
+    normalizeFieldNames: boolean;
+    collapseNullFields: boolean;
+    normalizeTypeArrayToNullable: boolean;
+    stripNullableKeyword: boolean;
+    autoPropertyOrdering: boolean;
+    ensureObjectProperties: boolean;
+    liftStrippedToDescription: false | {
+        keys?: (key: string) => boolean;
+        format?: DescriptionSpillFormat;
+    };
+    mergeObjectCombiners: boolean;
+    collapseSameTypeCombiners: boolean;
+    collapseMixedTypeCombiners: boolean;
+    stripResidualCombinersFixpoint: boolean;
+    extractNullableFromUnions: boolean;
+    rejectResidualIncompatibilities?: ReadonlyArray<ResidualSchemaIncompatibility>;
+    validateAndFallback?: {
+        fallback: unknown;
+    };
+}
+/** Copy all keys from a schema except the specified combiner key. */
+export declare function copySchemaWithout(schema: JsonObject, combiner: string): JsonObject;
+/**
+ * Recursively strip any remaining anyOf/oneOf that same-type or mixed-type
+ * collapse can handle. This is needed because object-combiner merging can
+ * create new anyOf in merged subtrees after child normalization already ran.
+ */
+export declare function stripResidualCombiners(value: unknown, epoch?: number): unknown;
+export declare function normalizeSchema(value: unknown, options: NormalizeSchemaOptions): unknown;
+export declare function normalizeSchemaForGoogle(value: unknown): unknown;
+export declare function normalizeSchemaForCCA(value: unknown): unknown;
+export declare function normalizeSchemaForMCP(value: unknown): unknown;
+/**
+ * OpenAI Responses rejects `oneOf` in tool schemas even when strict mode is
+ * disabled, and rejects every schema node with `type: "object"` unless it has
+ * a `properties` member. Normalize only schema-valued positions so literal
+ * payloads under `enum`, `const`, `default`, and `examples` remain unchanged.
+ *
+ * Identity-preserving: returns the input reference unchanged when no rewrite
+ * occurred so callers can dedupe via reference equality (and the strict-mode
+ * cache stays warm). If a node has both `oneOf` and `anyOf`, the two are
+ * concatenated (the wire payload accepts a single union; preserving both
+ * would not survive).
+ */
+export declare function sanitizeSchemaForOpenAIResponses(schema: JsonObject): JsonObject;
+/**
+ * Alias for {@link sanitizeSchemaForOpenAIResponses} matching the
+ * `normalizeSchemaFor*` dispatcher naming used elsewhere in this module.
+ */
+export declare const normalizeSchemaForOpenAIResponses: (schema: JsonObject) => JsonObject;
+/**
+ * First pass of strict-mode preparation.
+ *
+ * Rewrites everything strict mode forbids into something it accepts:
+ *  - Drops non-structural keywords (`format`, `pattern`, `examples`, …),
+ *    `const`, `nullable`, and `additionalProperties` (re-added by
+ *    `enforceStrictSchema` as `false`).
+ *  - `type: [a, b]` → `anyOf: [{type: a, …}, {type: b, …}]`, copying only the
+ *    keywords each variant can use (e.g. `properties` stays only on the
+ *    object variant).
+ *  - `const` → single-entry `enum`.
+ *  - Description carries a `(default: X)` suffix so the model still sees the
+ *    documented default after the keyword is stripped.
+ *  - `nullable: true` wraps the whole node in `anyOf:[T,{type:"null"}]`.
+ *
+ * Recurses into properties, items, prefixItems, combinators, and $defs. The
+ * `cache` WeakMap dedupes shared subgraphs; the `epoch` is the cycle guard.
+ */
+export declare function sanitizeSchemaForStrictMode(schema: Record<string, unknown>, epoch?: number, cache?: WeakMap<Record<string, unknown>, Record<string, unknown>>, root?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Recursively enforces JSON Schema constraints required by OpenAI/OpenAI code backend strict mode:
+ *   - `additionalProperties: false` on every object node
+ *   - every key in `properties` present in `required`
+ *
+ * Properties absent from the original `required` array were TypeBox-optional.
+ * They are made nullable (`anyOf: [T, { type: "null" }]`) so the model can
+ * signal omission by outputting null rather than omitting the key entirely.
+ *
+ * @throws {Error} When a schema node has no `type`, array-based combinator
+ *   (`anyOf`/`allOf`/`oneOf`), object-based combinator (`not`), or `$ref` —
+ *   i.e. the node is not representable in strict mode. Prefer
+ *   {@link tryEnforceStrictSchema} which catches this and degrades gracefully.
+ */
+export declare function enforceStrictSchema(schema: Record<string, unknown>, cache?: WeakMap<Record<string, unknown>, Record<string, unknown>>): Record<string, unknown>;
+export declare function tryEnforceStrictSchema(schema: Record<string, unknown>): {
+    schema: Record<string, unknown>;
+    strict: boolean;
+};

package/dist/types/utils/schema/spill.d.ts

@@ -0,0 +1,8 @@
+import type { JsonObject } from "./types";
+export type DescriptionSpillFormat = "spill" | "paren";
+/**
+ * Demote stripped JSON Schema keywords into a node's `description` so the model
+ * still receives the constraint as natural-language context after the wire
+ * schema drops it.
+ */
+export declare function spillToDescription(node: JsonObject, entries: ReadonlyArray<readonly [string, unknown]>, format?: DescriptionSpillFormat): void;

package/dist/types/utils/schema/stamps.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Symbol-keyed lazy memoization stamped directly onto the host object.
+ *
+ * Faster than a module-level `WeakMap` in V8/JSC because the symbol slot is
+ * resolved through the object's hidden class instead of a side-table hash
+ * lookup. The slot is defined as a non-enumerable property so the stamp
+ * does not leak through `{...spread}`, `Object.keys`, `JSON.stringify`, or
+ * `toEqual`-style deep equality.
+ *
+ * Caveats: the stamp lives as long as the host object, even after callers
+ * release their references to the cached value — only use this for caches
+ * whose lifetime should match the host. Frozen hosts will throw on write in
+ * strict mode; callers that may receive frozen input must handle that.
+ */
+export declare function stamp<T extends object, V>(target: T, key: symbol, compute: (target: T) => V): V;
+export declare function epochNext(): number;
+/**
+ * Marks `target` as visited for this `epoch`. Returns `true` the first time
+ * it is called for a given (target, epoch) pair and `false` on every
+ * subsequent call within the same epoch.
+ */
+export declare function once<T extends object>(target: T, epoch: number): boolean;
+/** Returns `true` on first entry, `false` if `target` is already on the current path. */
+export declare function enter<T extends object>(target: T): boolean;
+export declare function exit<T extends object>(target: T): void;

package/dist/types/utils/schema/types.d.ts

@@ -0,0 +1,4 @@
+export type JsonObject = Record<string, unknown>;
+export declare function isJsonObject(value: unknown): value is JsonObject;
+/** True when `value` is a plain JSON object with no own enumerable keys. */
+export declare function isJsonObjectEmpty(value: JsonObject): boolean;

package/dist/types/utils/schema/wire.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Compute the wire (JSON Schema) representation of a tool's parameters and
+ * convert TypeBox-style schemas into Zod for internal validation.
+ *
+ * Tools may author parameters in two shapes:
+ *   1. Zod (canonical going forward) — converted to JSON Schema on demand.
+ *   2. TypeBox / plain JSON Schema (legacy + extension compat) — upgraded to
+ *      draft 2020-12 without converting through Zod.
+ *
+ * Both are normalized at the boundary so providers and validators see the same
+ * JSON Schema dialect.
+ */
+import { type ZodType } from "zod/v4";
+import type { Tool } from "../../types";
+/**
+ * True when `value` is a live Zod schema instance.
+ *
+ * The check is stricter than "has a `_zod` property" because a JSON
+ * round-trip preserves the `_zod` key as a plain object and would otherwise
+ * fool the predicate — see issue #1101, where MCP servers ship
+ * `JSON.stringify(zodSchemaInstance)` as a tool's `inputSchema` and the
+ * resulting plain object then explodes `z.toJSONSchema` because the prototype
+ * (and every Zod parsing method) is gone.
+ *
+ * Live Zod instances always carry a `.parse` function on the prototype;
+ * impostors do not.
+ */
+export declare function isZodSchema(value: unknown): value is ZodType;
+/**
+ * Normalize `{}` (empty JSON Schema = `z.unknown()` / unconstrained value) to
+ * boolean `true` in every schema-valued position. JSON Schema draft 2020-12
+ * §4.3.1: `{}` and `true` are semantically equivalent ("any JSON value").
+ * Grammar-constrained samplers (llama.cpp, etc.) treat the object form as
+ * "generate an empty object" rather than "any JSON value", causing open-typed
+ * fields like `extra.title` (from `z.record(z.string(), z.unknown())`) to
+ * always emit `{}` instead of the intended string/number/etc. (issue #1179).
+ *
+ * Mutates in place. Provider-agnostic — applied to every tool wire schema so
+ * Anthropic, Google, OpenAI, Ollama, Bedrock, and Cursor all see the
+ * normalized form, regardless of whether the source was Zod or TypeBox.
+ */
+export declare function normalizeEmptySchemas(node: unknown): void;
+/** Convert a Zod schema into the JSON Schema shape providers consume. */
+export declare function zodToWireSchema(schema: ZodType): Record<string, unknown>;
+/**
+ * Resolve a tool's parameters to a JSON Schema object suitable for sending
+ * over the wire. Zod schemas are converted (and cached); legacy TypeBox / raw
+ * JSON Schema parameters are upgraded to draft 2020-12 (and cached).
+ *
+ * Both branches finish with `normalizeEmptySchemas` so every provider —
+ * OpenAI, Anthropic, Google, Ollama, Bedrock, Cursor — sees `{}` normalized
+ * to `true` in schema-valued positions (issue #1179).
+ */
+export declare function toolWireSchema(tool: Tool): Record<string, unknown>;

package/dist/types/utils/schema/zod-decontaminate.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Defensive rewrite for nodes that look like `JSON.stringify(zodSchemaInstance)`
+ * output rather than JSON Schema. MCP servers using Zod 4 sometimes ship a
+ * serialised schema instance directly as a tool's `inputSchema`, because the
+ * fields Zod surfaces on its instances (`type`, `enum`, `options`, `def`) shadow
+ * (and clash with) JSON Schema keywords. The resulting payload is neither valid
+ * Zod nor valid JSON Schema 2020-12 and Anthropic's strict validator rejects
+ * the whole tool list.
+ *
+ * Symptoms we've observed (gitnexus_impact.direction):
+ *   {
+ *     def:   { type: "enum", entries: { upstream: "upstream", ... } },
+ *     type:  "enum",                       // <- invalid `type` value
+ *     enum:  { upstream: "upstream", ... }, // <- `enum` MUST be an array
+ *     options: ["upstream", "downstream"],
+ *   }
+ *
+ * This module recognises the shape (`def.type === node.type` and `def.type` is
+ * a known Zod kind) and rewrites it to clean JSON Schema where deterministic.
+ * For Zod kinds we don't fully model, we strip the toxic siblings (`def`,
+ * `options`, object-shaped `enum`) and drop an invalid `type` so the remainder
+ * passes meta-schema validation as a permissive node.
+ *
+ * Pure / identity-preserving: returns the input reference when nothing changes.
+ */
+/**
+ * Walks a JSON value and rewrites every Zod-instance-shaped node into clean
+ * JSON Schema 2020-12. Identity-preserving when no rewrite fires. Tolerates
+ * self-referential graphs — a revisited node returns as-is.
+ */
+export declare function decontaminateZodInstance(value: unknown): unknown;

package/dist/types/utils/sse-debug.d.ts

@@ -0,0 +1,10 @@
+import type { ServerSentEvent } from "@gajae-code/utils";
+import type { RawSseEvent } from "../types";
+type FetchFunction = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+type FetchWithPreconnect = FetchFunction & {
+    preconnect?: typeof fetch.preconnect;
+};
+type RawSseObserver = (event: RawSseEvent) => void;
+export declare function notifyRawSseEvent(observer: RawSseObserver | undefined, event: ServerSentEvent | RawSseEvent): void;
+export declare function wrapFetchForSseDebug(fetchImpl: FetchWithPreconnect, observer: RawSseObserver | undefined): FetchWithPreconnect;
+export {};

package/dist/types/utils/tool-call-healing.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Streaming-safe filter for the Kimi K2 chat-template "tool-call section"
+ * grammar.
+ *
+ * Some providers hosting Kimi K2 (the native `kimi-code` API, OpenRouter,
+ * Fireworks, and others) leak the raw chat-template special tokens into
+ * `delta.content` instead of emitting structured `tool_calls`. Visually
+ * that looks like:
+ *
+ *     <|tool_calls_section_begin|>
+ *       <|tool_call_begin|>functions.read:0<|tool_call_argument_begin|>{"path":"foo"}<|tool_call_end|>
+ *     <|tool_calls_section_end|>
+ *
+ * Without healing, the user sees the raw markers and the agent loop never
+ * sees a tool call. This module reconstructs the embedded calls and strips
+ * the markers from visible text. It is stream-aware: any partial token at
+ * the end of a chunk is held back until the next chunk arrives.
+ */
+export interface HealedToolCall {
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: string;
+}
+/**
+ * State machine that consumes streamed text, emits visible text with all
+ * Kimi tool-call markers stripped, and accumulates the embedded tool calls
+ * for the caller to drain after each `feed()`.
+ *
+ * One instance per stream. Feed only the channel that may carry leaked
+ * markers (typically `delta.content`); mixing reasoning + content into the
+ * same accumulator corrupts the holdback buffer if both channels race in
+ * the same chunk.
+ */
+export declare class ToolCallHealer {
+    #private;
+    /**
+     * Feed a chunk of streamed text. Returns the portion safe to emit
+     * downstream (with all tokens stripped). Any partial token suffix is
+     * held back until the next chunk arrives or {@link flushPending} is
+     * called.
+     */
+    feed(text: string): string;
+    /**
+     * Like {@link feed}, but discards any tool calls that the chunk completes.
+     * Used when the upstream provider also emits structured `delta.tool_calls`
+     * for the same chunk: the healer still strips leaked marker text from the
+     * visible output, but the structured payload remains the single source of
+     * truth for the call list.
+     */
+    consumeWithoutCalls(text: string): string;
+    /**
+     * Drain accumulated tool calls. The internal list is cleared so a
+     * subsequent section in the same stream (rare) yields fresh calls.
+     */
+    drainCompleted(): HealedToolCall[];
+    /**
+     * Flush any held-back fragment when the stream ends. If we were mid-call
+     * the partial is dropped (emitting raw token bytes would surface markers
+     * to the user); otherwise the fragment is returned verbatim so a literal
+     * `<|` in prose is not silently lost.
+     */
+    flushPending(): string;
+    /** True once any tool-call section in this stream has fully closed. */
+    get sectionClosed(): boolean;
+}
+/**
+ * Cheap test for whether a given model is known to leak Kimi-K2 chat-template
+ * tool-call tokens into visible text. Used to gate the per-stream healer so
+ * non-Kimi providers do not pay for the scan.
+ */
+export declare function modelMayLeakKimiToolCalls(provider: string, modelId: string): boolean;

package/dist/types/utils/tool-choice.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Utility functions for mapping unified ToolChoice to provider-specific formats.
+ */
+import type { ToolChoice } from "../types";
+/** OpenAI Completions API tool choice format */
+export type OpenAICompletionsToolChoice = "auto" | "none" | "required" | {
+    type: "function";
+    function: {
+        name: string;
+    };
+} | undefined;
+/** OpenAI Responses API tool choice format (flat structure) */
+export type OpenAIResponsesToolChoice = "auto" | "none" | "required" | {
+    type: "function";
+    name: string;
+} | {
+    type: "custom";
+    name: string;
+} | undefined;
+/** Anthropic-compatible tool choice format */
+export type AnthropicToolChoice = "auto" | "none" | "any" | {
+    type: "tool";
+    name: string;
+} | undefined;
+/**
+ * Map unified ToolChoice to OpenAI Completions API format.
+ * - "any" → "required"
+ * - { type: "tool", name } → { type: "function", function: { name } }
+ */
+export declare function mapToOpenAICompletionsToolChoice(choice?: ToolChoice): OpenAICompletionsToolChoice;
+/**
+ * Returns true when an OpenAI-completions `tool_choice` value forces a tool
+ * call (`"required"` or a function-name pin), as opposed to leaving it open
+ * (`"auto"`, `"none"`, or unset). Accepts `unknown` because the param shape
+ * pulled from the OpenAI SDK (`ChatCompletionToolChoiceOption`) widens with
+ * each release; this check only needs the open/forced bit.
+ */
+export declare function isForcedToolChoice(choice: unknown): boolean;
+/**
+ * Map unified ToolChoice to OpenAI Responses API format.
+ * - "any" → "required"
+ * - { type: "tool", name } → { type: "function", name } (flat structure)
+ */
+export declare function mapToOpenAIResponsesToolChoice(choice?: ToolChoice): OpenAIResponsesToolChoice;
+/**
+ * Map unified ToolChoice to Anthropic-compatible format.
+ * - "required" → "any"
+ * - { type: "function", ... } → { type: "tool", name }
+ */
+export declare function mapToAnthropicToolChoice(choice?: ToolChoice): AnthropicToolChoice;

package/dist/types/utils/validation.d.ts

@@ -0,0 +1,17 @@
+import type { Tool, ToolCall } from "../types";
+/**
+ * Finds a tool by name and validates the tool call arguments against its schema.
+ * @param tools Array of tool definitions
+ * @param toolCall The tool call from the LLM
+ * @returns The validated arguments
+ * @throws Error if tool is not found or validation fails
+ */
+export declare function validateToolCall(tools: Tool[], toolCall: ToolCall): ToolCall["arguments"];
+/**
+ * Validates tool call arguments against the tool's schema (Zod or plain JSON
+ * Schema). Applies LLM-quirk coercions (numeric strings, JSON-string
+ * containers, null-for-optional, null-for-default) before declaring failure.
+ *
+ * @throws Error with a formatted message when validation cannot be reconciled.
+ */
+export declare function validateToolArguments(tool: Tool, toolCall: ToolCall): ToolCall["arguments"];

package/dist/types/utils.d.ts

@@ -0,0 +1,28 @@
+import type { ResponseInput } from "openai/resources/responses/responses";
+import type { CacheRetention, OpenAIResponsesHistoryPayload, ProviderPayload } from "./types";
+export { isRecord } from "@gajae-code/utils";
+export declare function normalizeSystemPrompts(systemPrompt: readonly string[] | string | undefined | null): string[];
+export declare function toNumber(value: unknown): number | undefined;
+export declare function toPositiveNumber(value: unknown, fallback: number): number;
+export declare function toBoolean(value: unknown): boolean | undefined;
+export declare function normalizeToolCallId(id: string): string;
+type ResponsesToolItemIdPrefix = "fc" | "ctc";
+export declare function normalizeResponsesToolCallId(id: string, itemPrefix?: ResponsesToolItemIdPrefix): {
+    callId: string;
+    itemId: string;
+};
+/**
+ * Truncate an OpenAI Responses API item ID to 64 characters.
+ * IDs exceeding the limit are replaced with a hash-based ID using the given prefix.
+ */
+export declare function truncateResponseItemId(id: string, prefix: string): string;
+export declare function sanitizeOpenAIResponsesHistoryItemsForReplay(items: Array<Record<string, unknown>>): ResponseInput;
+export declare function createOpenAIResponsesHistoryPayload(provider: string, items: Array<Record<string, unknown>>, incremental?: boolean): OpenAIResponsesHistoryPayload;
+export declare function getOpenAIResponsesHistoryPayload(providerPayload: ProviderPayload | undefined, currentProvider: string, fallbackProvider?: string): OpenAIResponsesHistoryPayload | undefined;
+export declare function getOpenAIResponsesHistoryItems(providerPayload: ProviderPayload | undefined, currentProvider: string, fallbackProvider?: string): Array<Record<string, unknown>> | undefined;
+/**
+ * Resolve cache retention preference.
+ * Defaults to "short" and uses PI_CACHE_RETENTION for backward compatibility.
+ */
+export declare function resolveCacheRetention(cacheRetention?: CacheRetention): CacheRetention;
+export declare function isAnthropicOAuthToken(key: string): boolean;

package/package.json

@@ -0,0 +1,146 @@
+{
+	"type": "module",
+	"name": "@gajae-code/ai",
+	"version": "0.1.1",
+	"description": "Unified LLM API with automatic model discovery and provider configuration",
+	"homepage": "https://gajae-code.dev",
+	"author": "Can Boluk",
+	"contributors": [
+		"Mario Zechner"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/gajae-ai/gajae-code.git",
+		"directory": "packages/ai"
+	},
+	"bugs": {
+		"url": "https://github.com/gajae-ai/gajae-code/issues"
+	},
+	"keywords": [
+		"ai",
+		"llm",
+		"openai",
+		"anthropic",
+		"gemini",
+		"unified",
+		"api"
+	],
+	"main": "./src/index.ts",
+	"types": "./dist/types/index.d.ts",
+	"bin": {
+		"pi-ai": "./src/cli.ts"
+	},
+	"scripts": {
+		"check": "biome check . && bun run check:types",
+		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"lint": "biome lint .",
+		"test": "bun test",
+		"fix": "biome check --write --unsafe .",
+		"fmt": "biome format --write .",
+		"generate-models": "bun scripts/generate-models.ts"
+	},
+	"dependencies": {
+		"@anthropic-ai/sdk": "^0.94.0",
+		"@bufbuild/protobuf": "^2.12.0",
+		"@gajae-code/utils": "0.1.1",
+		"openai": "^6.36.0",
+		"partial-json": "^0.1.7",
+		"zod": "4.4.3"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.14"
+	},
+	"engines": {
+		"bun": ">=1.3.14"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"CHANGELOG.md",
+		"dist/types"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./src/index.ts"
+		},
+		"./*": {
+			"types": "./dist/types/*.d.ts",
+			"import": "./src/*.ts"
+		},
+		"./auth-broker": {
+			"types": "./dist/types/auth-broker/index.d.ts",
+			"import": "./src/auth-broker/index.ts"
+		},
+		"./auth-broker/*": {
+			"types": "./dist/types/auth-broker/*.d.ts",
+			"import": "./src/auth-broker/*.ts"
+		},
+		"./auth-gateway": {
+			"types": "./dist/types/auth-gateway/index.d.ts",
+			"import": "./src/auth-gateway/index.ts"
+		},
+		"./auth-gateway/*": {
+			"types": "./dist/types/auth-gateway/*.d.ts",
+			"import": "./src/auth-gateway/*.ts"
+		},
+		"./models.json": {
+			"types": "./dist/types/models.json.d.d.ts",
+			"import": "./src/models.json"
+		},
+		"./provider-models": {
+			"types": "./dist/types/provider-models/index.d.ts",
+			"import": "./src/provider-models/index.ts"
+		},
+		"./provider-models/*": {
+			"types": "./dist/types/provider-models/*.d.ts",
+			"import": "./src/provider-models/*.ts"
+		},
+		"./providers/*": {
+			"types": "./dist/types/providers/*.d.ts",
+			"import": "./src/providers/*.ts"
+		},
+		"./providers/cursor/gen/*": {
+			"types": "./dist/types/providers/cursor/gen/*.d.ts",
+			"import": "./src/providers/cursor/gen/*.ts"
+		},
+		"./providers/openai-codex/*": {
+			"types": "./dist/types/providers/openai-codex/*.d.ts",
+			"import": "./src/providers/openai-codex/*.ts"
+		},
+		"./usage/*": {
+			"types": "./dist/types/usage/*.d.ts",
+			"import": "./src/usage/*.ts"
+		},
+		"./utils/*": {
+			"types": "./dist/types/utils/*.d.ts",
+			"import": "./src/utils/*.ts"
+		},
+		"./utils/discovery": {
+			"types": "./dist/types/utils/discovery/index.d.ts",
+			"import": "./src/utils/discovery/index.ts"
+		},
+		"./utils/discovery/*": {
+			"types": "./dist/types/utils/discovery/*.d.ts",
+			"import": "./src/utils/discovery/*.ts"
+		},
+		"./utils/oauth": {
+			"types": "./dist/types/utils/oauth/index.d.ts",
+			"import": "./src/utils/oauth/index.ts"
+		},
+		"./utils/oauth/*": {
+			"types": "./dist/types/utils/oauth/*.d.ts",
+			"import": "./src/utils/oauth/*.ts"
+		},
+		"./utils/schema": {
+			"types": "./dist/types/utils/schema/index.d.ts",
+			"import": "./src/utils/schema/index.ts"
+		},
+		"./utils/schema/*": {
+			"types": "./dist/types/utils/schema/*.d.ts",
+			"import": "./src/utils/schema/*.ts"
+		},
+		"./*.js": "./src/*.ts"
+	}
+}

package/src/api-registry.ts

@@ -0,0 +1,96 @@
+/**
+ * Custom API provider registry.
+ *
+ * Allows extensions to register streaming functions for custom API types
+ * (e.g., "vertex-Anthropic model-api") that are not built into stream.ts.
+ */
+import type {
+	Api,
+	AssistantMessageEventStream,
+	Context,
+	KnownApi,
+	Model,
+	SimpleStreamOptions,
+	StreamOptions,
+} from "./types";
+
+const BUILTIN_APIS = new Set<KnownApi>([
+	"openai-completions",
+	"openai-responses",
+	"openai-codex-responses",
+	"azure-openai-responses",
+	"anthropic-messages",
+	"bedrock-converse-stream",
+	"google-generative-ai",
+	"google-gemini-cli",
+	"google-vertex",
+	"ollama-chat",
+	"cursor-agent",
+]);
+
+export type CustomStreamFn = (
+	model: Model<Api>,
+	context: Context,
+	options?: StreamOptions,
+) => AssistantMessageEventStream;
+export type CustomStreamSimpleFn = (
+	model: Model<Api>,
+	context: Context,
+	options?: SimpleStreamOptions,
+) => AssistantMessageEventStream;
+
+export interface RegisteredCustomApi {
+	stream: CustomStreamFn;
+	streamSimple: CustomStreamSimpleFn;
+	sourceId?: string;
+}
+
+const customApiRegistry = new Map<string, RegisteredCustomApi>();
+
+function assertCustomApiName(api: string): void {
+	if (BUILTIN_APIS.has(api as KnownApi)) {
+		throw new Error(`Cannot register custom API "${api}": built-in API names are reserved.`);
+	}
+}
+
+/**
+ * Register a custom API streaming function.
+ */
+export function registerCustomApi(
+	api: string,
+	streamSimple: CustomStreamSimpleFn,
+	sourceId?: string,
+	stream?: CustomStreamFn,
+): void {
+	assertCustomApiName(api);
+	customApiRegistry.set(api, {
+		stream: stream ?? ((model, context, options) => streamSimple(model, context, options as SimpleStreamOptions)),
+		streamSimple,
+		sourceId,
+	});
+}
+
+/**
+ * Get a custom API provider by API identifier.
+ */
+export function getCustomApi(api: string): RegisteredCustomApi | undefined {
+	return customApiRegistry.get(api);
+}
+
+/**
+ * Remove all custom APIs registered by a specific source (e.g., extension path).
+ */
+export function unregisterCustomApis(sourceId: string): void {
+	for (const [api, entry] of customApiRegistry.entries()) {
+		if (entry.sourceId === sourceId) {
+			customApiRegistry.delete(api);
+		}
+	}
+}
+
+/**
+ * Clear all custom API registrations.
+ */
+export function clearCustomApis(): void {
+	customApiRegistry.clear();
+}