@paybond/kit 0.9.8 → 0.11.0

package/dist/completion-validate-evidence.js

@@ -0,0 +1,145 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { getCompletionPreset } from "./completion-catalog.js";
+import { forbiddenFieldsInEvidence, forbiddenFieldsInVendorPayload, } from "./completion-forbidden-fields.js";
+import { isVendorPack, mapVendorEvidenceToCanonical, resolveCompletionPreset, vendorEvidenceSchema, } from "./completion-resolve.js";
+function pushDriftKind(kinds, kind) {
+    if (!kinds.includes(kind)) {
+        kinds.push(kind);
+    }
+}
+function classifyAjvError(error) {
+    const message = error.message ?? "";
+    if (!error.instancePath && message.includes("required")) {
+        return "missing_field";
+    }
+    if (message.includes("required")) {
+        return "missing_field";
+    }
+    return "type_mismatch";
+}
+function validateJsonSchema(schema, instance) {
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    const validate = ajv.compile(schema);
+    if (validate(instance)) {
+        return [];
+    }
+    const kinds = [];
+    for (const error of validate.errors ?? []) {
+        pushDriftKind(kinds, classifyAjvError(error));
+    }
+    return kinds.length > 0 ? kinds : ["type_mismatch"];
+}
+function missingQualityFields(payload, qualityFields) {
+    if (!qualityFields?.length) {
+        return [];
+    }
+    return qualityFields.filter((field) => {
+        const value = payload[field];
+        return value === undefined || value === null;
+    });
+}
+/**
+ * Validates vendor and canonical completion evidence against catalog JSON Schemas.
+ * Signal-only: returns drift metadata without throwing on schema mismatch.
+ */
+export function validateCompletionEvidence(input) {
+    const preset = getCompletionPreset(input.presetId);
+    const resolved = resolveCompletionPreset(input.presetId);
+    const contract = preset.vendor_contract;
+    const driftKinds = [];
+    let vendorSchemaOk = true;
+    let canonicalSchemaOk = true;
+    let canonicalPayload = input.canonicalPayload;
+    if (!canonicalPayload && input.vendorPayload && isVendorPack(preset)) {
+        canonicalPayload = mapVendorEvidenceToCanonical(preset, input.vendorPayload);
+    }
+    if (!canonicalPayload && !isVendorPack(preset) && input.vendorPayload) {
+        canonicalPayload = input.vendorPayload;
+    }
+    let packStale = false;
+    if (input.frozenVendorApiVersion && contract?.api_version && input.frozenVendorApiVersion !== contract.api_version) {
+        packStale = true;
+        pushDriftKind(driftKinds, "pack_stale");
+    }
+    if (input.frozenVendorSchemaDigestHex &&
+        contract?.schema_digest_hex &&
+        input.frozenVendorSchemaDigestHex !== contract.schema_digest_hex) {
+        packStale = true;
+        pushDriftKind(driftKinds, "pack_stale");
+    }
+    if (input.frozenCanonicalSchemaDigestHex &&
+        contract?.canonical_schema_digest_hex &&
+        input.frozenCanonicalSchemaDigestHex !== contract.canonical_schema_digest_hex) {
+        packStale = true;
+        pushDriftKind(driftKinds, "pack_stale");
+    }
+    if (canonicalPayload) {
+        const canonicalKinds = validateJsonSchema(resolved.evidenceSchema, canonicalPayload);
+        if (canonicalKinds.length > 0) {
+            canonicalSchemaOk = false;
+            for (const kind of canonicalKinds) {
+                pushDriftKind(driftKinds, kind);
+            }
+        }
+    }
+    else if (!isVendorPack(preset)) {
+        canonicalSchemaOk = false;
+        pushDriftKind(driftKinds, "missing_field");
+    }
+    const vendorSchema = vendorEvidenceSchema(preset);
+    if (isVendorPack(preset)) {
+        if (input.vendorPayload && vendorSchema && !packStale) {
+            const vendorKinds = validateJsonSchema(vendorSchema, input.vendorPayload);
+            if (vendorKinds.length > 0) {
+                vendorSchemaOk = false;
+                for (const kind of vendorKinds) {
+                    pushDriftKind(driftKinds, kind);
+                }
+            }
+        }
+        else if (!input.vendorPayload) {
+            vendorSchemaOk = false;
+            pushDriftKind(driftKinds, "missing_field");
+        }
+    }
+    const qualityTarget = input.vendorPayload ?? canonicalPayload;
+    const qualityMissing = qualityTarget && contract?.quality_fields
+        ? missingQualityFields(qualityTarget, contract.quality_fields)
+        : [];
+    for (const _field of qualityMissing) {
+        pushDriftKind(driftKinds, "quality_field_missing");
+    }
+    const forbidden = preset.forbidden_evidence_fields;
+    const forbiddenHits = [];
+    if (forbidden?.length) {
+        if (input.vendorPayload) {
+            forbiddenHits.push(...forbiddenFieldsInVendorPayload(preset, input.vendorPayload, forbidden));
+        }
+        if (canonicalPayload) {
+            for (const field of forbiddenFieldsInEvidence(canonicalPayload, forbidden)) {
+                if (!forbiddenHits.includes(field)) {
+                    forbiddenHits.push(field);
+                }
+            }
+        }
+    }
+    for (const _field of forbiddenHits) {
+        if (isVendorPack(preset) && input.vendorPayload) {
+            vendorSchemaOk = false;
+        }
+        if (canonicalPayload) {
+            canonicalSchemaOk = false;
+        }
+        pushDriftKind(driftKinds, "forbidden_field_present");
+    }
+    return {
+        preset_id: input.presetId,
+        vendor_schema_ok: vendorSchemaOk,
+        canonical_schema_ok: canonicalSchemaOk,
+        quality_fields_missing: qualityMissing,
+        forbidden_fields_present: forbiddenHits,
+        pack_stale: packStale,
+        drift_kinds: driftKinds,
+        canonical_payload: canonicalPayload,
+    };
+}

package/dist/dev/offline-gateway.d.ts

@@ -0,0 +1,24 @@
+/**
+ * In-process offline Gateway mock for `paybond dev --offline`.
+ * Simulates sandbox capability bootstrap, verify, evidence, and settlement completion.
+ */
+export declare const OFFLINE_DEV_INTENT_ID = "00000000-0000-4000-8000-000000000001";
+export declare const OFFLINE_DEV_TENANT_ID = "tenant-dev-offline";
+/** Synthetic sandbox API key shape accepted by offline mocks (never validated remotely). */
+export declare const OFFLINE_SANDBOX_API_KEY: string;
+/** Visible prefix for production service-account API keys. */
+export declare const LIVE_API_KEY_PREFIX: "paybond_sk_live_";
+/** Return true when `apiKey` is a production (`paybond_sk_live_…`) service-account key. */
+export declare function isProductionApiKey(apiKey: string): boolean;
+export declare const DEV_WIREMOCK_DEFAULT_PORT = 18089;
+export declare const DEV_WIREMOCK_CONTAINER_NAME = "paybond-dev-wiremock";
+export type OfflineGatewayMockOptions = {
+    allowVerify?: boolean;
+    denyMessage?: string;
+};
+/** Build a fetch implementation that stubs Gateway routes for local dev smoke. */
+export declare function createOfflineDevGatewayFetch(options?: OfflineGatewayMockOptions): typeof fetch;
+/** Apply offline dev credentials and fetch mock; returns a restore function. */
+export declare function activateOfflineDevMode(): {
+    restore: () => void;
+};

package/dist/dev/offline-gateway.js

@@ -0,0 +1,102 @@
+/**
+ * In-process offline Gateway mock for `paybond dev --offline`.
+ * Simulates sandbox capability bootstrap, verify, evidence, and settlement completion.
+ */
+export const OFFLINE_DEV_INTENT_ID = "00000000-0000-4000-8000-000000000001";
+export const OFFLINE_DEV_TENANT_ID = "tenant-dev-offline";
+/** Synthetic sandbox API key shape accepted by offline mocks (never validated remotely). */
+export const OFFLINE_SANDBOX_API_KEY = "paybond_sk_sandbox_0123456789abcdef0123456789abcdef_" +
+    "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+/** Visible prefix for production service-account API keys. */
+export const LIVE_API_KEY_PREFIX = "paybond_sk_live_";
+/** Return true when `apiKey` is a production (`paybond_sk_live_…`) service-account key. */
+export function isProductionApiKey(apiKey) {
+    return apiKey.startsWith(LIVE_API_KEY_PREFIX);
+}
+export const DEV_WIREMOCK_DEFAULT_PORT = 18089;
+export const DEV_WIREMOCK_CONTAINER_NAME = "paybond-dev-wiremock";
+function jsonResponse(body, status = 200) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json" },
+    });
+}
+/** Build a fetch implementation that stubs Gateway routes for local dev smoke. */
+export function createOfflineDevGatewayFetch(options = {}) {
+    const allowVerify = options.allowVerify ?? true;
+    return (async (input, init) => {
+        const url = input.toString();
+        const body = init?.body ? JSON.parse(String(init.body)) : {};
+        if (url.endsWith("/v1/auth/principal")) {
+            return jsonResponse({
+                tenant_id: OFFLINE_DEV_TENANT_ID,
+                tenant_uuid: "550e8400-e29b-41d4-a716-446655440000",
+                environment: "sandbox",
+                service_account_role: "operator",
+            });
+        }
+        if (url.endsWith("/v1/sandbox/guardrails/bootstrap")) {
+            return jsonResponse({
+                tenant_id: OFFLINE_DEV_TENANT_ID,
+                intent_id: OFFLINE_DEV_INTENT_ID,
+                capability_token: "cap-dev-offline-1",
+                operation: body.operation,
+                requested_spend_cents: body.requested_spend_cents,
+                sandbox_lifecycle_status: "funded",
+            });
+        }
+        if (url.endsWith("/verify")) {
+            if (!allowVerify) {
+                return jsonResponse({
+                    allow: false,
+                    tenant: OFFLINE_DEV_TENANT_ID,
+                    intent_id: OFFLINE_DEV_INTENT_ID,
+                    audit_id: "audit-deny",
+                    decision_id: "decision-deny",
+                    message: options.denyMessage ?? "spend denied",
+                });
+            }
+            return jsonResponse({
+                allow: true,
+                tenant: OFFLINE_DEV_TENANT_ID,
+                intent_id: OFFLINE_DEV_INTENT_ID,
+                audit_id: "00000000-0000-4000-8000-000000000002",
+                decision_id: "00000000-0000-4000-8000-000000000003",
+            });
+        }
+        if (url.endsWith(`/v1/sandbox/guardrails/${OFFLINE_DEV_INTENT_ID}/evidence`)) {
+            return jsonResponse({
+                tenant_id: OFFLINE_DEV_TENANT_ID,
+                intent_id: OFFLINE_DEV_INTENT_ID,
+                operation: body.operation ?? "paid-tool",
+                requested_spend_cents: body.requested_spend_cents ?? 100,
+                sandbox_lifecycle_status: "released",
+                predicate_passed: true,
+                settlement_mode: "simulated",
+            });
+        }
+        if (url.includes("/v1/spend/decisions/") && url.endsWith("/complete")) {
+            return jsonResponse({ settlement_mode: "simulated" });
+        }
+        return jsonResponse({}, 404);
+    });
+}
+/** Apply offline dev credentials and fetch mock; returns a restore function. */
+export function activateOfflineDevMode() {
+    const previousApiKey = process.env.PAYBOND_API_KEY;
+    const trimmedPrevious = previousApiKey?.trim();
+    if (trimmedPrevious && isProductionApiKey(trimmedPrevious)) {
+        throw new Error("offline dev mode cannot be used with production API keys (paybond_sk_live_...); unset PAYBOND_API_KEY or use a sandbox key");
+    }
+    process.env.PAYBOND_API_KEY = OFFLINE_SANDBOX_API_KEY;
+    return {
+        restore() {
+            if (previousApiKey === undefined) {
+                delete process.env.PAYBOND_API_KEY;
+            }
+            else {
+                process.env.PAYBOND_API_KEY = previousApiKey;
+            }
+        },
+    };
+}

package/dist/dev/trace-buffer.d.ts

@@ -0,0 +1,61 @@
+import type { PaybondTraceEvent, PaybondTraceSink } from "../agent/types.js";
+export declare const DEV_TRACE_DEFAULT_PORT = 9477;
+export declare const DEV_AUDIT_DIR = ".paybond";
+export declare const DEV_AUDIT_FILE: string;
+export declare const DEV_TRACE_FILE: string;
+export declare const DEV_DEFAULT_POLICY_FILE = "paybond.policy.yaml";
+export declare const DEV_DEFAULT_PRESET = "travel";
+export type DevTraceStepPhase = "agent" | "tool" | "authorize" | "evidence" | "result";
+export type DevTraceStep = {
+    phase: DevTraceStepPhase;
+    label: string;
+    recorded_at: string;
+    detail?: Record<string, unknown>;
+};
+export type DevTraceEvent = {
+    id: string;
+    recorded_at: string;
+    preset: string;
+    operation: string;
+    intent_id?: string;
+    run_id?: string;
+    requested_spend_cents?: number;
+    authorized: boolean;
+    evidence_submitted: boolean;
+    sandbox_lifecycle_status?: string;
+    result_status?: string;
+    cost_cents?: number;
+    steps?: DevTraceStep[];
+    trace_events?: PaybondTraceEvent[];
+};
+/** Read persisted dev trace events from `.paybond/dev-trace.jsonl`. */
+export declare function readDevTraceEventsFromDisk(cwd: string): DevTraceEvent[];
+/** List dev trace events from disk (when `cwd` is set) and the in-process ring buffer. */
+export declare function listDevTraceEvents(cwd?: string): DevTraceEvent[];
+/** Find the most recent in-memory dev trace event for a run id (same-process fallback). */
+export declare function findDevTraceEventForRun(runId: string): DevTraceEvent | undefined;
+export declare function appendDevTraceEvent(event: DevTraceEvent, cwd?: string): void;
+export declare function devTraceUrl(port?: number, runId?: string): string;
+/** User-facing startup banner lines for `paybond dev loop`. */
+export declare function buildDevStartupBannerLines(port?: number): string[];
+export declare function devTraceHasCredentials(): boolean;
+export declare function appendDevAuditLog(cwd: string, entry: Record<string, unknown>): Promise<string>;
+export declare function devTraceStepsFromEvents(events: readonly PaybondTraceEvent[]): DevTraceStep[];
+/** Reset in-memory dev trace state (tests and local dashboard restarts). */
+export declare function clearDevTraceEvents(): void;
+/** Activate an in-process dev trace collector for the next bind/execute cycle. */
+export declare function activateDevTraceCollector(options: {
+    preset: string;
+    intentId?: string;
+    cwd?: string;
+}): void;
+/** Resolve the active dev trace sink for {@link PaybondAgentRun.bind}. */
+export declare function resolveDevTraceSink(): PaybondTraceSink | undefined;
+/** Finalize and persist the active dev trace collector as a dashboard event. */
+export declare function finalizeDevTraceCollector(resultBody?: Record<string, unknown>, cwd?: string): DevTraceEvent | undefined;
+export declare function recordSmokeTraceEvent(input: {
+    preset: string;
+    bind: Record<string, unknown>;
+    execute: Record<string, unknown>;
+    resultBody: Record<string, unknown>;
+}, cwd?: string): DevTraceEvent;

package/dist/dev/trace-buffer.js

@@ -0,0 +1,330 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const DEV_TRACE_DEFAULT_PORT = 9477;
+export const DEV_AUDIT_DIR = ".paybond";
+export const DEV_AUDIT_FILE = join(DEV_AUDIT_DIR, "dev-audit.jsonl");
+export const DEV_TRACE_FILE = join(DEV_AUDIT_DIR, "dev-trace.jsonl");
+export const DEV_DEFAULT_POLICY_FILE = "paybond.policy.yaml";
+export const DEV_DEFAULT_PRESET = "travel";
+const MAX_TRACE_EVENTS = 100;
+const traceEvents = [];
+/** Read persisted dev trace events from `.paybond/dev-trace.jsonl`. */
+export function readDevTraceEventsFromDisk(cwd) {
+    const path = join(cwd, DEV_TRACE_FILE);
+    if (!existsSync(path)) {
+        return [];
+    }
+    return readFileSync(path, "utf8")
+        .split("\n")
+        .filter((line) => line.trim().length > 0)
+        .map((line) => JSON.parse(line));
+}
+function mergeDevTraceEvents(fromDisk, fromMemory) {
+    const byId = new Map();
+    for (const event of fromDisk) {
+        byId.set(event.id, event);
+    }
+    for (const event of fromMemory) {
+        byId.set(event.id, event);
+    }
+    return [...byId.values()].sort((left, right) => left.recorded_at.localeCompare(right.recorded_at));
+}
+/** List dev trace events from disk (when `cwd` is set) and the in-process ring buffer. */
+export function listDevTraceEvents(cwd) {
+    const memory = [...traceEvents];
+    if (!cwd) {
+        return memory;
+    }
+    return mergeDevTraceEvents(readDevTraceEventsFromDisk(cwd), memory);
+}
+function trimDevTraceFileSync(path) {
+    if (!existsSync(path)) {
+        return;
+    }
+    const lines = readFileSync(path, "utf8").split("\n").filter((line) => line.trim().length > 0);
+    if (lines.length <= MAX_TRACE_EVENTS) {
+        return;
+    }
+    writeFileSync(path, `${lines.slice(-MAX_TRACE_EVENTS).join("\n")}\n`, "utf8");
+}
+function persistDevTraceEventSync(cwd, event) {
+    const dir = join(cwd, DEV_AUDIT_DIR);
+    mkdirSync(dir, { recursive: true });
+    const path = join(cwd, DEV_TRACE_FILE);
+    appendFileSync(path, `${JSON.stringify(event)}\n`, "utf8");
+    trimDevTraceFileSync(path);
+}
+/** Find the most recent in-memory dev trace event for a run id (same-process fallback). */
+export function findDevTraceEventForRun(runId) {
+    const normalized = runId.trim();
+    for (let index = traceEvents.length - 1; index >= 0; index -= 1) {
+        const event = traceEvents[index];
+        if (event?.run_id === normalized || event?.id === normalized) {
+            return event;
+        }
+    }
+    return undefined;
+}
+export function appendDevTraceEvent(event, cwd) {
+    traceEvents.push(event);
+    while (traceEvents.length > MAX_TRACE_EVENTS) {
+        traceEvents.shift();
+    }
+    if (cwd) {
+        persistDevTraceEventSync(cwd, event);
+    }
+}
+export function devTraceUrl(port = DEV_TRACE_DEFAULT_PORT, runId) {
+    const base = `http://localhost:${port}`;
+    return runId ? `${base}/runs/${encodeURIComponent(runId)}` : base;
+}
+/** User-facing startup banner lines for `paybond dev loop`. */
+export function buildDevStartupBannerLines(port = DEV_TRACE_DEFAULT_PORT) {
+    return [
+        "✓ Sandbox capability (or: offline mock)",
+        "✓ Settlement simulator",
+        `✓ Trace dashboard → ${devTraceUrl(port)}`,
+        `✓ Audit log → ${DEV_AUDIT_FILE}`,
+    ];
+}
+export function devTraceHasCredentials() {
+    return Boolean(process.env.PAYBOND_API_KEY?.trim());
+}
+export async function appendDevAuditLog(cwd, entry) {
+    const dir = join(cwd, DEV_AUDIT_DIR);
+    await mkdir(dir, { recursive: true });
+    const path = join(cwd, DEV_AUDIT_FILE);
+    await appendFile(path, `${JSON.stringify(entry)}\n`, "utf8");
+    return path;
+}
+export function devTraceStepsFromEvents(events) {
+    const steps = [];
+    for (const event of events) {
+        switch (event.type) {
+            case "tool_selected":
+                steps.push({
+                    phase: "tool",
+                    label: `Tool call: ${event.toolName}`,
+                    recorded_at: event.recordedAt,
+                    detail: { operation: event.operation, tool_call_id: event.toolCallId },
+                });
+                break;
+            case "spend_authorized":
+                steps.push({
+                    phase: "authorize",
+                    label: `Paybond approved $${(event.amountCents / 100).toFixed(2)}`,
+                    recorded_at: event.recordedAt,
+                    detail: {
+                        audit_id: event.auditId,
+                        decision_id: event.decisionId,
+                        amount_cents: event.amountCents,
+                    },
+                });
+                break;
+            case "spend_denied":
+                steps.push({
+                    phase: "authorize",
+                    label: `Spend denied: ${event.message}`,
+                    recorded_at: event.recordedAt,
+                    detail: { audit_id: event.auditId, code: event.code },
+                });
+                break;
+            case "approval_required":
+                steps.push({
+                    phase: "authorize",
+                    label: `Approval required: ${event.message}`,
+                    recorded_at: event.recordedAt,
+                    detail: { audit_id: event.auditId, code: event.code },
+                });
+                break;
+            case "tool_executed":
+                steps.push({
+                    phase: "result",
+                    label: `Tool executed (${event.durationMs}ms)`,
+                    recorded_at: event.recordedAt,
+                    detail: { duration_ms: event.durationMs },
+                });
+                break;
+            case "evidence_submitted":
+                steps.push({
+                    phase: "evidence",
+                    label: event.predicatePassed === false ? "Evidence submitted (predicate failed)" : "Evidence submitted",
+                    recorded_at: event.recordedAt,
+                    detail: {
+                        evidence_id: event.evidenceId,
+                        preset_id: event.presetId,
+                        evidence_preset: event.evidencePreset ?? event.presetId,
+                        sandbox_lifecycle_status: event.sandboxLifecycleStatus,
+                        predicate_passed: event.predicatePassed,
+                    },
+                });
+                if (event.sandboxLifecycleStatus) {
+                    steps.push({
+                        phase: "result",
+                        label: `Settlement: ${event.sandboxLifecycleStatus}`,
+                        recorded_at: event.recordedAt,
+                        detail: { sandbox_lifecycle_status: event.sandboxLifecycleStatus },
+                    });
+                }
+                break;
+            case "spend_finalized":
+                if (event.status === "consumed") {
+                    steps.push({
+                        phase: "result",
+                        label: "Spend authorization consumed",
+                        recorded_at: event.recordedAt,
+                        detail: { status: event.status },
+                    });
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    return steps;
+}
+function summarizeTraceEvents(events) {
+    const toolSelected = events.find((event) => event.type === "tool_selected");
+    const spendAuthorized = events.find((event) => event.type === "spend_authorized");
+    const evidenceSubmitted = events.find((event) => event.type === "evidence_submitted");
+    const spendDenied = events.some((event) => event.type === "spend_denied" || event.type === "approval_required");
+    return {
+        operation: toolSelected?.operation ?? spendAuthorized?.operation ?? "",
+        runId: toolSelected?.runId ?? spendAuthorized?.runId ?? `trace-${Date.now()}`,
+        requestedSpendCents: spendAuthorized?.amountCents,
+        authorized: Boolean(spendAuthorized) && !spendDenied,
+        evidenceSubmitted: Boolean(evidenceSubmitted),
+        sandboxLifecycleStatus: evidenceSubmitted?.sandboxLifecycleStatus,
+    };
+}
+class DevTraceCollector {
+    options;
+    events = [];
+    constructor(options) {
+        this.options = options;
+    }
+    sink = (event) => {
+        this.events.push(event);
+    };
+    finalize(resultBody, cwd) {
+        if (this.events.length === 0) {
+            return undefined;
+        }
+        const summary = summarizeTraceEvents(this.events);
+        const event = {
+            id: summary.runId,
+            recorded_at: this.events.at(-1)?.recordedAt ?? new Date().toISOString(),
+            preset: this.options.preset,
+            operation: summary.operation,
+            intent_id: this.options.intentId,
+            run_id: summary.runId,
+            requested_spend_cents: summary.requestedSpendCents,
+            authorized: summary.authorized,
+            evidence_submitted: summary.evidenceSubmitted,
+            sandbox_lifecycle_status: summary.sandboxLifecycleStatus,
+            result_status: typeof resultBody?.status === "string" ? resultBody.status : undefined,
+            cost_cents: typeof resultBody?.cost_cents === "number" ? resultBody.cost_cents : undefined,
+            steps: devTraceStepsFromEvents(this.events),
+            trace_events: [...this.events],
+        };
+        appendDevTraceEvent(event, cwd);
+        return event;
+    }
+}
+let activeDevTraceCollector;
+let activeDevTraceCollectorCwd;
+/** Reset in-memory dev trace state (tests and local dashboard restarts). */
+export function clearDevTraceEvents() {
+    traceEvents.length = 0;
+    activeDevTraceCollector = undefined;
+    activeDevTraceCollectorCwd = undefined;
+}
+/** Activate an in-process dev trace collector for the next bind/execute cycle. */
+export function activateDevTraceCollector(options) {
+    activeDevTraceCollector = new DevTraceCollector(options);
+    activeDevTraceCollectorCwd = options.cwd;
+}
+/** Resolve the active dev trace sink for {@link PaybondAgentRun.bind}. */
+export function resolveDevTraceSink() {
+    return activeDevTraceCollector?.sink;
+}
+/** Finalize and persist the active dev trace collector as a dashboard event. */
+export function finalizeDevTraceCollector(resultBody, cwd) {
+    const event = activeDevTraceCollector?.finalize(resultBody, cwd ?? activeDevTraceCollectorCwd);
+    activeDevTraceCollector = undefined;
+    activeDevTraceCollectorCwd = undefined;
+    return event;
+}
+export function recordSmokeTraceEvent(input, cwd) {
+    const runId = String(input.bind.run_id ?? "smoke-1");
+    const event = {
+        id: runId,
+        recorded_at: new Date().toISOString(),
+        preset: input.preset,
+        operation: String(input.bind.operation ?? ""),
+        intent_id: typeof input.bind.intent_id === "string" ? input.bind.intent_id : undefined,
+        run_id: runId,
+        requested_spend_cents: typeof input.bind.requested_spend_cents === "number"
+            ? input.bind.requested_spend_cents
+            : undefined,
+        authorized: true,
+        evidence_submitted: Boolean(input.execute.evidence_submitted ?? input.execute.evidence),
+        sandbox_lifecycle_status: typeof input.execute.sandbox_lifecycle_status === "string"
+            ? input.execute.sandbox_lifecycle_status
+            : typeof input.bind.sandbox_lifecycle_status === "string"
+                ? input.bind.sandbox_lifecycle_status
+                : undefined,
+        result_status: typeof input.resultBody.status === "string" ? input.resultBody.status : undefined,
+        cost_cents: typeof input.resultBody.cost_cents === "number" ? input.resultBody.cost_cents : undefined,
+        steps: devTraceStepsFromEvents([
+            {
+                type: "tool_selected",
+                runId,
+                toolName: String(input.bind.operation ?? "tool"),
+                toolCallId: "smoke-1",
+                operation: String(input.bind.operation ?? ""),
+                recordedAt: new Date().toISOString(),
+            },
+            {
+                type: "spend_authorized",
+                runId,
+                toolCallId: "smoke-1",
+                operation: String(input.bind.operation ?? ""),
+                auditId: "smoke",
+                amountCents: typeof input.bind.requested_spend_cents === "number"
+                    ? input.bind.requested_spend_cents
+                    : 0,
+                recordedAt: new Date().toISOString(),
+            },
+            {
+                type: "tool_executed",
+                runId,
+                toolCallId: "smoke-1",
+                operation: String(input.bind.operation ?? ""),
+                durationMs: 0,
+                recordedAt: new Date().toISOString(),
+            },
+            ...((input.execute.evidence_submitted ?? input.execute.evidence)
+                ? [
+                    {
+                        type: "evidence_submitted",
+                        runId,
+                        toolCallId: "smoke-1",
+                        operation: String(input.bind.operation ?? ""),
+                        evidenceId: `evidence:${String(input.bind.intent_id ?? "smoke")}:smoke-1`,
+                        presetId: input.preset,
+                        evidencePreset: input.preset,
+                        sandboxLifecycleStatus: typeof input.execute.sandbox_lifecycle_status === "string"
+                            ? input.execute.sandbox_lifecycle_status
+                            : undefined,
+                        recordedAt: new Date().toISOString(),
+                    },
+                ]
+                : []),
+        ]),
+    };
+    appendDevTraceEvent(event, cwd);
+    return event;
+}

package/dist/dev/trace-security-headers.d.ts

@@ -0,0 +1,11 @@
+/** Security headers applied to every dev trace dashboard HTTP response. */
+export declare const DEV_TRACE_SECURITY_HEADERS: {
+    readonly "cache-control": "no-store";
+    readonly "content-security-policy": "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'";
+    readonly "permissions-policy": "camera=(), microphone=(), geolocation=(), payment=()";
+    readonly "referrer-policy": "no-referrer";
+    readonly "x-content-type-options": "nosniff";
+    readonly "x-frame-options": "DENY";
+};
+/** Merge dev trace security headers with a response content type. */
+export declare function devTraceResponseHeaders(contentType: string): Record<string, string>;