@counterfact-labs/cli 0.1.2 → 0.2.3

package/dist/cli/sign-in-input.js

@@ -0,0 +1,97 @@
+import { createInterface } from "node:readline";
+import { PassThrough } from "node:stream";
+export function terminalSignInInput(input = process.stdin, output = process.stdout) {
+    const adapter = {
+        get isTerminal() { return input.isTTY === true && output.isTTY === true; },
+        async readCode(prompt, signal) {
+            if (signal?.aborted || !adapter.isTerminal || input.destroyed || input.readableEnded || output.destroyed || output.writableEnded)
+                return undefined;
+            if (!input.setRawMode)
+                return undefined;
+            const setRawMode = input.setRawMode.bind(input);
+            return new Promise(resolve => {
+                const wasRaw = input.isRaw === true;
+                const wasFlowing = input.readableFlowing === true;
+                // Keep readline's editing and keypress listeners off stdin, with no output to echo a code.
+                const hidden = new PassThrough();
+                const lines = createInterface({ input: hidden, terminal: true, historySize: 0 });
+                let finished = false;
+                let result;
+                const cancel = () => { result = undefined; finish(); };
+                const outputFailed = () => { cancel(); complete(); };
+                const forward = (chunk) => { hidden.write(chunk); };
+                function complete() {
+                    process.removeListener("SIGINT", cancel);
+                    signal?.removeEventListener("abort", cancel);
+                    output.removeListener("error", outputFailed);
+                    output.removeListener("close", outputFailed);
+                    output.removeListener("finish", outputFailed);
+                    resolve(result);
+                }
+                function finish(code) {
+                    if (finished)
+                        return;
+                    finished = true;
+                    result = code;
+                    lines.close();
+                    lines.removeAllListeners();
+                    hidden.destroy();
+                    hidden.removeAllListeners();
+                    input.removeListener("data", forward);
+                    input.removeListener("end", cancel);
+                    input.removeListener("close", cancel);
+                    input.removeListener("error", cancel);
+                    try {
+                        if (!wasRaw)
+                            setRawMode(false);
+                    }
+                    catch {
+                        result = undefined;
+                    }
+                    if (!wasFlowing)
+                        input.pause();
+                    if (output.destroyed || output.writableEnded) {
+                        result = undefined;
+                        return;
+                    }
+                    // Keep the error handler until the write finishes: stream errors usually arrive later.
+                    try {
+                        output.write("\n", error => { if (!error)
+                            complete(); });
+                    }
+                    catch {
+                        result = undefined;
+                        complete();
+                    }
+                }
+                lines.once("line", finish);
+                lines.once("close", finish);
+                lines.once("SIGINT", cancel);
+                lines.once("SIGTSTP", cancel);
+                input.once("end", cancel);
+                input.once("close", cancel);
+                input.once("error", cancel);
+                process.once("SIGINT", cancel);
+                signal?.addEventListener("abort", cancel, { once: true });
+                output.once("error", outputFailed);
+                output.once("close", outputFailed);
+                output.once("finish", outputFailed);
+                try {
+                    if (!wasRaw)
+                        setRawMode(true);
+                    if (finished)
+                        return;
+                    output.write(prompt);
+                    if (finished)
+                        return;
+                    input.on("data", forward);
+                    input.resume();
+                }
+                catch {
+                    finish();
+                }
+            });
+        },
+    };
+    return adapter;
+}

package/dist/cli/sign-in.js

@@ -0,0 +1,37 @@
+import { ApiError } from "./api.js";
+import { readCredentials, saveCredentials } from "./credentials.js";
+import { emailSignInMessages } from "../contract/email-sign-in-messages.js";
+async function pollSignIn(ctx, device) {
+    const until = ctx.now() + device.expiresIn * 1000;
+    while (ctx.now() < until) {
+        await ctx.sleep(device.interval * 1000);
+        const poll = await ctx.api.request("device/token", { deviceCode: device.deviceCode }, false);
+        if (poll.status === "ok") {
+            await saveCredentials(ctx.homeDir, ctx.api.baseUrl, poll.token);
+            return "signed_in";
+        }
+        if (poll.status === "expired")
+            break;
+        if (poll.status === "denied")
+            throw new Error(emailSignInMessages.cancelled);
+    }
+    throw new Error("The sign-in code expired. Run counterfact-labs login to try again.");
+}
+export async function startSignIn(ctx) {
+    const device = await ctx.api.request("device", {}, false);
+    return { userCode: device.userCode, verificationUri: device.verificationUri,
+        pageUrl: `${device.verificationUri}?code=${encodeURIComponent(device.userCode)}`, done: pollSignIn(ctx, device) };
+}
+export async function signInStatus(ctx) {
+    if (!await readCredentials(ctx.homeDir, ctx.api.baseUrl))
+        return { signedIn: false };
+    try {
+        await ctx.api.request("balance");
+        return { signedIn: true };
+    }
+    catch (error) {
+        if (error instanceof ApiError && error.status === 401)
+            return { signedIn: false };
+        throw error;
+    }
+}

package/dist/cli/suggested-email.js

@@ -0,0 +1,10 @@
+import { normalizeSignInEmail } from "./email-sign-in.js";
+import { userEmail } from "./git.js";
+export async function suggestedEmail(folder, readEmail = userEmail) {
+    try {
+        return normalizeSignInEmail(await readEmail(folder));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/cli/summary.js

@@ -0,0 +1,30 @@
+import { findingPresentation } from "../analysis-core/findings/presentation.js";
+export function formatSummary(report) {
+    const lines = ["# Counterfact analysis", "",
+        `${report.findings.length} findings; ${report.structures.length} structural proposals.`, ""];
+    if (!report.findings.length)
+        lines.push("No findings.", "");
+    for (const [index, finding] of report.findings.entries()) {
+        const presentation = findingPresentation(finding);
+        lines.push(`## ${index + 1}. ${presentation.displayTitle}`, "");
+        if (presentation.ifLeft)
+            lines.push(`If left: ${presentation.ifLeft}`, "");
+        lines.push(`Severity: ${finding.severity}; category: ${finding.category ?? "unclassified"}.`, "", finding.cause, "");
+        const sites = [...(finding.site ? [finding.site] : []), ...finding.otherSites];
+        if (sites.length)
+            lines.push(`Sources: ${sites.map(site => `${site.path}:${site.line ?? "?"}`).join(", ")}`, "");
+        if (finding.question)
+            lines.push(finding.question, "");
+        if (finding.fixes.length)
+            lines.push(...finding.fixes.map(fix => `- ${fix.title}`), "");
+    }
+    if (report.structures.length)
+        lines.push("## Structural proposals", "", ...report.structures.flatMap(proposal => {
+            const presentation = findingPresentation({ ...proposal, title: proposal.body.title });
+            return [presentation.ifLeft ? `- ${presentation.displayTitle}` : `- ${presentation.displayTitle}: ${proposal.body.cause}`, "",
+                ...(presentation.ifLeft ? [`If left: ${presentation.ifLeft}`, ""] : [])];
+        }));
+    if (report.warnings.length)
+        lines.push("## Reading and analysis notices", "", ...report.warnings.map(warning => `- ${warning}`), "");
+    return lines.join("\n");
+}

package/dist/contract/cli-api-messages.js

@@ -0,0 +1,5 @@
+export const cliApiMessages = Object.freeze({
+    unreachable: "Can't reach Counterfact. Try again shortly.",
+    invalid_response: "Counterfact returned an invalid response. Try again shortly.",
+    request_failed: "The request could not be completed. Try again shortly.",
+});

package/dist/contract/cli-refusals.js

@@ -0,0 +1,22 @@
+export const START_FAILURE_MESSAGE = "This couldn't start. Try again.";
+export const RESERVATION_EXPIRED_MESSAGE = "This reservation expired. Start a new analysis.";
+export const FINISH_FAILURE_MESSAGE = "The analysis couldn't finish. Try again.";
+export const RESULTS_TOO_LARGE_MESSAGE = "The results were too large to save. Try again.";
+export const COMMITTED_FILES_MESSAGE = "Counterfact analyzes the committed version of the agent's files. Commit your changes, then try again.";
+const unsupportedVersion = "This version of Counterfact can't run analyses. Update it: npm install -g @counterfact-labs/cli@latest.";
+/** Shared public refusals keep mode admission and reservation errors consistent. */
+export const cliRefusals = {
+    low_balance: "Your balance doesn't cover this analysis. Add credit at https://app.counterfactlabs.com/account?status=low_balance#balance",
+    local_checks_paused: "Analyses are paused right now. Try again later.",
+    cli_update_required: "Update Counterfact: run npm install -g @counterfact-labs/cli@latest.",
+    release_unavailable: unsupportedVersion,
+    invalid_plan: unsupportedVersion,
+    invalid_body: "Counterfact couldn't read this request. Update Counterfact, then try again.",
+    body_too_large: "This request is too large. The limit is 2 MB.",
+    free_cap_reached: "Free analyses are paused for today. Try again tomorrow, or top up to run a paid analysis.",
+    org_spend_limit: "The workspace spending limit was reached. Ask Counterfact to raise it.",
+    not_reserved: "Start a new analysis.",
+    reservation_expired: "Start a new analysis.",
+    stale_quote: START_FAILURE_MESSAGE,
+};
+export function refusalExitCode(code) { return code === "low_balance" ? 2 : 1; }

package/dist/contract/cli-version.js

@@ -0,0 +1 @@
+export const CLI_VERSION = "0.2.3";

package/dist/contract/console-url.js

@@ -0,0 +1,8 @@
+export function savedAnalysisUrl(projectId, consoleOrigin) {
+    return new URL(`/projects/${projectId}/findings`, consoleOrigin).href;
+}
+import { isLoopbackHost } from "../gatekeeper/loopback.js";
+/** Bearer credentials may use plain HTTP only on this machine. */
+export function consoleSchemeAllowed(url) {
+    return url.protocol === "https:" || url.protocol === "http:" && isLoopbackHost(url.hostname);
+}

package/dist/contract/console.js

@@ -0,0 +1,111 @@
+import { z } from "zod";
+import { fixDeltaSchema, fixFactsSchema } from "../analysis-core/data/finding-types.js";
+import { inspectFixSchema, otherSiteSchema, rawFindingSchema } from "../analysis-core/analysis/schemas.js";
+import { sourceNotesSchema } from "../analysis-core/analysis/source-notes/types.js";
+export const id = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/);
+const uuid = z.uuid().transform(value => value.toLowerCase());
+const money = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+const count = (max) => z.number().int().positive().max(max);
+// These data-only boundaries follow the SaaS local start, reservation and findings owners; see docs/provenance.md.
+export const LOCAL_START_EXECUTION_HEADER = { name: "x-counterfact-execution", value: "local" };
+export const LOCAL_START_BODY_LIMIT = 2 * 1024 * 1024;
+const localStartPath = z.string().min(1).max(4096).refine(value => !value.includes("\\") && !value.includes("\0") && !value.startsWith("/")
+    && value.split("/").every(part => part !== ".." && part !== "." && part !== ""));
+export const localStartRequestSchema = z.strictObject({
+    execution: z.literal("local"), remoteUrl: z.string().max(4096).nullable(), relPath: z.string().max(4096),
+    folderName: z.string().trim().min(1).max(255), branch: z.string().max(4096).nullable().optional(),
+    commit: z.string().max(4096).nullable().optional(), dirty: z.boolean().nullable().optional(),
+    files: z.array(z.strictObject({ path: localStartPath, size: money })).min(1)
+        .refine(files => new Set(files.map(file => file.path)).size === files.length),
+});
+export const localStartResponseSchema = z.strictObject({ jobId: uuid, projectId: uuid });
+export const relayPlanSchema = z.strictObject({
+    bundleVersion: id, bundleHash: z.string().regex(/^[a-f0-9]{64}$/), relayVersion: id,
+    calls: z.array(z.strictObject({ routeId: id, model: id, calls: count(512), maxInputBytes: count(800_000),
+        maxInputTokens: count(200_000), maxOutputTokens: count(64_000) })).min(1).max(64)
+        .refine(calls => new Set(calls.map(call => call.routeId)).size === calls.length && calls.reduce((sum, call) => sum + call.calls, 0) <= 512),
+});
+export const cliRelayReservationRequestSchema = z.discriminatedUnion("action", [
+    z.strictObject({ action: z.literal("create"), jobId: uuid, checkId: uuid, projectId: uuid, plan: relayPlanSchema }),
+    z.strictObject({ action: z.literal("reserve"), reservationId: uuid }),
+    z.strictObject({ action: z.literal("status"), reservationId: uuid }),
+    z.strictObject({ action: z.literal("heartbeat"), reservationId: uuid }),
+    z.strictObject({ action: z.literal("fail"), reservationId: uuid }),
+]);
+export const consoleCreatedSchema = z.strictObject({ reservationId: uuid, jobId: uuid, projectId: uuid, checkId: uuid, state: z.literal("quoted") });
+export const consoleStatusSchema = z.strictObject({
+    reservationId: uuid, checkId: uuid, projectId: uuid,
+    state: z.enum(["quoted", "reserved", "closing", "closed", "expired"]),
+    settlement: z.enum(["unheld", "held", "charged", "released"]),
+    reason: z.enum(["service_failure", "required_failure", "authorization_refused", "our_deadline_failure",
+        "findings_saved", "required_delivered", "no_required_delivery"]).nullable(),
+    uploadState: z.enum(["saved", "missing"]), analysisId: uuid.optional(), findingIds: z.array(uuid).max(20_000).optional(),
+    quoteId: z.string().min(1).max(256).optional(), priceMicro: money.nullable(), providerBudgetMicro: money,
+    expiresAt: z.iso.datetime(), absoluteExpiresAt: z.iso.datetime().nullable(),
+    deadlineClassification: z.enum(["caller_timeout", "our_deadline_failure"]).nullable(),
+}).refine(value => value.uploadState === "saved"
+    ? value.analysisId !== undefined && value.findingIds !== undefined
+    : value.analysisId === undefined && value.findingIds === undefined);
+export const consoleReservationSchema = consoleStatusSchema.safeExtend({ reservationToken: z.string().min(1).max(256),
+    quoteId: z.string().min(1).max(256) });
+export const consoleIntakeResultSchema = z.strictObject({
+    checkId: uuid, projectId: uuid, analysisId: uuid, findingIds: z.array(uuid).max(20_000),
+    settlement: z.enum(["unheld", "held", "charged", "released"]).optional(),
+});
+export const LOCAL_FINDINGS_BODY_LIMIT = 2 * 1024 * 1024;
+export const LOCAL_FINDINGS_QUOTE_LIMIT = 2000;
+export const LOCAL_FINDINGS_TEXT_LIMIT = 4096;
+function shortFindingFields(value) {
+    if (typeof value === "string")
+        return Buffer.byteLength(value, "utf8") <= LOCAL_FINDINGS_TEXT_LIMIT;
+    return value === null || typeof value !== "object" || Object.values(value).every(shortFindingFields);
+}
+function validIntakeText(value) {
+    if (typeof value === "string")
+        return !value.includes(String.fromCharCode(0)) && !/[\uD800-\uDFFF]/u.test(value);
+    return value === null || typeof value !== "object" || Object.values(value).every(validIntakeText);
+}
+const quote = z.string().refine(value => Buffer.byteLength(value, "utf8") <= LOCAL_FINDINGS_QUOTE_LIMIT);
+const text = z.string().min(1).refine(value => value.trim().length > 0);
+const delta = fixDeltaSchema.extend({
+    nodes: z.array(fixDeltaSchema.shape.nodes.element.strict()),
+    edges: z.array(fixDeltaSchema.shape.edges.element.strict()),
+}).strict();
+const fix = inspectFixSchema.extend({
+    ...fixFactsSchema.shape,
+    targetFiles: z.array(inspectFixSchema.shape.targetFiles.element.strict()),
+    delta: delta.nullable(),
+}).strict();
+const notes = sourceNotesSchema.extend({
+    sites: z.array(sourceNotesSchema.shape.sites.element.extend({ keyPhrase: quote }).strict()),
+    counterEvidence: z.array(sourceNotesSchema.shape.counterEvidence.element.extend({ excerpt: quote }).strict()),
+}).strict();
+const finding = rawFindingSchema.extend({
+    summary: z.string().nullable(),
+    category: rawFindingSchema.shape.category.removeCatch(),
+    question: rawFindingSchema.shape.question.removeCatch().nullable(),
+    siteRepo: text.nullable(),
+    site: rawFindingSchema.shape.site.unwrap().strict().nullable(),
+    excerpt: quote.nullable(),
+    otherSites: z.array(otherSiteSchema.extend({ repo: text, excerpt: otherSiteSchema.shape.excerpt.pipe(quote) }).strict()),
+    fixes: z.array(fix).min(1),
+    sourceNotes: notes.nullable().optional(),
+}).strict().refine(shortFindingFields);
+const payload = z.strictObject({
+    checkId: z.uuid(), projectId: z.uuid(), reservationId: uuid.optional(),
+    agent: z.strictObject({
+        repository: text.max(4096), commit: z.string().regex(/^(?:[a-f\d]{40}|[a-f\d]{64})$/i),
+        files: z.array(z.strictObject({ path: text.max(4096), hash: z.string().regex(/^[a-f\d]{64}$/i) })).min(1),
+    }),
+    findings: z.array(finding), bundleVersion: text.max(128), relayVersion: text.max(128), counterfactLocalVersion: text.max(128),
+}).refine(validIntakeText);
+// Original JSON size is checked before a shared schema can trim text or apply defaults.
+export const localFindingsPayloadSchema = z.unknown().refine(value => {
+    try {
+        const json = JSON.stringify(value);
+        return typeof json === "string" && Buffer.byteLength(json, "utf8") <= LOCAL_FINDINGS_BODY_LIMIT;
+    }
+    catch {
+        return false;
+    }
+}).pipe(payload);

package/dist/contract/email-sign-in-messages.js

@@ -0,0 +1,18 @@
+import { cliApiMessages } from "./cli-api-messages.js";
+const rateLimited = "Too many sign-in requests. Try again later.";
+export const emailSignInMessages = Object.freeze({
+    invalid_email: "Enter a valid email address.",
+    invalid_code: "Enter the code from your email.",
+    wrong_code: "That code didn't work. Try the code from your email again.",
+    expired: "That code expired. Request a new sign-in code.",
+    too_many_attempts: "Too many incorrect codes. Request a new sign-in code.",
+    rate_limited: rateLimited,
+    rate_limited_with_cooldown: (seconds) => seconds === 0 ? rateLimited
+        : `Too many sign-in requests. Try again in ${seconds} ${seconds === 1 ? "second" : "seconds"}.`,
+    email_unavailable: "Email sign-in isn't available. Use browser sign-in instead.",
+    browser_sign_in_pending: "A browser sign-in is still in progress. Finish it before starting email sign-in.",
+    unreachable: cliApiMessages.unreachable,
+    invalid_response: cliApiMessages.invalid_response,
+    request_failed: cliApiMessages.request_failed,
+    cancelled: "Sign-in was cancelled. Run counterfact-labs login to try again.",
+});

package/dist/contract/messages.js

@@ -0,0 +1,252 @@
+import { z } from "zod";
+import { executionRequest } from "../analysis-core/contracts/requests.js";
+import { checkRuntimeEnvironment } from "./runtime-environment.js";
+/**
+ * The messages that cross between the customer's machine and the sealed relay. This module is the only owner of
+ * their shape: the relay, the gatekeeper and the bundle tooling all import these schemas and never redefine them.
+ * Design: docs/design/sealed-model-relay.md and docs/design/relay-contract.md.
+ */
+const compactJwtPattern = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+const hexChallenge = z.string().length(64).regex(/^[0-9a-f]+$/);
+/** The wire adds routing identity to the core's data-only execution envelope. */
+export const relayRequest = executionRequest.extend({
+    bundleVersion: z.string().min(1).max(128),
+    reservationId: z.string().min(1).max(128),
+    reservationToken: z.string().min(1).max(256),
+    /** Stable paid-call identity; required by the production delivery transport. */
+    callId: z.uuid(),
+    /** Fresh per call, echoed in the answer, so an answer cannot be replayed into another call. */
+    nonce: z.string().min(16).max(256),
+    template: z.string().min(1).max(128),
+    answerFormat: z.string().min(1).max(128),
+    limits: executionRequest.shape.limits.unwrap().extend({ maxTokens: z.number().int().positive().safe().max(64_000).optional() }).optional(),
+}).strict();
+export const relayUsage = z.object({
+    inputTokens: z.number().int().nonnegative().safe(),
+    outputTokens: z.number().int().nonnegative().safe(),
+    cacheReadTokens: z.number().int().nonnegative().safe(),
+    cacheWriteTokens: z.number().int().nonnegative().safe(),
+    cacheWrite5mTokens: z.number().int().nonnegative().safe().optional(),
+    cacheWrite1hTokens: z.number().int().nonnegative().safe().optional(),
+}).strict();
+export const relayAnswer = z.discriminatedUnion("ok", [
+    z.object({
+        ok: z.literal(true),
+        nonce: z.string().max(256),
+        /** Validated against the shared format; local parsing applies defaults, fallbacks and cleanup. */
+        answer: z.unknown(),
+        usage: relayUsage,
+        /** True when the answer quoted our instruction text and the relay removed it. */
+        redacted: z.boolean(),
+    }).strict(),
+    z.object({
+        ok: z.literal(false),
+        nonce: z.string().max(256),
+        code: z.enum(["bad_request", "unknown_template", "bundle_version", "reservation", "model_failed", "leak_refused", "call_in_progress", "call_status", "busy"]),
+    }).strict(),
+]);
+export const RELAY_TLS_EXPORTER_LABEL = "EXPORTER-counterfact-relay-v1";
+export const RELAY_MAX_FRAME_BYTES = 2 * 1024 * 1024;
+export const deliveryConfirmation = z.object({
+    callId: z.uuid(), attemptId: z.uuid(), connectionId: z.uuid(),
+    challenge: hexChallenge,
+}).strict();
+/** The challenge is released with the complete answer, never in headers or a separate preliminary frame. */
+export const relayAnswerFrame = z.object({
+    answer: relayAnswer,
+    delivery: z.object({ confirmation: deliveryConfirmation, deadlineMs: z.number().int().positive().safe() }).strict().optional(),
+}).strict().refine(frame => frame.answer.ok === (frame.delivery !== undefined));
+export const deliveryReceipt = z.object({ receiptId: z.uuid() }).strict();
+// This is the count-only server boundary; it never accepts arbitrary diagnostics or request content.
+const billingId = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/);
+const billingScope = { actionId: z.uuid(), reservationId: z.uuid(), reservationToken: z.string().min(1).max(256), callId: z.uuid() };
+const inputCount = z.number().int().nonnegative().max(200_000);
+const outputCount = z.number().int().nonnegative().max(64_000);
+/** A reservation lookup establishes the owner without reserving spend or contacting the model provider. */
+export const reservationCheck = z.object({ action: z.literal("check"), ...billingScope }).strict();
+export const reservationIdentity = z.object({ clientId: z.string().min(1).max(128) }).strict();
+export const callCounts = z.object({ inputBytes: z.number().int().positive().max(800_000),
+    inputTokens: inputCount.positive(), maxOutputTokens: outputCount.positive() }).strict();
+export const authorizationRequest = z.object({ action: z.literal("authorize"), ...billingScope,
+    routeId: billingId, templateId: billingId, answerFormatId: billingId, model: billingId, ...callCounts.shape }).strict();
+export const callAuthorization = z.object({ attemptId: z.uuid(), model: billingId, role: z.enum(["required", "optional"]),
+    /** Stable opaque owner supplied only by the authenticated authorization service. */
+    clientId: reservationIdentity.shape.clientId,
+    deadline: z.iso.datetime(), countLimits: z.object({ maxInputBytes: z.number().int().positive().max(800_000),
+        maxInputTokens: inputCount.positive(), maxOutputTokens: outputCount.positive() }).strict() }).strict();
+export const providerUsage = z.object({ kind: z.enum(["actual", "estimated", "unpaid"]),
+    outcome: z.enum(["success", "unknown", "retryable_failure", "terminal_provider_failure", "schema_refusal", "leak_refusal"]),
+    inputTokens: inputCount, outputTokens: outputCount, cacheReadTokens: inputCount, cacheWriteTokens: inputCount,
+    cacheWrite5mTokens: inputCount.optional(), cacheWrite1hTokens: inputCount.optional() }).strict();
+export const serviceTiming = z.object({ kind: z.enum(["relay", "provider"]), startedAt: z.number().int().nonnegative().safe(),
+    endedAt: z.number().int().nonnegative().safe() }).strict().refine(timing => timing.endedAt >= timing.startedAt);
+export const usageReport = z.object({ action: z.literal("usage"), ...billingScope, attemptId: z.uuid(),
+    usage: providerUsage, timing: z.array(serviceTiming).max(2) }).strict();
+export const deliveryReport = z.object({ action: z.literal("delivery"), ...billingScope, attemptId: z.uuid(),
+    delivery: z.discriminatedUnion("status", [
+        z.object({ status: z.literal("confirmed"), confirmation: deliveryConfirmation.extend({
+                challenge: z.string().regex(/^[A-Za-z0-9_-]{43}$/),
+            }) }).strict(),
+        z.object({ status: z.enum(["unknown", "failed"]) }).strict(),
+    ]) }).strict();
+export const reservationAction = z.discriminatedUnion("action", [reservationCheck, authorizationRequest, usageReport, deliveryReport]);
+export const RELAY_HEALTH_VERSION = 2;
+export const RELAY_HEALTH_AUDIENCE = "counterfact-relay-health";
+export const RELAY_HEALTH_MAX_REQUEST_BYTES = 1024;
+/** Billing supplies a fresh random challenge; this route accepts no analysis data. */
+export const relayHealthRequest = z.object({
+    version: z.literal(RELAY_HEALTH_VERSION),
+    challenge: hexChallenge,
+}).strict();
+export const relayHealthRelease = z.object({
+    releaseId: z.string().min(1).max(128),
+    relayVersion: z.string().min(1).max(128),
+    bundleVersion: z.string().min(1).max(128),
+    workloadPolicySha256: z.string().regex(/^[0-9a-f]{64}$/),
+}).strict();
+export const relayHealthFilesystem = z.object({
+    readOnlyRootFilesystem: z.boolean(),
+    tmpFilesystemType: z.string().min(1).max(128).regex(/^[a-zA-Z0-9._-]+$/),
+}).strict();
+export const relayHealthResponse = z.discriminatedUnion("ok", [
+    z.object({
+        version: z.literal(RELAY_HEALTH_VERSION),
+        ok: z.literal(true),
+        bootId: z.uuid(),
+        challenge: hexChallenge,
+        release: relayHealthRelease,
+        filesystem: relayHealthFilesystem,
+        /** The evidence owner authenticates the audience and all three nonces before release. */
+        evidence: z.string().max(32 * 1024).regex(compactJwtPattern),
+    }).strict(),
+    z.object({
+        version: z.literal(RELAY_HEALTH_VERSION),
+        ok: z.literal(false),
+        code: z.enum(["bad_request", "unavailable"]),
+    }).strict(),
+]);
+export const PRODUCTION_EVIDENCE_VERSION = 1;
+export const RELAY_CHANNEL_AUDIENCE = "https://relay.counterfactlabs.com";
+// Passthrough forwarding keeps the non-root workload's listener port unchanged.
+export const RELAY_PORT = 8443;
+export const RELAY_URL = `${RELAY_CHANNEL_AUDIENCE}:${RELAY_PORT}`;
+export const RELAY_HEALTH_PATH = "/health";
+export const RELAY_HEALTH_URL = `${RELAY_URL}${RELAY_HEALTH_PATH}`;
+export const GOOGLE_ATTESTATION_ISSUER = "https://confidentialcomputing.googleapis.com";
+export const MAX_ATTESTATION_BYTES = 32 * 1024;
+export const attestationChallenge = z.object({
+    version: z.literal(PRODUCTION_EVIDENCE_VERSION),
+    challenge: hexChallenge,
+}).strict();
+export const productionEvidence = z.object({
+    version: z.literal(PRODUCTION_EVIDENCE_VERSION),
+    token: z.string().max(MAX_ATTESTATION_BYTES).regex(compactJwtPattern),
+}).strict();
+/** Google's launcher accepts up to six caller nonces, each at most 74 characters. */
+export const evidenceBinding = z.object({
+    audience: z.string().min(1).max(256).regex(/^[A-Za-z0-9:/._-]+$/),
+    nonces: z.array(z.string().min(1).max(74).regex(/^[A-Za-z0-9_:-]+$/)).min(1).max(6),
+}).strict();
+/** Native claims are interpreted only after the PKI chain and token signature are authenticated. */
+export const googleAttestationClaims = z.object({
+    iss: z.literal(GOOGLE_ATTESTATION_ISSUER),
+    aud: z.string(),
+    sub: z.string(),
+    iat: z.number().int(),
+    nbf: z.number().int(),
+    exp: z.number().int(),
+    eat_nonce: z.union([z.string(), z.array(z.string()).min(1).max(6)]),
+    secboot: z.literal(true),
+    dbgstat: z.literal("disabled-since-boot"),
+    oemid: z.literal(11129),
+    hwmodel: z.string(),
+    swname: z.literal("CONFIDENTIAL_SPACE"),
+    swversion: z.array(z.string()).length(1),
+    google_service_accounts: z.array(z.string()).min(1),
+    development: z.never().optional(),
+    identity: z.never().optional(),
+    submods: z.object({
+        confidential_space: z.object({
+            support_attributes: z.array(z.string()),
+            monitoring_enabled: z.object({ memory: z.literal(false) }).passthrough(),
+        }).passthrough(),
+        container: z.object({
+            image_digest: z.string().regex(/^sha256:[0-9a-f]{64}$/),
+            image_signatures: z.array(z.object({
+                key_id: z.string(), signature: z.string().min(1),
+                signature_algorithm: z.literal("RSASSA_PSS_SHA256"),
+            }).passthrough()).min(1),
+            // Google omits both override claims when nothing was overridden; when present they must still be empty.
+            cmd_override: z.array(z.unknown()).length(0).optional(),
+            env_override: z.object({}).strict().optional(),
+            // Real tokens list the container's own environment; the relay's start-up rule decides which settings are allowed.
+            env: z.record(z.string(), z.string()).refine(env => {
+                try {
+                    checkRuntimeEnvironment(env);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }),
+        }).passthrough(),
+    }).passthrough(),
+}).passthrough();
+/** Authenticated observations describe a refused workload without granting it an admitted identity. */
+export const observedAttestationClaims = googleAttestationClaims.extend({
+    dbgstat: z.string(),
+    submods: googleAttestationClaims.shape.submods.extend({
+        container: googleAttestationClaims.shape.submods.shape.container.extend({
+            image_signatures: z.array(googleAttestationClaims.shape.submods.shape.container.shape.image_signatures.element),
+            cmd_override: z.array(z.unknown()).optional(),
+            env_override: z.record(z.string(), z.unknown()).optional(),
+        }),
+    }),
+});
+/**
+ * Local development claims. These cannot establish production identity; production uses native Google claims.
+ */
+export const attestationClaims = z.object({
+    iss: z.string().url(),
+    /** The relay image's digest. Must be one we published. */
+    imageDigest: z.string().regex(/^sha256:[0-9a-f]{64}$/),
+    /** Hash of the relay's channel public key, so the token is bound to this connection. */
+    channelKeyHash: z.string().regex(/^[0-9a-f]{64}$/),
+    exp: z.number().int(),
+    iat: z.number().int(),
+}).passthrough();
+const assetMetadata = z.object({
+    /** HMAC-SHA256 keyed by a secret stored only in the encrypted payload. */
+    fingerprint: z.string().regex(/^[0-9a-f]{64}$/),
+    size: z.number().int().nonnegative(),
+}).strict();
+export const bundleMetadata = z.object({
+    templates: z.record(z.string().min(1), assetMetadata.extend({
+        role: z.enum(["required", "optional"]),
+        answerFormats: z.array(z.string().min(1)).min(1),
+    }).strict()),
+    includes: z.record(z.string().min(1), assetMetadata.extend({
+        expandedSize: z.number().int().nonnegative(),
+        expandedFingerprint: z.string().regex(/^[0-9a-f]{64}$/),
+    }).strict()),
+    descriptions: z.record(z.string().min(1), assetMetadata),
+    headlinePlan: assetMetadata.extend({ inputOverheadBytes: z.number().int().nonnegative(), evidenceCopies: z.number().int().nonnegative(),
+        resultVersion: z.number().int().positive().optional() }).strict().optional(),
+}).strict();
+/** The sealed instruction bundle as shipped with the CLI. Only the relay can open `sealed`. */
+export const sealedBundle = z.object({
+    version: z.string().min(1),
+    /** The relay versions able to open this bundle. */
+    relayVersions: z.array(z.string().min(1)).min(1),
+    /** Template names and answer formats are public; the wording is not (design section 9). */
+    templates: z.array(z.string().min(1)),
+    answerFormats: z.array(z.string().min(1)),
+    metadata: bundleMetadata,
+    /** AES-256-GCM over the serialised registry and private fingerprint key, base64. */
+    sealed: z.string().min(1),
+    iv: z.string().min(1),
+    /** The data key, wrapped by the key service so it is released only to an attested relay image. */
+    wrappedKey: z.string().min(1),
+    /** Ed25519 signature by our release key over every field above, base64. */
+    signature: z.string().min(1),
+}).strict();

package/dist/contract/release-key.js

@@ -0,0 +1,2 @@
+// Changing the release key requires a reviewed CLI release, independent of bundle metadata.
+export const RELEASE_KEY_SPKI_SHA256 = "470601058e910027392fca337233926b6ec38311472307b44c78c5b21d5dfc9c";

package/dist/contract/runtime-environment.js

@@ -0,0 +1,37 @@
+// The pinned distroless base image sets SSL_CERT_FILE to its bundled certificates. The relay accepts exactly that
+// value, so the image works while no operator setting can point the relay at a different trust store.
+export const BASE_CERTIFICATE_FILE = "/etc/ssl/certs/ca-certificates.crt";
+const fixedValues = Object.freeze({ SSL_CERT_FILE: BASE_CERTIFICATE_FILE });
+// Native startup consumes these data, so loader checks have the same owner as runtime checks.
+export const runtimeEnvironmentPolicy = Object.freeze({
+    fixedValues,
+    forbiddenPrefixes: ["CF_RELAY_", "ANTHROPIC_", "GOOGLE_AUTH_", "LD_"],
+    forbiddenNames: ["GOOGLE_APPLICATION_CREDENTIALS", "NODE_OPTIONS", "NODE_USE_ENV_PROXY", "NODE_EXTRA_CA_CERTS",
+        "NODE_TLS_REJECT_UNAUTHORIZED", "SSL_CERT_DIR", "GLIBC_TUNABLES", "GCONV_PATH"],
+    forbiddenNamesIgnoringCase: ["http_proxy", "https_proxy", "all_proxy"],
+});
+export const reviewedNativeImageEnvironment = Object.freeze([
+    "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+    `SSL_CERT_FILE=${BASE_CERTIFICATE_FILE}`, "NODE_ENV=production", "TMPDIR=/tmp",
+]);
+/** Refuses settings that could redirect credentials, trust or traffic; the image checker reads the same fixed values. */
+export function checkRuntimeEnvironment(env) {
+    for (const name of Object.keys(env)) {
+        const value = env[name];
+        if (value === undefined || value === "")
+            continue;
+        if (fixedValues[name] !== undefined) {
+            if (value !== fixedValues[name])
+                throw new Error();
+            continue;
+        }
+        if (runtimeEnvironmentPolicy.forbiddenPrefixes.some(prefix => name.startsWith(prefix)) ||
+            runtimeEnvironmentPolicy.forbiddenNamesIgnoringCase.includes(name.toLowerCase()) ||
+            runtimeEnvironmentPolicy.forbiddenNames.includes(name))
+            throw new Error();
+    }
+}
+/** True when an image configuration Env entry pins one of the fixed values the runtime accepts. */
+export function isFixedImageEnvironment(entry) {
+    return Object.entries(fixedValues).some(([name, value]) => entry === `${name}=${value}`);
+}

package/dist/core/analysis/finding-quality/config.js

@@ -0,0 +1,4 @@
+export { readLocalQualityConfig as readFindingQualityConfig } from "../../../adapters/quality.js";
+import { assertFindingQualityPrompts as assertSharedPrompts } from "../../../analysis-core/analysis/finding-quality/config.js";
+import { readableRequestTools } from "../../../adapters/instructions.js";
+export const assertFindingQualityPrompts = (config) => assertSharedPrompts(config, readableRequestTools());