@fitlab-ai/agent-infra 0.9.1 → 0.9.3

package/lib/task/events.ts

@@ -16,8 +16,15 @@ import {
   parseImplementationInputs,
   renderImplementationInputs
 } from './implementation-inputs.ts';
+import { parseLedger, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
+import type { ReviewStage } from './ledger.ts';
+import { parseReviewSummary } from './review-artifacts.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import { findSectionHeading } from './sections.ts';
+import { validateLifecycleExecution } from './lifecycle-execution.ts';
+import { commitOrchestrationStageCompletion } from './orchestration.ts';
+import type { OrchestrationStageCompletion } from './orchestration.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
 import { captureTaskWriteMetadata, writeTask } from './write.ts';
 import type { TaskOperationSummary, TaskWriteErrorCode, TaskWriteOptions } from './write.ts';
 
@@ -35,15 +42,20 @@ type Verdict = 'approved' | 'changes-requested' | 'rejected';
 type TaskEventErrorCode =
   | 'EVENT_UNKNOWN' | 'EVENT_PAYLOAD_INVALID' | 'EVENT_TRANSITION_INVALID'
   | 'EVENT_LOG_MISSING' | 'EVENT_START_MISSING' | 'EVENT_ALREADY_COMPLETED'
-  | 'EVENT_LOG_CONFLICT' | 'EVENT_ARTIFACT_CONFLICT' | ArtifactErrorCode | TaskWriteErrorCode;
+  | 'EVENT_LOG_CONFLICT' | 'EVENT_ARTIFACT_CONFLICT' | 'EVENT_FINDING_COUNT_MISMATCH'
+  | 'EVENT_ORCHESTRATION_COMMIT_FAILED'
+  | ArtifactErrorCode | TaskWriteErrorCode;
 type TaskEventRequest = {
-  taskRef: string; event: TaskEventName | string; agent: string; dryRun?: boolean;
+  taskRef: string; event: TaskEventName | string; agent: string; dryRun?: boolean; orchestrated?: boolean;
   round?: number; question?: number; artifact?: string; fixFor?: string; implementationInput?: string;
   verdict?: Verdict; blockers?: number; major?: number; minor?: number;
   manualValidation?: number; filesModified?: number; testsPassed?: number;
   summaryResult?: string;
 };
 type TaskEventError = { code: TaskEventErrorCode; message: string };
+type TaskEventOptions = TaskWriteOptions & {
+  commitOrchestrationCompletion?: (plan: OrchestrationStageCompletion) => void;
+};
 type TaskEventResult = {
   status: 'planned' | 'applied' | 'no-op' | 'failed'; changed: boolean;
   event: string; requestRef: string; taskId: string | null; taskMdPath: string | null;
@@ -59,17 +71,17 @@ const BASE_FIELDS = new Set(['taskRef', 'event', 'agent', 'dryRun']);
 const SCHEMAS: Record<TaskEventName, { required?: string[]; optional?: string[] }> = {
   'analyze.started': { optional: ['round'] },
   'analyze.awaiting-input': { required: ['question'] },
-  'analyze.completed': { required: ['artifact'], optional: ['round'] },
+  'analyze.completed': { required: ['artifact'], optional: ['round', 'orchestrated'] },
   'review-analysis.started': { optional: ['round'] },
-  'review-analysis.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round'] },
+  'review-analysis.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round', 'orchestrated'] },
   'plan.started': { optional: ['round'] },
-  'plan.completed': { required: ['artifact'], optional: ['round'] },
+  'plan.completed': { required: ['artifact'], optional: ['round', 'orchestrated'] },
   'review-plan.started': { optional: ['round'] },
-  'review-plan.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round'] },
+  'review-plan.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round', 'orchestrated'] },
   'code.started': { optional: ['round', 'fixFor', 'implementationInput'] },
-  'code.completed': { required: ['artifact'], optional: ['round', 'fixFor', 'implementationInput', 'filesModified', 'testsPassed', 'blockers', 'major', 'minor', 'manualValidation'] },
+  'code.completed': { required: ['artifact'], optional: ['round', 'fixFor', 'implementationInput', 'filesModified', 'testsPassed', 'blockers', 'major', 'minor', 'manualValidation', 'orchestrated'] },
   'review-code.started': { optional: ['round'] },
-  'review-code.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round'] },
+  'review-code.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round', 'orchestrated'] },
   'manual-validation.started': { optional: ['round'] },
   'manual-validation.completed': { required: ['artifact', 'summaryResult'], optional: ['round'] }
 };
@@ -105,7 +117,7 @@ function validateTaskEventRequest(request: TaskEventRequest): TaskEventError | n
 const FAMILY = {
   analyze: { artifact: 'analysis', started: ['requirement-analysis', 'requirement-analysis-review', 'code'], completed: ['requirement-analysis', 'requirement-analysis-review', 'code'], target: 'requirement-analysis', label: 'Analyze Task' },
   'review-analysis': { artifact: 'review-analysis', started: ['requirement-analysis', 'requirement-analysis-review'], completed: ['requirement-analysis', 'requirement-analysis-review'], target: 'requirement-analysis-review', label: 'Review Analysis' },
-  plan: { artifact: 'plan', started: ['requirement-analysis-review', 'technical-design-review'], completed: ['requirement-analysis-review', 'technical-design-review'], target: 'technical-design', label: 'Plan Task' },
+  plan: { artifact: 'plan', started: ['requirement-analysis-review', 'technical-design-review', 'commit'], completed: ['requirement-analysis-review', 'technical-design-review', 'commit'], target: 'technical-design', label: 'Plan Task' },
   'review-plan': { artifact: 'review-plan', started: ['technical-design', 'technical-design-review'], completed: ['technical-design', 'technical-design-review'], target: 'technical-design-review', label: 'Review Plan' },
   code: { artifact: 'code', started: ['technical-design-review', 'code-review'], completed: ['technical-design-review', 'code-review'], target: 'code', label: 'Code Task' },
   'review-code': { artifact: 'review-code', started: ['code', 'code-review', 'commit'], completed: ['code', 'code-review', 'commit'], target: 'code-review', label: 'Review Code' },
@@ -113,6 +125,72 @@ const FAMILY = {
 } as const;
 type EventFamily = keyof typeof FAMILY;
 
+const REVIEW_LEDGER_STAGES: Partial<Record<EventFamily, ReviewStage>> = {
+  'review-analysis': 'analysis',
+  'review-plan': 'plan',
+  'review-code': 'code'
+};
+
+function validateReviewFindingCounts(
+  request: TaskEventRequest,
+  content: string,
+  family: EventFamily,
+  artifactPath: string | null
+): TaskEventError | null {
+  const stage = REVIEW_LEDGER_STAGES[family];
+  if (!stage || !artifactPath) return null;
+  const rows = parseLedger(content);
+  const invalid = validateLedgerRows(rows);
+  if (invalid) return { code: 'TASK_DOCUMENT_INVALID', message: `${invalid.code}: ${invalid.message}` };
+  const expected = summarizeLedgerStage(rows, stage).unresolvedFindingCounts;
+  const payload = {
+    blocker: request.blockers!,
+    major: request.major!,
+    minor: request.minor!
+  };
+  let reportContent: string;
+  try {
+    reportContent = fs.readFileSync(artifactPath, 'utf8');
+  } catch (error) {
+    return { code: 'EVENT_FINDING_COUNT_MISMATCH', message: String(error) };
+  }
+  const parsed = parseReviewSummary(reportContent);
+  if (!parsed.ok || !parsed.summary.counts) {
+    return {
+      code: 'EVENT_FINDING_COUNT_MISMATCH',
+      message: parsed.ok ? 'review summary finding counts are not finalized' : parsed.message
+    };
+  }
+  const report = parsed.summary.counts;
+  const reportVerdict = parsed.summary.verdict === 'Approved'
+    ? 'approved'
+    : parsed.summary.verdict === 'Changes Requested' ? 'changes-requested' : 'rejected';
+  const fields = [
+    ['blocker', 'blockers'],
+    ['major', 'major'],
+    ['minor', 'minor']
+  ] as const;
+  const differences = fields.flatMap(([severity, cliField]) => {
+    const values = [
+      expected[severity] === payload[severity]
+        ? null
+        : `${cliField} ledger ${expected[severity]}, payload ${payload[severity]}`,
+      expected[severity] === report[severity]
+        ? null
+        : `${cliField} ledger ${expected[severity]}, report ${report[severity]}`
+    ];
+    return values.filter((value): value is string => value !== null);
+  });
+  if (request.verdict !== reportVerdict) {
+    differences.push(`verdict report ${reportVerdict}, payload ${request.verdict}`);
+  }
+  if (differences.length === 0) return null;
+  return {
+    code: 'EVENT_FINDING_COUNT_MISMATCH',
+    message: `review summary, payload, and ${stage} ledger do not match: ${differences.join('; ')}`
+  };
+}
+
 function eventParts(event: string): { family: EventFamily; phase: 'started' | 'waiting' | 'completed' } {
   const [family, suffix] = event.split('.') as [EventFamily, string];
   return { family, phase: suffix === 'started' ? 'started' : suffix === 'awaiting-input' ? 'waiting' : 'completed' };
@@ -190,7 +268,7 @@ function openStartedIdentity(rows: ReturnType<typeof pairEntries>, family: Event
   return matches.length === 1 ? matches[0] : matches.length > 1 ? { conflict: true as const } : null;
 }
 
-function applyTaskEvent(request: TaskEventRequest, options: TaskWriteOptions = {}): TaskEventResult {
+function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOptions = {}): TaskEventResult {
   const invalid = validateTaskEventRequest(request);
   if (invalid) return failed(request, invalid);
   const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
@@ -256,6 +334,35 @@ function applyTaskEvent(request: TaskEventRequest, options: TaskWriteOptions = {
   }
   const allowed = FAMILY[eventIdentity.family][eventIdentity.phase === 'started' ? 'started' : 'completed'];
   if (!(allowed as readonly string[]).includes(currentStep)) return failed(normalized, { code: 'EVENT_TRANSITION_INVALID', message: `${normalized.event} is not allowed from '${currentStep}'` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+  const findingCountError = validateReviewFindingCounts(
+    normalized,
+    content,
+    eventIdentity.family,
+    completedArtifact?.path ?? null
+  );
+  if (findingCountError) return failed(normalized, findingCountError, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+  let orchestrationCompletion: OrchestrationStageCompletion | null = null;
+  if (eventIdentity.phase === 'completed' && eventIdentity.family !== 'manual-validation') {
+    const orchestrationStage = eventIdentity.family === 'analyze' ? 'analysis' : eventIdentity.family;
+    const execution = validateLifecycleExecution(normalized.taskRef, {
+      mode: normalized.orchestrated ? 'orchestrated' : 'standalone',
+      identity: {
+        stage: orchestrationStage,
+        round: normalized.round!,
+        artifact: normalized.artifact!,
+        role: eventIdentity.family.startsWith('review-') ? 'reviewer' : 'executor'
+      },
+      agent: normalized.agent,
+      dryRun: normalized.dryRun
+    }, { repoRoot: options.repoRoot });
+    if (!execution.ok) {
+      return failed(normalized, {
+        code: 'EVENT_TRANSITION_INVALID',
+        message: `${execution.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH'}: ${execution.error?.message ?? 'orchestration provenance validation failed'}`
+      }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
+    }
+    orchestrationCompletion = execution.completionPlan;
+  }
   let metadata;
   try { metadata = (options.metadataProvider ?? captureTaskWriteMetadata)(); }
   catch (error) { return failed(normalized, { code: 'METADATA_CAPTURE_FAILED', message: String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath }); }
@@ -291,6 +398,27 @@ function applyTaskEvent(request: TaskEventRequest, options: TaskWriteOptions = {
   mutations.push({ kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: section.heading, body });
   const result = writeTask({ taskRef: normalized.taskRef, expectedState: 'active', dryRun: normalized.dryRun, mutations }, { ...options, metadataProvider: () => metadata });
   if (result.status === 'failed') return failed(normalized, result.error, { taskId: result.taskId, taskMdPath: result.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, timestamp: result.timestamp, agentInfraVersion: result.agentInfraVersion, operations: result.operations, artifactContext });
+  if (!normalized.dryRun && orchestrationCompletion) {
+    try {
+      (options.commitOrchestrationCompletion ?? commitOrchestrationStageCompletion)(orchestrationCompletion);
+    } catch (error) {
+      return failed(normalized, {
+        code: 'EVENT_ORCHESTRATION_COMMIT_FAILED',
+        message: `task.md was written but orchestration completion could not be persisted; manual recovery is required: ${error instanceof Error ? error.message : String(error)}`
+      }, {
+        taskId: result.taskId,
+        taskMdPath: result.taskMdPath,
+        fromStep: currentStep,
+        toStep: step,
+        action: eventIdentity.action,
+        phase: eventIdentity.phase,
+        timestamp: result.timestamp,
+        agentInfraVersion: result.agentInfraVersion,
+        operations: result.operations,
+        artifactContext
+      });
+    }
+  }
   return {
     status: result.status, changed: result.changed, event: normalized.event,
     requestRef: normalized.taskRef, taskId: result.taskId, taskMdPath: result.taskMdPath,
@@ -302,6 +430,31 @@ function applyTaskEvent(request: TaskEventRequest, options: TaskWriteOptions = {
   };
 }
 
+function applyTaskEvent(request: TaskEventRequest, options: TaskEventOptions = {}): TaskEventResult {
+  const invalid = validateTaskEventRequest(request);
+  if (invalid) return failed(request, invalid);
+  const parts = eventParts(request.event);
+  if (request.dryRun || parts.phase !== 'completed' || parts.family === 'manual-validation') {
+    return applyTaskEventUnlocked(request, options);
+  }
+  const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return applyTaskEventUnlocked(request, options);
+  try {
+    return withTaskExecutionLock(
+      resolved.repoRoot,
+      resolved.taskId,
+      `task-event.${request.event}`,
+      () => applyTaskEventUnlocked(request, options)
+    );
+  } catch (error) {
+    if (!(error instanceof TaskExecutionLockError)) throw error;
+    return failed(request, {
+      code: 'EVENT_TRANSITION_INVALID',
+      message: `${error.code}: ${error.message}`
+    }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+  }
+}
+
 function successNoOp(
   request: TaskEventRequest, taskId: string, taskMdPath: string, currentStep: string,
   eventIdentity: ReturnType<typeof identity>, timestamp: string,
@@ -317,4 +470,4 @@ function successNoOp(
 }
 
 export { eventCatalog, validateTaskEventRequest, applyTaskEvent };
-export type { TaskEventName, TaskEventRequest, TaskEventResult, TaskEventError, TaskEventErrorCode, Verdict };
+export type { TaskEventName, TaskEventRequest, TaskEventResult, TaskEventError, TaskEventErrorCode, TaskEventOptions, Verdict };

package/lib/task/finalization-artifacts.ts

@@ -0,0 +1,58 @@
+import {
+  assertWritableInventory,
+  inspectTaskArtifacts
+} from './artifact-lifecycle.ts';
+import type {
+  ArtifactError,
+  ArtifactFamily,
+  ArtifactIdentity,
+  InspectOptions
+} from './artifact-lifecycle.ts';
+
+const COMPLETION_BACKFILL_FAMILIES = [
+  'analysis',
+  'review-analysis',
+  'plan',
+  'review-plan',
+  'code',
+  'review-code',
+  'manual-validation'
+] as const satisfies readonly ArtifactFamily[];
+
+type CompletionArtifactResult = {
+  status: 'ready' | 'failed';
+  changed: false;
+  taskId: string | null;
+  taskDir: string | null;
+  artifacts: readonly ArtifactIdentity[];
+  error: ArtifactError | null;
+};
+
+function inspectCompletionArtifacts(
+  taskRef: string,
+  options: InspectOptions = {}
+): CompletionArtifactResult {
+  const artifacts: ArtifactIdentity[] = [];
+  let taskId: string | null = null;
+  let taskDir: string | null = null;
+  for (const family of COMPLETION_BACKFILL_FAMILIES) {
+    const inventory = inspectTaskArtifacts(taskRef, family, options);
+    taskId = inventory.taskId ?? taskId;
+    taskDir = inventory.taskDir ?? taskDir;
+    if (inventory.status === 'failed') {
+      return { status: 'failed', changed: false, taskId, taskDir, artifacts: [], error: inventory.error };
+    }
+    const writableError = assertWritableInventory(inventory);
+    const brokenReference = inventory.diagnostics.find((item) => item.code === 'BROKEN_REFERENCE');
+    const error = writableError ?? (brokenReference ? {
+      code: 'ARTIFACT_REFERENCE_INVALID' as const,
+      message: brokenReference.message
+    } : null);
+    if (error) return { status: 'failed', changed: false, taskId, taskDir, artifacts: [], error };
+    artifacts.push(...inventory.artifacts);
+  }
+  return { status: 'ready', changed: false, taskId, taskDir, artifacts, error: null };
+}
+
+export { COMPLETION_BACKFILL_FAMILIES, inspectCompletionArtifacts };
+export type { CompletionArtifactResult };

package/lib/task/lifecycle-execution.ts

@@ -0,0 +1,106 @@
+import {
+  inspectOrchestrationStage,
+  pauseOrchestration,
+  planOrchestrationStageCompletion,
+  readRun
+} from './orchestration.ts';
+import type {
+  OrchestrationStageCompletion,
+  OrchestrationStageIdentity
+} from './orchestration.ts';
+import { resolveTaskRef } from './resolve-ref.ts';
+
+type LifecycleExecutionMode = 'standalone' | 'orchestrated';
+type LifecycleExecutionRequest = Readonly<{
+  mode: LifecycleExecutionMode;
+  identity: OrchestrationStageIdentity;
+  agent?: string;
+  dryRun?: boolean;
+}>;
+type LifecycleExecutionResult = Readonly<{
+  ok: boolean;
+  mode: LifecycleExecutionMode;
+  completionPlan: OrchestrationStageCompletion | null;
+  error: Readonly<{ code: string; message: string }> | null;
+}>;
+
+function failure(mode: LifecycleExecutionMode, code: string, message: string): LifecycleExecutionResult {
+  return { ok: false, mode, completionPlan: null, error: { code, message } };
+}
+
+function inspectLifecycleExecution(
+  taskRef: string,
+  request: LifecycleExecutionRequest,
+  options: Readonly<{ repoRoot?: string }> = {}
+): LifecycleExecutionResult {
+  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return failure(request.mode, resolved.code, resolved.message);
+  if (request.mode === 'standalone') {
+    try {
+      const run = readRun(resolved.taskDir);
+      if (run?.pendingDelegation) {
+        return failure(
+          request.mode,
+          'ORCHESTRATION_STANDALONE_BUSY',
+          'standalone lifecycle execution is blocked by a pending orchestration delegation'
+        );
+      }
+      return { ok: true, mode: request.mode, completionPlan: null, error: null };
+    } catch (error) {
+      return failure(
+        request.mode,
+        'ORCHESTRATION_STATE_INVALID',
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+
+  if (request.agent) {
+    const planned = planOrchestrationStageCompletion(taskRef, {
+      ...request.identity,
+      agent: request.agent
+    }, options);
+    if (planned.plan) {
+      return { ok: true, mode: request.mode, completionPlan: planned.plan, error: null };
+    }
+    return failure(
+      request.mode,
+      planned.result.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH',
+      planned.result.error?.message ?? 'orchestration provenance validation failed'
+    );
+  }
+
+  const inspected = inspectOrchestrationStage(taskRef, request.identity, options);
+  if (inspected.status !== 'failed') {
+    return { ok: true, mode: request.mode, completionPlan: null, error: null };
+  }
+  return failure(
+    request.mode,
+    inspected.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH',
+    inspected.error?.message ?? 'orchestration provenance validation failed'
+  );
+}
+
+function validateLifecycleExecution(
+  taskRef: string,
+  request: LifecycleExecutionRequest,
+  options: Readonly<{ repoRoot?: string }> = {}
+): LifecycleExecutionResult {
+  const inspected = inspectLifecycleExecution(taskRef, request, options);
+  if (inspected.ok || request.mode === 'standalone' || request.dryRun) return inspected;
+  const paused = pauseOrchestration(
+    taskRef,
+    inspected.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH',
+    inspected.error?.message ?? 'orchestration provenance validation failed',
+    true,
+    options
+  );
+  return failure(
+    request.mode,
+    paused.run?.pause?.code ?? inspected.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH',
+    paused.run?.pause?.message ?? inspected.error?.message ?? 'orchestration provenance validation failed'
+  );
+}
+
+export { inspectLifecycleExecution, validateLifecycleExecution };
+export type { LifecycleExecutionMode, LifecycleExecutionRequest, LifecycleExecutionResult };