@jxburros/ai-nugget 0.3.1 → 0.6.0

package/nugget/dist/adapters/profiles.js

@@ -0,0 +1,121 @@
+const HOSTED_CLOUD = { nativeTools: true, jsonMode: true, local: false, embeddable: false };
+const LOCAL_RUNTIME = { nativeTools: false, jsonMode: false, local: true, embeddable: true };
+export const PROVIDER_PROFILES = {
+    openai: {
+        engine: 'openaiChat',
+        defaultBaseUrl: 'https://api.openai.com/v1',
+        auth: 'bearer',
+        listModelsPath: '/models',
+        capabilities: HOSTED_CLOUD,
+        quirks: { supportsUsageInStream: true, maxTokensParam: 'max_completion_tokens', supportsJsonSchema: true, supportsIdempotencyKey: true },
+    },
+    'azure-openai': {
+        engine: 'openaiChat',
+        auth: 'api-key-header',
+        capabilities: HOSTED_CLOUD,
+        quirks: { urlTemplate: '{baseUrl}/openai/deployments/{model}/chat/completions?api-version={apiVersion}', apiVersion: '2024-10-21', maxTokensParam: 'max_completion_tokens', supportsJsonSchema: true },
+    },
+    openrouter: {
+        engine: 'openaiChat',
+        defaultBaseUrl: 'https://openrouter.ai/api/v1',
+        auth: 'bearer',
+        defaultHeaders: { 'HTTP-Referer': 'https://github.com/jxburros/AI-Nugget', 'X-Title': 'ai-nugget' },
+        listModelsPath: '/models',
+        capabilities: HOSTED_CLOUD,
+        quirks: { supportsUsageInStream: true },
+    },
+    groq: { engine: 'openaiChat', defaultBaseUrl: 'https://api.groq.com/openai/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+    deepseek: { engine: 'openaiChat', defaultBaseUrl: 'https://api.deepseek.com/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+    mistral: { engine: 'openaiChat', defaultBaseUrl: 'https://api.mistral.ai/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+    together: { engine: 'openaiChat', defaultBaseUrl: 'https://api.together.xyz/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+    fireworks: { engine: 'openaiChat', defaultBaseUrl: 'https://api.fireworks.ai/inference/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+    cerebras: { engine: 'openaiChat', defaultBaseUrl: 'https://api.cerebras.ai/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+    moonshot: { engine: 'openaiChat', defaultBaseUrl: 'https://api.moonshot.ai/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+    // Cohere's OpenAI-compatible surface lives under /compatibility/v1.
+    cohere: { engine: 'openaiChat', defaultBaseUrl: 'https://api.cohere.ai/compatibility/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+    // Perplexity has no public model-listing endpoint, so listModels resolves empty.
+    perplexity: { engine: 'openaiChat', defaultBaseUrl: 'https://api.perplexity.ai', auth: 'bearer', capabilities: HOSTED_CLOUD },
+    lmstudio: {
+        engine: 'openaiChat',
+        defaultBaseUrl: 'http://localhost:1234/v1',
+        auth: 'none',
+        listModelsPath: '/models',
+        capabilities: LOCAL_RUNTIME,
+        quirks: { keyOptional: true },
+    },
+    llamacpp: {
+        engine: 'openaiChat',
+        defaultBaseUrl: 'http://localhost:8080/v1',
+        auth: 'none',
+        listModelsPath: '/models',
+        healthPath: '/health',
+        capabilities: LOCAL_RUNTIME,
+        quirks: { keyOptional: true, modelOptional: true },
+    },
+    vllm: {
+        engine: 'openaiChat',
+        defaultBaseUrl: 'http://localhost:8000/v1',
+        auth: 'none',
+        listModelsPath: '/models',
+        capabilities: LOCAL_RUNTIME,
+        quirks: { keyOptional: true },
+    },
+    ollama: {
+        engine: 'ollama',
+        defaultBaseUrl: 'http://localhost:11434',
+        auth: 'none',
+        listModelsPath: '/api/tags',
+        // Ollama's `format: 'json'` is engine-enforced (reliable regardless of
+        // model); its `tools` field is honored only by models trained for tool
+        // use, so nativeTools stays conservative like the other local runtimes.
+        capabilities: { ...LOCAL_RUNTIME, jsonMode: true },
+        quirks: { keyOptional: true },
+    },
+    anthropic: {
+        engine: 'anthropic',
+        defaultBaseUrl: 'https://api.anthropic.com',
+        auth: 'x-api-key',
+        defaultHeaders: { 'anthropic-version': '2023-06-01' },
+        capabilities: HOSTED_CLOUD,
+        quirks: { maxTokensRequired: true },
+    },
+    google: {
+        engine: 'google',
+        defaultBaseUrl: 'https://generativelanguage.googleapis.com',
+        auth: 'x-goog-api-key',
+        capabilities: HOSTED_CLOUD,
+    },
+    'openai-compat': {
+        engine: 'openaiChat',
+        auth: 'bearer',
+        listModelsPath: '/models',
+        // Unknown endpoint — usually pointed at a local/self-hosted server, so
+        // assume the conservative local-runtime defaults rather than the hosted-cloud ones.
+        capabilities: LOCAL_RUNTIME,
+        // Most servers reached through this escape hatch (JX Runtime and other
+        // local OpenAI-compatible runtimes) don't require a key at all; keep
+        // `auth: 'bearer'` for the ones that do (a key is only sent if provided).
+        quirks: { keyOptional: true },
+    },
+};
+export function profileFor(provider, baseUrl) {
+    return PROVIDER_PROFILES[provider] ?? {
+        ...PROVIDER_PROFILES['openai-compat'],
+        defaultBaseUrl: baseUrl,
+    };
+}
+export function applyAuth(profile, apiKey, headers) {
+    const next = { ...profile.defaultHeaders, ...headers };
+    if (!apiKey)
+        return next;
+    if (profile.auth === 'bearer')
+        next.authorization = `Bearer ${apiKey}`;
+    else if (profile.auth === 'x-api-key')
+        next['x-api-key'] = apiKey;
+    else if (profile.auth === 'x-goog-api-key')
+        next['x-goog-api-key'] = apiKey;
+    else if (profile.auth === 'api-key-header')
+        next['api-key'] = apiKey;
+    return next;
+}
+//# sourceMappingURL=profiles.js.map

package/nugget/dist/adapters/profiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.js","sourceRoot":"","sources":["../../src/adapters/profiles.ts"],"names":[],"mappings":"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"}

package/nugget/dist/agent/index.d.ts

@@ -0,0 +1,3 @@
+export * from './tools.js';
+export * from './loop.js';
+//# sourceMappingURL=index.d.ts.map

package/nugget/dist/agent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC"}

package/nugget/dist/agent/index.js

@@ -0,0 +1,3 @@
+export * from './tools.js';
+export * from './loop.js';
+//# sourceMappingURL=index.js.map

package/nugget/dist/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC"}

package/nugget/dist/agent/loop.d.ts

@@ -0,0 +1,112 @@
+import type { AIHandler } from '../handler.js';
+import type { AIErrorKind, ChatMessage, Connection, StreamEvent, ToolCall, Usage } from '../types.js';
+import type { ToolSpec } from './tools.js';
+export interface AgentOptions {
+    handler: AIHandler;
+    connection: Connection;
+    model: string;
+    tools: ToolSpec[];
+    messages: ChatMessage[];
+    /**
+     * `native` sends `tools` on the request; `promptJson` describes tools in a
+     * system message and parses a JSON directive back out of plain text.
+     * `auto` (the default) picks per-call from the connection's provider
+     * capability profile (`profileFor(provider).capabilities.nativeTools`) —
+     * hosted providers with reliable tool-calling get `native`, local runtimes
+     * (Ollama, llama.cpp, LM Studio, vLLM) and the `openai-compat` escape hatch
+     * default to `promptJson` since native tool support there is model-
+     * dependent, not protocol-guaranteed.
+     */
+    toolMode?: 'native' | 'promptJson' | 'auto';
+    /**
+     * Discovered capabilities of the specific model (e.g. Ollama `/api/show`
+     * `["tools"]`). When `toolMode` is `auto`, a `tools` capability here upgrades a
+     * local model to `native` tool-calling instead of the profile's conservative
+     * `promptJson` default — so a capable local model isn't forced onto the fallback.
+     */
+    modelCapabilities?: string[];
+    /** Sampler/decoding options forwarded to every model turn (parity with a plain chat call). */
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    stopSequences?: string[];
+    /** Provider-native passthrough forwarded to every turn — see {@link ChatRequest.providerOptions}. */
+    providerOptions?: Record<string, unknown>;
+    budget?: {
+        maxSteps?: number;
+        maxTokens?: number;
+        deadlineMs?: number;
+    };
+    approval?: ApprovalGate;
+    /**
+     * Which tools require the approval gate. `sideEffectsOnly` (default) gates only
+     * tools declared `sideEffects: true`; `all` gates every tool — so `tool_denied`
+     * is reachable without marking each tool, and a consumer can require approval
+     * for a whole run in one place.
+     */
+    approvalMode?: 'sideEffectsOnly' | 'all';
+    /**
+     * Bounds and framing applied to each tool result before it re-enters the
+     * model's context. `maxChars` truncates oversized results (with a notice) so a
+     * single large return can't blow the next turn's window; `wrapUntrusted` fences
+     * the result in an `<untrusted_tool_output>` envelope. Both are opt-in.
+     */
+    toolResult?: {
+        maxChars?: number;
+        wrapUntrusted?: boolean;
+    };
+    onEvent?: (e: AgentEvent) => void;
+    signal?: AbortSignal;
+    metadata?: Record<string, unknown>;
+}
+export type ApprovalGate = (req: {
+    call: ToolCall;
+    tool: ToolSpec;
+    step: number;
+}) => Promise<'allow' | 'deny' | {
+    modifiedArguments: unknown;
+}>;
+export type AgentEvent = StreamEvent | {
+    type: 'step_start';
+    step: number;
+} | {
+    type: 'tool_mode';
+    mode: 'native' | 'promptJson';
+} | {
+    type: 'tool_start';
+    step: number;
+    call: ToolCall;
+} | {
+    type: 'tool_result';
+    step: number;
+    call: ToolCall;
+    result: unknown;
+    isError: boolean;
+} | {
+    type: 'tool_denied';
+    step: number;
+    call: ToolCall;
+    reason: string;
+} | {
+    type: 'agent_done';
+    result: AgentResult;
+};
+export interface AgentResult {
+    finalText: string;
+    messages: ChatMessage[];
+    usage: Usage;
+    steps: number;
+    stopReason: 'finished' | 'max_steps' | 'budget' | 'deadline' | 'canceled' | 'error';
+    /**
+     * Populated when `stopReason` is `error`: the failure that ended the run, so
+     * the caller can see what went wrong without replaying the event stream.
+     */
+    error?: {
+        kind: AIErrorKind;
+        message: string;
+    };
+}
+export declare function runAgent(opts: AgentOptions): AsyncIterable<AgentEvent> & {
+    result: Promise<AgentResult>;
+};
+//# sourceMappingURL=loop.d.ts.map

package/nugget/dist/agent/loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"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"}

package/nugget/dist/agent/loop.js

@@ -0,0 +1,370 @@
+import { profileFor } from '../adapters/profiles.js';
+import { AIError } from '../errors.js';
+import { extractJson } from '../json.js';
+import { mergeUsage } from '../tokens.js';
+import { asRecord, sleep } from '../util.js';
+import { validateToolArgs } from './tools.js';
+export function runAgent(opts) {
+    let resolveResult;
+    const result = new Promise((resolve) => {
+        resolveResult = resolve;
+    });
+    const iterable = run(opts, resolveResult);
+    return Object.assign(iterable, { result });
+}
+async function* run(opts, resolveResult) {
+    const messages = [...opts.messages];
+    const toolMode = resolveToolMode(opts);
+    const maxSteps = opts.budget?.maxSteps ?? 8;
+    const agentSignal = createAgentSignal(opts.signal, opts.budget?.deadlineMs);
+    let usage;
+    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;
+            if (agentSignal.signal?.aborted)
+                return yield* yieldDone(agentSignal.timedOut() ? 'deadline' : 'canceled');
+            yield emit(opts, { type: 'step_start', step });
+            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') {
+                    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')
+                    streamFailure = event.error;
+                if (event.type === 'done') {
+                    usage = usage ? mergeUsage(usage, event.result.usage) : event.result.usage;
+                    if (toolMode === 'promptJson' && calls.length === 0)
+                        calls.push(...callsFromPromptJson(stepText));
+                }
+                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', errorInfo(streamFailure));
+            finalText = stepText;
+            messages.push(toolMode === 'promptJson'
+                ? { role: 'assistant', content: stepText }
+                : { role: 'assistant', content: stepText, toolCalls: calls.length ? calls : undefined });
+            if (calls.length === 0)
+                return yield* yieldDone('finished');
+            for (const call of calls) {
+                if (agentSignal.signal?.aborted)
+                    return yield* yieldDone(agentSignal.timedOut() ? 'deadline' : 'canceled');
+                const tool = opts.tools.find((candidate) => candidate.name === call.name);
+                if (!tool) {
+                    yield* appendToolError(opts, messages, step, call, `Unknown tool: ${call.name}`);
+                    continue;
+                }
+                const validation = validateToolArgs(tool, call);
+                if (!validation.ok) {
+                    yield* appendToolError(opts, messages, step, call, validation.message);
+                    continue;
+                }
+                let args = validation.args;
+                const requiresApproval = tool.sideEffects || opts.approvalMode === 'all';
+                if (requiresApproval) {
+                    if (!opts.approval) {
+                        yield* appendToolDenied(opts, messages, step, call, 'No approval gate configured');
+                        continue;
+                    }
+                    const approval = await opts.approval({ call, tool, step });
+                    if (agentSignal.signal?.aborted)
+                        return yield* yieldDone(agentSignal.timedOut() ? 'deadline' : 'canceled');
+                    if (approval === 'deny') {
+                        yield* appendToolDenied(opts, messages, step, call, 'Denied by approval gate');
+                        continue;
+                    }
+                    if (approval !== 'allow') {
+                        const modified = validateToolArgs(tool, { ...call, arguments: approval.modifiedArguments });
+                        if (!modified.ok) {
+                            yield* appendToolError(opts, messages, step, call, modified.message);
+                            continue;
+                        }
+                        args = modified.args;
+                    }
+                }
+                yield emit(opts, { type: 'tool_start', step, call });
+                let executed;
+                try {
+                    const result = await tool.execute(args, {
+                        signal: agentSignal.signal ?? new AbortController().signal,
+                        callId: call.id,
+                        step,
+                        metadata: opts.metadata,
+                    });
+                    executed = { ok: true, result };
+                }
+                catch (error) {
+                    executed = { ok: false, message: error instanceof Error ? error.message : 'Tool failed' };
+                }
+                if (!executed.ok) {
+                    yield* appendToolError(opts, messages, step, call, executed.message);
+                    continue;
+                }
+                try {
+                    // 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';
+                    yield* appendToolError(opts, messages, step, call, message);
+                }
+            }
+            const totalTokens = (usage?.inputTokens ?? 0) + (usage?.outputTokens ?? 0);
+            if (opts.budget?.maxTokens && totalTokens > opts.budget.maxTokens)
+                return yield* yieldDone('budget');
+            await sleep(0, agentSignal.signal);
+        }
+        return yield* yieldDone('max_steps');
+    }
+    catch (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 });
+    }
+    finally {
+        agentSignal.dispose();
+        if (!settled) {
+            const result = makeResult(finalText, messages, usage ?? { estimated: true }, step, 'canceled');
+            resolveResult(result);
+        }
+    }
+    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 });
+    }
+}
+function emit(opts, event) {
+    opts.onEvent?.(event);
+    return event;
+}
+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 };
+    messages.push({ role: 'tool', toolCallId: call.id, name: call.name, content: JSON.stringify(result) });
+    yield emit(opts, { type: 'tool_result', step, call, result, isError: true });
+}
+function* appendToolDenied(opts, messages, step, call, reason) {
+    messages.push({ role: 'tool', toolCallId: call.id, name: call.name, content: JSON.stringify({ denied: true, reason }) });
+    yield emit(opts, { type: 'tool_denied', step, call, reason });
+}
+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":{...}}]}. The "input" object must match the tool's parameters schema. Available tools:\n${catalog}`,
+        },
+        ...messages.map(toPromptJsonMessage),
+    ];
+}
+function toPromptJsonMessage(message) {
+    if (message.role === 'tool') {
+        return {
+            role: 'user',
+            content: `Tool ${message.name ?? message.toolCallId ?? 'unknown'} returned: ${textContent(message.content)}`,
+        };
+    }
+    return {
+        role: message.role,
+        content: textContent(message.content),
+    };
+}
+/**
+ * Parses a promptJson tool directive into zero or more calls. Accepts the single
+ * form ({"tool","input"}), the batched form ({"tools":[...]}), and a bare array
+ * of directives, so a promptJson-mode model can request several tools per turn
+ * just like native tool-calling can. Malformed entries are skipped, not thrown.
+ */
+function callsFromPromptJson(text) {
+    const value = extractJson(text);
+    if (!value || typeof value !== 'object')
+        return [];
+    const entries = Array.isArray(value)
+        ? value
+        : Array.isArray(value.tools)
+            ? value.tools
+            : [value];
+    const calls = [];
+    for (const entry of entries) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            continue;
+        const record = entry;
+        if (typeof record.tool !== 'string')
+            continue;
+        calls.push({
+            id: randomId(),
+            name: record.tool,
+            arguments: record.input && typeof record.input === 'object' ? record.input : {},
+            raw: JSON.stringify(record.input ?? {}),
+        });
+    }
+    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;
+    if (!content)
+        return '';
+    return content.filter((part) => part.type === 'text').map((part) => part.text ?? '').join('\n');
+}
+function createAgentSignal(signal, deadlineMs) {
+    if (!signal && deadlineMs === undefined)
+        return { signal: undefined, timedOut: () => false, dispose: () => undefined };
+    const controller = new AbortController();
+    let didTimeOut = false;
+    let timer;
+    const onAbort = () => controller.abort(signal?.reason);
+    if (signal) {
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener('abort', onAbort, { once: true });
+    }
+    if (deadlineMs !== undefined) {
+        timer = setTimeout(() => {
+            didTimeOut = true;
+            controller.abort(new AIError(`Agent deadline exceeded after ${deadlineMs}ms`, { kind: 'budget_exceeded', retryable: false }));
+        }, deadlineMs);
+    }
+    return {
+        signal: controller.signal,
+        timedOut: () => didTimeOut,
+        dispose() {
+            if (timer)
+                clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+        },
+    };
+}
+//# sourceMappingURL=loop.js.map