zk-credits 0.2.0 → 0.2.2

package/dist/cli.js

@@ -2,10 +2,11 @@
 import { homedir } from 'node:os';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
 import { launchCodexProcess } from './codex-launcher.js';
 import { launchClineProcess } from './cline-launcher.js';
 import { isCodexProfileInstalled, resolveCodexHome, writeCodexProfile, } from './codex-profile.js';
-import { createBasePrepaidClient, createFileWitnessProvider } from './base-sidecar.js';
+import { createBasePrepaidClient, createFileWitnessProvider, validateBaseCreditWitness } from './base-sidecar.js';
 import { createBaseEventWitnessProvider } from './base-event-sync.js';
 import { createPinnedBaseProofGenerator } from './proof-coordinator.js';
 import { createBaseProofMetrics } from './proof-metrics.js';
@@ -16,14 +17,26 @@ import { runCliCommand } from './cli-runtime.js';
 import { createNodeSidecarLifecycle } from './node-sidecar-lifecycle.js';
 import { activateSidecarServer } from './server-startup.js';
 import { createLoopbackToken, sidecarStatePaths } from './sidecar-config.js';
+import { applySetupConfig, readSetupConfig, resolveSetupInputs, writeSetupConfig, } from './setup-config.js';
 import { ensureSidecarReady } from './sidecar-lifecycle.js';
 import { readLoopbackToken, writeLoopbackToken } from './sidecar-state.js';
 import { createSidecarServer } from './sidecar.js';
+import { runBaseRegisteredTrialExchange } from './base-registered-trial.js';
+import { loadCircuitManifest } from './artifact-bundle.js';
+import { BASE_SEPOLIA_NETWORK } from '@zk-credits/x402-zk-prepaid';
 const DEFAULT_GATEWAY_URL = 'https://zk-credits-gateway.onrender.com';
 const DEFAULT_PORT = 3210;
 function stateDirectory() {
     return process.env.ZK_CREDITS_HOME || join(homedir(), '.zk-credits');
 }
+function setupConfigPath(directory = stateDirectory()) {
+    return join(directory, 'config.json');
+}
+async function applySavedSetupConfig(environment, directory = stateDirectory()) {
+    const config = await readSetupConfig(setupConfigPath(directory));
+    if (config)
+        applySetupConfig(environment, config);
+}
 function loopbackBaseUrl() {
     const port = Number(process.env.ZK_CREDITS_SIDECAR_PORT || DEFAULT_PORT);
     if (!Number.isInteger(port) || port < 1 || port > 65535) {
@@ -41,6 +54,58 @@ function readPort(args) {
     }
     return parsed;
 }
+async function chooseSetupCandidate(kind, candidates) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        const variable = kind === 'proving bundle' ? 'ZK_CREDITS_ARTIFACT_DIR' : 'ZK_CREDITS_WITNESS_PATH';
+        throw new Error('Found more than one valid local ' + kind + '. Rerun in an interactive terminal or set ' + variable + ' explicitly.');
+    }
+    const input = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        console.log('Found multiple valid ' + kind + 's:');
+        candidates.forEach((candidate, index) => console.log('  ' + (index + 1) + ') ' + candidate));
+        const answer = await input.question('Select a number: ');
+        const index = Number(answer);
+        if (!Number.isInteger(index) || index < 1 || index > candidates.length) {
+            throw new Error('Choose one of the listed local candidates');
+        }
+        return candidates[index - 1];
+    }
+    finally {
+        input.close();
+    }
+}
+async function witnessProviderForSource(source, cachePath) {
+    if (source.kind === 'file') {
+        let value;
+        try {
+            value = JSON.parse(await readFile(source.path, 'utf8'));
+        }
+        catch {
+            throw new Error('The Base witness file could not be read as JSON');
+        }
+        return createFileWitnessProvider(value);
+    }
+    return createBaseEventWitnessProvider({
+        rpcUrl: source.rpcUrl,
+        contractAddress: source.contractAddress,
+        deploymentBlock: source.deploymentBlock === undefined ? undefined : BigInt(source.deploymentBlock),
+        confirmations: source.confirmations === undefined ? undefined : BigInt(source.confirmations),
+        cachePath,
+    });
+}
+/** Reads a password written to the private stdin pipe by the foreground CLI. */
+async function readCredentialPasswordFromStdin() {
+    const chunks = [];
+    let byteLength = 0;
+    for await (const chunk of process.stdin) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        byteLength += bytes.length;
+        if (byteLength > 4096)
+            throw new Error('Credential password input is too long');
+        chunks.push(bytes);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
 /** Reads a credential backup password from a TTY without terminal echo or shell history. */
 async function readHiddenValue(prompt) {
     if (!process.stdin.isTTY || !process.stdin.setRawMode) {
@@ -54,6 +119,7 @@ async function readHiddenValue(prompt) {
         const done = (error) => {
             process.stdin.off('data', onData);
             process.stdin.setRawMode(false);
+            process.stdin.pause();
             process.stdout.write('\n');
             if (error)
                 reject(error);
@@ -98,30 +164,34 @@ function printHelp() {
   zk-credits codex [codex arguments...]
   zk-credits status
   zk-credits serve [--port <port>]
+  zk-credits trial-registered-adapter
   eval "$(zk-credits env)"
 
 "zk-credits cline" and the Codex companion configure and launch coding agents
-against the x402 zk-prepaid loopback sidecar. The pilot serves non-streaming
-POST /v1/chat/completions only.
-Set ZK_CREDITS_CREDENTIAL_PATH, ZK_CREDITS_CREDENTIAL_PASSWORD, and
-ZK_CREDITS_ARTIFACT_DIR for a headless process. The encrypted export is
-decrypted only in local memory.`);
+against the x402 zk-prepaid loopback sidecar. The gateway spend path is
+non-streaming POST /v1/chat/completions; Codex Responses requests pass through
+the sidecar's bounded local compatibility bridge.
+"zk-credits trial-registered-adapter" runs one confirmed, billable internal
+trial request through the directly registered official x402 client adapter.
+Set ZK_CREDITS_CREDENTIAL_PATH before setup. The wizard searches Downloads and
+~/.zk-credits for the pinned bundle and local Base witness, validates both,
+then saves their paths locally. Alternatively, set ZK_CREDITS_ARTIFACT_DIR and
+ZK_CREDITS_WITNESS_PATH explicitly. Setup prompts for the credential password
+without echo; the encrypted export is decrypted only in local memory.`);
 }
-async function serve(args) {
-    const port = readPort(args);
-    const statePaths = sidecarStatePaths(stateDirectory());
-    const localToken = createLoopbackToken();
+/** Loads the same credential, witness, proof, and durable ledger used by serve. */
+async function loadBaseClientRuntime(passwordInput) {
     const credentialPath = process.env.ZK_CREDITS_CREDENTIAL_PATH;
     if (!credentialPath)
         throw new Error('Set ZK_CREDITS_CREDENTIAL_PATH to the encrypted browser export');
-    const password = process.env.ZK_CREDITS_CREDENTIAL_PASSWORD ?? await readHiddenValue('Credential backup password: ');
+    const password = passwordInput ?? await readHiddenValue('Credential backup password: ');
     const credential = await readEncryptedCredential(credentialPath, password);
     const witnessPath = process.env.ZK_CREDITS_WITNESS_PATH;
     const artifactDirectory = process.env.ZK_CREDITS_ARTIFACT_DIR;
     if (!artifactDirectory) {
         throw new Error('Set ZK_CREDITS_ARTIFACT_DIR to the directory holding the installed pinned proving bundle');
     }
-    const witness = witnessPath
+    const witnessProvider = witnessPath
         ? createFileWitnessProvider(JSON.parse(await readFile(witnessPath, 'utf8')))
         : process.env.BASE_RPC_URL && process.env.BASE_PRIVATE_CREDIT_BOND_ADDRESS
             ? createBaseEventWitnessProvider({
@@ -136,14 +206,290 @@ async function serve(args) {
     const exchangeMetrics = createZkPrepaidLifecycleMetrics();
     const slotLedger = await BaseSlotLedger.open({ path: join(stateDirectory(), 'base-slots.json') });
     const prove = await createPinnedBaseProofGenerator({ artifactDirectory, metrics: proofMetrics });
+    validateBaseCreditWitness(await witnessProvider.witnessForCredential(credential));
+    return { credential, witnessProvider, slotLedger, proofMetrics, exchangeMetrics, prove };
+}
+const GATEWAY_COUNTER_NAMES = [
+    'challenge_issued',
+    'proof_valid',
+    'proof_invalid',
+    'reservation_new',
+    'reservation_existing',
+    'claim_committed',
+    'claim_cancelled',
+    'claim_replayed',
+    'claim_conflict',
+    'dispatch_ok',
+    'dispatch_error',
+    'dispatch_timeout',
+    'cap_exhausted_utc_day',
+    'cap_exhausted_rolling_30d',
+    'paused_rejected',
+    'request_rejected',
+];
+const GATEWAY_CLAIM_COUNT_NAMES = ['reserved', 'ready', 'committed', 'cancelled'];
+const GATEWAY_READINESS_CHECK_NAMES = new Set(['launchControl', 'database', 'baseRoot', 'baseRpc', 'verifierAssets', 'provider']);
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function safeCount(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+function gatewayOrigin() {
+    const origin = new URL(process.env.ZK_CREDITS_GATEWAY_URL || DEFAULT_GATEWAY_URL);
+    if (origin.protocol !== 'https:' || origin.username || origin.password || origin.search || origin.hash || origin.pathname !== '/') {
+        throw new Error('The internal trial requires a plain HTTPS gateway origin');
+    }
+    return origin;
+}
+async function readGatewayJson(url, headers) {
+    try {
+        const response = await fetch(url, { headers, signal: AbortSignal.timeout(10_000) });
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            body = undefined;
+        }
+        return { status: response.status, body };
+    }
+    catch {
+        return { status: null };
+    }
+}
+async function gatewayReadiness(origin) {
+    const response = await readGatewayJson(new URL('/ready', origin), { accept: 'application/json' });
+    const report = isRecord(response.body) ? response.body : undefined;
+    const checks = Array.isArray(report?.checks) ? report.checks : [];
+    const failedChecks = checks.flatMap((check) => (isRecord(check) && check.ok === true
+        ? []
+        : [isRecord(check) && typeof check.name === 'string' && GATEWAY_READINESS_CHECK_NAMES.has(check.name) ? check.name : 'unknown']));
+    const hasLaunchCheck = checks.some((check) => isRecord(check) && check.name === 'launchControl' && check.ok === true);
+    return {
+        status: response.status,
+        passed: response.status === 200 && report?.ready === true && failedChecks.length === 0 && hasLaunchCheck,
+        failedChecks,
+    };
+}
+async function gatewayTrialSnapshot(origin, token) {
+    const response = await readGatewayJson(new URL('/v1/admin/status', origin), {
+        accept: 'application/json',
+        authorization: `Bearer ${token}`,
+    });
+    const body = isRecord(response.body) ? response.body : undefined;
+    const launch = isRecord(body?.launchControl) ? body.launchControl : undefined;
+    const base = isRecord(body?.base) ? body.base : undefined;
+    const spend = isRecord(body?.spend) ? body.spend : undefined;
+    const rawMetrics = isRecord(body?.metrics) ? body.metrics : undefined;
+    const rawClaims = isRecord(body?.claims) ? body.claims : undefined;
+    const metrics = {};
+    const claims = {};
+    let countersValid = Boolean(rawMetrics && rawClaims);
+    for (const name of GATEWAY_COUNTER_NAMES) {
+        const count = safeCount(rawMetrics?.[name]);
+        if (count === undefined)
+            countersValid = false;
+        else
+            metrics[name] = count;
+    }
+    for (const name of GATEWAY_CLAIM_COUNT_NAMES) {
+        const count = safeCount(rawClaims?.[name]);
+        if (count !== undefined)
+            claims[name] = count;
+        else
+            countersValid = false;
+    }
+    const headroom = (value) => typeof value === 'string' && /^\d+$/u.test(value) && BigInt(value) > 0n;
+    const currentRoot = typeof base?.currentRoot === 'string' && base.currentRoot.length > 0 ? base.currentRoot : undefined;
+    const knownRoot = currentRoot !== undefined;
+    const lag = typeof base?.lagBlocks === 'string' && /^\d+$/u.test(base.lagBlocks) ? BigInt(base.lagBlocks) : undefined;
+    const snapshot = countersValid && currentRoot ? { metrics, claims, currentRoot } : undefined;
+    return {
+        status: response.status,
+        ...(snapshot ? { snapshot } : {}),
+        gatePassed: response.status === 200
+            && body?.network === BASE_SEPOLIA_NETWORK
+            && launch?.state === 'enabled'
+            && knownRoot
+            && safeCount(base?.knownRootCount) !== undefined
+            && (safeCount(base?.knownRootCount) ?? 0) > 0
+            && lag !== undefined
+            && lag <= 300n
+            && headroom(spend?.dailyHeadroomMicroUsd)
+            && headroom(spend?.rollingHeadroomMicroUsd)
+            && countersValid,
+    };
+}
+async function confirmDirectTrial() {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        throw new Error('the internal trial requires a local interactive terminal');
+    const input = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await input.question('Confirm local recovery completed, this slot ledger was not copied to another client, one credit remains, and you approve one billable internal exchange. Type RUN ONE INTERNAL EXCHANGE: ');
+        return answer.trim() === 'RUN ONE INTERNAL EXCHANGE';
+    }
+    finally {
+        input.close();
+    }
+}
+function gatewayCounterDelta(before, after) {
+    return {
+        metrics: Object.fromEntries(GATEWAY_COUNTER_NAMES.map((name) => [name, after.metrics[name] - before.metrics[name]])),
+        claims: Object.fromEntries(GATEWAY_CLAIM_COUNT_NAMES.map((name) => [name, after.claims[name] - before.claims[name]])),
+    };
+}
+async function trialRegisteredAdapter() {
+    if (!await confirmDirectTrial()) {
+        console.log(JSON.stringify({ path: 'registered-adapter', status: 'not_run' }));
+        return;
+    }
+    try {
+        const runtime = await loadBaseClientRuntime();
+        if (runtime.credential.tierId !== 0
+            || runtime.credential.deploymentDomain !== '84532'
+            || runtime.credential.expiry <= Math.floor(Date.now() / 1000)) {
+            console.log(JSON.stringify({ path: 'registered-adapter', status: 'stopped', failurePhase: 'credential_gate' }));
+            return;
+        }
+        const startingSlots = runtime.slotLedger.snapshot();
+        if (startingSlots.committed >= startingSlots.capacity) {
+            console.log(JSON.stringify({
+                path: 'registered-adapter',
+                status: 'stopped',
+                failurePhase: 'local_credit_gate',
+                localCredits: { capacity: startingSlots.capacity, committed: startingSlots.committed, available: 0 },
+            }));
+            return;
+        }
+        const gateway = gatewayOrigin();
+        const adminToken = process.env.BILLING_INTERNAL_TOKEN || await readHiddenValue('Gateway admin token: ');
+        if (!adminToken.trim()) {
+            console.log(JSON.stringify({ path: 'registered-adapter', status: 'stopped', failurePhase: 'admin_auth' }));
+            return;
+        }
+        const lifecycle = createNodeSidecarLifecycle({
+            loopbackBaseUrl: loopbackBaseUrl(),
+            stateDirectory: stateDirectory(),
+            tokenPath: sidecarStatePaths(stateDirectory()).tokenPath,
+            logPath: sidecarStatePaths(stateDirectory()).logPath,
+            cliEntryPath: process.argv[1] ?? '',
+        });
+        const codexHome = resolveCodexHome(process.env, homedir());
+        const [sidecarRunning, codexProfileInstalled] = await Promise.all([
+            lifecycle.isHealthy(),
+            isCodexProfileInstalled(codexHome),
+        ]);
+        const launcherStatus = { codexProfileInstalled, sidecarRunning };
+        if (sidecarRunning) {
+            console.log(JSON.stringify({ path: 'registered-adapter', status: 'stopped', failurePhase: 'sidecar_running', launcherStatus }));
+            return;
+        }
+        const witness = await runtime.witnessProvider.witnessForCredential(runtime.credential);
+        const readiness = await gatewayReadiness(gateway);
+        if (!readiness.passed) {
+            console.log(JSON.stringify({ path: 'registered-adapter', status: 'stopped', failurePhase: 'readiness', launcherStatus, readiness }));
+            return;
+        }
+        const adminBefore = await gatewayTrialSnapshot(gateway, adminToken);
+        if (!adminBefore.gatePassed || !adminBefore.snapshot) {
+            console.log(JSON.stringify({ path: 'registered-adapter', status: 'stopped', failurePhase: 'admin_status', launcherStatus, readiness, adminStatus: adminBefore.status }));
+            return;
+        }
+        if (witness.root !== adminBefore.snapshot.currentRoot) {
+            console.log(JSON.stringify({ path: 'registered-adapter', status: 'stopped', failurePhase: 'root_mismatch', launcherStatus, readiness, adminStatus: adminBefore.status }));
+            return;
+        }
+        const baselineSlots = runtime.slotLedger.snapshot();
+        const baselineProof = runtime.proofMetrics.snapshot();
+        const baselineLifecycle = runtime.exchangeMetrics.snapshot();
+        const requestUrl = new URL('/v1/chat/completions', gateway).toString();
+        const requestBody = JSON.stringify({
+            model: 'deepseek/deepseek-v4-flash',
+            messages: [{ role: 'user', content: 'Reply with exactly: internal trial complete.' }],
+            stream: false,
+        });
+        const exchange = await runBaseRegisteredTrialExchange({
+            url: requestUrl,
+            body: requestBody,
+            headers: { 'content-type': 'application/json' },
+            credential: runtime.credential,
+            witnessProvider: runtime.witnessProvider,
+            prove: runtime.prove,
+            slotLedger: runtime.slotLedger,
+            lifecycle: runtime.exchangeMetrics.observe,
+        });
+        const adminAfter = await gatewayTrialSnapshot(gateway, adminToken);
+        const proofAfter = runtime.proofMetrics.snapshot();
+        const lifecycleAfter = runtime.exchangeMetrics.snapshot();
+        const slotAfter = runtime.slotLedger.snapshot();
+        const localDeltas = {
+            proofAttempts: proofAfter.attempts - baselineProof.attempts,
+            proofSuccesses: proofAfter.successes - baselineProof.successes,
+            proofFailures: proofAfter.failures - baselineProof.failures,
+            challengesReceived: lifecycleAfter.challengesReceived - baselineLifecycle.challengesReceived,
+            paymentsPrepared: lifecycleAfter.paymentsPrepared - baselineLifecycle.paymentsPrepared,
+            settlementsConfirmed: lifecycleAfter.settlementsConfirmed - baselineLifecycle.settlementsConfirmed,
+            exchangeSuccesses: lifecycleAfter.exchangeSuccesses - baselineLifecycle.exchangeSuccesses,
+            exchangeFailures: lifecycleAfter.failures - baselineLifecycle.failures,
+            committedSlots: slotAfter.committed - baselineSlots.committed,
+        };
+        const counterDelta = adminAfter.snapshot ? gatewayCounterDelta(adminBefore.snapshot, adminAfter.snapshot) : undefined;
+        const expectedGatewayCounters = ['challenge_issued', 'proof_valid', 'reservation_new', 'claim_committed', 'dispatch_ok'];
+        const gatewayCountersMatch = Boolean(counterDelta)
+            && expectedGatewayCounters.every((name) => counterDelta.metrics[name] === 1)
+            && Object.entries(counterDelta?.metrics ?? {}).every(([name, value]) => expectedGatewayCounters.includes(name) || value === 0)
+            && (counterDelta?.claims.committed === 1)
+            && Object.entries(counterDelta?.claims ?? {}).every(([name, value]) => name === 'committed' || value === 0);
+        const failurePhase = exchange.failurePhase
+            ?? (!exchange.responseSucceeded ? 'response_not_ok' : undefined)
+            ?? (adminAfter.status !== 200 || !adminAfter.snapshot ? 'postflight_admin_status' : undefined)
+            ?? (!gatewayCountersMatch ? 'gateway_counter_delta' : undefined);
+        console.log(JSON.stringify({
+            path: 'registered-adapter',
+            readiness: { status: readiness.status, passed: readiness.passed, failedChecks: readiness.failedChecks },
+            launcherStatus,
+            adminStatus: { before: adminBefore.status, after: adminAfter.status },
+            localCredits: {
+                capacity: baselineSlots.capacity,
+                committedBefore: baselineSlots.committed,
+                committedAfter: slotAfter.committed,
+                availableBefore: baselineSlots.capacity - baselineSlots.committed,
+                availableAfter: slotAfter.capacity - slotAfter.committed,
+            },
+            exchange: {
+                challengeStatus: exchange.challengeStatus,
+                challengeReceived: exchange.challengeReceived,
+                proofPrepared: exchange.proofPrepared,
+                paymentSignatureSent: exchange.paymentSignatureSent,
+                paymentStatus: exchange.paymentStatus,
+                paymentResponseConfirmed: exchange.paymentResponseConfirmed,
+                responseStatus: exchange.responseStatus,
+                responseSucceeded: exchange.responseSucceeded,
+                committedSlotDelta: exchange.committedSlotDelta,
+            },
+            localCounterDelta: localDeltas,
+            gatewayCounterDelta: counterDelta ?? null,
+            failurePhase,
+        }));
+    }
+    catch {
+        console.log(JSON.stringify({ path: 'registered-adapter', status: 'stopped', failurePhase: 'local_setup' }));
+    }
+}
+async function serve(args, passwordInput) {
+    const port = readPort(args);
+    const statePaths = sidecarStatePaths(stateDirectory());
+    const localToken = createLoopbackToken();
+    const { credential, witnessProvider, proofMetrics, exchangeMetrics, slotLedger, prove } = await loadBaseClientRuntime(passwordInput);
     const prepaid = createBasePrepaidClient({
         credential,
-        witnessProvider: witness,
+        witnessProvider,
         prove,
         slotLedger,
         lifecycle: exchangeMetrics.observe,
     });
-    const gatewayBaseUrl = process.env.ZK_CREDITS_GATEWAY_URL || 'http://127.0.0.1:3001';
+    const gatewayBaseUrl = process.env.ZK_CREDITS_GATEWAY_URL || DEFAULT_GATEWAY_URL;
     const sidecar = createSidecarServer({
         localToken,
         gatewayBaseUrl,
@@ -176,22 +522,41 @@ async function main() {
         printHelp();
         return;
     }
+    const sidecarHome = stateDirectory();
+    if (args[0] !== 'setup' && args[0] !== 'status' && args[0] !== 'env') {
+        await applySavedSetupConfig(process.env, sidecarHome);
+    }
     if (args[0] === 'serve') {
-        await serve(args.slice(1));
+        const passwordFromStdin = args.includes('--credential-password-stdin')
+            ? await readCredentialPasswordFromStdin()
+            : undefined;
+        await serve(args.slice(1).filter((argument) => argument !== '--credential-password-stdin'), passwordFromStdin);
+        return;
+    }
+    if (args[0] === 'trial-registered-adapter') {
+        await trialRegisteredAdapter();
         return;
     }
-    const sidecarHome = stateDirectory();
     const statePaths = sidecarStatePaths(sidecarHome);
     const codexHome = resolveCodexHome(process.env, homedir());
     const cliEntryPath = process.argv[1];
     if (!cliEntryPath)
         throw new Error('Unable to resolve the zk-credits executable path');
+    let setupCredentialPassword;
     const lifecycle = createNodeSidecarLifecycle({
         loopbackBaseUrl: loopbackBaseUrl(),
         stateDirectory: sidecarHome,
         tokenPath: statePaths.tokenPath,
         logPath: statePaths.logPath,
         cliEntryPath,
+        readCredentialPassword: async () => {
+            if (setupCredentialPassword !== undefined) {
+                const password = setupCredentialPassword;
+                setupCredentialPassword = undefined;
+                return password;
+            }
+            return readHiddenValue('Credential backup password: ');
+        },
     });
     const exitCode = await runCliCommand(args, {
         loopbackBaseUrl: loopbackBaseUrl(),
@@ -209,6 +574,43 @@ async function main() {
                 return false;
             }
         },
+        validateSetupPrerequisites: async () => {
+            const credentialPath = process.env.ZK_CREDITS_CREDENTIAL_PATH;
+            if (!credentialPath?.trim())
+                throw new Error('Set ZK_CREDITS_CREDENTIAL_PATH to the encrypted browser export');
+            const password = await readHiddenValue('Credential backup password: ');
+            const credential = await readEncryptedCredential(credentialPath, password);
+            const manifest = await loadCircuitManifest();
+            const config = await resolveSetupInputs({
+                environment: process.env,
+                homeDirectory: homedir(),
+                stateDirectory: sidecarHome,
+                configPath: setupConfigPath(sidecarHome),
+                manifest,
+                validateWitness: async (source) => {
+                    const provider = await witnessProviderForSource(source, join(stateDirectory(), 'base-event-sync.json'));
+                    validateBaseCreditWitness(await provider.witnessForCredential(credential));
+                },
+                chooseCandidate: chooseSetupCandidate,
+            });
+            const artifactDirectory = config.artifactDirectory;
+            try {
+                await createPinnedBaseProofGenerator({
+                    artifactDirectory,
+                    metrics: createBaseProofMetrics(),
+                });
+            }
+            catch (error) {
+                if (error instanceof Error)
+                    throw new Error(`Pinned proving bundle check failed: ${error.message}`);
+                throw new Error('Pinned proving bundle check failed. Reinstall the bundle from your pilot invite.');
+            }
+            await writeSetupConfig(setupConfigPath(sidecarHome), config);
+            applySetupConfig(process.env, config);
+            setupCredentialPassword = password;
+            console.log('Pinned proving bundle and witness validated for this activated credential.');
+            console.log('Local setup paths saved to ' + setupConfigPath(sidecarHome));
+        },
         configureCodex: async (model) => {
             await writeCodexProfile({ codexHome, loopbackBaseUrl: loopbackBaseUrl(), model });
         },

package/dist/node-sidecar-lifecycle.d.ts

@@ -4,6 +4,7 @@ export interface DetachedSidecarProcess {
     args: readonly string[];
     env: NodeJS.ProcessEnv;
     logPath: string;
+    stdin?: string;
 }
 export interface NodeSidecarLifecycleOptions {
     loopbackBaseUrl: string;
@@ -11,6 +12,7 @@ export interface NodeSidecarLifecycleOptions {
     tokenPath: string;
     logPath: string;
     cliEntryPath: string;
+    readCredentialPassword?: () => Promise<string>;
 }
 export interface NodeSidecarLifecycleRuntime {
     fetchHealth(url: string): Promise<Response>;

package/dist/node-sidecar-lifecycle.js

@@ -2,6 +2,24 @@ import { spawn } from 'node:child_process';
 import { chmod, mkdir, open } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { readLoopbackToken } from './sidecar-state.js';
+const CHILD_ENVIRONMENT_KEYS = [
+    'HOME', 'PATH', 'TMP', 'TEMP', 'TMPDIR', 'LANG', 'LC_ALL', 'TZ',
+    'SystemRoot', 'WINDIR', 'COMSPEC', 'PATHEXT',
+    'ZK_CREDITS_CREDENTIAL_PATH', 'ZK_CREDITS_ARTIFACT_DIR', 'ZK_CREDITS_WITNESS_PATH',
+    'ZK_CREDITS_GATEWAY_URL', 'BASE_RPC_URL', 'BASE_PRIVATE_CREDIT_BOND_ADDRESS',
+    'BASE_DEPLOYMENT_BLOCK', 'BASE_CONFIRMATIONS',
+];
+function sidecarEnvironment(stateDirectory, port) {
+    const environment = {};
+    for (const key of CHILD_ENVIRONMENT_KEYS) {
+        const value = process.env[key];
+        if (value !== undefined)
+            environment[key] = value;
+    }
+    environment.ZK_CREDITS_HOME = stateDirectory;
+    environment.ZK_CREDITS_SIDECAR_PORT = port;
+    return environment;
+}
 async function startDetachedProcess(specification) {
     await mkdir(dirname(specification.logPath), { recursive: true, mode: 0o700 });
     const log = await open(specification.logPath, 'a', 0o600);
@@ -10,12 +28,16 @@ async function startDetachedProcess(specification) {
         const child = spawn(specification.executable, specification.args, {
             detached: true,
             env: specification.env,
-            stdio: ['ignore', log.fd, log.fd],
+            stdio: [specification.stdin === undefined ? 'ignore' : 'pipe', log.fd, log.fd],
         });
         await new Promise((resolve, reject) => {
             child.once('spawn', resolve);
             child.once('error', reject);
         });
+        if (specification.stdin !== undefined && child.stdin) {
+            child.stdin.on('error', () => undefined);
+            child.stdin.end(specification.stdin);
+        }
         child.unref();
     }
     finally {
@@ -48,15 +70,15 @@ export function createNodeSidecarLifecycle(options, runtime = defaultRuntime) {
             }
         },
         async startDetached() {
+            if (!options.readCredentialPassword)
+                throw new Error('Credential password prompt is unavailable');
+            const password = await options.readCredentialPassword();
             await runtime.startDetachedProcess({
                 executable: process.execPath,
-                args: [options.cliEntryPath, 'serve', '--port', url.port],
-                env: {
-                    ...process.env,
-                    ZK_CREDITS_HOME: options.stateDirectory,
-                    ZK_CREDITS_SIDECAR_PORT: url.port,
-                },
+                args: [options.cliEntryPath, 'serve', '--port', url.port, '--credential-password-stdin'],
+                env: sidecarEnvironment(options.stateDirectory, url.port),
                 logPath: options.logPath,
+                stdin: password,
             });
         },
         readToken: () => readLoopbackToken(options.tokenPath),

package/dist/responses-bridge.d.ts

@@ -0,0 +1,14 @@
+type JsonRecord = Record<string, unknown>;
+export type ResponsesTranslation = {
+    ok: true;
+    chatRequest: JsonRecord;
+    responseModel: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** Converts the small Responses surface emitted by Codex into the fixed Chat Completions request. */
+export declare function translateResponsesRequest(body: unknown): ResponsesTranslation;
+/** Builds the Responses SSE event sequence from one committed Chat Completions result. */
+export declare function responsesEventStream(chatValue: unknown, model: string): string;
+export {};