@harny/sdk 0.1.2 → 0.1.3

package/dist/cjs/agent/adapters.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Model adapters: three wire styles, configured entirely from a roster entry.
+ *
+ * The loop speaks one neutral shape (messages, tool specs, tool calls). An
+ * adapter translates it to one wire style and back:
+ *
+ * - `chat_completions`: the widely shared chat-completions request shape.
+ * - `messages`: the messages request shape with content blocks.
+ * - `generate_content`: the generate-content shape with function declarations.
+ *
+ * Which provider speaks which style, the base URL, the auth header, any fixed
+ * headers and any extra request-body fields (a pin to one host on a provider
+ * that routes to many) all come from the roster entry, so no provider or model
+ * name is written here and a new provider on an existing style is a roster edit.
+ *
+ * Within one run, the model's own assistant turns are replayed in the native
+ * form the provider returned (some providers require their reasoning or
+ * signature fields back on the next call), with one repair: a tool call whose
+ * arguments are not a JSON object is replayed with `{}` (the loop has already
+ * answered it as invalid), because some hosts refuse the whole request
+ * otherwise. Across runs the session store keeps plain text and action notes
+ * only, so a conversation survives a change of preset or provider.
+ *
+ * A model that thinks before it answers (`thinking_always_on` in its roster
+ * entry; the agent never switches thinking off) spends part of the answer
+ * limit thinking. Its adapter gives every call at least the entry's
+ * `answer_room_tokens`; only the tokens the model uses are billed, and the
+ * thinking itself is never capped. A turn the provider stopped at the limit,
+ * or before it finished for another documented reason, is marked `cutOff`.
+ */
+import type { ResolvedModel } from "./roster.js";
+export interface ToolSpec {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, unknown>;
+}
+export interface ToolCall {
+    readonly id: string;
+    readonly name: string;
+    /** `null` when the model's arguments were not a JSON object (see `parseError`). */
+    readonly arguments: Record<string, unknown> | null;
+    readonly parseError?: string | null;
+}
+export interface ToolResult {
+    readonly callId: string;
+    readonly name: string;
+    readonly content: string;
+    readonly isError?: boolean;
+}
+export declare class Usage {
+    inputTokens: number;
+    outputTokens: number;
+    constructor(inputTokens?: number, outputTokens?: number);
+    get totalTokens(): number;
+    add(other: Usage): void;
+}
+export type MessageRole = "user" | "assistant" | "tool_results";
+/**
+ * One neutral message. `native` holds a provider's own assistant turn.
+ *
+ * A `tool_results` message may carry `text`: the loop's own words to the model
+ * after the results (the closing turn at the step limit), sent in the same
+ * turn as the results so user and model turns keep alternating.
+ */
+export declare class Message {
+    readonly role: MessageRole;
+    readonly text: string;
+    readonly toolCalls: ToolCall[];
+    readonly results: ToolResult[];
+    readonly native: unknown;
+    readonly nativeStyle: string | null;
+    constructor(init: {
+        role: MessageRole;
+        text?: string;
+        toolCalls?: ToolCall[];
+        results?: ToolResult[];
+        native?: unknown;
+        nativeStyle?: string | null;
+    });
+}
+export declare class ModelTurn {
+    readonly text: string;
+    readonly toolCalls: ToolCall[];
+    readonly usage: Usage;
+    readonly stop: string;
+    readonly native: unknown;
+    constructor(text: string, toolCalls: ToolCall[], usage: Usage, stop: string, native?: unknown);
+    /** The provider stopped this turn before it finished: text and tool calls may be incomplete. */
+    get cutOff(): boolean;
+    /** Stopped at the answer limit (the common case of `cutOff`). */
+    get atAnswerLimit(): boolean;
+}
+/** The model provider refused or failed the call (after retries). */
+export declare class ModelProviderError extends Error {
+    readonly statusCode: number | null;
+    constructor(message: string, statusCode?: number | null);
+}
+export interface CompleteRequest {
+    system: string;
+    messages: Message[];
+    tools: ToolSpec[];
+    maxOutputTokens: number;
+    /** Aborts the call (the run's time ran out). */
+    signal?: AbortSignal | null;
+}
+export interface ModelAdapter {
+    readonly provider: string;
+    readonly model: string;
+    readonly style: string;
+    complete(request: CompleteRequest): Promise<ModelTurn>;
+}
+export interface AdapterOptions {
+    /** A `fetch` to use instead of the global one (tests, proxies). */
+    fetch?: typeof fetch;
+    /** Per-call timeout. Default 60 seconds. */
+    timeoutMs?: number;
+}
+declare abstract class HttpAdapter implements ModelAdapter {
+    abstract readonly style: string;
+    readonly provider: string;
+    readonly model: string;
+    /** The answer limit a model that always thinks gets at least (`null`: no floor). */
+    readonly answerRoomTokens: number | null;
+    protected readonly base: string;
+    private readonly auth;
+    private readonly fixedHeaders;
+    protected readonly maxTokensParam: string;
+    private readonly extraBody;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(resolved: ResolvedModel, options?: AdapterOptions);
+    /** The caller's limit, raised to the roster's answer room for a model that always thinks. */
+    protected answerLimit(requested: number): number;
+    /** The roster entry's extra fields, added where the adapter set nothing. */
+    protected withExtra(body: Record<string, unknown>): Record<string, unknown>;
+    private headers;
+    protected post(url: string, body: Record<string, unknown>, signal?: AbortSignal | null): Promise<Record<string, unknown>>;
+    abstract complete(request: CompleteRequest): Promise<ModelTurn>;
+}
+/** `[arguments, error]`: an object, or `null` with the reason it is not one. */
+export declare function parseArguments(raw: unknown): [Record<string, unknown> | null, string | null];
+/**
+ * The model's own turn, safe to send back: a tool call whose arguments are not
+ * a JSON object is replayed with `{}`. Valid arguments go back byte for byte;
+ * the stored turn is never changed.
+ */
+export declare function replayable(native: unknown): unknown;
+export declare class ChatCompletionsAdapter extends HttpAdapter {
+    readonly style = "chat_completions";
+    private wireMessages;
+    complete(request: CompleteRequest): Promise<ModelTurn>;
+}
+export declare class MessagesAdapter extends HttpAdapter {
+    readonly style = "messages";
+    private wireMessages;
+    complete(request: CompleteRequest): Promise<ModelTurn>;
+}
+/** Reduce a JSON schema to the subset function declarations accept. */
+export declare function declarationSchema(schema: unknown): unknown;
+export declare class GenerateContentAdapter extends HttpAdapter {
+    readonly style = "generate_content";
+    private wireContents;
+    complete(request: CompleteRequest): Promise<ModelTurn>;
+}
+/** The adapter for a resolved roster entry's wire style. */
+export declare function buildAdapter(resolved: ResolvedModel, options?: AdapterOptions): ModelAdapter;
+export {};