pi-background-tasks 0.7.6 → 0.9.0

package/src/core/fusion/orchestrator.ts

@@ -1,6 +1,6 @@
 import { randomBytes as nodeRandomBytes } from 'node:crypto';
 import { parseJsonText } from '../common.js';
-import { FusionBudget, assertChildOutputWithinContract } from './budget.js';
+import { FUSION_BUDGET_POLICY, FusionBudget, assertChildOutputWithinContract } from './budget.js';
 import {
   FusionArtifactStore,
   type CreateFusionArtifactStoreOptions,
@@ -13,10 +13,6 @@ import {
 } from './evaluation.js';
 import { FusionChildRunError, runPiChild, type RunPiChildOptions } from './pi-child.js';
 import {
-  FUSION_CANDIDATE_SYSTEM_PROMPT,
-  FUSION_EVALUATION_REPAIR_SYSTEM_PROMPT,
-  FUSION_EVALUATOR_SYSTEM_PROMPT,
-  FUSION_MERGER_SYSTEM_PROMPT,
   buildBlindEvaluationInput,
   buildCandidatePrompt,
   buildEvaluationPrompt,
@@ -26,10 +22,18 @@ import {
   type AnonymousFusionCandidate,
 } from './prompts.js';
 import {
+  FUSION_BRAINSTORM_WORKFLOW,
+  resolveWorkflowCapability,
+  type FusionWorkflowProfile,
+} from './workflows.js';
+import {
+  FUSION_DEFAULT_CAPABILITY,
   FUSION_RESULT_SCHEMA_VERSION,
   FusionError,
   addFusionUsage,
   createEmptyFusionUsage,
+  type FusionCalibrationViolation,
+  type FusionCapability,
   type FusionCanonicalInputV3,
   type FusionCandidateId,
   type FusionContextOmissionLedgerV2,
@@ -61,6 +65,9 @@ export interface FusionWorkflowInput {
   contextLedger: FusionContextOmissionLedgerV2;
   config: FusionModelConfigV1;
   models: ResolvedFusionModels;
+  candidateCapability?: FusionCapability | undefined;
+  /** Stage framing and capability policy. Defaults to the brainstorm workflow. */
+  profile?: FusionWorkflowProfile | undefined;
   signal?: AbortSignal | undefined;
   onProgress?: FusionProgressSink | undefined;
 }
@@ -178,21 +185,25 @@ function childOptions(
   model: ResolvedFusionModel,
   stage: FusionStage,
   attempt: number,
+  capability: FusionCapability,
   systemPrompt: string,
   userPrompt: string,
   signal: AbortSignal,
   slot?: CandidateSlot,
+  toolCallLogPath?: string,
 ): RunPiChildOptions {
   const out: RunPiChildOptions = {
     stage,
     attempt,
     cwd: input.cwd,
     model,
+    capability,
     systemPrompt,
     userPrompt,
     signal,
   };
   if (slot !== undefined) out.slot = slot;
+  if (toolCallLogPath !== undefined) out.toolCallLogPath = toolCallLogPath;
   return out;
 }
 
@@ -323,17 +334,29 @@ export class FusionOrchestrator {
   }
 
   async run(input: FusionWorkflowInput): Promise<FusionRunResult> {
+    const profile = input.profile ?? FUSION_BRAINSTORM_WORKFLOW;
+    // Workflow policy, not caller input: a fixed-capability workflow rejects each
+    // other capability here, before a single child exists, rather than silently
+    // substituting its own and running a review that never read the code.
+    const candidateCapability = resolveWorkflowCapability(profile, input.candidateCapability);
     const storeOptions: CreateFusionArtifactStoreOptions = {
       cwd: input.cwd,
+      profile,
       source: input.source,
       config: input.config,
       models: input.models,
+      capabilities: {
+        candidate: candidateCapability,
+        evaluation: FUSION_DEFAULT_CAPABILITY,
+        merge: FUSION_DEFAULT_CAPABILITY,
+      },
     };
     if (input.sessionId !== undefined) storeOptions.sessionId = input.sessionId;
     if (this.now !== undefined) storeOptions.now = this.now;
     const store = await this.createArtifactStore(storeOptions);
     input.onProgress?.({ type: 'state', state: 'initializing' });
     const usage = createEmptyFusionUsage();
+    const calibrationWarnings: FusionCalibrationViolation[] = [];
     try {
       await store.writeCanonicalInput(input.canonicalInputSerialized);
       await store.writeContextLedger(input.contextLedger);
@@ -342,6 +365,8 @@ export class FusionOrchestrator {
       const budget = new FusionBudget(
         input.models,
         input.canonicalInput.conversation_projection.policy.id,
+        candidateCapability,
+        profile,
       );
       const budgetPlan = budget.plan(input.canonicalInput);
       await store.writeBudgetPlan(budgetPlan);
@@ -355,7 +380,15 @@ export class FusionOrchestrator {
       }
       await store.transition('candidates_running');
       input.onProgress?.({ type: 'state', state: 'candidates_running' });
-      const candidateResults = await this.runCandidates(input, store, usage, budget);
+      const candidateResults = await this.runCandidates(
+        input,
+        store,
+        usage,
+        budget,
+        calibrationWarnings,
+        profile,
+        candidateCapability,
+      );
       await store.transition('candidates_complete');
       input.onProgress?.({ type: 'state', state: 'candidates_complete' });
 
@@ -366,7 +399,15 @@ export class FusionOrchestrator {
 
       await store.transition('evaluating');
       input.onProgress?.({ type: 'state', state: 'evaluating' });
-      const evaluation = await this.runEvaluation(input, store, usage, blindInput, budget);
+      const evaluation = await this.runEvaluation(
+        input,
+        store,
+        usage,
+        blindInput,
+        budget,
+        calibrationWarnings,
+        profile,
+      );
       await store.writeEvaluationJson(evaluation);
       await store.transition('evaluation_complete');
       input.onProgress?.({ type: 'state', state: 'evaluation_complete' });
@@ -375,7 +416,7 @@ export class FusionOrchestrator {
       input.onProgress?.({ type: 'state', state: 'merging' });
       const mergeInput = buildMergeInput(input.canonicalInput, shuffled.candidates, evaluation);
       const mergePrompt = buildMergePrompt(mergeInput);
-      budget.assertStagePrompt('merge', FUSION_MERGER_SYSTEM_PROMPT, mergePrompt);
+      budget.assertStagePrompt('merge', profile.mergerSystemPrompt, mergePrompt);
       input.onProgress?.({ type: 'merge_started' });
       const merged = await this.runChildWithRetry(
         input,
@@ -383,14 +424,26 @@ export class FusionOrchestrator {
         usage,
         input.models.merger,
         'merge',
-        FUSION_MERGER_SYSTEM_PROMPT,
+        profile.mergerSystemPrompt,
         mergePrompt,
         input.signal ?? new AbortController().signal,
+        // Stage policy, not caller input: evaluator and merger are always reasoning-only.
+        FUSION_DEFAULT_CAPABILITY,
         undefined,
         'md',
       );
       addFusionUsage(usage, merged.usage);
       await store.recordChildAttempt({ result: merged, prompt: mergePrompt, responseKind: 'md' });
+      await this.recordCalibrationObservation(
+        input,
+        store,
+        budget,
+        calibrationWarnings,
+        'merge',
+        profile.mergerSystemPrompt,
+        mergePrompt,
+        merged,
+      );
       assertChildOutputWithinContract('merge', merged.text);
       await store.writeMerged(merged.text);
       await store.setUsage(usage);
@@ -401,6 +454,7 @@ export class FusionOrchestrator {
         details: {
           schema_version: FUSION_RESULT_SCHEMA_VERSION,
           run_id: store.runId,
+          workflow: profile.id,
           source: input.source,
           status: 'completed',
           artifact_dir: store.artifactDir,
@@ -409,6 +463,14 @@ export class FusionOrchestrator {
             .snapshot()
             .attempts.filter((attempt) => attempt.stage === 'evaluation').length,
           usage,
+          budget: {
+            policy_id: FUSION_BUDGET_POLICY.id,
+            calibration_version: budgetPlan.policy.calibration_version,
+            route_table: budget.routes,
+            rate_sources: budget.resultRateSources,
+            unknown_provider_warnings: budget.unknownProviderWarnings,
+            calibration_warnings: calibrationWarnings,
+          },
         },
       };
     } catch (error) {
@@ -446,14 +508,18 @@ export class FusionOrchestrator {
     store: FusionArtifactStore,
     usage: FusionUsage,
     budget: FusionBudget,
+    calibrationWarnings: FusionCalibrationViolation[],
+    profile: FusionWorkflowProfile,
+    candidateCapability: FusionCapability,
   ): Promise<readonly CandidateResult[]> {
     const controller = new AbortController();
     const abortListener = () => controller.abort();
     input.signal?.addEventListener('abort', abortListener, { once: true });
     if (input.signal?.aborted) controller.abort();
+    const systemPrompt = profile.candidateSystemPrompt(candidateCapability);
     const prompt = buildCandidatePrompt(input.canonicalInput);
     for (const slot of [1, 2, 3] as const) {
-      budget.assertStagePrompt('candidate', FUSION_CANDIDATE_SYSTEM_PROMPT, prompt, slot);
+      budget.assertStagePrompt('candidate', systemPrompt, prompt, slot);
     }
     let primaryError: unknown;
     let completed = 0;
@@ -473,13 +539,25 @@ export class FusionOrchestrator {
           usage,
           model,
           'candidate',
-          FUSION_CANDIDATE_SYSTEM_PROMPT,
+          systemPrompt,
           prompt,
           controller.signal,
+          candidateCapability,
           slot,
           'md',
         ).then(async (result) => {
           await store.recordChildAttempt({ result, prompt, responseKind: 'md' });
+          await this.recordCalibrationObservation(
+            input,
+            store,
+            budget,
+            calibrationWarnings,
+            'candidate',
+            systemPrompt,
+            prompt,
+            result,
+            slot,
+          );
           // The response is durable before the contract check, so an oversized
           // answer is preserved as evidence rather than lost.
           assertChildOutputWithinContract('candidate', result.text);
@@ -516,10 +594,22 @@ export class FusionOrchestrator {
     usage: FusionUsage,
     blindInput: Parameters<typeof buildEvaluationPrompt>[0],
     budget: FusionBudget,
+    calibrationWarnings: FusionCalibrationViolation[],
+    profile: FusionWorkflowProfile,
   ): Promise<FusionEvaluationV1> {
     const firstPrompt = buildEvaluationPrompt(blindInput);
-    budget.assertStagePrompt('evaluation', FUSION_EVALUATOR_SYSTEM_PROMPT, firstPrompt);
-    const first = await this.runEvaluationAttempt(input, store, usage, firstPrompt, 1, false);
+    budget.assertStagePrompt('evaluation', profile.evaluatorSystemPrompt, firstPrompt);
+    const first = await this.runEvaluationAttempt(
+      input,
+      store,
+      usage,
+      budget,
+      calibrationWarnings,
+      firstPrompt,
+      1,
+      false,
+      profile,
+    );
     if (first.evaluation !== undefined) return first.evaluation;
     const errors = boundedEvaluationErrors(first.errors);
     input.onProgress?.({ type: 'evaluation_retry', errors });
@@ -531,10 +621,20 @@ export class FusionOrchestrator {
     });
     budget.assertStagePrompt(
       'evaluation_repair',
-      FUSION_EVALUATION_REPAIR_SYSTEM_PROMPT,
+      profile.evaluationRepairSystemPrompt,
+      repairPrompt,
+    );
+    const second = await this.runEvaluationAttempt(
+      input,
+      store,
+      usage,
+      budget,
+      calibrationWarnings,
       repairPrompt,
+      2,
+      true,
+      profile,
     );
-    const second = await this.runEvaluationAttempt(input, store, usage, repairPrompt, 2, true);
     if (second.evaluation !== undefined) return second.evaluation;
     throw new FusionError(
       `evaluation schema repair failed: ${formatEvaluationErrors(second.errors)}`,
@@ -550,14 +650,17 @@ export class FusionOrchestrator {
     input: FusionWorkflowInput,
     store: FusionArtifactStore,
     usage: FusionUsage,
+    budget: FusionBudget,
+    calibrationWarnings: FusionCalibrationViolation[],
     prompt: string,
     attempt: 1 | 2,
     repair: boolean,
+    profile: FusionWorkflowProfile,
   ): Promise<EvaluationAttemptResult> {
     input.onProgress?.({ type: 'evaluation_started', attempt, repair });
     const systemPrompt = repair
-      ? FUSION_EVALUATION_REPAIR_SYSTEM_PROMPT
-      : FUSION_EVALUATOR_SYSTEM_PROMPT;
+      ? profile.evaluationRepairSystemPrompt
+      : profile.evaluatorSystemPrompt;
     const result = await this.runChildWithRetry(
       input,
       store,
@@ -567,12 +670,24 @@ export class FusionOrchestrator {
       systemPrompt,
       prompt,
       input.signal ?? new AbortController().signal,
+      // Stage policy, not caller input: evaluator and merger are always reasoning-only.
+      FUSION_DEFAULT_CAPABILITY,
       undefined,
       'txt',
       attempt,
     );
     addFusionUsage(usage, result.usage);
     await store.recordChildAttempt({ result, prompt, responseKind: 'txt' });
+    await this.recordCalibrationObservation(
+      input,
+      store,
+      budget,
+      calibrationWarnings,
+      'evaluation',
+      systemPrompt,
+      prompt,
+      result,
+    );
     await store.setUsage(usage);
     // Bound the evaluator output before it can be embedded in a repair prompt.
     assertChildOutputWithinContract('evaluation', result.text);
@@ -580,6 +695,41 @@ export class FusionOrchestrator {
     return { result, evaluation: parsed.evaluation, errors: parsed.errors };
   }
 
+  private async recordCalibrationObservation(
+    input: FusionWorkflowInput,
+    store: FusionArtifactStore,
+    budget: FusionBudget,
+    calibrationWarnings: FusionCalibrationViolation[],
+    stage: FusionStage,
+    systemPrompt: string,
+    userPrompt: string,
+    result: FusionChildRunResult,
+    slot?: CandidateSlot,
+  ): Promise<void> {
+    const violation = budget.calibrationViolationForCompletedChild(
+      stage,
+      systemPrompt,
+      userPrompt,
+      result,
+      slot,
+    );
+    if (violation === undefined) return;
+    calibrationWarnings.push(violation);
+    let artifact = 'calibration-violation artifact was not written';
+    try {
+      const ref = await store.recordCalibrationViolation({
+        stage,
+        attempt: result.attempt,
+        violation,
+        ...(slot === undefined ? {} : { slot }),
+      });
+      artifact = ref.path;
+    } catch (error) {
+      artifact = `calibration-violation artifact write failed: ${errorText(error)}`;
+    }
+    input.onProgress?.({ type: 'calibration_warning', warning: violation, artifact });
+  }
+
   private async runChildWithRetry(
     input: FusionWorkflowInput,
     store: FusionArtifactStore,
@@ -589,6 +739,7 @@ export class FusionOrchestrator {
     systemPrompt: string,
     userPrompt: string,
     signal: AbortSignal,
+    capability: FusionCapability,
     slot: CandidateSlot | undefined,
     responseKind: 'md' | 'txt',
     fixedAttempt?: 1 | 2,
@@ -598,9 +749,24 @@ export class FusionOrchestrator {
       if (stage === 'candidate' && slot !== undefined) {
         input.onProgress?.({ type: 'candidate_started', slot, attempt: logicalAttempt });
       }
+      const toolCallLogPath =
+        capability !== 'reason'
+          ? store.childToolCallLogPath(stage, slot, logicalAttempt)
+          : undefined;
       try {
         return await this.childRunner(
-          childOptions(input, model, stage, logicalAttempt, systemPrompt, userPrompt, signal, slot),
+          childOptions(
+            input,
+            model,
+            stage,
+            logicalAttempt,
+            capability,
+            systemPrompt,
+            userPrompt,
+            signal,
+            slot,
+            toolCallLogPath,
+          ),
         );
       } catch (error) {
         if (!signal.aborted && retryableSpawn(error, launchTry) && launchTry === 1) continue;