@jxburros/ai-nugget 0.3.1 → 0.6.0

package/dist/agent/loop.js

@@ -2,7 +2,7 @@ import { profileFor } from '../adapters/profiles.js';
 import { AIError } from '../errors.js';
 import { extractJson } from '../json.js';
 import { mergeUsage } from '../tokens.js';
-import { sleep } from '../util.js';
+import { asRecord, sleep } from '../util.js';
 import { validateToolArgs } from './tools.js';
 export function runAgent(opts) {
     let resolveResult;
@@ -21,6 +21,9 @@ async function* run(opts, resolveResult) {
     let finalText = '';
     let step = 0;
     let settled = false;
+    // Disclose the resolved tool protocol once up front (a silent promptJson
+    // fallback was the friction behind FR‑2).
+    yield emit(opts, { type: 'tool_mode', mode: toolMode });
     try {
         while (step < maxSteps) {
             step += 1;
@@ -30,16 +33,32 @@ async function* run(opts, resolveResult) {
             const calls = [];
             let stepText = '';
             let streamFailure;
+            // In promptJson mode a tool directive must not leak into the visible
+            // stream, so directive-looking text is withheld from `delta` events (still
+            // accumulated in `stepText` for parsing). Prose streams normally.
+            const filter = toolMode === 'promptJson' ? new PromptJsonDeltaFilter() : undefined;
             const requestMessages = toolMode === 'promptJson' ? withPromptJsonInstruction(messages, opts.tools) : messages;
             for await (const event of opts.handler.stream(opts.connection, {
                 model: opts.model,
                 messages: requestMessages,
                 tools: toolMode === 'promptJson' ? undefined : opts.tools,
+                temperature: opts.temperature,
+                maxTokens: opts.maxTokens,
+                topP: opts.topP,
+                stopSequences: opts.stopSequences,
+                providerOptions: opts.providerOptions,
                 signal: agentSignal.signal,
                 metadata: { ...opts.metadata, agentStep: step },
             })) {
-                if (event.type === 'delta')
+                if (event.type === 'delta') {
                     stepText += event.text;
+                    if (filter) {
+                        const visible = filter.push(event.text);
+                        if (visible)
+                            yield emit(opts, { type: 'delta', text: visible });
+                        continue;
+                    }
+                }
                 if (event.type === 'tool_call')
                     calls.push(event.call);
                 if (event.type === 'error')
@@ -51,10 +70,17 @@ async function* run(opts, resolveResult) {
                 }
                 yield emit(opts, event);
             }
+            // If withheld text turned out not to be a real directive, flush it so the
+            // user still sees the model's answer.
+            if (filter && calls.length === 0) {
+                const flushed = filter.flush();
+                if (flushed)
+                    yield emit(opts, { type: 'delta', text: flushed });
+            }
             // A handler-level failure (auth, policy, cancel, exhausted retries) must
             // stop the loop honestly rather than looking like an empty completion.
             if (streamFailure)
-                return yield* yieldDone(agentSignal.timedOut() ? 'deadline' : streamFailure.kind === 'canceled' ? 'canceled' : 'error');
+                return yield* yieldDone(agentSignal.timedOut() ? 'deadline' : streamFailure.kind === 'canceled' ? 'canceled' : 'error', errorInfo(streamFailure));
             finalText = stepText;
             messages.push(toolMode === 'promptJson'
                 ? { role: 'assistant', content: stepText }
@@ -75,7 +101,8 @@ async function* run(opts, resolveResult) {
                     continue;
                 }
                 let args = validation.args;
-                if (tool.sideEffects) {
+                const requiresApproval = tool.sideEffects || opts.approvalMode === 'all';
+                if (requiresApproval) {
                     if (!opts.approval) {
                         yield* appendToolDenied(opts, messages, step, call, 'No approval gate configured');
                         continue;
@@ -115,8 +142,16 @@ async function* run(opts, resolveResult) {
                     continue;
                 }
                 try {
-                    messages.push({ role: 'tool', toolCallId: call.id, name: call.name, content: JSON.stringify(executed.result) });
-                    yield emit(opts, { type: 'tool_result', step, call, result: executed.result, isError: false });
+                    // Guard against a tool returning `undefined` (JSON.stringify(undefined)
+                    // is the value `undefined`, not a string) — an unguarded value here
+                    // used to crash the next step's message mapper and kill the whole run.
+                    const serialized = JSON.stringify(executed.result) ?? 'null';
+                    messages.push({ role: 'tool', toolCallId: call.id, name: call.name, content: formatToolResult(serialized, opts.toolResult) });
+                    // A tool that returns a structured `{ ok: false, ... }` is a recoverable
+                    // error the model should react to — surface it as an error result.
+                    const record = asRecord(executed.result);
+                    const isError = record?.ok === false;
+                    yield emit(opts, { type: 'tool_result', step, call, result: executed.result, isError });
                 }
                 catch (error) {
                     const message = error instanceof Error ? error.message : 'Tool result was not serializable';
@@ -131,7 +166,8 @@ async function* run(opts, resolveResult) {
         return yield* yieldDone('max_steps');
     }
     catch (error) {
-        const result = makeResult(finalText, messages, usage ?? { estimated: true }, step, agentSignal.timedOut() ? 'deadline' : (agentSignal.signal?.aborted || (error instanceof AIError && error.kind === 'canceled')) ? 'canceled' : 'error');
+        const stopReason = agentSignal.timedOut() ? 'deadline' : (agentSignal.signal?.aborted || (error instanceof AIError && error.kind === 'canceled')) ? 'canceled' : 'error';
+        const result = makeResult(finalText, messages, usage ?? { estimated: true }, step, stopReason, stopReason === 'error' ? errorInfo(error) : undefined);
         settled = true;
         resolveResult(result);
         yield emit(opts, { type: 'agent_done', result });
@@ -143,8 +179,8 @@ async function* run(opts, resolveResult) {
             resolveResult(result);
         }
     }
-    function* yieldDone(stopReason) {
-        const result = makeResult(finalText, messages, usage ?? { estimated: true }, step, stopReason);
+    function* yieldDone(stopReason, error) {
+        const result = makeResult(finalText, messages, usage ?? { estimated: true }, step, stopReason, error);
         settled = true;
         resolveResult(result);
         yield emit(opts, { type: 'agent_done', result });
@@ -154,8 +190,67 @@ function emit(opts, event) {
     opts.onEvent?.(event);
     return event;
 }
-function makeResult(finalText, messages, usage, steps, stopReason) {
-    return { finalText, messages, usage, steps, stopReason };
+function makeResult(finalText, messages, usage, steps, stopReason, error) {
+    return error ? { finalText, messages, usage, steps, stopReason, error } : { finalText, messages, usage, steps, stopReason };
+}
+function errorInfo(error) {
+    if (error instanceof AIError)
+        return { kind: error.kind, message: error.message };
+    return { kind: 'tool_error', message: error instanceof Error ? error.message : 'Agent run failed' };
+}
+/**
+ * Applies the optional size cap and untrusted-content framing to a serialized
+ * tool result before it re-enters the model's context.
+ */
+function formatToolResult(serialized, opts) {
+    let out = serialized;
+    const max = opts?.maxChars;
+    if (max !== undefined && out.length > max) {
+        out = `${out.slice(0, max)}\n…[truncated ${out.length - max} chars]`;
+    }
+    if (opts?.wrapUntrusted) {
+        out = `<untrusted_tool_output>\n${out}\n</untrusted_tool_output>`;
+    }
+    return out;
+}
+/**
+ * Withholds a promptJson tool directive from the visible `delta` stream. Once
+ * the leading non-whitespace character is known: a `{`, `[`, or fence marks a
+ * directive candidate whose text is buffered (never streamed); anything else is
+ * prose that streams through untouched. `flush()` returns any buffered text when
+ * the stream ended without yielding a parsed directive.
+ */
+class PromptJsonDeltaFilter {
+    decided = false;
+    withhold = false;
+    buffer = '';
+    push(text) {
+        if (!this.decided) {
+            this.buffer += text;
+            const lead = this.buffer.replace(/^\s+/, '');
+            if (lead.length === 0)
+                return '';
+            this.decided = true;
+            this.withhold = /^[[{`]/.test(lead);
+            if (this.withhold)
+                return '';
+            const flushed = this.buffer;
+            this.buffer = '';
+            return flushed;
+        }
+        if (this.withhold) {
+            this.buffer += text;
+            return '';
+        }
+        return text;
+    }
+    flush() {
+        if (!this.withhold)
+            return '';
+        const out = this.buffer;
+        this.buffer = '';
+        return out;
+    }
 }
 function* appendToolError(opts, messages, step, call, message) {
     const result = { error: message };
@@ -170,13 +265,22 @@ function resolveToolMode(opts) {
     const mode = opts.toolMode ?? 'auto';
     if (mode !== 'auto')
         return mode;
+    // A model that actually advertises tool support gets native tool-calling even
+    // on a local runtime whose profile is conservatively `nativeTools: false`.
+    if (opts.modelCapabilities?.includes('tools'))
+        return 'native';
     return profileFor(opts.connection.provider, opts.connection.baseUrl).capabilities.nativeTools ? 'native' : 'promptJson';
 }
 function withPromptJsonInstruction(messages, tools) {
+    // Include each tool's parameter schema, not just its description, so the model
+    // knows the argument shape instead of guessing it (FR‑3).
+    const catalog = tools
+        .map((tool) => `- ${tool.name}: ${tool.description}\n  parameters: ${JSON.stringify(tool.parameters)}`)
+        .join('\n');
     return [
         {
             role: 'system',
-            content: `When you need tools, respond only with JSON. For one tool: {"tool":"name","input":{...}}. For several in one turn: {"tools":[{"tool":"name","input":{...}}]}. Available tools: ${tools.map((tool) => `${tool.name}: ${tool.description}`).join('; ')}`,
+            content: `When you need tools, respond only with JSON. For one tool: {"tool":"name","input":{...}}. For several in one turn: {"tools":[{"tool":"name","input":{...}}]}. The "input" object must match the tool's parameters schema. Available tools:\n${catalog}`,
         },
         ...messages.map(toPromptJsonMessage),
     ];
@@ -216,7 +320,7 @@ function callsFromPromptJson(text) {
         if (typeof record.tool !== 'string')
             continue;
         calls.push({
-            id: crypto.randomUUID(),
+            id: randomId(),
             name: record.tool,
             arguments: record.input && typeof record.input === 'object' ? record.input : {},
             raw: JSON.stringify(record.input ?? {}),
@@ -224,6 +328,9 @@ function callsFromPromptJson(text) {
     }
     return calls;
 }
+function randomId() {
+    return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
 function textContent(content) {
     if (typeof content === 'string')
         return content;

package/dist/cjs/adapters/engines/anthropic.js

@@ -0,0 +1,308 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnthropicAdapter = void 0;
+const errors_js_1 = require("../../errors.js");
+const tokens_js_1 = require("../../tokens.js");
+const transport_js_1 = require("../../transport.js");
+const util_js_1 = require("../../util.js");
+const base_js_1 = require("./base.js");
+const JSON_MODE_TOOL = 'json_output';
+class AnthropicAdapter {
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+    }
+    async chat(conn, req) {
+        let result;
+        for await (const event of this.stream(conn, req)) {
+            if (event.type === 'done')
+                result = event.result;
+            if (event.type === 'error')
+                throw event.error;
+        }
+        if (!result)
+            throw new errors_js_1.AIError('Anthropic stream ended without a result', { kind: 'invalid_response', provider: conn.provider });
+        return result;
+    }
+    async *stream(conn, req) {
+        const started = Date.now();
+        const jsonMode = req.responseFormat?.type === 'json' && !req.tools?.length;
+        let firstTokenMs = null;
+        let text = '';
+        let inputTokens;
+        let outputTokens;
+        let stopReason;
+        let sawTerminal = false;
+        const emittedTools = [];
+        // Partial tool_use blocks keyed by content-block index (input_json_delta accumulation).
+        const blocks = new Map();
+        const timeout = (0, base_js_1.streamTimeout)(conn, req.signal);
+        yield { type: 'start', callId: '', provider: conn.provider, model: req.model };
+        // Anthropic JSON mode is implemented as a forced `json_output` tool, which
+        // cannot coexist with the caller's own tools — same silent-downgrade shape
+        // as Gemini, so it gets the same signal rather than quietly dropping.
+        if (req.responseFormat?.type === 'json' && req.tools?.length) {
+            yield {
+                type: 'context',
+                kind: 'json_mode_downgraded',
+                data: { reason: 'Anthropic JSON mode uses a forced tool and cannot be combined with caller tools; the request was sent without JSON mode', provider: conn.provider },
+            };
+        }
+        try {
+            const res = await (0, transport_js_1.postResponse)(`${conn.baseUrl}/v1/messages`, body(req, jsonMode), conn.headers, timeout.signal, conn.provider);
+            const contentType = res.headers.get('content-type') ?? '';
+            if (!contentType.includes('text/event-stream')) {
+                const data = await res.json();
+                const parsed = parseResponse(data);
+                inputTokens = parsed.inputTokens;
+                outputTokens = parsed.outputTokens;
+                stopReason = parsed.stopReason;
+                sawTerminal = true;
+                if (jsonMode) {
+                    text = jsonTextFrom(parsed.toolCalls, parsed.text);
+                    if (text)
+                        yield { type: 'delta', text };
+                }
+                else {
+                    text = parsed.text;
+                    if (text)
+                        yield { type: 'delta', text };
+                    for (const call of parsed.toolCalls) {
+                        emittedTools.push(call);
+                        yield { type: 'tool_call', call };
+                    }
+                }
+            }
+            else {
+                for await (const line of (0, transport_js_1.sseLines)(res)) {
+                    timeout.bump();
+                    const record = (0, util_js_1.asRecord)((0, base_js_1.safeParse)(line));
+                    if (!record)
+                        continue;
+                    const type = (0, util_js_1.asString)(record.type);
+                    if (type === 'message_start') {
+                        const usage = (0, util_js_1.asRecord)((0, util_js_1.asRecord)(record.message)?.usage);
+                        inputTokens = (0, util_js_1.asNumber)(usage?.input_tokens) ?? inputTokens;
+                        outputTokens = (0, util_js_1.asNumber)(usage?.output_tokens) ?? outputTokens;
+                    }
+                    else if (type === 'content_block_start') {
+                        const index = (0, util_js_1.asNumber)(record.index) ?? 0;
+                        const block = (0, util_js_1.asRecord)(record.content_block);
+                        if (block?.type === 'tool_use') {
+                            blocks.set(index, { id: (0, util_js_1.asString)(block.id) ?? (0, base_js_1.randomId)(), name: (0, util_js_1.asString)(block.name) ?? 'unknown', raw: '' });
+                        }
+                    }
+                    else if (type === 'content_block_delta') {
+                        const index = (0, util_js_1.asNumber)(record.index) ?? 0;
+                        const delta = (0, util_js_1.asRecord)(record.delta);
+                        if (delta?.type === 'text_delta') {
+                            const piece = (0, util_js_1.asString)(delta.text) ?? '';
+                            if (piece) {
+                                if (firstTokenMs === null)
+                                    firstTokenMs = Date.now() - started;
+                                text += piece;
+                                yield { type: 'delta', text: piece };
+                            }
+                        }
+                        else if (delta?.type === 'thinking_delta') {
+                            // Extended-thinking tokens ride the reasoning channel, kept out of `text`.
+                            const piece = (0, util_js_1.asString)(delta.thinking) ?? '';
+                            if (piece)
+                                yield { type: 'reasoning', text: piece };
+                        }
+                        else if (delta?.type === 'input_json_delta') {
+                            const partial = blocks.get(index);
+                            if (partial)
+                                partial.raw += (0, util_js_1.asString)(delta.partial_json) ?? '';
+                        }
+                    }
+                    else if (type === 'content_block_stop') {
+                        const index = (0, util_js_1.asNumber)(record.index) ?? 0;
+                        const partial = blocks.get(index);
+                        if (partial) {
+                            const call = { id: partial.id, name: partial.name, raw: partial.raw, arguments: (0, base_js_1.parseArgs)(partial.raw) };
+                            blocks.delete(index);
+                            if (jsonMode && call.name === JSON_MODE_TOOL) {
+                                text = jsonTextFrom([call], text);
+                                if (firstTokenMs === null)
+                                    firstTokenMs = Date.now() - started;
+                                yield { type: 'delta', text };
+                            }
+                            else {
+                                emittedTools.push(call);
+                                yield { type: 'tool_call', call };
+                            }
+                        }
+                    }
+                    else if (type === 'message_stop') {
+                        sawTerminal = true;
+                    }
+                    else if (type === 'message_delta') {
+                        const delta = (0, util_js_1.asRecord)(record.delta);
+                        if ((0, util_js_1.asString)(delta?.stop_reason))
+                            sawTerminal = true;
+                        stopReason = (0, util_js_1.asString)(delta?.stop_reason) ?? stopReason;
+                        const usage = (0, util_js_1.asRecord)(record.usage);
+                        outputTokens = (0, util_js_1.asNumber)(usage?.output_tokens) ?? outputTokens;
+                    }
+                }
+            }
+            if (!sawTerminal)
+                yield (0, base_js_1.streamAnomaly)('stream ended without a stop_reason or message_stop');
+            const hasTools = emittedTools.length > 0;
+            yield { type: 'done', result: {
+                    text,
+                    toolCalls: hasTools ? emittedTools : undefined,
+                    finishReason: mapStop(stopReason, hasTools),
+                    usage: inputTokens !== undefined || outputTokens !== undefined ? { inputTokens, outputTokens, estimated: false } : (0, tokens_js_1.estimatedUsage)((0, util_js_1.textFromMessages)(req.messages), text),
+                    timing: { firstTokenMs, totalMs: Date.now() - started },
+                    model: req.model,
+                    source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl },
+                } };
+        }
+        catch (error) {
+            throw (0, base_js_1.streamError)(error, timeout, conn.provider);
+        }
+        finally {
+            timeout.done();
+        }
+    }
+    /**
+     * Lists models from Anthropic's `/v1/models` endpoint (auth + version headers
+     * already applied to `conn.headers`). The endpoint does not report a context
+     * window, so `contextWindow` is left undefined rather than guessed.
+     */
+    async listModels(conn) {
+        const { data } = await (0, transport_js_1.fetchJson)((0, util_js_1.joinUrl)(conn.baseUrl, '/v1/models'), {
+            method: 'GET',
+            headers: conn.headers,
+            timeoutMs: Math.min(conn.timeoutMs ?? base_js_1.DEFAULT_TIMEOUT_MS, 15_000),
+            provider: conn.provider,
+        });
+        const rows = Array.isArray((0, util_js_1.asRecord)(data)?.data) ? (0, util_js_1.asRecord)(data).data : [];
+        return rows
+            .map((row) => (0, util_js_1.asString)((0, util_js_1.asRecord)(row)?.id))
+            .filter((id) => Boolean(id))
+            .map((id) => ({ id, source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl } }));
+    }
+}
+exports.AnthropicAdapter = AnthropicAdapter;
+function body(req, jsonMode) {
+    const system = req.messages.filter((m) => m.role === 'system').map((m) => textContent(m.content)).join('\n\n') || undefined;
+    const base = {
+        model: req.model,
+        max_tokens: req.maxTokens ?? 4096,
+        temperature: req.temperature,
+        top_p: req.topP,
+        stop_sequences: req.stopSequences,
+        system,
+        messages: toAnthropicMessages(req.messages.filter((m) => m.role !== 'system')),
+        stream: true,
+    };
+    if (jsonMode) {
+        // Forced-tool JSON mode: Anthropic has no response_format, so we make the
+        // model answer through a single required tool whose input is the JSON we want.
+        base.tools = [{ name: JSON_MODE_TOOL, description: 'Return the answer as a JSON object.', input_schema: schemaFor(req) }];
+        base.tool_choice = { type: 'tool', name: JSON_MODE_TOOL };
+    }
+    else if (req.tools?.length) {
+        base.tools = req.tools.map((tool) => ({ name: tool.name, description: tool.description, input_schema: tool.parameters }));
+        if (typeof req.toolChoice === 'object')
+            base.tool_choice = { type: 'tool', name: req.toolChoice.name };
+        else if (req.toolChoice === 'auto')
+            base.tool_choice = { type: 'auto' };
+        else if (req.toolChoice === 'none')
+            base.tool_choice = { type: 'none' };
+    }
+    // providerOptions carries Anthropic-native fields (`thinking`, `metadata`,
+    // top-level `cache_control` extras, `service_tier`, …) without a release.
+    return (0, util_js_1.applyProviderOptions)(base, req.providerOptions);
+}
+function toAnthropicMessages(messages) {
+    const out = [];
+    for (let index = 0; index < messages.length; index += 1) {
+        const message = messages[index];
+        if (message.role !== 'tool') {
+            out.push(toAnthropicMessage(message));
+            continue;
+        }
+        const content = [];
+        while (index < messages.length && messages[index]?.role === 'tool') {
+            const toolMessage = messages[index];
+            content.push({ type: 'tool_result', tool_use_id: toolMessage.toolCallId ?? '', content: textContent(toolMessage.content) });
+            index += 1;
+        }
+        index -= 1;
+        out.push({ role: 'user', content });
+    }
+    return out;
+}
+function toAnthropicMessage(m) {
+    // Tool-role messages are handled by toAnthropicMessages' batching loop and
+    // never reach here, so no tool branch is needed.
+    // assistant turns that carried tool calls replay them as tool_use blocks,
+    // preserving any text/image content parts that accompanied the calls.
+    if (m.role === 'assistant' && m.toolCalls?.length) {
+        const content = [...contentBlocks(m.content)];
+        for (const call of m.toolCalls)
+            content.push({ type: 'tool_use', id: call.id, name: call.name, input: call.arguments ?? {} });
+        return { role: 'assistant', content };
+    }
+    return {
+        role: m.role === 'assistant' ? 'assistant' : 'user',
+        content: typeof m.content === 'string' ? m.content : contentBlocks(m.content),
+    };
+}
+/** Maps text/image content — a string or a ContentPart[] — onto Anthropic content blocks. */
+function contentBlocks(content) {
+    if (typeof content === 'string')
+        return content ? [{ type: 'text', text: content }] : [];
+    return content.map((part) => part.type === 'image'
+        ? { type: 'image', source: { type: 'base64', media_type: part.mimeType ?? 'image/png', data: part.imageBase64 ?? '' } }
+        : { type: 'text', text: part.text ?? '' });
+}
+function textContent(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!content)
+        return '';
+    return content.filter((part) => part.type === 'text').map((part) => part.text ?? '').join('\n');
+}
+function parseResponse(data) {
+    const record = (0, util_js_1.asRecord)(data);
+    const content = Array.isArray(record?.content) ? record.content : [];
+    let text = '';
+    const toolCalls = [];
+    for (const blockValue of content) {
+        const block = (0, util_js_1.asRecord)(blockValue);
+        if (block?.type === 'text')
+            text += (0, util_js_1.asString)(block.text) ?? '';
+        if (block?.type === 'tool_use') {
+            toolCalls.push({
+                id: (0, util_js_1.asString)(block.id) ?? (0, base_js_1.randomId)(),
+                name: (0, util_js_1.asString)(block.name) ?? 'unknown',
+                arguments: block.input ?? {},
+                raw: JSON.stringify(block.input ?? {}),
+            });
+        }
+    }
+    const usage = (0, util_js_1.asRecord)(record?.usage);
+    return { text, inputTokens: (0, util_js_1.asNumber)(usage?.input_tokens), outputTokens: (0, util_js_1.asNumber)(usage?.output_tokens), stopReason: (0, util_js_1.asString)(record?.stop_reason), toolCalls };
+}
+function schemaFor(req) {
+    const schema = req.responseFormat?.type === 'json' ? req.responseFormat.schema : undefined;
+    return schema ?? { type: 'object' };
+}
+function jsonTextFrom(toolCalls, fallback) {
+    const json = toolCalls.find((call) => call.name === JSON_MODE_TOOL) ?? toolCalls[0];
+    if (json)
+        return json.raw && json.raw.trim() ? json.raw : JSON.stringify(json.arguments ?? {});
+    return fallback;
+}
+function mapStop(stop, hasTools) {
+    if (stop === 'tool_use' && hasTools)
+        return 'tool';
+    if (stop === 'max_tokens')
+        return 'length';
+    return 'stop';
+}