@open-agent-toolkit/cli 0.2.76 → 0.2.79

package/assets/skills/recon/scripts/reconcile-ledger.mjs

@@ -1,5 +1,24 @@
-import { canonicalJson } from './lib/canonical-json.mjs';
+#!/usr/bin/env node
+
+import { randomUUID } from 'node:crypto';
+import {
+  link as linkFile,
+  open,
+  readFile,
+  realpath,
+  unlink,
+} from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+import { canonicalJson, hashFile } from './lib/canonical-json.mjs';
+import { isDirectExecution } from './lib/cli-entry.mjs';
 import { validateArtifactShape } from './lib/contracts.mjs';
+import {
+  assertCanonicalRoot,
+  assertSafeExistingPath,
+  assertSafeOutputPath,
+  assertUnchangedRoot,
+} from './lib/safe-path.mjs';
 
 const requiredDispositions = new Map([
   ['semantic', 'affirmed'],
@@ -42,7 +61,7 @@ export function reconcileLedger({
   reviewResults,
   priorReference,
   runId = priorLedger?.runId,
-  reviewerLane = 'lane-reconciliation',
+  reviewerLane = 'controller:reconcile-ledger-v1',
 }) {
   if (!priorLedger || priorLedger.runId !== runId || priorLedger.revision < 1) {
     throw new Error(
@@ -358,3 +377,251 @@ export function reconcileLedger({
   }
   return { ledger, reconciliation };
 }
+
+function parseArgs(argv) {
+  const values = { review: [] };
+  for (let index = 0; index < argv.length; index += 2) {
+    const key = argv[index]?.replace(/^--/, '');
+    const value = argv[index + 1];
+    if (!key || value === undefined)
+      throw new Error('Invalid reconciliation arguments');
+    if (key === 'review') values.review.push(value);
+    else values[key] = value;
+  }
+  for (const key of [
+    'manifest',
+    'input-ledger',
+    'output-ledger',
+    'output-review',
+  ]) {
+    if (!values[key]) throw new Error(`Missing --${key}`);
+  }
+  return values;
+}
+
+async function removeCreatedPath(path) {
+  try {
+    await unlink(path);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+}
+
+async function stageOutput(path, value) {
+  const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
+  const handle = await open(temporary, 'wx', 0o600);
+  let closed = false;
+  try {
+    await handle.writeFile(`${canonicalJson(value)}\n`, 'utf8');
+    await handle.sync();
+    await handle.close();
+    closed = true;
+  } catch (error) {
+    if (!closed) await handle.close().catch(() => {});
+    await removeCreatedPath(temporary).catch(() => {});
+    throw error;
+  }
+  return temporary;
+}
+
+async function writeAtomicPair(outputs, packetIdentity) {
+  const staged = [];
+  const published = [];
+  try {
+    for (const output of outputs) {
+      staged.push({
+        ...output,
+        temporary: await stageOutput(output.path, output.value),
+      });
+    }
+    await assertUnchangedRoot(packetIdentity);
+    for (const output of staged) {
+      await linkFile(output.temporary, output.path);
+      published.push(output.path);
+    }
+  } catch (error) {
+    const cleanupErrors = [];
+    for (const path of published.reverse()) {
+      try {
+        await removeCreatedPath(path);
+      } catch (cleanupError) {
+        cleanupErrors.push(cleanupError);
+      }
+    }
+    for (const { temporary } of staged) {
+      try {
+        await removeCreatedPath(temporary);
+      } catch (cleanupError) {
+        cleanupErrors.push(cleanupError);
+      }
+    }
+    if (cleanupErrors.length > 0) {
+      throw new Error(
+        `Reconciliation output publication failed and ${cleanupErrors.length} cleanup operation(s) also failed`,
+        { cause: error },
+      );
+    }
+    throw error;
+  }
+  for (const { temporary } of staged) {
+    await removeCreatedPath(temporary);
+  }
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+  const manifestPath = await realpath(options.manifest);
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  const manifestValidation = validateArtifactShape(manifest);
+  if (!manifestValidation.valid) {
+    throw new Error(
+      `Reconciliation rejects invalid manifest: ${manifestValidation.errors
+        .map((error) => error.code)
+        .join(', ')}`,
+    );
+  }
+  const declaration = manifest.execution?.reconciliation;
+  if (
+    !declaration ||
+    declaration.producer !== 'controller:reconcile-ledger-v1'
+  ) {
+    throw new Error(
+      'Manifest does not authorize controller:reconcile-ledger-v1',
+    );
+  }
+  const artifacts = manifest.artifacts ?? [];
+  const packetRoot = dirname(manifestPath);
+  const packetIdentity = await assertCanonicalRoot(packetRoot);
+  await assertSafeExistingPath(packetRoot, resolve(options.manifest));
+  const expected = (path) => resolve(packetRoot, path);
+  const resolvedInputs = new Map();
+  const resolvedOutputs = new Map();
+  for (const [option, field] of [
+    ['input-ledger', 'inputLedger'],
+    ['output-ledger', 'outputLedger'],
+    ['output-review', 'outputReview'],
+  ]) {
+    if (resolve(options[option]) !== expected(declaration[field])) {
+      throw new Error(
+        `Reconciliation ${option} drifts from the manifest declaration`,
+      );
+    }
+    if (option === 'input-ledger') {
+      await assertSafeExistingPath(packetRoot, resolve(options[option]));
+      resolvedInputs.set(option, await realpath(options[option]));
+    } else {
+      const outputPath = resolve(options[option]);
+      await assertSafeExistingPath(packetRoot, dirname(outputPath));
+      await assertSafeOutputPath(packetRoot, outputPath);
+      resolvedOutputs.set(option, outputPath);
+    }
+  }
+  const declaredReviews = [
+    ...(declaration.requiredReviews ?? []),
+    ...(declaration.conditionalReviews ?? []).filter((path) =>
+      artifacts.some((reference) => reference.path === path),
+    ),
+  ];
+  const declaredReviewInputs = await Promise.all(
+    declaredReviews.map(async (path) => {
+      const reference = artifacts.find((artifact) => artifact.path === path);
+      if (!reference) {
+        throw new Error(
+          `Reconciliation review ${path} has no manifest artifact reference`,
+        );
+      }
+      return { path: await realpath(expected(path)), reference };
+    }),
+  );
+  const declaredByPath = new Map(
+    declaredReviewInputs.map((input) => [input.path, input.reference]),
+  );
+  const suppliedReviews = await Promise.all(
+    options.review.map(async (path) => {
+      await assertSafeExistingPath(packetRoot, resolve(path));
+      return realpath(path);
+    }),
+  );
+  if (
+    new Set(suppliedReviews).size !== suppliedReviews.length ||
+    suppliedReviews.length !== declaredByPath.size ||
+    suppliedReviews.some((path) => !declaredByPath.has(path))
+  ) {
+    throw new Error(
+      'Reconciliation review set drifts from the manifest declaration',
+    );
+  }
+  const priorLedger = JSON.parse(
+    await readFile(resolvedInputs.get('input-ledger'), 'utf8'),
+  );
+  const priorReference = artifacts.find(
+    (reference) => reference.path === declaration.inputLedger,
+  );
+  if (
+    !priorReference ||
+    (await hashFile(resolvedInputs.get('input-ledger'))) !==
+      priorReference.digest
+  ) {
+    throw new Error(
+      'Reconciliation input ledger does not match its manifest digest',
+    );
+  }
+  const reviewResults = await Promise.all(
+    declaredReviewInputs.map(async ({ path, reference: artifactReference }) => {
+      if ((await hashFile(path)) !== artifactReference.digest) {
+        throw new Error(
+          `Reconciliation review ${artifactReference.path} does not match its manifest digest`,
+        );
+      }
+      const value = JSON.parse(await readFile(path, 'utf8'));
+      return {
+        ...value,
+        artifactReference,
+      };
+    }),
+  );
+  const result = reconcileLedger({
+    priorLedger,
+    reviewResults,
+    priorReference,
+    runId: manifest.run.id,
+    reviewerLane: declaration.producer,
+  });
+  await assertUnchangedRoot(packetIdentity);
+  await writeAtomicPair(
+    [
+      {
+        path: resolvedOutputs.get('output-ledger'),
+        value: result.ledger,
+      },
+      {
+        path: resolvedOutputs.get('output-review'),
+        value: result.reconciliation,
+      },
+    ],
+    packetIdentity,
+  );
+  process.stdout.write(
+    `${JSON.stringify(
+      {
+        ledger: {
+          path: declaration.outputLedger,
+          digest: await hashFile(resolvedOutputs.get('output-ledger')),
+        },
+        reconciliation: {
+          path: declaration.outputReview,
+          digest: await hashFile(resolvedOutputs.get('output-review')),
+        },
+      },
+      null,
+      2,
+    )}\n`,
+  );
+}
+
+if (isDirectExecution(import.meta.url)) {
+  main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
+    process.exitCode = 1;
+  });
+}

package/assets/skills/recon/scripts/render-packet.mjs

@@ -3,9 +3,9 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { lstat, open, rename, rm } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
 
 import { hashFile } from './lib/canonical-json.mjs';
+import { isDirectExecution } from './lib/cli-entry.mjs';
 import {
   assertSafeExistingPath,
   assertSafeOutputPath,
@@ -436,10 +436,7 @@ async function main(argv) {
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
 }
 
-if (
-  process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
-) {
+if (isDirectExecution(import.meta.url)) {
   main(process.argv.slice(2)).catch((error) => {
     process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
     process.exitCode = 1;

package/assets/skills/recon/scripts/validate-artifact.mjs

@@ -2,8 +2,8 @@
 
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { basename, join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
 
+import { isDirectExecution } from './lib/cli-entry.mjs';
 import { validateArtifactShape } from './lib/contracts.mjs';
 import {
   assertSafeExistingPath,
@@ -85,10 +85,7 @@ async function main(argv) {
   process.exitCode = result.valid ? 0 : 1;
 }
 
-if (
-  process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
-) {
+if (isDirectExecution(import.meta.url)) {
   main(process.argv.slice(2)).catch((error) => {
     process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
     process.exitCode = 2;

package/assets/skills/recon/scripts/validate-packet.mjs

@@ -2,9 +2,9 @@
 
 import { readFile, rm } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
 
 import { hashCanonicalJson, hashFile, sha256 } from './lib/canonical-json.mjs';
+import { isDirectExecution } from './lib/cli-entry.mjs';
 import {
   isDigest,
   isObject,
@@ -29,7 +29,6 @@ const requiredPasses = {
     'semantic-verification',
     'adversarial',
     'coverage',
-    'reconciliation',
   ],
   thorough: [
     'map',
@@ -37,7 +36,6 @@ const requiredPasses = {
     'semantic-verification',
     'adversarial',
     'coverage',
-    'reconciliation',
     'redundant-gather',
     'redundant-verification',
   ],
@@ -674,10 +672,6 @@ const passContracts = {
   },
   adversarial: { kind: 'recon.review-result', reviewKind: 'adversarial' },
   coverage: { kind: 'recon.review-result', reviewKind: 'coverage' },
-  reconciliation: {
-    kind: 'recon.review-result',
-    reviewKind: 'reconciliation',
-  },
   'redundant-verification': {
     kind: 'recon.review-result',
     reviewKind: 'redundant-verification',
@@ -746,7 +740,6 @@ const reviewWaveMode = {
   semantic: 'semantic-verification',
   adversarial: 'adversarial',
   coverage: 'coverage',
-  reconciliation: 'reconciliation',
   'redundant-verification': 'redundant-verification',
   'contradiction-resolution': 'contradiction-resolution',
 };
@@ -967,6 +960,13 @@ function validateApprovedLanes(
   const written = new Set();
   for (const [id, { reference, value }] of artifactsById) {
     if (value.runId !== manifest.run.id) continue;
+    if (
+      value.kind === 'recon.review-result' &&
+      value.reviewKind === 'reconciliation' &&
+      value.reviewerLane === 'controller:reconcile-ledger-v1'
+    ) {
+      continue;
+    }
     const laneId = artifactLaneId(value);
     if (laneId === null) continue;
     const approved = lanes.get(laneId);
@@ -1242,33 +1242,68 @@ function sameReference(left, right) {
 }
 
 function resolveTerminalReconciliation(
+  manifest,
   artifactsById,
   artifactsByPath,
-  passes,
   reconciliationRequired,
   errors,
 ) {
-  const terminalId = passes.get('reconciliation')?.[0];
+  const declaration = manifest.execution?.reconciliation;
   const reconciliationResults = [...artifactsById.values()].filter(
     ({ value }) =>
       value.kind === 'recon.review-result' &&
       value.reviewKind === 'reconciliation',
   );
   const expectedCount = reconciliationRequired ? 1 : 0;
-  if (
-    reconciliationResults.length !== expectedCount ||
-    (reconciliationRequired &&
-      reconciliationResults[0]?.value.id !== terminalId)
-  ) {
+  if (reconciliationResults.length !== expectedCount) {
     errors.push(
       issue(
         'SHADOW_RECONCILIATION',
         'The packet must contain exactly its one complete terminal reconciliation',
-        terminalId ?? '$.artifacts',
+        declaration?.outputReview ?? '$.artifacts',
+      ),
+    );
+  }
+  const entry = declaration
+    ? artifactsByPath.get(declaration.outputReview)
+    : null;
+  const outputLedgerEntry = declaration
+    ? artifactsByPath.get(declaration.outputLedger)
+    : null;
+  const reconciliation = entry?.value ?? null;
+  if (
+    reconciliationRequired &&
+    (!entry ||
+      reconciliation.reviewKind !== 'reconciliation' ||
+      reconciliation.reviewerLane !== declaration.producer ||
+      !sameReference(
+        entry.reference,
+        manifest.artifacts.find(
+          (item) => item.path === declaration.outputReview,
+        ),
+      ))
+  ) {
+    errors.push(
+      issue(
+        'INVALID_RECONCILIATION_BINDING',
+        'Reconciliation result must match the manifest-bound controller producer and output path',
+        declaration?.outputReview ?? '$.execution.reconciliation',
+      ),
+    );
+  }
+  if (
+    reconciliationRequired &&
+    (!outputLedgerEntry ||
+      outputLedgerEntry.value.kind !== 'recon.claim-ledger')
+  ) {
+    errors.push(
+      issue(
+        'INVALID_RECONCILIATION_OUTPUT',
+        'Controller reconciliation must produce its manifest-declared ledger candidate',
+        declaration?.outputLedger ?? '$.execution.reconciliation',
       ),
     );
   }
-  const reconciliation = artifactsById.get(terminalId)?.value ?? null;
   const priorLedger = reconciliation
     ? ([...artifactsByPath.values()].find(
         ({ reference, value }) =>
@@ -1276,7 +1311,11 @@ function resolveTerminalReconciliation(
           value.kind === 'recon.claim-ledger',
       )?.value ?? null)
     : null;
-  return { reconciliation, priorLedger };
+  return {
+    reconciliation,
+    priorLedger,
+    outputLedger: outputLedgerEntry?.value ?? null,
+  };
 }
 
 function reviewBriefBindsClaim(brief, reviewKind, claim, ledger, manifest) {
@@ -2461,12 +2500,26 @@ export async function compileValidatedRun(packetDirectory) {
     const reconciliationRequired =
       achievedProfile === 'standard' || achievedProfile === 'thorough';
     const reconciliationContext = resolveTerminalReconciliation(
+      manifest,
       artifactsById,
       artifactsByPath,
-      passes,
       reconciliationRequired,
       errors,
     );
+    if (
+      reconciliationRequired &&
+      reconciliationContext.outputLedger &&
+      hashCanonicalJson(reconciliationContext.outputLedger) !==
+        hashCanonicalJson(ledger)
+    ) {
+      errors.push(
+        issue(
+          'RECONCILIATION_PROMOTION_MISMATCH',
+          'Canonical claims.json must exactly match the validated controller ledger candidate',
+          '$.claims',
+        ),
+      );
+    }
     if (
       routing &&
       (!reconciliationRequired || reconciliationContext.priorLedger)
@@ -2598,10 +2651,7 @@ async function main(argv) {
   process.exitCode = result.publishable ? 0 : 1;
 }
 
-if (
-  process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
-) {
+if (isDirectExecution(import.meta.url)) {
   main(process.argv.slice(2)).catch((error) => {
     process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
     process.exitCode = 2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.2.76",
+  "version": "0.2.79",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.2.76"
+    "@open-agent-toolkit/control-plane": "0.2.79"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",