@linxiraos/pi-ai 1.0.0

package/dist/types/providers/google-types.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Local mirror of the subset of `@google/genai` types this package consumes.
+ *
+ * Field shapes match Gemini / Vertex AI wire format 1:1. Enum-shaped values are
+ * modelled as string literal unions so they pass through `JSON.stringify` and
+ * `JSON.parse` unchanged.
+ *
+ * Keep this file in sync with the actual request/response surface of:
+ *   - `POST {generativelanguage,aiplatform}.googleapis.com/.../models/{model}:streamGenerateContent?alt=sse`
+ *   - The Cloud Code Assist endpoint used by `google-gemini-cli.ts`
+ */
+/** Mirror of `@google/genai`'s `FinishReason` string enum. */
+export type FinishReason = "FINISH_REASON_UNSPECIFIED" | "STOP" | "MAX_TOKENS" | "SAFETY" | "RECITATION" | "LANGUAGE" | "OTHER" | "BLOCKLIST" | "PROHIBITED_CONTENT" | "SPII" | "MALFORMED_FUNCTION_CALL" | "IMAGE_SAFETY" | "IMAGE_PROHIBITED_CONTENT" | "IMAGE_RECITATION" | "IMAGE_OTHER" | "UNEXPECTED_TOOL_CALL" | "NO_IMAGE";
+/** Mirror of `@google/genai`'s `FunctionCallingConfigMode` string enum. */
+export type FunctionCallingConfigMode = "MODE_UNSPECIFIED" | "AUTO" | "NONE" | "ANY" | "VALIDATED";
+/** Mirror of `@google/genai`'s `ThinkingLevel` string enum. */
+export type ThinkingLevel = "THINKING_LEVEL_UNSPECIFIED" | "MINIMAL" | "LOW" | "MEDIUM" | "HIGH";
+/** Inline base64-encoded data part. */
+export interface InlineDataPart {
+    mimeType: string;
+    data: string;
+}
+/** Function call emitted by the model. */
+export interface FunctionCallPart {
+    name?: string;
+    args?: Record<string, unknown>;
+    id?: string;
+}
+/** Tool execution result fed back to the model. */
+export interface FunctionResponsePart {
+    name: string;
+    response: Record<string, unknown>;
+    parts?: Part[];
+    id?: string;
+}
+/**
+ * A single piece of a `Content` message. Mirrors the SDK's union by keeping
+ * every optional field — the model and the wire treat shape as discriminator.
+ */
+export interface Part {
+    text?: string;
+    thought?: boolean;
+    thoughtSignature?: string;
+    inlineData?: InlineDataPart;
+    functionCall?: FunctionCallPart;
+    functionResponse?: FunctionResponsePart;
+}
+/** Conversation turn. Roles: `"user"`, `"model"`, optionally absent for system instructions. */
+export interface Content {
+    role?: string;
+    parts?: Part[];
+}
+/** Thinking/reasoning configuration shared by Gemini 2.x and 3.x models. */
+export interface ThinkingConfig {
+    includeThoughts?: boolean;
+    thinkingBudget?: number;
+    thinkingLevel?: ThinkingLevel;
+}
+/** Function declaration entry inside `tools[].functionDeclarations`. */
+export interface FunctionDeclaration {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    parametersJsonSchema?: Record<string, unknown>;
+}
+/** Tool group as accepted at the request top level. */
+export interface ToolDeclaration {
+    functionDeclarations: Record<string, unknown>[];
+}
+/** Tool selection mode container. */
+export interface ToolConfig {
+    functionCallingConfig?: {
+        mode: FunctionCallingConfigMode;
+        allowedFunctionNames?: string[];
+    };
+}
+/**
+ * Generation/sampling and request-shape options passed via the SDK's `config`.
+ *
+ * Fields that the wire format places at the request body root (systemInstruction,
+ * tools, toolConfig, safetySettings, cachedContent) live here too — the
+ * transformer in `google-shared.ts` lifts them out when serializing.
+ */
+export interface GenerateContentConfig {
+    temperature?: number;
+    maxOutputTokens?: number;
+    topP?: number;
+    topK?: number;
+    candidateCount?: number;
+    stopSequences?: string[];
+    presencePenalty?: number;
+    frequencyPenalty?: number;
+    seed?: number;
+    responseMimeType?: string;
+    responseSchema?: Record<string, unknown>;
+    responseJsonSchema?: Record<string, unknown>;
+    responseModalities?: string[];
+    systemInstruction?: Content | {
+        role?: string;
+        parts: {
+            text: string;
+        }[];
+    };
+    tools?: ToolDeclaration[];
+    toolConfig?: ToolConfig;
+    safetySettings?: Array<Record<string, unknown>>;
+    cachedContent?: string;
+    thinkingConfig?: ThinkingConfig;
+    /**
+     * Gemini/Vertex serving tier. Serialized to the request body root as
+     * `serviceTier` (camelCase) by the transformer in `google-shared.ts`.
+     */
+    serviceTier?: "auto" | "default" | "flex" | "scale" | "priority";
+    abortSignal?: AbortSignal;
+}
+/** Top-level argument to `generateContentStream`. */
+export interface GenerateContentParameters {
+    model: string;
+    contents: Content[];
+    config?: GenerateContentConfig;
+}
+/** Per-stream candidate envelope. */
+export interface Candidate {
+    content?: Content;
+    finishReason?: FinishReason;
+    index?: number;
+}
+/** Cumulative token accounting attached to the trailing chunk. */
+export interface UsageMetadata {
+    promptTokenCount?: number;
+    candidatesTokenCount?: number;
+    thoughtsTokenCount?: number;
+    totalTokenCount?: number;
+    cachedContentTokenCount?: number;
+}
+/** Prompt-level safety feedback; `blockReason` is set (with no candidates) when the prompt is blocked. */
+export interface PromptFeedback {
+    blockReason?: string;
+    blockReasonMessage?: string;
+    [key: string]: unknown;
+}
+/** Single SSE chunk's parsed JSON body. */
+export interface GenerateContentResponse {
+    candidates?: Candidate[];
+    usageMetadata?: UsageMetadata;
+    modelVersion?: string;
+    responseId?: string;
+    promptFeedback?: PromptFeedback;
+    /** In-band stream failure (quota, internal error) delivered as a final JSON event. */
+    error?: {
+        code?: number;
+        message?: string;
+        status?: string;
+    };
+}

package/dist/types/providers/google-vertex.d.ts

@@ -0,0 +1,7 @@
+import type { StreamFunction } from "../types.js";
+import { type GoogleSharedStreamOptions } from "./google-shared.js";
+export interface GoogleVertexOptions extends GoogleSharedStreamOptions {
+    project?: string;
+    location?: string;
+}
+export declare const streamGoogleVertex: StreamFunction<"google-vertex">;

package/dist/types/providers/google.d.ts

@@ -0,0 +1,4 @@
+import type { StreamFunction } from "../types.js";
+import { type GoogleSharedStreamOptions } from "./google-shared.js";
+export type GoogleOptions = GoogleSharedStreamOptions;
+export declare const streamGoogle: StreamFunction<"google-generative-ai">;

package/dist/types/providers/grammar.d.ts

@@ -0,0 +1 @@
+export declare function compactGrammarDefinition(syntax: "lark" | "regex", definition: string): string;

package/dist/types/providers/kimi.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Kimi Code provider - wraps OpenAI or Anthropic API based on format setting.
+ *
+ * Kimi offers both OpenAI-compatible and Anthropic-compatible APIs:
+ * - OpenAI: https://api.kimi.com/coding/v1/chat/completions
+ * - Anthropic: https://api.kimi.com/coding/v1/messages
+ *
+ * Each discovered model selects its server-declared protocol; legacy models
+ * without protocol metadata retain the Anthropic-compatible default.
+ */
+import type { Api, Context, Model } from "../types.js";
+import type { AssistantMessageEventStream } from "../utils/event-stream.js";
+import { type OpenAIAnthropicApiFormat, type OpenAIAnthropicShimOptions } from "./openai-anthropic-shim.js";
+export type KimiApiFormat = OpenAIAnthropicApiFormat;
+export interface KimiOptions extends OpenAIAnthropicShimOptions {
+    /** Explicit API format override. Defaults to the model's discovered protocol. */
+    format?: KimiApiFormat;
+}
+/**
+ * Stream from Kimi Code, routing to either OpenAI or Anthropic API based on format.
+ * Returns synchronously like other providers - async header fetching happens internally.
+ */
+export declare function streamKimi(model: Model<"openai-completions">, context: Context, options?: KimiOptions): AssistantMessageEventStream;
+/**
+ * Check if a model is a Kimi Code model.
+ */
+export declare function isKimiModel(model: Model<Api>): boolean;

package/dist/types/providers/mock.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Mock provider for tests.
+ *
+ * Implements `Model<"mock">` + `streamMock` so test code can drive
+ * pi-agent-core / streamSimple-shaped consumers without an HTTP client.
+ *
+ * Usage:
+ *
+ *   import { createMockModel, registerMockApi } from "@linxiraos/pi-ai/providers/mock";
+ *
+ *   // 1. Array of responses, one per call.
+ *   const mock = createMockModel({
+ *     responses: [
+ *       { content: [{ type: "toolCall", name: "read", arguments: { path: "/x" } }] },
+ *       { content: ["done"] },
+ *     ],
+ *   });
+ *
+ *   // 2. Async generator — full state-machine power, can await between turns.
+ *   const mock = createMockModel({
+ *     responses: (async function* () {
+ *       yield { content: [{ type: "toolCall", name: "fetch", arguments: { url } }] };
+ *       // wait for external coordination
+ *       await externalReady;
+ *       yield { content: ["got it"] };
+ *     })(),
+ *   });
+ *
+ *   // 3. Per-call handler (closure with access to the call).
+ *   const mock = createMockModel({
+ *     handler: (context) => ({ content: [`turn ${context.messages.length}`] }),
+ *   });
+ *
+ *   // 4. Use as a streamFn for agentLoop:
+ *   await agentLoop(prompts, context, config, undefined, mock.stream).result();
+ *
+ *   // 5. Or register globally and use stream():
+ *   registerMockApi();
+ *   stream(mock.model, context, options);
+ *
+ *   // Inspect calls afterwards.
+ *   expect(mock.calls).toHaveLength(2);
+ */
+import type { Api, Context, Model, SimpleStreamOptions, StopDetails, StopReason, Usage } from "../types.js";
+import { AssistantMessageEventStream } from "../utils/event-stream.js";
+/** The API string this provider serves. */
+export declare const MOCK_API: "mock";
+export type MockApi = typeof MOCK_API;
+/** Shorthand for a single content block. Strings become text blocks. */
+export type MockContent = string | {
+    type: "text";
+    text: string;
+} | {
+    type: "thinking";
+    thinking: string;
+    thinkingSignature?: string;
+} | {
+    type: "toolCall";
+    /** Optional explicit id; auto-generated when omitted. */
+    id?: string;
+    name: string;
+    /** Object form is preferred; strings are passed through verbatim. */
+    arguments: Record<string, unknown> | string;
+};
+/** One scripted response. */
+export interface MockResponse {
+    /** Content blocks to emit, in order. Strings become text blocks. */
+    content?: ReadonlyArray<MockContent>;
+    /** Stop reason. Defaults to `"toolUse"` when content has tool calls, else `"stop"`. */
+    stopReason?: StopReason;
+    /** Structured terminal stop classification, e.g. Anthropic refusal metadata. */
+    stopDetails?: StopDetails | null;
+    /** Error text paired with an explicit `"error"` stop reason. */
+    errorMessage?: string;
+    /** Usage stats. Missing fields default to 0; missing `cost.total` is recomputed from components. */
+    usage?: Partial<Omit<Usage, "cost">> & {
+        cost?: Partial<Usage["cost"]>;
+    };
+    /** Pre-set responseId. */
+    responseId?: string;
+    /** If set, the stream emits a terminal error event instead of completing. */
+    throw?: string | Error;
+    /** Delay before any event is emitted. Honors the call's AbortSignal. */
+    delayMs?: number;
+    /**
+     * If set, the mock synthesizes a {@link ProviderResponseMetadata} and fires
+     * `options.onResponse` once before streaming events. Headers are forwarded
+     * verbatim (keys lowercased to match real provider plumbing).
+     */
+    responseHeaders?: Readonly<Record<string, string>>;
+    /** HTTP status code paired with {@link responseHeaders}. Defaults to 200. */
+    responseStatus?: number;
+    /** Pre-set requestId surfaced via {@link ProviderResponseMetadata.requestId}. */
+    responseRequestId?: string;
+}
+/** Handler resolved per call: static script or function. */
+export type MockHandler = MockResponse | ((context: Context, options?: SimpleStreamOptions) => MockResponse | Promise<MockResponse>);
+/**
+ * A source of handlers, one per call.
+ *
+ * - Arrays / iterables consume one entry per call (most ergonomic for scripts).
+ * - Async iterables (e.g. `async function*()`) let the test pause between calls,
+ *   coordinate with external events, or build state machines.
+ *
+ * The first call pulls the first entry, the second call pulls the second, and
+ * so on. When the source is exhausted, `MockModelOptions.handler` is used; if
+ * neither is set, the call rejects.
+ */
+export type MockResponseSource = Iterable<MockHandler> | AsyncIterable<MockHandler>;
+/** Recorded call for inspection. */
+export interface MockCall {
+    readonly context: Context;
+    readonly options?: SimpleStreamOptions;
+}
+/** Construction options. */
+export interface MockModelOptions {
+    /** Model id. Defaults to `"mock-model"`. */
+    id?: string;
+    /** Provider string used in the returned AssistantMessage. Defaults to `"mock"`. */
+    provider?: string;
+    /** A sequence of responses, one per call. Accepts arrays, generators, or any iterable. */
+    responses?: MockResponseSource;
+    /** Fallback handler used when `responses` is exhausted. */
+    handler?: MockHandler;
+    /** Cost per million tokens. Defaults to zeros. */
+    cost?: Model["cost"];
+    /** Context window. Defaults to 200_000. */
+    contextWindow?: number;
+    /** Max output tokens. Defaults to 32_768. */
+    maxTokens?: number;
+    /** Whether the model claims to support reasoning. Defaults to false. */
+    reasoning?: boolean;
+}
+/**
+ * A `Model<"mock">` that carries its own scripted state. Pass instances to
+ * `stream()` or agent configs, and use the same instance to inspect calls
+ * and feed additional handlers.
+ */
+export declare class MockModel implements Model<MockApi> {
+    readonly id: string;
+    readonly name: string;
+    readonly api: MockApi;
+    readonly provider: string;
+    readonly baseUrl = "mock://";
+    readonly reasoning: boolean;
+    readonly input: ("text" | "image")[];
+    readonly cost: Model["cost"];
+    readonly contextWindow: number;
+    readonly maxTokens: number;
+    readonly compat: undefined;
+    /** Recorded calls in invocation order. */
+    readonly calls: MockCall[];
+    iterator?: Iterator<MockHandler> | AsyncIterator<MockHandler>;
+    exhausted: boolean;
+    readonly extras: MockHandler[];
+    fallback?: MockHandler;
+    toolCallCounter: number;
+    constructor(options?: MockModelOptions);
+    /** Back-compat alias: the model is its own handle. */
+    get model(): this;
+    /** A streamFn-compatible callable. Forward to `agentLoop` or pi `stream()`. */
+    stream: (_model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
+    /**
+     * Append a handler to the internal queue consumed AFTER the constructor
+     * `responses` source is exhausted (but before the fallback). Use this for
+     * interactive tests that decide responses after the model is created.
+     */
+    push(response: MockHandler): void;
+    /** Reset recorded calls AND the extras queue. The constructor `responses` are NOT reset. */
+    reset(): void;
+}
+/** Check whether `model` was produced by `createMockModel`. */
+export declare function isMockModel(model: Model<Api>): model is MockModel;
+/** Construct a mock model. */
+export declare function createMockModel(options?: MockModelOptions): MockModel;
+/** Stream function for `Model<"mock">`. Matches the pi-ai per-provider stream signature. */
+export declare function streamMock(model: Model<Api>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream;
+/** Convenience: register the mock provider with the global custom API registry. */
+export declare function registerMockApi(sourceId?: string): void;

package/dist/types/providers/ollama.d.ts

@@ -0,0 +1,8 @@
+import type { StreamFunction, StreamOptions, ToolChoice } from "../types.js";
+export interface OllamaChatOptions extends StreamOptions {
+    reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+    disableReasoning?: boolean;
+    toolChoice?: ToolChoice;
+}
+/** Retry EOS-only Ollama completions before the agent loop sees an empty stop. */
+export declare const streamOllama: StreamFunction<"ollama-chat">;

package/dist/types/providers/openai-anthropic-shim.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared implementation for providers that expose BOTH an OpenAI-compatible
+ * and an Anthropic-compatible API surface against the same model catalog
+ * (currently Kimi Code and Synthetic).
+ *
+ * Each call site supplies the provider-specific bits (base URLs, default
+ * format, optional extra headers); the streaming/forwarding plumbing lives
+ * here once.
+ */
+import type { Context, Model, SimpleStreamOptions, ThinkingControlMode } from "../types.js";
+import { AssistantMessageEventStream } from "../utils/event-stream.js";
+export type OpenAIAnthropicApiFormat = "openai" | "anthropic";
+export interface OpenAIAnthropicShimOptions extends SimpleStreamOptions {
+    /** API format: "openai" or "anthropic". */
+    format?: OpenAIAnthropicApiFormat;
+}
+export interface OpenAIAnthropicShimConfig {
+    /** Base URL for the Anthropic-compatible endpoint (without trailing /v1/messages). */
+    anthropicBaseUrl: string;
+    /** Optional override for the OpenAI-compatible base URL. If omitted, `model.baseUrl` is used as-is. */
+    openaiBaseUrl?: string;
+    /** Default API format when caller does not specify one. */
+    defaultFormat: OpenAIAnthropicApiFormat;
+    /** Thinking transport used when this provider's Anthropic endpoint differs from generic budget semantics. */
+    anthropicThinkingMode?: ThinkingControlMode;
+    /** Forward cache-retention and request-metadata options to the selected transport. Default: false. */
+    forwardCacheOptions?: boolean;
+    /** Provider-specific headers (e.g. auth/session) merged ahead of user-supplied headers. */
+    extraHeaders?: () => Record<string, string>;
+}
+/**
+ * Stream from an OpenAI-or-Anthropic compatible provider. Returns synchronously;
+ * async header fetching and stream piping happen internally.
+ */
+export declare function streamOpenAIAnthropicShim(model: Model<"openai-completions">, context: Context, options: OpenAIAnthropicShimOptions | undefined, config: OpenAIAnthropicShimConfig): AssistantMessageEventStream;