fixo-cli 1.0.0

package/dist/runtime/background-jobs.js

@@ -0,0 +1,331 @@
+/**
+ * background-jobs.ts — Async command execution registry.
+ *
+ * Phase 3.1: lets the agent spawn long-running commands
+ * (`run_command_async`) and poll their status without blocking
+ * the REPL or the agent loop. Every job is keyed by a
+ * `job_<short-uuid>` and stored in an in-memory `Map` so a
+ * crashed CLI invocation can rebuild the tail buffers from the
+ * on-disk JSON snapshot.
+ *
+ * Safety:
+ *   - `spawn` reuses `isCommandSafe` from `command-parser.ts` so
+ *     a workspace-escape or sensitive-file read is rejected
+ *     before any process is started.
+ *   - The `cwd` argument is resolved through `WorkspaceGuard`
+ *     so the spawned process cannot chdir outside the workspace.
+ *   - The 64 KiB per-stream cap matches the staging-manager
+ *     contract — no unbounded buffer growth.
+ *   - A 1-hour reaper (`setInterval` in `startReaper`) kills any
+ *     job whose `pid` is no longer alive, even if the executor
+ *     never received an `exit` event.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { isCommandSafe } from '../agent/command-parser.js';
+import { WorkspaceGuard } from '../workspace-guard.js';
+import { recordTelemetry, telemetry } from '../agent/telemetry.js';
+/* ──────────────────────── Constants ──────────────────────── */
+const STREAM_CAP_BYTES = 64 * 1024;
+const SNAPSHOT_FLUSH_MS = 5_000;
+const REAPER_INTERVAL_MS = 60_000;
+const REAPER_MAX_AGE_MS = 60 * 60 * 1_000; // 1 hour
+/* ──────────────────────── Helpers ──────────────────────── */
+function appendCapped(buffer, chunk) {
+    const next = buffer.text + chunk;
+    const bytes = Buffer.byteLength(next, 'utf-8');
+    if (bytes > STREAM_CAP_BYTES) {
+        // Slice from the END so the user always sees the most recent
+        // output, not the oldest. The `totalStdoutBytes` counter
+        // preserves the original length so `sinceBytes` can still
+        // compute deltas.
+        const overflow = bytes - STREAM_CAP_BYTES;
+        let startIdx = 0;
+        let acc = 0;
+        // Walk forward until the cumulative byte count equals the
+        // overflow, then slice from there. This is a character-safe
+        // approach that avoids splitting a multi-byte UTF-8 char.
+        for (let i = 0; i < next.length; i++) {
+            acc += Buffer.byteLength(next[i], 'utf-8');
+            if (acc > overflow) {
+                startIdx = i;
+                break;
+            }
+        }
+        buffer.text = next.slice(startIdx);
+        buffer.truncated = true;
+    }
+    else {
+        buffer.text = next;
+    }
+    buffer.bytes += Buffer.byteLength(chunk, 'utf-8');
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/* ──────────────────────── Registry ──────────────────────── */
+export class BackgroundJobRegistry {
+    jobs = new Map();
+    processes = new Map();
+    cwd;
+    snapshotDir;
+    flushTimer = null;
+    reaperTimer = null;
+    constructor(cwd, opts = {}) {
+        this.cwd = cwd;
+        this.snapshotDir = opts.snapshotDir ?? path.join(cwd, '.fixo', 'jobs');
+        fs.mkdirSync(this.snapshotDir, { recursive: true });
+        this.startSnapshotFlusher();
+        if (!opts.disableReaper)
+            this.startReaper();
+    }
+    /** Spawn a new background command. Reuses `isCommandSafe` for AST validation. */
+    async register(input) {
+        if (input.cmd.trim().length === 0) {
+            return { ok: false, error: 'cmd is empty' };
+        }
+        // Resolve the requested cwd through the workspace guard so the
+        // child process cannot chdir outside the workspace root.
+        const guard = new WorkspaceGuard(this.cwd);
+        let resolvedCwd;
+        try {
+            resolvedCwd = guard.resolve(input.cwd, 'background-job cwd');
+        }
+        catch (err) {
+            return { ok: false, error: err.message };
+        }
+        const safety = await isCommandSafe(`${input.cmd} ${input.args.join(' ')}`.trim(), this.cwd);
+        if (!safety.safe) {
+            return { ok: false, error: `command rejected by command-parser: ${safety.reason ?? 'unsafe'}` };
+        }
+        const id = `job_${randomUUID().slice(0, 8)}`;
+        const job = {
+            id,
+            cmd: input.cmd,
+            args: [...input.args],
+            cwd: resolvedCwd,
+            status: 'running',
+            startedAt: new Date().toISOString(),
+            stdout: '',
+            stderr: '',
+            totalStdoutBytes: 0,
+            totalStderrBytes: 0,
+            stdoutTruncated: false,
+            stderrTruncated: false,
+        };
+        let child;
+        try {
+            child = spawn(input.cmd, input.args, {
+                cwd: resolvedCwd,
+                env: { ...process.env, FIXO_BACKGROUND_JOB: id },
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch (err) {
+            job.status = 'failed';
+            job.failureReason = 'spawn threw';
+            job.lastError = err.message;
+            job.exitedAt = new Date().toISOString();
+            this.jobs.set(id, job);
+            return { ok: false, jobId: id, error: job.lastError };
+        }
+        job.pid = child.pid;
+        this.jobs.set(id, job);
+        this.processes.set(id, child);
+        const stdoutBuf = { text: job.stdout, truncated: false, bytes: 0 };
+        const stderrBuf = { text: job.stderr, truncated: false, bytes: 0 };
+        child.stdout?.setEncoding('utf-8');
+        child.stderr?.setEncoding('utf-8');
+        child.stdout?.on('data', (chunk) => {
+            appendCapped(stdoutBuf, chunk);
+            job.stdout = stdoutBuf.text;
+            job.stdoutTruncated = stdoutBuf.truncated;
+            job.totalStdoutBytes = stdoutBuf.bytes;
+        });
+        child.stderr?.on('data', (chunk) => {
+            appendCapped(stderrBuf, chunk);
+            job.stderr = stderrBuf.text;
+            job.stderrTruncated = stderrBuf.truncated;
+            job.totalStderrBytes = stderrBuf.bytes;
+        });
+        child.on('error', (err) => {
+            job.lastError = err.message;
+            // Spawn failures do not emit an `exit` event — flip the
+            // status to `failed` here so pollers can detect the
+            // terminal state without waiting forever.
+            if (job.status === 'running') {
+                job.status = 'failed';
+                job.failureReason = err.message;
+                job.exitedAt = new Date().toISOString();
+                this.processes.delete(id);
+            }
+        });
+        child.on('exit', (code, signal) => {
+            job.exitedAt = new Date().toISOString();
+            if (signal === 'SIGTERM' || signal === 'SIGKILL') {
+                job.status = 'killed';
+            }
+            else if (code === 0) {
+                job.status = 'exited';
+            }
+            else {
+                job.status = 'failed';
+                job.failureReason = job.lastError ?? `exit code ${String(code)}`;
+            }
+            job.exitCode = code ?? undefined;
+            this.processes.delete(id);
+            recordTelemetry(telemetry.asyncSpawn({
+                jobId: id,
+                cmd: input.cmd,
+                pid: job.pid,
+            }));
+        });
+        recordTelemetry(telemetry.asyncSpawn({ jobId: id, cmd: input.cmd, pid: job.pid }));
+        return { ok: true, jobId: id, pid: job.pid };
+    }
+    /** Read a snapshot. Honours `tailLines` and `sinceBytes` for the streams. */
+    poll(input) {
+        const job = this.jobs.get(input.jobId);
+        if (!job)
+            return null;
+        const tailLines = input.tailLines;
+        const sinceBytes = input.sinceBytes ?? 0;
+        const sliceTail = (text) => {
+            if (tailLines === undefined)
+                return text;
+            if (tailLines <= 0)
+                return '';
+            // Trim the trailing empty that comes from a terminal newline
+            // so "tail 2" returns the last 2 *content* lines, not
+            // "<last content>\n".
+            const lines = text.split('\n');
+            if (lines.length > 0 && lines[lines.length - 1] === '') {
+                lines.pop();
+            }
+            return lines.slice(Math.max(0, lines.length - tailLines)).join('\n');
+        };
+        return {
+            id: job.id,
+            status: job.status,
+            exitCode: job.exitCode,
+            startedAt: job.startedAt,
+            exitedAt: job.exitedAt,
+            cmd: job.cmd,
+            args: job.args,
+            cwd: job.cwd,
+            stdout: sliceTail(job.stdout),
+            stderr: sliceTail(job.stderr),
+            totalStdoutBytes: job.totalStdoutBytes,
+            totalStderrBytes: job.totalStderrBytes,
+            stdoutTruncated: job.stdoutTruncated,
+            stderrTruncated: job.stderrTruncated,
+            stdoutDelta: sinceBytes > 0 ? sliceTail(job.stdout.slice(sinceBytes)) : undefined,
+            stderrDelta: sinceBytes > 0 ? sliceTail(job.stderr.slice(sinceBytes)) : undefined,
+        };
+    }
+    /** Kill a running job. Returns false if the job was already terminal. */
+    kill(jobId) {
+        const child = this.processes.get(jobId);
+        const job = this.jobs.get(jobId);
+        if (!job)
+            return { ok: false, error: 'no such job' };
+        if (!child)
+            return { ok: false, error: `job is ${job.status}; nothing to kill` };
+        try {
+            child.kill('SIGTERM');
+            return { ok: true };
+        }
+        catch (err) {
+            return { ok: false, error: err.message };
+        }
+    }
+    /** List all jobs (newest first). */
+    list() {
+        return Array.from(this.jobs.values()).sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+    }
+    /** Read a job directly (no tail / sinceBytes shaping). */
+    get(jobId) {
+        return this.jobs.get(jobId) ?? null;
+    }
+    /** Stop timers and kill all running children. Called on CLI shutdown. */
+    shutdown() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        if (this.reaperTimer) {
+            clearInterval(this.reaperTimer);
+            this.reaperTimer = null;
+        }
+        for (const child of this.processes.values()) {
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                // best-effort
+            }
+        }
+        this.processes.clear();
+    }
+    /* ──────── internals ──────── */
+    startSnapshotFlusher() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setInterval(() => {
+            this.flushAllSnapshots();
+        }, SNAPSHOT_FLUSH_MS);
+        // The flusher is a per-process helper; if the event loop exits
+        // (process exit), Node tears it down automatically. We still
+        // call `.unref()` so a stuck flusher never holds the loop open.
+        this.flushTimer.unref?.();
+    }
+    flushAllSnapshots() {
+        for (const job of this.jobs.values()) {
+            const file = path.join(this.snapshotDir, `${job.id}.json`);
+            try {
+                const tmp = `${file}.tmp`;
+                fs.writeFileSync(tmp, JSON.stringify(job, null, 2), { encoding: 'utf-8', mode: 0o600 });
+                fs.renameSync(tmp, file);
+            }
+            catch {
+                // best-effort
+            }
+        }
+    }
+    startReaper() {
+        if (this.reaperTimer)
+            return;
+        this.reaperTimer = setInterval(() => {
+            const now = Date.now();
+            for (const [id, child] of this.processes.entries()) {
+                const job = this.jobs.get(id);
+                if (!job)
+                    continue;
+                const ageMs = now - new Date(job.startedAt).getTime();
+                const pidDead = job.pid !== undefined && !isPidAlive(job.pid);
+                if (ageMs > REAPER_MAX_AGE_MS || pidDead) {
+                    try {
+                        child.kill('SIGKILL');
+                    }
+                    catch {
+                        // best-effort
+                    }
+                    job.status = pidDead ? 'failed' : 'killed';
+                    job.failureReason = pidDead ? 'pid no longer alive' : 'exceeded 1-hour reaper window';
+                    job.exitedAt = new Date().toISOString();
+                    this.processes.delete(id);
+                }
+            }
+        }, REAPER_INTERVAL_MS);
+        this.reaperTimer.unref?.();
+    }
+}
+//# sourceMappingURL=background-jobs.js.map

package/dist/runtime/background-jobs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-jobs.js","sourceRoot":"","sources":["../../src/runtime/background-jobs.ts"],"names":[],"mappings":"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"}

package/dist/runtime/credential-vault.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Restricted Credential Sandbox — Pillar 4 of the Phase 2 safety
+ * refactor. The problem: API keys for OpenAI, Anthropic, Google,
+ * AWS, OpenRouter, etc. are long-lived secrets with catastrophic
+ * blast radius if leaked into a tool result, an LLM prompt, or a
+ * log line. The legacy `ProvidersManager.getDirectConfig(name)`
+ * returns the raw key in an object — every caller that touches
+ * that object now has the key on its stack, in error messages,
+ * in telemetry, and in crash dumps.
+ *
+ * The fix: a {@link ProviderKeyVault} that owns the credentials
+ * in a private, read-only `Map` and exposes them **only** inside
+ * a scoped executor block. Outside the block, the vault reveals
+ * nothing but metadata (provider names, presence, count). There
+ * is no `getApiKey`, no `peek`, no `toJSON`. The only way to
+ * read a key is to hand a callback to the vault, and the key
+ * is never visible to the caller after the callback returns.
+ *
+ * The vault is in-memory and process-local; persistence is
+ * delegated to `ProvidersManager`, which calls `vault.ingest()`
+ * after a disk read. Test code can call `ingest()` directly with
+ * fixture credentials.
+ *
+ * The class is intentionally small (no `any`, no async-only
+ * fast paths) so the security boundary is auditable in one read.
+ */
+/** A scoped credential, exposed only inside a vault callback. */
+export interface ProviderCredential {
+    /** The provider name as it appears in `PROVIDER_REGISTRY`. */
+    readonly providerName: string;
+    /** The raw API key. Never log, never stringify, never serialise. */
+    readonly apiKey: string;
+    /** Provider base URL. */
+    readonly baseUrl: string;
+    /** Display name (e.g. "OpenAI"). */
+    readonly displayName: string;
+}
+/** Callback that receives a key. */
+export type KeyCallback<T> = (key: string) => Promise<T> | T;
+/** Callback that receives a full credential. */
+export type CredentialCallback<T> = (cred: ProviderCredential) => Promise<T> | T;
+/** Options for the vault. */
+export interface ProviderKeyVaultOptions {
+    /**
+     * When true (default), `ingest()` rejects empty / whitespace-only
+     * keys. Disable for tests that exercise the empty-key error path
+     * via direct construction.
+     */
+    rejectEmptyKeys?: boolean;
+}
+/** Thrown when a requested provider is not in the vault. */
+export declare class ProviderNotInVaultError extends Error {
+    readonly providerName: string;
+    constructor(providerName: string);
+}
+/** Thrown when ingest() is called with an empty / blank key. */
+export declare class EmptyKeyRejectedError extends Error {
+    constructor(providerName: string);
+}
+export declare class ProviderKeyVault {
+    #private;
+    constructor(options?: ProviderKeyVaultOptions);
+    /**
+     * Add or replace a credential. Existing entries for the same
+     * provider are silently overwritten; the old `ProviderCredential`
+     * is dropped, and the previous key becomes unreachable.
+     */
+    ingest(providerName: string, apiKey: string, baseUrl: string, displayName?: string): void;
+    /**
+     * True if the vault has a credential for the given provider.
+     * Safe to call from anywhere — does not leak the key.
+     */
+    hasProvider(providerName: string): boolean;
+    /** Number of providers currently in the vault. */
+    size(): number;
+    /** Sorted list of configured provider names. */
+    listProviderNames(): string[];
+    /**
+     * Resolve the provider name for a given model id by walking a
+     * caller-supplied resolver. The vault itself does not know the
+     * provider registry; callers pass a pure function so the vault
+     * stays a pure credential container.
+     *
+     * Returns the resolved provider name or null if `resolveModel`
+     * returned null.
+     */
+    providerForModel(model: string, resolveModel: (model: string) => string | null): string | null;
+    /**
+     * The ONLY way to read an API key. Pass a callback; the vault
+     * invokes it with the key as the sole argument. The key is
+     * never returned, never serialised, never assigned to a wider
+     * scope. If the provider is not configured, the callback is
+     * never called and {@link ProviderNotInVaultError} is thrown.
+     */
+    withApiKey<T>(providerName: string, fn: KeyCallback<T>): Promise<T>;
+    /**
+     * Synchronous variant of {@link withApiKey}. Throws if the
+     * callback returns a promise (use `withApiKey` for async).
+     */
+    withApiKeySync<T>(providerName: string, fn: KeyCallback<T>): T;
+    /**
+     * Like {@link withApiKey} but exposes the entire
+     * {@link ProviderCredential} (apiKey, baseUrl, displayName).
+     * Use this for the common "build a request to a provider" case
+     * where the URL is part of the credential surface.
+     */
+    withCredential<T>(providerName: string, fn: CredentialCallback<T>): Promise<T>;
+    /** Remove a single provider's credential. */
+    evict(providerName: string): boolean;
+    /** Remove every credential. Used by `/fixo vault:reset`. */
+    clearAll(): void;
+    /**
+     * Internal: build a `Headers`-shaped object for the provider
+     * using a callback. The callback receives the credential and
+     * returns a `Record<string, string>`. The callback is the only
+     * place where the key is materialised, and the returned object
+     * is owned by the caller (which can pass it to `fetch`).
+     */
+    buildAuthHeaders(providerName: string, builder: (cred: ProviderCredential) => Record<string, string>): Promise<Record<string, string>>;
+}
+export declare function getProviderKeyVault(): ProviderKeyVault;
+/** Test hook — drop the cached singleton. */
+export declare function resetProviderKeyVault(): void;
+//# sourceMappingURL=credential-vault.d.ts.map

package/dist/runtime/credential-vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-vault.d.ts","sourceRoot":"","sources":["../../src/runtime/credential-vault.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oCAAoC;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,oCAAoC;AACpC,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAC7D,gDAAgD;AAChD,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,kBAAkB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAEjF,6BAA6B;AAC7B,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAID,4DAA4D;AAC5D,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,SAAgB,YAAY,EAAE,MAAM,CAAC;gBACzB,YAAY,EAAE,MAAM;CAKjC;AAED,gEAAgE;AAChE,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,YAAY,EAAE,MAAM;CAIjC;AAID,qBAAa,gBAAgB;;gBAUf,OAAO,GAAE,uBAA4B;IAIjD;;;;OAIG;IACI,MAAM,CACX,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,GACnB,IAAI;IAeP;;;OAGG;IACI,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAIjD,kDAAkD;IAC3C,IAAI,IAAI,MAAM;IAIrB,gDAAgD;IACzC,iBAAiB,IAAI,MAAM,EAAE;IAIpC;;;;;;;;OAQG;IACI,gBAAgB,CACrB,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAC7C,MAAM,GAAG,IAAI;IAMhB;;;;;;OAMG;IACU,UAAU,CAAC,CAAC,EACvB,YAAY,EAAE,MAAM,EACpB,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC,GACjB,OAAO,CAAC,CAAC,CAAC;IAMb;;;OAGG;IACI,cAAc,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC;IAYrE;;;;;OAKG;IACU,cAAc,CAAC,CAAC,EAC3B,YAAY,EAAE,MAAM,EACpB,EAAE,EAAE,kBAAkB,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,CAAC,CAAC;IAMb,6CAA6C;IACtC,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAI3C,4DAA4D;IACrD,QAAQ,IAAI,IAAI;IAIvB;;;;;;OAMG;IACU,gBAAgB,CAC3B,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5D,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAKnC;AAYD,wBAAgB,mBAAmB,IAAI,gBAAgB,CAGtD;AAED,6CAA6C;AAC7C,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C"}

package/dist/runtime/credential-vault.js

@@ -0,0 +1,184 @@
+/**
+ * Restricted Credential Sandbox — Pillar 4 of the Phase 2 safety
+ * refactor. The problem: API keys for OpenAI, Anthropic, Google,
+ * AWS, OpenRouter, etc. are long-lived secrets with catastrophic
+ * blast radius if leaked into a tool result, an LLM prompt, or a
+ * log line. The legacy `ProvidersManager.getDirectConfig(name)`
+ * returns the raw key in an object — every caller that touches
+ * that object now has the key on its stack, in error messages,
+ * in telemetry, and in crash dumps.
+ *
+ * The fix: a {@link ProviderKeyVault} that owns the credentials
+ * in a private, read-only `Map` and exposes them **only** inside
+ * a scoped executor block. Outside the block, the vault reveals
+ * nothing but metadata (provider names, presence, count). There
+ * is no `getApiKey`, no `peek`, no `toJSON`. The only way to
+ * read a key is to hand a callback to the vault, and the key
+ * is never visible to the caller after the callback returns.
+ *
+ * The vault is in-memory and process-local; persistence is
+ * delegated to `ProvidersManager`, which calls `vault.ingest()`
+ * after a disk read. Test code can call `ingest()` directly with
+ * fixture credentials.
+ *
+ * The class is intentionally small (no `any`, no async-only
+ * fast paths) so the security boundary is auditable in one read.
+ */
+/* ──────────────────────── Errors ──────────────────────── */
+/** Thrown when a requested provider is not in the vault. */
+export class ProviderNotInVaultError extends Error {
+    providerName;
+    constructor(providerName) {
+        super(`ProviderKeyVault: no credential for "${providerName}"`);
+        this.name = 'ProviderNotInVaultError';
+        this.providerName = providerName;
+    }
+}
+/** Thrown when ingest() is called with an empty / blank key. */
+export class EmptyKeyRejectedError extends Error {
+    constructor(providerName) {
+        super(`ProviderKeyVault: refused to ingest empty key for "${providerName}"`);
+        this.name = 'EmptyKeyRejectedError';
+    }
+}
+/* ──────────────────────── ProviderKeyVault ──────────────────────── */
+export class ProviderKeyVault {
+    /**
+     * Backing store. Marked `readonly` so a misbehaving consumer
+     * cannot reassign the map, but the map itself is private so
+     * the `ProviderCredential` objects are unreachable from
+     * outside the class.
+     */
+    #store = new Map();
+    #rejectEmpty;
+    constructor(options = {}) {
+        this.#rejectEmpty = options.rejectEmptyKeys ?? true;
+    }
+    /**
+     * Add or replace a credential. Existing entries for the same
+     * provider are silently overwritten; the old `ProviderCredential`
+     * is dropped, and the previous key becomes unreachable.
+     */
+    ingest(providerName, apiKey, baseUrl, displayName) {
+        if (!providerName) {
+            throw new Error('ProviderKeyVault.ingest: providerName is required');
+        }
+        if (this.#rejectEmpty && (!apiKey || !apiKey.trim())) {
+            throw new EmptyKeyRejectedError(providerName);
+        }
+        this.#store.set(providerName, {
+            providerName,
+            apiKey,
+            baseUrl,
+            displayName: displayName ?? providerName,
+        });
+    }
+    /**
+     * True if the vault has a credential for the given provider.
+     * Safe to call from anywhere — does not leak the key.
+     */
+    hasProvider(providerName) {
+        return this.#store.has(providerName);
+    }
+    /** Number of providers currently in the vault. */
+    size() {
+        return this.#store.size;
+    }
+    /** Sorted list of configured provider names. */
+    listProviderNames() {
+        return Array.from(this.#store.keys()).sort();
+    }
+    /**
+     * Resolve the provider name for a given model id by walking a
+     * caller-supplied resolver. The vault itself does not know the
+     * provider registry; callers pass a pure function so the vault
+     * stays a pure credential container.
+     *
+     * Returns the resolved provider name or null if `resolveModel`
+     * returned null.
+     */
+    providerForModel(model, resolveModel) {
+        const name = resolveModel(model);
+        if (!name)
+            return null;
+        return this.#store.has(name) ? name : null;
+    }
+    /**
+     * The ONLY way to read an API key. Pass a callback; the vault
+     * invokes it with the key as the sole argument. The key is
+     * never returned, never serialised, never assigned to a wider
+     * scope. If the provider is not configured, the callback is
+     * never called and {@link ProviderNotInVaultError} is thrown.
+     */
+    async withApiKey(providerName, fn) {
+        const cred = this.#store.get(providerName);
+        if (!cred)
+            throw new ProviderNotInVaultError(providerName);
+        return await fn(cred.apiKey);
+    }
+    /**
+     * Synchronous variant of {@link withApiKey}. Throws if the
+     * callback returns a promise (use `withApiKey` for async).
+     */
+    withApiKeySync(providerName, fn) {
+        const cred = this.#store.get(providerName);
+        if (!cred)
+            throw new ProviderNotInVaultError(providerName);
+        const result = fn(cred.apiKey);
+        if (result instanceof Promise) {
+            throw new Error('ProviderKeyVault.withApiKeySync: callback returned a Promise; use withApiKey() instead');
+        }
+        return result;
+    }
+    /**
+     * Like {@link withApiKey} but exposes the entire
+     * {@link ProviderCredential} (apiKey, baseUrl, displayName).
+     * Use this for the common "build a request to a provider" case
+     * where the URL is part of the credential surface.
+     */
+    async withCredential(providerName, fn) {
+        const cred = this.#store.get(providerName);
+        if (!cred)
+            throw new ProviderNotInVaultError(providerName);
+        return await fn(cred);
+    }
+    /** Remove a single provider's credential. */
+    evict(providerName) {
+        return this.#store.delete(providerName);
+    }
+    /** Remove every credential. Used by `/fixo vault:reset`. */
+    clearAll() {
+        this.#store.clear();
+    }
+    /**
+     * Internal: build a `Headers`-shaped object for the provider
+     * using a callback. The callback receives the credential and
+     * returns a `Record<string, string>`. The callback is the only
+     * place where the key is materialised, and the returned object
+     * is owned by the caller (which can pass it to `fetch`).
+     */
+    async buildAuthHeaders(providerName, builder) {
+        const cred = this.#store.get(providerName);
+        if (!cred)
+            throw new ProviderNotInVaultError(providerName);
+        return builder(cred);
+    }
+}
+/* ──────────────────────── Process-wide singleton ─────────────────── */
+/**
+ * Process-wide vault singleton. Lazily created on first call to
+ * {@link getProviderKeyVault}. Tests that need an isolated vault
+ * should construct their own {@link ProviderKeyVault} directly
+ * and use it without going through this singleton.
+ */
+let cachedVault = null;
+export function getProviderKeyVault() {
+    if (!cachedVault)
+        cachedVault = new ProviderKeyVault();
+    return cachedVault;
+}
+/** Test hook — drop the cached singleton. */
+export function resetProviderKeyVault() {
+    cachedVault = null;
+}
+//# sourceMappingURL=credential-vault.js.map

package/dist/runtime/credential-vault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-vault.js","sourceRoot":"","sources":["../../src/runtime/credential-vault.ts"],"names":[],"mappings":"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"}