@linxiraos/pi-ai 1.0.0

package/dist/types/utils/thinking-loop.d.ts

@@ -0,0 +1,102 @@
+import type { Api, Model, StreamOptions } from "../types.js";
+import { AssistantMessageEventStream } from "./event-stream.js";
+/** Stable lead phrase of the guard's error message; exported for tests. The
+ *  message also carries "stream stall" so the session + transport retry
+ *  classifiers treat it as a transient (retryable) stop without bespoke rules. */
+export declare const THINKING_LOOP_ERROR_MARKER = "Thinking loop detected";
+/**
+ * True when `model` is a Gemini model whose native thinking stream surfaces the
+ * "thought summary" titles this module's header guard counts.
+ *
+ * OpenAI-compat transports can serve Gemini under an arbitrary provider/id, so they
+ * carry the explicit `compat.enableGeminiThinkingLoopGuard` flag; direct Gemini
+ * transports carry a clearly shaped id/provider, so a string match is sufficient.
+ */
+export declare function isGeminiThinkingModel(model: Model<Api>): boolean;
+/**
+ * True when `model` should be guarded for thinking/response loops (Gemini & DeepSeek).
+ *
+ * OpenAI-compat transports can serve Gemini or DeepSeek under an arbitrary provider/id.
+ * Direct Gemini/DeepSeek transports carry a clearly shaped id/provider, so a string match
+ * is sufficient.
+ */
+export declare function isLoopGuardedModel(model: Model<Api>, options?: StreamOptions): boolean;
+/** @deprecated Use isLoopGuardedModel instead. */
+export declare function isGeminiThinkingLoopModel(model: Model<Api>): boolean;
+/**
+ * Stateful detector fed the streamed thinking deltas. `push` returns a
+ * human-readable reason the first time a loop shape is recognized; the caller
+ * is responsible for stopping after the first hit.
+ */
+export declare class ThinkingLoopDetector {
+    #private;
+    push(delta: string): string | null;
+    /** Process the buffered trailing paragraph (one with no blank-line / heading
+     *  terminator). Called when the thinking block ends so the final segment —
+     *  which may be the one that completes a duplicate cluster — is not dropped. */
+    flush(): string | null;
+}
+/**
+ * Consecutive Gemini thought-summary headers in one uninterrupted reasoning
+ * stream that trips the tool-call reminder. Gemini occasionally narrates a long
+ * chain of titled summaries ("Examining Result Handling", "Refining Result
+ * Rendering", …) without ever calling a tool, burning the whole budget on
+ * planning. This is the over-planning shape {@link ThinkingLoopDetector} misses —
+ * those titles are stripped before its similarity analysis precisely because their
+ * wording keeps changing, so a genuinely-distinct planning runaway never trips it.
+ *
+ * Set well above legitimate hard-problem depth: a capable model can emit ~10
+ * distinct, progressing hypotheses in a single reasoning block before acting (and
+ * a false trip is costly — the interrupt discards the whole reasoning turn). A
+ * real narration runaway burns dozens-to-hundreds of titles, so this still trips
+ * fast on the actual pathology.
+ */
+export declare const GEMINI_HEADER_RUNAWAY_THRESHOLD = 24;
+/**
+ * True when a single trimmed line is a Gemini reasoning-summary title: a markdown
+ * ATX heading (`## …`) or a whole-line bold / bold-italic run (`**Title**`,
+ * `***Title***`). Inline emphasis inside prose never matches — the bold run must
+ * span the entire line. Mirrors the title shapes {@link ThinkingLoopDetector}
+ * strips before similarity analysis.
+ */
+export declare function isReasoningSummaryHeader(line: string): boolean;
+/**
+ * Counts consecutive Gemini reasoning-summary headers across a streamed thinking
+ * block. {@link push} returns true exactly once — when the running header count
+ * first reaches {@link GEMINI_HEADER_RUNAWAY_THRESHOLD} — and the caller then
+ * interrupts the stream and reminds the model to issue a tool call. Paragraph
+ * lines between titles do NOT reset the run (Gemini emits header + paragraph per
+ * thought, so the run IS the number of summaries); leaving the reasoning channel
+ * does, via {@link reset} on a new thinking block / prose / tool call.
+ */
+export declare class GeminiHeaderRunDetector {
+    #private;
+    /** Feed a thinking delta. Returns true the first time the run hits the threshold. */
+    push(delta: string): boolean;
+    /** Number of summary titles counted in the current run (for the reminder/log). */
+    get count(): number;
+    /** Re-arm for a fresh reasoning block: clears the buffer, count, and latch. */
+    reset(): void;
+}
+/**
+ * Wrap a provider stream with the loop guard. `controller` is the guard's own
+ * abort handle: aborting it (after wiring it into the provider's signal via
+ * {@link withGeminiThinkingLoopGuard}) tears down the upstream once a loop
+ * trips.
+ */
+export declare function guardThinkingLoopStream(inner: AssistantMessageEventStream, model: Model<Api>, controller: AbortController, options?: StreamOptions): AssistantMessageEventStream;
+/**
+ * Apply the loop guard around a provider dispatch. For non-guarded models
+ * (or when disabled) this is a transparent pass-through. For guarded models it injects a
+ * guard abort signal into the provider call so a detected loop tears down the
+ * upstream, then wraps the returned stream. The guard only raises the retryable
+ * stall; bounding the re-samples and the final cook pass lives in the
+ * result-awaiting caller.
+ */
+export declare function withGeminiThinkingLoopGuard<O extends {
+    signal?: AbortSignal;
+    loopGuard?: {
+        enabled?: boolean;
+        checkAssistantContent?: boolean;
+    };
+}>(model: Model<Api>, options: O | undefined, dispatch: (options: O | undefined) => AssistantMessageEventStream): AssistantMessageEventStream;

package/dist/types/utils/tool-call-loop-guard.d.ts

@@ -0,0 +1,26 @@
+import type { AssistantMessage, ToolResultMessage } from "../types.js";
+/** Runtime settings for cross-turn tool-call repetition detection. */
+export interface ToolCallLoopGuardOptions {
+    readonly threshold: number;
+    readonly exemptTools: readonly string[];
+}
+/** A completed assistant turn plus the tool results it produced. */
+export interface ToolCallLoopTurn {
+    readonly message: AssistantMessage;
+    readonly toolResults: readonly ToolResultMessage[];
+}
+/** Details needed to steer the model away from a repeated tool call. */
+export interface RepeatedToolCallDetection {
+    readonly kind: "repeated_tool_call";
+    readonly toolName: string;
+    readonly count: number;
+    readonly resultSummary: string;
+    readonly argumentsSummary: string;
+}
+/** Detects consecutive identical assistant tool calls across model turns. */
+export declare class ToolCallLoopGuard {
+    #private;
+    constructor(options: ToolCallLoopGuardOptions);
+    /** Records one completed turn and returns the threshold hit, if any. */
+    recordTurn(turn: ToolCallLoopTurn): RepeatedToolCallDetection | null;
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Utility functions for mapping unified ToolChoice to provider-specific formats.
+ */
+import type { ToolChoice } from "../types.js";
+/** 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;
+} | {
+    type: "computer";
+} | 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,28 @@
+/**
+ * Tool-call argument validation pipeline.
+ *
+ * Tools may declare ArkType schemas or plain JSON Schema. This module builds a
+ * cached validation context, normalizes common LLM quirks against the wire
+ * schema, validates, performs conservative schema-directed coercions, and
+ * returns parsed arguments while preserving unknown root fields.
+ *
+ * The goal is to be conservative: every coercion is a structural rewrite that
+ * keeps the schema in charge of acceptance — we never invent values, only
+ * massage shapes the LLM almost got right.
+ */
+import type { Tool, ToolCall } from "../types.js";
+/**
+ * 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 an ArkType or plain JSON Schema schema.
+ * Applies conservative LLM-quirk normalization 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,57 @@
+import type { ResponseInput } from "./providers/openai-responses-wire.js";
+import type { CacheRetention, OpenAIResponsesHistoryPayload, ProviderPayload } from "./types.js";
+export { isRecord } from "@linxiraos/pi-utils";
+export declare function normalizeSystemPrompts(systemPrompt: readonly string[] | string | undefined | null): string[];
+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;
+interface OpenAIResponsesReplaySanitizeOptions {
+    supportsImageDetailOriginal?: boolean;
+    supportsComputerUse?: boolean;
+}
+/**
+ * Removes response-only lifecycle status from item types that reject it when replayed as input.
+ *
+ * Returns the original array when no item needs sanitization.
+ */
+export declare function stripOpenAIResponsesOutputOnlyStatusesForReplay<TItem extends {
+    type?: unknown;
+    status?: unknown;
+}>(items: TItem[]): TItem[];
+export declare function sanitizeOpenAIResponsesHistoryItemsForReplay(items: Array<Record<string, unknown>>, options?: OpenAIResponsesReplaySanitizeOptions): ResponseInput;
+/** Strip reasoning IDs whose only linked native output is a computer call that will be demoted. */
+export declare function stripOpenAIResponsesComputerLinkedReasoningIdsForReplay(items: ResponseInput): ResponseInput;
+/**
+ * Finalize provisional native-computer reasoning IDs after the complete
+ * Responses input has been rebuilt, model-adapted, and orphan-repaired.
+ */
+export declare function stripUnpairedOpenAIResponsesComputerReasoningIdsForReplay(items: ResponseInput): ResponseInput;
+/**
+ * Sanitize assistant-native Responses history for replay.
+ *
+ * Returns `undefined` for hidden-empty turns that only contain reasoning and an
+ * empty assistant message, allowing callers to rebuild visible transcript
+ * history instead of replaying stale native state.
+ */
+export declare function sanitizeOpenAIResponsesAssistantHistoryItemsForReplay(items: Array<Record<string, unknown>>, options?: OpenAIResponsesReplaySanitizeOptions): ResponseInput | undefined;
+/**
+ * Drop hidden-only fallback assistant replay after a native Responses snapshot is rejected.
+ */
+export declare function sanitizeOpenAIResponsesAssistantFallbackItemsForReplay(items: ResponseInput): 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: explicit request option first, then the
+ * `PI_CACHE_RETENTION` env override (`long` | `short` | `none`), then the
+ * provider-supplied fallback.
+ */
+export declare function resolveCacheRetention(cacheRetention?: CacheRetention, fallback?: CacheRetention): CacheRetention;

package/package.json

@@ -0,0 +1,138 @@
+{
+	"type": "module",
+	"name": "@linxiraos/pi-ai",
+	"version": "1.0.0",
+	"description": "Unified LLM API with automatic model discovery and provider configuration",
+	"homepage": "https://linxira-os.github.io",
+	"author": "Can Boluk",
+	"contributors": [
+		"Mario Zechner"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Linxira-OS/linxira-zeta.git",
+		"directory": "packages/ai"
+	},
+	"bugs": {
+		"url": "https://github.com/can1357/oh-my-pi/issues"
+	},
+	"keywords": [
+		"ai",
+		"llm",
+		"openai",
+		"anthropic",
+		"gemini",
+		"unified",
+		"api"
+	],
+	"main": "./src/index.ts",
+	"types": "./dist/types/index.d.ts",
+	"scripts": {
+		"check": "biome check . && bun run check:types",
+		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"lint": "biome lint .",
+		"test": "bun test --parallel",
+		"fix": "biome check --write --unsafe .",
+		"fmt": "biome format --write ."
+	},
+	"dependencies": {
+		"@bufbuild/protobuf": "^2.12.1",
+		"@linxiraos/pi-omptype": "1.0.0",
+		"@linxiraos/pi-catalog": "1.0.0",
+		"@linxiraos/pi-utils": "1.0.0",
+		"@linxiraos/pi-wire": "1.0.0"
+	},
+	"devDependencies": {
+		"@bufbuild/protoc-gen-es": "^2.12.1",
+		"@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"
+		},
+		"./error": {
+			"types": "./dist/types/error/index.d.ts",
+			"import": "./src/error/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"
+		},
+		"./providers/*": {
+			"types": "./dist/types/providers/*.d.ts",
+			"import": "./src/providers/*.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/harmony-leak": {
+			"types": "./dist/types/utils/harmony-leak.d.ts",
+			"import": "./src/utils/harmony-leak.ts"
+		},
+		"./dialect": {
+			"types": "./dist/types/dialect/index.d.ts",
+			"import": "./src/dialect/index.ts"
+		},
+		"./utils/*": {
+			"types": "./dist/types/utils/*.d.ts",
+			"import": "./src/utils/*.ts"
+		},
+		"./oauth": {
+			"types": "./dist/types/registry/oauth/index.d.ts",
+			"import": "./src/registry/oauth/index.ts"
+		},
+		"./oauth/*": {
+			"types": "./dist/types/registry/oauth/*.d.ts",
+			"import": "./src/registry/oauth/*.ts"
+		},
+		"./registry": {
+			"types": "./dist/types/registry/index.d.ts",
+			"import": "./src/registry/index.ts"
+		},
+		"./registry/oauth": {
+			"types": "./dist/types/registry/oauth/index.d.ts",
+			"import": "./src/registry/oauth/index.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,109 @@
+/**
+ * Custom API provider registry.
+ *
+ * Allows extensions to register streaming functions for custom API types
+ * (e.g., "vertex-claude-api") that are not built into stream.ts.
+ */
+
+import * as AIError from "./error";
+import type {
+	Api,
+	AssistantMessageEventStream,
+	Context,
+	KnownApi,
+	Model,
+	SimpleStreamOptions,
+	StreamOptions,
+} from "./types";
+
+const BUILTIN_API_IDS = [
+	"openai-completions",
+	"openai-responses",
+	"openrouter",
+	"openai-codex-responses",
+	"azure-openai-responses",
+	"anthropic-messages",
+	"bedrock-converse-stream",
+	"google-generative-ai",
+	"google-gemini-cli",
+	"google-vertex",
+	"ollama-chat",
+	"cursor-agent",
+	"gitlab-duo-agent",
+	"devin-agent",
+] as const satisfies readonly KnownApi[];
+
+type _MissingBuiltinApis = Exclude<KnownApi, (typeof BUILTIN_API_IDS)[number]>;
+type _CheckBuiltinApis = _MissingBuiltinApis extends never
+	? true
+	: ["BUILTIN_APIS is missing KnownApi values", _MissingBuiltinApis];
+true satisfies _CheckBuiltinApis;
+
+const BUILTIN_APIS = new Set<KnownApi>(BUILTIN_API_IDS);
+
+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 AIError.ConfigurationError(`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();
+}