@paybond/kit 0.9.8 → 0.11.0

package/dist/cli/agent/env-write.js

@@ -0,0 +1,47 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { quoteEnvValue } from "./env-quote.js";
+export async function appendAgentRunEnvVars(input) {
+    const envPath = resolve(input.cwd, input.envFile);
+    let existing = "";
+    try {
+        existing = await readFile(envPath, "utf8");
+    }
+    catch (err) {
+        if (!(err && typeof err === "object" && "code" in err && err.code === "ENOENT")) {
+            throw err;
+        }
+    }
+    const lines = [
+        `PAYBOND_INTENT_ID=${quoteEnvValue(input.intentId)}`,
+        `PAYBOND_CAPABILITY_TOKEN=${quoteEnvValue(input.capabilityToken)}`,
+        `PAYBOND_RUN_ID=${quoteEnvValue(input.runId)}`,
+    ];
+    const updates = new Map();
+    for (const line of lines) {
+        const key = line.split("=", 1)[0];
+        updates.set(key, line);
+    }
+    const output = [];
+    const seen = new Set();
+    for (const rawLine of existing.split(/\r?\n/)) {
+        const match = /^(\s*(?:export\s+)?([A-Z0-9_]+)\s*=)/.exec(rawLine);
+        if (match && updates.has(match[2])) {
+            output.push(updates.get(match[2]));
+            seen.add(match[2]);
+            continue;
+        }
+        output.push(rawLine);
+    }
+    for (const [key, line] of updates) {
+        if (!seen.has(key)) {
+            output.push(line);
+        }
+    }
+    let body = output.join("\n");
+    if (body.length > 0 && !body.endsWith("\n")) {
+        body += "\n";
+    }
+    await writeFile(envPath, body, { encoding: "utf8", mode: 0o600 });
+    return envPath;
+}

package/dist/cli/agent/paybond.d.ts

@@ -0,0 +1,16 @@
+import { Paybond, type PaybondEnvironment } from "../../index.js";
+import type { CliContext } from "../context.js";
+export declare function apiKeyEnvironment(apiKey: string): PaybondEnvironment | "unknown";
+export declare function assertAgentSandboxDefault(apiKey: string, production: boolean): void;
+export type PaybondAgentCliSession = {
+    paybond: Paybond;
+    apiKey: string;
+    warnings: string[];
+};
+/**
+ * Open a Paybond SDK session and run gateway-backed agent middleware work while
+ * `ctx.fetch` is patched (bootstrap, verify, evidence, spend complete).
+ */
+export declare function withPaybondAgentCli<T>(ctx: CliContext, production: boolean, handler: (session: PaybondAgentCliSession) => Promise<T>): Promise<T>;
+/** @deprecated Use {@link withPaybondAgentCli} so SDK gateway calls stay on `ctx.fetch`. */
+export declare function openPaybondForAgentCli(ctx: CliContext, production: boolean): Promise<PaybondAgentCliSession>;

package/dist/cli/agent/paybond.js

@@ -0,0 +1,55 @@
+import { Paybond } from "../../index.js";
+import { resolveApiKeyWithMeta } from "../credentials.js";
+import { CliError } from "../types.js";
+export function apiKeyEnvironment(apiKey) {
+    if (apiKey.includes("_sandbox_")) {
+        return "sandbox";
+    }
+    if (apiKey.includes("_live_")) {
+        return "live";
+    }
+    return "unknown";
+}
+export function assertAgentSandboxDefault(apiKey, production) {
+    if (production) {
+        return;
+    }
+    const env = apiKeyEnvironment(apiKey);
+    if (env === "live") {
+        throw new CliError("agent commands default to sandbox-only; pass --production to use live credentials", {
+            category: "validation",
+            code: "cli.agent.production_required",
+            exitCode: 1,
+        });
+    }
+}
+/**
+ * Open a Paybond SDK session and run gateway-backed agent middleware work while
+ * `ctx.fetch` is patched (bootstrap, verify, evidence, spend complete).
+ */
+export async function withPaybondAgentCli(ctx, production, handler) {
+    const resolved = await resolveApiKeyWithMeta(ctx.globals, ctx.cwd);
+    assertAgentSandboxDefault(resolved.apiKey, production);
+    const expectedEnvironment = production ? undefined : "sandbox";
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = ctx.fetch;
+    try {
+        const paybond = await Paybond.open({
+            apiKey: resolved.apiKey,
+            gatewayBaseUrl: ctx.globals.gateway,
+            expectedEnvironment,
+        });
+        return await handler({
+            paybond,
+            apiKey: resolved.apiKey,
+            warnings: resolved.warnings,
+        });
+    }
+    finally {
+        globalThis.fetch = originalFetch;
+    }
+}
+/** @deprecated Use {@link withPaybondAgentCli} so SDK gateway calls stay on `ctx.fetch`. */
+export async function openPaybondForAgentCli(ctx, production) {
+    return withPaybondAgentCli(ctx, production, async (session) => session);
+}

package/dist/cli/agent/policy-file.d.ts

@@ -0,0 +1,29 @@
+import type { PaybondToolRegistry } from "../../agent/registry.js";
+import type { PaybondRunBindingSandboxBootstrapInput } from "../../agent/types.js";
+import { PaybondPolicy } from "../../policy/load.js";
+import { type PaybondPolicySnapshot } from "../../policy/snapshot.js";
+export type ResolvedAgentPolicyBind = {
+    policyPath: string;
+    policy: PaybondPolicy;
+    registry: PaybondToolRegistry;
+    policySnapshot: PaybondPolicySnapshot;
+    defaultDeny: boolean;
+    bootstrap?: PaybondRunBindingSandboxBootstrapInput;
+    operation: string;
+    completionPreset?: string;
+};
+/** Resolve bind inputs from persisted policy file content (CLI re-attach for reload). */
+export declare function resolveAgentPolicyBindFromContent(options: {
+    policyPath: string;
+    content: string;
+    operation?: string;
+    requestedSpendCents?: number;
+    forAttach?: boolean;
+}): ResolvedAgentPolicyBind;
+export declare function resolveAgentPolicyBind(options: {
+    cwd: string;
+    policyFile: string;
+    operation?: string;
+    requestedSpendCents?: number;
+    forAttach?: boolean;
+}): Promise<ResolvedAgentPolicyBind>;

package/dist/cli/agent/policy-file.js

@@ -0,0 +1,61 @@
+import { resolve } from "node:path";
+import { PaybondPolicy } from "../../policy/load.js";
+import { parsePolicyDocumentText } from "../../policy/parse-text.js";
+import { parsePaybondPolicyDocument, parsePaybondPolicyDocumentV1 } from "../../policy/schema.js";
+import { PaybondPolicySandboxBootstrapError } from "../../policy/sandbox-bootstrap.js";
+import { createPolicySnapshot } from "../../policy/snapshot.js";
+function resolveAgentPolicyDocument(policyPath, content) {
+    const raw = parsePolicyDocumentText(content, policyPath);
+    const document = parsePaybondPolicyDocument(raw);
+    return PaybondPolicy.fromDocument(parsePaybondPolicyDocumentV1(document));
+}
+function finalizeAgentPolicyBind(policyPath, policy, options) {
+    const registry = policy.toToolRegistry();
+    const defaultDeny = policy.defaultDeny;
+    const policySnapshot = createPolicySnapshot({
+        document: policy.document,
+        registry,
+        source: "file",
+    });
+    if (options.forAttach) {
+        const sideEffecting = Object.entries(policy.document.tools).find(([, entry]) => entry.side_effecting);
+        const operation = options.operation?.trim() ||
+            (sideEffecting
+                ? sideEffecting[1].operation?.trim() || sideEffecting[0]
+                : "");
+        return { policyPath, policy, registry, policySnapshot, defaultDeny, operation };
+    }
+    const bootstrap = policy.sandboxBootstrap({
+        operation: options.operation,
+        requestedSpendCents: options.requestedSpendCents,
+    });
+    return {
+        policyPath,
+        policy,
+        registry,
+        policySnapshot,
+        defaultDeny,
+        bootstrap,
+        operation: bootstrap.operation,
+        completionPreset: bootstrap.completionPreset,
+    };
+}
+/** Resolve bind inputs from persisted policy file content (CLI re-attach for reload). */
+export function resolveAgentPolicyBindFromContent(options) {
+    const policy = resolveAgentPolicyDocument(options.policyPath, options.content);
+    return finalizeAgentPolicyBind(options.policyPath, policy, options);
+}
+export async function resolveAgentPolicyBind(options) {
+    const policyPath = resolve(options.cwd, options.policyFile);
+    let policy;
+    try {
+        policy = await PaybondPolicy.load(policyPath);
+    }
+    catch (err) {
+        if (err instanceof PaybondPolicySandboxBootstrapError) {
+            throw err;
+        }
+        throw err;
+    }
+    return finalizeAgentPolicyBind(policyPath, policy, options);
+}

package/dist/cli/agent/production-evidence.d.ts

@@ -0,0 +1,24 @@
+import type { PaybondRunProductionEvidenceCredentials } from "../../agent/types.js";
+export type PersistedProductionEvidence = {
+    payee_did: string;
+    agent_recognition_key_id: string;
+};
+/** Resolve production auto-evidence credentials from CLI flags and APP_* env fallbacks. */
+export declare function resolveProductionEvidenceFromCli(input: {
+    cwd: string;
+    envFile: string;
+    payeeDid?: string;
+    payeeSigningSeedHex?: string;
+    agentRecognitionKeyId?: string;
+    agentRecognitionSigningSeedHex?: string;
+}): Promise<PaybondRunProductionEvidenceCredentials>;
+export declare function productionEvidenceToPersisted(credentials: PaybondRunProductionEvidenceCredentials): PersistedProductionEvidence;
+/** Re-supply signing seeds at tool execute (or other re-attach) time; metadata comes from the run store. */
+export declare function resolveProductionEvidenceForReattach(input: {
+    cwd: string;
+    envFile: string;
+    persisted: PersistedProductionEvidence;
+    payeeSigningSeedHex?: string;
+    agentRecognitionSigningSeedHex?: string;
+    command?: string;
+}): Promise<PaybondRunProductionEvidenceCredentials>;

package/dist/cli/agent/production-evidence.js

@@ -0,0 +1,98 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { readEnvFileValue } from "../credentials.js";
+import { CliError } from "../types.js";
+function resolveEnvPath(cwd, envFile) {
+    return resolve(cwd, envFile);
+}
+async function readConfiguredEnvValue(cwd, envFile, key) {
+    const fromProcess = process.env[key]?.trim();
+    if (fromProcess) {
+        return fromProcess;
+    }
+    try {
+        const body = await readFile(resolveEnvPath(cwd, envFile), "utf8");
+        return readEnvFileValue(body, key);
+    }
+    catch (err) {
+        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+            return undefined;
+        }
+        throw err;
+    }
+}
+function parseSeed32Hex(raw, field) {
+    const hex = raw.trim().replace(/^0x/i, "");
+    if (!/^[0-9a-fA-F]{64}$/.test(hex)) {
+        throw new CliError(`${field} must be a 32-byte Ed25519 seed (64 hex characters)`, {
+            category: "usage",
+            code: "cli.agent.invalid_signing_seed",
+            details: { field },
+        });
+    }
+    const out = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+        out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+/** Resolve production auto-evidence credentials from CLI flags and APP_* env fallbacks. */
+export async function resolveProductionEvidenceFromCli(input) {
+    const payeeDid = input.payeeDid?.trim() ||
+        (await readConfiguredEnvValue(input.cwd, input.envFile, "APP_PAYEE_DID"));
+    const payeeSigningSeedHex = input.payeeSigningSeedHex?.trim() ||
+        (await readConfiguredEnvValue(input.cwd, input.envFile, "APP_PAYEE_SEED_HEX"));
+    const agentRecognitionKeyId = input.agentRecognitionKeyId?.trim() ||
+        (await readConfiguredEnvValue(input.cwd, input.envFile, "APP_AGENT_RECOGNITION_KEY_ID"));
+    const agentRecognitionSigningSeedHex = input.agentRecognitionSigningSeedHex?.trim() ||
+        (await readConfiguredEnvValue(input.cwd, input.envFile, "APP_AGENT_RECOGNITION_SEED_HEX"));
+    if (!payeeDid) {
+        throw new CliError("production attach requires --payee-did or APP_PAYEE_DID", { category: "usage", code: "cli.agent.production_evidence_incomplete" });
+    }
+    if (!payeeSigningSeedHex) {
+        throw new CliError("production attach requires --payee-signing-seed-hex or APP_PAYEE_SEED_HEX", { category: "usage", code: "cli.agent.production_evidence_incomplete" });
+    }
+    if (!agentRecognitionKeyId) {
+        throw new CliError("production attach requires --agent-recognition-key-id or APP_AGENT_RECOGNITION_KEY_ID", { category: "usage", code: "cli.agent.production_evidence_incomplete" });
+    }
+    if (!agentRecognitionSigningSeedHex) {
+        throw new CliError("production attach requires --agent-recognition-signing-seed-hex or APP_AGENT_RECOGNITION_SEED_HEX", { category: "usage", code: "cli.agent.production_evidence_incomplete" });
+    }
+    return {
+        payeeDid,
+        payeeSigningSeed: parseSeed32Hex(payeeSigningSeedHex, "--payee-signing-seed-hex"),
+        agentRecognitionKeyId,
+        agentRecognitionSigningSeed: parseSeed32Hex(agentRecognitionSigningSeedHex, "--agent-recognition-signing-seed-hex"),
+    };
+}
+export function productionEvidenceToPersisted(credentials) {
+    return {
+        payee_did: credentials.payeeDid,
+        agent_recognition_key_id: credentials.agentRecognitionKeyId,
+    };
+}
+/** Re-supply signing seeds at tool execute (or other re-attach) time; metadata comes from the run store. */
+export async function resolveProductionEvidenceForReattach(input) {
+    const command = input.command ?? "agent tool execute";
+    const payeeDid = input.persisted.payee_did?.trim() ?? "";
+    const keyId = input.persisted.agent_recognition_key_id?.trim() ?? "";
+    if (!payeeDid || !keyId) {
+        throw new CliError("run is missing production_evidence metadata; re-bind with production attach flags", { category: "validation", code: "cli.agent.missing_production_evidence" });
+    }
+    const payeeSigningSeedHex = input.payeeSigningSeedHex?.trim() ||
+        (await readConfiguredEnvValue(input.cwd, input.envFile, "APP_PAYEE_SEED_HEX"));
+    const agentRecognitionSigningSeedHex = input.agentRecognitionSigningSeedHex?.trim() ||
+        (await readConfiguredEnvValue(input.cwd, input.envFile, "APP_AGENT_RECOGNITION_SEED_HEX"));
+    if (!payeeSigningSeedHex) {
+        throw new CliError(`${command} requires --payee-signing-seed-hex or APP_PAYEE_SEED_HEX for production runs`, { category: "usage", code: "cli.agent.production_signing_seed_required" });
+    }
+    if (!agentRecognitionSigningSeedHex) {
+        throw new CliError(`${command} requires --agent-recognition-signing-seed-hex or APP_AGENT_RECOGNITION_SEED_HEX for production runs`, { category: "usage", code: "cli.agent.production_signing_seed_required" });
+    }
+    return {
+        payeeDid,
+        payeeSigningSeed: parseSeed32Hex(payeeSigningSeedHex, "--payee-signing-seed-hex"),
+        agentRecognitionKeyId: keyId,
+        agentRecognitionSigningSeed: parseSeed32Hex(agentRecognitionSigningSeedHex, "--agent-recognition-signing-seed-hex"),
+    };
+}

package/dist/cli/agent/run-store.d.ts

@@ -0,0 +1,30 @@
+import type { PersistedProductionEvidence } from "./production-evidence.js";
+export type PersistedAgentRunContext = {
+    run_id: string;
+    tenant_id: string;
+    intent_id: string;
+    capability_token: string;
+    operation: string;
+    allowed_tools: string[];
+    sandbox: boolean;
+    sandbox_lifecycle_status?: string;
+    requested_spend_cents?: number;
+    completion_preset?: string;
+    registry_file?: string;
+    default_deny?: boolean;
+    policy_digest?: string;
+    policy_version?: string;
+    policy_loaded_at?: string;
+    reload_watch?: boolean;
+    reload_poll?: boolean;
+    last_reload_at?: string;
+    /** Raw policy file content at last successful bind/reload (for CLI re-attach). */
+    policy_bind_content?: string;
+    /** Production auto-evidence credentials for non-sandbox attach binds. */
+    production_evidence?: PersistedProductionEvidence;
+    created_at: string;
+};
+export declare function agentRunsDir(cwd: string): string;
+export declare function agentRunFilePath(cwd: string, runId: string): string;
+export declare function persistAgentRunContext(cwd: string, context: PersistedAgentRunContext): Promise<string>;
+export declare function loadAgentRunContext(cwd: string, runId: string): Promise<PersistedAgentRunContext>;

package/dist/cli/agent/run-store.js

@@ -0,0 +1,42 @@
+import { mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { writeAtomicFileAsync } from "../automation.js";
+import { CliError } from "../types.js";
+export function agentRunsDir(cwd) {
+    return join(cwd, ".paybond", "runs");
+}
+export function agentRunFilePath(cwd, runId) {
+    return join(agentRunsDir(cwd), `${runId.trim()}.json`);
+}
+export async function persistAgentRunContext(cwd, context) {
+    const path = agentRunFilePath(cwd, context.run_id);
+    await mkdir(agentRunsDir(cwd), { recursive: true });
+    await writeAtomicFileAsync(path, `${JSON.stringify(context, null, 2)}\n`, 0o600);
+    return path;
+}
+export async function loadAgentRunContext(cwd, runId) {
+    const path = agentRunFilePath(cwd, runId.trim());
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (err) {
+        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+            throw new CliError(`unknown run_id "${runId}"; run paybond agent run bind first`, {
+                category: "validation",
+                code: "cli.agent.unknown_run_id",
+                exitCode: 1,
+                details: { run_id: runId, path },
+            });
+        }
+        throw err;
+    }
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliError(`invalid run context at ${path}`, {
+            category: "validation",
+            code: "cli.agent.invalid_run_context",
+        });
+    }
+    return parsed;
+}

package/dist/cli/agent/run-trace-store.d.ts

@@ -0,0 +1,39 @@
+import type { PaybondTraceEvent, PaybondTraceSink } from "../../agent/types.js";
+import type { PaybondAgentRun } from "../../agent/run.js";
+import { type AgentRunUpsertInput } from "../../agent/gateway-trace-reporter.js";
+type GatewayAgentRunHost = Readonly<{
+    harbor: {
+        createAgentRunTraceReporter(runId: string): {
+            registerRun(input: AgentRunUpsertInput): void;
+            reportEvent(event: PaybondTraceEvent): void;
+        };
+    };
+}>;
+export type PersistedAgentRunTrace = {
+    run_id: string;
+    intent_id: string;
+    trace_events: PaybondTraceEvent[];
+    updated_at: string;
+};
+export declare function agentRunTraceFilePath(cwd: string, runId: string): string;
+export declare function loadAgentRunTraceIfExistsSync(cwd: string, runId: string): PersistedAgentRunTrace | undefined;
+export declare function loadAgentRunTraceIfExists(cwd: string, runId: string): Promise<PersistedAgentRunTrace | undefined>;
+export declare function loadAgentRunTrace(cwd: string, runId: string): Promise<PersistedAgentRunTrace>;
+export declare function appendAgentRunTraceEventSync(cwd: string, runId: string, event: PaybondTraceEvent, intentId?: string): void;
+export declare function appendAgentRunTraceEvent(cwd: string, runId: string, event: PaybondTraceEvent, intentId?: string): Promise<void>;
+export declare function persistAgentRunTraceEventsSync(cwd: string, runId: string, events: readonly PaybondTraceEvent[], intentId?: string): string;
+export declare function persistAgentRunTraceEvents(cwd: string, runId: string, events: readonly PaybondTraceEvent[], intentId?: string): Promise<string>;
+/** Composite sink that persists per-run trace events and optionally forwards to another sink. */
+export declare function createAgentRunTraceSink(cwd: string, runId: string, options?: {
+    intentId?: string;
+    forward?: PaybondTraceSink;
+}): PaybondTraceSink;
+/** Forward middleware trace events to Gateway when a tenant session is available. */
+export declare function createGatewayAgentRunTraceSink(paybond: GatewayAgentRunHost, runId: string): PaybondTraceSink;
+/** Register run metadata on Gateway after a successful bind. */
+export declare function registerGatewayAgentRun(paybond: GatewayAgentRunHost, run: PaybondAgentRun, options?: {
+    completionPreset?: string;
+}): void;
+/** Composite sink: local run trace file, optional dev collector, optional Gateway reporter. */
+export declare function resolveAgentRunTraceSink(cwd: string, runId: string, intentId?: string, forward?: PaybondTraceSink, gateway?: PaybondTraceSink): PaybondTraceSink;
+export {};

package/dist/cli/agent/run-trace-store.js

@@ -0,0 +1,143 @@
+import { mkdirSync, readFileSync } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
+import { writeAtomicFile, writeAtomicFileAsync } from "../automation.js";
+import { CliError } from "../types.js";
+import { agentRunFilePath, agentRunsDir } from "./run-store.js";
+export function agentRunTraceFilePath(cwd, runId) {
+    return `${agentRunFilePath(cwd, runId).replace(/\.json$/, "")}.trace.json`;
+}
+export function loadAgentRunTraceIfExistsSync(cwd, runId) {
+    const path = agentRunTraceFilePath(cwd, runId);
+    try {
+        const raw = readFileSync(path, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new CliError(`invalid run trace at ${path}`, {
+                category: "validation",
+                code: "cli.agent.invalid_run_trace",
+            });
+        }
+        return parsed;
+    }
+    catch (err) {
+        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+            return undefined;
+        }
+        throw err;
+    }
+}
+export async function loadAgentRunTraceIfExists(cwd, runId) {
+    const path = agentRunTraceFilePath(cwd, runId);
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (err) {
+        if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+            return undefined;
+        }
+        throw err;
+    }
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliError(`invalid run trace at ${path}`, {
+            category: "validation",
+            code: "cli.agent.invalid_run_trace",
+        });
+    }
+    return parsed;
+}
+export async function loadAgentRunTrace(cwd, runId) {
+    const stored = await loadAgentRunTraceIfExists(cwd, runId);
+    if (!stored) {
+        throw new CliError(`no trace events for run "${runId}"; run paybond agent tool execute first`, {
+            category: "validation",
+            code: "cli.agent.trace_not_found",
+            exitCode: 1,
+            details: { run_id: runId, path: agentRunTraceFilePath(cwd, runId) },
+        });
+    }
+    return stored;
+}
+export function appendAgentRunTraceEventSync(cwd, runId, event, intentId) {
+    const existing = loadAgentRunTraceIfExistsSync(cwd, runId);
+    const traceEvents = [...(existing?.trace_events ?? []), event];
+    persistAgentRunTraceEventsSync(cwd, runId, traceEvents, intentId ?? existing?.intent_id ?? "");
+}
+export async function appendAgentRunTraceEvent(cwd, runId, event, intentId) {
+    const existing = await loadAgentRunTraceIfExists(cwd, runId);
+    const traceEvents = [...(existing?.trace_events ?? []), event];
+    await persistAgentRunTraceEvents(cwd, runId, traceEvents, intentId ?? existing?.intent_id ?? "");
+}
+export function persistAgentRunTraceEventsSync(cwd, runId, events, intentId = "") {
+    const path = agentRunTraceFilePath(cwd, runId);
+    mkdirSync(agentRunsDir(cwd), { recursive: true });
+    const payload = {
+        run_id: runId.trim(),
+        intent_id: intentId,
+        trace_events: [...events],
+        updated_at: new Date().toISOString(),
+    };
+    writeAtomicFile(path, `${JSON.stringify(payload, null, 2)}\n`, 0o600);
+    return path;
+}
+export async function persistAgentRunTraceEvents(cwd, runId, events, intentId = "") {
+    const path = agentRunTraceFilePath(cwd, runId);
+    await mkdir(agentRunsDir(cwd), { recursive: true });
+    const payload = {
+        run_id: runId.trim(),
+        intent_id: intentId,
+        trace_events: [...events],
+        updated_at: new Date().toISOString(),
+    };
+    await writeAtomicFileAsync(path, `${JSON.stringify(payload, null, 2)}\n`, 0o600);
+    return path;
+}
+/** Composite sink that persists per-run trace events and optionally forwards to another sink. */
+export function createAgentRunTraceSink(cwd, runId, options) {
+    return (event) => {
+        appendAgentRunTraceEventSync(cwd, runId, event, options?.intentId);
+        options?.forward?.(event);
+    };
+}
+/** Forward middleware trace events to Gateway when a tenant session is available. */
+export function createGatewayAgentRunTraceSink(paybond, runId) {
+    const reporter = paybond.harbor.createAgentRunTraceReporter(runId);
+    return (event) => {
+        reporter.reportEvent(event);
+    };
+}
+/** Register run metadata on Gateway after a successful bind. */
+export function registerGatewayAgentRun(paybond, run, options) {
+    const meta = {
+        intentId: run.intentId,
+        operation: run.binding.sandbox?.operation ?? run.allowedTools[0] ?? "",
+        sandbox: Boolean(run.binding.sandbox),
+        allowedTools: run.allowedTools,
+        completionPreset: options?.completionPreset,
+    };
+    paybond.harbor.createAgentRunTraceReporter(run.runId).registerRun(meta);
+}
+/** Composite sink: local run trace file, optional dev collector, optional Gateway reporter. */
+export function resolveAgentRunTraceSink(cwd, runId, intentId, forward, gateway) {
+    const sinks = [];
+    if (gateway) {
+        sinks.push(gateway);
+    }
+    if (forward) {
+        sinks.push(forward);
+    }
+    const composed = sinks.length === 0
+        ? undefined
+        : sinks.length === 1
+            ? sinks[0]
+            : (event) => {
+                for (const sink of sinks) {
+                    sink(event);
+                }
+            };
+    return createAgentRunTraceSink(cwd, runId, {
+        intentId,
+        forward: composed,
+    });
+}

package/dist/cli/agent-run-trace-table.d.ts

@@ -0,0 +1,9 @@
+import type { DevTraceStep } from "../dev/trace-buffer.js";
+import type { GlobalOptions } from "./types.js";
+/** Build human-readable agent run trace lines for `--format table`. */
+export declare function formatAgentRunTraceTable(options: {
+    runId: string;
+    intentId: string;
+    steps: readonly DevTraceStep[];
+    globals: GlobalOptions;
+}): string[];

package/dist/cli/agent-run-trace-table.js

@@ -0,0 +1,24 @@
+import { colorize, shouldUseColor } from "./color.js";
+/** Build human-readable agent run trace lines for `--format table`. */
+export function formatAgentRunTraceTable(options) {
+    const useColor = shouldUseColor(options.globals);
+    const mark = (line) => {
+        if (line.startsWith("✓")) {
+            return colorize(line, "green", useColor);
+        }
+        return line;
+    };
+    const lines = [
+        `run_id: ${options.runId}`,
+        `intent_id: ${options.intentId}`,
+        "",
+    ];
+    if (options.steps.length === 0) {
+        lines.push("No trace events recorded.");
+        return lines;
+    }
+    for (const step of options.steps) {
+        lines.push(mark(`✓ ${step.label}`));
+    }
+    return lines;
+}

package/dist/cli/agent-sandbox-smoke-checklist.d.ts

@@ -0,0 +1,9 @@
+import type { GlobalOptions } from "./types.js";
+/** Build human-readable sandbox smoke checklist lines for `--format table`. */
+export declare function formatAgentSandboxSmokeChecklist(options: {
+    presetId?: string;
+    bind: Record<string, unknown>;
+    execute: Record<string, unknown>;
+    resultBody: Record<string, unknown>;
+    globals: GlobalOptions;
+}): string[];