@paybond/kit 0.10.0 → 0.11.1

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[];

package/dist/cli/agent-sandbox-smoke-checklist.js

@@ -0,0 +1,50 @@
+import { basename } from "node:path";
+import { colorize, shouldUseColor } from "./color.js";
+function formatUsdFromCents(cents) {
+    return `$${(cents / 100).toFixed(2)}`;
+}
+function evidencePresetFromBind(bind) {
+    const preset = bind.completion_preset;
+    return typeof preset === "string" && preset.trim() ? preset.trim() : undefined;
+}
+/** Build human-readable sandbox smoke checklist lines for `--format table`. */
+export function formatAgentSandboxSmokeChecklist(options) {
+    const useColor = shouldUseColor(options.globals);
+    const mark = (line) => {
+        if (line.startsWith("✓") || line === "Success") {
+            return colorize(line, "green", useColor);
+        }
+        return line;
+    };
+    const presetLabel = options.presetId?.trim() ||
+        (typeof options.bind.policy_file === "string"
+            ? basename(options.bind.policy_file)
+            : "custom");
+    const lines = [];
+    lines.push(mark(`✓ Policy loaded (${presetLabel})`));
+    if (options.bind.intent_id) {
+        lines.push(mark("✓ Sandbox intent created"));
+    }
+    const operation = String(options.bind.operation ?? "").trim();
+    if (operation) {
+        lines.push(mark(`✓ Tool call: ${operation}`));
+    }
+    const authorization = options.execute.authorization;
+    if (authorization?.allow) {
+        const costCents = typeof options.resultBody.cost_cents === "number"
+            ? options.resultBody.cost_cents
+            : typeof options.bind.requested_spend_cents === "number"
+                ? options.bind.requested_spend_cents
+                : undefined;
+        const spendLabel = costCents !== undefined ? formatUsdFromCents(costCents) : "approved";
+        lines.push(mark(`✓ Spend approved (${spendLabel})`));
+    }
+    const evidence = options.execute.evidence;
+    if (evidence?.submitted) {
+        const preset = evidencePresetFromBind(options.bind) ?? "cost_and_completion";
+        lines.push(mark(`✓ Evidence validated (${preset})`));
+        lines.push(mark("✓ Settlement simulated"));
+    }
+    lines.push(mark("Success"));
+    return lines;
+}

package/dist/cli/command-spec.d.ts

@@ -2,6 +2,7 @@ export declare const COMMAND_PATHS: string[];
 export declare const GLOBAL_FLAG_NAMES: string[];
 export declare const COMMAND_EXAMPLES: Record<string, string[]>;
 export declare const COMPLETIONS: Record<string, string[]>;
+export declare const COMPLETION_PRESET_IDS: string[];
 export declare const WORKFLOWS: Array<{
     title: string;
     description?: string;