@sdods/agents 0.2.0

package/dist/adapter/mcp-bridge.js

@@ -0,0 +1,122 @@
+/**
+ * What to keep from a browser server when the menu has to be short: look, go, act, read — in the
+ * order a person would use them.
+ */
+const BROWSER_ESSENTIALS = [
+    'browser_snapshot',
+    'browser_navigate',
+    'browser_click',
+    'browser_type',
+    'browser_fill_form',
+    'browser_find',
+    'browser_wait_for',
+    'browser_console_messages',
+];
+/** Ranks a server's tools so a cap keeps the useful ones rather than the alphabetical ones. */
+function prioritise(names, limit) {
+    const ranked = [...names].sort((a, b) => {
+        const ia = BROWSER_ESSENTIALS.indexOf(a);
+        const ib = BROWSER_ESSENTIALS.indexOf(b);
+        return (ia === -1 ? 99 : ia) - (ib === -1 ? 99 : ib);
+    });
+    return new Set(ranked.slice(0, limit));
+}
+/** Playwright's own MCP server, so a role that must look at the application can. */
+const PLAYWRIGHT_SERVER = {
+    transport: 'stdio',
+    command: 'npx',
+    args: ['playwright', 'mcp', '--headless'],
+};
+export async function bridgeMcpServers(opts) {
+    const configured = { ...(opts.servers ?? {}) };
+    if (opts.withPlaywright && !configured.playwright)
+        configured.playwright = PLAYWRIGHT_SERVER;
+    const entries = Object.entries(configured);
+    if (!entries.length)
+        return { tools: [], close: async () => undefined };
+    const { Client } = await import('@modelcontextprotocol/client');
+    const closers = [];
+    const tools = [];
+    for (const [name, cfg] of entries) {
+        try {
+            const client = new Client({ name: 'sdods-agent', version: '0.1.0' });
+            const transport = await transportFor(cfg, opts.cwd);
+            await client.connect(transport);
+            closers.push(() => client.close().catch(() => undefined));
+            const listed = await client.listTools();
+            const allowed = cfg.allowedTools?.length
+                ? new Set(cfg.allowedTools)
+                : opts.maxToolsPerServer && listed.tools.length > opts.maxToolsPerServer
+                    ? prioritise(listed.tools.map((t) => t.name), opts.maxToolsPerServer)
+                    : undefined;
+            for (const tool of listed.tools) {
+                if (allowed && !allowed.has(tool.name))
+                    continue;
+                tools.push({
+                    name: `mcp__${name}__${tool.name}`,
+                    description: tool.description ?? `${name} ${tool.name}`,
+                    // The server already speaks JSON Schema; converting it to zod and back would only lose
+                    // detail, so it is passed through and used verbatim.
+                    inputSchema: {},
+                    parametersJsonSchema: (tool.inputSchema ?? {
+                        type: 'object',
+                        properties: {},
+                    }),
+                    annotations: {
+                        readOnlyHint: tool.annotations?.readOnlyHint ?? false,
+                        destructiveHint: tool.annotations?.destructiveHint ?? false,
+                    },
+                    handler: async (args) => {
+                        const result = await client.callTool({ name: tool.name, arguments: args });
+                        const content = (result.content ?? []).map((c) => c.type === 'text'
+                            ? { type: 'text', text: c.text }
+                            : c.type === 'image'
+                                ? { type: 'image', data: c.data, mimeType: c.mimeType }
+                                : { type: 'text', text: `[${c.type}]` });
+                        return { content, isError: Boolean(result.isError) };
+                    },
+                });
+            }
+            const kept = allowed ? [...allowed].length : listed.tools.length;
+            opts.onEvent?.({
+                type: 'status',
+                message: `mcp: ${name} connected (${kept} of ${listed.tools.length} tool(s))`,
+            });
+        }
+        catch (err) {
+            // A server that will not start must not take the job with it: the model simply has fewer
+            // tools, and the reason is on the record.
+            opts.onEvent?.({
+                type: 'status',
+                message: `mcp: ${name} unavailable (${err.message})`,
+            });
+        }
+    }
+    return {
+        tools,
+        close: async () => {
+            await Promise.all(closers.map((c) => c()));
+        },
+    };
+}
+async function transportFor(cfg, cwd) {
+    if (cfg.transport === 'http' || (!cfg.command && cfg.url)) {
+        if (!cfg.url)
+            throw new Error('an http MCP server needs a url');
+        const { StreamableHTTPClientTransport } = await import('@modelcontextprotocol/client');
+        return new StreamableHTTPClientTransport(new URL(cfg.url), {
+            requestInit: cfg.headers ? { headers: cfg.headers } : undefined,
+        });
+    }
+    if (!cfg.command)
+        throw new Error('a stdio MCP server needs a command');
+    const { StdioClientTransport } = await import('@modelcontextprotocol/client/stdio');
+    return new StdioClientTransport({
+        command: cfg.command,
+        args: cfg.args ?? [],
+        env: { ...process.env, ...(cfg.env ?? {}) },
+        cwd,
+        stderr: 'ignore',
+    });
+}
+//# sourceMappingURL=mcp-bridge.js.map

package/dist/adapter/ollama.d.ts

@@ -0,0 +1,62 @@
+import { type CompleteRequest, type CompleteResult, type LlmAdapter, type RunAgentOptions, type RunAgentResult } from './types.js';
+export interface OllamaOptions {
+    baseUrl?: string;
+    model?: string;
+    /** Sets `options.num_ctx`, and the ceiling the prompt is measured against. */
+    contextTokens?: number;
+    temperature?: number;
+    timeoutMs?: number;
+    /** How long the server keeps the model in memory between turns. */
+    keepAlive?: string;
+    fetchImpl?: typeof fetch;
+}
+export interface OllamaModel {
+    name: string;
+    sizeBytes: number;
+    parameterSize?: string;
+    family?: string;
+    capabilities?: string[];
+    contextLength?: number;
+}
+export declare class OllamaAdapter implements LlmAdapter {
+    private readonly opts;
+    readonly provider: "ollama";
+    readonly defaultModel: string;
+    readonly baseUrl: string;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly temperature;
+    private readonly contextTokens?;
+    private readonly keepAlive;
+    constructor(opts?: OllamaOptions);
+    /** Installed models. Throws a readable error when nothing is listening. */
+    models(): Promise<OllamaModel[]>;
+    /** What a model can do, and the context its weights allow. */
+    show(model: string): Promise<{
+        capabilities: string[];
+        contextLength?: number;
+    }>;
+    /** The context a loaded model is actually running with — usually far below its maximum. */
+    loadedContext(model: string): Promise<number | undefined>;
+    version(): Promise<string>;
+    /** True when a server answers at all — used by detection and `doctor`, so it is quick. */
+    static reachable(baseUrl?: string, timeoutMs?: number): Promise<boolean>;
+    complete(req: CompleteRequest): Promise<CompleteResult>;
+    stream(req: CompleteRequest): AsyncIterable<string>;
+    runAgent(o: RunAgentOptions): Promise<RunAgentResult>;
+    /** Native shapes: tool calls carry no id and arguments arrive already parsed. */
+    private transport;
+    /**
+     * Refuses to start a job whose prompt cannot fit, instead of letting Ollama truncate it.
+     *
+     * This is the failure nobody reports, because the answer still looks plausible — so it is a
+     * hard error with the two commands that fix it, not a warning.
+     */
+    private assertFits;
+    private options;
+    private chat;
+    private get;
+    private post;
+    private request;
+}
+//# sourceMappingURL=ollama.d.ts.map

package/dist/adapter/ollama.js

@@ -0,0 +1,272 @@
+import { AgentsConfigError, DEFAULT_MODELS, } from './types.js';
+import { readToolArgs, runToolLoop, } from './tool-loop.js';
+import { toolParameters } from './json-schema.js';
+import { bridgeMcpServers } from './mcp-bridge.js';
+/**
+ * Models running on this machine, through Ollama's native API.
+ *
+ * Ollama also speaks the OpenAI protocol, and `openai-compatible` will talk to it — but that path
+ * cannot set `num_ctx`. Ollama loads a model at 4096 tokens by default even when the weights
+ * advertise 128k, and it truncates a longer prompt **silently**: the model answers confidently
+ * from half a question and nothing anywhere reports a problem. An agent prompt carrying tool
+ * schemas passes 4096 on the first turn, so the native endpoint is the only honest transport.
+ *
+ * The same endpoint buys two more things worth having: `format` accepts a JSON schema, which is
+ * what makes a 7B model reliable at structured output, and `/api/tags`, `/api/show` and `/api/ps`
+ * report what is installed, what it can do, and how much context it was actually loaded with.
+ */
+const DEFAULT_HOST = 'http://127.0.0.1:11434';
+/** Local generation is minutes, not seconds: a first load pulls weights into memory. */
+const DEFAULT_TIMEOUT_MS = 300_000;
+/** Rough characters-per-token for the budget guard; deliberately pessimistic. */
+const CHARS_PER_TOKEN = 3.5;
+export class OllamaAdapter {
+    opts;
+    provider = 'ollama';
+    defaultModel;
+    baseUrl;
+    fetchImpl;
+    timeoutMs;
+    temperature;
+    contextTokens;
+    keepAlive;
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.defaultModel = opts.model ?? process.env.OLLAMA_MODEL ?? DEFAULT_MODELS.ollama;
+        this.baseUrl = normalizeHost(opts.baseUrl ?? process.env.OLLAMA_HOST ?? DEFAULT_HOST);
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.temperature = opts.temperature ?? 0;
+        this.contextTokens = opts.contextTokens;
+        this.keepAlive = opts.keepAlive ?? '10m';
+    }
+    /* ── discovery ──────────────────────────────────────────────────────────── */
+    /** Installed models. Throws a readable error when nothing is listening. */
+    async models() {
+        const json = (await this.get('/api/tags'));
+        return (json.models ?? []).map((m) => ({
+            name: m.name,
+            sizeBytes: m.size,
+            family: m.details?.family,
+            parameterSize: m.details?.parameter_size,
+        }));
+    }
+    /** What a model can do, and the context its weights allow. */
+    async show(model) {
+        const json = (await this.post('/api/show', { model }));
+        const ctxKey = Object.keys(json.model_info ?? {}).find((k) => k.endsWith('.context_length'));
+        return {
+            capabilities: json.capabilities ?? [],
+            contextLength: ctxKey ? Number(json.model_info[ctxKey]) : undefined,
+        };
+    }
+    /** The context a loaded model is actually running with — usually far below its maximum. */
+    async loadedContext(model) {
+        const json = (await this.get('/api/ps'));
+        const hit = (json.models ?? []).find((m) => m.name === model || m.model === model);
+        return hit?.context_length;
+    }
+    async version() {
+        const json = (await this.get('/api/version'));
+        return json.version ?? 'unknown';
+    }
+    /** True when a server answers at all — used by detection and `doctor`, so it is quick. */
+    static async reachable(baseUrl, timeoutMs = 400) {
+        const url = `${normalizeHost(baseUrl ?? process.env.OLLAMA_HOST ?? DEFAULT_HOST)}/api/tags`;
+        try {
+            const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    /* ── generation ─────────────────────────────────────────────────────────── */
+    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 },
+            ],
+            ...(req.responseSchema ? { format: req.responseSchema } : {}),
+            options: this.options(req.maxTokens),
+        }, req.signal));
+        return {
+            text: json.message?.content ?? '',
+            usage: usageOf(json),
+            costUsd: 0,
+            model,
+        };
+    }
+    async *stream(req) {
+        yield (await this.complete(req)).text;
+    }
+    async runAgent(o) {
+        const model = o.model ?? this.defaultModel;
+        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] };
+            await this.assertFits(model, withMcp, o.onEvent);
+            return await runToolLoop(this.transport(model, withMcp), withMcp);
+        }
+        finally {
+            await bridged.close();
+        }
+    }
+    /** Native shapes: tool calls carry no id and arguments arrive already parsed. */
+    transport(model, o) {
+        return {
+            model,
+            start: (system, prompt) => [
+                { role: 'system', content: system },
+                { role: 'user', content: prompt },
+            ],
+            send: async (history, tools, signal, turnOpts) => {
+                // Ollama's native API has no tool_choice, so 'required' is said in words on the turn it
+                // applies to — which is enough to stop a small model narrating instead of calling.
+                const nudged = turnOpts?.toolChoice === 'required' && tools.length
+                    ? [
+                        ...history,
+                        {
+                            role: 'system',
+                            content: 'Reply with a tool call, not prose. Call exactly one tool.',
+                        },
+                    ]
+                    : history;
+                const json = (await this.chat({
+                    model,
+                    messages: nudged,
+                    tools: tools.length ? nativeTools(tools) : undefined,
+                    options: this.options(o.maxTokens),
+                }, signal));
+                const calls = (json.message?.tool_calls ?? []).map((call, i) => {
+                    const { args, error } = readToolArgs(call.function?.arguments);
+                    return { id: `call_${i}`, name: call.function?.name ?? '', args, error };
+                });
+                return {
+                    text: json.message?.content ?? '',
+                    calls,
+                    usage: usageOf(json),
+                    finishReason: json.done_reason ?? 'stop',
+                };
+            },
+            pushAssistant: (history, turn) => {
+                history.push({
+                    role: 'assistant',
+                    content: turn.text,
+                    tool_calls: turn.calls.length
+                        ? turn.calls.map((c) => ({ function: { name: c.name, arguments: c.args } }))
+                        : undefined,
+                });
+            },
+            pushToolResult: (history, call, output) => {
+                history.push({ role: 'tool', tool_name: call.name, content: output });
+            },
+            // Electricity is not billed per token: local runs are free, and budget gates never fire.
+            cost: () => 0,
+        };
+    }
+    /**
+     * Refuses to start a job whose prompt cannot fit, instead of letting Ollama truncate it.
+     *
+     * This is the failure nobody reports, because the answer still looks plausible — so it is a
+     * hard error with the two commands that fix it, not a warning.
+     */
+    async assertFits(model, o, onEvent) {
+        const chars = o.system.length + o.prompt.length + JSON.stringify(nativeTools(o.tools) ?? []).length;
+        const estimate = Math.ceil(chars / CHARS_PER_TOKEN);
+        const want = this.contextTokens;
+        if (want && estimate < want * 0.9)
+            return;
+        const loaded = await this.loadedContext(model).catch(() => undefined);
+        const ceiling = want ?? loaded;
+        if (!ceiling)
+            return;
+        if (estimate < ceiling * 0.9)
+            return;
+        const max = (await this.show(model).catch(() => undefined))?.contextLength;
+        const target = Math.min(max ?? 32_768, Math.max(8192, 2 ** Math.ceil(Math.log2(estimate * 2))));
+        throw new AgentsConfigError(`The prompt for this job is about ${estimate.toLocaleString()} tokens, but ${model} is running with a ${ceiling.toLocaleString()}-token context. Ollama would truncate it without saying so.`, `Set agents.contextTokens: ${target} in the project yaml, or start the server with OLLAMA_CONTEXT_LENGTH=${target}${max ? ` (this model supports up to ${max.toLocaleString()})` : ''}. A smaller tool set (agents.profile: small) also shortens the prompt.`);
+        onEvent?.({ type: 'status', message: 'context checked' });
+    }
+    options(maxTokens) {
+        return {
+            temperature: this.temperature,
+            // Changing num_ctx reloads the model, so it is fixed once per adapter, from configuration.
+            ...(this.contextTokens ? { num_ctx: this.contextTokens } : {}),
+            ...(maxTokens ? { num_predict: maxTokens } : {}),
+        };
+    }
+    /* ── transport ──────────────────────────────────────────────────────────── */
+    async chat(body, signal) {
+        // stream defaults to true, which would return NDJSON; keep_alive stops the model being
+        // unloaded and reloaded between turns; think spends the output budget on reasoning tokens
+        // that this loop has no use for.
+        return this.post('/api/chat', { stream: false, keep_alive: this.keepAlive, think: false, ...body }, signal);
+    }
+    async get(path, signal) {
+        return this.request(path, undefined, signal);
+    }
+    async post(path, body, signal) {
+        return this.request(path, body, signal);
+    }
+    async request(path, body, signal) {
+        const url = `${this.baseUrl}${path}`;
+        const deadline = AbortSignal.timeout(this.timeoutMs);
+        const composed = signal ? AbortSignal.any([signal, deadline]) : deadline;
+        let res;
+        try {
+            res = await this.fetchImpl(url, {
+                method: body ? 'POST' : 'GET',
+                headers: body ? { 'content-type': 'application/json' } : undefined,
+                body: body ? JSON.stringify(body) : undefined,
+                signal: composed,
+            });
+        }
+        catch (err) {
+            if (signal?.aborted)
+                throw err;
+            if (deadline.aborted)
+                throw new AgentsConfigError(`${url} did not answer within ${Math.round(this.timeoutMs / 1000)}s.`, 'Raise agents.requestTimeoutMs, or check that the model is not still loading (`ollama ps`).');
+            throw new AgentsConfigError(`Cannot reach Ollama at ${this.baseUrl} (${err.message}).`, 'Start it with `ollama serve`, or point agents.baseUrl / OLLAMA_HOST at the machine running it.');
+        }
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            if (res.status === 404 && /not found/i.test(text)) {
+                const model = String(body?.model ?? this.defaultModel);
+                throw new AgentsConfigError(`Ollama has no model named "${model}".`, `Pull it with \`ollama pull ${model}\`, or pick one of the installed models with --model.`);
+            }
+            throw new Error(`${url} → ${res.status} ${text}`);
+        }
+        return res.json();
+    }
+}
+function usageOf(json) {
+    return { inputTokens: json.prompt_eval_count ?? 0, outputTokens: json.eval_count ?? 0 };
+}
+function nativeTools(tools) {
+    if (!tools.length)
+        return undefined;
+    return tools.map((t) => ({
+        type: 'function',
+        function: {
+            name: t.name,
+            description: t.description,
+            parameters: toolParameters(t.inputSchema, t.parametersJsonSchema),
+        },
+    }));
+}
+/** Accepts `host:port`, a full URL, or one with the OpenAI `/v1` suffix already attached. */
+function normalizeHost(raw) {
+    const withScheme = /^https?:\/\//.test(raw) ? raw : `http://${raw}`;
+    return withScheme.replace(/\/+$/, '').replace(/\/v1$/, '');
+}
+//# sourceMappingURL=ollama.js.map

package/dist/adapter/openai-compat.d.ts

@@ -0,0 +1,44 @@
+import { type CompleteRequest, type CompleteResult, type LlmAdapter, type RunAgentOptions, type RunAgentResult } from './types.js';
+export interface OpenAiCompatOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    model?: string;
+    fetchImpl?: typeof fetch;
+    /** USD per 1M tokens, for cost estimates */
+    prices?: Record<string, {
+        input: number;
+        output: number;
+    }>;
+    /** Per-request ceiling. Local models are minutes, not seconds, so this is generous. */
+    timeoutMs?: number;
+    /** 0 by default: test generation should be reproducible, not creative. */
+    temperature?: number;
+}
+/** Chat-completions tool loop for OpenAI-compatible endpoints (OpenAI, Azure, Ollama, vLLM …). */
+export declare class OpenAiCompatibleAdapter implements LlmAdapter {
+    private readonly opts;
+    readonly provider: "openai-compatible";
+    readonly defaultModel: string;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly temperature;
+    constructor(opts?: OpenAiCompatOptions);
+    private key;
+    /**
+     * 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.
+     */
+    private chat;
+    complete(req: CompleteRequest): Promise<CompleteResult>;
+    stream(req: CompleteRequest): AsyncIterable<string>;
+    runAgent(o: RunAgentOptions): Promise<RunAgentResult>;
+    /** Chat-completions shapes: tool calls carry an id, results are `{role:'tool', tool_call_id}`. */
+    private transport;
+    private cost;
+}
+//# sourceMappingURL=openai-compat.d.ts.map