@open-agent-toolkit/cli 0.2.77 → 0.3.0

package/assets/skills/recon/scripts/lib/contracts.mjs

@@ -33,7 +33,6 @@ export const workerModes = [
   'verify',
   'adversary',
   'coverage',
-  'reconcile',
 ];
 export const evidenceRelations = [
   'supports',
@@ -49,7 +48,6 @@ export const waveModes = [
   'semantic-verification',
   'adversarial',
   'coverage',
-  'reconciliation',
   'redundant-gather',
   'redundant-verification',
   'contradiction-resolution',
@@ -67,6 +65,18 @@ export const conditionPredicates = [
   'unresolved-material-challenge',
 ];
 
+const reconciliationReviewPaths = Object.freeze({
+  'semantic-verification': 'reviews/semantic.json',
+  adversarial: 'reviews/adversarial.json',
+  coverage: 'reviews/coverage.json',
+  'redundant-verification': 'reviews/redundant-verification.json',
+  'contradiction-resolution': 'reviews/contradiction-resolution.json',
+});
+
+const singletonReviewWaveModes = new Set(
+  Object.keys(reconciliationReviewPaths),
+);
+
 function profilePolicy(
   orderedSingletonWaveModes,
   allowedWaveModes,
@@ -100,7 +110,6 @@ export const profileRoutingPolicy = Object.freeze({
       'semantic-verification',
       'adversarial',
       'coverage',
-      'reconciliation',
     ],
     [
       'map',
@@ -109,7 +118,6 @@ export const profileRoutingPolicy = Object.freeze({
       'semantic-verification',
       'adversarial',
       'coverage',
-      'reconciliation',
       'contradiction-resolution',
     ],
     [
@@ -131,7 +139,6 @@ export const profileRoutingPolicy = Object.freeze({
       'adversarial',
       'coverage',
       'redundant-verification',
-      'reconciliation',
     ],
     [
       'map',
@@ -142,7 +149,6 @@ export const profileRoutingPolicy = Object.freeze({
       'coverage',
       'redundant-gather',
       'redundant-verification',
-      'reconciliation',
       'contradiction-resolution',
     ],
     [
@@ -154,7 +160,7 @@ export const profileRoutingPolicy = Object.freeze({
       'redundant-verification',
       'contradiction-resolution',
     ],
-    { lanes: 20, concurrency: 8, conditions: 2 },
+    { lanes: 20, concurrency: 8, conditions: 1 },
   ),
 });
 
@@ -359,6 +365,7 @@ const executionV2Keys = new Set([
   'retryLimit',
   'waves',
   'conditions',
+  'reconciliation',
   'approval',
 ]);
 
@@ -410,6 +417,57 @@ function validateExecutionV2(value, errors, path) {
   requiredObject(value, 'approval', errors, path);
   validateApprovalEvidence(value.approval, errors, `${path}.approval`);
 
+  if (Object.hasOwn(value, 'reconciliation')) {
+    const reconciliation = value.reconciliation;
+    requiredObject(value, 'reconciliation', errors, path);
+    if (isObject(reconciliation)) {
+      closedObject(
+        reconciliation,
+        new Set([
+          'producer',
+          'inputLedger',
+          'outputLedger',
+          'outputReview',
+          'requiredReviews',
+          'conditionalReviews',
+        ]),
+        errors,
+        `${path}.reconciliation`,
+      );
+      for (const key of [
+        'producer',
+        'inputLedger',
+        'outputLedger',
+        'outputReview',
+      ]) {
+        requiredString(reconciliation, key, errors, `${path}.reconciliation`);
+      }
+      if (reconciliation.producer !== 'controller:reconcile-ledger-v1') {
+        errors.push(
+          issue(
+            'INVALID_RECONCILIATION_PRODUCER',
+            'Controller reconciliation must use controller:reconcile-ledger-v1',
+            `${path}.reconciliation.producer`,
+          ),
+        );
+      }
+      for (const key of ['requiredReviews', 'conditionalReviews']) {
+        requiredArray(reconciliation, key, errors, `${path}.reconciliation`);
+        for (const [index, item] of (reconciliation[key] ?? []).entries()) {
+          if (typeof item !== 'string' || item.length === 0) {
+            errors.push(
+              issue(
+                'INVALID_RECONCILIATION_PATH',
+                `${key} must contain non-empty paths`,
+                `${path}.reconciliation.${key}[${index}]`,
+              ),
+            );
+          }
+        }
+      }
+    }
+  }
+
   const waves = Array.isArray(value.waves) ? value.waves : [];
   const waveIds = new Set();
   const laneIds = new Set();
@@ -624,7 +682,8 @@ export function validateV2ProfileTopology(
   for (const [waveIndex, wave] of waves.entries()) {
     if (
       policy.allowedWaveModes.includes(wave?.mode) &&
-      !policy.countedLaneModes.includes(wave.mode) &&
+      (!policy.countedLaneModes.includes(wave.mode) ||
+        singletonReviewWaveModes.has(wave.mode)) &&
       Array.isArray(wave?.lanes) &&
       wave.lanes.length !== 1
     ) {
@@ -673,25 +732,77 @@ export function validateV2ProfileTopology(
       ),
     );
   }
-  const reconciliationIndexes = waves
-    .map((wave, index) => (wave?.mode === 'reconciliation' ? index : -1))
-    .filter((index) => index !== -1);
   const requiresReconciliation = ['standard', 'thorough'].includes(
     requestedProfile,
   );
-  if (
-    reconciliationIndexes.length > 1 ||
-    (requiresReconciliation && reconciliationIndexes.length !== 1) ||
-    reconciliationIndexes.some((index) => index !== waves.length - 1) ||
-    reconciliationIndexes.some((index) => waves[index]?.conditional === true)
-  ) {
+  if (requiresReconciliation !== isObject(execution.reconciliation)) {
     errors.push(
       issue(
         'INVALID_TERMINAL_TOPOLOGY',
-        'Standard and thorough routing require exactly one non-conditional terminal reconciliation wave',
-        `${path}.waves`,
+        'Standard and thorough routing require exactly one controller reconciliation declaration',
+        `${path}.reconciliation`,
       ),
     );
+  } else if (requiresReconciliation) {
+    const reconciliation = execution.reconciliation;
+    const expected = {
+      producer: 'controller:reconcile-ledger-v1',
+      inputLedger: 'raw/drafts/claims-v1.json',
+      outputLedger: 'raw/drafts/claims-v2.json',
+      outputReview: 'reviews/reconciliation.json',
+      requiredReviews: [
+        reconciliationReviewPaths['semantic-verification'],
+        reconciliationReviewPaths.adversarial,
+        reconciliationReviewPaths.coverage,
+      ],
+      conditionalReviews: [
+        reconciliationReviewPaths['redundant-verification'],
+        reconciliationReviewPaths['contradiction-resolution'],
+      ],
+    };
+    const matchesExpected =
+      ['producer', 'inputLedger', 'outputLedger', 'outputReview'].every(
+        (key) => reconciliation[key] === expected[key],
+      ) &&
+      ['requiredReviews', 'conditionalReviews'].every(
+        (key) =>
+          Array.isArray(reconciliation[key]) &&
+          reconciliation[key].length === expected[key].length &&
+          reconciliation[key].every(
+            (value, index) => value === expected[key][index],
+          ),
+      );
+    if (!matchesExpected) {
+      errors.push(
+        issue(
+          'INVALID_RECONCILIATION_PATH',
+          'Controller reconciliation paths and review sets must exactly match the closed manifest contract',
+          `${path}.reconciliation`,
+        ),
+      );
+    }
+    for (const [mode, reviewPath] of Object.entries(
+      reconciliationReviewPaths,
+    )) {
+      const matchingWaves = waves.filter((wave) => wave?.mode === mode);
+      if (matchingWaves.length !== 1 || matchingWaves[0].lanes?.length !== 1) {
+        continue;
+      }
+      const writeRoot = matchingWaves[0].lanes[0].writeRoot;
+      if (
+        typeof writeRoot === 'string' &&
+        reviewPath !== writeRoot &&
+        !reviewPath.startsWith(`${writeRoot}/`)
+      ) {
+        errors.push(
+          issue(
+            'INVALID_RECONCILIATION_PATH',
+            `${mode} output ${reviewPath} must be inside its approved write root`,
+            `${path}.waves`,
+          ),
+        );
+      }
+    }
   }
 
   const waveIndexes = new Map(
@@ -708,7 +819,6 @@ export function validateV2ProfileTopology(
     'predicate',
     'maxActivations',
   ]);
-  const terminalIndex = reconciliationIndexes[0] ?? -1;
   for (const [index, condition] of conditions.entries()) {
     const conditionPath = `${path}.conditions[${index}]`;
     if (
@@ -852,24 +962,10 @@ export function validateV2ProfileTopology(
         );
       }
     }
-    if (
-      terminalIndex !== -1 &&
-      destinationIndex !== undefined &&
-      destinationIndex >= terminalIndex
-    ) {
-      errors.push(
-        issue(
-          'INVALID_TERMINAL_TOPOLOGY',
-          'Conditional evidence waves must complete before the one terminal reconciliation',
-          `${conditionPath}.destinationWaveId`,
-        ),
-      );
-    }
   }
   for (const wave of waves) {
     if (
       wave?.conditional === true &&
-      wave.mode !== 'reconciliation' &&
       !policy.orderedSingletonWaveModes.includes(wave.mode) &&
       !conditionDestinations.has(wave.waveId)
     ) {
@@ -927,10 +1023,7 @@ export function validateV2ProfileTopology(
     );
   }
   const conditionalRequired = stageIndexes.find(
-    ({ mode, indexes }) =>
-      mode !== 'reconciliation' &&
-      indexes.length === 1 &&
-      waves[indexes[0]]?.conditional,
+    ({ indexes }) => indexes.length === 1 && waves[indexes[0]]?.conditional,
   );
   if (conditionalRequired) {
     errors.push(
@@ -2192,6 +2285,19 @@ function validateReviewResult(value, errors) {
   ]) {
     requiredArray(value, key, errors);
   }
+  if (Array.isArray(value.unresolvedIssues)) {
+    for (const [index, unresolvedIssue] of value.unresolvedIssues.entries()) {
+      if (typeof unresolvedIssue !== 'string') {
+        errors.push(
+          issue(
+            'INVALID_UNRESOLVED_ISSUE',
+            'unresolvedIssues members must be strings',
+            `$.unresolvedIssues[${index}]`,
+          ),
+        );
+      }
+    }
+  }
   if (
     ![
       'semantic',

package/assets/skills/recon/scripts/lib/routing.mjs

@@ -52,11 +52,6 @@ const economicalDefaults = Object.freeze({
       'Compare evidence with an explicit question or source inventory.',
     taskClass: 'mechanical-recon',
   }),
-  reconciliation: Object.freeze({
-    assignment:
-      'Assemble agreement and disagreement without deciding implications.',
-    taskClass: 'mechanical-recon',
-  }),
   'contradiction-resolution': Object.freeze({
     assignment: 'Seek discriminating evidence for a named contradiction.',
     taskClass: 'mechanical-recon',
@@ -172,6 +167,7 @@ function assertProposalExecution(manifest) {
       'retryLimit',
       'waves',
       'conditions',
+      'reconciliation',
       'approval',
     ]),
     'INVALID_ROUTING_PROPOSAL',
@@ -377,6 +373,7 @@ export function normalizeManifestRouting(manifest) {
       target: resolveEffectiveWaveTarget(execution, wave),
     })),
     conditions: clone(execution.conditions),
+    reconciliation: clone(execution.reconciliation ?? null),
     approval: clone(execution.approval),
   };
   return deepFreeze(routing);

package/assets/skills/recon/scripts/lib/validated-run.mjs

@@ -58,7 +58,7 @@ export function createValidatedRun({
     passes: normalizePasses(passes),
     achievedProfile,
     assuranceReviewIds: [...assuranceReviewIds].sort(),
-    terminalReconciliation: reconciliationContext?.reconciliation
+    controllerReconciliation: reconciliationContext?.reconciliation
       ? clone(reconciliationContext.reconciliation)
       : null,
     priorLedger: reconciliationContext?.priorLedger

package/assets/skills/recon/scripts/prepare-routing.mjs

@@ -1,10 +1,8 @@
 #!/usr/bin/env node
 
-import { realpathSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
 
+import { isDirectExecution } from './lib/cli-entry.mjs';
 import {
   checkApprovedWaveTarget,
   createRoutingPreview,
@@ -81,29 +79,7 @@ export async function main(argv = process.argv.slice(2)) {
   );
 }
 
-/**
- * Direct invocation, compared as canonical paths on both sides. Comparing a raw
- * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
- * that exits 0 whenever the skill is reached through a symlinked install root,
- * and canonicalizing only one side has the same effect under
- * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
- * A path that cannot be canonicalized is not a module Node loaded as the entry
- * point, so a thrown `realpathSync` means "not invoked directly" and returns
- * `false`; it never masks a direct run.
- */
-function isDirectInvocation(invokedPath) {
-  if (!invokedPath) return false;
-  try {
-    return (
-      realpathSync(fileURLToPath(import.meta.url)) ===
-      realpathSync(resolve(invokedPath))
-    );
-  } catch {
-    return false;
-  }
-}
-
-if (isDirectInvocation(process.argv[1])) {
+if (isDirectExecution(import.meta.url)) {
   main().catch((error) => {
     const code = error instanceof RoutingContractError ? error.code : 'ERROR';
     process.stderr.write(`${code}: ${error.message}\n`);

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;
+  });
+}