@ziggs-ai/agent-sdk 0.1.12 → 0.2.0

package/dist/adapters/McpAdapter.js

@@ -0,0 +1,468 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { AgentHost } from '../AgentHost.js';
+import { thinkingDefaults } from '../runtime/defaults.js';
+/**
+ * Typed failure from the Ziggs MCP gateway (ZIG-702). `code` is the stable
+ * machine-readable reason — e.g. `GRANT_REVOKED`, `GRANT_EXPIRED`,
+ * `GRANT_HOLDER_MISMATCH`, `GRANT_CONNECTION_MISMATCH` — so agent code can
+ * branch ("revoked → tell the user and stop retrying" vs "network blip →
+ * retry") instead of parsing transport-error prose.
+ */
+export class ZiggsGatewayError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.name = 'ZiggsGatewayError';
+        this.code = code;
+        this.status = status;
+    }
+}
+/**
+ * Wrap fetch so structured gateway denials (401/403 with a `code` body)
+ * surface as ZiggsGatewayError instead of a generic transport failure.
+ */
+export function wrapGatewayFetch(baseFetch = fetch) {
+    return (async (input, init) => {
+        const response = await baseFetch(input, init);
+        if (response.status === 401 || response.status === 403) {
+            const body = (await response
+                .clone()
+                .json()
+                .catch(() => null));
+            if (body && typeof body.code === 'string') {
+                throw new ZiggsGatewayError(body.code, typeof body.message === 'string' ? body.message : body.code, response.status);
+            }
+        }
+        return response;
+    });
+}
+/** Resolve the gateway URL + auth headers for a `type: 'ziggs'` transport. */
+export function resolveZiggsGatewayTarget(config, defaults = {}) {
+    if (!config.connectionId) {
+        throw new Error('ziggs MCP transport requires a connectionId');
+    }
+    if (!config.grantId) {
+        throw new Error('ziggs MCP transport requires a grantId');
+    }
+    const operatorKey = config.operatorKey || process.env.ZIGGS_OPERATOR_KEY;
+    if (!operatorKey) {
+        throw new Error('ziggs MCP transport requires an operatorKey (or ZIGGS_OPERATOR_KEY)');
+    }
+    const agentId = config.agentId || defaults.agentId;
+    if (!agentId) {
+        throw new Error('ziggs MCP transport requires an agentId to impersonate (X-Agent-Id)');
+    }
+    const baseUrl = (config.baseUrl ||
+        process.env.BACKEND_URL ||
+        process.env.ZIGGS_BACKEND_URL ||
+        'http://localhost:3000').replace(/\/$/, '');
+    return {
+        url: new URL(`${baseUrl}/connections/${encodeURIComponent(config.connectionId)}/mcp`),
+        headers: {
+            authorization: `Bearer ${operatorKey}`,
+            'x-agent-id': agentId,
+            'x-grant-id': config.grantId,
+        },
+    };
+}
+/**
+ * Resolve the per-user gateway URL + headers (ZIG-771). No connectionId/grantId —
+ * the gateway resolves the invoking user's own connection + grant from
+ * `x-on-behalf-of-user` + the impersonated agent.
+ */
+export function resolvePerUserGatewayTarget(config, agentId, userId, onBehalfOfAgreementId) {
+    const operatorKey = config.operatorKey || process.env.ZIGGS_OPERATOR_KEY;
+    if (!operatorKey) {
+        throw new Error('ziggs-per-user MCP transport requires an operatorKey (or ZIGGS_OPERATOR_KEY)');
+    }
+    const baseUrl = (config.baseUrl ||
+        process.env.BACKEND_URL ||
+        process.env.ZIGGS_BACKEND_URL ||
+        'http://localhost:3000').replace(/\/$/, '');
+    return {
+        url: new URL(`${baseUrl}/connections/mcp/relay`),
+        headers: {
+            authorization: `Bearer ${operatorKey}`,
+            'x-agent-id': agentId,
+            'x-on-behalf-of-user': userId,
+            // ZIG-831: when this call runs under a delegation, userId is the delegating
+            // agent (senderId), not the end-user who owns the connection. The gateway
+            // uses this agreement to resolve the delegation root's user.
+            ...(onBehalfOfAgreementId ? { 'x-on-behalf-of-agreement': onBehalfOfAgreementId } : {}),
+        },
+    };
+}
+/** Provider `tools` array cap (OpenAI's is 128). */
+const DEFAULT_MAX_TOOLS = 128;
+/** Headroom reserved for control actions (wait/respond) + future additions. */
+const CONTROL_TOOL_RESERVE = 4;
+/**
+ * How many MCP tools may be bound to the LLM, given the provider cap and the
+ * number of extra (non-MCP) tools the agent also carries. Always >= 1 so a
+ * pathological config still binds something rather than nothing. ZIG-759.
+ */
+export function mcpToolBudget(maxTools, extraToolCount) {
+    return Math.max(1, maxTools - CONTROL_TOOL_RESERVE - extraToolCount);
+}
+export function buildTransport(config, defaults = {}) {
+    if (config.type === 'stdio') {
+        return new StdioClientTransport({
+            command: config.command,
+            args: config.args ?? [],
+            env: config.env,
+        });
+    }
+    if (config.type === 'ziggs') {
+        const target = resolveZiggsGatewayTarget(config, defaults);
+        return new StreamableHTTPClientTransport(target.url, {
+            requestInit: { headers: target.headers },
+            fetch: wrapGatewayFetch(),
+        });
+    }
+    if (config.type === 'ziggs-per-user') {
+        // Per-user transports are built lazily per invoking user in createMcpAgent
+        // (each needs a different x-on-behalf-of-user header), not here.
+        throw new Error('ziggs-per-user transport is created per invoking user, not via buildTransport');
+    }
+    return new StreamableHTTPClientTransport(new URL(config.url), config.headers && Object.keys(config.headers).length > 0
+        ? { requestInit: { headers: config.headers } }
+        : undefined);
+}
+function mcpContentToResult(content) {
+    const text = content
+        .map(c => (c.type === 'text' ? c.text ?? '' : JSON.stringify(c)))
+        .join('\n');
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function mapMcpTools(callTool, tools) {
+    return tools.map(tool => ({
+        schema: {
+            type: 'function',
+            function: {
+                name: tool.name,
+                description: tool.description ?? '',
+                parameters: tool.inputSchema ?? { type: 'object', properties: {} },
+            },
+        },
+        handler: async (args, context) => {
+            const result = await callTool(tool.name, args, context);
+            if (result.isError) {
+                throw new Error(mcpContentToResult(result.content));
+            }
+            return mcpContentToResult(result.content);
+        },
+        isGenericFallback: true,
+    }));
+}
+function buildDefaultWorkflow(description, mcpTools) {
+    const dflt = thinkingDefaults({ initial: 'idle' });
+    // Bind each MCP tool as an explicit action so runTurn includes them in the
+    // LLM API call and the decision schema. Without this, allowedToolNames is
+    // empty and the tools array passed to the LLM is also empty.
+    const toolActions = Object.fromEntries(mcpTools.map(t => [t.name, {
+            tool: t.name,
+            prompt: { when: t.description || `Use ${t.name}` },
+        }]));
+    return {
+        id: 'mcp-agent',
+        description: description || 'MCP-backed agent',
+        initial: 'idle',
+        states: {
+            idle: {
+                kind: 'thinking',
+                prompt: {
+                    role: 'You are a helpful agent powered by an MCP server.',
+                    goal: description || 'Help the user by calling the available tools.',
+                    constraints: 'Use your tools to answer the user\'s request. After gathering results, use "respond" to send the answer. Use "wait" only when no action is needed.',
+                },
+                actions: {
+                    ...dflt.actions,
+                    ...toolActions,
+                    respond: {
+                        prompt: {
+                            instruction: 'Send your final answer to the user.',
+                            when: 'You have gathered enough information and are ready to reply to the user.',
+                            format: 'args: { receiverId: "<userId>", message: "<your answer>" }',
+                        },
+                        produces: 'message-sent',
+                    },
+                },
+                transitions: [
+                    { to: 'idle', when: (o) => o.kind === 'wait' },
+                    { to: 'idle', when: (o) => o.kind === 'error' },
+                    { to: 'done', when: (o) => o.kind === 'message-sent' },
+                ],
+            },
+            done: {
+                kind: 'parked',
+                transitions: [
+                    { to: 'idle', when: (o) => o.kind === 'message-received' },
+                ],
+            },
+        },
+    };
+}
+/**
+ * Max chars for a single tool description bound to the LLM. Verbose MCP servers
+ * embed whole manuals in their descriptions (PostHog's `execute-sql` alone is
+ * ~30K chars of HogQL docs; its 146 tools total ~54K tokens of descriptions) and
+ * that full block rides every turn. Keep the lead — what the tool does + how to
+ * call it — and drop the embedded reference; agents fetch detail via dedicated
+ * schema/help tools at call time. Tunable; big enough to preserve real guidance.
+ * ZIG-759.
+ */
+export const MAX_TOOL_DESC_CHARS = 2000;
+/** Truncate one description at a sentence/newline boundary near the cap. */
+export function trimDescription(desc) {
+    if (!desc || desc.length <= MAX_TOOL_DESC_CHARS)
+        return desc;
+    const slice = desc.slice(0, MAX_TOOL_DESC_CHARS);
+    const boundary = Math.max(slice.lastIndexOf('\n'), slice.lastIndexOf('. '));
+    const head = boundary > MAX_TOOL_DESC_CHARS * 0.6 ? slice.slice(0, boundary + 1) : slice;
+    return `${head.trimEnd()} […description truncated; use the server's schema/help tools for full detail]`;
+}
+/** Trim oversized descriptions across the tool set (cost control, ZIG-759). */
+function trimToolDescriptions(tools, agentId) {
+    let trimmedCount = 0;
+    let savedChars = 0;
+    const out = tools.map((t) => {
+        const nextDesc = trimDescription(t.description);
+        if (nextDesc === t.description)
+            return t;
+        trimmedCount += 1;
+        savedChars += (t.description?.length ?? 0) - (nextDesc?.length ?? 0);
+        return { ...t, description: nextDesc };
+    });
+    if (trimmedCount > 0) {
+        console.warn(`[McpAdapter] ${agentId}: trimmed ${trimmedCount} oversized tool description(s) to ${MAX_TOOL_DESC_CHARS} chars, saving ~${Math.round(savedChars / 4 / 1000)}K tokens/turn. (ZIG-759)`);
+    }
+    return out;
+}
+/**
+ * Keep only tools whose name matches one of the allowlist substrings
+ * (case-insensitive). No allowlist → pass through unchanged. Applied before the
+ * maxTools cap so a targeted agent binds exactly the tools it needs. ZIG-759.
+ */
+function filterToolsByAllowlist(tools, allowedTools, agentId) {
+    if (!allowedTools || allowedTools.length === 0)
+        return tools;
+    const patterns = allowedTools.map((p) => p.toLowerCase());
+    const kept = tools.filter((t) => patterns.some((p) => t.name.toLowerCase().includes(p)));
+    console.warn(`[McpAdapter] ${agentId}: tool allowlist active — bound ${kept.length}/${tools.length} tools matching [${allowedTools.join(', ')}]${kept.length === 0 ? ' ⚠️ NONE MATCHED — check patterns against the server\'s tool names' : ': ' + kept.map((t) => t.name).join(', ')}.`);
+    return kept;
+}
+/**
+ * Cap the tool set bound to the LLM at the provider limit (OpenAI 128) —
+ * truncate and log rather than crash — and trim oversized descriptions so the
+ * bound schema doesn't ship a manual every turn. ZIG-759 Phase 1. Shared by the
+ * boot-time (single-client) and per-user paths. When `allowedTools` is set the
+ * server's tools are narrowed by name first, so the cap rarely bites.
+ */
+function capTools(tools, agentId, maxTools, extraToolCount, allowedTools) {
+    const allowed = filterToolsByAllowlist(tools, allowedTools, agentId);
+    const trimmed = trimToolDescriptions(allowed, agentId);
+    const budget = mcpToolBudget(maxTools, extraToolCount);
+    if (trimmed.length <= budget)
+        return trimmed;
+    console.warn(`[McpAdapter] ${agentId}: MCP server exposes ${trimmed.length} tools, over the ${maxTools}-tool LLM cap; binding the first ${budget}, dropping ${trimmed.length - budget}. (ZIG-759 Phase 2 will select per query.)`);
+    return trimmed.slice(0, budget);
+}
+/**
+ * Wraps any MCP server as a Ziggs AgentHost.
+ *
+ * 1. Opens a connection to the MCP server (stdio, HTTP, or the Ziggs gateway).
+ * 2. Calls tools/list and maps each tool to a Ziggs ToolDefinition.
+ * 3. Returns an AgentHost pre-loaded with those tools, ready to connectAsync().
+ *
+ * Usage (local stdio server):
+ *   const { host, closeMcp } = await createMcpAgent({
+ *     transport: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'] },
+ *     agentId: 'my-github-agent',
+ *     name: 'GitHub Agent',
+ *     description: 'Wraps the GitHub MCP server',
+ *   });
+ *   await host.connectAsync();
+ *
+ * Usage (OAuth-protected remote server, brokered through Ziggs — the user
+ * connected the server and issued this agent a grant; the agent never sees
+ * the user's token):
+ *   const { host, closeMcp } = await createMcpAgent({
+ *     transport: { type: 'ziggs', connectionId: 'con_abc', grantId: 'cgr_xyz' },
+ *     agentId: 'my-notion-agent',
+ *     name: 'Notion Agent',
+ *     description: 'Works in the owner\'s Notion via their MCP connection',
+ *   });
+ *   await host.connectAsync();
+ *
+ *   process.on('SIGTERM', async () => {
+ *     host.disconnect();
+ *     await host.drain();
+ *     await closeMcp();
+ *   });
+ */
+export async function createMcpAgent(options) {
+    const { transport: transportConfig, extraTools = [], workflow, maxTools = DEFAULT_MAX_TOOLS, allowedTools, toolSchema, ...hostOptions } = options;
+    // ── Per-user path (ZIG-771): no boot connection; one MCP client per invoking
+    // user, each carrying that user's on-behalf-of header for an isolated session.
+    if (transportConfig.type === 'ziggs-per-user') {
+        const agentId = transportConfig.agentId || hostOptions.agentId;
+        if (!agentId) {
+            throw new Error('ziggs-per-user MCP transport requires an agentId to impersonate');
+        }
+        if (!toolSchema || toolSchema.length === 0) {
+            throw new Error('ziggs-per-user MCP transport requires toolSchema (no boot connection to discover tools)');
+        }
+        const tools = capTools(toolSchema, agentId, maxTools, extraTools.length, allowedTools);
+        const clients = new Map();
+        const clientFor = (userId, onBehalfOfAgreementId) => {
+            // Key by user + agreement: the gateway may resolve a different end-user
+            // per agreement (delegation), so sessions must not be shared across them.
+            const cacheKey = `${userId}|${onBehalfOfAgreementId ?? ''}`;
+            let p = clients.get(cacheKey);
+            if (!p) {
+                p = (async () => {
+                    const target = resolvePerUserGatewayTarget(transportConfig, agentId, userId, onBehalfOfAgreementId);
+                    const transport = new StreamableHTTPClientTransport(target.url, {
+                        requestInit: { headers: target.headers },
+                        fetch: wrapGatewayFetch(),
+                    });
+                    const c = new Client({ name: 'ziggs-mcp-agent', version: '1.0.0' });
+                    await c.connect(transport);
+                    return c;
+                })().catch((err) => {
+                    // Don't cache a failed connect (e.g. NO_USER_CONNECTION before the
+                    // user consents) — the next turn must be able to retry.
+                    clients.delete(cacheKey);
+                    throw err;
+                });
+                clients.set(cacheKey, p);
+            }
+            return p;
+        };
+        // When the invoking user hasn't connected this server, open a connection
+        // request targeting THEM (X-On-Behalf-Of-User) so the consent prompt lands
+        // in their inbox. The backend dedups pending requests, so retrying every
+        // turn is safe. ZIG-771.
+        const backendBase = (transportConfig.baseUrl ||
+            process.env.BACKEND_URL ||
+            process.env.ZIGGS_BACKEND_URL ||
+            'http://localhost:3000').replace(/\/$/, '');
+        // App URL for the user-facing connect link (ZIG-790): api.ziggsai.com → ziggsai.com.
+        const appUrl = backendBase.includes('localhost')
+            ? 'http://localhost:1234'
+            : backendBase.replace(/\/\/api\./, '//');
+        const serverLabel = transportConfig.serverUrl
+            ? new URL(transportConfig.serverUrl).host
+            : 'the external service';
+        // Open a connection request for this user; returns its id so the caller can
+        // deep-link the user straight to it on the Connections page (ZIG-790).
+        const triggerConnectionRequest = async (userId) => {
+            if (!transportConfig.serverUrl)
+                return null;
+            const operatorKey = transportConfig.operatorKey || process.env.ZIGGS_OPERATOR_KEY;
+            const res = await fetch(`${backendBase}/connections/mcp/requests`, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    authorization: `Bearer ${operatorKey}`,
+                    'x-agent-id': agentId,
+                    'x-on-behalf-of-user': userId,
+                },
+                body: JSON.stringify({
+                    serverUrl: transportConfig.serverUrl,
+                    tools: tools.map(t => t.name),
+                }),
+            });
+            const body = (await res.json().catch(() => null));
+            return body?.request?.requestId ?? null;
+        };
+        const caller = async (name, args, context) => {
+            const userId = typeof context.senderId === 'string' ? context.senderId : undefined;
+            if (!userId) {
+                throw new Error('per-user MCP tool call requires an invoking user (context.senderId is missing)');
+            }
+            // ZIG-831: for a delegated wake, senderId is the delegating agent, not the
+            // connection-owning end-user; pass the agreement so the gateway resolves
+            // the delegation root's user.
+            const onBehalfOfAgreementId = typeof context.onBehalfOfAgreementId === 'string' ? context.onBehalfOfAgreementId : undefined;
+            // ZIG-832 (B): per-user resolution is intermittently flaky even when the
+            // connection is valid and resolvable — the same on-behalf call fails with
+            // NO_USER_CONNECTION on one wake and succeeds on the next. clientFor never
+            // caches a failed connect, so each attempt re-resolves from scratch. Retry
+            // a few times (with backoff) before surfacing the connect prompt, so a
+            // transient miss no longer fails the whole fetch step.
+            const MAX_ATTEMPTS = 3;
+            let lastErr;
+            for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+                try {
+                    const c = await clientFor(userId, onBehalfOfAgreementId);
+                    return (await c.callTool({ name, arguments: args }));
+                }
+                catch (err) {
+                    lastErr = err;
+                    const resolutionMiss = err instanceof ZiggsGatewayError && err.code === 'NO_USER_CONNECTION';
+                    const transient = resolutionMiss || !(err instanceof ZiggsGatewayError);
+                    if (attempt < MAX_ATTEMPTS && transient) {
+                        console.warn(`[McpAdapter] per-user ${name} attempt ${attempt}/${MAX_ATTEMPTS} failed (${err.message}); retrying with a fresh connection`);
+                        await new Promise((r) => setTimeout(r, 500 * attempt));
+                        continue;
+                    }
+                    break;
+                }
+            }
+            if (lastErr instanceof ZiggsGatewayError &&
+                lastErr.code === 'NO_USER_CONNECTION' &&
+                transportConfig.serverUrl) {
+                const requestId = await triggerConnectionRequest(userId).catch(() => null);
+                const link = `${appUrl}/app/settings/connections${requestId ? `?request=${encodeURIComponent(requestId)}` : ''}`;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `ACTION NEEDED: the user has not connected ${serverLabel}. Ask them to approve the connection here: ${link} — then retry.`,
+                        },
+                    ],
+                };
+            }
+            throw lastErr;
+        };
+        const host = new AgentHost({
+            ...hostOptions,
+            workflow: workflow ?? buildDefaultWorkflow(hostOptions.description ?? '', tools),
+            tools: [...mapMcpTools(caller, tools), ...extraTools],
+        });
+        return {
+            host,
+            closeMcp: async () => {
+                await Promise.all([...clients.values()].map(p => p.then(c => c.close()).catch(() => { })));
+            },
+            toolNames: tools.map(t => t.name),
+        };
+    }
+    // ── Single-client path (stdio / http / brokered ziggs): discover tools at boot.
+    const transport = buildTransport(transportConfig, { agentId: hostOptions.agentId });
+    const client = new Client({ name: 'ziggs-mcp-agent', version: '1.0.0' });
+    await client.connect(transport);
+    const rawTools = capTools((await client.listTools()).tools, hostOptions.agentId, maxTools, extraTools.length, allowedTools);
+    const caller = (name, args) => client.callTool({ name, arguments: args });
+    const mcpTools = mapMcpTools(caller, rawTools);
+    const resolvedWorkflow = workflow ?? buildDefaultWorkflow(hostOptions.description ?? '', rawTools);
+    const host = new AgentHost({
+        ...hostOptions,
+        workflow: resolvedWorkflow,
+        tools: [...mcpTools, ...extraTools],
+    });
+    return {
+        host,
+        closeMcp: () => client.close(),
+        toolNames: rawTools.map((t) => t.name),
+    };
+}

package/dist/adapters/OpenAIAdapter.d.ts

@@ -0,0 +1,26 @@
+import OpenAI from 'openai';
+import type { ToolDefinition } from '../tools/defineTool.js';
+interface ChatResult {
+    content: string | null;
+    tool_calls: OpenAI.Chat.ChatCompletionMessageToolCall[] | null;
+    message: OpenAI.Chat.ChatCompletionMessage;
+    usage: OpenAI.CompletionUsage | undefined;
+}
+interface AdapterOptions {
+    key?: string;
+    model?: string;
+}
+/** OpenAI completion-token cap varies by model family (e.g. gpt-4o-mini max 16384). */
+export declare function maxCompletionTokensForModel(model: string): number;
+export declare class OpenAIAdapter {
+    private client;
+    model: string;
+    constructor({ key, model }: AdapterOptions);
+    chat(prompt: string, tools?: ToolDefinition[], temperature?: number, systemHints?: OpenAI.Chat.ChatCompletionMessageParam[], options?: Record<string, unknown>): Promise<ChatResult>;
+    chatMessages(messages: OpenAI.Chat.ChatCompletionMessageParam[], tools?: ToolDefinition[], options?: Record<string, unknown>): Promise<ChatResult>;
+    chatMessagesStream(messages: OpenAI.Chat.ChatCompletionMessageParam[], onChunk: (text: string) => void): Promise<{
+        text: string;
+        usage: OpenAI.CompletionUsage | undefined;
+    }>;
+}
+export {};

package/dist/adapters/OpenAIAdapter.js

@@ -0,0 +1,158 @@
+import OpenAI from 'openai';
+import { runtimeLog } from '../shared/runtimeLog.js';
+/** OpenAI completion-token cap varies by model family (e.g. gpt-4o-mini max 16384). */
+export function maxCompletionTokensForModel(model) {
+    const m = model.toLowerCase();
+    if (m.includes('gpt-4o'))
+        return 16384;
+    return 25000;
+}
+export class OpenAIAdapter {
+    client;
+    model;
+    constructor({ key, model = 'gpt-5.4' }) {
+        this.client = new OpenAI({ apiKey: key });
+        this.model = model;
+    }
+    async chat(prompt, tools = [], temperature = 0.2, systemHints = [], options = {}) {
+        const messages = [
+            { role: 'system', content: 'Respond with valid JSON.' },
+            ...systemHints,
+            { role: 'user', content: prompt },
+        ];
+        return this.chatMessages(messages, tools, { ...options, temperature });
+    }
+    async chatMessages(messages, tools = [], options = {}) {
+        const openAITools = tools.length > 0
+            ? tools.map(t => {
+                const fn = (t.schema.function || t.schema);
+                const tAny = t;
+                const usageWhen = tAny['usage']
+                    ? ` Use when: ${tAny['usage']['when']}`
+                    : '';
+                return {
+                    type: 'function',
+                    function: {
+                        name: fn['name'],
+                        description: (fn['description'] || '') + usageWhen,
+                        parameters: fn['parameters'],
+                    },
+                };
+            })
+            : undefined;
+        try {
+            const { usage: _u, response_format: _explicitResponseFormat, ...restOptions } = options;
+            const responseFormat = openAITools
+                ? undefined
+                : (_explicitResponseFormat ?? { type: 'json_object' });
+            // OpenAI 400s response_format:{type:'json_object'} unless the word "json"
+            // appears somewhere in the messages. Callers are expected to mention it
+            // in their system prompt, but that's an implicit cross-file contract —
+            // guarantee it here instead of trusting every call site to remember.
+            let finalMessages = messages;
+            if (responseFormat?.type === 'json_object' &&
+                !messages.some(m => {
+                    const c = typeof m.content === 'string' ? m.content : JSON.stringify(m.content ?? '');
+                    return /json/i.test(c);
+                })) {
+                finalMessages = [...messages, { role: 'system', content: 'Respond with valid JSON.' }];
+            }
+            // Verbose LLM request/response logging — enabled for debugging.
+            // Comment out again to reduce log noise.
+            const divider = '─'.repeat(80);
+            console.log(`\n${divider}`);
+            console.log(`📤 LLM REQUEST → ${this.model}  (${finalMessages.length} msg${finalMessages.length === 1 ? '' : 's'})`);
+            console.log(divider);
+            for (const m of finalMessages) {
+                const content = typeof m.content === 'string' ? m.content : JSON.stringify(m.content);
+                const len = content?.length ?? 0;
+                console.log(`\n[${m.role.toUpperCase()}]  ${len} chars`);
+                console.log(content ?? '');
+            }
+            console.log(`${divider}\n`);
+            const res = await this.client.chat.completions.create({
+                model: this.model,
+                messages: finalMessages,
+                stream: false,
+                // Reasoning models (gpt-5.x/o-series) need a high cap for hidden
+                // reasoning tokens; gpt-4o family is capped lower by the API.
+                max_completion_tokens: maxCompletionTokensForModel(this.model),
+                response_format: responseFormat,
+                ...(openAITools && { tools: openAITools }),
+                ...restOptions,
+            });
+            const msg = res.choices[0].message;
+            const finishReason = res.choices[0].finish_reason;
+            const content = msg.content?.trim() ?? null;
+            const toolCalls = msg.tool_calls?.length ? msg.tool_calls : null;
+            // Verbose LLM response logging — enabled for debugging.
+            // Comment out again to reduce log noise.
+            console.log(`\n${divider}`);
+            console.log(`📥 LLM RESPONSE ← ${this.model}  finish=${finishReason}`);
+            console.log(divider);
+            if (content) {
+                console.log(`\n[CONTENT]  ${content.length} chars`);
+                console.log(content);
+            }
+            if (toolCalls) {
+                console.log(`\n[TOOL CALLS]  ${toolCalls.length}`);
+                for (const tc of toolCalls) {
+                    console.log(`  → ${tc.function.name}(${tc.function.arguments})`);
+                }
+            }
+            if (!content && !toolCalls)
+                console.log('\n(no content, no tool calls)');
+            if (res.usage) {
+                const u = res.usage;
+                console.log(`\n[USAGE]  prompt=${u.prompt_tokens} completion=${u.completion_tokens}${u.completion_tokens_details?.reasoning_tokens != null ? ` (reasoning=${u.completion_tokens_details.reasoning_tokens})` : ''} total=${u.total_tokens}`);
+            }
+            console.log(`${divider}\n`);
+            if (!content && !toolCalls && finishReason === 'length') {
+                const u = res.usage;
+                throw new Error(`LLM returned no usable output — completion token budget exhausted before any content ` +
+                    `(finish_reason=length, reasoning_tokens=${u?.completion_tokens_details?.reasoning_tokens ?? 'unknown'})`);
+            }
+            return {
+                content,
+                tool_calls: toolCalls,
+                message: msg,
+                usage: res.usage,
+            };
+        }
+        catch (error) {
+            const err = error;
+            runtimeLog.error('OpenAIAdapter', `LLM API call failed: ${err.message}`, {
+                model: this.model,
+                error: err.message,
+                status: err.status || 'unknown',
+                code: err.code || 'unknown',
+            });
+            throw error;
+        }
+    }
+    async chatMessagesStream(messages, onChunk) {
+        const stream = await this.client.chat.completions.create({
+            model: this.model,
+            messages,
+            stream: true,
+            // Without this, a streamed completion never returns a usage block — the
+            // streamed reply (often the largest output) would bill tokens that are
+            // counted nowhere (ZIG-813). The usage arrives on a final chunk whose
+            // `choices` is empty.
+            stream_options: { include_usage: true },
+            max_completion_tokens: maxCompletionTokensForModel(this.model),
+        });
+        let text = '';
+        let usage;
+        for await (const chunk of stream) {
+            if (chunk.usage)
+                usage = chunk.usage;
+            const delta = chunk.choices[0]?.delta?.content;
+            if (delta) {
+                text += delta;
+                onChunk(delta);
+            }
+        }
+        return { text, usage };
+    }
+}

package/dist/adapters/index.js

@@ -0,0 +1,2 @@
+export { OpenAIAdapter } from './OpenAIAdapter.js';
+export { AnthropicAdapter } from './AnthropicAdapter.js';