praxis-agent 0.65.0 → 0.67.0

package/dist/persistence/native-compaction-receipt-store.js

@@ -0,0 +1,380 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { writeFileAtomically } from '../platform/atomic-write.js';
+import { ExclusiveFileLease } from '../platform/exclusive-file-lease.js';
+export const NATIVE_COMPACTION_RECEIPT_VERSION = 1;
+const MAX_RECEIPTS = 4096;
+const MAX_BYTES = 512 * 1024;
+function recordKeys(value, keys) {
+    return Object.keys(value).every((key) => keys.includes(key));
+}
+function exactKeys(value, keys) {
+    return Object.keys(value).length === keys.length && recordKeys(value, keys);
+}
+function nonblank(value, field) {
+    if (typeof value !== 'string' || value.trim() === '')
+        throw new TypeError(`${field} must not be blank`);
+}
+function usage(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const row = value;
+    if (!recordKeys(row, [
+        'inputTokens',
+        'outputTokens',
+        'cacheReadInputTokens',
+        'cacheCreationInputTokens',
+        'cacheCreationInputTokens1h',
+        'webSearchRequests',
+        'contextWindow',
+        'maxOutputTokens',
+    ]))
+        return false;
+    for (const field of [
+        'inputTokens',
+        'outputTokens',
+        'cacheReadInputTokens',
+        'cacheCreationInputTokens',
+        'cacheCreationInputTokens1h',
+        'webSearchRequests',
+    ]) {
+        const n = row[field];
+        if (n !== undefined && (!Number.isSafeInteger(n) || Number(n) < 0))
+            return false;
+    }
+    for (const field of ['contextWindow', 'maxOutputTokens']) {
+        const n = row[field];
+        if (n !== undefined && (!Number.isSafeInteger(n) || Number(n) < 0))
+            return false;
+    }
+    if (Number(row.cacheCreationInputTokens1h ?? 0) >
+        Number(row.cacheCreationInputTokens ?? 0))
+        return false;
+    return (Number.isSafeInteger(row.inputTokens) &&
+        Number(row.inputTokens) >= 0 &&
+        Number.isSafeInteger(row.outputTokens) &&
+        Number(row.outputTokens) >= 0);
+}
+function metric(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const row = value;
+    if (!recordKeys(row, [
+        'usage',
+        'model',
+        'durationApiMs',
+        'durationApiWithoutRetriesMs',
+    ]) ||
+        !usage(row.usage))
+        return false;
+    if (row.model !== undefined &&
+        (typeof row.model !== 'string' || row.model.trim() === ''))
+        return false;
+    if ([
+        row.usage.inputTokens,
+        row.usage.outputTokens,
+        row.usage.cacheReadInputTokens,
+        row.usage.cacheCreationInputTokens,
+        row.usage.cacheCreationInputTokens1h,
+        row.usage.webSearchRequests,
+    ].some((value) => typeof value === 'number' && value > 0) &&
+        row.model === undefined)
+        return false;
+    return [row.durationApiMs, row.durationApiWithoutRetriesMs].every((n) => typeof n === 'number' && Number.isFinite(n) && Number(n) >= 0);
+}
+function parseReceipt(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new TypeError('Invalid compaction receipt');
+    const row = value;
+    const keys = [
+        'version',
+        'receiptId',
+        'sessionId',
+        'boundaryId',
+        'summaryId',
+        'trigger',
+        'metric',
+        'costUsd',
+        'before',
+        'after',
+    ];
+    if (!exactKeys(row, keys) || row.version !== 1 || !metric(row.metric))
+        throw new TypeError('Invalid compaction receipt');
+    for (const key of [
+        'receiptId',
+        'sessionId',
+        'boundaryId',
+        'summaryId',
+        'before',
+        'after',
+    ])
+        nonblank(row[key], key);
+    safeId(row.receiptId);
+    safeId(row.sessionId);
+    safeId(row.boundaryId);
+    safeId(row.summaryId);
+    if (!/^[a-f0-9]{64}$/u.test(row.before) ||
+        !/^[a-f0-9]{64}$/u.test(row.after))
+        throw new TypeError('Invalid compaction accounting fingerprint');
+    if (row.receiptId === row.boundaryId ||
+        row.receiptId === row.summaryId ||
+        row.boundaryId === row.summaryId)
+        throw new TypeError('Compaction receipt IDs must be distinct');
+    if (row.trigger !== 'auto' && row.trigger !== 'manual')
+        throw new TypeError('Invalid compaction receipt trigger');
+    if (row.costUsd !== null &&
+        (typeof row.costUsd !== 'number' ||
+            !Number.isFinite(row.costUsd) ||
+            row.costUsd < 0))
+        throw new TypeError('Invalid compaction receipt cost');
+    const parsedMetric = row.metric;
+    if (parsedMetric.durationApiWithoutRetriesMs > parsedMetric.durationApiMs ||
+        (![
+            parsedMetric.usage.inputTokens,
+            parsedMetric.usage.outputTokens,
+            parsedMetric.usage.cacheReadInputTokens,
+            parsedMetric.usage.cacheCreationInputTokens,
+            parsedMetric.usage.cacheCreationInputTokens1h,
+            parsedMetric.usage.webSearchRequests,
+        ].some((entry) => typeof entry === 'number' && entry > 0) &&
+            row.costUsd !== null))
+        throw new TypeError('Invalid compaction receipt accounting outcome');
+    return structuredClone(row);
+}
+function safeId(value) {
+    if (!/^[A-Za-z0-9_-]{1,128}$/u.test(value))
+        throw new TypeError('Invalid compaction receipt ID');
+}
+export class NativeCompactionReceiptStore {
+    /** Compatibility alias for callers that name the file-backed adapter. */
+    directory;
+    lease;
+    constructor(options) {
+        nonblank(options.sidecarRoot, 'sidecarRoot');
+        this.directory = join(options.sidecarRoot, 'compaction-receipts');
+        this.lease = new ExclusiveFileLease(options.lockFile ??
+            join(options.sidecarRoot, 'locks', 'compaction-receipts.lock'));
+    }
+    async prepare(receipt) {
+        const checked = parseReceipt(receipt);
+        safeId(checked.receiptId);
+        const serialized = `${JSON.stringify(checked)}\n`;
+        if (Buffer.byteLength(serialized, 'utf8') > MAX_BYTES)
+            throw new Error('Invalid compaction receipt file');
+        const handle = await this.acquire();
+        try {
+            const directory = join(this.directory, checked.sessionId);
+            try {
+                const stat = await lstat(directory);
+                if (!stat.isDirectory())
+                    throw new Error('Compaction receipt session path is not a directory');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                await mkdir(directory, { recursive: true, mode: 0o700 });
+            }
+            const requestedIds = new Set([
+                checked.receiptId,
+                checked.boundaryId,
+                checked.summaryId,
+            ]);
+            for (const { receipt: existingReceipt } of await this.list(checked.sessionId)) {
+                if (existingReceipt.receiptId === checked.receiptId)
+                    continue;
+                if ([
+                    existingReceipt.receiptId,
+                    existingReceipt.boundaryId,
+                    existingReceipt.summaryId,
+                ].some((id) => requestedIds.has(id)))
+                    throw new Error('Duplicate compaction transaction identity');
+            }
+            const path = join(directory, `${checked.receiptId}.json`);
+            const ackPath = join(directory, `${checked.receiptId}.ack`);
+            try {
+                await lstat(ackPath);
+                throw new Error('Compaction receipt acknowledgement already exists for this receipt');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            let existing = null;
+            try {
+                const reader = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+                try {
+                    const stat = await reader.stat();
+                    if (!stat.isFile() ||
+                        (stat.mode & 0o077) !== 0 ||
+                        stat.size > MAX_BYTES)
+                        throw new Error('Invalid compaction receipt file');
+                    existing = await reader.readFile('utf8');
+                }
+                finally {
+                    await reader.close();
+                }
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            if (existing !== null) {
+                const prior = parseReceipt(JSON.parse(existing));
+                if (JSON.stringify(prior) !== JSON.stringify(checked))
+                    throw new Error('Compaction receipt ID already contains a different receipt');
+                return;
+            }
+            await writeFileAtomically(path, serialized, { mode: 0o600 });
+        }
+        finally {
+            await handle.release();
+        }
+    }
+    async acknowledge(sessionId, receiptId) {
+        safeId(sessionId);
+        safeId(receiptId);
+        const handle = await this.acquire();
+        try {
+            const directory = join(this.directory, sessionId);
+            const directoryStat = await lstat(directory);
+            if (!directoryStat.isDirectory())
+                throw new Error('Compaction receipt session path is not a directory');
+            const source = join(directory, `${receiptId}.json`);
+            const sourceHandle = await open(source, constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                const stat = await sourceHandle.stat();
+                if (!stat.isFile() || (stat.mode & 0o077) !== 0)
+                    throw new Error('Compaction receipt is not a regular file');
+                if (stat.size > MAX_BYTES)
+                    throw new Error('Invalid compaction receipt file');
+                const parsed = parseReceipt(JSON.parse(await sourceHandle.readFile('utf8')));
+                if (parsed.sessionId !== sessionId || parsed.receiptId !== receiptId)
+                    throw new Error('Compaction receipt path mismatch');
+            }
+            finally {
+                await sourceHandle.close();
+            }
+            const ack = join(directory, `${receiptId}.ack`);
+            try {
+                const marker = await open(ack, constants.O_RDONLY | constants.O_NOFOLLOW);
+                try {
+                    const stat = await marker.stat();
+                    if (!stat.isFile() ||
+                        (stat.mode & 0o077) !== 0 ||
+                        stat.size > 256 ||
+                        (await marker.readFile('utf8')) !== `${receiptId}\n`)
+                        throw new Error('Invalid compaction receipt acknowledgement');
+                    return;
+                }
+                finally {
+                    await marker.close();
+                }
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            await writeFileAtomically(ack, `${receiptId}\n`, { mode: 0o600 });
+        }
+        finally {
+            await handle.release();
+        }
+    }
+    async list(sessionId) {
+        safeId(sessionId);
+        const sessionDirectory = join(this.directory, sessionId);
+        let files;
+        try {
+            const directoryStat = await lstat(sessionDirectory);
+            if (!directoryStat.isDirectory())
+                throw new Error('Compaction receipt session path is not a directory');
+            files = await readdir(sessionDirectory);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+        if (files.length > MAX_RECEIPTS)
+            throw new Error('Too many compaction receipt artifacts');
+        const result = [];
+        const receiptIds = new Set();
+        const transactionIds = new Set();
+        const ackIds = new Set();
+        for (const name of files.sort()) {
+            if (!name.endsWith('.json') && !name.endsWith('.ack'))
+                throw new Error('Unknown compaction receipt artifact');
+            if (name.endsWith('.ack')) {
+                const ackId = name.slice(0, -4);
+                safeId(ackId);
+                ackIds.add(ackId);
+                continue;
+            }
+            const receiptId = name.slice(0, -5);
+            safeId(receiptId);
+            const handle = await open(join(sessionDirectory, name), constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                const stat = await handle.stat();
+                if (!stat.isFile() ||
+                    (stat.mode & 0o077) !== 0 ||
+                    stat.size > MAX_BYTES)
+                    throw new Error('Invalid compaction receipt file');
+                const parsed = parseReceipt(JSON.parse(await handle.readFile('utf8')));
+                if (parsed.sessionId !== sessionId || parsed.receiptId !== receiptId)
+                    throw new Error('Compaction receipt path mismatch');
+                if (receiptIds.has(receiptId))
+                    throw new Error('Duplicate compaction receipt ID');
+                receiptIds.add(receiptId);
+                for (const id of [receiptId, parsed.boundaryId, parsed.summaryId]) {
+                    if (transactionIds.has(id))
+                        throw new Error('Duplicate compaction transaction identity');
+                    transactionIds.add(id);
+                }
+                let acknowledged = false;
+                try {
+                    const marker = await open(join(sessionDirectory, `${receiptId}.ack`), constants.O_RDONLY | constants.O_NOFOLLOW);
+                    try {
+                        const markerStat = await marker.stat();
+                        if (!markerStat.isFile() ||
+                            (markerStat.mode & 0o077) !== 0 ||
+                            markerStat.size > 256 ||
+                            (await marker.readFile('utf8')) !== `${receiptId}\n`)
+                            throw new Error('Invalid compaction receipt acknowledgement');
+                    }
+                    finally {
+                        await marker.close();
+                    }
+                    acknowledged = true;
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+                result.push({ receipt: parsed, acknowledged });
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        for (const ackId of ackIds)
+            if (!receiptIds.has(ackId))
+                throw new Error('Acknowledgement has no receipt');
+        return result.sort((a, b) => a.receipt.receiptId < b.receipt.receiptId
+            ? -1
+            : a.receipt.receiptId > b.receipt.receiptId
+                ? 1
+                : 0);
+    }
+    async acquire() {
+        for (let i = 0; i < 400; i += 1) {
+            const handle = await this.lease.tryAcquire();
+            if (handle)
+                return handle;
+            await new Promise((resolve) => setTimeout(resolve, 5));
+        }
+        throw new Error('Timed out acquiring compaction receipt lock');
+    }
+}
+export { NativeCompactionReceiptStore as NativeCompactionReceiptFileStore };
+//# sourceMappingURL=native-compaction-receipt-store.js.map

package/dist/platform/praxis-build-identity.d.ts

@@ -0,0 +1,14 @@
+export declare const PRAXIS_BUILD_IDENTITY_SCHEMA_VERSION: "1.0";
+export interface PraxisBuildIdentity {
+    schema_version: typeof PRAXIS_BUILD_IDENTITY_SCHEMA_VERSION;
+    source_revision: `git:${string}` | 'unavailable';
+    source_dirty: boolean | null;
+    artifact_sha256: `sha256:${string}`;
+}
+export declare function writePraxisBuildIdentity({ sourceRoot, outputRoot, }: {
+    sourceRoot: string;
+    outputRoot: string;
+}): Promise<PraxisBuildIdentity>;
+export declare function validatePraxisBuildIdentity(value: unknown): PraxisBuildIdentity;
+export declare function loadPraxisBuildIdentity(outputRoot?: string): Promise<PraxisBuildIdentity>;
+//# sourceMappingURL=praxis-build-identity.d.ts.map

package/dist/platform/praxis-build-identity.js

@@ -0,0 +1,204 @@
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { promisify } from 'node:util';
+export const PRAXIS_BUILD_IDENTITY_SCHEMA_VERSION = '1.0';
+const execFileAsync = promisify(execFile);
+const DIGEST = /^sha256:[0-9a-f]{64}$/u;
+const REVISION = /^git:[0-9a-f]{40}$/u;
+const MAX_BYTES = 512 * 1024 * 1024;
+const MAX_FILES = 10_000;
+const MAX_DEPTH = 32;
+const MAX_METADATA_BYTES = 64 * 1024;
+function invalid(message) {
+    throw new Error(`Invalid Praxis build identity: ${message}`);
+}
+function codeUnitCompare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+async function artifactEntries(outputRoot) {
+    const entries = [];
+    let totalBytes = 0;
+    async function hashFile(path) {
+        const handle = await fs.open(path, 'r');
+        const hash = createHash('sha256');
+        const buffer = Buffer.alloc(64 * 1024);
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile())
+                invalid('emitted runtime tree contains a non-regular JavaScript file');
+            if (stat.size > MAX_BYTES - totalBytes)
+                invalid('emitted runtime tree exceeds byte limit');
+            let fileBytes = 0;
+            while (true) {
+                const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
+                if (bytesRead === 0)
+                    break;
+                fileBytes += bytesRead;
+                if (fileBytes > MAX_BYTES - totalBytes)
+                    invalid('emitted runtime tree exceeds byte limit');
+                hash.update(buffer.subarray(0, bytesRead));
+            }
+            totalBytes += fileBytes;
+            return `sha256:${hash.digest('hex')}`;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async function visit(directory, depth) {
+        if (depth > MAX_DEPTH)
+            invalid('emitted runtime tree exceeds depth limit');
+        const children = await fs.readdir(directory, { withFileTypes: true });
+        for (const child of children) {
+            const fullPath = join(directory, child.name);
+            if (child.isSymbolicLink())
+                invalid(`emitted runtime tree contains symlink ${child.name}`);
+            if (child.isDirectory()) {
+                await visit(fullPath, depth + 1);
+                continue;
+            }
+            if (!child.isFile())
+                invalid(`emitted runtime tree contains unsupported entry ${child.name}`);
+            if (!child.name.endsWith('.js'))
+                continue;
+            entries.push({
+                path: relative(outputRoot, fullPath).split(sep).join('/'),
+                sha256: await hashFile(fullPath),
+            });
+            if (entries.length > MAX_FILES)
+                invalid('emitted runtime tree exceeds file limit');
+        }
+    }
+    await visit(outputRoot, 0);
+    if (entries.length === 0)
+        invalid('emitted runtime tree contains no JavaScript files');
+    entries.sort((left, right) => codeUnitCompare(left.path, right.path));
+    return entries;
+}
+async function artifactDigest(outputRoot) {
+    const entries = await artifactEntries(outputRoot);
+    return `sha256:${createHash('sha256').update(JSON.stringify(entries), 'utf8').digest('hex')}`;
+}
+async function sourceState(sourceRoot) {
+    try {
+        const { stdout } = await execFileAsync('git', ['-C', sourceRoot, 'rev-parse', '--verify', 'HEAD'], { encoding: 'utf8' });
+        const revision = stdout.trim();
+        if (!/^[0-9a-f]{40}$/u.test(revision))
+            return { revision: 'unavailable', dirty: null };
+        let status;
+        try {
+            const result = await execFileAsync('git', ['-C', sourceRoot, 'status', '--porcelain=v1', '--untracked-files=all'], { encoding: 'utf8' });
+            status = result.stdout;
+        }
+        catch (error) {
+            throw new Error(`unable to read Git status: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return { revision: `git:${revision}`, dirty: status.length > 0 };
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            error.message.startsWith('unable to read Git status:'))
+            throw error;
+        return { revision: 'unavailable', dirty: null };
+    }
+}
+export async function writePraxisBuildIdentity({ sourceRoot, outputRoot, }) {
+    const state = await sourceState(resolve(sourceRoot));
+    const identity = {
+        schema_version: PRAXIS_BUILD_IDENTITY_SCHEMA_VERSION,
+        source_revision: state.revision,
+        source_dirty: state.dirty,
+        artifact_sha256: await artifactDigest(resolve(outputRoot)),
+    };
+    const target = join(resolve(outputRoot), 'build-identity.json');
+    const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+    await fs.writeFile(temporary, `${JSON.stringify(identity)}\n`, {
+        encoding: 'utf8',
+        mode: 0o644,
+    });
+    await fs.rename(temporary, target);
+    return identity;
+}
+export function validatePraxisBuildIdentity(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        invalid('metadata must be an object');
+    const source = value;
+    const keys = [
+        'schema_version',
+        'source_revision',
+        'source_dirty',
+        'artifact_sha256',
+    ];
+    const unknown = Object.keys(source).find((key) => !keys.includes(key));
+    if (unknown)
+        invalid(`${unknown} is not supported`);
+    if (source.schema_version !== PRAXIS_BUILD_IDENTITY_SCHEMA_VERSION)
+        invalid('schema_version must be "1.0"');
+    if (typeof source.source_revision !== 'string' ||
+        (source.source_revision !== 'unavailable' &&
+            !REVISION.test(source.source_revision)))
+        invalid('source_revision is invalid');
+    if (source.source_revision === 'unavailable') {
+        if (source.source_dirty !== null)
+            invalid('source_dirty must be null when source_revision is unavailable');
+    }
+    else if (typeof source.source_dirty !== 'boolean')
+        invalid('source_dirty must be boolean for an available source revision');
+    if (typeof source.artifact_sha256 !== 'string' ||
+        !DIGEST.test(source.artifact_sha256))
+        invalid('artifact_sha256 must be a sha256 digest');
+    return Object.freeze({
+        schema_version: PRAXIS_BUILD_IDENTITY_SCHEMA_VERSION,
+        source_revision: source.source_revision,
+        source_dirty: source.source_dirty,
+        artifact_sha256: source.artifact_sha256,
+    });
+}
+export async function loadPraxisBuildIdentity(outputRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../../dist')) {
+    const target = join(resolve(outputRoot), 'build-identity.json');
+    let raw;
+    try {
+        const handle = await fs.open(target, 'r');
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile())
+                invalid('metadata is not a regular file');
+            const buffer = Buffer.alloc(MAX_METADATA_BYTES + 1);
+            let bytesRead = 0;
+            while (bytesRead < buffer.length) {
+                const result = await handle.read(buffer, bytesRead, buffer.length - bytesRead, bytesRead);
+                if (result.bytesRead === 0)
+                    break;
+                bytesRead += result.bytesRead;
+            }
+            if (bytesRead > MAX_METADATA_BYTES || stat.size > MAX_METADATA_BYTES)
+                invalid('metadata exceeds 64 KiB');
+            raw = buffer.subarray(0, bytesRead).toString('utf8');
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            error.message.startsWith('Invalid Praxis build identity:'))
+            throw error;
+        invalid('metadata is missing or unreadable');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        invalid('metadata is not valid JSON');
+    }
+    const identity = validatePraxisBuildIdentity(parsed);
+    const actual = await artifactDigest(resolve(outputRoot));
+    if (actual !== identity.artifact_sha256)
+        invalid('artifact_sha256 does not match emitted JavaScript');
+    return identity;
+}
+//# sourceMappingURL=praxis-build-identity.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-agent",
-  "version": "0.65.0",
+  "version": "0.67.0",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",
@@ -28,7 +28,7 @@
     "praxis": "./dist/cli.js"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && node scripts/write-build-identity.mjs",
     "check": "npm run format:check && npm run lint && npm run test:docs && npm run verify:release-automation && npm run verify:ci-coverage && npm run verify:fixture-contracts && npm run check:boundaries && npm run typecheck && npm run build:native && npm run build && npm test",
     "check:boundaries": "node scripts/check-boundaries.mjs",
     "dev": "tsx src/cli.ts",