@sayknow-cli/ai 0.4.2 → 0.4.3

package/dist/types/providers/openai-responses-shared.d.ts

@@ -0,0 +1,104 @@
+import type OpenAI from "openai";
+import type { ResponseInput, ResponseInputContent, ResponseOutputItem } from "openai/resources/responses/responses";
+import { type Api, type AssistantMessage, type ImageContent, type Model, type ServiceTier, type StopReason, type StreamOptions, type TextContent, type TextSignatureV1, type ToolCall, type ToolResultMessage } from "../types";
+import type { AssistantMessageEventStream } from "../utils/event-stream";
+export declare function encodeTextSignatureV1(id: string, phase?: TextSignatureV1["phase"]): string;
+export declare function parseTextSignature(signature: string | undefined): {
+    id: string;
+    phase?: TextSignatureV1["phase"];
+} | undefined;
+export declare function encodeResponsesToolCallId(callId: string, itemId: string | null | undefined): string;
+export declare function normalizeResponsesToolCallIdForTransform(id: string, model?: Model<Api>, source?: AssistantMessage): string;
+export declare function collectKnownCallIds(messages: ResponseInput): Set<string>;
+/** Scan replay items for call_ids that were originally custom tool calls. */
+export declare function collectCustomCallIds(messages: ResponseInput): Set<string>;
+/**
+ * Convert orphan `function_call_output` / `custom_tool_call_output` items —
+ * those whose `call_id` has no matching preceding `function_call` /
+ * `custom_tool_call` in the same input — into assistant text notes.
+ *
+ * The Responses API rejects unpaired outputs with
+ * `400 No tool call found for function call output with call_id …`. Orphans
+ * sneak in through two paths today:
+ *
+ * - A previous turn's `providerPayload` snapshot replaces the input array via
+ *   the `dt: false` splice (see {@link convertConversationMessages}), wiping
+ *   the matching `function_call` while leaving the matching
+ *   `function_call_output` queued in a later `toolResult`.
+ * - A locally-rejected tool call (argument-validation failure, hook reject,
+ *   aborted turn before the call streamed) produces a tool result without a
+ *   `function_call` ever landing in any persisted provider payload.
+ *
+ * Dropping the result loses information the model needs to recover; sending
+ * it as-is 400s the request. Folding it into an assistant `message` preserves
+ * the payload (call_id + truncated output) while staying within the Responses
+ * input grammar. Matches the behavior of {@link transformRequestBody} in the
+ * OpenAI code backend provider — issue #1351 / regression of #472.
+ */
+export declare function repairOrphanResponsesToolOutputs(input: ResponseInput): ResponseInput;
+export declare function convertResponsesInputContent(content: string | Array<TextContent | ImageContent>, supportsImages: boolean): ResponseInputContent[] | undefined;
+export declare function convertResponsesAssistantMessage<TApi extends Api>(assistantMsg: AssistantMessage, model: Model<TApi>, msgIndex: number, knownCallIds: Set<string>, includeThinkingSignatures?: boolean, customCallIds?: Set<string>): ResponseInput;
+export declare function appendResponsesToolResultMessages<TApi extends Api>(messages: ResponseInput, toolResult: ToolResultMessage, model: Model<TApi>, strictResponsesPairing: boolean, knownCallIds: ReadonlySet<string>, customCallIds?: ReadonlySet<string>): void;
+export interface ProcessResponsesStreamOptions {
+    onFirstToken?: () => void;
+    onOutputItemDone?: (item: ResponseOutputItem) => void;
+}
+export declare function processResponsesStream<TApi extends Api>(openaiStream: AsyncIterable<OpenAI.Responses.ResponseStreamEvent>, output: AssistantMessage, stream: AssistantMessageEventStream, model: Model<TApi>, options?: ProcessResponsesStreamOptions): Promise<void>;
+/**
+ * Mark tool-call blocks left incomplete by a length-truncated response so the
+ * agent loop rejects them instead of executing a best-effort partial parse.
+ *
+ * The universal signal is finalization: a call that never received its terminal
+ * `output_item.done` (passed in via `isFinalized`) was cut off mid-arguments.
+ * This covers both JSON function calls and raw-input custom tools without
+ * mis-flagging a *completed* custom tool whose raw input is not valid JSON. As a
+ * defensive secondary, a finalized JSON function call whose buffered arguments
+ * still don't parse (e.g. a misbehaving relay) is flagged too. No-op unless the
+ * turn stopped for length.
+ *
+ * Shared by both Responses providers (`openai-responses`, `openai-codex-responses`).
+ */
+export declare function flagTruncatedToolCalls(output: AssistantMessage, stopReason: StopReason, isFinalized: (block: ToolCall) => boolean): void;
+export declare function mapOpenAIResponsesStopReason(status: OpenAI.Responses.ResponseStatus | undefined): StopReason;
+/** Initial empty `AssistantMessage` that streaming providers accumulate into. */
+export declare function createInitialResponsesAssistantMessage(api: Api, provider: string, modelId: string): AssistantMessage;
+/** Extension fields we add on top of `ResponseCreateParamsStreaming` across the Responses-family providers. */
+export type ResponsesSamplingParamsExtras = {
+    top_p?: number;
+    top_k?: number;
+    min_p?: number;
+    presence_penalty?: number;
+    repetition_penalty?: number;
+};
+type CommonResponsesParams = OpenAI.Responses.ResponseCreateParamsStreaming & ResponsesSamplingParamsExtras;
+type CommonSamplingOptions = Pick<StreamOptions, "temperature" | "topP" | "topK" | "minP" | "presencePenalty" | "repetitionPenalty" | "maxTokens"> & {
+    serviceTier?: ServiceTier;
+};
+/**
+ * Apply the common `StreamOptions` → Responses sampling-parameter mapping (max output tokens,
+ * temperature, top-p/k, min-p, presence/repetition penalties, service tier). Mutates `params`.
+ */
+export declare function applyCommonResponsesSamplingParams<P extends CommonResponsesParams>(params: P, options: CommonSamplingOptions | undefined, provider: string): void;
+type ReasoningOptions = {
+    reasoning?: string;
+    reasoningSummary?: "auto" | "detailed" | "concise" | null;
+};
+/**
+ * Apply reasoning-related Responses parameters: enable encrypted reasoning content for replay,
+ * set effort/summary when requested, and otherwise inject the GPT-5 "Juice: 0" no-reasoning hack.
+ * Mutates `params` and may push a developer message into `messages`.
+ */
+export declare function applyResponsesReasoningParams<P extends OpenAI.Responses.ResponseCreateParamsStreaming>(params: P, model: Model<Api>, options: ReasoningOptions | undefined, messages: ResponseInput, mapEffort?: (effort: string) => string): void;
+/** Populate `output.usage` from a Responses-API `response.usage` payload. Does not invoke `calculateCost`. */
+export declare function populateResponsesUsageFromResponse(output: AssistantMessage, usage: {
+    input_tokens?: number | null;
+    output_tokens?: number | null;
+    total_tokens?: number | null;
+    input_tokens_details?: {
+        cached_tokens?: number | null;
+    } | null;
+    output_tokens_details?: {
+        reasoning_tokens?: number | null;
+    } | null;
+} | null | undefined): void;
+export {};

package/dist/types/providers/openai-responses.d.ts

@@ -0,0 +1,32 @@
+import type { Tool as OpenAITool } from "openai/resources/responses/responses";
+import type { Model, ServiceTier, StreamFunction, StreamOptions, Tool, ToolChoice } from "../types";
+import { type OpenAIResponsesToolChoice } from "../utils/tool-choice";
+export declare function normalizeOpenAIResponsesPromptCacheKey(sessionId: string | undefined): string | undefined;
+export interface OpenAIResponsesOptions extends StreamOptions {
+    reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+    reasoningSummary?: "auto" | "detailed" | "concise" | null;
+    serviceTier?: ServiceTier;
+    toolChoice?: ToolChoice;
+    /**
+     * Enforce strict tool call/result pairing when building Responses API inputs.
+     * Azure OpenAI and GitHub Copilot Responses paths require tool results to match prior tool calls.
+     */
+    strictResponsesPairing?: boolean;
+}
+/**
+ * Generate function for OpenAI Responses API
+ */
+export declare const streamOpenAIResponses: StreamFunction<"openai-responses">;
+export declare function supportsDeveloperRole(modelOrBaseUrl: Pick<Model, "provider" | "baseUrl"> | string): boolean;
+/**
+ * Whether this model should get the OpenAI custom-tool grammar variant
+ * for `apply_patch`. The generated model catalog sets
+ * `model.applyPatchToolType` for first-party GPT-5 Responses models; this
+ * runtime path only consumes that metadata.
+ * @internal Exported for tests.
+ */
+export declare function supportsFreeformApplyPatch(model: Model<"openai-responses">): boolean;
+/** @internal Exported for tests. */
+export declare function mapOpenAIResponsesToolChoiceForTools(choice: ToolChoice | undefined, tools: Tool[], model: Model<"openai-responses">): OpenAIResponsesToolChoice;
+/** @internal Exported for tests. */
+export declare function convertTools(tools: Tool[], strictMode: boolean, model: Model<"openai-responses">): OpenAITool[];

package/dist/types/providers/pi-native-client.d.ts

@@ -0,0 +1,13 @@
+import type { Api, AssistantMessageEventStream as AssistantMessageEventStreamType, Context, Model, SimpleStreamOptions } from "../types";
+/**
+ * Stream a turn through an `skc auth-gateway` over the pi-native protocol.
+ *
+ * The returned {@link AssistantMessageEventStream} receives each parsed
+ * `AssistantMessageEvent` verbatim from the gateway; the terminal `done` /
+ * `error` event resolves `.result()` automatically via the base class's
+ * completion check. Non-streaming consumers just call `.result()` and pay
+ * for SSE framing they don't use — that overhead is dominated by provider
+ * latency, so we always stream rather than maintaining a parallel
+ * non-streaming path.
+ */
+export declare function streamPiNative<TApi extends Api>(model: Model<TApi>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStreamType;

package/dist/types/providers/pi-native-server.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Pi-native wire format for the auth-gateway.
+ *
+ * Where the OpenAI / Anthropic / Responses route modules translate foreign
+ * wire shapes through pi-ai's canonical {@link Context}, this module accepts
+ * the canonical shape *directly* — for clients that already speak pi-ai
+ * (containerized SKC deployments and sidecar auth gateways).
+ * Skipping the wire-format → Context → wire-format round-trip cuts
+ * per-request CPU but, more importantly, avoids the quantization that those
+ * translations impose on first-class pi-ai fields (service tier, cache
+ * markers, thinking budgets, tool-choice variants, …).
+ *
+ * The streaming wire is {@link AssistantMessageEvent} serialized as SSE. Public
+ * projections omit private raw reasoning and serialized Responses reasoning
+ * signatures while preserving provider-displayable summaries and genuine opaque
+ * signatures. Including `partial: AssistantMessage` on every delta is O(N²) in
+ * turn length on the wire — acceptable for the loopback / sidecar topology this
+ * transport is designed for; provider latency dominates the actual cost.
+ *
+ * Endpoint contract:
+ *   POST /v1/pi/stream
+ *   body:    { modelId, context, options?, stream? }   // `stream` defaults to true
+ *   200 SSE: stream of `AssistantMessageEvent` (terminated by `data: [DONE]`)
+ *   200 JSON (stream=false): { message: AssistantMessage }
+ *   4xx/5xx: { error: { type, message } }
+ */
+import type { AssistantMessageEventStream, Context, SimpleStreamOptions } from "../types";
+export interface PiNativeParsedRequest {
+    modelId: string;
+    context: Context;
+    options: SimpleStreamOptions;
+    stream: boolean;
+}
+/**
+ * Parse a pi-native request body. Validation is intentionally minimal — only
+ * the shape the gateway itself reads is checked (`modelId`, `context.messages`
+ * array, options is an object). Everything downstream is the canonical pi-ai
+ * type surface; mis-shaped values surface as a `502 upstream_error` from
+ * `streamSimple` rather than being re-validated here.
+ *
+ * Accepts both `{ modelId: string }` and `{ model: { id: string } }` so the
+ * existing `streamProxy` client (which sends the full Model object) can target
+ * the gateway with only a URL swap.
+ */
+export declare function parseRequest(body: unknown, _headers?: Headers): PiNativeParsedRequest;
+/**
+ * Ship only public-safe {@link AssistantMessageEvent} projections. Unknown
+ * thinking blocks remain buffered until their terminal partial establishes that
+ * the provider-native block is safe; raw and mixed blocks never reach SSE.
+ */
+export declare function encodeStream(events: AssistantMessageEventStream): ReadableStream<Uint8Array>;
+/**
+ * Pi-native error envelope:
+ *   `{ error: { type, message } }`
+ *
+ * Mirrors OpenAI's outer shape (which clients/SDKs already parse) without the
+ * provider-specific status taxonomy — pi-native callers consume `type`
+ * directly.
+ */
+export declare function formatError(status: number, type: string, message: string): Response;

package/dist/types/providers/register-builtins.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Lazy provider module loading.
+ *
+ * Each provider module is loaded only when its stream function is first called.
+ * This avoids eagerly importing heavy SDK dependencies (e.g., @anthropic-ai/sdk,
+ * openai) at startup. The loaded module promise is cached so subsequent calls
+ * reuse the same import.
+ *
+ * stream.ts imports its provider stream functions from this module (see the
+ * lazy wrappers below), so this file IS the main streaming path's provider
+ * loader: heavy SDKs stay out of the CLI startup parse graph.
+ */
+import type { AssistantMessageEventStream, Context, Model, OptionsForApi } from "../types";
+import { AssistantMessageEventStream as EventStreamImpl } from "../utils/event-stream";
+import type { BedrockOptions } from "./amazon-bedrock";
+interface BedrockProviderModule {
+    streamBedrock: (model: Model<"bedrock-converse-stream">, context: Context, options: BedrockOptions) => AssistantMessageEventStream;
+}
+export declare function setBedrockProviderModule(module: BedrockProviderModule): void;
+export declare const streamAnthropic: (model: Model<"anthropic-messages">, context: Context, options: OptionsForApi<"anthropic-messages">) => EventStreamImpl;
+export declare const streamAzureOpenAIResponses: (model: Model<"azure-openai-responses">, context: Context, options: OptionsForApi<"azure-openai-responses">) => EventStreamImpl;
+export declare const streamGoogle: (model: Model<"google-generative-ai">, context: Context, options: OptionsForApi<"google-generative-ai">) => EventStreamImpl;
+export declare const streamGoogleGeminiCli: (model: Model<"google-gemini-cli">, context: Context, options: OptionsForApi<"google-gemini-cli">) => EventStreamImpl;
+export declare const streamGoogleVertex: (model: Model<"google-vertex">, context: Context, options: OptionsForApi<"google-vertex">) => EventStreamImpl;
+export declare const streamOpenAICodexResponses: (model: Model<"openai-codex-responses">, context: Context, options: OptionsForApi<"openai-codex-responses">) => EventStreamImpl;
+export declare const streamOpenAICompletions: (model: Model<"openai-completions">, context: Context, options: OptionsForApi<"openai-completions">) => EventStreamImpl;
+export declare const streamOpenAIResponses: (model: Model<"openai-responses">, context: Context, options: OptionsForApi<"openai-responses">) => EventStreamImpl;
+export declare const streamCursor: (model: Model<"cursor-agent">, context: Context, options: OptionsForApi<"cursor-agent">) => EventStreamImpl;
+export declare const streamOllama: (model: Model<"ollama-chat">, context: Context, options: OptionsForApi<"ollama-chat">) => EventStreamImpl;
+export declare const streamBedrock: (model: Model<"bedrock-converse-stream">, context: Context, options: OptionsForApi<"bedrock-converse-stream">) => EventStreamImpl;
+export {};

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

@@ -0,0 +1,26 @@
+/**
+ * Synthetic provider - wraps OpenAI or Anthropic API based on format setting.
+ *
+ * Synthetic offers both OpenAI-compatible and Anthropic-compatible APIs:
+ * - OpenAI: https://api.synthetic.new/openai/v1/chat/completions
+ * - Anthropic: https://api.synthetic.new/anthropic/v1/messages
+ *
+ * @see https://dev.synthetic.new/docs/api/overview
+ */
+import type { Api, Context, Model } from "../types";
+import type { AssistantMessageEventStream } from "../utils/event-stream";
+import { type OpenAIAnthropicApiFormat, type OpenAIAnthropicShimOptions } from "./openai-anthropic-shim";
+export type SyntheticApiFormat = OpenAIAnthropicApiFormat;
+export interface SyntheticOptions extends OpenAIAnthropicShimOptions {
+    /** API format: "openai" or "anthropic". Default: "openai" */
+    format?: SyntheticApiFormat;
+}
+/**
+ * Stream from Synthetic, routing to either OpenAI or Anthropic API based on format.
+ * Returns synchronously like other providers - async processing happens internally.
+ */
+export declare function streamSynthetic(model: Model<"openai-completions">, context: Context, options?: SyntheticOptions): AssistantMessageEventStream;
+/**
+ * Check if a model is a Synthetic model.
+ */
+export declare function isSyntheticModel(model: Model<Api>): boolean;

package/dist/types/providers/transform-messages.d.ts

@@ -0,0 +1,14 @@
+import type { Api, AssistantMessage, Message, Model } from "../types";
+/**
+ * Normalize tool call ID for cross-provider compatibility.
+ * OpenAI Responses API generates IDs that are 450+ chars with special characters like `|`.
+ * Anthropic APIs require IDs matching ^[a-zA-Z0-9_-]+$ (max 64 chars).
+ *
+ * For aborted/errored turns, this function:
+ * - Preserves tool call structure (unlike converting to text summaries)
+ * - Injects synthetic "aborted" tool results
+ * - Adds a <turn-aborted> guidance marker for the model
+ */
+export declare function transformMessages<TApi extends Api>(messages: Message[], model: Model<TApi>, normalizeToolCallId?: (id: string, model: Model<TApi>, source: AssistantMessage) => string, options?: {
+    repairLatestAssistantThinking?: boolean;
+}): Message[];

package/dist/types/providers/vision-guard.d.ts

@@ -0,0 +1,8 @@
+import type { ImageContent, TextContent } from "../types";
+export declare const NON_VISION_IMAGE_PLACEHOLDER = "[image omitted: model does not support vision]";
+export declare function partitionVisionContent(content: ReadonlyArray<TextContent | ImageContent>, supportsImages: boolean): {
+    textBlocks: TextContent[];
+    imageBlocks: ImageContent[];
+    omittedImages: boolean;
+};
+export declare function joinTextWithImagePlaceholder(text: string, omittedImages: boolean): string;

package/dist/types/rate-limit-utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Rate limit reason classification and backoff calculation utilities.
+ * Ported from opencode-antigravity-auth plugin for consistency.
+ */
+export type RateLimitReason = "QUOTA_EXHAUSTED" | "RATE_LIMIT_EXCEEDED" | "MODEL_CAPACITY_EXHAUSTED" | "SERVER_ERROR" | "UNKNOWN";
+/**
+ * Classify a rate-limit error message into a reason category.
+ * Priority order: MODEL_CAPACITY > RATE_LIMIT > QUOTA > SERVER_ERROR > UNKNOWN.
+ *
+ * "resource exhausted" maps to MODEL_CAPACITY (transient, short wait)
+ * "quota exceeded" maps to QUOTA_EXHAUSTED (long wait, switch account)
+ */
+export declare function parseRateLimitReason(errorMessage: string): RateLimitReason;
+/**
+ * Calculate backoff delay in ms for a given rate limit reason.
+ * MODEL_CAPACITY gets jitter to prevent thundering herd.
+ */
+export declare function calculateRateLimitBackoffMs(reason: RateLimitReason): number;
+export declare function isUsageLimitError(errorMessage: string): boolean;

package/dist/types/stream.d.ts

@@ -0,0 +1,43 @@
+import type { Effort } from "./model-thinking";
+import type { AnthropicOptions } from "./providers/anthropic";
+import type { Api, AssistantMessage, Context, Model, OptionsForApi, SimpleStreamOptions, ToolChoice } from "./types";
+import { AssistantMessageEventStream } from "./utils/event-stream";
+/**
+ * Get API key for provider from known environment variables, e.g. OPENAI_API_KEY.
+ *
+ * Provider authentication intentionally excludes cwd/.env values. Project dotenv files are
+ * loaded into $env for app/tool execution, but must not silently fund SKC model requests.
+ */
+export declare function getEnvApiKey(provider: string): string | undefined;
+/**
+ * Enumerate every provider that has an env-var fallback for `getEnvApiKey`.
+ * Used by `skc auth-broker migrate --include-env` to discover env-sourced keys
+ * that should be uploaded to the broker.
+ */
+export declare function listProvidersWithEnvKey(): string[];
+/**
+ * Provider-specific credential guidance appended to "no credential" errors.
+ *
+ * Headless SKC has no interactive `/login` TUI, so a bare "No API key" /
+ * "No credentials" error left users — OpenCode Go subscribers especially
+ * (#755) — unsure what signal SKC actually reads. OpenCode subscriptions are
+ * themselves API keys, so this names the env var SKC reads for the provider,
+ * warns that a project `.env` is intentionally ignored for provider
+ * credentials, and points OpenCode users at one-time interactive CLI credential capture.
+ *
+ * Returns an empty string when the provider has no env-var key and no special
+ * handling, so callers can append it unconditionally.
+ */
+export declare function formatProviderCredentialHint(provider: string): string;
+/**
+ * Build an actionable "missing API key" error for a provider, used by the
+ * low-level `stream`/`complete` entry points (#755).
+ */
+export declare function formatMissingApiKeyError(provider: string): string;
+export declare function stream<TApi extends Api>(model: Model<TApi>, context: Context, options?: OptionsForApi<TApi>): AssistantMessageEventStream;
+export declare function complete<TApi extends Api>(model: Model<TApi>, context: Context, options?: OptionsForApi<TApi>): Promise<AssistantMessage>;
+export declare function streamSimple<TApi extends Api>(model: Model<TApi>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream;
+export declare function completeSimple<TApi extends Api>(model: Model<TApi>, context: Context, options?: SimpleStreamOptions): Promise<AssistantMessage>;
+export declare const OUTPUT_FALLBACK_BUFFER = 4000;
+export declare const ANTHROPIC_THINKING: Record<Effort, number>;
+export declare function mapAnthropicToolChoice(choice?: ToolChoice): AnthropicOptions["toolChoice"];