Repository Public
1/**2 * Public contract of `@aos/providers` (CONTRACT §3).3 *4 * The engine only reads the normalised view (`blocks`, `stop`, `usage`, `model`). The transcript is an5 * opaque, append-only array of provider-native entries owned by the adapter; it is never converted from6 * one provider to the other.7 */8import type { Effort, ModelInfo, ModelResponse, Provider, ToolResult, Usage } from '@aos/shared';910/** JSON Schema tool definition. The adapters normalise `inputSchema` with `toStrictSchema()` before sending. */11export interface ToolDef {12 name: string;13 description: string;14 inputSchema: Record<string, unknown>;15}1617export interface ModelDelta {18 type: 'text' | 'reasoning';19 text: string;20}2122export interface ModelRequest {23 model: string;24 effort?: Effort;25 system: string;26 tools: ToolDef[];27 /** Provider-native transcript so far: opaque array owned by the provider adapter. Append-only. */28 transcript: unknown[];29 maxOutputTokens?: number;30 signal?: AbortSignal;31 onDelta?: (d: ModelDelta) => void;32}3334/**35 * What `call()` returns: a `ModelResponse` plus additive, JSON-serialisable details.36 *37 * `native` is ALWAYS an array of native entries. Append it with `adapter.appendAssistant(transcript, native)`,38 * `[...transcript, ...native]` or `[...transcript, native]` — the adapters flatten one level, so all three39 * produce the same request.40 */41export interface ProviderResponse extends ModelResponse {42 native: unknown[];43 /** Present when `stop === 'refusal'`. `category` is informational and may be null. */44 refusal?: { category: string | null; explanation: string | null };45 /** Raw provider stop signal (`stop_reason`, or `status[:incomplete reason]` for OpenAI). */46 nativeStop: string | null;47 /** Number of HTTP attempts made for this call (retries and continuations included). */48 attempts: number;49}5051export interface ProviderAdapter {52 readonly id: Provider;53 /** Start a native transcript from the first user message. */54 initTranscript(userText: string): unknown[];55 /** Append `ModelResponse.native` (additive helper, equivalent to spreading it). Returns a new array. */56 appendAssistant(transcript: unknown[], native: unknown): unknown[];57 /** All tool results of one turn in ONE batch; `ok:false` results are flagged as errors. Returns a new array. */58 appendToolResults(transcript: unknown[], results: ToolResult[]): unknown[];59 appendUser(transcript: unknown[], text: string): unknown[];60 /** Operator-authority note: mid-conversation system/developer message where supported, else a delimited user-turn note. */61 appendOperatorNote(transcript: unknown[], text: string): unknown[];62 /** Streaming under the hood; retries 429/5xx/overloaded/connection errors; throws `ProviderError`. */63 call(req: ModelRequest): Promise<ProviderResponse>;64 /** Catalogue entries of this provider merged with the live Models API. Never throws. */65 listModels(): Promise<ModelInfo[]>;66 /** Raw model IDs returned by the live Models API (additive; throws `ProviderError`). */67 listLiveModelIds(): Promise<string[]>;68 /** USD for ONE call's usage, from the versioned price table. */69 price(model: string, usage: Pick<Usage, 'inputTokens' | 'outputTokens' | 'cacheReadTokens' | 'cacheWriteTokens'>): number;70}7172/** Construction options; everything defaults to production behaviour. Tests inject `fetch`/`sleep`/`random`. */73export interface AdapterOptions {74 /** Defaults to the provider's env variable (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`). Never logged. */75 apiKey?: string;76 baseURL?: string;77 fetch?: typeof globalThis.fetch;78 /** Total attempts per request, first try included. Default 6. */79 maxAttempts?: number;80 sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;81 random?: () => number;82 /** Per-request timeout handed to the SDK (ms). Default 10 minutes. */83 timeoutMs?: number;84}8586/** Minimal database handle so this package does not depend on the kernel (`pg.Pool` and `pg.Client` satisfy it). */87export interface PriceDb {88 query(sql: string, params?: unknown[]): Promise<unknown>;89}90