@open-agent-toolkit/cli 0.3.10 → 0.3.12

package/assets/skills/recon/scripts/create-review-brief.mjs

@@ -6,6 +6,13 @@ import { dirname, relative, resolve } from 'node:path';
 import { canonicalJson, hashFile } from './lib/canonical-json.mjs';
 import { isDirectExecution } from './lib/cli-entry.mjs';
 import { issue, isObject, validateArtifactShape } from './lib/contracts.mjs';
+import {
+  projectEvidenceLink,
+  projectReviewQuestions,
+  projectReviewScope,
+  projectReviewSources,
+  reviewBriefExcludedInputs,
+} from './lib/review-binding.mjs';
 import { assertSafeOutputPath } from './lib/safe-path.mjs';
 
 const commonKeys = [
@@ -38,53 +45,11 @@ const forbiddenKeys = new Set([
   'dossierPath',
 ]);
 
-const reviewSourceFields = {
-  repository: ['root', 'revision', 'dirty', 'contentHashes'],
-  file: ['path', 'contentHash'],
-  url: ['url', 'capturePath', 'captureDigest', 'validatorState'],
-  'command-output': [
-    'argv',
-    'cwd',
-    'exitStatus',
-    'outputPath',
-    'outputDigest',
-    'environmentNames',
-  ],
-  'connected-resource': [
-    'system',
-    'resourceId',
-    'resourceVersion',
-    'retrievalToken',
-    'capturePath',
-    'captureDigest',
-  ],
-};
-const commonReviewSourceFields = [
-  'id',
-  'kind',
-  'available',
-  'authority',
-  'observedAt',
-  'validationState',
-];
-
 function selectedClaims(ledger, claimIds) {
   const selected = claimIds ? new Set(claimIds) : null;
   return ledger.claims.filter((claim) => !selected || selected.has(claim.id));
 }
 
-function projectReviewSource(source) {
-  const kindFields = reviewSourceFields[source.kind];
-  if (!kindFields) {
-    throw new Error(`Cannot project unknown source kind ${source.kind}`);
-  }
-  return Object.fromEntries(
-    [...commonReviewSourceFields, ...kindFields]
-      .filter((key) => Object.hasOwn(source, key))
-      .map((key) => [key, structuredClone(source[key])]),
-  );
-}
-
 function verificationBrief(input) {
   const claims = selectedClaims(input.ledger, input.claimIds);
   const evidenceById = new Map(
@@ -95,19 +60,14 @@ function verificationBrief(input) {
     id: claim.id,
     statement: claim.statement,
     evidence: claim.evidence.map((link) => {
-      const evidence = evidenceById.get(link.evidenceId);
+      const evidence = projectEvidenceLink(link, evidenceById);
       if (!evidence) {
         throw new Error(
           `Claim ${claim.id} references missing evidence ${link.evidenceId}`,
         );
       }
       sourceIds.add(evidence.sourceId);
-      return {
-        id: evidence.id,
-        sourceId: evidence.sourceId,
-        displayExcerpt: evidence.displayExcerpt,
-        locator: structuredClone(evidence.locator),
-      };
+      return evidence;
     }),
   }));
   const declaredSourceIds = new Set(
@@ -125,17 +85,9 @@ function verificationBrief(input) {
     runId: input.manifest.run.id,
     mode: 'verify',
     createdAt: input.createdAt,
-    excludedInputs: [
-      'worker_intermediates',
-      'prior_reasoning',
-      'consumer_summary',
-      'artifact_lineage',
-      'earlier_reviews',
-    ],
+    excludedInputs: [...reviewBriefExcludedInputs.verify],
     claims: projectedClaims,
-    sources: input.manifest.sources
-      .filter((source) => sourceIds.has(source.id))
-      .map(projectReviewSource),
+    sources: projectReviewSources(input.manifest, sourceIds),
   };
 }
 
@@ -147,19 +99,9 @@ function adversarialBrief(input) {
     runId: input.manifest.run.id,
     mode: 'adversary',
     createdAt: input.createdAt,
-    excludedInputs: [
-      'worker_intermediates',
-      'prior_reasoning',
-      'consumer_summary',
-      'artifact_lineage',
-      'earlier_reviews',
-      'verification_conclusions',
-    ],
-    scope: {
-      included: structuredClone(input.manifest.request.includedScope ?? []),
-      excluded: structuredClone(input.manifest.request.excludedScope ?? []),
-    },
-    questions: structuredClone(input.manifest.request.questions ?? []),
+    excludedInputs: [...reviewBriefExcludedInputs.adversary],
+    scope: projectReviewScope(input.manifest),
+    questions: projectReviewQuestions(input.manifest),
     provisionalStatements: selectedClaims(input.ledger, input.claimIds).map(
       (claim) => ({ id: claim.id, statement: claim.statement }),
     ),
@@ -174,20 +116,9 @@ function coverageBrief(input) {
     runId: input.manifest.run.id,
     mode: 'coverage',
     createdAt: input.createdAt,
-    excludedInputs: [
-      'worker_intermediates',
-      'prior_reasoning',
-      'consumer_summary',
-      'artifact_lineage',
-      'earlier_reviews',
-      'verification_conclusions',
-      'adversarial_conclusions',
-    ],
-    scope: {
-      included: structuredClone(input.manifest.request.includedScope ?? []),
-      excluded: structuredClone(input.manifest.request.excludedScope ?? []),
-    },
-    questions: structuredClone(input.manifest.request.questions ?? []),
+    excludedInputs: [...reviewBriefExcludedInputs.coverage],
+    scope: projectReviewScope(input.manifest),
+    questions: projectReviewQuestions(input.manifest),
     claims: selectedClaims(input.ledger, input.claimIds).map((claim) => ({
       id: claim.id,
       statement: claim.statement,

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

@@ -1,3 +1,8 @@
+import {
+  commonReviewSourceFields,
+  reviewSourceKindFields,
+} from './review-binding.mjs';
+
 export const SCHEMA_VERSION = 1;
 export const MANIFEST_SCHEMA_VERSION = 2;
 
@@ -1807,36 +1812,6 @@ function validateDossier(value, errors) {
   }
 }
 
-const reviewSourceKindFields = {
-  repository: ['root', 'revision', 'dirty', 'contentHashes'],
-  file: ['path', 'contentHash'],
-  url: ['url', 'capturePath', 'captureDigest', 'validatorState'],
-  'command-output': [
-    'argv',
-    'cwd',
-    'exitStatus',
-    'outputPath',
-    'outputDigest',
-    'environmentNames',
-  ],
-  'connected-resource': [
-    'system',
-    'resourceId',
-    'resourceVersion',
-    'retrievalToken',
-    'capturePath',
-    'captureDigest',
-  ],
-};
-const commonReviewSourceFields = [
-  'id',
-  'kind',
-  'available',
-  'authority',
-  'observedAt',
-  'validationState',
-];
-
 function validateReviewBriefSource(source, index, errors) {
   const path = `$.sources[${index}]`;
   if (!isObject(source)) {
@@ -2073,10 +2048,44 @@ function validateReviewBriefSource(source, index, errors) {
   }
 }
 
+const reviewBriefIdPattern = /^[a-z0-9]+(?:[-_.][a-z0-9]+)*$/;
+const reviewBriefTimestampPattern =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+
 function validateReviewBriefArtifact(value, errors) {
   for (const key of ['id', 'runId', 'mode', 'createdAt']) {
     requiredString(value, key, errors);
   }
+  // A brief's identifier and timestamp are shown to a blind reviewer, so
+  // both are structurally fixed: a short lowercase slug and a UTC ISO-8601
+  // instant. Neither can carry free text.
+  if (
+    typeof value.id === 'string' &&
+    (value.id.length > 64 || !reviewBriefIdPattern.test(value.id))
+  ) {
+    errors.push(
+      issue(
+        'INVALID_REVIEW_BRIEF',
+        'Brief id must be a lowercase slug of at most 64 characters',
+        '$.id',
+      ),
+    );
+  }
+  if (
+    typeof value.createdAt === 'string' &&
+    !(
+      reviewBriefTimestampPattern.test(value.createdAt) &&
+      Number.isFinite(Date.parse(value.createdAt))
+    )
+  ) {
+    errors.push(
+      issue(
+        'INVALID_REVIEW_BRIEF',
+        'Brief createdAt must be a UTC ISO-8601 timestamp',
+        '$.createdAt',
+      ),
+    );
+  }
   requiredArray(value, 'excludedInputs', errors);
   if (value.mode === 'verify') {
     requiredArray(value, 'claims', errors);
@@ -2271,6 +2280,124 @@ function validateReviewBriefArtifact(value, errors) {
   }
 }
 
+// The affirming disposition each review kind gives a claim it supports. The
+// first three are the required reviews for `verified`. The reconciler, the
+// validator, and the renderer all read this one table.
+export const affirmingDispositionByReviewKind = Object.freeze({
+  semantic: 'affirmed',
+  adversarial: 'unchallenged',
+  coverage: 'covered',
+  'redundant-verification': 'affirmed',
+  'contradiction-resolution': 'resolved',
+});
+
+export const requiredReviewKinds = Object.freeze([
+  'semantic',
+  'adversarial',
+  'coverage',
+]);
+
+// `unresolvedIssues` entries are a closed union:
+// - a string (legacy), read as a global issue;
+// - `{ text, claimIds }`, scoped to a non-empty list of unique claims the
+//   review covers; or
+// - `{ text, scope: 'global' }`.
+// Returns `{ scope: 'global' }`, `{ scope: 'claims', claimIds }`, or
+// `{ error }`. `coveredClaimIds`, when given, also rejects a scoped claim the
+// review does not cover. An error is rejected at artifact acceptance and is
+// never read as "no issue": `unresolvedIssuesBlockClaim` treats it as global.
+export function classifyUnresolvedIssue(entry, coveredClaimIds = null) {
+  if (typeof entry === 'string') return { scope: 'global' };
+  if (!isObject(entry)) {
+    return {
+      error: 'unresolvedIssues members must be strings or scoped issue objects',
+    };
+  }
+  if (typeof entry.text !== 'string' || entry.text.trim().length === 0) {
+    return { error: 'Scoped unresolved issues require non-empty text' };
+  }
+  const hasClaimIds = Object.hasOwn(entry, 'claimIds');
+  const hasScope = Object.hasOwn(entry, 'scope');
+  if (hasClaimIds && hasScope) {
+    return {
+      error: 'An unresolved issue names claimIds or a global scope, not both',
+    };
+  }
+  if (!hasClaimIds && !hasScope) {
+    return {
+      error: 'An unresolved issue object requires claimIds or scope: global',
+    };
+  }
+  const unknown = Object.keys(entry).filter(
+    (key) => !['text', hasClaimIds ? 'claimIds' : 'scope'].includes(key),
+  );
+  if (unknown.length > 0) {
+    return {
+      error: `Unresolved issue has unknown fields: ${unknown.join(', ')}`,
+    };
+  }
+  if (hasScope) {
+    return entry.scope === 'global'
+      ? { scope: 'global' }
+      : { error: 'An unresolved issue scope must be global' };
+  }
+  if (!Array.isArray(entry.claimIds) || entry.claimIds.length === 0) {
+    return {
+      error: 'Scoped unresolved issues require a non-empty claimIds array',
+    };
+  }
+  if (!entry.claimIds.every((id) => typeof id === 'string' && id.length > 0)) {
+    return {
+      error: 'Scoped unresolved issue claim IDs must be non-empty strings',
+    };
+  }
+  if (new Set(entry.claimIds).size !== entry.claimIds.length) {
+    return { error: 'Scoped unresolved issue claim IDs must be unique' };
+  }
+  const uncovered = coveredClaimIds
+    ? entry.claimIds.filter((id) => !coveredClaimIds.has(id))
+    : [];
+  if (uncovered.length > 0) {
+    return {
+      error: `Scoped unresolved issue names claims the review does not cover: ${uncovered.join(', ')}`,
+    };
+  }
+  return { scope: 'claims', claimIds: [...entry.claimIds] };
+}
+
+// True when any of the review's unresolved issues applies to `claimId`. Call
+// it only for a claim the review covers: a global issue applies to every
+// covered claim, a scoped issue only to the claims it names.
+export function unresolvedIssuesBlockClaim(review, claimId) {
+  return (
+    Array.isArray(review?.unresolvedIssues) ? review.unresolvedIssues : []
+  ).some((entry) => {
+    const classification = classifyUnresolvedIssue(entry);
+    if (classification.scope !== 'claims') return true;
+    return classification.claimIds.includes(claimId);
+  });
+}
+
+function validateUnresolvedIssues(value, errors) {
+  const coveredClaimIds = new Set(
+    (Array.isArray(value.dispositions) ? value.dispositions : [])
+      .map((disposition) => disposition?.claimId)
+      .filter((id) => typeof id === 'string'),
+  );
+  for (const [index, entry] of value.unresolvedIssues.entries()) {
+    const { error } = classifyUnresolvedIssue(entry, coveredClaimIds);
+    if (error) {
+      errors.push(
+        issue(
+          'INVALID_UNRESOLVED_ISSUE',
+          error,
+          `$.unresolvedIssues[${index}]`,
+        ),
+      );
+    }
+  }
+}
+
 function validateReviewResult(value, errors) {
   for (const key of ['id', 'runId', 'reviewKind', 'reviewerLane', 'status']) {
     requiredString(value, key, errors);
@@ -2286,17 +2413,7 @@ 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}]`,
-          ),
-        );
-      }
-    }
+    validateUnresolvedIssues(value, errors);
   }
   if (
     ![

package/assets/skills/recon/scripts/lib/review-binding.mjs

@@ -0,0 +1,123 @@
+// One owner for review-brief projection: the descriptor allowlists, source,
+// evidence, scope, and question projections, and each mode's fixed exclusion
+// list. The brief generator and the artifact-shape contract read these, and
+// the packet validator checks a brief by rebuilding it through the generator,
+// so there is no second projection to drift. Briefs stay blind: only the
+// fields below are projected, never full manifest entries or provenance.
+
+export const reviewSourceKindFields = Object.freeze({
+  repository: Object.freeze(['root', 'revision', 'dirty', 'contentHashes']),
+  file: Object.freeze(['path', 'contentHash']),
+  url: Object.freeze(['url', 'capturePath', 'captureDigest', 'validatorState']),
+  'command-output': Object.freeze([
+    'argv',
+    'cwd',
+    'exitStatus',
+    'outputPath',
+    'outputDigest',
+    'environmentNames',
+  ]),
+  'connected-resource': Object.freeze([
+    'system',
+    'resourceId',
+    'resourceVersion',
+    'retrievalToken',
+    'capturePath',
+    'captureDigest',
+  ]),
+});
+
+export const commonReviewSourceFields = Object.freeze([
+  'id',
+  'kind',
+  'available',
+  'authority',
+  'observedAt',
+  'validationState',
+]);
+
+// The fixed exclusion declaration each brief mode carries. It is structural,
+// not caller-supplied, so a brief cannot use it as a free-text channel.
+export const reviewBriefExcludedInputs = Object.freeze({
+  verify: Object.freeze([
+    'worker_intermediates',
+    'prior_reasoning',
+    'consumer_summary',
+    'artifact_lineage',
+    'earlier_reviews',
+  ]),
+  adversary: Object.freeze([
+    'worker_intermediates',
+    'prior_reasoning',
+    'consumer_summary',
+    'artifact_lineage',
+    'earlier_reviews',
+    'verification_conclusions',
+  ]),
+  coverage: Object.freeze([
+    'worker_intermediates',
+    'prior_reasoning',
+    'consumer_summary',
+    'artifact_lineage',
+    'earlier_reviews',
+    'verification_conclusions',
+    'adversarial_conclusions',
+  ]),
+});
+
+// Adversarial and coverage briefs carry the approved request's scope and
+// questions, projected here for both the generator and the validator.
+export function projectReviewScope(manifest) {
+  return {
+    included: structuredClone(manifest?.request?.includedScope ?? []),
+    excluded: structuredClone(manifest?.request?.excludedScope ?? []),
+  };
+}
+
+export function projectReviewQuestions(manifest) {
+  return structuredClone(manifest?.request?.questions ?? []);
+}
+
+const adversaryReviewKinds = new Set([
+  'adversarial',
+  'contradiction-resolution',
+]);
+
+export function projectReviewSource(source) {
+  const kindFields = reviewSourceKindFields[source?.kind];
+  if (!kindFields) {
+    throw new Error(`Cannot project unknown source kind ${source?.kind}`);
+  }
+  return Object.fromEntries(
+    [...commonReviewSourceFields, ...kindFields]
+      .filter((key) => Object.hasOwn(source, key))
+      .map((key) => [key, structuredClone(source[key])]),
+  );
+}
+
+// Projects the manifest sources named by `sourceIds`, in manifest order.
+export function projectReviewSources(manifest, sourceIds) {
+  return (manifest?.sources ?? [])
+    .filter((source) => sourceIds.has(source?.id))
+    .map(projectReviewSource);
+}
+
+export function projectEvidenceLink(link, evidenceById) {
+  const evidence = evidenceById.get(link?.evidenceId);
+  if (!evidence) return null;
+  return {
+    id: evidence.id,
+    sourceId: evidence.sourceId,
+    displayExcerpt: evidence.displayExcerpt,
+    locator: structuredClone(evidence.locator),
+  };
+}
+
+// The claim-bearing entries of a brief: adversarial briefs project
+// `provisionalStatements`; verification and coverage briefs project `claims`.
+export function reviewBriefEntries(brief, reviewKind) {
+  const entries = adversaryReviewKinds.has(reviewKind)
+    ? brief?.provisionalStatements
+    : brief?.claims;
+  return Array.isArray(entries) ? entries : [];
+}

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

@@ -428,7 +428,10 @@ export function createRoutingPreview(manifest) {
       maxConcurrency: execution.maxConcurrency,
       deadlineSeconds: execution.deadlineSeconds,
       retryLimit: execution.retryLimit,
-      worstCaseLaneAttempts: laneCount * (execution.retryLimit + 1),
+      // retryLimit counts pre-acceptance admission retries per lane, and the
+      // controller makes at most one, so a lane has at most two attempts.
+      worstCaseLaneAttempts:
+        laneCount * (Math.min(execution.retryLimit, 1) + 1),
     },
   });
 }
@@ -512,7 +515,7 @@ export function renderRoutingPreview(preview, format = 'markdown') {
     `- Conditions: ${encodeMarkdownValue(preview.limits.conditionCount)}`,
     `- Concurrency: ${encodeMarkdownValue(preview.limits.maxConcurrency)}`,
     `- Deadline seconds: ${encodeMarkdownValue(preview.limits.deadlineSeconds)}`,
-    `- Retry limit: ${encodeMarkdownValue(preview.limits.retryLimit)}`,
+    `- Pre-acceptance admission retries per lane (at most one used): ${encodeMarkdownValue(preview.limits.retryLimit)}`,
     `- Lane attempts: ${encodeMarkdownValue(preview.limits.worstCaseLaneAttempts)}`,
   );
   if (preview.profileCaps) {

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

@@ -12,7 +12,12 @@ 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 {
+  affirmingDispositionByReviewKind,
+  requiredReviewKinds,
+  unresolvedIssuesBlockClaim,
+  validateArtifactShape,
+} from './lib/contracts.mjs';
 import {
   assertCanonicalRoot,
   assertSafeExistingPath,
@@ -20,11 +25,12 @@ import {
   assertUnchangedRoot,
 } from './lib/safe-path.mjs';
 
-const requiredDispositions = new Map([
-  ['semantic', 'affirmed'],
-  ['adversarial', 'unchallenged'],
-  ['coverage', 'covered'],
-]);
+const requiredDispositions = new Map(
+  requiredReviewKinds.map((kind) => [
+    kind,
+    affirmingDispositionByReviewKind[kind],
+  ]),
+);
 
 const permittedDispositions = new Map([
   ['semantic', new Set(['affirmed', 'rejected', 'uncertain'])],
@@ -233,6 +239,11 @@ export function reconcileLedger({
         (item) => item.claimId === claim.id && item.disposition === 'uncertain',
       ),
     );
+    // A covering review's global issue, or an issue scoped to this claim,
+    // keeps the claim below verified. Publication applies the same rule.
+    const issueBlocked = supporting.some((review) =>
+      unresolvedIssuesBlockClaim(review, claim.id),
+    );
     const incomplete = [...requiredDispositions.keys()].some(
       (kind) =>
         !reviewResults.some(
@@ -291,7 +302,7 @@ export function reconcileLedger({
       }
       continue;
     }
-    if (uncertain || incomplete) {
+    if (uncertain || issueBlocked || incomplete) {
       const from = claim.status;
       const to = 'unresolved';
       if (legalReconciliationTransitions.has(`${from}:${to}`)) {