@fitlab-ai/agent-infra 0.9.2 → 0.9.3

package/lib/task/delegation-receipts.ts

@@ -16,13 +16,17 @@ type DelegationReceipt = Readonly<{
   artifact: string;
   client: AgentClientId;
   requestedModel: string | null;
+  requestedReasoningEffort: string | null;
   actualModel: string | null;
+  actualReasoningEffort: string | null;
   modelFallbackReason: string | null;
+  reasoningEffortFallbackReason: string | null;
   parentId: string | null;
   childId: string | null;
   spawnMode: string | null;
   agent: string | null;
   status: DelegationStatus;
+  workspaceSnapshotScope?: 'task';
   beforeFingerprint: string;
   afterFingerprint: string | null;
   changedPaths: readonly string[];
@@ -50,14 +54,16 @@ function fail(code: string, message: string): ReceiptFailure {
 }
 
 function prepareDelegation(
-  input: Omit<DelegationReceipt, 'id' | 'actualModel' | 'modelFallbackReason' | 'parentId' | 'childId' | 'spawnMode' | 'agent' | 'status' | 'afterFingerprint' | 'changedPaths' | 'createdAt' | 'activatedAt' | 'sealedAt' | 'consumedAt'>,
+  input: Omit<DelegationReceipt, 'id' | 'requestedModel' | 'requestedReasoningEffort' | 'actualModel' | 'actualReasoningEffort' | 'modelFallbackReason' | 'reasoningEffortFallbackReason' | 'parentId' | 'childId' | 'spawnMode' | 'agent' | 'status' | 'afterFingerprint' | 'changedPaths' | 'createdAt' | 'activatedAt' | 'sealedAt' | 'consumedAt'> & Readonly<{ requestedModel: string; requestedReasoningEffort: string }>,
   options: { id?: () => string; now?: () => string } = {}
 ): DelegationReceipt {
   return Object.freeze({
     ...input,
     id: (options.id ?? randomUUID)(),
     actualModel: null,
+    actualReasoningEffort: null,
     modelFallbackReason: null,
+    reasoningEffortFallbackReason: null,
     parentId: null,
     childId: null,
     spawnMode: null,
@@ -80,7 +86,9 @@ function activateDelegation(
     parentId: string;
     spawnMode: string;
     actualModel?: string;
+    actualReasoningEffort?: string;
     modelFallbackReason?: string;
+    reasoningEffortFallbackReason?: string;
   }>,
   options: { now?: () => string } = {}
 ): ReceiptResult {
@@ -92,10 +100,29 @@ function activateDelegation(
     return fail('DELEGATION_IDENTITY_INVALID', 'native parent/child identity does not match the prepared delegation');
   }
   if (event.spawnMode !== 'fresh') return fail('DELEGATION_FORK_FORBIDDEN', `spawn mode '${event.spawnMode}' is not fresh`);
-  const actualModel = event.actualModel ?? null;
-  if (actualModel && receipt.requestedModel && actualModel !== receipt.requestedModel && !event.modelFallbackReason) {
+  const actualModel = event.actualModel;
+  if (!actualModel || actualModel.trim() !== actualModel) {
+    return fail('DELEGATION_MODEL_IDENTITY_MISSING', 'native start event must provide a non-empty actual model identity');
+  }
+  if (actualModel !== receipt.requestedModel && (!event.modelFallbackReason || event.modelFallbackReason.trim() === '')) {
     return fail('DELEGATION_MODEL_FALLBACK_UNRECORDED', 'actual model differs from requested model without a fallback reason');
   }
+  const actualReasoningEffort = event.actualReasoningEffort;
+  if (!actualReasoningEffort || actualReasoningEffort.trim() !== actualReasoningEffort) {
+    return fail('DELEGATION_REASONING_EFFORT_MISSING', 'native start event must provide a non-empty actual reasoning effort');
+  }
+  if (
+    actualReasoningEffort !== receipt.requestedReasoningEffort
+    && (!event.reasoningEffortFallbackReason || event.reasoningEffortFallbackReason.trim() === '')
+  ) {
+    return fail('DELEGATION_REASONING_EFFORT_FALLBACK_UNRECORDED', 'actual reasoning effort differs from requested effort without a fallback reason');
+  }
+  if (actualModel === receipt.requestedModel && event.modelFallbackReason) {
+    return fail('DELEGATION_MODEL_FALLBACK_INVALID', 'model fallback reason is only valid when actual model differs');
+  }
+  if (actualReasoningEffort === receipt.requestedReasoningEffort && event.reasoningEffortFallbackReason) {
+    return fail('DELEGATION_REASONING_EFFORT_FALLBACK_INVALID', 'reasoning-effort fallback reason is only valid when actual effort differs');
+  }
   return { ok: true, receipt: Object.freeze({
     ...receipt,
     status: 'activated',
@@ -103,7 +130,9 @@ function activateDelegation(
     childId: event.childId,
     spawnMode: event.spawnMode,
     actualModel,
+    actualReasoningEffort,
     modelFallbackReason: event.modelFallbackReason ?? null,
+    reasoningEffortFallbackReason: event.reasoningEffortFallbackReason ?? null,
     activatedAt: (options.now ?? (() => new Date().toISOString()))()
   }) };
 }

package/lib/task/events.ts

@@ -21,7 +21,10 @@ import type { ReviewStage } from './ledger.ts';
 import { parseReviewSummary } from './review-artifacts.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import { findSectionHeading } from './sections.ts';
-import { completeOrchestrationStage, validateOrchestrationStage } from './orchestration.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';
 
@@ -40,15 +43,19 @@ 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' | '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;
@@ -64,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'] }
 };
@@ -261,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 });
@@ -334,20 +341,27 @@ function applyTaskEvent(request: TaskEventRequest, options: TaskWriteOptions = {
     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 });
-  if (eventIdentity.phase === 'completed' && !normalized.dryRun && eventIdentity.family !== 'manual-validation') {
+  let orchestrationCompletion: OrchestrationStageCompletion | null = null;
+  if (eventIdentity.phase === 'completed' && eventIdentity.family !== 'manual-validation') {
     const orchestrationStage = eventIdentity.family === 'analyze' ? 'analysis' : eventIdentity.family;
-    const provenance = validateOrchestrationStage(normalized.taskRef, {
-      stage: orchestrationStage,
-      round: normalized.round!,
-      artifact: normalized.artifact!,
-      role: eventIdentity.family.startsWith('review-') ? 'reviewer' : 'executor'
+    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 (provenance.status === 'failed' || provenance.status === 'paused') {
+    if (!execution.ok) {
       return failed(normalized, {
         code: 'EVENT_TRANSITION_INVALID',
-        message: provenance.error?.message ?? provenance.run?.pause?.message ?? 'orchestration provenance validation failed'
+        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)(); }
@@ -384,19 +398,25 @@ 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 (eventIdentity.phase === 'completed' && !normalized.dryRun && eventIdentity.family !== 'manual-validation') {
-    const orchestrationStage = eventIdentity.family === 'analyze' ? 'analysis' : eventIdentity.family;
-    const orchestration = completeOrchestrationStage(normalized.taskRef, {
-      stage: orchestrationStage,
-      round: normalized.round!,
-      artifact: normalized.artifact!,
-      agent: normalized.agent
-    }, { repoRoot: options.repoRoot });
-    if (orchestration.status === 'failed' || orchestration.status === 'paused') {
+  if (!normalized.dryRun && orchestrationCompletion) {
+    try {
+      (options.commitOrchestrationCompletion ?? commitOrchestrationStageCompletion)(orchestrationCompletion);
+    } catch (error) {
       return failed(normalized, {
-        code: 'EVENT_TRANSITION_INVALID',
-        message: orchestration.error?.message ?? orchestration.run?.pause?.message ?? 'orchestration provenance validation failed'
-      }, { 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 });
+        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 {
@@ -410,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,
@@ -425,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 };