@jxburros/ai-nugget 0.3.1

package/dist/agent/loop.js

@@ -0,0 +1,263 @@
+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 { 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;
+    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;
+            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,
+                signal: agentSignal.signal,
+                metadata: { ...opts.metadata, agentStep: step },
+            })) {
+                if (event.type === 'delta')
+                    stepText += event.text;
+                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);
+            }
+            // 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');
+            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;
+                if (tool.sideEffects) {
+                    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 {
+                    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 });
+                }
+                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 result = makeResult(finalText, messages, usage ?? { estimated: true }, step, agentSignal.timedOut() ? 'deadline' : (agentSignal.signal?.aborted || (error instanceof AIError && error.kind === 'canceled')) ? 'canceled' : 'error');
+        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) {
+        const result = makeResult(finalText, messages, usage ?? { estimated: true }, step, stopReason);
+        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) {
+    return { finalText, messages, usage, steps, stopReason };
+}
+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;
+    return profileFor(opts.connection.provider, opts.connection.baseUrl).capabilities.nativeTools ? 'native' : 'promptJson';
+}
+function withPromptJsonInstruction(messages, tools) {
+    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('; ')}`,
+        },
+        ...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: crypto.randomUUID(),
+            name: record.tool,
+            arguments: record.input && typeof record.input === 'object' ? record.input : {},
+            raw: JSON.stringify(record.input ?? {}),
+        });
+    }
+    return calls;
+}
+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

package/dist/agent/tools.d.ts

@@ -0,0 +1,29 @@
+import type { ToolCall, ToolSchema } from '../types.js';
+export interface ToolSpec<A = unknown, R = unknown> extends ToolSchema {
+    sideEffects?: boolean;
+    execute(args: A, ctx: ToolContext): Promise<R> | R;
+}
+export interface ToolContext {
+    signal: AbortSignal;
+    callId: string;
+    step: number;
+    metadata?: Record<string, unknown>;
+}
+export declare function defineTool<A, R>(spec: ToolSpec<A, R>): ToolSpec<A, R>;
+/**
+ * Light validation only: object-ness, `required` presence, and top-level
+ * `properties[key].type` against JS typeof/Array.isArray/Number.isInteger.
+ * It does not implement full JSON Schema — no `enum`, nested `properties`,
+ * `oneOf`/`anyOf`, numeric bounds, string `pattern`, array `items` schemas, or
+ * `additionalProperties`. That's intentional for a zero-dependency nugget; a
+ * caller that needs stricter guarantees should validate `args` again inside
+ * `tool.execute` with its own schema library.
+ */
+export declare function validateToolArgs(tool: ToolSpec, call: ToolCall): {
+    ok: true;
+    args: unknown;
+} | {
+    ok: false;
+    message: string;
+};
+//# sourceMappingURL=tools.d.ts.map

package/dist/agent/tools.js

@@ -0,0 +1,48 @@
+export function defineTool(spec) {
+    return spec;
+}
+/**
+ * Light validation only: object-ness, `required` presence, and top-level
+ * `properties[key].type` against JS typeof/Array.isArray/Number.isInteger.
+ * It does not implement full JSON Schema — no `enum`, nested `properties`,
+ * `oneOf`/`anyOf`, numeric bounds, string `pattern`, array `items` schemas, or
+ * `additionalProperties`. That's intentional for a zero-dependency nugget; a
+ * caller that needs stricter guarantees should validate `args` again inside
+ * `tool.execute` with its own schema library.
+ */
+export function validateToolArgs(tool, call) {
+    const schema = tool.parameters;
+    if (schema.type && schema.type !== 'object')
+        return { ok: false, message: `Tool ${tool.name} parameters must be an object schema` };
+    if (typeof call.arguments !== 'object' || call.arguments === null || Array.isArray(call.arguments)) {
+        return { ok: false, message: `Tool ${tool.name} expected object arguments` };
+    }
+    const args = call.arguments;
+    const required = Array.isArray(schema.required) ? schema.required.filter((key) => typeof key === 'string') : [];
+    for (const key of required) {
+        if (!(key in args))
+            return { ok: false, message: `Tool ${tool.name} missing required argument: ${key}` };
+    }
+    const properties = schema.properties && typeof schema.properties === 'object' ? schema.properties : {};
+    for (const [key, spec] of Object.entries(properties)) {
+        if (!(key in args) || spec.type === undefined)
+            continue;
+        const value = args[key];
+        const ok = matchesType(value, spec.type);
+        if (!ok)
+            return { ok: false, message: `Tool ${tool.name} argument ${key} must be ${spec.type}` };
+    }
+    return { ok: true, args };
+}
+function matchesType(value, type) {
+    if (type === 'array')
+        return Array.isArray(value);
+    if (type === 'integer')
+        return typeof value === 'number' && Number.isInteger(value);
+    if (type === 'null')
+        return value === null;
+    if (type === 'object')
+        return typeof value === 'object' && value !== null && !Array.isArray(value);
+    return typeof value === type;
+}
+//# sourceMappingURL=tools.js.map

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+import type { AIErrorKind } from './types.js';
+export declare class AIError extends Error {
+    kind: AIErrorKind;
+    status?: number;
+    retryable: boolean;
+    provider?: string;
+    raw?: string;
+    retryAfterMs?: number;
+    constructor(message: string, opts: {
+        kind: AIErrorKind;
+        status?: number;
+        retryable?: boolean;
+        provider?: string;
+        raw?: string;
+        retryAfterMs?: number;
+        cause?: unknown;
+    });
+}
+export declare function defaultRetryable(kind: AIErrorKind): boolean;
+export declare function classify(status: number, body?: string, provider?: string, headers?: Headers): AIError;
+export declare function fromUnknown(error: unknown, provider?: string): AIError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,80 @@
+export class AIError extends Error {
+    kind;
+    status;
+    retryable;
+    provider;
+    raw;
+    retryAfterMs;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'AIError';
+        this.kind = opts.kind;
+        this.retryable = opts.retryable ?? defaultRetryable(opts.kind);
+        if (opts.status !== undefined)
+            this.status = opts.status;
+        if (opts.provider !== undefined)
+            this.provider = opts.provider;
+        if (opts.raw !== undefined)
+            this.raw = opts.raw;
+        if (opts.retryAfterMs !== undefined)
+            this.retryAfterMs = opts.retryAfterMs;
+        if (opts.cause !== undefined)
+            this.cause = opts.cause;
+    }
+}
+export function defaultRetryable(kind) {
+    return kind === 'rate_limit' || kind === 'timeout' || kind === 'network' || kind === 'server' || kind === 'invalid_response';
+}
+export function classify(status, body = '', provider, headers) {
+    const excerpt = body.slice(0, 200);
+    const lower = body.toLowerCase();
+    let kind = 'server';
+    if (status === 401 || status === 403)
+        kind = 'auth';
+    else if (status === 408)
+        kind = 'timeout';
+    else if (status === 429)
+        kind = 'rate_limit';
+    else if (status === 400 || status === 422) {
+        kind = lower.includes('context') || lower.includes('maximum context') || lower.includes('token limit')
+            ? 'context_length'
+            : 'invalid_request';
+    }
+    else if (status >= 500)
+        kind = 'server';
+    else
+        kind = 'invalid_request';
+    return new AIError(`HTTP ${status}: ${excerpt}`, {
+        kind,
+        status,
+        provider,
+        raw: excerpt,
+        retryAfterMs: parseRetryAfter(headers?.get('retry-after') ?? null),
+    });
+}
+export function fromUnknown(error, provider) {
+    if (error instanceof AIError)
+        return error;
+    if (error instanceof DOMException && error.name === 'AbortError') {
+        return new AIError('Request was canceled', { kind: 'canceled', retryable: false, provider, cause: error });
+    }
+    if (error instanceof Error && /timeout|timed out/i.test(error.message)) {
+        return new AIError(error.message, { kind: 'timeout', provider, cause: error });
+    }
+    if (error instanceof Error) {
+        return new AIError(error.message, { kind: 'network', provider, cause: error });
+    }
+    return new AIError('Unknown AI provider error', { kind: 'network', provider, cause: error });
+}
+function parseRetryAfter(value) {
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds * 1000);
+    const time = Date.parse(value);
+    if (!Number.isNaN(time))
+        return Math.max(0, time - Date.now());
+    return undefined;
+}
+//# sourceMappingURL=errors.js.map

package/dist/handler.d.ts

@@ -0,0 +1,48 @@
+import type { CallInfo, CallRecord, ChatRequest, ChatResult, Connection, GovernancePolicy, KeySource, ModelInfo, Redactor, StreamEvent, TelemetrySink } from './types.js';
+export interface HandlerOptions {
+    keySource: KeySource;
+    policy?: GovernancePolicy;
+    redactor?: Redactor;
+    telemetry?: TelemetrySink;
+    hooks?: {
+        beforeCall?(info: CallInfo): Promise<void | 'deny'>;
+        afterCall?(record: CallRecord): Promise<void>;
+    };
+    retry?: {
+        maxAttempts?: number;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+    };
+    limits?: {
+        maxConcurrent?: number;
+        minIntervalMs?: number;
+    };
+}
+export declare class AIHandler {
+    private opts;
+    private active;
+    private queue;
+    private lastStarted;
+    private sessionRedactor;
+    private policy;
+    constructor(opts: HandlerOptions);
+    chat(conn: Connection, req: ChatRequest): Promise<ChatResult>;
+    stream(conn: Connection, req: ChatRequest): AsyncIterable<StreamEvent>;
+    listModels(conn: Connection): Promise<ModelInfo[]>;
+    testConnection(conn: Connection): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    private runProbe;
+    private resolveConnection;
+    private acquire;
+    private release;
+    private retryDelay;
+    private recordSuccess;
+    private recordFailure;
+    private record;
+    private redact;
+    private redactedError;
+    private redactedCause;
+}
+//# sourceMappingURL=handler.d.ts.map