@fitlab-ai/agent-infra 0.9.0 → 0.9.2

package/lib/task/delegation-receipts.ts

@@ -0,0 +1,170 @@
+import { randomUUID } from 'node:crypto';
+
+import type { AgentClientId } from '../agent-clients/types.ts';
+
+type DelegationRole = 'executor' | 'reviewer';
+type DelegationStage = 'analysis' | 'review-analysis' | 'plan' | 'review-plan' | 'code' | 'review-code' | 'commit';
+type DelegationStatus = 'prepared' | 'activated' | 'stage-completed' | 'sealed' | 'consumed' | 'aborted' | 'expired';
+
+type DelegationReceipt = Readonly<{
+  id: string;
+  taskId: string;
+  runId: string;
+  role: DelegationRole;
+  stage: DelegationStage;
+  round: number;
+  artifact: string;
+  client: AgentClientId;
+  requestedModel: string | null;
+  actualModel: string | null;
+  modelFallbackReason: string | null;
+  parentId: string | null;
+  childId: string | null;
+  spawnMode: string | null;
+  agent: string | null;
+  status: DelegationStatus;
+  beforeFingerprint: string;
+  afterFingerprint: string | null;
+  changedPaths: readonly string[];
+  createdAt: string;
+  activatedAt: string | null;
+  sealedAt: string | null;
+  consumedAt: string | null;
+}>;
+
+type ReceiptFailure = Readonly<{ ok: false; code: string; message: string; receipt?: never }>;
+type ReceiptSuccess = Readonly<{ ok: true; receipt: DelegationReceipt; code?: never; message?: never }>;
+type ReceiptResult = ReceiptSuccess | ReceiptFailure;
+
+const MANAGED_AGENTS = {
+  'agent-infra-lifecycle-executor': 'executor',
+  'agent-infra-lifecycle-reviewer': 'reviewer'
+} as const;
+
+function managedDelegationRole(nativeAgent: string): DelegationRole | null {
+  return MANAGED_AGENTS[nativeAgent as keyof typeof MANAGED_AGENTS] ?? null;
+}
+
+function fail(code: string, message: string): ReceiptFailure {
+  return { ok: false, code, message };
+}
+
+function prepareDelegation(
+  input: Omit<DelegationReceipt, 'id' | 'actualModel' | 'modelFallbackReason' | 'parentId' | 'childId' | 'spawnMode' | 'agent' | 'status' | 'afterFingerprint' | 'changedPaths' | 'createdAt' | 'activatedAt' | 'sealedAt' | 'consumedAt'>,
+  options: { id?: () => string; now?: () => string } = {}
+): DelegationReceipt {
+  return Object.freeze({
+    ...input,
+    id: (options.id ?? randomUUID)(),
+    actualModel: null,
+    modelFallbackReason: null,
+    parentId: null,
+    childId: null,
+    spawnMode: null,
+    agent: null,
+    status: 'prepared' as const,
+    afterFingerprint: null,
+    changedPaths: Object.freeze([]),
+    createdAt: (options.now ?? (() => new Date().toISOString()))(),
+    activatedAt: null,
+    sealedAt: null,
+    consumedAt: null
+  });
+}
+
+function activateDelegation(
+  receipt: DelegationReceipt,
+  event: Readonly<{
+    nativeAgent: string;
+    childId: string;
+    parentId: string;
+    spawnMode: string;
+    actualModel?: string;
+    modelFallbackReason?: string;
+  }>,
+  options: { now?: () => string } = {}
+): ReceiptResult {
+  const managedRole = managedDelegationRole(event.nativeAgent);
+  if (!managedRole) return fail('DELEGATION_IGNORED', `subagent '${event.nativeAgent}' is not lifecycle-managed`);
+  if (receipt.status !== 'prepared') return fail('DELEGATION_STATE_INVALID', `delegation ${receipt.id} is ${receipt.status}, expected prepared`);
+  if (managedRole !== receipt.role) return fail('DELEGATION_ROLE_MISMATCH', `managed role ${managedRole} does not match ${receipt.role}`);
+  if (!event.parentId || (receipt.parentId !== null && event.parentId !== receipt.parentId) || !event.childId || event.childId === event.parentId) {
+    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) {
+    return fail('DELEGATION_MODEL_FALLBACK_UNRECORDED', 'actual model differs from requested model without a fallback reason');
+  }
+  return { ok: true, receipt: Object.freeze({
+    ...receipt,
+    status: 'activated',
+    parentId: event.parentId,
+    childId: event.childId,
+    spawnMode: event.spawnMode,
+    actualModel,
+    modelFallbackReason: event.modelFallbackReason ?? null,
+    activatedAt: (options.now ?? (() => new Date().toISOString()))()
+  }) };
+}
+
+function completeDelegationStage(
+  receipt: DelegationReceipt,
+  event: Readonly<{ stage: DelegationStage; round: number; artifact: string; agent: string }>
+): ReceiptResult {
+  if (receipt.status !== 'activated') return fail('DELEGATION_STATE_INVALID', `delegation ${receipt.id} is ${receipt.status}, expected activated`);
+  if (event.stage !== receipt.stage || event.round !== receipt.round || event.artifact !== receipt.artifact) {
+    return fail('DELEGATION_STAGE_MISMATCH', 'stage completion identity does not match the active delegation');
+  }
+  const acceptedAgents = receipt.client === 'claude-code' ? ['claude', 'claude-code'] : [receipt.client];
+  if (!acceptedAgents.includes(event.agent)) {
+    return fail('DELEGATION_AGENT_MISMATCH', `stage agent '${event.agent}' does not match client '${receipt.client}'`);
+  }
+  return { ok: true, receipt: Object.freeze({ ...receipt, status: 'stage-completed', agent: event.agent }) };
+}
+
+function sealDelegation(
+  receipt: DelegationReceipt,
+  event: Readonly<{ childId: string; exitCode: number; afterFingerprint: string; changedPaths: readonly string[] }>,
+  options: { now?: () => string } = {}
+): ReceiptResult {
+  if (receipt.status !== 'stage-completed') return fail('DELEGATION_STATE_INVALID', `delegation ${receipt.id} is ${receipt.status}, expected stage-completed`);
+  if (event.childId !== receipt.childId || event.exitCode !== 0) return fail('DELEGATION_STOP_INVALID', 'native stop identity or exit status is invalid');
+  if (receipt.role === 'reviewer') {
+    const taskRoot = `.agents/workspace/active/${receipt.taskId}/`;
+    const allowed = new Set([
+      `${taskRoot}${receipt.artifact}`,
+      `${taskRoot}task.md`,
+      `${taskRoot}orchestration.json`
+    ]);
+    const disallowed = event.changedPaths.find((entry) => !allowed.has(entry));
+    if (disallowed) return fail('DELEGATION_REVIEWER_WRITE_FORBIDDEN', `reviewer changed forbidden path '${disallowed}'`);
+  }
+  return { ok: true, receipt: Object.freeze({
+    ...receipt,
+    status: 'sealed',
+    afterFingerprint: event.afterFingerprint,
+    changedPaths: Object.freeze([...event.changedPaths]),
+    sealedAt: (options.now ?? (() => new Date().toISOString()))()
+  }) };
+}
+
+function consumeDelegation(receipt: DelegationReceipt, options: { now?: () => string } = {}): ReceiptResult {
+  if (receipt.status === 'consumed') return fail('DELEGATION_REPLAY', `delegation ${receipt.id} was already consumed`);
+  if (receipt.status !== 'sealed') return fail('DELEGATION_STATE_INVALID', `delegation ${receipt.id} is ${receipt.status}, expected sealed`);
+  return { ok: true, receipt: Object.freeze({
+    ...receipt,
+    status: 'consumed',
+    consumedAt: (options.now ?? (() => new Date().toISOString()))()
+  }) };
+}
+
+export {
+  activateDelegation,
+  completeDelegationStage,
+  consumeDelegation,
+  managedDelegationRole,
+  prepareDelegation,
+  sealDelegation
+};
+export type { DelegationReceipt, DelegationRole, DelegationStage, DelegationStatus, ReceiptResult };

package/lib/task/events.ts

@@ -16,8 +16,12 @@ 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 { completeOrchestrationStage, validateOrchestrationStage } from './orchestration.ts';
 import { captureTaskWriteMetadata, writeTask } from './write.ts';
 import type { TaskOperationSummary, TaskWriteErrorCode, TaskWriteOptions } from './write.ts';
 
@@ -35,7 +39,8 @@ 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'
+  | ArtifactErrorCode | TaskWriteErrorCode;
 type TaskEventRequest = {
   taskRef: string; event: TaskEventName | string; agent: string; dryRun?: boolean;
   round?: number; question?: number; artifact?: string; fixFor?: string; implementationInput?: string;
@@ -105,14 +110,80 @@ 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' },
-  'manual-validation': { artifact: 'manual-validation', started: ['code-review'], completed: ['code-review'], target: null, label: 'Complete Manual Validation' }
+  'manual-validation': { artifact: 'manual-validation', started: ['code-review', 'commit'], completed: ['code-review', 'commit'], target: null, label: 'Complete Manual Validation' }
 } 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' };
@@ -256,6 +327,28 @@ 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 });
+  if (eventIdentity.phase === 'completed' && !normalized.dryRun && 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'
+    }, { repoRoot: options.repoRoot });
+    if (provenance.status === 'failed' || provenance.status === 'paused') {
+      return failed(normalized, {
+        code: 'EVENT_TRANSITION_INVALID',
+        message: provenance.error?.message ?? provenance.run?.pause?.message ?? 'orchestration provenance validation failed'
+      }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
+    }
+  }
   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 +384,21 @@ 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') {
+      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 });
+    }
+  }
   return {
     status: result.status, changed: result.changed, event: normalized.event,
     requestRef: normalized.taskRef, taskId: result.taskId, taskMdPath: result.taskMdPath,

package/lib/task/issue-form.ts

@@ -4,6 +4,8 @@ type TaskFields = {
   title: string;
   description: string;
   requirements: string;
+  taskInput: string;
+  taskInputHeading: string;
 };
 
 // Field id -> task value mapping (single source of truth, per HD-1).
@@ -84,6 +86,8 @@ function renderTemplateBody(formText: string, fields: TaskFields): string {
     const value = mapped.trim() === '' ? PLACEHOLDER : mapped;
     sections.push(`### ${label}\n\n${value}`);
   }
+  const taskInput = fields.taskInput.trim() === '' ? PLACEHOLDER : fields.taskInput;
+  sections.push(`### ${fields.taskInputHeading}\n\n${taskInput}`);
   return `${sections.join('\n\n')}\n`;
 }