@jxburros/ai-nugget 0.3.1 → 0.6.0

package/nugget/src/handler.ts

@@ -1,6 +1,7 @@
 import { adapterFor } from './adapters/index.js';
 import { applyAuth, profileFor } from './adapters/profiles.js';
 import { AIError, fromUnknown } from './errors.js';
+import { extractJson } from './json.js';
 import { allowAllPolicy } from './policy.js';
 import { SessionRedactor } from './redact.js';
 import type {
@@ -9,13 +10,18 @@ import type {
   ChatRequest,
   ChatResult,
   Connection,
+  EmbedRequest,
+  EmbedResult,
   GovernancePolicy,
   KeySource,
   ModelInfo,
+  ParsedResult,
   Redactor,
   ResolvedConnection,
+  StandardSchemaV1,
   StreamEvent,
   TelemetrySink,
+  Usage,
 } from './types.js';
 import { promptChars, sleep } from './util.js';
 
@@ -36,7 +42,39 @@ export interface HandlerOptions {
     afterCall?(record: CallRecord): Promise<void>;
   };
   retry?: { maxAttempts?: number; baseDelayMs?: number; maxDelayMs?: number };
+  /**
+   * Concurrency and pacing limits, enforced by an **in-memory queue on this
+   * handler instance only**. There is no shared/external coordination, so N
+   * instances behind a load balancer allow N × `maxConcurrent` in flight against
+   * the provider. Size these per instance, or put a shared limiter in front if a
+   * global ceiling matters.
+   */
   limits?: { maxConcurrent?: number; minIntervalMs?: number };
+  /**
+   * Silence the one-time startup notice logged when no `policy` is supplied.
+   * Set this only when running unrestricted is a deliberate choice — passing an
+   * explicit `policy: allowAllPolicy()` says the same thing and is clearer.
+   */
+  silencePolicyWarning?: boolean;
+  /**
+   * Optional cost estimator. Called once per successful call/embedding with the
+   * final usage; its return value (USD) is stored on the telemetry record's
+   * `costUsd`. Return undefined to leave a call uncosted. Pricing tables live in
+   * the app, not the library — this is only the seam to attach one.
+   */
+  pricing?(info: { provider: string; model: string; usage: Usage }): number | undefined;
+}
+
+/**
+ * A *startup* notice, so it fires once per process rather than once per handler
+ * — an app that builds a handler per request would otherwise flood its logs
+ * with a message that says the same thing every time.
+ */
+let warnedNoPolicy = false;
+
+/** Test seam: reset the once-per-process startup notice. */
+export function resetPolicyWarningForTests(): void {
+  warnedNoPolicy = false;
 }
 
 export class AIHandler {
@@ -48,6 +86,17 @@ export class AIHandler {
 
   constructor(private opts: HandlerOptions) {
     this.policy = opts.policy ?? allowAllPolicy();
+    // `allowAllPolicy()` stays the default — a library must not decide an app's
+    // governance — but "no policy configured" should be visible at runtime, not
+    // only in a README paragraph. Passing an explicit policy (including
+    // `allowAllPolicy()`) is the opt-out.
+    if (!opts.policy && !opts.silencePolicyWarning && !warnedNoPolicy) {
+      warnedNoPolicy = true;
+      globalThis.console?.warn?.(
+        '[ai-nugget] No GovernancePolicy configured — every provider/model is allowed. ' +
+        'Pass `policy` (e.g. allowlistPolicy(...)), or `policy: allowAllPolicy()` / `silencePolicyWarning: true` to accept this deliberately.',
+      );
+    }
   }
 
   async chat(conn: Connection, req: ChatRequest): Promise<ChatResult> {
@@ -64,41 +113,13 @@ export class AIHandler {
     const callId = createCallId();
     const startedAt = Date.now();
     const adapter = adapterFor(conn.provider, conn.baseUrl);
-    const policyResult = this.policy.checkModel(conn.provider, req.model);
-    if (!policyResult.allowed) {
-      const error = new AIError(policyResult.reason, { kind: 'policy_blocked', retryable: false, provider: conn.provider });
-      await this.recordFailure(callId, conn, req, startedAt, 1, error);
-      yield { type: 'error', error: this.redactedError(error) };
-      return;
-    }
 
-    let resolved: ResolvedConnection;
-    try {
-      resolved = await this.resolveConnection(conn);
-    } catch (errorValue) {
-      // Key resolution failures (missing/locked/denied) are a recorded outcome,
-      // not an uncaught throw — the traceability contract covers them too.
-      const error = fromUnknown(errorValue, conn.provider);
-      await this.recordFailure(callId, conn, req, startedAt, 1, error);
-      yield { type: 'error', error: this.redactedError(error) };
-      return;
-    }
-    const info: CallInfo = { callId, connection: conn, provider: conn.provider, model: req.model, metadata: req.metadata };
-    try {
-      if (await this.opts.hooks?.beforeCall?.(info) === 'deny') {
-        const error = new AIError('Call denied by beforeCall hook', { kind: 'policy_blocked', retryable: false, provider: conn.provider });
-        await this.recordFailure(callId, conn, req, startedAt, 1, error);
-        yield { type: 'error', error: this.redactedError(error) };
-        return;
-      }
-    } catch (errorValue) {
-      // A throwing beforeCall hook is a recorded, redacted outcome too — not
-      // an uncaught throw that skips telemetry and the redaction guarantee.
-      const error = fromUnknown(errorValue, conn.provider);
-      await this.recordFailure(callId, conn, req, startedAt, 1, error);
-      yield { type: 'error', error: this.redactedError(error) };
-      return;
-    }
+    const preflight = await this.preflight(callId, conn, req.model, req.metadata);
+    if (!preflight.ok) return yield* this.failStream(callId, conn, req, startedAt, 1, preflight.error);
+    // One idempotency key per logical call, reused across every retry attempt,
+    // so a provider that supports it collapses a re-sent generation instead of
+    // billing it twice (see `supportsIdempotencyKey` in the profile table).
+    const resolved = withIdempotencyKey(preflight.resolved, callId);
 
     let acquired = false;
     let recorded = false;
@@ -132,31 +153,25 @@ export class AIHandler {
           throw new AIError('Provider did not emit a done event', { kind: 'invalid_response', provider: conn.provider });
         } catch (errorValue) {
           const error = fromUnknown(errorValue, conn.provider);
+          // `emittedOutput` stops retries once any byte has reached the caller:
+          // never silently re-run a partially delivered answer.
           if (!error.retryable || attempt >= maxAttempts || req.signal?.aborted || emittedOutput) {
-            await this.recordFailure(callId, conn, req, startedAt, attempt, error);
             recorded = true;
-            yield { type: 'error', error: this.redactedError(error) };
-            return;
+            return yield* this.failStream(callId, conn, req, startedAt, attempt, error);
           }
           const delayMs = this.retryDelay(error, attempt);
           yield { type: 'retry', attempt, reason: error.kind, delayMs };
           try {
             await sleep(delayMs, req.signal);
           } catch (sleepError) {
-            const canceled = fromUnknown(sleepError, conn.provider);
-            await this.recordFailure(callId, conn, req, startedAt, attempt, canceled);
             recorded = true;
-            yield { type: 'error', error: this.redactedError(canceled) };
-            return;
+            return yield* this.failStream(callId, conn, req, startedAt, attempt, fromUnknown(sleepError, conn.provider));
           }
         }
       }
     } catch (errorValue) {
-      const error = fromUnknown(errorValue, conn.provider);
-      await this.recordFailure(callId, conn, req, startedAt, Math.max(1, attempt), error);
       recorded = true;
-      yield { type: 'error', error: this.redactedError(error) };
-      return;
+      return yield* this.failStream(callId, conn, req, startedAt, Math.max(1, attempt), fromUnknown(errorValue, conn.provider));
     } finally {
       if (acquired) this.release();
       if (acquired && !recorded) {
@@ -172,6 +187,59 @@ export class AIHandler {
     }
   }
 
+  /**
+   * The shared pre-call preamble: policy check → key resolution → `beforeCall`
+   * hook. Every entry point (`stream`, `embed`, `listModels`/`testConnection`)
+   * runs exactly this sequence, so it lives once. Failures are *returned*, not
+   * recorded — each caller owns its own telemetry shape (`recordFailure` for
+   * chat/probe, `recordEmbed` for embeddings) and records the returned error.
+   */
+  private async preflight(
+    callId: string,
+    conn: Connection,
+    model: string,
+    metadata: Record<string, unknown> | undefined,
+  ): Promise<{ ok: true; resolved: ResolvedConnection } | { ok: false; error: AIError }> {
+    const policyResult = this.policy.checkModel(conn.provider, model);
+    if (!policyResult.allowed) {
+      return { ok: false, error: new AIError(policyResult.reason, { kind: 'policy_blocked', retryable: false, provider: conn.provider }) };
+    }
+
+    let resolved: ResolvedConnection;
+    try {
+      resolved = await this.resolveConnection(conn);
+    } catch (errorValue) {
+      // Key resolution failures (missing/locked/denied) are a recorded outcome,
+      // not an uncaught throw — the traceability contract covers them too.
+      return { ok: false, error: fromUnknown(errorValue, conn.provider) };
+    }
+
+    try {
+      const info: CallInfo = {
+        callId,
+        connection: safeConnection(conn),
+        provider: conn.provider,
+        model,
+        metadata,
+        resolved: safeResolved(resolved),
+      };
+      if (await this.opts.hooks?.beforeCall?.(info) === 'deny') {
+        return { ok: false, error: new AIError('Call denied by beforeCall hook', { kind: 'policy_blocked', retryable: false, provider: conn.provider }) };
+      }
+    } catch (errorValue) {
+      // A throwing beforeCall hook is a recorded, redacted outcome too — not
+      // an uncaught throw that skips telemetry and the redaction guarantee.
+      return { ok: false, error: fromUnknown(errorValue, conn.provider) };
+    }
+    return { ok: true, resolved };
+  }
+
+  /** Record a failed call and emit the single redacted `error` event for it. */
+  private async *failStream(callId: string, conn: Connection, req: ChatRequest, startedAt: number, attempts: number, error: AIError): AsyncGenerator<StreamEvent> {
+    await this.recordFailure(callId, conn, req, startedAt, attempts, error);
+    yield { type: 'error', error: this.redactedError(error) };
+  }
+
   async listModels(conn: Connection): Promise<ModelInfo[]> {
     return this.runProbe(conn, '__listModels__', async (resolved) => {
       const adapter = adapterFor(conn.provider, conn.baseUrl);
@@ -196,23 +264,112 @@ export class AIHandler {
     }
   }
 
-  private async runProbe<T>(conn: Connection, operation: '__listModels__' | '__testConnection__', action: (resolved: ResolvedConnection) => Promise<T>): Promise<T> {
+  /**
+   * Warm a connection so the first real call doesn't pay cold DNS/TLS and
+   * (for a local daemon) process spin-up on the hot path. Runs a lightweight
+   * health probe and never throws — call it once at boot. Combined with a CJS
+   * `require` path it removes the cold-start "offline" false negative.
+   */
+  async prewarm(conn: Connection): Promise<void> {
+    try {
+      await this.testConnection(conn);
+    } catch {
+      // Warm-up only: a failure here just means the first real call pays the cost.
+    }
+  }
+
+  /**
+   * Chat that returns typed, validated output. Requests JSON mode, extracts the
+   * JSON from the reply, and validates it against any Standard Schema validator
+   * (Zod / Valibot / ArkType). On a validation miss it performs exactly one
+   * corrective retry that shows the model its error, then throws
+   * `invalid_response` if still invalid. No schema library is bundled — the
+   * caller supplies the schema.
+   */
+  async chatParsed<T>(conn: Connection, req: ChatRequest, schema: StandardSchemaV1<T>): Promise<ParsedResult<T>> {
+    const base: ChatRequest = { ...req, responseFormat: req.responseFormat ?? { type: 'json' } };
+    let result = await this.chat(conn, base);
+    let validated = await validateWithSchema(schema, result.text);
+    if (validated.ok) return { data: validated.value, result };
+
+    const retry: ChatRequest = {
+      ...base,
+      messages: [
+        ...base.messages,
+        { role: 'assistant', content: result.text },
+        { role: 'user', content: `That response did not match the required schema (${validated.message}). Reply again with ONLY a valid JSON value that matches it.` },
+      ],
+    };
+    result = await this.chat(conn, retry);
+    validated = await validateWithSchema(schema, result.text);
+    if (validated.ok) return { data: validated.value, result };
+    throw new AIError(`Model output failed schema validation: ${validated.message}`, { kind: 'invalid_response', provider: conn.provider });
+  }
+
+  /**
+   * Produce embeddings through the same governed pipeline as chat: policy check,
+   * key resolution, `beforeCall` hook, concurrency, and exactly one redacted
+   * telemetry record. Throws a typed `invalid_request` error for providers whose
+   * adapter has no `embed` (Anthropic, Google) rather than failing silently.
+   */
+  async embed(conn: Connection, req: EmbedRequest): Promise<EmbedResult> {
     const callId = createCallId();
     const startedAt = Date.now();
-    const req: ChatRequest = { model: operation, messages: [], metadata: { operation } };
-    const policyResult = this.policy.checkModel(conn.provider, operation);
-    if (!policyResult.allowed) {
-      const error = new AIError(policyResult.reason, { kind: 'policy_blocked', retryable: false, provider: conn.provider });
-      await this.recordFailure(callId, conn, req, startedAt, 1, error);
+    const inputChars = (Array.isArray(req.input) ? req.input : [req.input]).reduce((sum, text) => sum + text.length, 0);
+    const fail = async (error: AIError): Promise<never> => {
+      await this.recordEmbed(callId, conn, req, startedAt, { estimated: true }, inputChars, error);
       throw this.redactedError(error);
+    };
+
+    const preflight = await this.preflight(callId, conn, req.model, req.metadata);
+    if (!preflight.ok) return fail(preflight.error);
+    const resolved = preflight.resolved;
+
+    const adapter = adapterFor(conn.provider, conn.baseUrl);
+    if (!adapter.embed) {
+      return fail(new AIError(`Provider ${conn.provider} does not support embeddings`, { kind: 'invalid_request', retryable: false, provider: conn.provider }));
     }
-    let resolved: ResolvedConnection;
+
+    await this.acquire(req.signal);
     try {
-      resolved = await this.resolveConnection(conn);
-      const info: CallInfo = { callId, connection: conn, provider: conn.provider, model: operation, metadata: req.metadata };
-      if (await this.opts.hooks?.beforeCall?.(info) === 'deny') {
-        throw new AIError('Call denied by beforeCall hook', { kind: 'policy_blocked', retryable: false, provider: conn.provider });
-      }
+      const result = await adapter.embed(resolved, req);
+      await this.recordEmbed(callId, conn, req, startedAt, result.usage, inputChars);
+      return result;
+    } catch (errorValue) {
+      return fail(fromUnknown(errorValue, conn.provider));
+    } finally {
+      this.release();
+    }
+  }
+
+  private async recordEmbed(callId: string, conn: Connection, req: EmbedRequest, startedAt: number, usage: Usage, inputChars: number, error?: AIError): Promise<void> {
+    const costUsd = error ? undefined : this.opts.pricing?.({ provider: conn.provider, model: req.model, usage });
+    await this.record({
+      callId,
+      connectionId: conn.id,
+      provider: conn.provider,
+      model: req.model,
+      startedAt,
+      timing: { firstTokenMs: null, totalMs: Date.now() - startedAt },
+      usage,
+      finishReason: error ? (error.kind === 'canceled' ? 'canceled' : 'error') : 'stop',
+      ...(error ? { error: { kind: error.kind, status: error.status, message: error.message } } : {}),
+      attempts: 1,
+      metadata: { ...req.metadata, operation: '__embed__' },
+      promptChars: inputChars,
+      responseChars: 0,
+      ...(costUsd !== undefined ? { costUsd } : {}),
+    });
+  }
+
+  private async runProbe<T>(conn: Connection, operation: '__listModels__' | '__testConnection__', action: (resolved: ResolvedConnection) => Promise<T>): Promise<T> {
+    const callId = createCallId();
+    const startedAt = Date.now();
+    const req: ChatRequest = { model: operation, messages: [], metadata: { operation } };
+    try {
+      const preflight = await this.preflight(callId, conn, operation, req.metadata);
+      if (!preflight.ok) throw preflight.error;
+      const resolved = preflight.resolved;
       await this.acquire(undefined);
       try {
         const value = await action(resolved);
@@ -274,12 +431,17 @@ export class AIHandler {
     }
     this.active += 1;
     const minInterval = this.opts.limits?.minIntervalMs ?? 0;
-    const wait = Math.max(0, this.lastStarted + minInterval - Date.now());
-    this.lastStarted = Date.now() + wait;
+    const previousLastStarted = this.lastStarted;
+    const wait = Math.max(0, previousLastStarted + minInterval - Date.now());
+    const reserved = Date.now() + wait;
+    this.lastStarted = reserved;
     try {
       if (wait) await sleep(wait, signal);
     } catch (error) {
       this.release();
+      // Only undo our own reservation — a later caller may have already
+      // paced itself off `reserved` and must keep that spacing.
+      if (this.lastStarted === reserved) this.lastStarted = previousLastStarted;
       throw error;
     }
   }
@@ -304,6 +466,7 @@ export class AIHandler {
   }
 
   private async recordSuccess(callId: string, conn: Connection, req: ChatRequest, startedAt: number, attempts: number, result: ChatResult): Promise<void> {
+    const costUsd = this.opts.pricing?.({ provider: conn.provider, model: req.model, usage: result.usage });
     await this.record({
       callId,
       connectionId: conn.id,
@@ -317,6 +480,7 @@ export class AIHandler {
       metadata: req.metadata,
       promptChars: promptChars(req.messages),
       responseChars: result.text.length,
+      ...(costUsd !== undefined ? { costUsd } : {}),
     });
   }
 
@@ -403,6 +567,69 @@ function trimSlash(value: string): string {
   return value.replace(/\/+$/, '');
 }
 
+/**
+ * Drops the resolved API key *and* neutralizes the auth headers built from it,
+ * so a `beforeCall` hook can inspect the endpoint but never the secret.
+ * `keyRef` is scrubbed too — a `{ kind: 'literal' }` ref carries the plaintext
+ * key, and hooks routinely log the whole object.
+ */
+function safeResolved(resolved: ResolvedConnection): Omit<ResolvedConnection, 'apiKey'> {
+  const { apiKey: _apiKey, headers, ...rest } = resolved;
+  return { ...rest, ...safeKeyRef(resolved), headers: maskAuthHeaders(headers) };
+}
+
+/**
+ * The caller's own `Connection`, with any plaintext `keyRef` masked. Hooks get
+ * the connection so they can key off `id`/`provider`/`baseUrl`; they must never
+ * be handed the secret, since logging `info.connection` for audit is the
+ * obvious thing to do and would otherwise ship the key in clear text.
+ */
+function safeConnection(conn: Connection): Connection {
+  return { ...conn, ...safeKeyRef(conn) };
+}
+
+function safeKeyRef(conn: Connection): { keyRef?: Connection['keyRef'] } {
+  if (conn.keyRef?.kind !== 'literal') return conn.keyRef === undefined ? {} : { keyRef: conn.keyRef };
+  return { keyRef: { kind: 'literal', value: REDACTED } };
+}
+
+const REDACTED = '[REDACTED]';
+
+/** Header names whose value is derived from the API key by {@link applyAuth}. */
+const AUTH_HEADERS = new Set(['authorization', 'x-api-key', 'x-goog-api-key', 'api-key']);
+
+function maskAuthHeaders(headers: Record<string, string>): Record<string, string> {
+  const masked: Record<string, string> = {};
+  for (const [name, value] of Object.entries(headers)) {
+    masked[name] = AUTH_HEADERS.has(name.toLowerCase()) ? REDACTED : value;
+  }
+  return masked;
+}
+
+/**
+ * Attach a per-call `Idempotency-Key` for providers that honor one, so a retry
+ * after a dropped connection can't be billed as a second generation. Only set
+ * where the profile declares support, and never overrides a caller-supplied
+ * header.
+ */
+function withIdempotencyKey(resolved: ResolvedConnection, callId: string): ResolvedConnection {
+  const profile = profileFor(resolved.provider, resolved.baseUrl);
+  if (!profile.quirks?.supportsIdempotencyKey) return resolved;
+  if (Object.keys(resolved.headers).some((name) => name.toLowerCase() === 'idempotency-key')) return resolved;
+  return { ...resolved, headers: { ...resolved.headers, 'idempotency-key': callId } };
+}
+
+async function validateWithSchema<T>(schema: StandardSchemaV1<T>, text: string): Promise<{ ok: true; value: T } | { ok: false; message: string }> {
+  const value = extractJson(text);
+  if (value === null) return { ok: false, message: 'no JSON found in model output' };
+  const result = await schema['~standard'].validate(value);
+  if (result.issues) {
+    const message = result.issues.map((issue) => issue.message).join('; ');
+    return { ok: false, message: message || 'validation failed' };
+  }
+  return { ok: true, value: result.value };
+}
+
 function createCallId(): string {
   return globalThis.crypto?.randomUUID?.() ?? `call_${Date.now()}_${Math.random().toString(36).slice(2)}`;
 }

package/nugget/src/index.ts

@@ -4,6 +4,7 @@ export * from './transport.js';
 export * from './json.js';
 export * from './tokens.js';
 export * from './keys.js';
+export * from './connect.js';
 export * from './redact.js';
 export * from './policy.js';
 export * from './handler.js';

package/nugget/src/keys.ts

@@ -1,4 +1,5 @@
 import type { KeyRef, KeySource } from './types.js';
+import { globalEnv } from './util.js';
 
 export function parseKeyRef(value?: string | null): KeyRef {
   const trimmed = value?.trim();
@@ -63,8 +64,3 @@ export function chainKeySources(...sources: KeySource[]): KeySource {
     },
   };
 }
-
-function globalEnv(): Record<string, string | undefined> {
-  const maybeProcess = globalThis as typeof globalThis & { process?: { env?: Record<string, string | undefined> } };
-  return maybeProcess.process?.env ?? {};
-}

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();
+    },
   };
 }