@jxburros/ai-nugget 0.4.1 → 0.7.0

package/dist/redact.js

@@ -1,4 +1,8 @@
-const SECRET_PATTERNS = [
+/**
+ * Prefixed secret formats. Each pattern is anchored on a vendor prefix that is
+ * distinctive enough that a match is a secret, not a coincidence.
+ */
+export const SECRET_PATTERNS = [
     /sk-[A-Za-z0-9_-]{20,}/g,
     /sk-proj-[A-Za-z0-9_-]{20,}/g,
     /sk-ant-[A-Za-z0-9_-]{20,}/g,
@@ -20,6 +24,27 @@ const SECRET_PATTERNS = [
     /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
     /eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g,
 ];
+/**
+ * Unprefixed/opaque secrets — Azure OpenAI `api-key` values, AWS *secret*
+ * access keys, generic bearer/session tokens — carry no distinctive prefix, so
+ * matching them on shape alone would redact commit SHAs, content hashes, and
+ * base64 payloads. These patterns instead anchor on the *label* that precedes
+ * the value (`api-key: …`, `"aws_secret_access_key": "…"`, `password=…`) and
+ * redact only the value, keeping the label readable in logs.
+ *
+ * Exact-match registration (`SessionRedactor.addSecret`, which the handler does
+ * for every resolved key) remains the only guaranteed catch for a bare,
+ * unlabeled, unprefixed secret.
+ */
+export const LABELED_SECRET_PATTERNS = [
+    new RegExp(
+    // Lookbehind rather than `\b` so an underscore-joined prefix still matches
+    // the label (`aws_secret_access_key`, `azure_api_key`).
+    String.raw `(?<![A-Za-z0-9])(api[_-]?key|apikey|secret[_-]?access[_-]?key|access[_-]?token|auth[_-]?token|session[_-]?token|client[_-]?secret|refresh[_-]?token|private[_-]?key|password|passwd)` +
+        // Optional closing quote handles JSON keys (`"api_key": "…"`).
+        String.raw `(["']?\s*[:=]\s*|\s+)` +
+        String.raw `(["']?)([A-Za-z0-9/+_.~-]{16,}={0,2})\3`, 'gi'),
+];
 export function createDefaultRedactor(extraSecrets = []) {
     const secrets = new Set([...extraSecrets].filter((value) => value.length >= 6));
     return {
@@ -27,6 +52,9 @@ export function createDefaultRedactor(extraSecrets = []) {
             let output = text;
             for (const pattern of SECRET_PATTERNS)
                 output = output.replace(pattern, '[REDACTED]');
+            for (const pattern of LABELED_SECRET_PATTERNS) {
+                output = output.replace(pattern, (_match, label, separator, quote) => `${label}${separator}${quote}[REDACTED]${quote}`);
+            }
             for (const secret of secrets)
                 output = output.split(secret).join('[REDACTED]');
             return output;

package/dist/transport.d.ts

@@ -1,7 +1,9 @@
-export declare function withTimeout(ms: number, external?: AbortSignal): {
+export declare function withTimeout(ms: number, external?: AbortSignal, idleMs?: number): {
     signal: AbortSignal;
     done(): void;
     timedOut(): boolean;
+    /** Reset the idle timer. No-op unless `idleMs` was supplied. Call on each chunk. */
+    bump(): void;
 };
 export declare function fetchJson(url: string, init: RequestInit & {
     timeoutMs: number;

package/dist/transport.js

@@ -1,11 +1,25 @@
 import { AIError, classify, fromUnknown } from './errors.js';
-export function withTimeout(ms, external) {
+export function withTimeout(ms, external, idleMs) {
     const controller = new AbortController();
     let didTimeOut = false;
     const timer = setTimeout(() => {
         didTimeOut = true;
         controller.abort(new AIError(`Request timed out after ${ms}ms`, { kind: 'timeout' }));
     }, ms);
+    // Optional idle timeout: aborts only when no chunk has arrived for `idleMs`,
+    // rearmed on every `bump()`. Keeps a long but healthy stream alive while the
+    // total `ms` ceiling still bounds a truly stuck call.
+    let idleTimer;
+    const armIdle = () => {
+        if (idleMs === undefined)
+            return;
+        if (idleTimer)
+            clearTimeout(idleTimer);
+        idleTimer = setTimeout(() => {
+            didTimeOut = true;
+            controller.abort(new AIError(`Request idle for ${idleMs}ms`, { kind: 'timeout' }));
+        }, idleMs);
+    };
     const onAbort = () => controller.abort(external?.reason);
     if (external) {
         if (external.aborted)
@@ -13,15 +27,21 @@ export function withTimeout(ms, external) {
         else
             external.addEventListener('abort', onAbort, { once: true });
     }
+    armIdle();
     return {
         signal: controller.signal,
         done() {
             clearTimeout(timer);
+            if (idleTimer)
+                clearTimeout(idleTimer);
             external?.removeEventListener('abort', onAbort);
         },
         timedOut() {
             return didTimeOut;
         },
+        bump() {
+            armIdle();
+        },
     };
 }
 export async function fetchJson(url, init) {

package/dist/types.d.ts

@@ -1,3 +1,5 @@
+import type { KnownProvider } from './adapters/profiles.js';
+export type { KnownProvider };
 export type Role = 'system' | 'user' | 'assistant' | 'tool';
 export interface ContentPart {
     type: 'text' | 'image';
@@ -23,12 +25,28 @@ export interface ToolSchema {
     description: string;
     parameters: object;
 }
+/**
+ * How hard a reasoning-capable model should think before answering. The nugget
+ * maps one vocabulary onto each provider's own knob (see `docs/providers.md`,
+ * "Reasoning effort"): OpenAI `reasoning_effort`, Anthropic `thinking`
+ * (`budget_tokens` tiers), Google `generationConfig.thinkingConfig.thinkingBudget`,
+ * Ollama `think`. `'none'` disables reasoning where the provider allows it.
+ * Unset means the provider's own default — the nugget never sends the knob
+ * unasked, because non-reasoning models reject it.
+ */
+export type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high';
 export interface ChatRequest {
     model: string;
     messages: ChatMessage[];
     temperature?: number;
     maxTokens?: number;
     topP?: number;
+    /**
+     * Reasoning effort for thinking-capable models — see {@link ReasoningEffort}.
+     * A provider-native value in `providerOptions` (e.g. `reasoning_effort`,
+     * `thinking`, `thinkingConfig`, `think`) wins over this on collision.
+     */
+    reasoningEffort?: ReasoningEffort;
     responseFormat?: {
         type: 'text';
     } | {
@@ -42,14 +60,39 @@ export interface ChatRequest {
     stopSequences?: string[];
     signal?: AbortSignal;
     metadata?: Record<string, unknown>;
+    /**
+     * Provider-native request fields the nugget does not model as first-class
+     * options — an escape hatch so a caller can reach a capability without waiting
+     * for a library release. Merged into the outgoing provider request body:
+     * shallow at the top level, and one level deep into the provider's own nested
+     * option container (Ollama `options`, Google `generationConfig`). Examples:
+     * `{ options: { num_ctx: 8192 }, keep_alive: '30m' }` (Ollama),
+     * `{ reasoning_effort: 'high' }` (OpenAI), `{ thinking: { type: 'enabled' } }`
+     * (Anthropic), `{ safetySettings: [...] }` (Google). Values here win over the
+     * nugget's own fields on a key collision, so use with care.
+     */
+    providerOptions?: Record<string, unknown>;
 }
 export interface Connection {
     id: string;
-    provider: string;
+    /**
+     * A provider with a profile in the table, or any other string — an unknown
+     * key with a `baseUrl` resolves through the `openai-compat` escape hatch.
+     * The union is there for autocomplete and typo-catching; the `string & {}`
+     * arm keeps the escape hatch open.
+     */
+    provider: KnownProvider | (string & {});
     baseUrl?: string;
     keyRef?: KeyRef;
     timeoutMs?: number;
     headers?: Record<string, string>;
+    /**
+     * Idle timeout for streaming calls: aborts the stream only if no bytes arrive
+     * for this many milliseconds, resetting on every chunk. Distinct from
+     * `timeoutMs`, which bounds the total call lifetime. Set this (and a generous
+     * `timeoutMs`) for long local generations that stream slowly but healthily.
+     */
+    idleTimeoutMs?: number;
 }
 export type KeyRef = {
     kind: 'none';
@@ -103,8 +146,27 @@ export interface ModelSource {
     connectionId: string;
     baseUrl?: string;
 }
+export interface EmbedRequest {
+    model: string;
+    /** One string, or a batch of strings embedded in a single call. */
+    input: string | string[];
+    signal?: AbortSignal;
+    metadata?: Record<string, unknown>;
+    /** Provider-native passthrough, same contract as {@link ChatRequest.providerOptions}. */
+    providerOptions?: Record<string, unknown>;
+}
+export interface EmbedResult {
+    /** One vector per input, in input order. */
+    embeddings: number[][];
+    model: string;
+    usage: Usage;
+    source: ModelSource;
+    raw?: unknown;
+}
 export declare function modelRef(source: ModelSource, model: string): string;
-export type AIErrorKind = 'auth' | 'rate_limit' | 'timeout' | 'network' | 'server' | 'invalid_request' | 'invalid_response' | 'context_length' | 'canceled' | 'policy_blocked' | 'key_unavailable' | 'tool_error' | 'budget_exceeded';
+export type AIErrorKind = 'auth' | 'rate_limit' | 'timeout' | 'network' | 'server' | 'invalid_request' | 'invalid_response'
+/** 404/410 — endpoint, deployment, or model not found (wrong baseUrl/model, or a misrouted edge). */
+ | 'not_found' | 'context_length' | 'canceled' | 'policy_blocked' | 'key_unavailable' | 'tool_error' | 'budget_exceeded';
 export type StreamEvent = {
     type: 'start';
     callId: string;
@@ -113,6 +175,9 @@ export type StreamEvent = {
 } | {
     type: 'delta';
     text: string;
+} | {
+    type: 'reasoning';
+    text: string;
 } | {
     type: 'tool_call';
     call: ToolCall;
@@ -141,6 +206,7 @@ export interface ProviderAdapter {
         ok: boolean;
         detail?: string;
     }>;
+    embed?(conn: ResolvedConnection, req: EmbedRequest): Promise<EmbedResult>;
 }
 export interface ModelInfo {
     id: string;
@@ -168,6 +234,15 @@ export interface CallInfo {
     provider: string;
     model: string;
     metadata?: Record<string, unknown>;
+    /**
+     * The fully resolved connection for this call — base URL defaulted from the
+     * provider profile and auth headers applied. Present whenever `beforeCall`
+     * runs after resolution (chat/stream and probes), letting a hook validate the
+     * *effective* endpoint (e.g. a request-time SSRF/DNS-rebinding re-check on the
+     * resolved `baseUrl`) without duplicating profile logic. The resolved
+     * `apiKey` is intentionally not exposed here.
+     */
+    resolved?: Omit<ResolvedConnection, 'apiKey'>;
 }
 export interface CallRecord {
     callId: string;
@@ -187,5 +262,40 @@ export interface CallRecord {
     metadata?: Record<string, unknown>;
     promptChars: number;
     responseChars: number;
+    /**
+     * Estimated cost of this call in USD, computed by the optional `pricing` hook
+     * passed to the handler. Undefined when no pricing hook is configured or the
+     * hook returns nothing for this provider/model.
+     */
+    costUsd?: number;
+}
+/**
+ * Minimal [Standard Schema](https://standardschema.dev) validator surface. Any
+ * Zod / Valibot / ArkType schema (v1+) satisfies this via its `~standard`
+ * property, so `chatParsed` can validate model output against a schema the app
+ * already owns — with zero dependency added to this library.
+ */
+export interface StandardSchemaV1<Output = unknown> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+    };
+}
+export type StandardSchemaResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<{
+        readonly message: string;
+        readonly path?: ReadonlyArray<PropertyKey | {
+            readonly key: PropertyKey;
+        }>;
+    }>;
+};
+/** Output of {@link AIHandler.chatParsed}: the validated value plus the raw chat result. */
+export interface ParsedResult<T> {
+    data: T;
+    result: ChatResult;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/util.d.ts

@@ -5,5 +5,27 @@ export declare function asNumber(value: unknown): number | undefined;
 export declare function promptChars(messages: ChatMessage[]): number;
 export declare function textFromMessages(messages: ChatMessage[]): string;
 export declare function globalEnv(): Record<string, string | undefined>;
+/**
+ * Merges app-supplied {@link ChatRequest.providerOptions} into a provider
+ * request body: shallow at the top level, and one level deep for each key in
+ * `nestedKeys` where both sides are plain objects (Ollama `options`, Google
+ * `generationConfig`). Values in `providerOptions` win on collision.
+ */
+export declare function applyProviderOptions(body: Record<string, unknown>, providerOptions: Record<string, unknown> | undefined, nestedKeys?: readonly string[]): Record<string, unknown>;
+/** Joins a base URL and path without producing a double slash, even if `base` ends with `/`. */
+export declare function joinUrl(base: string, path: string): string;
+/**
+ * Runs `fn` over `items` with at most `limit` in flight at once, preserving
+ * input order in the returned array. Used to probe many local models
+ * concurrently without opening an unbounded number of sockets.
+ */
+export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
 export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Token budgets behind the {@link ReasoningEffort} tiers for providers that
+ * express effort as a thinking-token budget (Anthropic `budget_tokens`, Google
+ * `thinkingBudget`). `'none'` is 0. Deliberately conservative: they are floors
+ * a model may stop under, not ceilings it fills.
+ */
+export declare const REASONING_BUDGET_TOKENS: Record<'none' | 'minimal' | 'low' | 'medium' | 'high', number>;
 //# sourceMappingURL=util.d.ts.map

package/dist/util.js

@@ -25,6 +25,52 @@ export function globalEnv() {
     const maybeProcess = globalThis;
     return maybeProcess.process?.env ?? {};
 }
+/**
+ * Merges app-supplied {@link ChatRequest.providerOptions} into a provider
+ * request body: shallow at the top level, and one level deep for each key in
+ * `nestedKeys` where both sides are plain objects (Ollama `options`, Google
+ * `generationConfig`). Values in `providerOptions` win on collision.
+ */
+export function applyProviderOptions(body, providerOptions, nestedKeys = []) {
+    if (!providerOptions)
+        return body;
+    const merged = { ...body };
+    for (const [key, value] of Object.entries(providerOptions)) {
+        const base = asRecord(merged[key]);
+        if (nestedKeys.includes(key) && base && asRecord(value)) {
+            merged[key] = { ...base, ...value };
+        }
+        else {
+            merged[key] = value;
+        }
+    }
+    return merged;
+}
+/** Joins a base URL and path without producing a double slash, even if `base` ends with `/`. */
+export function joinUrl(base, path) {
+    return `${base.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
+}
+/**
+ * Runs `fn` over `items` with at most `limit` in flight at once, preserving
+ * input order in the returned array. Used to probe many local models
+ * concurrently without opening an unbounded number of sockets.
+ */
+export async function mapWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const workerCount = Math.max(1, Math.min(limit, items.length));
+    const worker = async () => {
+        for (;;) {
+            const index = next;
+            next += 1;
+            if (index >= items.length)
+                return;
+            results[index] = await fn(items[index], index);
+        }
+    };
+    await Promise.all(Array.from({ length: workerCount }, worker));
+    return results;
+}
 export function sleep(ms, signal) {
     if (ms <= 0)
         return Promise.resolve();
@@ -52,4 +98,17 @@ export function sleep(ms, signal) {
         }
     });
 }
+/**
+ * Token budgets behind the {@link ReasoningEffort} tiers for providers that
+ * express effort as a thinking-token budget (Anthropic `budget_tokens`, Google
+ * `thinkingBudget`). `'none'` is 0. Deliberately conservative: they are floors
+ * a model may stop under, not ceilings it fills.
+ */
+export const REASONING_BUDGET_TOKENS = {
+    none: 0,
+    minimal: 1024,
+    low: 2048,
+    medium: 8192,
+    high: 16384,
+};
 //# sourceMappingURL=util.js.map

package/nugget/VERSION.txt

@@ -1,2 +1,2 @@
-0.4.1
-4dec12bfcf23c8282cd488a90048ea2a96247d16b84140fad709a3b976ce71e9
+0.7.0
+e0e4c28d06eb5e7474c628652e1c56fa5f29ce41c24428270895d7af3b8cd75e

package/nugget/dist/adapters/engines/anthropic.d.ts

@@ -0,0 +1,14 @@
+import type { ChatRequest, ChatResult, ModelInfo, ProviderAdapter, ResolvedConnection, StreamEvent } from '../../types.js';
+export declare class AnthropicAdapter implements ProviderAdapter {
+    readonly provider: string;
+    constructor(provider: string);
+    chat(conn: ResolvedConnection, req: ChatRequest): Promise<ChatResult>;
+    stream(conn: ResolvedConnection, req: ChatRequest): AsyncIterable<StreamEvent>;
+    /**
+     * 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.
+     */
+    listModels(conn: ResolvedConnection): Promise<ModelInfo[]>;
+}
+//# sourceMappingURL=anthropic.d.ts.map

package/nugget/dist/adapters/engines/anthropic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.d.ts","sourceRoot":"","sources":["../../../src/adapters/engines/anthropic.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAe,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,eAAe,EAAE,kBAAkB,EAAE,WAAW,EAAY,MAAM,gBAAgB,CAAC;AAMlJ,qBAAa,gBAAiB,YAAW,eAAe;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBACd,QAAQ,EAAE,MAAM;IAItB,IAAI,CAAC,IAAI,EAAE,kBAAkB,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAUpE,MAAM,CAAC,IAAI,EAAE,kBAAkB,EAAE,GAAG,EAAE,WAAW,GAAG,aAAa,CAAC,WAAW,CAAC;IA2HrF;;;;OAIG;IACG,UAAU,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;CAajE"}