open-multi-agent-kit 0.80.5 → 0.80.7

package/dist/core/contract-verification.d.ts

@@ -0,0 +1,78 @@
+/**
+ * `cli.contract.verify` — durable, tamper-evident verification of a CLI contract.
+ *
+ * Builds on the harness-control hash-chained ledger to record a contract
+ * verification as two correlated events (started -> completed/blocked), each
+ * carrying the SHA-256 of the contract's manifest and test files. After
+ * recording, the whole ledger is re-verified; a contract is only `passed` when
+ * both the gate succeeds AND the hash-chain ledger verifies. This lets a release
+ * gate detect after-the-fact tampering of either the contract artifacts or the
+ * audit ledger itself.
+ *
+ * Dependency-free: uses node:crypto only (no fast-check/xterm/etc.).
+ */
+export declare const CONTRACT_VERIFY_EVENT_KIND = "cli.contract.verify";
+export declare const CONTRACT_RESULT_SCHEMA_VERSION = "omk.cli-contract.result.v1";
+export interface ContractFileRef {
+    readonly id: string;
+    readonly path: string;
+}
+export interface ContractFileHash {
+    readonly id: string;
+    readonly path: string;
+    /** `sha256:<hex>` of the file contents. */
+    readonly sha256: string;
+}
+export type ContractVerificationStatus = "passed" | "blocked";
+export interface ContractGateResult {
+    readonly ok: boolean;
+    readonly details?: string;
+}
+export interface ContractLedgerSummary {
+    readonly path: string;
+    readonly verified: boolean;
+    readonly errors: readonly string[];
+}
+export interface ContractResult {
+    readonly schemaVersion: typeof CONTRACT_RESULT_SCHEMA_VERSION;
+    readonly contractId: string;
+    readonly contractVersion: string;
+    readonly status: ContractVerificationStatus;
+    readonly manifestHash: string;
+    readonly testFileHash: string;
+    readonly files: readonly ContractFileHash[];
+    readonly gate: ContractGateResult;
+    readonly ledger: ContractLedgerSummary;
+    readonly startedAt: string;
+    readonly completedAt: string;
+}
+export interface VerifyCliContractOptions {
+    readonly contractId: string;
+    readonly contractVersion: string;
+    readonly manifestPath: string;
+    readonly testPath: string;
+    readonly extraFiles?: readonly ContractFileRef[];
+    /** Runs the actual contract gate (e.g. the vitest contract file). */
+    readonly runGate: () => ContractGateResult | Promise<ContractGateResult>;
+    readonly cwd?: string;
+    readonly logPath?: string;
+    readonly runId?: string;
+    /** When set, a JSON contract-result is written here (atomically). */
+    readonly resultPath?: string;
+    readonly now?: () => Date;
+}
+/**
+ * Verify a CLI contract and append a tamper-evident audit trail.
+ *
+ * Algorithm:
+ *  1. SHA-256 the manifest, test, and any extra contract files.
+ *  2. Record a `started` ledger event (manifest/test hashes + artifact manifest).
+ *  3. Run the contract gate.
+ *  4. Record a `completed` (gate ok) or `blocked` (gate failed) ledger event.
+ *  5. Re-verify the whole hash-chain ledger.
+ *  6. Status is `passed` only when the gate passed AND the ledger verifies;
+ *     otherwise `blocked`.
+ *  7. Optionally write a canonical contract-result.json.
+ */
+export declare function verifyCliContract(options: VerifyCliContractOptions): Promise<ContractResult>;
+//# sourceMappingURL=contract-verification.d.ts.map

package/dist/core/contract-verification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-verification.d.ts","sourceRoot":"","sources":["../../src/core/contract-verification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAaH,eAAO,MAAM,0BAA0B,wBAAwB,CAAC;AAChE,eAAO,MAAM,8BAA8B,+BAA+B,CAAC;AAE3E,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,0BAA0B,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,aAAa,EAAE,OAAO,8BAA8B,CAAC;IAC9D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAC5C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACjD,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACzE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B;AAkBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgFlG","sourcesContent":["/**\n * `cli.contract.verify` — durable, tamper-evident verification of a CLI contract.\n *\n * Builds on the harness-control hash-chained ledger to record a contract\n * verification as two correlated events (started -> completed/blocked), each\n * carrying the SHA-256 of the contract's manifest and test files. After\n * recording, the whole ledger is re-verified; a contract is only `passed` when\n * both the gate succeeds AND the hash-chain ledger verifies. This lets a release\n * gate detect after-the-fact tampering of either the contract artifacts or the\n * audit ledger itself.\n *\n * Dependency-free: uses node:crypto only (no fast-check/xterm/etc.).\n */\n\nimport { createHash, randomUUID } from \"node:crypto\";\nimport { mkdirSync, readFileSync, renameSync, writeFileSync } from \"node:fs\";\nimport { dirname, resolve } from \"node:path\";\nimport {\n\ttype HarnessControlEventOptions,\n\ttype HarnessControlEventWriteResult,\n\trecordHarnessControlEvent,\n\tresolveHarnessControlEventLogPath,\n\tverifyHarnessControlLedger,\n} from \"./harness-control-events.ts\";\n\nexport const CONTRACT_VERIFY_EVENT_KIND = \"cli.contract.verify\";\nexport const CONTRACT_RESULT_SCHEMA_VERSION = \"omk.cli-contract.result.v1\";\n\nexport interface ContractFileRef {\n\treadonly id: string;\n\treadonly path: string;\n}\n\nexport interface ContractFileHash {\n\treadonly id: string;\n\treadonly path: string;\n\t/** `sha256:<hex>` of the file contents. */\n\treadonly sha256: string;\n}\n\nexport type ContractVerificationStatus = \"passed\" | \"blocked\";\n\nexport interface ContractGateResult {\n\treadonly ok: boolean;\n\treadonly details?: string;\n}\n\nexport interface ContractLedgerSummary {\n\treadonly path: string;\n\treadonly verified: boolean;\n\treadonly errors: readonly string[];\n}\n\nexport interface ContractResult {\n\treadonly schemaVersion: typeof CONTRACT_RESULT_SCHEMA_VERSION;\n\treadonly contractId: string;\n\treadonly contractVersion: string;\n\treadonly status: ContractVerificationStatus;\n\treadonly manifestHash: string;\n\treadonly testFileHash: string;\n\treadonly files: readonly ContractFileHash[];\n\treadonly gate: ContractGateResult;\n\treadonly ledger: ContractLedgerSummary;\n\treadonly startedAt: string;\n\treadonly completedAt: string;\n}\n\nexport interface VerifyCliContractOptions {\n\treadonly contractId: string;\n\treadonly contractVersion: string;\n\treadonly manifestPath: string;\n\treadonly testPath: string;\n\treadonly extraFiles?: readonly ContractFileRef[];\n\t/** Runs the actual contract gate (e.g. the vitest contract file). */\n\treadonly runGate: () => ContractGateResult | Promise<ContractGateResult>;\n\treadonly cwd?: string;\n\treadonly logPath?: string;\n\treadonly runId?: string;\n\t/** When set, a JSON contract-result is written here (atomically). */\n\treadonly resultPath?: string;\n\treadonly now?: () => Date;\n}\n\nfunction hashFile(path: string): string {\n\treturn `sha256:${createHash(\"sha256\").update(readFileSync(path)).digest(\"hex\")}`;\n}\n\nfunction writeJsonAtomic(path: string, value: unknown): void {\n\tmkdirSync(dirname(path), { recursive: true });\n\tconst tmp = `${path}.tmp-${process.pid}-${randomUUID()}`;\n\twriteFileSync(tmp, `${JSON.stringify(value, null, 2)}\\n`, { encoding: \"utf-8\", mode: 0o600 });\n\trenameSync(tmp, path);\n}\n\nfunction ledgerErrorOf(record: HarnessControlEventWriteResult): string | undefined {\n\tif (record.ok) return undefined;\n\treturn record.error ? `event not recorded: ${record.error}` : \"event not recorded\";\n}\n\n/**\n * Verify a CLI contract and append a tamper-evident audit trail.\n *\n * Algorithm:\n *  1. SHA-256 the manifest, test, and any extra contract files.\n *  2. Record a `started` ledger event (manifest/test hashes + artifact manifest).\n *  3. Run the contract gate.\n *  4. Record a `completed` (gate ok) or `blocked` (gate failed) ledger event.\n *  5. Re-verify the whole hash-chain ledger.\n *  6. Status is `passed` only when the gate passed AND the ledger verifies;\n *     otherwise `blocked`.\n *  7. Optionally write a canonical contract-result.json.\n */\nexport async function verifyCliContract(options: VerifyCliContractOptions): Promise<ContractResult> {\n\tconst clock = options.now ?? (() => new Date());\n\tconst cwd = options.cwd ?? process.cwd();\n\tconst operationId = randomUUID();\n\tconst startedAt = clock().toISOString();\n\n\tconst files: ContractFileHash[] = [\n\t\t{ id: \"manifest\", path: options.manifestPath, sha256: hashFile(options.manifestPath) },\n\t\t{ id: \"test\", path: options.testPath, sha256: hashFile(options.testPath) },\n\t\t...(options.extraFiles ?? []).map((file) => ({ id: file.id, path: file.path, sha256: hashFile(file.path) })),\n\t];\n\tconst manifestHash = files[0]?.sha256 ?? \"\";\n\tconst testFileHash = files[1]?.sha256 ?? \"\";\n\tconst artifactRefs = files.map((file) => file.path);\n\n\tconst eventBase: HarnessControlEventOptions = {\n\t\tcwd,\n\t\tlogPath: options.logPath,\n\t\trunId: options.runId,\n\t\toperationId,\n\t\tcorrelationId: operationId,\n\t\tartifactRefs,\n\t};\n\n\tconst startedRecord = recordHarnessControlEvent(\n\t\tCONTRACT_VERIFY_EVENT_KIND,\n\t\t\"started\",\n\t\t{ contractId: options.contractId, contractVersion: options.contractVersion, manifestHash, testFileHash, files },\n\t\t{ ...eventBase, now: clock() },\n\t);\n\n\tconst gate = await options.runGate();\n\tconst completedAt = clock().toISOString();\n\n\tconst completedRecord = recordHarnessControlEvent(\n\t\tCONTRACT_VERIFY_EVENT_KIND,\n\t\tgate.ok ? \"completed\" : \"blocked\",\n\t\t{\n\t\t\tcontractId: options.contractId,\n\t\t\tcontractVersion: options.contractVersion,\n\t\t\tmanifestHash,\n\t\t\ttestFileHash,\n\t\t\tgate,\n\t\t},\n\t\t{ ...eventBase, causationId: startedRecord.event?.eventId ?? null, now: clock() },\n\t);\n\n\tconst ledgerPath = resolveHarnessControlEventLogPath({ cwd, logPath: options.logPath, runId: options.runId });\n\tconst ledgerErrors: string[] = [];\n\tlet ledgerChainOk = true;\n\tif (ledgerPath) {\n\t\tconst verification = verifyHarnessControlLedger(ledgerPath);\n\t\tledgerChainOk = verification.ok;\n\t\tledgerErrors.push(...verification.errors);\n\t}\n\tfor (const record of [startedRecord, completedRecord]) {\n\t\tconst error = ledgerErrorOf(record);\n\t\tif (error) ledgerErrors.push(error);\n\t}\n\tconst ledgerVerified = ledgerChainOk && ledgerErrors.length === 0;\n\n\tconst result: ContractResult = {\n\t\tschemaVersion: CONTRACT_RESULT_SCHEMA_VERSION,\n\t\tcontractId: options.contractId,\n\t\tcontractVersion: options.contractVersion,\n\t\tstatus: gate.ok && ledgerVerified ? \"passed\" : \"blocked\",\n\t\tmanifestHash,\n\t\ttestFileHash,\n\t\tfiles,\n\t\tgate,\n\t\tledger: { path: ledgerPath ?? \"\", verified: ledgerVerified, errors: ledgerErrors },\n\t\tstartedAt,\n\t\tcompletedAt,\n\t};\n\n\tif (options.resultPath) {\n\t\twriteJsonAtomic(resolve(cwd, options.resultPath), result);\n\t}\n\n\treturn result;\n}\n"]}

package/dist/core/contract-verification.js

@@ -0,0 +1,110 @@
+/**
+ * `cli.contract.verify` — durable, tamper-evident verification of a CLI contract.
+ *
+ * Builds on the harness-control hash-chained ledger to record a contract
+ * verification as two correlated events (started -> completed/blocked), each
+ * carrying the SHA-256 of the contract's manifest and test files. After
+ * recording, the whole ledger is re-verified; a contract is only `passed` when
+ * both the gate succeeds AND the hash-chain ledger verifies. This lets a release
+ * gate detect after-the-fact tampering of either the contract artifacts or the
+ * audit ledger itself.
+ *
+ * Dependency-free: uses node:crypto only (no fast-check/xterm/etc.).
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { recordHarnessControlEvent, resolveHarnessControlEventLogPath, verifyHarnessControlLedger, } from "./harness-control-events.js";
+export const CONTRACT_VERIFY_EVENT_KIND = "cli.contract.verify";
+export const CONTRACT_RESULT_SCHEMA_VERSION = "omk.cli-contract.result.v1";
+function hashFile(path) {
+    return `sha256:${createHash("sha256").update(readFileSync(path)).digest("hex")}`;
+}
+function writeJsonAtomic(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}-${randomUUID()}`;
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf-8", mode: 0o600 });
+    renameSync(tmp, path);
+}
+function ledgerErrorOf(record) {
+    if (record.ok)
+        return undefined;
+    return record.error ? `event not recorded: ${record.error}` : "event not recorded";
+}
+/**
+ * Verify a CLI contract and append a tamper-evident audit trail.
+ *
+ * Algorithm:
+ *  1. SHA-256 the manifest, test, and any extra contract files.
+ *  2. Record a `started` ledger event (manifest/test hashes + artifact manifest).
+ *  3. Run the contract gate.
+ *  4. Record a `completed` (gate ok) or `blocked` (gate failed) ledger event.
+ *  5. Re-verify the whole hash-chain ledger.
+ *  6. Status is `passed` only when the gate passed AND the ledger verifies;
+ *     otherwise `blocked`.
+ *  7. Optionally write a canonical contract-result.json.
+ */
+export async function verifyCliContract(options) {
+    const clock = options.now ?? (() => new Date());
+    const cwd = options.cwd ?? process.cwd();
+    const operationId = randomUUID();
+    const startedAt = clock().toISOString();
+    const files = [
+        { id: "manifest", path: options.manifestPath, sha256: hashFile(options.manifestPath) },
+        { id: "test", path: options.testPath, sha256: hashFile(options.testPath) },
+        ...(options.extraFiles ?? []).map((file) => ({ id: file.id, path: file.path, sha256: hashFile(file.path) })),
+    ];
+    const manifestHash = files[0]?.sha256 ?? "";
+    const testFileHash = files[1]?.sha256 ?? "";
+    const artifactRefs = files.map((file) => file.path);
+    const eventBase = {
+        cwd,
+        logPath: options.logPath,
+        runId: options.runId,
+        operationId,
+        correlationId: operationId,
+        artifactRefs,
+    };
+    const startedRecord = recordHarnessControlEvent(CONTRACT_VERIFY_EVENT_KIND, "started", { contractId: options.contractId, contractVersion: options.contractVersion, manifestHash, testFileHash, files }, { ...eventBase, now: clock() });
+    const gate = await options.runGate();
+    const completedAt = clock().toISOString();
+    const completedRecord = recordHarnessControlEvent(CONTRACT_VERIFY_EVENT_KIND, gate.ok ? "completed" : "blocked", {
+        contractId: options.contractId,
+        contractVersion: options.contractVersion,
+        manifestHash,
+        testFileHash,
+        gate,
+    }, { ...eventBase, causationId: startedRecord.event?.eventId ?? null, now: clock() });
+    const ledgerPath = resolveHarnessControlEventLogPath({ cwd, logPath: options.logPath, runId: options.runId });
+    const ledgerErrors = [];
+    let ledgerChainOk = true;
+    if (ledgerPath) {
+        const verification = verifyHarnessControlLedger(ledgerPath);
+        ledgerChainOk = verification.ok;
+        ledgerErrors.push(...verification.errors);
+    }
+    for (const record of [startedRecord, completedRecord]) {
+        const error = ledgerErrorOf(record);
+        if (error)
+            ledgerErrors.push(error);
+    }
+    const ledgerVerified = ledgerChainOk && ledgerErrors.length === 0;
+    const result = {
+        schemaVersion: CONTRACT_RESULT_SCHEMA_VERSION,
+        contractId: options.contractId,
+        contractVersion: options.contractVersion,
+        status: gate.ok && ledgerVerified ? "passed" : "blocked",
+        manifestHash,
+        testFileHash,
+        files,
+        gate,
+        ledger: { path: ledgerPath ?? "", verified: ledgerVerified, errors: ledgerErrors },
+        startedAt,
+        completedAt,
+    };
+    if (options.resultPath) {
+        writeJsonAtomic(resolve(cwd, options.resultPath), result);
+    }
+    return result;
+}
+//# sourceMappingURL=contract-verification.js.map

package/dist/core/contract-verification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-verification.js","sourceRoot":"","sources":["../../src/core/contract-verification.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `cli.contract.verify` — durable, tamper-evident verification of a CLI contract.\n *\n * Builds on the harness-control hash-chained ledger to record a contract\n * verification as two correlated events (started -> completed/blocked), each\n * carrying the SHA-256 of the contract's manifest and test files. After\n * recording, the whole ledger is re-verified; a contract is only `passed` when\n * both the gate succeeds AND the hash-chain ledger verifies. This lets a release\n * gate detect after-the-fact tampering of either the contract artifacts or the\n * audit ledger itself.\n *\n * Dependency-free: uses node:crypto only (no fast-check/xterm/etc.).\n */\n\nimport { createHash, randomUUID } from \"node:crypto\";\nimport { mkdirSync, readFileSync, renameSync, writeFileSync } from \"node:fs\";\nimport { dirname, resolve } from \"node:path\";\nimport {\n\ttype HarnessControlEventOptions,\n\ttype HarnessControlEventWriteResult,\n\trecordHarnessControlEvent,\n\tresolveHarnessControlEventLogPath,\n\tverifyHarnessControlLedger,\n} from \"./harness-control-events.ts\";\n\nexport const CONTRACT_VERIFY_EVENT_KIND = \"cli.contract.verify\";\nexport const CONTRACT_RESULT_SCHEMA_VERSION = \"omk.cli-contract.result.v1\";\n\nexport interface ContractFileRef {\n\treadonly id: string;\n\treadonly path: string;\n}\n\nexport interface ContractFileHash {\n\treadonly id: string;\n\treadonly path: string;\n\t/** `sha256:<hex>` of the file contents. */\n\treadonly sha256: string;\n}\n\nexport type ContractVerificationStatus = \"passed\" | \"blocked\";\n\nexport interface ContractGateResult {\n\treadonly ok: boolean;\n\treadonly details?: string;\n}\n\nexport interface ContractLedgerSummary {\n\treadonly path: string;\n\treadonly verified: boolean;\n\treadonly errors: readonly string[];\n}\n\nexport interface ContractResult {\n\treadonly schemaVersion: typeof CONTRACT_RESULT_SCHEMA_VERSION;\n\treadonly contractId: string;\n\treadonly contractVersion: string;\n\treadonly status: ContractVerificationStatus;\n\treadonly manifestHash: string;\n\treadonly testFileHash: string;\n\treadonly files: readonly ContractFileHash[];\n\treadonly gate: ContractGateResult;\n\treadonly ledger: ContractLedgerSummary;\n\treadonly startedAt: string;\n\treadonly completedAt: string;\n}\n\nexport interface VerifyCliContractOptions {\n\treadonly contractId: string;\n\treadonly contractVersion: string;\n\treadonly manifestPath: string;\n\treadonly testPath: string;\n\treadonly extraFiles?: readonly ContractFileRef[];\n\t/** Runs the actual contract gate (e.g. the vitest contract file). */\n\treadonly runGate: () => ContractGateResult | Promise<ContractGateResult>;\n\treadonly cwd?: string;\n\treadonly logPath?: string;\n\treadonly runId?: string;\n\t/** When set, a JSON contract-result is written here (atomically). */\n\treadonly resultPath?: string;\n\treadonly now?: () => Date;\n}\n\nfunction hashFile(path: string): string {\n\treturn `sha256:${createHash(\"sha256\").update(readFileSync(path)).digest(\"hex\")}`;\n}\n\nfunction writeJsonAtomic(path: string, value: unknown): void {\n\tmkdirSync(dirname(path), { recursive: true });\n\tconst tmp = `${path}.tmp-${process.pid}-${randomUUID()}`;\n\twriteFileSync(tmp, `${JSON.stringify(value, null, 2)}\\n`, { encoding: \"utf-8\", mode: 0o600 });\n\trenameSync(tmp, path);\n}\n\nfunction ledgerErrorOf(record: HarnessControlEventWriteResult): string | undefined {\n\tif (record.ok) return undefined;\n\treturn record.error ? `event not recorded: ${record.error}` : \"event not recorded\";\n}\n\n/**\n * Verify a CLI contract and append a tamper-evident audit trail.\n *\n * Algorithm:\n *  1. SHA-256 the manifest, test, and any extra contract files.\n *  2. Record a `started` ledger event (manifest/test hashes + artifact manifest).\n *  3. Run the contract gate.\n *  4. Record a `completed` (gate ok) or `blocked` (gate failed) ledger event.\n *  5. Re-verify the whole hash-chain ledger.\n *  6. Status is `passed` only when the gate passed AND the ledger verifies;\n *     otherwise `blocked`.\n *  7. Optionally write a canonical contract-result.json.\n */\nexport async function verifyCliContract(options: VerifyCliContractOptions): Promise<ContractResult> {\n\tconst clock = options.now ?? (() => new Date());\n\tconst cwd = options.cwd ?? process.cwd();\n\tconst operationId = randomUUID();\n\tconst startedAt = clock().toISOString();\n\n\tconst files: ContractFileHash[] = [\n\t\t{ id: \"manifest\", path: options.manifestPath, sha256: hashFile(options.manifestPath) },\n\t\t{ id: \"test\", path: options.testPath, sha256: hashFile(options.testPath) },\n\t\t...(options.extraFiles ?? []).map((file) => ({ id: file.id, path: file.path, sha256: hashFile(file.path) })),\n\t];\n\tconst manifestHash = files[0]?.sha256 ?? \"\";\n\tconst testFileHash = files[1]?.sha256 ?? \"\";\n\tconst artifactRefs = files.map((file) => file.path);\n\n\tconst eventBase: HarnessControlEventOptions = {\n\t\tcwd,\n\t\tlogPath: options.logPath,\n\t\trunId: options.runId,\n\t\toperationId,\n\t\tcorrelationId: operationId,\n\t\tartifactRefs,\n\t};\n\n\tconst startedRecord = recordHarnessControlEvent(\n\t\tCONTRACT_VERIFY_EVENT_KIND,\n\t\t\"started\",\n\t\t{ contractId: options.contractId, contractVersion: options.contractVersion, manifestHash, testFileHash, files },\n\t\t{ ...eventBase, now: clock() },\n\t);\n\n\tconst gate = await options.runGate();\n\tconst completedAt = clock().toISOString();\n\n\tconst completedRecord = recordHarnessControlEvent(\n\t\tCONTRACT_VERIFY_EVENT_KIND,\n\t\tgate.ok ? \"completed\" : \"blocked\",\n\t\t{\n\t\t\tcontractId: options.contractId,\n\t\t\tcontractVersion: options.contractVersion,\n\t\t\tmanifestHash,\n\t\t\ttestFileHash,\n\t\t\tgate,\n\t\t},\n\t\t{ ...eventBase, causationId: startedRecord.event?.eventId ?? null, now: clock() },\n\t);\n\n\tconst ledgerPath = resolveHarnessControlEventLogPath({ cwd, logPath: options.logPath, runId: options.runId });\n\tconst ledgerErrors: string[] = [];\n\tlet ledgerChainOk = true;\n\tif (ledgerPath) {\n\t\tconst verification = verifyHarnessControlLedger(ledgerPath);\n\t\tledgerChainOk = verification.ok;\n\t\tledgerErrors.push(...verification.errors);\n\t}\n\tfor (const record of [startedRecord, completedRecord]) {\n\t\tconst error = ledgerErrorOf(record);\n\t\tif (error) ledgerErrors.push(error);\n\t}\n\tconst ledgerVerified = ledgerChainOk && ledgerErrors.length === 0;\n\n\tconst result: ContractResult = {\n\t\tschemaVersion: CONTRACT_RESULT_SCHEMA_VERSION,\n\t\tcontractId: options.contractId,\n\t\tcontractVersion: options.contractVersion,\n\t\tstatus: gate.ok && ledgerVerified ? \"passed\" : \"blocked\",\n\t\tmanifestHash,\n\t\ttestFileHash,\n\t\tfiles,\n\t\tgate,\n\t\tledger: { path: ledgerPath ?? \"\", verified: ledgerVerified, errors: ledgerErrors },\n\t\tstartedAt,\n\t\tcompletedAt,\n\t};\n\n\tif (options.resultPath) {\n\t\twriteJsonAtomic(resolve(cwd, options.resultPath), result);\n\t}\n\n\treturn result;\n}\n"]}

package/dist/core/exact-cache-policy.d.ts

@@ -0,0 +1,100 @@
+export declare const EXACT_CACHE_KEY_VERSION = "v1";
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | readonly JsonValue[] | JsonObject;
+export interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+export interface ExactResponseCacheKeyInput {
+    readonly provider: string;
+    readonly model: string;
+    readonly modelRevision: string;
+    readonly messages: JsonValue;
+    readonly toolSchema: JsonValue;
+    readonly temperature: number | null;
+    readonly seed: string | number | null;
+    readonly reasoningEffort: string | null;
+    readonly promptPolicyVersion: string;
+    readonly tenantId: string | null;
+    readonly userId: string | null;
+    readonly repoHead: string;
+    readonly worktreeHash: string;
+    readonly environmentHash: string;
+}
+export interface ExactResponseCacheKeyMaterial extends JsonObject {
+    readonly kind: "exact-response";
+    readonly version: typeof EXACT_CACHE_KEY_VERSION;
+    readonly provider: string;
+    readonly model: string;
+    readonly modelRevision: string;
+    readonly messagesHash: string;
+    readonly toolSchemaHash: string;
+    readonly temperature: number | null;
+    readonly seed: string | number | null;
+    readonly reasoningEffort: string | null;
+    readonly promptPolicyVersion: string;
+    readonly tenantId: string | null;
+    readonly userId: string | null;
+    readonly repoHead: string;
+    readonly worktreeHash: string;
+    readonly environmentHash: string;
+}
+export interface ExactResponseCacheKey {
+    readonly kind: "exact-response";
+    readonly version: typeof EXACT_CACHE_KEY_VERSION;
+    readonly key: string;
+    readonly hash: string;
+    readonly messagesHash: string;
+    readonly toolSchemaHash: string;
+    readonly material: ExactResponseCacheKeyMaterial;
+}
+export interface ToolResultCacheKeyInput {
+    readonly toolName: string;
+    readonly args: JsonValue;
+    readonly repoHead: string;
+    readonly worktreeHash: string;
+    readonly toolVersion: string;
+    readonly environmentHash: string;
+}
+export interface ToolResultCacheKeyMaterial extends JsonObject {
+    readonly kind: "tool-result";
+    readonly version: typeof EXACT_CACHE_KEY_VERSION;
+    readonly toolName: string;
+    readonly canonicalArgs: string;
+    readonly repoHead: string;
+    readonly worktreeHash: string;
+    readonly toolVersion: string;
+    readonly environmentHash: string;
+}
+export interface ToolResultCacheKey {
+    readonly kind: "tool-result";
+    readonly version: typeof EXACT_CACHE_KEY_VERSION;
+    readonly key: string;
+    readonly hash: string;
+    readonly canonicalArgs: string;
+    readonly argsHash: string;
+    readonly material: ToolResultCacheKeyMaterial;
+}
+export type ToolResultCacheStatus = "success" | "error";
+export interface ToolResultCachePolicyCandidate {
+    readonly toolName: string;
+    readonly status: ToolResultCacheStatus;
+    readonly mutates?: boolean;
+    readonly secretMarked?: boolean;
+    readonly bashPure?: boolean;
+}
+export type ToolResultCachePolicyReason = "eligible" | "tool.mutating" | "result.error" | "result.secret" | "bash.impure";
+export interface ToolResultCachePolicyDecision {
+    readonly eligible: boolean;
+    readonly reason: ToolResultCachePolicyReason;
+    readonly detail?: string;
+}
+export declare const MUTATING_TOOL_NAME_TERMS: readonly ["write", "edit", "patch", "delete", "remove", "move", "rename", "commit", "merge", "rebase", "checkout", "push", "deploy", "publish", "install", "execute", "exec", "run"];
+export declare function canonicalizeJson(value: JsonValue): string;
+export declare function hashCanonicalJson(value: JsonValue): string;
+export declare function createExactResponseCacheKey(input: ExactResponseCacheKeyInput): ExactResponseCacheKey;
+export declare function createToolResultCacheKey(input: ToolResultCacheKeyInput): ToolResultCacheKey;
+export declare function classifyToolResultCacheEligibility(candidate: ToolResultCachePolicyCandidate): ToolResultCachePolicyDecision;
+export declare function canCacheToolResult(candidate: ToolResultCachePolicyCandidate): boolean;
+export declare function isKnownMutatingToolName(toolName: string): boolean;
+export declare function isBashToolName(toolName: string): boolean;
+//# sourceMappingURL=exact-cache-policy.d.ts.map

package/dist/core/exact-cache-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exact-cache-policy.d.ts","sourceRoot":"","sources":["../../src/core/exact-cache-policy.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\n\nexport const EXACT_CACHE_KEY_VERSION = \"v1\";\n\nexport type JsonPrimitive = string | number | boolean | null;\nexport type JsonValue = JsonPrimitive | readonly JsonValue[] | JsonObject;\n\nexport interface JsonObject {\n\treadonly [key: string]: JsonValue;\n}\n\nexport interface ExactResponseCacheKeyInput {\n\treadonly provider: string;\n\treadonly model: string;\n\treadonly modelRevision: string;\n\treadonly messages: JsonValue;\n\treadonly toolSchema: JsonValue;\n\treadonly temperature: number | null;\n\treadonly seed: string | number | null;\n\treadonly reasoningEffort: string | null;\n\treadonly promptPolicyVersion: string;\n\treadonly tenantId: string | null;\n\treadonly userId: string | null;\n\treadonly repoHead: string;\n\treadonly worktreeHash: string;\n\treadonly environmentHash: string;\n}\n\nexport interface ExactResponseCacheKeyMaterial extends JsonObject {\n\treadonly kind: \"exact-response\";\n\treadonly version: typeof EXACT_CACHE_KEY_VERSION;\n\treadonly provider: string;\n\treadonly model: string;\n\treadonly modelRevision: string;\n\treadonly messagesHash: string;\n\treadonly toolSchemaHash: string;\n\treadonly temperature: number | null;\n\treadonly seed: string | number | null;\n\treadonly reasoningEffort: string | null;\n\treadonly promptPolicyVersion: string;\n\treadonly tenantId: string | null;\n\treadonly userId: string | null;\n\treadonly repoHead: string;\n\treadonly worktreeHash: string;\n\treadonly environmentHash: string;\n}\n\nexport interface ExactResponseCacheKey {\n\treadonly kind: \"exact-response\";\n\treadonly version: typeof EXACT_CACHE_KEY_VERSION;\n\treadonly key: string;\n\treadonly hash: string;\n\treadonly messagesHash: string;\n\treadonly toolSchemaHash: string;\n\treadonly material: ExactResponseCacheKeyMaterial;\n}\n\nexport interface ToolResultCacheKeyInput {\n\treadonly toolName: string;\n\treadonly args: JsonValue;\n\treadonly repoHead: string;\n\treadonly worktreeHash: string;\n\treadonly toolVersion: string;\n\treadonly environmentHash: string;\n}\n\nexport interface ToolResultCacheKeyMaterial extends JsonObject {\n\treadonly kind: \"tool-result\";\n\treadonly version: typeof EXACT_CACHE_KEY_VERSION;\n\treadonly toolName: string;\n\treadonly canonicalArgs: string;\n\treadonly repoHead: string;\n\treadonly worktreeHash: string;\n\treadonly toolVersion: string;\n\treadonly environmentHash: string;\n}\n\nexport interface ToolResultCacheKey {\n\treadonly kind: \"tool-result\";\n\treadonly version: typeof EXACT_CACHE_KEY_VERSION;\n\treadonly key: string;\n\treadonly hash: string;\n\treadonly canonicalArgs: string;\n\treadonly argsHash: string;\n\treadonly material: ToolResultCacheKeyMaterial;\n}\n\nexport type ToolResultCacheStatus = \"success\" | \"error\";\n\nexport interface ToolResultCachePolicyCandidate {\n\treadonly toolName: string;\n\treadonly status: ToolResultCacheStatus;\n\treadonly mutates?: boolean;\n\treadonly secretMarked?: boolean;\n\treadonly bashPure?: boolean;\n}\n\nexport type ToolResultCachePolicyReason =\n\t| \"eligible\"\n\t| \"tool.mutating\"\n\t| \"result.error\"\n\t| \"result.secret\"\n\t| \"bash.impure\";\n\nexport interface ToolResultCachePolicyDecision {\n\treadonly eligible: boolean;\n\treadonly reason: ToolResultCachePolicyReason;\n\treadonly detail?: string;\n}\n\nexport const MUTATING_TOOL_NAME_TERMS = [\n\t\"write\",\n\t\"edit\",\n\t\"patch\",\n\t\"delete\",\n\t\"remove\",\n\t\"move\",\n\t\"rename\",\n\t\"commit\",\n\t\"merge\",\n\t\"rebase\",\n\t\"checkout\",\n\t\"push\",\n\t\"deploy\",\n\t\"publish\",\n\t\"install\",\n\t\"execute\",\n\t\"exec\",\n\t\"run\",\n] as const;\n\nexport function canonicalizeJson(value: JsonValue): string {\n\tif (value === null) {\n\t\treturn \"null\";\n\t}\n\n\tswitch (typeof value) {\n\t\tcase \"string\":\n\t\tcase \"boolean\":\n\t\t\treturn stringifyCanonicalPrimitive(value);\n\t\tcase \"number\":\n\t\t\tif (!Number.isFinite(value)) {\n\t\t\t\tthrow new TypeError(\"Canonical JSON only supports finite numbers\");\n\t\t\t}\n\t\t\treturn stringifyCanonicalPrimitive(value);\n\t\tcase \"object\":\n\t\t\tif (Array.isArray(value)) {\n\t\t\t\treturn `[${value.map((item) => canonicalizeJson(item)).join(\",\")}]`;\n\t\t\t}\n\t\t\tassertPlainJsonObject(value);\n\t\t\treturn canonicalizeObject(value);\n\t\tdefault:\n\t\t\tthrow new TypeError(`Unsupported JSON value type: ${typeof value}`);\n\t}\n}\n\nexport function hashCanonicalJson(value: JsonValue): string {\n\treturn sha256Hex(canonicalizeJson(value));\n}\n\nexport function createExactResponseCacheKey(input: ExactResponseCacheKeyInput): ExactResponseCacheKey {\n\tconst messagesHash = hashCanonicalJson(input.messages);\n\tconst toolSchemaHash = hashCanonicalJson(input.toolSchema);\n\tconst material: ExactResponseCacheKeyMaterial = {\n\t\tkind: \"exact-response\",\n\t\tversion: EXACT_CACHE_KEY_VERSION,\n\t\tprovider: requireNonEmptyString(\"provider\", input.provider),\n\t\tmodel: requireNonEmptyString(\"model\", input.model),\n\t\tmodelRevision: requireNonEmptyString(\"modelRevision\", input.modelRevision),\n\t\tmessagesHash,\n\t\ttoolSchemaHash,\n\t\ttemperature: input.temperature,\n\t\tseed: input.seed,\n\t\treasoningEffort: normalizeNullableString(\"reasoningEffort\", input.reasoningEffort),\n\t\tpromptPolicyVersion: requireNonEmptyString(\"promptPolicyVersion\", input.promptPolicyVersion),\n\t\ttenantId: normalizeNullableString(\"tenantId\", input.tenantId),\n\t\tuserId: normalizeNullableString(\"userId\", input.userId),\n\t\trepoHead: requireNonEmptyString(\"repoHead\", input.repoHead),\n\t\tworktreeHash: requireNonEmptyString(\"worktreeHash\", input.worktreeHash),\n\t\tenvironmentHash: requireNonEmptyString(\"environmentHash\", input.environmentHash),\n\t};\n\tconst hash = hashCanonicalJson(material);\n\treturn {\n\t\tkind: \"exact-response\",\n\t\tversion: EXACT_CACHE_KEY_VERSION,\n\t\tkey: `exact-response:${EXACT_CACHE_KEY_VERSION}:${hash}`,\n\t\thash,\n\t\tmessagesHash,\n\t\ttoolSchemaHash,\n\t\tmaterial,\n\t};\n}\n\nexport function createToolResultCacheKey(input: ToolResultCacheKeyInput): ToolResultCacheKey {\n\tconst canonicalArgs = canonicalizeJson(input.args);\n\tconst argsHash = sha256Hex(canonicalArgs);\n\tconst material: ToolResultCacheKeyMaterial = {\n\t\tkind: \"tool-result\",\n\t\tversion: EXACT_CACHE_KEY_VERSION,\n\t\ttoolName: requireNonEmptyString(\"toolName\", input.toolName),\n\t\tcanonicalArgs,\n\t\trepoHead: requireNonEmptyString(\"repoHead\", input.repoHead),\n\t\tworktreeHash: requireNonEmptyString(\"worktreeHash\", input.worktreeHash),\n\t\ttoolVersion: requireNonEmptyString(\"toolVersion\", input.toolVersion),\n\t\tenvironmentHash: requireNonEmptyString(\"environmentHash\", input.environmentHash),\n\t};\n\tconst hash = hashCanonicalJson(material);\n\treturn {\n\t\tkind: \"tool-result\",\n\t\tversion: EXACT_CACHE_KEY_VERSION,\n\t\tkey: `tool-result:${EXACT_CACHE_KEY_VERSION}:${hash}`,\n\t\thash,\n\t\tcanonicalArgs,\n\t\targsHash,\n\t\tmaterial,\n\t};\n}\n\nexport function classifyToolResultCacheEligibility(\n\tcandidate: ToolResultCachePolicyCandidate,\n): ToolResultCachePolicyDecision {\n\tconst toolName = requireNonEmptyString(\"toolName\", candidate.toolName);\n\tif (candidate.mutates === true || isKnownMutatingToolName(toolName)) {\n\t\treturn denyToolResultCache(\"tool.mutating\", toolName);\n\t}\n\n\tif (candidate.status !== \"success\") {\n\t\treturn denyToolResultCache(\"result.error\", candidate.status);\n\t}\n\n\tif (candidate.secretMarked === true) {\n\t\treturn denyToolResultCache(\"result.secret\", toolName);\n\t}\n\n\tif (isBashToolName(toolName) && candidate.bashPure !== true) {\n\t\treturn denyToolResultCache(\"bash.impure\", toolName);\n\t}\n\n\treturn { eligible: true, reason: \"eligible\" };\n}\n\nexport function canCacheToolResult(candidate: ToolResultCachePolicyCandidate): boolean {\n\treturn classifyToolResultCacheEligibility(candidate).eligible;\n}\n\nexport function isKnownMutatingToolName(toolName: string): boolean {\n\tconst terms = splitToolName(toolName);\n\treturn MUTATING_TOOL_NAME_TERMS.some((term) => terms.includes(term));\n}\n\nexport function isBashToolName(toolName: string): boolean {\n\treturn splitToolName(toolName).includes(\"bash\");\n}\n\nfunction canonicalizeObject(value: JsonObject): string {\n\treturn `{${Object.keys(value)\n\t\t.sort()\n\t\t.map((key) => `${stringifyCanonicalPrimitive(key)}:${canonicalizeJson(value[key])}`)\n\t\t.join(\",\")}}`;\n}\n\nfunction stringifyCanonicalPrimitive(value: JsonPrimitive): string {\n\tconst encoded = JSON.stringify(value);\n\tif (encoded === undefined) {\n\t\tthrow new TypeError(\"Unsupported JSON primitive\");\n\t}\n\treturn encoded;\n}\n\nfunction assertPlainJsonObject(value: object): asserts value is JsonObject {\n\tconst prototype = Object.getPrototypeOf(value);\n\tif (prototype !== Object.prototype && prototype !== null) {\n\t\tthrow new TypeError(\"Canonical JSON only supports plain objects and arrays\");\n\t}\n}\n\nfunction sha256Hex(value: string): string {\n\treturn createHash(\"sha256\").update(value, \"utf8\").digest(\"hex\");\n}\n\nfunction requireNonEmptyString(name: string, value: string): string {\n\tif (value.trim().length === 0) {\n\t\tthrow new TypeError(`${name} must be a non-empty string`);\n\t}\n\treturn value;\n}\n\nfunction normalizeNullableString(name: string, value: string | null): string | null {\n\tif (value === null) {\n\t\treturn null;\n\t}\n\treturn requireNonEmptyString(name, value);\n}\n\nfunction splitToolName(toolName: string): readonly string[] {\n\treturn toolName\n\t\t.trim()\n\t\t.toLowerCase()\n\t\t.split(/[^a-z0-9]+/g)\n\t\t.filter((term) => term.length > 0);\n}\n\nfunction denyToolResultCache(\n\treason: Exclude<ToolResultCachePolicyReason, \"eligible\">,\n\tdetail: string,\n): ToolResultCachePolicyDecision {\n\treturn { eligible: false, reason, detail };\n}\n"]}

package/dist/core/exact-cache-policy.js

@@ -0,0 +1,175 @@
+import { createHash } from "node:crypto";
+export const EXACT_CACHE_KEY_VERSION = "v1";
+export const MUTATING_TOOL_NAME_TERMS = [
+    "write",
+    "edit",
+    "patch",
+    "delete",
+    "remove",
+    "move",
+    "rename",
+    "commit",
+    "merge",
+    "rebase",
+    "checkout",
+    "push",
+    "deploy",
+    "publish",
+    "install",
+    "execute",
+    "exec",
+    "run",
+];
+export function canonicalizeJson(value) {
+    if (value === null) {
+        return "null";
+    }
+    switch (typeof value) {
+        case "string":
+        case "boolean":
+            return stringifyCanonicalPrimitive(value);
+        case "number":
+            if (!Number.isFinite(value)) {
+                throw new TypeError("Canonical JSON only supports finite numbers");
+            }
+            return stringifyCanonicalPrimitive(value);
+        case "object":
+            if (Array.isArray(value)) {
+                return `[${value.map((item) => canonicalizeJson(item)).join(",")}]`;
+            }
+            assertPlainJsonObject(value);
+            return canonicalizeObject(value);
+        default:
+            throw new TypeError(`Unsupported JSON value type: ${typeof value}`);
+    }
+}
+export function hashCanonicalJson(value) {
+    return sha256Hex(canonicalizeJson(value));
+}
+export function createExactResponseCacheKey(input) {
+    const messagesHash = hashCanonicalJson(input.messages);
+    const toolSchemaHash = hashCanonicalJson(input.toolSchema);
+    const material = {
+        kind: "exact-response",
+        version: EXACT_CACHE_KEY_VERSION,
+        provider: requireNonEmptyString("provider", input.provider),
+        model: requireNonEmptyString("model", input.model),
+        modelRevision: requireNonEmptyString("modelRevision", input.modelRevision),
+        messagesHash,
+        toolSchemaHash,
+        temperature: input.temperature,
+        seed: input.seed,
+        reasoningEffort: normalizeNullableString("reasoningEffort", input.reasoningEffort),
+        promptPolicyVersion: requireNonEmptyString("promptPolicyVersion", input.promptPolicyVersion),
+        tenantId: normalizeNullableString("tenantId", input.tenantId),
+        userId: normalizeNullableString("userId", input.userId),
+        repoHead: requireNonEmptyString("repoHead", input.repoHead),
+        worktreeHash: requireNonEmptyString("worktreeHash", input.worktreeHash),
+        environmentHash: requireNonEmptyString("environmentHash", input.environmentHash),
+    };
+    const hash = hashCanonicalJson(material);
+    return {
+        kind: "exact-response",
+        version: EXACT_CACHE_KEY_VERSION,
+        key: `exact-response:${EXACT_CACHE_KEY_VERSION}:${hash}`,
+        hash,
+        messagesHash,
+        toolSchemaHash,
+        material,
+    };
+}
+export function createToolResultCacheKey(input) {
+    const canonicalArgs = canonicalizeJson(input.args);
+    const argsHash = sha256Hex(canonicalArgs);
+    const material = {
+        kind: "tool-result",
+        version: EXACT_CACHE_KEY_VERSION,
+        toolName: requireNonEmptyString("toolName", input.toolName),
+        canonicalArgs,
+        repoHead: requireNonEmptyString("repoHead", input.repoHead),
+        worktreeHash: requireNonEmptyString("worktreeHash", input.worktreeHash),
+        toolVersion: requireNonEmptyString("toolVersion", input.toolVersion),
+        environmentHash: requireNonEmptyString("environmentHash", input.environmentHash),
+    };
+    const hash = hashCanonicalJson(material);
+    return {
+        kind: "tool-result",
+        version: EXACT_CACHE_KEY_VERSION,
+        key: `tool-result:${EXACT_CACHE_KEY_VERSION}:${hash}`,
+        hash,
+        canonicalArgs,
+        argsHash,
+        material,
+    };
+}
+export function classifyToolResultCacheEligibility(candidate) {
+    const toolName = requireNonEmptyString("toolName", candidate.toolName);
+    if (candidate.mutates === true || isKnownMutatingToolName(toolName)) {
+        return denyToolResultCache("tool.mutating", toolName);
+    }
+    if (candidate.status !== "success") {
+        return denyToolResultCache("result.error", candidate.status);
+    }
+    if (candidate.secretMarked === true) {
+        return denyToolResultCache("result.secret", toolName);
+    }
+    if (isBashToolName(toolName) && candidate.bashPure !== true) {
+        return denyToolResultCache("bash.impure", toolName);
+    }
+    return { eligible: true, reason: "eligible" };
+}
+export function canCacheToolResult(candidate) {
+    return classifyToolResultCacheEligibility(candidate).eligible;
+}
+export function isKnownMutatingToolName(toolName) {
+    const terms = splitToolName(toolName);
+    return MUTATING_TOOL_NAME_TERMS.some((term) => terms.includes(term));
+}
+export function isBashToolName(toolName) {
+    return splitToolName(toolName).includes("bash");
+}
+function canonicalizeObject(value) {
+    return `{${Object.keys(value)
+        .sort()
+        .map((key) => `${stringifyCanonicalPrimitive(key)}:${canonicalizeJson(value[key])}`)
+        .join(",")}}`;
+}
+function stringifyCanonicalPrimitive(value) {
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined) {
+        throw new TypeError("Unsupported JSON primitive");
+    }
+    return encoded;
+}
+function assertPlainJsonObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new TypeError("Canonical JSON only supports plain objects and arrays");
+    }
+}
+function sha256Hex(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function requireNonEmptyString(name, value) {
+    if (value.trim().length === 0) {
+        throw new TypeError(`${name} must be a non-empty string`);
+    }
+    return value;
+}
+function normalizeNullableString(name, value) {
+    if (value === null) {
+        return null;
+    }
+    return requireNonEmptyString(name, value);
+}
+function splitToolName(toolName) {
+    return toolName
+        .trim()
+        .toLowerCase()
+        .split(/[^a-z0-9]+/g)
+        .filter((term) => term.length > 0);
+}
+function denyToolResultCache(reason, detail) {
+    return { eligible: false, reason, detail };
+}
+//# sourceMappingURL=exact-cache-policy.js.map

package/dist/core/exact-cache-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exact-cache-policy.js","sourceRoot":"","sources":["../../src/core/exact-cache-policy.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\n\nexport const EXACT_CACHE_KEY_VERSION = \"v1\";\n\nexport type JsonPrimitive = string | number | boolean | null;\nexport type JsonValue = JsonPrimitive | readonly JsonValue[] | JsonObject;\n\nexport interface JsonObject {\n\treadonly [key: string]: JsonValue;\n}\n\nexport interface ExactResponseCacheKeyInput {\n\treadonly provider: string;\n\treadonly model: string;\n\treadonly modelRevision: string;\n\treadonly messages: JsonValue;\n\treadonly toolSchema: JsonValue;\n\treadonly temperature: number | null;\n\treadonly seed: string | number | null;\n\treadonly reasoningEffort: string | null;\n\treadonly promptPolicyVersion: string;\n\treadonly tenantId: string | null;\n\treadonly userId: string | null;\n\treadonly repoHead: string;\n\treadonly worktreeHash: string;\n\treadonly environmentHash: string;\n}\n\nexport interface ExactResponseCacheKeyMaterial extends JsonObject {\n\treadonly kind: \"exact-response\";\n\treadonly version: typeof EXACT_CACHE_KEY_VERSION;\n\treadonly provider: string;\n\treadonly model: string;\n\treadonly modelRevision: string;\n\treadonly messagesHash: string;\n\treadonly toolSchemaHash: string;\n\treadonly temperature: number | null;\n\treadonly seed: string | number | null;\n\treadonly reasoningEffort: string | null;\n\treadonly promptPolicyVersion: string;\n\treadonly tenantId: string | null;\n\treadonly userId: string | null;\n\treadonly repoHead: string;\n\treadonly worktreeHash: string;\n\treadonly environmentHash: string;\n}\n\nexport interface ExactResponseCacheKey {\n\treadonly kind: \"exact-response\";\n\treadonly version: typeof EXACT_CACHE_KEY_VERSION;\n\treadonly key: string;\n\treadonly hash: string;\n\treadonly messagesHash: string;\n\treadonly toolSchemaHash: string;\n\treadonly material: ExactResponseCacheKeyMaterial;\n}\n\nexport interface ToolResultCacheKeyInput {\n\treadonly toolName: string;\n\treadonly args: JsonValue;\n\treadonly repoHead: string;\n\treadonly worktreeHash: string;\n\treadonly toolVersion: string;\n\treadonly environmentHash: string;\n}\n\nexport interface ToolResultCacheKeyMaterial extends JsonObject {\n\treadonly kind: \"tool-result\";\n\treadonly version: typeof EXACT_CACHE_KEY_VERSION;\n\treadonly toolName: string;\n\treadonly canonicalArgs: string;\n\treadonly repoHead: string;\n\treadonly worktreeHash: string;\n\treadonly toolVersion: string;\n\treadonly environmentHash: string;\n}\n\nexport interface ToolResultCacheKey {\n\treadonly kind: \"tool-result\";\n\treadonly version: typeof EXACT_CACHE_KEY_VERSION;\n\treadonly key: string;\n\treadonly hash: string;\n\treadonly canonicalArgs: string;\n\treadonly argsHash: string;\n\treadonly material: ToolResultCacheKeyMaterial;\n}\n\nexport type ToolResultCacheStatus = \"success\" | \"error\";\n\nexport interface ToolResultCachePolicyCandidate {\n\treadonly toolName: string;\n\treadonly status: ToolResultCacheStatus;\n\treadonly mutates?: boolean;\n\treadonly secretMarked?: boolean;\n\treadonly bashPure?: boolean;\n}\n\nexport type ToolResultCachePolicyReason =\n\t| \"eligible\"\n\t| \"tool.mutating\"\n\t| \"result.error\"\n\t| \"result.secret\"\n\t| \"bash.impure\";\n\nexport interface ToolResultCachePolicyDecision {\n\treadonly eligible: boolean;\n\treadonly reason: ToolResultCachePolicyReason;\n\treadonly detail?: string;\n}\n\nexport const MUTATING_TOOL_NAME_TERMS = [\n\t\"write\",\n\t\"edit\",\n\t\"patch\",\n\t\"delete\",\n\t\"remove\",\n\t\"move\",\n\t\"rename\",\n\t\"commit\",\n\t\"merge\",\n\t\"rebase\",\n\t\"checkout\",\n\t\"push\",\n\t\"deploy\",\n\t\"publish\",\n\t\"install\",\n\t\"execute\",\n\t\"exec\",\n\t\"run\",\n] as const;\n\nexport function canonicalizeJson(value: JsonValue): string {\n\tif (value === null) {\n\t\treturn \"null\";\n\t}\n\n\tswitch (typeof value) {\n\t\tcase \"string\":\n\t\tcase \"boolean\":\n\t\t\treturn stringifyCanonicalPrimitive(value);\n\t\tcase \"number\":\n\t\t\tif (!Number.isFinite(value)) {\n\t\t\t\tthrow new TypeError(\"Canonical JSON only supports finite numbers\");\n\t\t\t}\n\t\t\treturn stringifyCanonicalPrimitive(value);\n\t\tcase \"object\":\n\t\t\tif (Array.isArray(value)) {\n\t\t\t\treturn `[${value.map((item) => canonicalizeJson(item)).join(\",\")}]`;\n\t\t\t}\n\t\t\tassertPlainJsonObject(value);\n\t\t\treturn canonicalizeObject(value);\n\t\tdefault:\n\t\t\tthrow new TypeError(`Unsupported JSON value type: ${typeof value}`);\n\t}\n}\n\nexport function hashCanonicalJson(value: JsonValue): string {\n\treturn sha256Hex(canonicalizeJson(value));\n}\n\nexport function createExactResponseCacheKey(input: ExactResponseCacheKeyInput): ExactResponseCacheKey {\n\tconst messagesHash = hashCanonicalJson(input.messages);\n\tconst toolSchemaHash = hashCanonicalJson(input.toolSchema);\n\tconst material: ExactResponseCacheKeyMaterial = {\n\t\tkind: \"exact-response\",\n\t\tversion: EXACT_CACHE_KEY_VERSION,\n\t\tprovider: requireNonEmptyString(\"provider\", input.provider),\n\t\tmodel: requireNonEmptyString(\"model\", input.model),\n\t\tmodelRevision: requireNonEmptyString(\"modelRevision\", input.modelRevision),\n\t\tmessagesHash,\n\t\ttoolSchemaHash,\n\t\ttemperature: input.temperature,\n\t\tseed: input.seed,\n\t\treasoningEffort: normalizeNullableString(\"reasoningEffort\", input.reasoningEffort),\n\t\tpromptPolicyVersion: requireNonEmptyString(\"promptPolicyVersion\", input.promptPolicyVersion),\n\t\ttenantId: normalizeNullableString(\"tenantId\", input.tenantId),\n\t\tuserId: normalizeNullableString(\"userId\", input.userId),\n\t\trepoHead: requireNonEmptyString(\"repoHead\", input.repoHead),\n\t\tworktreeHash: requireNonEmptyString(\"worktreeHash\", input.worktreeHash),\n\t\tenvironmentHash: requireNonEmptyString(\"environmentHash\", input.environmentHash),\n\t};\n\tconst hash = hashCanonicalJson(material);\n\treturn {\n\t\tkind: \"exact-response\",\n\t\tversion: EXACT_CACHE_KEY_VERSION,\n\t\tkey: `exact-response:${EXACT_CACHE_KEY_VERSION}:${hash}`,\n\t\thash,\n\t\tmessagesHash,\n\t\ttoolSchemaHash,\n\t\tmaterial,\n\t};\n}\n\nexport function createToolResultCacheKey(input: ToolResultCacheKeyInput): ToolResultCacheKey {\n\tconst canonicalArgs = canonicalizeJson(input.args);\n\tconst argsHash = sha256Hex(canonicalArgs);\n\tconst material: ToolResultCacheKeyMaterial = {\n\t\tkind: \"tool-result\",\n\t\tversion: EXACT_CACHE_KEY_VERSION,\n\t\ttoolName: requireNonEmptyString(\"toolName\", input.toolName),\n\t\tcanonicalArgs,\n\t\trepoHead: requireNonEmptyString(\"repoHead\", input.repoHead),\n\t\tworktreeHash: requireNonEmptyString(\"worktreeHash\", input.worktreeHash),\n\t\ttoolVersion: requireNonEmptyString(\"toolVersion\", input.toolVersion),\n\t\tenvironmentHash: requireNonEmptyString(\"environmentHash\", input.environmentHash),\n\t};\n\tconst hash = hashCanonicalJson(material);\n\treturn {\n\t\tkind: \"tool-result\",\n\t\tversion: EXACT_CACHE_KEY_VERSION,\n\t\tkey: `tool-result:${EXACT_CACHE_KEY_VERSION}:${hash}`,\n\t\thash,\n\t\tcanonicalArgs,\n\t\targsHash,\n\t\tmaterial,\n\t};\n}\n\nexport function classifyToolResultCacheEligibility(\n\tcandidate: ToolResultCachePolicyCandidate,\n): ToolResultCachePolicyDecision {\n\tconst toolName = requireNonEmptyString(\"toolName\", candidate.toolName);\n\tif (candidate.mutates === true || isKnownMutatingToolName(toolName)) {\n\t\treturn denyToolResultCache(\"tool.mutating\", toolName);\n\t}\n\n\tif (candidate.status !== \"success\") {\n\t\treturn denyToolResultCache(\"result.error\", candidate.status);\n\t}\n\n\tif (candidate.secretMarked === true) {\n\t\treturn denyToolResultCache(\"result.secret\", toolName);\n\t}\n\n\tif (isBashToolName(toolName) && candidate.bashPure !== true) {\n\t\treturn denyToolResultCache(\"bash.impure\", toolName);\n\t}\n\n\treturn { eligible: true, reason: \"eligible\" };\n}\n\nexport function canCacheToolResult(candidate: ToolResultCachePolicyCandidate): boolean {\n\treturn classifyToolResultCacheEligibility(candidate).eligible;\n}\n\nexport function isKnownMutatingToolName(toolName: string): boolean {\n\tconst terms = splitToolName(toolName);\n\treturn MUTATING_TOOL_NAME_TERMS.some((term) => terms.includes(term));\n}\n\nexport function isBashToolName(toolName: string): boolean {\n\treturn splitToolName(toolName).includes(\"bash\");\n}\n\nfunction canonicalizeObject(value: JsonObject): string {\n\treturn `{${Object.keys(value)\n\t\t.sort()\n\t\t.map((key) => `${stringifyCanonicalPrimitive(key)}:${canonicalizeJson(value[key])}`)\n\t\t.join(\",\")}}`;\n}\n\nfunction stringifyCanonicalPrimitive(value: JsonPrimitive): string {\n\tconst encoded = JSON.stringify(value);\n\tif (encoded === undefined) {\n\t\tthrow new TypeError(\"Unsupported JSON primitive\");\n\t}\n\treturn encoded;\n}\n\nfunction assertPlainJsonObject(value: object): asserts value is JsonObject {\n\tconst prototype = Object.getPrototypeOf(value);\n\tif (prototype !== Object.prototype && prototype !== null) {\n\t\tthrow new TypeError(\"Canonical JSON only supports plain objects and arrays\");\n\t}\n}\n\nfunction sha256Hex(value: string): string {\n\treturn createHash(\"sha256\").update(value, \"utf8\").digest(\"hex\");\n}\n\nfunction requireNonEmptyString(name: string, value: string): string {\n\tif (value.trim().length === 0) {\n\t\tthrow new TypeError(`${name} must be a non-empty string`);\n\t}\n\treturn value;\n}\n\nfunction normalizeNullableString(name: string, value: string | null): string | null {\n\tif (value === null) {\n\t\treturn null;\n\t}\n\treturn requireNonEmptyString(name, value);\n}\n\nfunction splitToolName(toolName: string): readonly string[] {\n\treturn toolName\n\t\t.trim()\n\t\t.toLowerCase()\n\t\t.split(/[^a-z0-9]+/g)\n\t\t.filter((term) => term.length > 0);\n}\n\nfunction denyToolResultCache(\n\treason: Exclude<ToolResultCachePolicyReason, \"eligible\">,\n\tdetail: string,\n): ToolResultCachePolicyDecision {\n\treturn { eligible: false, reason, detail };\n}\n"]}

package/dist/core/exec.d.ts

@@ -11,6 +11,8 @@ export interface ExecOptions {
     timeout?: number;
     /** Working directory */
     cwd?: string;
+    /** Environment variables for the spawned process. Defaults to the parent environment. */
+    env?: NodeJS.ProcessEnv;
 }
 /**
  * Result of executing a shell command.

package/dist/core/exec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/core/exec.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,wCAAwC;IACxC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,CAAC,CAyErB","sourcesContent":["/**\n * Shared command execution utilities for extensions and custom tools.\n */\n\nimport { spawn } from \"node:child_process\";\nimport { waitForChildProcess } from \"../utils/child-process.ts\";\n\n/**\n * Options for executing shell commands.\n */\nexport interface ExecOptions {\n\t/** AbortSignal to cancel the command */\n\tsignal?: AbortSignal;\n\t/** Timeout in milliseconds */\n\ttimeout?: number;\n\t/** Working directory */\n\tcwd?: string;\n}\n\n/**\n * Result of executing a shell command.\n */\nexport interface ExecResult {\n\tstdout: string;\n\tstderr: string;\n\tcode: number;\n\tkilled: boolean;\n}\n\n/**\n * Execute a shell command and return stdout/stderr/code.\n * Supports timeout and abort signal.\n */\nexport async function execCommand(\n\tcommand: string,\n\targs: string[],\n\tcwd: string,\n\toptions?: ExecOptions,\n): Promise<ExecResult> {\n\treturn new Promise((resolve) => {\n\t\tconst proc = spawn(command, args, {\n\t\t\tcwd,\n\t\t\tshell: false,\n\t\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t\t});\n\n\t\tlet stdout = \"\";\n\t\tlet stderr = \"\";\n\t\tlet killed = false;\n\t\tlet timeoutId: NodeJS.Timeout | undefined;\n\t\tlet forceKillTimeoutId: NodeJS.Timeout | undefined;\n\n\t\tconst killProcess = () => {\n\t\t\tif (!killed) {\n\t\t\t\tkilled = true;\n\t\t\t\tproc.kill(\"SIGTERM\");\n\t\t\t\t// Force kill after 5 seconds if SIGTERM doesn't work.\n\t\t\t\t// Note: proc.killed only means a signal was successfully SENT, so we\n\t\t\t\t// must check whether the process actually exited instead.\n\t\t\t\tforceKillTimeoutId = setTimeout(() => {\n\t\t\t\t\tif (proc.exitCode === null && proc.signalCode === null) {\n\t\t\t\t\t\tproc.kill(\"SIGKILL\");\n\t\t\t\t\t}\n\t\t\t\t}, 5000);\n\t\t\t\tforceKillTimeoutId.unref();\n\t\t\t}\n\t\t};\n\n\t\t// Handle abort signal\n\t\tif (options?.signal) {\n\t\t\tif (options.signal.aborted) {\n\t\t\t\tkillProcess();\n\t\t\t} else {\n\t\t\t\toptions.signal.addEventListener(\"abort\", killProcess, { once: true });\n\t\t\t}\n\t\t}\n\n\t\t// Handle timeout\n\t\tif (options?.timeout && options.timeout > 0) {\n\t\t\ttimeoutId = setTimeout(() => {\n\t\t\t\tkillProcess();\n\t\t\t}, options.timeout);\n\t\t}\n\n\t\tproc.stdout?.on(\"data\", (data) => {\n\t\t\tstdout += data.toString();\n\t\t});\n\n\t\tproc.stderr?.on(\"data\", (data) => {\n\t\t\tstderr += data.toString();\n\t\t});\n\n\t\tconst settle = (code: number) => {\n\t\t\tif (timeoutId) clearTimeout(timeoutId);\n\t\t\tif (forceKillTimeoutId) clearTimeout(forceKillTimeoutId);\n\t\t\tif (options?.signal) {\n\t\t\t\toptions.signal.removeEventListener(\"abort\", killProcess);\n\t\t\t}\n\t\t\tresolve({ stdout, stderr, code, killed });\n\t\t};\n\n\t\t// Wait for process termination without hanging on inherited stdio handles\n\t\t// held open by detached descendants.\n\t\twaitForChildProcess(proc)\n\t\t\t.then((code) => {\n\t\t\t\tsettle(code ?? 0);\n\t\t\t})\n\t\t\t.catch((_err) => {\n\t\t\t\tsettle(1);\n\t\t\t});\n\t});\n}\n"]}
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/core/exec.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,wCAAwC;IACxC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,CAAC,CA0ErB","sourcesContent":["/**\n * Shared command execution utilities for extensions and custom tools.\n */\n\nimport { spawn } from \"node:child_process\";\nimport { waitForChildProcess } from \"../utils/child-process.ts\";\n\n/**\n * Options for executing shell commands.\n */\nexport interface ExecOptions {\n\t/** AbortSignal to cancel the command */\n\tsignal?: AbortSignal;\n\t/** Timeout in milliseconds */\n\ttimeout?: number;\n\t/** Working directory */\n\tcwd?: string;\n\t/** Environment variables for the spawned process. Defaults to the parent environment. */\n\tenv?: NodeJS.ProcessEnv;\n}\n\n/**\n * Result of executing a shell command.\n */\nexport interface ExecResult {\n\tstdout: string;\n\tstderr: string;\n\tcode: number;\n\tkilled: boolean;\n}\n\n/**\n * Execute a shell command and return stdout/stderr/code.\n * Supports timeout and abort signal.\n */\nexport async function execCommand(\n\tcommand: string,\n\targs: string[],\n\tcwd: string,\n\toptions?: ExecOptions,\n): Promise<ExecResult> {\n\treturn new Promise((resolve) => {\n\t\tconst proc = spawn(command, args, {\n\t\t\tcwd,\n\t\t\tenv: options?.env ?? process.env,\n\t\t\tshell: false,\n\t\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t\t});\n\n\t\tlet stdout = \"\";\n\t\tlet stderr = \"\";\n\t\tlet killed = false;\n\t\tlet timeoutId: NodeJS.Timeout | undefined;\n\t\tlet forceKillTimeoutId: NodeJS.Timeout | undefined;\n\n\t\tconst killProcess = () => {\n\t\t\tif (!killed) {\n\t\t\t\tkilled = true;\n\t\t\t\tproc.kill(\"SIGTERM\");\n\t\t\t\t// Force kill after 5 seconds if SIGTERM doesn't work.\n\t\t\t\t// Note: proc.killed only means a signal was successfully SENT, so we\n\t\t\t\t// must check whether the process actually exited instead.\n\t\t\t\tforceKillTimeoutId = setTimeout(() => {\n\t\t\t\t\tif (proc.exitCode === null && proc.signalCode === null) {\n\t\t\t\t\t\tproc.kill(\"SIGKILL\");\n\t\t\t\t\t}\n\t\t\t\t}, 5000);\n\t\t\t\tforceKillTimeoutId.unref();\n\t\t\t}\n\t\t};\n\n\t\t// Handle abort signal\n\t\tif (options?.signal) {\n\t\t\tif (options.signal.aborted) {\n\t\t\t\tkillProcess();\n\t\t\t} else {\n\t\t\t\toptions.signal.addEventListener(\"abort\", killProcess, { once: true });\n\t\t\t}\n\t\t}\n\n\t\t// Handle timeout\n\t\tif (options?.timeout && options.timeout > 0) {\n\t\t\ttimeoutId = setTimeout(() => {\n\t\t\t\tkillProcess();\n\t\t\t}, options.timeout);\n\t\t}\n\n\t\tproc.stdout?.on(\"data\", (data) => {\n\t\t\tstdout += data.toString();\n\t\t});\n\n\t\tproc.stderr?.on(\"data\", (data) => {\n\t\t\tstderr += data.toString();\n\t\t});\n\n\t\tconst settle = (code: number) => {\n\t\t\tif (timeoutId) clearTimeout(timeoutId);\n\t\t\tif (forceKillTimeoutId) clearTimeout(forceKillTimeoutId);\n\t\t\tif (options?.signal) {\n\t\t\t\toptions.signal.removeEventListener(\"abort\", killProcess);\n\t\t\t}\n\t\t\tresolve({ stdout, stderr, code, killed });\n\t\t};\n\n\t\t// Wait for process termination without hanging on inherited stdio handles\n\t\t// held open by detached descendants.\n\t\twaitForChildProcess(proc)\n\t\t\t.then((code) => {\n\t\t\t\tsettle(code ?? 0);\n\t\t\t})\n\t\t\t.catch((_err) => {\n\t\t\t\tsettle(1);\n\t\t\t});\n\t});\n}\n"]}

package/dist/core/exec.js

@@ -11,6 +11,7 @@ export async function execCommand(command, args, cwd, options) {
     return new Promise((resolve) => {
         const proc = spawn(command, args, {
             cwd,
+            env: options?.env ?? process.env,
             shell: false,
             stdio: ["ignore", "pipe", "pipe"],
         });