@jxburros/ai-nugget 0.4.1 → 0.7.0

package/nugget/src/redact.ts

@@ -1,6 +1,10 @@
 import type { Redactor } from './types.js';
 
-const SECRET_PATTERNS: RegExp[] = [
+/**
+ * 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: RegExp[] = [
   /sk-[A-Za-z0-9_-]{20,}/g,
   /sk-proj-[A-Za-z0-9_-]{20,}/g,
   /sk-ant-[A-Za-z0-9_-]{20,}/g,
@@ -23,12 +27,39 @@ const SECRET_PATTERNS: RegExp[] = [
   /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: RegExp[] = [
+  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: Iterable<string> = []): Redactor {
   const secrets = new Set([...extraSecrets].filter((value) => value.length >= 6));
   return {
     redact(text: string): string {
       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: string, separator: string, quote: string) => `${label}${separator}${quote}[REDACTED]${quote}`);
+      }
       for (const secret of secrets) output = output.split(secret).join('[REDACTED]');
       return output;
     },

package/nugget/src/transport.ts

@@ -1,9 +1,11 @@
 import { AIError, classify, fromUnknown } from './errors.js';
 
-export function withTimeout(ms: number, external?: AbortSignal): {
+export 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;
 } {
   const controller = new AbortController();
   let didTimeOut = false;
@@ -11,20 +13,37 @@ export function withTimeout(ms: number, external?: AbortSignal): {
     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: ReturnType<typeof setTimeout> | undefined;
+  const armIdle = (): void => {
+    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) onAbort();
     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();
+    },
   };
 }
 

package/nugget/src/types.ts

@@ -1,3 +1,7 @@
+import type { KnownProvider } from './adapters/profiles.js';
+
+export type { KnownProvider };
+
 export type Role = 'system' | 'user' | 'assistant' | 'tool';
 
 export interface ContentPart {
@@ -29,27 +33,69 @@ export interface ToolSchema {
   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' } | { type: 'json'; schema?: object };
   tools?: ToolSchema[];
   toolChoice?: 'auto' | 'none' | { name: string };
   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 =
@@ -95,6 +141,25 @@ export interface ModelSource {
   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 function modelRef(source: ModelSource, model: string): string {
   return `${source.provider}/${model}`;
 }
@@ -107,6 +172,8 @@ export type AIErrorKind =
   | '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'
@@ -117,6 +184,11 @@ export type AIErrorKind =
 export type StreamEvent =
   | { type: 'start'; callId: string; provider: string; model: string }
   | { type: 'delta'; text: string }
+  // Reasoning/thinking tokens surfaced as their own channel so callers can show
+  // or discard them without them polluting `delta` (the user-facing answer).
+  // Emitted from Anthropic `thinking_delta` and OpenAI-compat `reasoning`/
+  // `reasoning_content` deltas; providers that don't stream reasoning never emit it.
+  | { type: 'reasoning'; text: string }
   | { type: 'tool_call'; call: ToolCall }
   | { type: 'context'; kind: string; data: unknown }
   | { type: 'retry'; attempt: number; reason: AIErrorKind; delayMs: number }
@@ -129,6 +201,7 @@ export interface ProviderAdapter {
   stream(conn: ResolvedConnection, req: ChatRequest): AsyncIterable<StreamEvent>;
   listModels?(conn: ResolvedConnection): Promise<ModelInfo[]>;
   health?(conn: ResolvedConnection): Promise<{ ok: boolean; detail?: string }>;
+  embed?(conn: ResolvedConnection, req: EmbedRequest): Promise<EmbedResult>;
 }
 
 export interface ModelInfo {
@@ -156,6 +229,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 {
@@ -172,4 +254,34 @@ 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;
 }

package/nugget/src/util.ts

@@ -31,6 +31,56 @@ export function globalEnv(): Record<string, string | undefined> {
   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: Record<string, unknown>,
+  providerOptions: Record<string, unknown> | undefined,
+  nestedKeys: readonly string[] = [],
+): Record<string, unknown> {
+  if (!providerOptions) return body;
+  const merged: Record<string, unknown> = { ...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 as Record<string, unknown>) };
+    } 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: string, path: string): string {
+  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<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]> {
+  const results = new Array<R>(items.length);
+  let next = 0;
+  const workerCount = Math.max(1, Math.min(limit, items.length));
+  const worker = async (): Promise<void> => {
+    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: number, signal?: AbortSignal): Promise<void> {
   if (ms <= 0) return Promise.resolve();
   return new Promise((resolve, reject) => {
@@ -54,3 +104,17 @@ export 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 const REASONING_BUDGET_TOKENS: Record<'none' | 'minimal' | 'low' | 'medium' | 'high', number> = {
+  none: 0,
+  minimal: 1024,
+  low: 2048,
+  medium: 8192,
+  high: 16384,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxburros/ai-nugget",
-  "version": "0.4.1",
+  "version": "0.7.0",
   "private": false,
   "type": "module",
   "description": "Small isomorphic AI model nugget for provider calls, policy, redaction, telemetry, and agent loops.",
@@ -34,37 +34,50 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
+      "require": "./dist/cjs/index.js",
       "default": "./dist/index.js"
     },
     "./agent": {
       "types": "./dist/agent/index.d.ts",
       "import": "./dist/agent/index.js",
+      "require": "./dist/cjs/agent/index.js",
       "default": "./dist/agent/index.js"
     }
   },
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
+    "dist/cjs/package.json",
     "nugget",
     "README.md",
+    "UPGRADING.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/finalize-cjs.mjs",
     "test": "vitest run",
     "test:browser": "vitest run --config vitest.browser.config.ts",
     "test:live": "vitest run tests/live-smoke.test.ts",
+    "test:coverage": "vitest run --coverage",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
     "build:nugget": "node scripts/build-nugget.mjs",
     "demo:steel-chat": "npm run build && node examples/steel-chat/server.mjs",
     "prepublishOnly": "npm run build && npm run build:nugget"
   },
   "devDependencies": {
     "@types/node": "^22.15.21",
-    "@vitest/browser": "^4.1.9",
-    "@vitest/browser-playwright": "^4.1.9",
+    "@vitest/browser": "^4.1.10",
+    "@vitest/browser-playwright": "^4.1.10",
+    "@vitest/coverage-v8": "^4.1.10",
+    "eslint": "^9.18.0",
     "playwright": "^1.61.1",
     "typescript": "^5.8.3",
-    "vitest": "^4.1.5"
+    "typescript-eslint": "^8.21.0",
+    "vitest": "^4.1.10"
+  },
+  "overrides": {
+    "nanoid": "^3.3.17",
+    "postcss": "^8.5.23"
   }
 }