@sdods/agents 0.2.0

package/dist/adapter/openai-compat.js

@@ -0,0 +1,200 @@
+import { DEFAULT_MODELS, AgentsConfigError, } from './types.js';
+import { toolParameters } from './json-schema.js';
+import { bridgeMcpServers } from './mcp-bridge.js';
+import { readToolArgs, runToolLoop, } from './tool-loop.js';
+/** A hosted endpoint answers in seconds; a local one can take minutes on a first load. */
+const DEFAULT_TIMEOUT_MS = 300_000;
+/** Chat-completions tool loop for OpenAI-compatible endpoints (OpenAI, Azure, Ollama, vLLM …). */
+export class OpenAiCompatibleAdapter {
+    opts;
+    provider = 'openai-compatible';
+    defaultModel;
+    baseUrl;
+    fetchImpl;
+    timeoutMs;
+    temperature;
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.defaultModel =
+            opts.model ?? process.env.OPENAI_MODEL ?? DEFAULT_MODELS['openai-compatible'];
+        this.baseUrl = (opts.baseUrl ??
+            process.env.OPENAI_BASE_URL ??
+            'https://api.openai.com/v1').replace(/\/$/, '');
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.temperature = opts.temperature ?? 0;
+    }
+    key() {
+        const k = this.opts.apiKey ?? process.env.OPENAI_API_KEY;
+        if (!k && !/localhost|127\.0\.0\.1/.test(this.baseUrl))
+            throw new AgentsConfigError('OPENAI_API_KEY is not set.', 'Export OPENAI_API_KEY (and OPENAI_BASE_URL for compatible servers) or use --adapter fake.');
+        return k ?? 'local';
+    }
+    /**
+     * One chat-completions call, with a deadline and a single retry.
+     *
+     * The deadline matters most for local servers, which can sit silent for minutes while a model
+     * loads; without it a hung server hangs the job forever. The retry covers the transient half of
+     * the failures (connection reset, 429, 5xx) and nothing else — a 400 or a missing model is the
+     * caller's problem and is reported as such.
+     */
+    async chat(body, signal) {
+        const url = `${this.baseUrl}/chat/completions`;
+        const send = async () => {
+            const deadline = AbortSignal.timeout(this.timeoutMs);
+            const composed = signal ? AbortSignal.any([signal, deadline]) : deadline;
+            let res;
+            try {
+                res = await this.fetchImpl(url, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json', authorization: `Bearer ${this.key()}` },
+                    body: JSON.stringify({ temperature: this.temperature, ...body }),
+                    signal: composed,
+                });
+            }
+            catch (err) {
+                if (signal?.aborted)
+                    throw err;
+                if (deadline.aborted)
+                    throw new Error(`${url} did not answer within ${Math.round(this.timeoutMs / 1000)}s. Raise agents.requestTimeoutMs, or check that the server is running and the model is loaded.`);
+                throw err;
+            }
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                const error = new Error(`${url} → ${res.status} ${text}`);
+                error.status = res.status;
+                error.retryable = res.status === 429 || res.status >= 500;
+                throw error;
+            }
+            return res.json();
+        };
+        try {
+            return await send();
+        }
+        catch (err) {
+            const retryable = err.retryable ??
+                /ECONNRESET|ECONNREFUSED|EPIPE|fetch failed/i.test(String(err));
+            if (!retryable || signal?.aborted)
+                throw err;
+            await new Promise((r) => setTimeout(r, 1000));
+            return send();
+        }
+    }
+    async complete(req) {
+        const model = req.model ?? this.defaultModel;
+        const json = await this.chat({
+            model,
+            messages: [
+                ...(req.system ? [{ role: 'system', content: req.system }] : []),
+                { role: 'user', content: req.prompt },
+            ],
+            max_tokens: req.maxTokens,
+        }, req.signal);
+        const usage = usageOf(json.usage);
+        return {
+            text: json.choices?.[0]?.message?.content ?? '',
+            usage,
+            costUsd: this.cost(model, usage),
+            model,
+        };
+    }
+    async *stream(req) {
+        const r = await this.complete(req);
+        yield r.text;
+    }
+    async runAgent(o) {
+        const model = o.model ?? this.defaultModel;
+        // MCP servers become ordinary functions, so a role that needs a browser gets one here too.
+        const bridged = await bridgeMcpServers({
+            servers: o.mcpServers,
+            withPlaywright: o.needsBrowser,
+            maxToolsPerServer: o.maxBridgedTools,
+            cwd: o.cwd,
+            onEvent: o.onEvent,
+        });
+        try {
+            const withMcp = { ...o, tools: [...o.tools, ...bridged.tools] };
+            return await runToolLoop(this.transport(model, withMcp), withMcp);
+        }
+        finally {
+            await bridged.close();
+        }
+    }
+    /** Chat-completions shapes: tool calls carry an id, results are `{role:'tool', tool_call_id}`. */
+    transport(model, o) {
+        return {
+            model,
+            start: (system, prompt) => [
+                { role: 'system', content: system },
+                { role: 'user', content: prompt },
+            ],
+            send: async (history, tools, signal, turnOpts) => {
+                const json = await this.chat({
+                    model,
+                    messages: history,
+                    tools: tools.length ? toolFunctions(tools) : undefined,
+                    tool_choice: tools.length ? (turnOpts?.toolChoice ?? 'auto') : undefined,
+                    // One decision per turn is the small profile's rule; the flag says so directly here.
+                    parallel_tool_calls: o.maxToolCallsPerTurn === 1 ? false : undefined,
+                    max_tokens: o.maxTokens,
+                }, signal);
+                const choice = json.choices?.[0];
+                const msg = choice?.message ?? {};
+                const calls = (msg.tool_calls ?? []).map((call, i) => {
+                    const { args, error } = readToolArgs(call.function?.arguments);
+                    return { id: call.id ?? `call_${i}`, name: call.function?.name ?? '', args, error };
+                });
+                return {
+                    text: msg.content ?? '',
+                    calls,
+                    usage: usageOf(json.usage),
+                    finishReason: choice?.finish_reason ?? 'stop',
+                };
+            },
+            pushAssistant: (history, turn) => {
+                history.push({
+                    role: 'assistant',
+                    content: turn.text || null,
+                    tool_calls: turn.calls.length
+                        ? turn.calls.map((c) => ({
+                            id: c.id,
+                            type: 'function',
+                            function: { name: c.name, arguments: JSON.stringify(c.args) },
+                        }))
+                        : undefined,
+                });
+            },
+            pushToolResult: (history, call, output) => {
+                history.push({ role: 'tool', tool_call_id: call.id, content: output });
+            },
+            cost: (usage) => this.cost(model, usage),
+        };
+    }
+    cost(model, usage) {
+        const price = this.opts.prices?.[model];
+        if (!price || !usage)
+            return undefined;
+        return (((usage.inputTokens ?? 0) * price.input + (usage.outputTokens ?? 0) * price.output) /
+            1_000_000);
+    }
+}
+/** Function definitions for the `tools` field of a chat-completions request. */
+function toolFunctions(tools) {
+    return tools.map((t) => ({
+        type: 'function',
+        function: {
+            name: t.name,
+            description: t.description,
+            parameters: toolParameters(t.inputSchema, t.parametersJsonSchema),
+        },
+    }));
+}
+function usageOf(u) {
+    if (!u)
+        return undefined;
+    return {
+        inputTokens: Number(u.prompt_tokens ?? 0),
+        outputTokens: Number(u.completion_tokens ?? 0),
+    };
+}
+//# sourceMappingURL=openai-compat.js.map

package/dist/adapter/profile.d.ts

@@ -0,0 +1,54 @@
+import type { Provider } from './types.js';
+/**
+ * How much of the platform to put in front of a model.
+ *
+ * A role exposes 33–35 tools, and a browser role adds Playwright's 24 on top. A frontier model
+ * copes with that; a 7–8B model does not — past roughly twenty functions it stops choosing one and
+ * starts *describing* the call it would make, in prose, forever. That is not a prompt problem, it
+ * is a menu problem.
+ *
+ * The small profile shrinks the menu: a handful of tools chosen for the role, one call per turn, a
+ * short turn budget, and the project's real step vocabulary in the system prompt so the model
+ * picks phrasing instead of inventing it. It is selected automatically for local models and can
+ * always be forced either way.
+ */
+export type ProfileName = 'full' | 'small';
+export type ProfileSetting = 'auto' | ProfileName;
+export interface ProfileSettings {
+    profile: ProfileName;
+    /** Why this profile was chosen, for the status line and `--dry-run`. */
+    reason: string;
+    /** Cap on turns; the role's own default wins when it is lower. */
+    maxTurns?: number;
+    /** Small models handle one decision at a time. */
+    maxToolCallsPerTurn?: number;
+    /** Make the first turn act instead of narrate. */
+    firstTurnToolChoice?: 'auto' | 'required';
+    /** Cap on one assistant turn, so a rambling model does not eat the context. */
+    maxTokens?: number;
+    /** How many step patterns to inline in the system prompt. */
+    stepVocabularyLimit: number;
+    /** Ceiling on tools bridged from MCP servers (the browser server alone offers 24). */
+    maxBridgedTools?: number;
+    /**
+     * Whether a browser role gets the browser server attached.
+     *
+     * Measured on llama3.1:8b: with the five generator tools it calls `feature_write`; add a single
+     * `browser_*` tool and it stops calling anything and describes a plan instead. The browser is a
+     * different *kind* of work — explore, then decide — and a small model cannot hold both. So the
+     * small profile writes from the project's step vocabulary, and the browser is opt-in.
+     */
+    attachBrowser: boolean;
+    /** Read a tool call out of the prose when the model wrote one instead of making it. */
+    recoverTextToolCalls: boolean;
+}
+export declare function resolveProfile(o: {
+    configured?: ProfileSetting;
+    provider: Provider;
+    model: string;
+    baseUrl?: string;
+    contextTokens?: number;
+    /** From the server, when it reports them: a model without `tools` cannot drive the loop. */
+    capabilities?: string[];
+}): ProfileSettings;
+//# sourceMappingURL=profile.d.ts.map

package/dist/adapter/profile.js

@@ -0,0 +1,42 @@
+const FULL = {
+    profile: 'full',
+    stepVocabularyLimit: 0,
+    attachBrowser: true,
+    recoverTextToolCalls: false,
+};
+const SMALL = {
+    profile: 'small',
+    maxTurns: 10,
+    maxToolCallsPerTurn: 1,
+    firstTurnToolChoice: 'required',
+    // A tool call is a hundred tokens; the cap exists to stop a model that has started rambling,
+    // and on a laptop at a few tokens a second a generous cap is a timeout waiting to happen.
+    maxTokens: 1024,
+    stepVocabularyLimit: 60,
+    maxBridgedTools: 6,
+    attachBrowser: false,
+    recoverTextToolCalls: true,
+};
+/** Model ids that name their own size: qwen2.5-coder:7b, llama3.1:8b, gemma:2b, phi3:3.8b … */
+const SMALL_MODEL = /(^|[-:_.])(0\.5|1|1\.5|2|3|3\.8|4|6|7|8|9|12|13|14)\s*b\b/i;
+/** A loopback or private address means someone is running the model themselves. */
+const PRIVATE_HOST = /^(https?:\/\/)?(localhost|127\.|0\.0\.0\.0|\[?::1\]?|10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|host\.docker\.internal|[^/]*\.local(:|\/|$))/i;
+export function resolveProfile(o) {
+    const configured = o.configured ?? 'auto';
+    if (configured === 'full')
+        return { ...FULL, reason: 'configured' };
+    if (configured === 'small')
+        return { ...SMALL, reason: 'configured' };
+    if (o.capabilities?.length && !o.capabilities.includes('tools'))
+        return { ...SMALL, reason: `${o.model} does not advertise tool calling` };
+    if (o.provider === 'ollama')
+        return { ...SMALL, reason: 'a local model' };
+    if (o.provider === 'openai-compatible' && o.baseUrl && PRIVATE_HOST.test(o.baseUrl))
+        return { ...SMALL, reason: `a model served from ${o.baseUrl}` };
+    if (SMALL_MODEL.test(o.model))
+        return { ...SMALL, reason: `${o.model} is a small model` };
+    if (o.contextTokens && o.contextTokens < 16_384)
+        return { ...SMALL, reason: `a ${o.contextTokens}-token context` };
+    return { ...FULL, reason: 'a hosted model' };
+}
+//# sourceMappingURL=profile.js.map

package/dist/adapter/tool-loop.d.ts

@@ -0,0 +1,64 @@
+import type { AgentSdkToolDef } from '@sdods/mcp';
+import type { RunAgentOptions, RunAgentResult, TokenUsage } from './types.js';
+/**
+ * The agent turn loop, shared by every adapter that drives a chat endpoint itself.
+ *
+ * Claude and the CLI adapters bring their own loop (the SDK or the CLI owns it). The
+ * chat-completions adapters do not, and they used to each own a copy — which is how the two
+ * drifted on argument validation and budget accounting. The loop lives here now; a transport
+ * supplies only the three things that genuinely differ between providers: how a request is sent,
+ * and how an assistant turn and a tool result are written back into the history.
+ */
+/** One tool call, after the provider's own encoding has been normalised away. */
+export interface NormalizedCall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+    /** Set when the model's arguments could not be read; the call must not be executed. */
+    error?: string;
+}
+export interface NormalizedTurn {
+    text: string;
+    calls: NormalizedCall[];
+    usage?: TokenUsage;
+    finishReason: string;
+}
+export interface TurnOptions {
+    /** 'required' makes a model act on the first turn instead of narrating what it would do. */
+    toolChoice?: 'auto' | 'required';
+}
+export interface ToolLoopTransport<Message> {
+    readonly model: string;
+    /** The opening history: whatever this provider expects for a system + user turn. */
+    start(system: string, prompt: string): Message[];
+    send(history: Message[], tools: AgentSdkToolDef[], signal?: AbortSignal, turnOpts?: TurnOptions): Promise<NormalizedTurn>;
+    pushAssistant(history: Message[], turn: NormalizedTurn): void;
+    pushToolResult(history: Message[], call: NormalizedCall, output: string, isError: boolean): void;
+    /** USD for one turn, or undefined when the provider does not price (local models: 0). */
+    cost(usage: TokenUsage | undefined): number | undefined;
+}
+export declare function runToolLoop<Message>(transport: ToolLoopTransport<Message>, o: RunAgentOptions): Promise<RunAgentResult>;
+/**
+ * Recovers a tool call a model wrote out instead of making.
+ *
+ * Small models often produce exactly the right call in exactly the right shape — as prose:
+ * `step_find({"project":"shop"})`, or a fenced JSON object with `name` and `arguments`. The
+ * structured field stays empty and the job ends having done nothing. Since the arguments are
+ * validated against the tool's schema either way, reading the call out of the text costs nothing
+ * and turns a wasted run into a working one. It only ever runs when the turn made no real call.
+ */
+export declare function recoverTextToolCall(text: string, known: Set<string>): {
+    name: string;
+    args: Record<string, unknown>;
+} | undefined;
+/**
+ * Reads the `arguments` a model sent for a tool call. OpenAI encodes them as a JSON string; some
+ * local servers send an object. Anything else is reported rather than silently turned into `{}` —
+ * calling a write tool with no arguments is how an empty feature file gets written and nobody
+ * finds out why.
+ */
+export declare function readToolArgs(raw: unknown): {
+    args: Record<string, unknown>;
+    error?: string;
+};
+//# sourceMappingURL=tool-loop.d.ts.map

package/dist/adapter/tool-loop.js

@@ -0,0 +1,192 @@
+/**
+ * How many malformed tool calls to answer with a correction before giving up. One repair turn is
+ * enough for a model that can recover; a model that cannot will not on the tenth either.
+ */
+const MAX_BAD_TOOL_CALLS = 2;
+export async function runToolLoop(transport, o) {
+    const byName = new Map(o.tools.map((t) => [t.name, t]));
+    const history = transport.start(o.system, o.prompt);
+    const usageTotal = { inputTokens: 0, outputTokens: 0 };
+    const maxTurns = o.maxTurns ?? 30;
+    let turns = 0;
+    let toolCalls = 0;
+    let badToolCalls = 0;
+    /** Recovered calls are deduplicated: a model describing what it already did must not repeat it. */
+    const executed = new Set();
+    let text = '';
+    let cost = 0;
+    const finish = (stopReason, isError) => {
+        o.onEvent?.({ type: 'result', costUsd: cost, usage: usageTotal, turns, stopReason, isError });
+        return { text, costUsd: cost, usage: usageTotal, turns, stopReason, isError, toolCalls };
+    };
+    while (turns < maxTurns) {
+        if (o.signal?.aborted)
+            return { text, turns, stopReason: 'aborted', toolCalls, costUsd: cost, usage: usageTotal };
+        turns++;
+        const turn = await transport.send(history, o.tools, o.signal, {
+            toolChoice: turns === 1 ? (o.firstTurnToolChoice ?? 'auto') : 'auto',
+        });
+        // One decision per turn: a small model given two calls at once usually gets the second wrong,
+        // and the dropped call is cheaper to explain than to undo.
+        if (o.maxToolCallsPerTurn && turn.calls.length > o.maxToolCallsPerTurn) {
+            const dropped = turn.calls.slice(o.maxToolCallsPerTurn);
+            turn.calls = turn.calls.slice(0, o.maxToolCallsPerTurn);
+            o.onEvent?.({
+                type: 'status',
+                message: `dropped ${dropped.length} extra tool call(s) this turn: ${dropped.map((c) => c.name).join(', ')}`,
+            });
+        }
+        usageTotal.inputTokens += turn.usage?.inputTokens ?? 0;
+        usageTotal.outputTokens += turn.usage?.outputTokens ?? 0;
+        cost += transport.cost(turn.usage) ?? 0;
+        if (o.maxBudgetUsd && cost > o.maxBudgetUsd)
+            return finish('error_max_budget_usd', true);
+        if (turn.text) {
+            text += turn.text;
+            o.onEvent?.({ type: 'text', text: turn.text });
+        }
+        if (!turn.calls.length && o.recoverTextToolCalls && turn.text) {
+            const recovered = recoverTextToolCall(turn.text, new Set(byName.keys()));
+            const signature = recovered && `${recovered.name}:${JSON.stringify(recovered.args)}`;
+            if (recovered && signature && !executed.has(signature)) {
+                turn.calls = [{ id: `text_${turns}`, name: recovered.name, args: recovered.args }];
+                o.onEvent?.({
+                    type: 'status',
+                    message: `recovered a ${recovered.name} call the model wrote as text`,
+                });
+            }
+        }
+        transport.pushAssistant(history, turn);
+        if (!turn.calls.length)
+            return finish(turn.finishReason, false);
+        for (const call of turn.calls) {
+            toolCalls++;
+            executed.add(`${call.name}:${JSON.stringify(call.args)}`);
+            o.onEvent?.({ type: 'tool_call', id: call.id, name: call.name, input: call.args });
+            const tool = byName.get(call.name);
+            const result = call.error
+                ? {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `${call.error}. Call ${call.name} again with a single JSON object matching its parameters.`,
+                        },
+                    ],
+                    isError: true,
+                }
+                : tool
+                    ? await tool.handler(call.args)
+                    : {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Unknown tool ${call.name}. Available: ${[...byName.keys()].join(', ')}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+            const output = result.content
+                .map((c) => (c.type === 'text' ? c.text : `[image ${c.mimeType}]`))
+                .join('\n');
+            o.onEvent?.({ type: 'tool_result', id: call.id, output, isError: result.isError });
+            transport.pushToolResult(history, call, output, Boolean(result.isError));
+            if (call.error) {
+                badToolCalls++;
+                if (badToolCalls > MAX_BAD_TOOL_CALLS)
+                    return finish('error_tool_arguments', true);
+            }
+        }
+    }
+    return finish('error_max_turns', true);
+}
+/**
+ * Recovers a tool call a model wrote out instead of making.
+ *
+ * Small models often produce exactly the right call in exactly the right shape — as prose:
+ * `step_find({"project":"shop"})`, or a fenced JSON object with `name` and `arguments`. The
+ * structured field stays empty and the job ends having done nothing. Since the arguments are
+ * validated against the tool's schema either way, reading the call out of the text costs nothing
+ * and turns a wasted run into a working one. It only ever runs when the turn made no real call.
+ */
+export function recoverTextToolCall(text, known) {
+    if (!text)
+        return undefined;
+    // `tool_name({ ... })`
+    const callSyntax = /\b([a-z][a-z0-9_]{2,})\s*\(\s*(\{[\s\S]*?\})\s*\)/gi;
+    for (const m of text.matchAll(callSyntax)) {
+        const name = m[1];
+        if (!known.has(name))
+            continue;
+        const args = parseObject(m[2]);
+        if (args)
+            return { name, args };
+    }
+    // `{"name": "tool_name", "arguments"|"parameters": { ... }}`, fenced or not. The object is
+    // found by matching braces rather than by regex: the payload contains nested objects, and a
+    // non-greedy pattern stops at the first inner brace.
+    for (const candidate of balancedObjects(text)) {
+        const obj = parseObject(candidate);
+        if (!obj)
+            continue;
+        const name = typeof obj.name === 'string' ? obj.name : undefined;
+        if (!name || !known.has(name))
+            continue;
+        const args = obj.arguments ?? obj.parameters ?? obj.input;
+        if (args && typeof args === 'object')
+            return { name, args: args };
+    }
+    return undefined;
+}
+/** Every balanced `{...}` substring, outermost first, so nested payloads survive. */
+function balancedObjects(text) {
+    const found = [];
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] !== '{')
+            continue;
+        let depth = 0;
+        for (let j = i; j < text.length; j++) {
+            if (text[j] === '{')
+                depth++;
+            else if (text[j] === '}') {
+                depth--;
+                if (depth === 0) {
+                    found.push(text.slice(i, j + 1));
+                    i = j;
+                    break;
+                }
+            }
+        }
+    }
+    return found;
+}
+function parseObject(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Reads the `arguments` a model sent for a tool call. OpenAI encodes them as a JSON string; some
+ * local servers send an object. Anything else is reported rather than silently turned into `{}` —
+ * calling a write tool with no arguments is how an empty feature file gets written and nobody
+ * finds out why.
+ */
+export function readToolArgs(raw) {
+    if (raw && typeof raw === 'object')
+        return { args: raw };
+    if (typeof raw !== 'string' || !raw.trim())
+        return { args: {} };
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object')
+            return { args: parsed };
+        return { args: {}, error: `arguments must be a JSON object, got ${typeof parsed}` };
+    }
+    catch (err) {
+        return { args: {}, error: `arguments were not valid JSON (${err.message})` };
+    }
+}
+//# sourceMappingURL=tool-loop.js.map

package/dist/adapter/types.d.ts

@@ -0,0 +1,109 @@
+import type { AgentSdkToolDef } from '@sdods/mcp';
+/**
+ * claude / openai-compatible: API keys. claude-code / codex: shell out to the user's logged-in
+ * CLI (no key needed). ollama: a model running on this machine, no key and no cost.
+ * fake: scripted, for tests and --dry-run.
+ */
+export type Provider = 'claude' | 'claude-code' | 'codex' | 'openai-compatible' | 'ollama' | 'fake';
+export interface TokenUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+}
+export type AgentEvent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_call';
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: 'tool_result';
+    id: string;
+    output: unknown;
+    isError?: boolean;
+} | {
+    type: 'status';
+    message: string;
+} | {
+    type: 'result';
+    costUsd?: number;
+    usage?: TokenUsage;
+    turns: number;
+    stopReason: string;
+    isError?: boolean;
+};
+export interface ExternalMcpServerConfig {
+    transport?: 'stdio' | 'http';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+    allowedTools?: string[];
+}
+export interface CompleteRequest {
+    system?: string;
+    prompt: string;
+    model?: string;
+    maxTokens?: number;
+    effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    /** JSON schema the answer must satisfy, where the provider can enforce one. */
+    responseSchema?: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+export interface CompleteResult {
+    text: string;
+    usage?: TokenUsage;
+    costUsd?: number;
+    model?: string;
+}
+export interface RunAgentOptions {
+    system: string;
+    prompt: string;
+    tools: AgentSdkToolDef[];
+    mcpServers?: Record<string, ExternalMcpServerConfig>;
+    /** The role wants to look at the application, so a browser server should be attached. */
+    needsBrowser?: boolean;
+    /** Small-model profile: one tool call per turn, and a first turn that must act. */
+    maxToolCallsPerTurn?: number;
+    firstTurnToolChoice?: 'auto' | 'required';
+    /** Ceiling on tools taken from each bridged MCP server. */
+    maxBridgedTools?: number;
+    /** Read a tool call out of the answer when the model wrote one instead of making it. */
+    recoverTextToolCalls?: boolean;
+    model?: string;
+    maxTurns?: number;
+    /** Cap on one assistant turn; local models otherwise ramble until the context ends. */
+    maxTokens?: number;
+    maxBudgetUsd?: number;
+    cwd?: string;
+    signal?: AbortSignal;
+    onEvent?: (e: AgentEvent) => void;
+}
+export interface RunAgentResult {
+    text: string;
+    costUsd?: number;
+    usage?: TokenUsage;
+    turns: number;
+    stopReason: string;
+    isError?: boolean;
+    toolCalls: number;
+}
+export interface LlmAdapter {
+    readonly provider: Provider;
+    readonly defaultModel: string;
+    complete(req: CompleteRequest): Promise<CompleteResult>;
+    stream(req: CompleteRequest): AsyncIterable<string>;
+    runAgent(opts: RunAgentOptions): Promise<RunAgentResult>;
+}
+export declare class AgentsConfigError extends Error {
+    readonly hint?: string | undefined;
+    readonly code = "AGENTS_CONFIG";
+    constructor(message: string, hint?: string | undefined);
+}
+/** `default` means "let the CLI pick its configured model" (claude-code, codex). */
+export declare const DEFAULT_MODELS: Record<Provider, string>;
+//# sourceMappingURL=types.d.ts.map

package/dist/adapter/types.js

@@ -0,0 +1,20 @@
+export class AgentsConfigError extends Error {
+    hint;
+    code = 'AGENTS_CONFIG';
+    constructor(message, hint) {
+        super(message);
+        this.hint = hint;
+        this.name = 'AgentsConfigError';
+    }
+}
+/** `default` means "let the CLI pick its configured model" (claude-code, codex). */
+export const DEFAULT_MODELS = {
+    claude: 'claude-opus-5',
+    'claude-code': 'default',
+    codex: 'default',
+    'openai-compatible': 'gpt-4.1',
+    // Small enough to run on a laptop, and the best of that size at tool calls and structured output.
+    ollama: 'qwen2.5-coder:7b',
+    fake: 'fake-model',
+};
+//# sourceMappingURL=types.js.map