@jxburros/ai-nugget 0.3.1 → 0.6.0

package/dist/adapters/engines/ollama.js

@@ -1,8 +1,10 @@
 import { AIError } from '../../errors.js';
 import { estimatedUsage } from '../../tokens.js';
 import { fetchJson, ndjsonLines, postResponse } from '../../transport.js';
-import { asNumber, asRecord, asString, textFromMessages } from '../../util.js';
-import { DEFAULT_TIMEOUT_MS, streamError, streamTimeout } from './base.js';
+import { applyProviderOptions, asNumber, asRecord, asString, joinUrl, mapWithConcurrency, textFromMessages } from '../../util.js';
+import { DEFAULT_TIMEOUT_MS, parseArgs, randomId, streamAnomaly, streamError, streamTimeout } from './base.js';
+/** Max concurrent /api/show probes when listing models — enough to be fast, few enough to be polite to a local daemon. */
+const SHOW_CONCURRENCY = 6;
 export class OllamaAdapter {
     provider;
     constructor(provider) {
@@ -27,14 +29,19 @@ export class OllamaAdapter {
         let inputTokens;
         let outputTokens;
         let doneReason;
+        let sawTerminal = false;
         const toolCalls = [];
         const timeout = streamTimeout(conn, req.signal);
         yield { type: 'start', callId: '', provider: conn.provider, model: req.model };
         try {
-            const res = await postResponse(`${conn.baseUrl}/api/chat`, body(req), conn.headers, timeout.signal, conn.provider);
+            const res = await postResponse(joinUrl(conn.baseUrl, '/api/chat'), body(req), conn.headers, timeout.signal, conn.provider);
             for await (const value of ndjsonLines(res)) {
+                timeout.bump();
                 const record = asRecord(value);
                 const message = asRecord(record?.message);
+                const thinking = asString(message?.thinking);
+                if (thinking)
+                    yield { type: 'reasoning', text: thinking };
                 const piece = asString(message?.content);
                 if (piece) {
                     if (firstTokenMs === null)
@@ -45,6 +52,8 @@ export class OllamaAdapter {
                 inputTokens = asNumber(record?.prompt_eval_count) ?? inputTokens;
                 outputTokens = asNumber(record?.eval_count) ?? outputTokens;
                 doneReason = asString(record?.done_reason) ?? doneReason;
+                if (record?.done === true)
+                    sawTerminal = true;
                 const calls = Array.isArray(message?.tool_calls) ? message.tool_calls : [];
                 for (const callValue of calls) {
                     const fn = asRecord(asRecord(callValue)?.function);
@@ -52,13 +61,18 @@ export class OllamaAdapter {
                     const toolCall = {
                         id: randomId(),
                         name: asString(fn?.name) ?? 'unknown',
-                        arguments: args,
+                        // Ollama itself sends a native object, but llama.cpp-style backends
+                        // behind the same protocol send a JSON *string* — coerce either into
+                        // the object `validateToolArgs` expects.
+                        arguments: parseArgs(args),
                         raw: typeof args === 'string' ? args : JSON.stringify(args),
                     };
                     toolCalls.push(toolCall);
                     yield { type: 'tool_call', call: toolCall };
                 }
             }
+            if (!sawTerminal)
+                yield streamAnomaly('NDJSON stream ended without a done record');
             const hasTools = toolCalls.length > 0;
             yield { type: 'done', result: {
                     text,
@@ -86,19 +100,39 @@ export class OllamaAdapter {
         });
         const models = Array.isArray(asRecord(data)?.models) ? asRecord(data).models : [];
         const ids = models.map((model) => asString(asRecord(model)?.name) ?? asString(asRecord(model)?.model) ?? '').filter(Boolean);
-        // Probe /api/show per model for context window + capabilities (best effort, sequential
-        // to avoid overwhelming a local Ollama instance).
-        const results = [];
-        for (const id of ids) {
+        // Probe /api/show per model for context window + capabilities (best effort),
+        // with bounded concurrency so a large model list resolves quickly without
+        // opening an unbounded number of sockets against a local daemon.
+        return mapWithConcurrency(ids, SHOW_CONCURRENCY, async (id) => {
             const info = { id, source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl } };
             const probed = await this.showModel(conn, id).catch(() => undefined);
             if (probed?.contextWindow !== undefined)
                 info.contextWindow = probed.contextWindow;
             if (probed?.capabilities)
                 info.capabilities = probed.capabilities;
-            results.push(info);
-        }
-        return results;
+            return info;
+        });
+    }
+    async embed(conn, req) {
+        const inputs = Array.isArray(req.input) ? req.input : [req.input];
+        const { data } = await fetchJson(joinUrl(conn.baseUrl, '/api/embed'), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...conn.headers },
+            body: JSON.stringify(applyProviderOptions({ model: req.model, input: inputs }, req.providerOptions)),
+            timeoutMs: conn.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            provider: conn.provider,
+        });
+        const record = asRecord(data);
+        const rows = Array.isArray(record?.embeddings) ? record.embeddings : [];
+        const embeddings = rows.map((row) => (Array.isArray(row) ? row.filter((n) => typeof n === 'number') : []));
+        const inputTokens = asNumber(record?.prompt_eval_count);
+        return {
+            embeddings,
+            model: req.model,
+            usage: { inputTokens, outputTokens: 0, estimated: inputTokens === undefined },
+            source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl },
+            raw: data,
+        };
     }
     async showModel(conn, model) {
         const { data } = await fetchJson(`${conn.baseUrl}/api/show`, {
@@ -130,7 +164,7 @@ export class OllamaAdapter {
     }
 }
 function body(req) {
-    return {
+    const base = {
         model: req.model,
         messages: req.messages.map(toOllamaMessage),
         stream: true,
@@ -138,6 +172,11 @@ function body(req) {
         format: req.responseFormat?.type === 'json' ? (req.responseFormat.schema ?? 'json') : undefined,
         tools: req.tools?.map((tool) => ({ type: 'function', function: { name: tool.name, description: tool.description, parameters: tool.parameters } })),
     };
+    // providerOptions reaches Ollama's real request fields — `options.num_ctx`,
+    // `options.num_keep`, top-level `keep_alive`, `think`, etc. `options` is
+    // merged one level deep so num_ctx joins the samplers above rather than
+    // replacing them.
+    return applyProviderOptions(base, req.providerOptions, ['options']);
 }
 function toOllamaMessage(m) {
     const images = typeof m.content === 'string' ? undefined : m.content.filter((part) => part.type === 'image').map((part) => part.imageBase64).filter(Boolean);
@@ -154,7 +193,4 @@ function toOllamaMessage(m) {
     }
     return message;
 }
-function randomId() {
-    return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
-}
 //# sourceMappingURL=ollama.js.map

package/dist/adapters/engines/openaiChat.d.ts

@@ -1,4 +1,4 @@
-import type { ChatRequest, ChatResult, ProviderAdapter, ResolvedConnection, StreamEvent } from '../../types.js';
+import type { ChatRequest, ChatResult, EmbedRequest, EmbedResult, ProviderAdapter, ResolvedConnection, StreamEvent } from '../../types.js';
 import type { ProviderProfile } from '../profiles.js';
 export declare class OpenAIChatAdapter implements ProviderAdapter {
     private profile;
@@ -11,5 +11,6 @@ export declare class OpenAIChatAdapter implements ProviderAdapter {
         ok: boolean;
         detail?: string;
     }>;
+    embed(conn: ResolvedConnection, req: EmbedRequest): Promise<EmbedResult>;
 }
 //# sourceMappingURL=openaiChat.d.ts.map

package/dist/adapters/engines/openaiChat.js

@@ -1,8 +1,8 @@
 import { AIError } from '../../errors.js';
 import { estimatedUsage } from '../../tokens.js';
-import { postResponse, sseLines } from '../../transport.js';
-import { asNumber, asRecord, asString, textFromMessages } from '../../util.js';
-import { health, listOpenModels, streamError, streamTimeout } from './base.js';
+import { fetchJson, postResponse, sseLines } from '../../transport.js';
+import { applyProviderOptions, asNumber, asRecord, asString, joinUrl, textFromMessages } from '../../util.js';
+import { DEFAULT_TIMEOUT_MS, health, listOpenModels, parseArgs, randomId, safeParse, streamAnomaly, streamError, streamTimeout } from './base.js';
 export class OpenAIChatAdapter {
     profile;
     provider;
@@ -34,7 +34,7 @@ export class OpenAIChatAdapter {
         const timeout = streamTimeout(conn, req.signal);
         yield { type: 'start', callId: '', provider: conn.provider, model: req.model };
         try {
-            const res = await postResponse(urlFor(conn, this.profile, req.model), openAiBody(req, this.profile), conn.headers, timeout.signal, conn.provider);
+            const res = await postResponse(urlFor(conn, this.profile, req), openAiBody(req, this.profile), conn.headers, timeout.signal, conn.provider);
             const contentType = res.headers.get('content-type') ?? '';
             if (!contentType.includes('text/event-stream')) {
                 // Server ignored stream:true (or is a buffered gateway) — recover the whole body.
@@ -47,6 +47,8 @@ export class OpenAIChatAdapter {
                 outputTokens = parsed.outputTokens;
                 finish = parsed.finish;
                 sawTerminal = true;
+                if (parsed.reasoning)
+                    yield { type: 'reasoning', text: parsed.reasoning };
                 if (text)
                     yield { type: 'delta', text };
                 for (const call of toolCalls)
@@ -55,6 +57,7 @@ export class OpenAIChatAdapter {
             else {
                 const partialTools = new Map();
                 for await (const line of sseLines(res)) {
+                    timeout.bump();
                     const chunk = safeParse(line);
                     const record = asRecord(chunk);
                     if (!record)
@@ -68,6 +71,11 @@ export class OpenAIChatAdapter {
                     if (choice?.finish_reason)
                         sawTerminal = true;
                     const delta = asRecord(choice?.delta);
+                    // Reasoning tokens (DeepSeek `reasoning_content`, others `reasoning`)
+                    // ride their own channel so they don't contaminate the answer text.
+                    const reasoning = asString(delta?.reasoning_content) ?? asString(delta?.reasoning);
+                    if (reasoning)
+                        yield { type: 'reasoning', text: reasoning };
                     const piece = asString(delta?.content);
                     if (piece) {
                         if (firstTokenMs === null)
@@ -96,9 +104,8 @@ export class OpenAIChatAdapter {
                 for (const call of toolCalls)
                     yield { type: 'tool_call', call };
             }
-            if (!sawTerminal) {
-                yield { type: 'context', kind: 'stream_anomaly', data: { reason: 'stream ended without a finish_reason' } };
-            }
+            if (!sawTerminal)
+                yield streamAnomaly('stream ended without a finish_reason');
             const result = makeResult(conn, req, text, toolCalls, finish, started, firstTokenMs, inputTokens, outputTokens);
             yield { type: 'done', result };
         }
@@ -115,6 +122,34 @@ export class OpenAIChatAdapter {
     health(conn) {
         return health(conn, this.profile);
     }
+    async embed(conn, req) {
+        const inputs = Array.isArray(req.input) ? req.input : [req.input];
+        const { data } = await fetchJson(joinUrl(conn.baseUrl, '/embeddings'), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...conn.headers },
+            body: JSON.stringify(applyProviderOptions({ model: req.model, input: inputs }, req.providerOptions)),
+            timeoutMs: conn.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            provider: conn.provider,
+        });
+        const record = asRecord(data);
+        const rows = Array.isArray(record?.data) ? record.data : [];
+        // Order by the `index` each row reports, falling back to array order.
+        const byIndex = rows
+            .map((row, i) => ({ index: asNumber(asRecord(row)?.index) ?? i, embedding: asEmbedding(asRecord(row)?.embedding) }))
+            .sort((a, b) => a.index - b.index);
+        const usage = asRecord(record?.usage);
+        const inputTokens = asNumber(usage?.prompt_tokens);
+        return {
+            embeddings: byIndex.map((row) => row.embedding),
+            model: req.model,
+            usage: { inputTokens, outputTokens: 0, estimated: inputTokens === undefined },
+            source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl },
+            raw: data,
+        };
+    }
+}
+function asEmbedding(value) {
+    return Array.isArray(value) ? value.filter((n) => typeof n === 'number') : [];
 }
 function openAiBody(req, profile) {
     const body = {
@@ -134,7 +169,12 @@ function openAiBody(req, profile) {
     };
     if (req.maxTokens !== undefined)
         body[profile.quirks?.maxTokensParam ?? 'max_tokens'] = req.maxTokens;
-    return body;
+    // providerOptions carries OpenAI-native fields the nugget doesn't model
+    // (`reasoning_effort`, `parallel_tool_calls`, `seed`, `logprobs`, …). `apiVersion`
+    // is consumed by urlFor for Azure and stripped here so it never hits the body.
+    const { apiVersion, ...passthrough } = req.providerOptions ?? {};
+    void apiVersion;
+    return applyProviderOptions(body, Object.keys(passthrough).length ? passthrough : undefined);
 }
 function responseFormatFor(req, profile) {
     if (req.responseFormat?.type !== 'json')
@@ -157,11 +197,18 @@ function toOpenAiMessage(message) {
         tool_calls: message.toolCalls?.map((call) => ({ id: call.id, type: 'function', function: { name: call.name, arguments: call.raw ?? JSON.stringify(call.arguments) } })),
     };
 }
-function urlFor(conn, profile, model) {
+function urlFor(conn, profile, req) {
     if (profile.quirks?.urlTemplate) {
-        return profile.quirks.urlTemplate.replace('{baseUrl}', conn.baseUrl).replace('{model}', encodeURIComponent(model));
+        // `{apiVersion}` (Azure) is filled from a per-call override, then the
+        // profile default — so a retired Azure api-version is fixable without a
+        // library release: pass `providerOptions: { apiVersion: '2025-01-01-preview' }`.
+        const apiVersion = asString(req.providerOptions?.apiVersion) ?? profile.quirks.apiVersion ?? '';
+        return profile.quirks.urlTemplate
+            .replace('{baseUrl}', conn.baseUrl)
+            .replace('{model}', encodeURIComponent(req.model))
+            .replace('{apiVersion}', apiVersion);
     }
-    return `${conn.baseUrl}/chat/completions`;
+    return joinUrl(conn.baseUrl, '/chat/completions');
 }
 function parseOpenAiResponse(raw) {
     const record = asRecord(raw);
@@ -169,9 +216,11 @@ function parseOpenAiResponse(raw) {
     const choice = asRecord(Array.isArray(record?.choices) ? record.choices[0] : undefined);
     const message = asRecord(choice?.message);
     const text = asString(message?.content) ?? asString(record?.text) ?? '';
+    const reasoning = asString(message?.reasoning_content) ?? asString(message?.reasoning);
     const calls = Array.isArray(message?.tool_calls) ? message.tool_calls : [];
     return {
         text,
+        reasoning,
         finish: asString(choice?.finish_reason),
         toolCalls: calls.map((value) => {
             const call = asRecord(value);
@@ -206,23 +255,4 @@ function mapFinish(finish, hasToolCalls) {
         return 'content_filter';
     return 'stop';
 }
-function parseArgs(raw) {
-    try {
-        return raw ? JSON.parse(raw) : {};
-    }
-    catch {
-        return {};
-    }
-}
-function safeParse(line) {
-    try {
-        return JSON.parse(line);
-    }
-    catch {
-        return undefined;
-    }
-}
-function randomId() {
-    return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
-}
 //# sourceMappingURL=openaiChat.js.map

package/dist/adapters/profiles.d.ts

@@ -32,11 +32,31 @@ export interface ProviderProfile {
         maxTokensRequired?: boolean;
         maxTokensParam?: 'max_tokens' | 'max_completion_tokens';
         supportsJsonSchema?: boolean;
+        /**
+         * Default value for the `{apiVersion}` token in `urlTemplate` (Azure OpenAI).
+         * Overridable per call via `ChatRequest.providerOptions.apiVersion`, so a
+         * retired Azure api-version never requires a library release.
+         */
+        apiVersion?: string;
+        /**
+         * Provider honors an `Idempotency-Key` request header. When set, the handler
+         * attaches one key per logical call and reuses it across retries, so a retry
+         * after a connection drops post-generation is deduped by the provider rather
+         * than billed twice. Left off unless the provider documents the header —
+         * sending an unknown header is harmless, but claiming the guarantee is not.
+         */
+        supportsIdempotencyKey?: boolean;
     };
     listModelsPath?: string;
     healthPath?: string;
 }
-export declare const PROVIDER_PROFILES: Record<string, ProviderProfile>;
+/**
+ * The provider keys that have a profile in {@link PROVIDER_PROFILES}. Used to
+ * type `Connection.provider` so IDEs autocomplete valid names and typos are a
+ * compile error rather than a silent fall-through to `openai-compat`.
+ */
+export type KnownProvider = 'openai' | 'azure-openai' | 'openrouter' | 'groq' | 'deepseek' | 'mistral' | 'together' | 'fireworks' | 'cerebras' | 'moonshot' | 'cohere' | 'perplexity' | 'lmstudio' | 'llamacpp' | 'vllm' | 'ollama' | 'anthropic' | 'google' | 'openai-compat';
+export declare const PROVIDER_PROFILES: Record<KnownProvider, ProviderProfile> & Record<string, ProviderProfile>;
 export declare function profileFor(provider: string, baseUrl?: string): ProviderProfile;
 export declare function applyAuth(profile: ProviderProfile, apiKey: string | null, headers: Record<string, string>): Record<string, string>;
 //# sourceMappingURL=profiles.d.ts.map

package/dist/adapters/profiles.js

@@ -7,13 +7,13 @@ export const PROVIDER_PROFILES = {
         auth: 'bearer',
         listModelsPath: '/models',
         capabilities: HOSTED_CLOUD,
-        quirks: { supportsUsageInStream: true, maxTokensParam: 'max_completion_tokens', supportsJsonSchema: true },
+        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=2024-10-21', maxTokensParam: 'max_completion_tokens', supportsJsonSchema: true },
+        quirks: { urlTemplate: '{baseUrl}/openai/deployments/{model}/chat/completions?api-version={apiVersion}', apiVersion: '2024-10-21', maxTokensParam: 'max_completion_tokens', supportsJsonSchema: true },
     },
     openrouter: {
         engine: 'openaiChat',
@@ -29,6 +29,12 @@ export const PROVIDER_PROFILES = {
     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',
@@ -86,6 +92,10 @@ export const PROVIDER_PROFILES = {
         // 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) {

package/dist/agent/loop.d.ts

@@ -1,5 +1,5 @@
 import type { AIHandler } from '../handler.js';
-import type { ChatMessage, Connection, StreamEvent, ToolCall, Usage } from '../types.js';
+import type { AIErrorKind, ChatMessage, Connection, StreamEvent, ToolCall, Usage } from '../types.js';
 import type { ToolSpec } from './tools.js';
 export interface AgentOptions {
     handler: AIHandler;
@@ -18,12 +18,43 @@ export interface AgentOptions {
      * 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>;
@@ -38,6 +69,9 @@ export type ApprovalGate = (req: {
 export type AgentEvent = StreamEvent | {
     type: 'step_start';
     step: number;
+} | {
+    type: 'tool_mode';
+    mode: 'native' | 'promptJson';
 } | {
     type: 'tool_start';
     step: number;
@@ -63,6 +97,14 @@ export interface AgentResult {
     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>;