profclaw 2.3.0 → 2.4.0

package/dist/agents/receipt/receipt-cli.js

@@ -0,0 +1,82 @@
+/**
+ * Helpers that connect receipts to the CLI: key handling and writer setup.
+ */
+import { createRequire } from 'node:module';
+import { generateKeyPairSync } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { ReceiptWriter, defaultReceiptPath, loadSignerFromFile } from './receipt-writer.js';
+/** Create the writer for a run. Signing is off unless a key path is given. */
+export function createRunReceipt(args) {
+    const env = args.env ?? process.env;
+    const keyPath = args.signKeyPath ?? (env['PROFCLAW_RECEIPT_KEY']?.trim() || undefined);
+    return new ReceiptWriter({
+        path: defaultReceiptPath(args.projectRoot, args.runId, env),
+        signer: keyPath ? loadSignerFromFile(keyPath) : undefined,
+    });
+}
+/** Version of the running profclaw package, or 'unknown'. */
+export function toolVersion() {
+    try {
+        const pkg = createRequire(import.meta.url)('../../../package.json');
+        return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** Write an Ed25519 keypair into dir. The private key file is mode 0600. */
+export function generateKeyPairFiles(dir) {
+    mkdirSync(dir, { recursive: true });
+    const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+    const privateKeyPath = join(dir, 'receipt-key.pem');
+    const publicKeyPath = join(dir, 'receipt-key.pub.pem');
+    writeFileSync(privateKeyPath, privateKey.export({ type: 'pkcs8', format: 'pem' }), { mode: 0o600, flag: 'wx' });
+    writeFileSync(publicKeyPath, publicKey.export({ type: 'spki', format: 'pem' }), { mode: 0o644, flag: 'wx' });
+    return { privateKeyPath, publicKeyPath };
+}
+function argsSummaryChars(env) {
+    const n = Number(env['PROFCLAW_RECEIPT_ARGS_CHARS']);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : 300;
+}
+/** Short one-line description of tool arguments. Long values are cut so files are not copied into the receipt. */
+export function summarizeArgs(args, maxChars = 300) {
+    const perValue = Math.max(16, Math.floor(maxChars / 3));
+    const parts = Object.entries(args).map(([key, value]) => {
+        const text = typeof value === 'string' ? value : JSON.stringify(value) ?? 'undefined';
+        const short = text.length > perValue ? `${text.slice(0, perValue)}...(${text.length} chars)` : text;
+        return `${key}=${JSON.stringify(short)}`;
+    });
+    const joined = parts.join(' ');
+    return joined.length > maxChars ? `${joined.slice(0, maxChars)}...` : joined;
+}
+/** Everything `profclaw run` needs to record a receipt; a no-op setup when disabled. */
+export function setupRunReceipt(args) {
+    const runId = randomUUID().slice(0, 8);
+    if (!args.enabled)
+        return { runId };
+    const env = args.env ?? process.env;
+    const receipt = createRunReceipt({ projectRoot: args.projectRoot, runId, signKeyPath: args.signKeyPath, env });
+    const cap = argsSummaryChars(env);
+    return {
+        runId,
+        receipt,
+        onToolCall: (e) => {
+            try {
+                receipt.append('tool_call', {
+                    attempt: e.attempt,
+                    name: e.name,
+                    argsSummary: summarizeArgs(e.args, cap),
+                    redacted: false,
+                    durationMs: e.durationMs,
+                    ok: e.ok,
+                });
+            }
+            catch {
+                // Receipt problems must never break the agent; a missing event shows up as a bad chain or gap.
+            }
+        },
+    };
+}
+//# sourceMappingURL=receipt-cli.js.map

package/dist/agents/receipt/receipt-types.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Run receipt types (spec: docs/specs/run-receipt-v0.md).
+ * Shared by the writer, verifier and viewer.
+ */
+export declare const RECEIPT_VERSION = "0";
+/** `prev` of the first event: 64 zeros. */
+export declare const GENESIS_HASH: string;
+export interface RunStartData {
+    goal: string;
+    verifyCommand: string;
+    repoHead: string | null;
+    branch: string;
+    tool: {
+        name: string;
+        version: string;
+    };
+}
+export interface AttemptStartData {
+    attempt: number;
+    model?: string;
+}
+export interface ToolCallData {
+    attempt: number;
+    name: string;
+    argsSummary: string;
+    redacted: boolean;
+    durationMs: number;
+    ok: boolean;
+}
+export type FileChangeKind = 'created' | 'modified' | 'deleted';
+export interface FileChangeData {
+    path: string;
+    status: FileChangeKind;
+    beforeSha256: string | null;
+    afterSha256: string | null;
+    diffSha256: string;
+    diff?: string;
+    diffTruncated?: boolean;
+}
+export interface VerifierResultData {
+    attempt: number;
+    command: string;
+    exitCode: number | null;
+    passed: boolean;
+    output: string;
+    failureScore: number;
+    durationMs?: number;
+    timedOut?: boolean;
+}
+export interface UsageData {
+    attempt: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    totalTokens: number;
+    costUsd: number;
+    model?: string;
+}
+export interface RollbackData {
+    attempt: number;
+    reason: string;
+}
+export type ReceiptOutcome = 'verified' | 'improved' | 'unchanged' | 'worse' | 'agent_error';
+export interface AttemptEndData {
+    attempt: number;
+    outcome: ReceiptOutcome;
+    rolledBack: boolean;
+}
+export interface RunEndData {
+    stopReason: string;
+    verified: boolean;
+    totals: {
+        attempts: number;
+        totalTokens: number;
+        costUsd: number;
+        filesChanged: number;
+    };
+}
+export interface ReceiptDataMap {
+    run_start: RunStartData;
+    attempt_start: AttemptStartData;
+    tool_call: ToolCallData;
+    file_change: FileChangeData;
+    verifier_result: VerifierResultData;
+    usage: UsageData;
+    rollback: RollbackData;
+    attempt_end: AttemptEndData;
+    run_end: RunEndData;
+}
+export type ReceiptEventType = keyof ReceiptDataMap;
+export declare const RECEIPT_EVENT_TYPES: readonly ReceiptEventType[];
+export interface ReceiptSignature {
+    alg: 'ed25519';
+    /** base64 SPKI DER */
+    publicKey: string;
+    /** base64 Ed25519 signature over the UTF-8 bytes of the run_end hash */
+    sig: string;
+}
+interface EventBase {
+    v: typeof RECEIPT_VERSION;
+    seq: number;
+    ts: string;
+    prev: string;
+    hash: string;
+}
+export type ReceiptEvent = {
+    [K in ReceiptEventType]: EventBase & {
+        type: K;
+        data: ReceiptDataMap[K];
+        signature?: ReceiptSignature;
+    };
+}[ReceiptEventType];
+/** Anything that can record receipt events. runVerifiedGoal only needs this. */
+export interface ReceiptSink {
+    append<K extends ReceiptEventType>(type: K, data: ReceiptDataMap[K]): ReceiptEvent;
+}
+export type VerifyFailureReason = 'unreadable' | 'empty' | 'invalid_json' | 'invalid_event' | 'seq_mismatch' | 'prev_mismatch' | 'hash_mismatch' | 'bad_first_event' | 'event_after_run_end' | 'truncated' | 'bad_signature' | 'unsigned' | 'untrusted_key';
+export interface SignatureStatus {
+    present: boolean;
+    valid?: boolean;
+    publicKey?: string;
+}
+export interface VerifyResult {
+    ok: boolean;
+    eventCount: number;
+    /** seq of the first bad event, or the seq where an event was expected (truncation) */
+    firstBadSeq?: number;
+    reason?: VerifyFailureReason;
+    message: string;
+    signature: SignatureStatus;
+    /** Hash of the last event read, when the chain was readable that far */
+    lastHash?: string;
+}
+export {};
+//# sourceMappingURL=receipt-types.d.ts.map

package/dist/agents/receipt/receipt-types.js

@@ -0,0 +1,19 @@
+/**
+ * Run receipt types (spec: docs/specs/run-receipt-v0.md).
+ * Shared by the writer, verifier and viewer.
+ */
+export const RECEIPT_VERSION = '0';
+/** `prev` of the first event: 64 zeros. */
+export const GENESIS_HASH = '0'.repeat(64);
+export const RECEIPT_EVENT_TYPES = [
+    'run_start',
+    'attempt_start',
+    'tool_call',
+    'file_change',
+    'verifier_result',
+    'usage',
+    'rollback',
+    'attempt_end',
+    'run_end',
+];
+//# sourceMappingURL=receipt-types.js.map

package/dist/agents/receipt/receipt-verify.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Receipt verifier: chain integrity, completeness and optional signature.
+ * Reports the first bad seq and why. Spec: docs/specs/run-receipt-v0.md
+ */
+import type { ReceiptEvent, VerifyResult } from './receipt-types.js';
+export interface VerifyOptions {
+    /** Trusted public key (PEM, or base64 SPKI DER). If set, the receipt must be signed by it. */
+    expectedPublicKey?: string;
+    /** Fail an unsigned receipt. Implied by expectedPublicKey. */
+    requireSignature?: boolean;
+}
+/** Normalise a PEM or base64 DER public key to base64 SPKI DER. */
+export declare function normalizePublicKey(input: string): string;
+/** Verify receipt text (JSON Lines). */
+export declare function verifyReceiptText(text: string, options?: VerifyOptions): VerifyResult;
+export declare function verifyReceiptFile(path: string, options?: VerifyOptions): VerifyResult;
+/** Parse events without verifying. For viewers; callers should verify separately. */
+export declare function parseReceiptText(text: string): ReceiptEvent[];
+//# sourceMappingURL=receipt-verify.d.ts.map

package/dist/agents/receipt/receipt-verify.js

@@ -0,0 +1,176 @@
+/**
+ * Receipt verifier: chain integrity, completeness and optional signature.
+ * Reports the first bad seq and why. Spec: docs/specs/run-receipt-v0.md
+ */
+import { createPublicKey, verify as edVerify } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { computeEventHash } from './receipt-writer.js';
+import { GENESIS_HASH, RECEIPT_EVENT_TYPES, RECEIPT_VERSION } from './receipt-types.js';
+const HEX64 = /^[0-9a-f]{64}$/;
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Normalise a PEM or base64 DER public key to base64 SPKI DER. */
+export function normalizePublicKey(input) {
+    const trimmed = input.trim();
+    const key = trimmed.includes('-----BEGIN')
+        ? createPublicKey(trimmed)
+        : createPublicKey({ key: Buffer.from(trimmed, 'base64'), format: 'der', type: 'spki' });
+    return key.export({ type: 'spki', format: 'der' }).toString('base64');
+}
+function fail(events, seq, reason, message, extra = {}) {
+    return { ok: false, eventCount: events, firstBadSeq: seq, reason, message, signature: { present: false }, ...extra };
+}
+/** Structural check of one parsed line. Returns a problem description or null. */
+function shapeProblem(obj) {
+    if (obj['v'] !== RECEIPT_VERSION)
+        return `unsupported version ${JSON.stringify(obj['v'])}`;
+    if (typeof obj['seq'] !== 'number' || !Number.isInteger(obj['seq']))
+        return 'seq is not an integer';
+    if (typeof obj['ts'] !== 'string')
+        return 'ts is not a string';
+    if (typeof obj['type'] !== 'string')
+        return 'type is not a string';
+    if (!isRecord(obj['data']))
+        return 'data is not an object';
+    if (typeof obj['prev'] !== 'string' || !HEX64.test(obj['prev']))
+        return 'prev is not a sha256 hex string';
+    if (typeof obj['hash'] !== 'string' || !HEX64.test(obj['hash']))
+        return 'hash is not a sha256 hex string';
+    return null;
+}
+/** Verify receipt text (JSON Lines). */
+export function verifyReceiptText(text, options = {}) {
+    const lines = text.split('\n');
+    if (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    if (lines.length === 0)
+        return fail(0, 0, 'empty', 'Receipt is empty: expected a run_start event at seq 0');
+    let prev = GENESIS_HASH;
+    let runEnd;
+    let count = 0;
+    for (let i = 0; i < lines.length; i++) {
+        let parsed;
+        try {
+            parsed = JSON.parse(lines[i]);
+        }
+        catch {
+            return fail(count, i, 'invalid_json', `Line ${i + 1} (seq ${i}) is not valid JSON`);
+        }
+        if (!isRecord(parsed))
+            return fail(count, i, 'invalid_event', `Line ${i + 1} (seq ${i}) is not a JSON object`);
+        const problem = shapeProblem(parsed);
+        if (problem)
+            return fail(count, i, 'invalid_event', `Event at seq ${i}: ${problem}`);
+        if (runEnd) {
+            return fail(count, i, 'event_after_run_end', `Event at seq ${i} follows run_end`);
+        }
+        if (parsed['seq'] !== i) {
+            return fail(count, i, 'seq_mismatch', `Expected seq ${i} but found seq ${String(parsed['seq'])}: events were reordered, or one was deleted or inserted`);
+        }
+        if (parsed['prev'] !== prev) {
+            return fail(count, i, 'prev_mismatch', `seq ${i}: prev does not match the hash of seq ${i - 1}: the previous event was changed or removed`);
+        }
+        const expected = computeEventHash(parsed);
+        if (parsed['hash'] !== expected) {
+            return fail(count, i, 'hash_mismatch', `seq ${i}: hash does not match the event content: the event was edited`);
+        }
+        if (i === 0 && parsed['type'] !== 'run_start') {
+            return fail(count, 0, 'bad_first_event', `seq 0 must be run_start, found ${String(parsed['type'])}`);
+        }
+        prev = parsed['hash'];
+        count++;
+        if (parsed['type'] === 'run_end')
+            runEnd = parsed;
+    }
+    if (!runEnd) {
+        return fail(count, count, 'truncated', `No run_end event after seq ${count - 1}: the receipt is truncated or the run did not finish`, {
+            lastHash: prev,
+        });
+    }
+    return checkSignature(runEnd, count, prev, options);
+}
+function checkSignature(runEnd, count, lastHash, options) {
+    const seq = count - 1;
+    const sig = runEnd['signature'];
+    const wantSigned = options.requireSignature === true || options.expectedPublicKey !== undefined;
+    if (sig === undefined) {
+        if (wantSigned) {
+            return fail(count, seq, 'unsigned', 'Receipt has no signature but one is required', { lastHash });
+        }
+        return { ok: true, eventCount: count, message: `Chain intact, ${count} events, run complete (unsigned)`, signature: { present: false }, lastHash };
+    }
+    if (!isRecord(sig) || sig['alg'] !== 'ed25519' || typeof sig['publicKey'] !== 'string' || typeof sig['sig'] !== 'string') {
+        return fail(count, seq, 'bad_signature', 'run_end signature block is malformed', { lastHash, signature: { present: true, valid: false } });
+    }
+    const publicKey = sig['publicKey'];
+    let valid = false;
+    try {
+        const key = createPublicKey({ key: Buffer.from(publicKey, 'base64'), format: 'der', type: 'spki' });
+        valid = edVerify(null, Buffer.from(lastHash, 'utf-8'), key, Buffer.from(sig['sig'], 'base64'));
+    }
+    catch {
+        valid = false;
+    }
+    if (!valid) {
+        return fail(count, seq, 'bad_signature', 'Signature does not verify against the last hash', {
+            lastHash,
+            signature: { present: true, valid: false, publicKey },
+        });
+    }
+    if (options.expectedPublicKey !== undefined) {
+        let trusted;
+        try {
+            trusted = normalizePublicKey(options.expectedPublicKey);
+        }
+        catch {
+            return fail(count, seq, 'untrusted_key', 'The expected public key could not be parsed', { lastHash, signature: { present: true, valid: true, publicKey } });
+        }
+        if (trusted !== publicKey) {
+            return fail(count, seq, 'untrusted_key', 'Signature is valid but the signing key is not the expected key', {
+                lastHash,
+                signature: { present: true, valid: true, publicKey },
+            });
+        }
+    }
+    return {
+        ok: true,
+        eventCount: count,
+        message: `Chain intact, ${count} events, run complete, signature valid`,
+        signature: { present: true, valid: true, publicKey },
+        lastHash,
+    };
+}
+export function verifyReceiptFile(path, options = {}) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf-8');
+    }
+    catch (error) {
+        return fail(0, 0, 'unreadable', `Cannot read ${path}: ${error instanceof Error ? error.message : 'unknown error'}`);
+    }
+    return verifyReceiptText(text, options);
+}
+/** Parse events without verifying. For viewers; callers should verify separately. */
+export function parseReceiptText(text) {
+    const events = [];
+    for (const line of text.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (isRecord(parsed) && shapeProblem(parsed) === null && isKnownType(parsed['type'])) {
+            events.push(parsed);
+        }
+    }
+    return events;
+}
+function isKnownType(t) {
+    return typeof t === 'string' && RECEIPT_EVENT_TYPES.includes(t);
+}
+//# sourceMappingURL=receipt-verify.js.map

package/dist/agents/receipt/receipt-view.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Receipt viewer: a terminal summary and a self-contained single-file HTML page
+ * (inline CSS and JS, no external assets). Every piece of receipt data is
+ * HTML-escaped, and a CSP meta tag blocks anything not inline.
+ */
+import type { AttemptEndData, FileChangeData, ReceiptEvent, RollbackData, RunEndData, RunStartData, ToolCallData, UsageData, VerifierResultData, VerifyResult } from './receipt-types.js';
+export interface AttemptView {
+    attempt: number;
+    model?: string;
+    toolCalls: ToolCallData[];
+    verifier?: VerifierResultData;
+    usage?: UsageData;
+    rollbacks: RollbackData[];
+    end?: AttemptEndData;
+}
+export interface ReceiptModel {
+    start?: RunStartData;
+    baseline?: VerifierResultData;
+    attempts: AttemptView[];
+    files: FileChangeData[];
+    end?: RunEndData;
+    startedAt?: string;
+    endedAt?: string;
+}
+export declare function buildReceiptModel(events: ReceiptEvent[]): ReceiptModel;
+export declare function renderTerminalSummary(events: ReceiptEvent[], verify?: VerifyResult): string;
+export declare function escapeHtml(input: string): string;
+export declare function renderHtml(events: ReceiptEvent[], verify?: VerifyResult): string;
+//# sourceMappingURL=receipt-view.d.ts.map