@open-agent-toolkit/cli 0.2.53 → 0.2.54

package/assets/skills/recon/scripts/lib/safe-path.mjs

@@ -0,0 +1,120 @@
+import { lstat, realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+
+function contains(root, candidate) {
+  const fromRoot = relative(root, candidate);
+  return (
+    fromRoot === '' ||
+    (!fromRoot.startsWith(`..${sep}`) &&
+      fromRoot !== '..' &&
+      !isAbsolute(fromRoot))
+  );
+}
+
+async function assertNoSymlinkComponents(root, candidate, allowMissing) {
+  const rootIdentity = await assertCanonicalRoot(root);
+  const resolvedRoot = rootIdentity.path;
+  const resolvedCandidate = resolve(candidate);
+  if (!contains(resolvedRoot, resolvedCandidate)) {
+    throw Object.assign(new Error('Path escapes its managed root'), {
+      code: 'PATH_ESCAPE',
+    });
+  }
+  const parts = relative(resolvedRoot, resolvedCandidate)
+    .split(sep)
+    .filter(Boolean);
+  let current = resolvedRoot;
+  for (const part of parts) {
+    current = resolve(current, part);
+    try {
+      const stat = await lstat(current);
+      if (stat.isSymbolicLink()) {
+        throw Object.assign(
+          new Error(`Symlink component is forbidden: ${current}`),
+          {
+            code: 'SYMLINK_ESCAPE',
+          },
+        );
+      }
+    } catch (error) {
+      if (error?.code === 'ENOENT' && allowMissing) break;
+      throw error;
+    }
+  }
+  const realRoot = rootIdentity.path;
+  let existing = resolvedCandidate;
+  while (true) {
+    try {
+      existing = await realpath(existing);
+      break;
+    } catch (error) {
+      if (error?.code !== 'ENOENT' || !allowMissing) throw error;
+      const parent = dirname(existing);
+      if (parent === existing) throw error;
+      existing = parent;
+    }
+  }
+  if (!contains(realRoot, existing)) {
+    throw Object.assign(new Error('Resolved path escapes its managed root'), {
+      code: 'SYMLINK_ESCAPE',
+    });
+  }
+  return resolvedCandidate;
+}
+
+export async function assertCanonicalRoot(root) {
+  if (typeof root !== 'string' || !isAbsolute(root)) {
+    throw Object.assign(new Error('Managed root must be an absolute path'), {
+      code: 'NON_CANONICAL_ROOT',
+    });
+  }
+  const resolvedRoot = resolve(root);
+  const stat = await lstat(resolvedRoot);
+  if (stat.isSymbolicLink()) {
+    throw Object.assign(new Error('Managed root cannot be a symlink alias'), {
+      code: 'SYMLINK_ESCAPE',
+    });
+  }
+  const canonicalRoot = await realpath(resolvedRoot);
+  if (canonicalRoot !== resolvedRoot) {
+    throw Object.assign(
+      new Error('Managed root must be its canonical realpath'),
+      {
+        code: 'NON_CANONICAL_ROOT',
+      },
+    );
+  }
+  return Object.freeze({
+    path: canonicalRoot,
+    device: stat.dev,
+    inode: stat.ino,
+  });
+}
+
+export async function assertUnchangedRoot(identity) {
+  const current = await assertCanonicalRoot(identity?.path);
+  if (
+    current.device !== identity?.device ||
+    current.inode !== identity?.inode
+  ) {
+    throw Object.assign(
+      new Error('Managed root identity changed after validation'),
+      {
+        code: 'ROOT_IDENTITY_CHANGED',
+      },
+    );
+  }
+  return current;
+}
+
+export function isContainedPath(root, candidate) {
+  return contains(resolve(root), resolve(candidate));
+}
+
+export async function assertSafeExistingPath(root, candidate) {
+  return assertNoSymlinkComponents(root, candidate, false);
+}
+
+export async function assertSafeOutputPath(root, candidate) {
+  return assertNoSymlinkComponents(root, candidate, true);
+}

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

@@ -0,0 +1,86 @@
+import { canonicalJson } from './canonical-json.mjs';
+
+const validatedRuns = new WeakSet();
+
+function clone(value) {
+  return JSON.parse(canonicalJson(value));
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) {
+    return value;
+  }
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+function normalizeTopology(topology) {
+  return {
+    requiredLanes: clone(topology.requiredLanes),
+    stages: [...topology.stageByLane.entries()]
+      .map(([laneId, stage]) => ({ laneId, stage: clone(stage) }))
+      .sort((left, right) => left.laneId.localeCompare(right.laneId)),
+    completeArtifactIdsByMode: Object.fromEntries(
+      [...topology.completeArtifactIdsByMode.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([mode, ids]) => [mode, [...ids].sort()]),
+    ),
+  };
+}
+
+export function createValidatedRun({
+  packetRoot,
+  filesystemIdentities,
+  canonicalByteDigests,
+  manifest,
+  ledger,
+  artifactsById,
+  exactEvidence,
+  topology,
+  achievedProfile,
+  receiptedReviewIds,
+  reconciliationContext,
+}) {
+  const run = {
+    packetRoot,
+    filesystemIdentities: [...filesystemIdentities.values()]
+      .map((identity) => clone(identity))
+      .sort((left, right) => left.path.localeCompare(right.path)),
+    canonicalByteDigests: [...canonicalByteDigests.entries()]
+      .map(([path, digest]) => ({ path, digest }))
+      .sort((left, right) => left.path.localeCompare(right.path)),
+    manifest: clone(manifest),
+    ledger: clone(ledger),
+    artifacts: [...artifactsById.entries()]
+      .map(([id, artifact]) => ({
+        id,
+        reference: clone(artifact.reference),
+        value: clone(artifact.value),
+      }))
+      .sort((left, right) => left.id.localeCompare(right.id)),
+    exactEvidenceIds: [...exactEvidence].sort(),
+    topology: normalizeTopology(topology),
+    achievedProfile,
+    receiptedReviewIds: [...receiptedReviewIds].sort(),
+    terminalReconciliation: reconciliationContext?.reconciliation
+      ? clone(reconciliationContext.reconciliation)
+      : null,
+    priorLedger: reconciliationContext?.priorLedger
+      ? clone(reconciliationContext.priorLedger)
+      : null,
+  };
+  deepFreeze(run);
+  validatedRuns.add(run);
+  return run;
+}
+
+export function assertValidatedRun(value) {
+  if (!value || !validatedRuns.has(value) || !Object.isFrozen(value)) {
+    throw new TypeError('Expected an immutable ValidatedRun');
+  }
+  return value;
+}
+
+export function isValidatedRun(value) {
+  return Boolean(value && validatedRuns.has(value) && Object.isFrozen(value));
+}

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

@@ -0,0 +1,360 @@
+import { canonicalJson } from './lib/canonical-json.mjs';
+import { validateArtifactShape } from './lib/contracts.mjs';
+
+const requiredDispositions = new Map([
+  ['semantic', 'affirmed'],
+  ['adversarial', 'unchallenged'],
+  ['coverage', 'covered'],
+]);
+
+const permittedDispositions = new Map([
+  ['semantic', new Set(['affirmed', 'rejected', 'uncertain'])],
+  ['adversarial', new Set(['unchallenged', 'challenged'])],
+  ['coverage', new Set(['covered', 'gap'])],
+]);
+
+const legalReconciliationTransitions = new Set([
+  'provisional:verified',
+  'provisional:contested',
+  'provisional:unresolved',
+  'provisional:unsupported',
+  'supported:verified',
+  'supported:contested',
+  'supported:unresolved',
+  'supported:unsupported',
+  'verified:contested',
+  'verified:unresolved',
+  'verified:unsupported',
+  'contested:verified',
+  'contested:unresolved',
+  'contested:unsupported',
+  'unresolved:verified',
+  'unresolved:contested',
+  'unresolved:unsupported',
+]);
+
+function exactClone(value) {
+  return JSON.parse(canonicalJson(value));
+}
+
+export function reconcileLedger({
+  priorLedger,
+  reviewResults,
+  priorReference,
+  runId = priorLedger?.runId,
+  reviewerLane = 'lane-reconciliation',
+}) {
+  if (!priorLedger || priorLedger.runId !== runId || priorLedger.revision < 1) {
+    throw new Error(
+      'Reconciliation requires the exact prior ledger for this run',
+    );
+  }
+  if (!Array.isArray(reviewResults)) {
+    throw new Error('Reconciliation requires an exact review-result array');
+  }
+  for (const review of reviewResults) {
+    const reviewArtifact = { ...review };
+    delete reviewArtifact.artifactReference;
+    const validation = validateArtifactShape(reviewArtifact);
+    if (!validation.valid) {
+      throw new Error(
+        `Reconciliation rejects schema-invalid review ${review.id ?? '<unknown>'}: ${validation.errors.map((error) => error.code).join(', ')}`,
+      );
+    }
+  }
+  const reviewKinds = reviewResults.map((review) => review.reviewKind);
+  if (
+    new Set(reviewKinds).size !== reviewKinds.length ||
+    reviewKinds.includes('reconciliation')
+  ) {
+    throw new Error(
+      'Reconciliation rejects duplicate, nested, or shadow review results',
+    );
+  }
+  const reviews = new Map(
+    reviewResults.map((review) => [review.reviewKind, review]),
+  );
+  for (const [kind] of requiredDispositions) {
+    const review = reviews.get(kind);
+    if (!review || review.runId !== runId || review.status !== 'complete') {
+      throw new Error(`Reconciliation requires a complete ${kind} result`);
+    }
+    const allowed = permittedDispositions.get(kind);
+    if (!review.dispositions.every((item) => allowed.has(item.disposition))) {
+      throw new Error(`Reconciliation received an invalid ${kind} disposition`);
+    }
+  }
+  const ledger = exactClone(priorLedger);
+  ledger.revision = priorLedger.revision + 1;
+  ledger.inputArtifacts = [
+    ...priorLedger.inputArtifacts,
+    priorReference,
+    ...reviewResults.map(
+      (review) => review.artifactReference ?? review.permittedInputs[0],
+    ),
+  ];
+  const claimsById = new Map(ledger.claims.map((claim) => [claim.id, claim]));
+  const priorEvidenceById = new Map();
+  for (const evidence of ledger.evidence) {
+    if (priorEvidenceById.has(evidence.id)) {
+      throw new Error(
+        `Reconciliation rejects duplicate evidence ${evidence.id}`,
+      );
+    }
+    priorEvidenceById.set(evidence.id, canonicalJson(evidence));
+  }
+  for (const claim of ledger.claims) {
+    const links = new Set();
+    for (const link of claim.evidence) {
+      if (!priorEvidenceById.has(link.evidenceId)) {
+        throw new Error(
+          `Reconciliation rejects invented evidence link ${link.evidenceId} on ${claim.id}`,
+        );
+      }
+      const key = canonicalJson(link);
+      if (links.has(key)) {
+        throw new Error(
+          `Reconciliation rejects duplicate evidence link ${link.evidenceId} on ${claim.id}`,
+        );
+      }
+      links.add(key);
+    }
+  }
+  const incorporatedEvidence = new Map();
+  for (const review of reviewResults) {
+    const reviewEvidenceById = new Map(
+      review.newEvidence.map((evidence) => [evidence.id, evidence]),
+    );
+    const dispositionClaimIds = new Set(
+      review.dispositions.map((item) => item.claimId),
+    );
+    const associationKeys = new Set();
+    for (const association of review.evidenceAssociations ?? []) {
+      const key = canonicalJson(association);
+      if (associationKeys.has(key)) {
+        throw new Error(
+          `Reconciliation rejects duplicate evidence association ${association.evidenceId} -> ${association.claimId}`,
+        );
+      }
+      associationKeys.add(key);
+      if (!reviewEvidenceById.has(association.evidenceId)) {
+        throw new Error(
+          `Reconciliation rejects association for ${association.evidenceId} without matching new evidence`,
+        );
+      }
+      if (!claimsById.has(association.claimId)) {
+        throw new Error(
+          `Reconciliation rejects association to unknown claim ${association.claimId}`,
+        );
+      }
+      if (!dispositionClaimIds.has(association.claimId)) {
+        throw new Error(
+          `Reconciliation rejects association to claim ${association.claimId} without a review disposition`,
+        );
+      }
+    }
+    for (const evidence of review.newEvidence) {
+      const bytes = canonicalJson(evidence);
+      const previousBytes = priorEvidenceById.get(evidence.id);
+      const incorporated = incorporatedEvidence.get(evidence.id);
+      if (previousBytes !== undefined || incorporated) {
+        const existingBytes = previousBytes ?? incorporated.bytes;
+        const description =
+          existingBytes === bytes
+            ? 'duplicate evidence'
+            : 'conflicting evidence';
+        throw new Error(`Reconciliation rejects ${description} ${evidence.id}`);
+      }
+      const associations = (review.evidenceAssociations ?? []).filter(
+        (association) => association.evidenceId === evidence.id,
+      );
+      if (associations.length === 0) {
+        throw new Error(
+          `Reconciliation rejects unincorporated evidence ${evidence.id} without an affected claim`,
+        );
+      }
+      incorporatedEvidence.set(evidence.id, {
+        bytes,
+        evidence: exactClone(evidence),
+        associations: exactClone(associations),
+      });
+    }
+  }
+  for (const { evidence, associations } of incorporatedEvidence.values()) {
+    ledger.evidence.push(evidence);
+    for (const association of associations) {
+      claimsById.get(association.claimId).evidence.push({
+        evidenceId: association.evidenceId,
+        relation: association.relation,
+      });
+    }
+  }
+  const transitions = [];
+  const removals = [];
+  const removalDispositions = [];
+  for (const claim of ledger.claims) {
+    const supporting = reviewResults.filter((review) =>
+      review.dispositions.some((item) => item.claimId === claim.id),
+    );
+    const rejectedReview = supporting.find((review) =>
+      review.dispositions.some(
+        (item) => item.claimId === claim.id && item.disposition === 'rejected',
+      ),
+    );
+    const challenged = supporting.some(
+      (review) =>
+        review.reviewKind === 'adversarial' &&
+        review.dispositions.some(
+          (item) =>
+            item.claimId === claim.id && item.disposition === 'challenged',
+        ),
+    );
+    const uncertain = supporting.some((review) =>
+      review.dispositions.some(
+        (item) => item.claimId === claim.id && item.disposition === 'uncertain',
+      ),
+    );
+    const incomplete = [...requiredDispositions.keys()].some(
+      (kind) =>
+        !reviewResults.some(
+          (review) =>
+            review.reviewKind === kind &&
+            review.dispositions.some((item) => item.claimId === claim.id),
+        ),
+    );
+    const coverageGap = supporting.some(
+      (review) =>
+        review.reviewKind === 'coverage' &&
+        review.dispositions.some(
+          (item) => item.claimId === claim.id && item.disposition === 'gap',
+        ),
+    );
+    const materialCoverageGap = reviewResults.some(
+      (review) =>
+        review.reviewKind === 'coverage' &&
+        review.coverageFindings.some(
+          (finding) =>
+            finding.material === true && finding.claimIds.includes(claim.id),
+        ),
+    );
+    const coreComplete = [...requiredDispositions].every(
+      ([kind, disposition]) =>
+        supporting.some(
+          (review) =>
+            review.reviewKind === kind &&
+            review.dispositions.some(
+              (item) =>
+                item.claimId === claim.id && item.disposition === disposition,
+            ),
+        ),
+    );
+    claim.reviewIds = [
+      ...new Set([
+        ...claim.reviewIds,
+        ...supporting.map((review) => review.id),
+      ]),
+    ];
+    if (rejectedReview) {
+      const from = claim.status;
+      const to = 'unsupported';
+      if (legalReconciliationTransitions.has(`${from}:${to}`)) {
+        claim.status = to;
+        if (from !== to) transitions.push({ claimId: claim.id, from, to });
+      }
+      continue;
+    }
+    if (challenged) {
+      const from = claim.status;
+      const to = 'contested';
+      if (legalReconciliationTransitions.has(`${from}:${to}`)) {
+        claim.status = to;
+        if (from !== to) transitions.push({ claimId: claim.id, from, to });
+      }
+      continue;
+    }
+    if (uncertain || incomplete) {
+      const from = claim.status;
+      const to = 'unresolved';
+      if (legalReconciliationTransitions.has(`${from}:${to}`)) {
+        claim.status = to;
+        if (from !== to) transitions.push({ claimId: claim.id, from, to });
+      }
+      continue;
+    }
+    if (coverageGap && !coreComplete) {
+      if (
+        claim.status === 'verified' ||
+        claim.status === 'provisional' ||
+        materialCoverageGap
+      ) {
+        const from = claim.status;
+        const to = materialCoverageGap ? 'contested' : 'unresolved';
+        if (legalReconciliationTransitions.has(`${from}:${to}`)) {
+          claim.status = to;
+          if (from !== to) transitions.push({ claimId: claim.id, from, to });
+        }
+        continue;
+      }
+    }
+    if (!coreComplete) continue;
+    const from = claim.status;
+    const to = materialCoverageGap ? 'contested' : 'verified';
+    if (!legalReconciliationTransitions.has(`${from}:${to}`)) continue;
+    claim.status = to;
+    if (from !== claim.status)
+      transitions.push({ claimId: claim.id, from, to: claim.status });
+  }
+  if (removals.length > 0) {
+    const removed = new Set(removals);
+    ledger.claims = ledger.claims.filter((claim) => !removed.has(claim.id));
+    if (ledger.synthesis && Array.isArray(ledger.synthesis.keyClaimIds)) {
+      ledger.synthesis.keyClaimIds = ledger.synthesis.keyClaimIds.filter(
+        (id) => !removed.has(id),
+      );
+    }
+  }
+  ledger.transitions = transitions;
+  const coverageDispositions = (
+    reviews.get('coverage')?.coverageFindings ?? []
+  ).map((finding) => ({
+    findingId: finding.id,
+    gapId: finding.gapId,
+    disposition: 'accepted-gap',
+  }));
+  const reconciliation = {
+    kind: 'recon.review-result',
+    schemaVersion: 1,
+    id: 'review-reconciliation',
+    runId,
+    reviewKind: 'reconciliation',
+    reviewerLane,
+    status: 'complete',
+    inputLedger: { ...priorReference, revision: priorLedger.revision },
+    outputRevision: ledger.revision,
+    incorporatedReviewIds: reviewResults.map((review) => review.id),
+    transitions: exactClone(transitions),
+    additions: [],
+    removals,
+    removalDispositions,
+    coverageDispositions,
+    permittedInputs: [
+      priorReference,
+      ...reviewResults.map(
+        (review) => review.artifactReference ?? review.permittedInputs[0],
+      ),
+    ],
+    excludedInputs: [],
+    dispositions: [],
+    newEvidence: [],
+    evidenceAssociations: [],
+    coverageFindings: [],
+    unresolvedIssues: [],
+  };
+  const ledgerValidation = validateArtifactShape(ledger);
+  if (!ledgerValidation.valid) {
+    throw new Error(
+      `Reconciliation rejects schema-invalid review evidence: ${ledgerValidation.errors.map((error) => error.code).join(', ')}`,
+    );
+  }
+  return { ledger, reconciliation };
+}