@jxburros/ai-nugget 0.3.1 → 0.6.0

package/dist/connect.js

@@ -0,0 +1,25 @@
+import { globalEnv } from './util.js';
+/**
+ * Resolves a server-side `Connection` plus a default `model` from app-owned
+ * env vars (`AI_PROVIDER`, `AI_MODEL`, `AI_KEY_ENV`, `AI_BASE_URL` unless
+ * overridden). This only collapses the config-reading boilerplate that was
+ * being hand-rolled the same way in every small server app; it does not add
+ * policy. `provider`/`baseUrl` still come from the server's own environment,
+ * never from client input, and the returned `keyRef` still resolves through
+ * `KeySource` at call time like any other `Connection`.
+ */
+export function envConnection(options = {}) {
+    const env = options.env ?? globalEnv();
+    const provider = env[options.providerVar ?? 'AI_PROVIDER']?.trim() || options.defaultProvider || 'openai';
+    const model = env[options.modelVar ?? 'AI_MODEL']?.trim() || options.defaultModel || 'gpt-4o-mini';
+    const keyEnvName = env[options.keyEnvVar ?? 'AI_KEY_ENV']?.trim() || options.defaultKeyEnv || 'OPENAI_API_KEY';
+    const baseUrl = env[options.baseUrlVar ?? 'AI_BASE_URL']?.trim();
+    const connection = {
+        id: options.id ?? 'app',
+        provider,
+        keyRef: { kind: 'env', name: keyEnvName },
+        ...(baseUrl ? { baseUrl } : {}),
+    };
+    return { connection, model };
+}
+//# sourceMappingURL=connect.js.map

package/dist/errors.js

@@ -1,3 +1,12 @@
+import { createDefaultRedactor } from './redact.js';
+/**
+ * Pattern-based redaction applied at the wire boundary, before an error object
+ * exists. `AIHandler` redacts again on the way out (adding session-registered
+ * exact secrets), but doing it here means a provider body that echoes a
+ * recognizable secret can never be carried by an `AIError` in the first place —
+ * including on code paths that never reach the handler's own catch blocks.
+ */
+const wireRedactor = createDefaultRedactor();
 export class AIError extends Error {
     kind;
     status;
@@ -26,9 +35,13 @@ export function defaultRetryable(kind) {
     return kind === 'rate_limit' || kind === 'timeout' || kind === 'network' || kind === 'server' || kind === 'invalid_response';
 }
 export function classify(status, body = '', provider, headers) {
-    const excerpt = body.slice(0, 200);
+    const excerpt = wireRedactor.redact(body.slice(0, 200));
     const lower = body.toLowerCase();
     let kind = 'server';
+    // 403 is classified as `auth` (non-retryable) deliberately: a forbidden
+    // response almost always means a bad/insufficient credential or a blocked
+    // region/model, none of which a retry fixes. Callers that know a specific
+    // provider returns a retryable 403 can reclassify in a `beforeCall`/adapter.
     if (status === 401 || status === 403)
         kind = 'auth';
     else if (status === 408)
@@ -40,8 +53,19 @@ export function classify(status, body = '', provider, headers) {
             ? 'context_length'
             : 'invalid_request';
     }
+    else if (status === 404 || status === 410) {
+        // A missing route/deployment is not a malformed request: it is usually a
+        // wrong baseUrl or model name, and sometimes a temporarily misrouted load
+        // balancer. `not_found` keeps it distinguishable from `invalid_request` so
+        // apps don't tell a user "your request was invalid" for an infra problem.
+        // Non-retryable by default — a caller that knows its 404s are transient can
+        // retry on `kind === 'not_found'` itself.
+        kind = 'not_found';
+    }
     else if (status >= 500)
         kind = 'server';
+    // Everything else in 4xx (409 conflict, 405, 415, 451, …) is a genuine
+    // client-side request problem, so `invalid_request` is honest for it.
     else
         kind = 'invalid_request';
     return new AIError(`HTTP ${status}: ${excerpt}`, {

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);
@@ -241,14 +360,20 @@ 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;
         }
     }
@@ -272,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,
@@ -285,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) {
@@ -365,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/index.d.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/dist/index.js

@@ -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/dist/keys.js

@@ -1,3 +1,4 @@
+import { globalEnv } from './util.js';
 export function parseKeyRef(value) {
     const trimmed = value?.trim();
     if (!trimmed)
@@ -71,8 +72,4 @@ export function chainKeySources(...sources) {
         },
     };
 }
-function globalEnv() {
-    const maybeProcess = globalThis;
-    return maybeProcess.process?.env ?? {};
-}
 //# sourceMappingURL=keys.js.map

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;