@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/lib/task/pr-delivery-fact.ts

@@ -1,5 +1,4 @@
 import type { ResourceIdentity } from '../platform/resource-identity.ts';
-import { isLegacyCompatibilityEnabled, legacyCompatibilityError, VERSION } from '../version.ts';
 import {
   isResourceIdentity,
   parseResourceIdentity,
@@ -17,14 +16,6 @@ type PrDeliveryIdentity = {
   base: { repository: string; ref: string; sha: string };
 };
 
-type LegacyPrDeliveryIdentity = {
-  repository: string;
-  number: number;
-  nodeId: string;
-  url: string;
-  head: { repository: string; ref: string; sha: string };
-  base: { repository: string; ref: string; sha: string };
-};
 type CurrentPrDeliveryIdentityInput = {
   resource: ResourceIdentity;
   repository: string;
@@ -93,10 +84,6 @@ function timestamp(value: unknown, label: string): string {
   if (Number.isNaN(Date.parse(result))) throw factError(`${label} must be a valid timestamp`);
   return new Date(result).toISOString();
 }
-function positiveNumber(value: unknown, label: string): number {
-  if (!Number.isSafeInteger(value) || (value as number) <= 0) throw factError(`${label} must be a positive integer`);
-  return value as number;
-}
 function parseRef(value: unknown, label: string): { repository: string; ref: string; sha: string } {
   if (!isRecord(value)) throw factError(`${label} must be an object`);
   exactKeys(value, ['repository', 'ref', 'sha'], label);
@@ -115,35 +102,19 @@ function canonicalIdentity(value: unknown): PrDeliveryIdentity {
   };
 }
 
-function decodeLegacyIdentity(value: unknown): PrDeliveryIdentity {
-  if (!isRecord(value)) throw factError('legacy identity must be an object');
-  // TODO(compat): Remove the v1 identity decoder before the first stable v1.0.0 release.
-  exactKeys(value, ['repository', 'number', 'nodeId', 'url', 'head', 'base'], 'legacy identity');
-  const legacy = {
-    number: positiveNumber(value.number, 'legacy identity.number'),
-    repository: text(value.repository, 'identity.repository'),
-    nodeId: text(value.nodeId, 'legacy identity.nodeId'),
-    url: text(value.url, 'identity.url'),
-    head: parseRef(value.head, 'identity.head'),
-    base: parseRef(value.base, 'identity.base')
-  } satisfies LegacyPrDeliveryIdentity;
-  return {
-    resource: { kind: 'number', value: legacy.number },
-    repository: legacy.repository,
-    url: legacy.url,
-    head: legacy.head,
-    base: legacy.base
-  };
-}
-
 function provenanceForSource(source: PrDeliveryBindingSource): PrDeliveryProvenance { return source === 'created' ? 'create-post' : source === 'reused' ? 'reuse' : source; }
 
-function parseFact(value: unknown, runtimeVersion = VERSION): PrDeliveryFact {
+function legacyFactError(): PrDeliveryFactError {
+  return Object.assign(
+    new Error('PLATFORM_IDENTITY_LEGACY_UNSUPPORTED: v1 PR delivery fact is unsupported; use the previous tool version to view this task or migrate its fact to version 2 before using this version'),
+    { code: 'PLATFORM_IDENTITY_LEGACY_UNSUPPORTED' }
+  );
+}
+
+function parseFact(value: unknown): PrDeliveryFact {
   if (!isRecord(value)) throw factError('fact must be an object');
-  if ((value.version !== 1 && value.version !== 2) || typeof value.state !== 'string') throw factError('version or state is invalid');
-  if (value.version === 1 && !isLegacyCompatibilityEnabled(runtimeVersion)) {
-    throw legacyCompatibilityError('v1 PR delivery fact', runtimeVersion);
-  }
+  if (value.version === 1) throw legacyFactError();
+  if (value.version !== 2 || typeof value.state !== 'string') throw factError('version or state is invalid');
   if (value.state === 'unbound') {
     exactKeys(value, ['version', 'state', 'reason'], 'unbound fact');
     if (value.reason !== 'initial') throw factError('unbound reason is invalid');
@@ -155,24 +126,6 @@ function parseFact(value: unknown, runtimeVersion = VERSION): PrDeliveryFact {
     return { version: 2, state: 'skipped', reason: 'explicit', decidedAt: timestamp(value.decidedAt, 'skipped.decidedAt') };
   }
   if (value.state !== 'bound') throw factError('state is invalid');
-  if (value.version === 1) {
-    // TODO(compat): Remove this v1-to-v2 shape conversion before the first stable v1.0.0 release.
-    exactKeys(value, ['version', 'state', 'identity', 'binding', 'provenance'], 'legacy bound fact');
-    if (!isRecord(value.binding) || !isRecord(value.provenance)) throw factError('legacy binding or provenance is invalid');
-    exactKeys(value.binding, ['status', 'source', 'verifiedAt', 'issueNumber', 'remoteState', 'mergedAt', 'mergeCommitSha'], 'legacy binding');
-    const issueNumber = value.binding.issueNumber === null ? null : positiveNumber(value.binding.issueNumber, 'legacy binding.issueNumber');
-    return parseFact({
-      version: 2,
-      state: 'bound',
-      identity: decodeLegacyIdentity(value.identity),
-      binding: {
-        status: 'verified', source: value.binding.source, verifiedAt: timestamp(value.binding.verifiedAt, 'binding.verifiedAt'),
-        issueIdentity: issueNumber === null ? null : { kind: 'number', value: issueNumber }, remoteState: value.binding.remoteState,
-        mergedAt: value.binding.mergedAt === null ? null : timestamp(value.binding.mergedAt, 'binding.mergedAt'), mergeCommitSha: nullableText(value.binding.mergeCommitSha, 'binding.mergeCommitSha')
-      },
-      provenance: value.provenance
-    }, runtimeVersion);
-  }
   exactKeys(value, ['version', 'state', 'identity', 'binding', 'provenance'], 'bound fact');
   if (!isRecord(value.binding) || !isRecord(value.provenance)) throw factError('binding or provenance is invalid');
   exactKeys(value.binding, ['status', 'source', 'verifiedAt', 'issueIdentity', 'remoteState', 'mergedAt', 'mergeCommitSha'], 'binding');
@@ -195,19 +148,19 @@ function parseFact(value: unknown, runtimeVersion = VERSION): PrDeliveryFact {
   };
 }
 
-function decodePrDeliveryFact(value: unknown, runtimeVersion = VERSION): PrDeliveryFact {
+function decodePrDeliveryFact(value: unknown, _runtimeVersion?: string): PrDeliveryFact {
   if (typeof value === 'string') {
     let decoded: unknown;
     try { decoded = JSON.parse(value); }
     catch { throw factError('value is not valid JSON'); }
-    return parseFact(decoded, runtimeVersion);
+    return parseFact(decoded);
   }
-  return parseFact(value, runtimeVersion);
+  return parseFact(value);
 }
 function encodePrDeliveryFact(fact: PrDeliveryFact): string { return JSON.stringify(parseFact(fact)); }
-function readPrDeliveryFact(metadata: Record<string, unknown>, runtimeVersion = VERSION): PrDeliveryFactReadResult {
+function readPrDeliveryFact(metadata: Record<string, unknown>, _runtimeVersion?: string): PrDeliveryFactReadResult {
   if (!Object.hasOwn(metadata, PR_DELIVERY_FACT_KEY) || metadata[PR_DELIVERY_FACT_KEY] === '') return { status: 'missing', fact: null };
-  try { return { status: 'valid', fact: decodePrDeliveryFact(metadata[PR_DELIVERY_FACT_KEY], runtimeVersion) }; }
+  try { return { status: 'valid', fact: decodePrDeliveryFact(metadata[PR_DELIVERY_FACT_KEY]) }; }
   catch (error) { return { status: 'invalid', fact: null, error: asFactError(error) }; }
 }
 function buildUnboundFact(): PrDeliveryFact { return { version: 2, state: 'unbound', reason: 'initial' }; }

package/lib/task/qualification-audit.ts

@@ -1,7 +1,9 @@
 import { createHash } from 'node:crypto';
 
+import { parseArtifactName } from './artifact-name.ts';
 import { parseTypedTaskFrontmatter } from './frontmatter.ts';
-import { parseTable } from './sections.ts';
+import { findSectionRange, parseTable } from './sections.ts';
+import { scanVisibleMarkdown } from './markdown.ts';
 
 const TASK_CONSTRAINT_HEADINGS = ['约束', 'Constraints'] as const;
 const TASK_CANDIDATE_HEADINGS = ['候选与否决方案', 'Candidate and Rejected Options', 'Candidates and Rejected Options', 'Candidates and Rejected Alternatives'] as const;
@@ -170,21 +172,9 @@ function taskInputDigest(qualification: Pick<TaskQualification, 'constraints' |
   return digest(canonicalTaskInput(qualification));
 }
 
-function sectionBody(content: string, aliases: readonly string[], level = 2): string | null {
-  const heading = aliases.map((value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
-  const marker = '#'.repeat(level);
-  const match = new RegExp(`^${marker}\\s+(${heading})\\s*$`, 'm').exec(content);
-  if (!match) return null;
-  const rest = content.slice((match.index ?? 0) + match[0].length);
-  const end = rest.search(new RegExp(`^#{2,${level}}\\s+`, 'm'));
-  return rest.slice(0, end < 0 ? rest.length : end);
-}
-
-function stripSection(content: string, aliases: readonly string[]): string {
-  const body = sectionBody(content, aliases);
-  if (body === null) return normalizeText(content);
-  const heading = aliases.map((value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
-  return normalizeText(content.replace(new RegExp(`^##\\s+(?:${heading})\\s*$[\\s\\S]*?(?=^##\\s+|(?![\\s\\S]))`, 'm'), ''));
+function sectionBody(content: string, aliases: readonly string[], level: 2 | 3 = 2): string | null {
+  const section = findSectionRange(content, aliases, level);
+  return section ? content.slice(section.bodyStart, section.end) : null;
 }
 
 function stripFrontmatter(content: string): string {
@@ -218,7 +208,7 @@ function nonConstraintInputDigest(content: string): string {
     ['返工意图', 'Rework Intents'],
     CONFIRMATION_HEADINGS,
     ['完成检查清单', 'Completion Checklist']
-  ].reduce((value, aliases) => stripSection(value, aliases), projection);
+  ].reduce((value, aliases) => stripSectionAtLevel(value, aliases, 2), projection);
   return digest(projection);
 }
 
@@ -231,12 +221,9 @@ function stripTaskInputSection(content: string, aliases: readonly string[]): str
   return stripSectionAtLevel(result, aliases, 2);
 }
 
-function stripSectionAtLevel(content: string, aliases: readonly string[], level: number): string {
-  const body = sectionBody(content, aliases, level);
-  if (body === null) return normalizeText(content);
-  const heading = aliases.map((value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
-  const marker = '#'.repeat(level);
-  return normalizeText(content.replace(new RegExp(`^${marker}\\s+(?:${heading})\\s*$[\\s\\S]*?(?=^#{2,${level}}\\s+|(?![\\s\\S]))`, 'm'), ''));
+function stripSectionAtLevel(content: string, aliases: readonly string[], level: 2 | 3): string {
+  const section = findSectionRange(content, aliases, level);
+  return normalizeText(section ? content.slice(0, section.start) + content.slice(section.end) : content);
 }
 
 function parseTaskQualification(content: string): { ok: true; qualification: TaskQualification } | { ok: false; code: string; message: string } {
@@ -246,12 +233,14 @@ function parseTaskQualification(content: string): { ok: true; qualification: Tas
   const hasCandidateHeading = candidateBody !== null;
   if ((!hasConstraintHeading && !hasCandidateHeading)
     || (hasConstraintHeading && hasCandidateHeading
-      && !/^\s*\|/m.test(constraintBody!) && !/^\s*\|/m.test(candidateBody!))) {
+      && !scanVisibleMarkdown(constraintBody!).lines.some((line) => line.text.trim().startsWith('|'))
+      && !scanVisibleMarkdown(candidateBody!).lines.some((line) => line.text.trim().startsWith('|')))) {
     return { ok: true, qualification: { present: false, constraints: [], candidates: [], constraintDigest: digest([]), taskInputDigest: digest({ constraints: [], candidates: [] }), nonConstraintInputDigest: nonConstraintInputDigest(content) } };
   }
   if (!hasConstraintHeading || !hasCandidateHeading) {
-    const hasCanonicalTable = new RegExp(`\\|\\s*${CONSTRAINT_COLUMNS.join('\\s*\\|\\s*')}\\s*\\|`).test(content)
-      || new RegExp(`\\|\\s*${CANDIDATE_COLUMNS.join('\\s*\\|\\s*')}\\s*\\|`).test(content);
+    const visible = scanVisibleMarkdown(content).lines.map((line) => line.text).join('\n');
+    const hasCanonicalTable = new RegExp(`\\|\\s*${CONSTRAINT_COLUMNS.join('\\s*\\|\\s*')}\\s*\\|`).test(visible)
+      || new RegExp(`\\|\\s*${CANDIDATE_COLUMNS.join('\\s*\\|\\s*')}\\s*\\|`).test(visible);
     if (hasCanonicalTable) return { ok: false, code: 'QUALIFICATION_TASK_CONTRACT_INVALID', message: 'task qualification requires both constraints and candidates sections' };
     return { ok: true, qualification: { present: false, constraints: [], candidates: [], constraintDigest: digest([]), taskInputDigest: digest({ constraints: [], candidates: [] }), nonConstraintInputDigest: nonConstraintInputDigest(content) } };
   }
@@ -315,10 +304,10 @@ function parseAuditTable(content: string, heading: (typeof AUDIT_SUBSECTIONS)[nu
   return table?.rows.map((row) => ({ ...row.values })) ?? null;
 }
 
-function parseArtifactName(value: string): { family: ArtifactFamily; round: number } | null {
-  const match = /^(analysis|review-analysis|plan|review-plan|code|review-code)(?:-r([2-9]|[1-9]\d+))?\.md$/.exec(value);
-  if (!match) return null;
-  return { family: match[1] as ArtifactFamily, round: match[2] ? Number(match[2]) : 1 };
+function parseAuditArtifactName(value: string): { family: ArtifactFamily; round: number } | null {
+  const identity = parseArtifactName(value);
+  return identity && ARTIFACT_FAMILIES.includes(identity.family as ArtifactFamily)
+    ? { family: identity.family as ArtifactFamily, round: identity.round } : null;
 }
 
 function upstreamArtifactDigest(rows: readonly UpstreamRelation[]): string {
@@ -327,7 +316,7 @@ function upstreamArtifactDigest(rows: readonly UpstreamRelation[]): string {
 }
 
 function validateUpstreamRelation(row: UpstreamRelation): void {
-  const identity = parseArtifactName(row.upstreamArtifact);
+  const identity = parseAuditArtifactName(row.upstreamArtifact);
   if (!ARTIFACT_FAMILIES.includes(row.upstreamFamily) || !identity || identity.family !== row.upstreamFamily
     || identity.round !== row.upstreamRound || !Number.isSafeInteger(row.upstreamRound)
     || !/^[a-f0-9]{64}$/i.test(row.upstreamSha256) || !RELATIONS.includes(row.relation)) {
@@ -368,7 +357,7 @@ function expectedQualificationRelations(
   const inputName = family === 'code' ? frontmatter.code_input_artifact : family.startsWith('review-') ? frontmatter.review_input_artifact : '';
   const inputSha256 = family === 'code' ? frontmatter.code_input_sha256 : family.startsWith('review-') ? frontmatter.review_input_sha256 : '';
   if (typeof inputName !== 'string' || !inputName || typeof inputSha256 !== 'string' || !inputSha256) return { ok: true, relations: undefined };
-  const identity = parseArtifactName(inputName);
+  const identity = parseAuditArtifactName(inputName);
   if (!identity) return { ok: false, code: 'QUALIFICATION_STARTED_INPUT_INVALID', message: `started input '${inputName}' is not canonical` };
   const relation: UpstreamRelation = {
     upstreamFamily: identity.family, upstreamArtifact: inputName, upstreamRound: identity.round,
@@ -507,7 +496,7 @@ function validateQualificationAudit(
     || upstreamArtifactDigest(options.expectedUpstreamRelations) !== upstreamArtifactDigest(audit.audit.upstreamRelations)
   )) return { ok: false, code: 'QUALIFICATION_UPSTREAM_RELATION_MISMATCH', message: 'qualification audit upstream relations do not match the started artifact inputs' };
   if (options.family && options.artifact) {
-    const identity = parseArtifactName(options.artifact);
+    const identity = parseAuditArtifactName(options.artifact);
     if (!identity || identity.family !== options.family) return { ok: false, code: 'QUALIFICATION_ARTIFACT_IDENTITY_INVALID', message: `artifact '${options.artifact}' is not canonical for '${options.family}'` };
   }
   return { ok: true, qualification: task.qualification, audit: audit.audit };

package/lib/task/recovery-warning.ts

@@ -0,0 +1,21 @@
+export type RecoveryWarning = Readonly<{ code: string; message: string; action: string }>;
+
+function warningText(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0 && value.trim() === value && !/[\r\n]/u.test(value);
+}
+
+export function isRecoveryWarning(value: unknown): value is RecoveryWarning {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const warning = value as Record<string, unknown>;
+  return Object.keys(warning).sort().join(',') === 'action,code,message'
+    && warningText(warning.code)
+    && warningText(warning.message)
+    && warningText(warning.action);
+}
+
+export function sameRecoveryWarning(left: unknown, right: unknown): boolean {
+  return isRecoveryWarning(left) && isRecoveryWarning(right)
+    && left.code === right.code
+    && left.message === right.message
+    && left.action === right.action;
+}

package/lib/task/review-artifacts.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { scanVisibleMarkdown } from './decision-details.ts';
+import { scanVisibleMarkdown } from './markdown.ts';
 
 type ReviewFindingCounts = {
   blocker: number;
@@ -53,23 +53,6 @@ function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
-function maxRound(entries: string[], stem: string): number {
-  let max = 0;
-  for (const entry of entries) {
-    if (entry === `${stem}.md`) {
-      max = Math.max(max, 1);
-      continue;
-    }
-    const match = entry.match(new RegExp(`^${escapeRegExp(stem)}-r(\\d+)\\.md$`));
-    if (match) max = Math.max(max, Number(match[1]));
-  }
-  return max;
-}
-
-function artifactName(stem: string, round: number): string {
-  return round === 1 ? `${stem}.md` : `${stem}-r${round}.md`;
-}
-
 function normalizeVerdict(raw: unknown): ReviewVerdict | '' {
   const value = String(raw).trim().toLowerCase();
   if (value === '通过' || value === 'approved') return 'Approved';
@@ -260,12 +243,10 @@ function parseVerdict(reviewPath: string): PathVerdictResult {
 }
 
 export {
-  artifactName,
   equalCounts,
   escapeRegExp,
   extractSection,
   finalizeReviewSummaryContent,
-  maxRound,
   normalizeVerdict,
   parseReviewSummary,
   parseVerdict,

package/lib/task/review-command.ts

@@ -0,0 +1,24 @@
+import type { ReviewFinalizationRequest } from './review-finalization.ts';
+
+export function parseReviewCommand(args: readonly string[]): ReviewFinalizationRequest & {
+  overrideTicket?: string; overrideTarget?: string; overrideScope?: string;
+} {
+  if (!args[0] || args[1] !== 'finalize-summary') throw new Error('task ref and finalize-summary are required');
+  const values: Record<string, string | boolean> = {};
+  const flags = {
+    '--stage': 'stage', '--artifact': 'artifact', '--orchestrated': 'orchestrated', '--dry-run': 'dryRun',
+    '--recovery-id': 'recoveryId',
+    '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
+  } as const;
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (!Object.hasOwn(flags, flag)) throw new Error(`unknown option '${flag}'`);
+    const key = flags[flag as keyof typeof flags];
+    if (Object.hasOwn(values, key)) throw new Error(`duplicate option '${flag}'`);
+    const value = flag === '--orchestrated' || flag === '--dry-run' ? true : args[++index];
+    if (!value || typeof value === 'string' && value.startsWith('--')) throw new Error(`option '${flag}' requires a value`);
+    values[key] = value;
+  }
+  if (!values.stage || !values.artifact) throw new Error("options '--stage' and '--artifact' are required");
+  return { taskRef: args[0], ...values } as ReturnType<typeof parseReviewCommand>;
+}