@jxburros/ai-nugget 0.4.1 → 0.6.0

package/dist/handler.d.ts

@@ -1,4 +1,4 @@
-import type { CallInfo, CallRecord, ChatRequest, ChatResult, Connection, GovernancePolicy, KeySource, ModelInfo, Redactor, StreamEvent, TelemetrySink } from './types.js';
+import type { CallInfo, CallRecord, ChatRequest, ChatResult, Connection, EmbedRequest, EmbedResult, GovernancePolicy, KeySource, ModelInfo, ParsedResult, Redactor, StandardSchemaV1, StreamEvent, TelemetrySink, Usage } from './types.js';
 export interface HandlerOptions {
     keySource: KeySource;
     policy?: GovernancePolicy;
@@ -13,11 +13,37 @@ export interface HandlerOptions {
         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;
 }
+/** Test seam: reset the once-per-process startup notice. */
+export declare function resetPolicyWarningForTests(): void;
 export declare class AIHandler {
     private opts;
     private active;
@@ -28,11 +54,45 @@ export declare class AIHandler {
     constructor(opts: HandlerOptions);
     chat(conn: Connection, req: ChatRequest): Promise<ChatResult>;
     stream(conn: Connection, req: ChatRequest): AsyncIterable<StreamEvent>;
+    /**
+     * 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 preflight;
+    /** Record a failed call and emit the single redacted `error` event for it. */
+    private failStream;
     listModels(conn: Connection): Promise<ModelInfo[]>;
     testConnection(conn: Connection): Promise<{
         ok: boolean;
         message: string;
     }>;
+    /**
+     * 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.
+     */
+    prewarm(conn: Connection): Promise<void>;
+    /**
+     * 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.
+     */
+    chatParsed<T>(conn: Connection, req: ChatRequest, schema: StandardSchemaV1<T>): Promise<ParsedResult<T>>;
+    /**
+     * 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.
+     */
+    embed(conn: Connection, req: EmbedRequest): Promise<EmbedResult>;
+    private recordEmbed;
     private runProbe;
     private resolveConnection;
     private acquire;

package/dist/handler.js

@@ -1,9 +1,20 @@
 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 { promptChars, sleep } from './util.js';
+/**
+ * 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() {
+    warnedNoPolicy = false;
+}
 export class AIHandler {
     opts;
     active = 0;
@@ -14,6 +25,15 @@ export class AIHandler {
     constructor(opts) {
         this.opts = opts;
         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, req) {
         let result;
@@ -31,42 +51,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;
-        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 = { 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;
         let attempt = 0;
@@ -101,11 +92,11 @@ export class AIHandler {
                 }
                 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 };
@@ -113,21 +104,15 @@ export class AIHandler {
                         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)
@@ -137,6 +122,52 @@ 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.
+     */
+    async preflight(callId, conn, model, metadata) {
+        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;
+        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 = {
+                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. */
+    async *failStream(callId, conn, req, startedAt, attempts, error) {
+        await this.recordFailure(callId, conn, req, startedAt, attempts, error);
+        yield { type: 'error', error: this.redactedError(error) };
+    }
     async listModels(conn) {
         return this.runProbe(conn, '__listModels__', async (resolved) => {
             const adapter = adapterFor(conn.provider, conn.baseUrl);
@@ -161,23 +192,111 @@ export class AIHandler {
             return { ok: false, message: error instanceof Error ? this.redact(error.message) : 'Connection failed' };
         }
     }
-    async runProbe(conn, operation, action) {
+    /**
+     * 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) {
+        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(conn, req, schema) {
+        const base = { ...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 = {
+            ...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, req) {
         const callId = createCallId();
         const startedAt = Date.now();
-        const req = { 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) => {
+            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;
+        await this.acquire(req.signal);
         try {
-            resolved = await this.resolveConnection(conn);
-            const info = { 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();
+        }
+    }
+    async recordEmbed(callId, conn, req, startedAt, usage, inputChars, error) {
+        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 } : {}),
+        });
+    }
+    async runProbe(conn, operation, action) {
+        const callId = createCallId();
+        const startedAt = Date.now();
+        const req = { 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);
@@ -278,6 +397,7 @@ export class AIHandler {
         return Math.round(exponential * (0.75 + Math.random() * 0.5));
     }
     async recordSuccess(callId, conn, req, startedAt, attempts, result) {
+        const costUsd = this.opts.pricing?.({ provider: conn.provider, model: req.model, usage: result.usage });
         await this.record({
             callId,
             connectionId: conn.id,
@@ -291,6 +411,7 @@ export class AIHandler {
             metadata: req.metadata,
             promptChars: promptChars(req.messages),
             responseChars: result.text.length,
+            ...(costUsd !== undefined ? { costUsd } : {}),
         });
     }
     async recordFailure(callId, conn, req, startedAt, attempts, error) {
@@ -371,6 +492,65 @@ function redactMetadata(metadata, redact) {
 function trimSlash(value) {
     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) {
+    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) {
+    return { ...conn, ...safeKeyRef(conn) };
+}
+function safeKeyRef(conn) {
+    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) {
+    const masked = {};
+    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, callId) {
+    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(schema, text) {
+    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() {
     return globalThis.crypto?.randomUUID?.() ?? `call_${Date.now()}_${Math.random().toString(36).slice(2)}`;
 }

package/dist/redact.d.ts

@@ -1,4 +1,22 @@
 import type { Redactor } from './types.js';
+/**
+ * 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 declare const SECRET_PATTERNS: RegExp[];
+/**
+ * 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 declare const LABELED_SECRET_PATTERNS: RegExp[];
 export declare function createDefaultRedactor(extraSecrets?: Iterable<string>): Redactor;
 export declare class SessionRedactor implements Redactor {
     private secrets;

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) {