pi-background-tasks 1.0.6 → 2.0.0

package/src/core/fusion/orchestrator.ts

@@ -1,4 +1,4 @@
-import { randomBytes as nodeRandomBytes } from 'node:crypto';
+import { createHash, randomBytes as nodeRandomBytes } from 'node:crypto';
 import { canonicalJson } from '../attested-pi-run.js';
 import { parseJsonText } from '../common.js';
 import { FUSION_BUDGET_POLICY, FusionBudget, assertChildOutputWithinContract } from './budget.js';
@@ -11,6 +11,7 @@ import {
   boundedEvaluationErrors,
   formatEvaluationErrors,
   parseFusionValidationCandidateReport,
+  recoverFencedFusionValidationCandidateReport,
   renderValidatedFusionValidationReport,
   validateFusionEvaluation,
   validateFusionFindingAccounting,
@@ -35,6 +36,7 @@ import {
   FUSION_INPUT_SCHEMA_VERSION,
   FUSION_NO_TOOLS_CAPABILITY,
   FUSION_RESULT_SCHEMA_VERSION,
+  FUSION_VALIDATE_CANDIDATE_SCHEMA_VERSION,
   FusionError,
   addFusionUsage,
   createEmptyFusionUsage,
@@ -61,6 +63,12 @@ export type FusionChildRunner = (options: RunPiChildOptions) => Promise<FusionCh
 export type FusionProgressSink = (event: FusionProgressEvent) => void;
 export type FusionRandomBytes = (size: number) => Buffer;
 
+export interface FusionRunReady {
+  runId: string;
+  artifactDir: string;
+  artifactDirAbs: string;
+}
+
 type CandidateSlot = 1 | 2 | 3;
 
 export interface FusionWorkflowInput {
@@ -77,6 +85,12 @@ export interface FusionWorkflowInput {
   profile?: FusionWorkflowProfile | undefined;
   signal?: AbortSignal | undefined;
   onProgress?: FusionProgressSink | undefined;
+  /**
+   * Optional no-child-yet handoff. The orchestrator pauses here after durable
+   * preflight and budget admission, allowing a background registry receipt to
+   * become durable before candidate launch.
+   */
+  onReady?: ((ready: FusionRunReady) => Promise<void>) | undefined;
 }
 
 export interface FusionOrchestratorOptions {
@@ -118,7 +132,8 @@ function hasOnlyKeys(value: Record<string, unknown>, allowed: readonly string[])
 
 function isStrictCleanCanonicalInput(value: unknown): boolean {
   if (!isRecord(value)) return false;
-  if (!hasOnlyKeys(value, ['schema_version', 'workflow', 'cwd', 'request', 'context'])) return false;
+  if (!hasOnlyKeys(value, ['schema_version', 'workflow', 'cwd', 'request', 'context']))
+    return false;
   const request = value['request'];
   if (!isRecord(request)) return false;
   if (!hasOnlyKeys(request, ['source', 'authority', 'text', 'sha256'])) return false;
@@ -129,7 +144,8 @@ function isStrictCleanCanonicalInput(value: unknown): boolean {
   const declaredSources = context['declared_sources'];
   if (!Array.isArray(declaredSources)) return false;
   for (const source of declaredSources) {
-    if (!isRecord(source) || !hasOnlyKeys(source, ['url', 'canonical_url', 'purpose', 'sha256'])) return false;
+    if (!isRecord(source) || !hasOnlyKeys(source, ['url', 'canonical_url', 'purpose', 'sha256']))
+      return false;
   }
   return true;
 }
@@ -169,6 +185,7 @@ function recordFailureInput(
   stage: FusionStage,
   slot: CandidateSlot | undefined,
   attempt: number,
+  systemPrompt: string,
   prompt: string,
   responseKind: 'md' | 'txt',
 ): RecordFusionFailedAttemptInput {
@@ -176,6 +193,7 @@ function recordFailureInput(
     const base: RecordFusionFailedAttemptInput = {
       stage,
       attempt,
+      systemPrompt,
       prompt,
       events: error.events,
       partialResponse: error.response,
@@ -194,6 +212,7 @@ function recordFailureInput(
   const base: RecordFusionFailedAttemptInput = {
     stage,
     attempt,
+    systemPrompt,
     prompt,
     events: Buffer.alloc(0),
     partialResponse: Buffer.alloc(0),
@@ -271,7 +290,10 @@ function parseEvaluationAttempt(
     };
   }
   if (expectedValidationFindings !== undefined) {
-    const accountingErrors = validateEvaluationAccountsForSourceFindings(result.value, expectedValidationFindings);
+    const accountingErrors = validateEvaluationAccountsForSourceFindings(
+      result.value,
+      expectedValidationFindings,
+    );
     if (accountingErrors.length > 0) return { evaluation: undefined, errors: accountingErrors };
   }
   return { evaluation: result.value, errors: [] };
@@ -371,22 +393,135 @@ function anonymousCandidates(
 }
 
 interface ValidationSourceData {
+  candidates: readonly [
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+  ];
   findings: readonly FusionValidationFindingRecord[];
   verified: readonly string[];
   limitations: readonly string[];
 }
 
-function validationSourceData(candidates: readonly [AnonymousFusionCandidate, AnonymousFusionCandidate, AnonymousFusionCandidate]): ValidationSourceData {
+function sha256Text(value: string): string {
+  return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+
+function boundedContractError(error: unknown): string {
+  const value = errorText(error);
+  return value.length <= 1_000 ? value : `${value.slice(0, 999)}…`;
+}
+
+/**
+ * Enforce the validation-candidate contract without making the shared JSON
+ * parser permissive. A single, tightly recognized fenced response is recovered
+ * with a durable warning. One irrecoverable minority report is represented as
+ * an explicit limitation; two or more still fail the workflow loudly.
+ */
+async function prepareValidationSourceData(
+  candidates: readonly [
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+  ],
+  anonymousMap: Record<FusionCandidateId, CandidateSlot>,
+  store: FusionArtifactStore,
+): Promise<ValidationSourceData> {
+  const prepared = candidates.map((candidate) => ({ ...candidate })) as [
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+  ];
   const findings: FusionValidationFindingRecord[] = [];
   const verified: string[] = [];
   const limitations: string[] = [];
-  for (const candidate of candidates) {
-    const report = parseFusionValidationCandidateReport(candidate.response, candidate.candidate_id);
-    findings.push(...report.findings);
-    verified.push(...report.verified);
+  let normalizationCount = 0;
+  const failures: Array<{ candidate: AnonymousFusionCandidate; error: string }> = [];
+
+  for (const candidate of prepared) {
+    try {
+      const report = parseFusionValidationCandidateReport(
+        candidate.response,
+        candidate.candidate_id,
+      );
+      findings.push(...report.findings);
+      verified.push(...report.verified);
+      limitations.push(...report.limitations);
+      continue;
+    } catch (strictError) {
+      try {
+        const recovered = recoverFencedFusionValidationCandidateReport(
+          candidate.response,
+          candidate.candidate_id,
+        );
+        if (recovered === undefined) throw strictError;
+        await store.recordValidationCandidateContractEvent({
+          candidateId: candidate.candidate_id,
+          slot: anonymousMap[candidate.candidate_id],
+          status: 'normalized',
+          detail: {
+            normalization: recovered.normalization,
+            original_sha256: sha256Text(candidate.response),
+            forwarded_sha256: sha256Text(recovered.response),
+            warning:
+              'Candidate output violated the bare-JSON contract; a single complete JSON fence was removed and recorded.',
+          },
+        });
+        candidate.response = recovered.response;
+        findings.push(...recovered.report.findings);
+        verified.push(...recovered.report.verified);
+        limitations.push(...recovered.report.limitations);
+        normalizationCount += 1;
+        continue;
+      } catch (recoveryError) {
+        failures.push({
+          candidate,
+          error: boundedContractError(recoveryError === strictError ? strictError : recoveryError),
+        });
+      }
+    }
+  }
+
+  if (normalizationCount > 0) {
+    limitations.push(
+      `${String(normalizationCount)} validation report${normalizationCount === 1 ? '' : 's'} required audited removal of a Markdown JSON wrapper; JSON content was unchanged.`,
+    );
+  }
+
+  for (const failure of failures) {
+    await store.recordValidationCandidateContractEvent({
+      candidateId: failure.candidate.candidate_id,
+      slot: anonymousMap[failure.candidate.candidate_id],
+      status: 'dropped',
+      detail: {
+        response_sha256: sha256Text(failure.candidate.response),
+        error: failure.error,
+        warning: 'Candidate output could not be parsed under the strict or fenced-JSON contract.',
+      },
+    });
+  }
+  if (failures.length > 1) {
+    throw new FusionError(
+      `fusion_validate cannot continue: ${String(failures.length)} of 3 candidate reports violated the structured-output contract`,
+      { code: 'evaluation_invalid', stage: 'candidate' },
+    );
+  }
+  const failure = failures[0];
+  if (failure !== undefined) {
+    const synthetic = canonicalJson({
+      schema_version: FUSION_VALIDATE_CANDIDATE_SCHEMA_VERSION,
+      findings: [],
+      verified: [],
+      limitations: [
+        'This validation report could not be parsed after strict contract checks; no findings or verification claims from it were included.',
+      ],
+    });
+    failure.candidate.response = synthetic;
+    const report = parseFusionValidationCandidateReport(synthetic, failure.candidate.candidate_id);
     limitations.push(...report.limitations);
   }
-  return { findings, verified, limitations };
+
+  return { candidates: prepared, findings, verified, limitations };
 }
 
 function validateEvaluationAccountsForSourceFindings(
@@ -400,14 +535,18 @@ function validateEvaluationAccountsForSourceFindings(
   }
   const expected = sourceFindings.map((finding) => canonicalJson(finding)).sort();
   const actual = accounting.findings.map((finding) => canonicalJson(finding)).sort();
-  if (expected.length !== actual.length || expected.some((value, index) => value !== actual[index])) {
-    errors.push('validation evaluator validation_accounting.findings must exactly equal host-assigned source findings');
+  if (
+    expected.length !== actual.length ||
+    expected.some((value, index) => value !== actual[index])
+  ) {
+    errors.push(
+      'validation evaluator validation_accounting.findings must exactly equal host-assigned source findings',
+    );
   }
   errors.push(...validateFusionFindingAccounting(accounting));
   return errors;
 }
 
-
 function resolveRunProfile(input: FusionWorkflowInput): FusionWorkflowProfile {
   if (input.profile !== undefined) return fusionWorkflowProfile(input.profile.id);
   const workflow = input.canonicalInput.workflow;
@@ -458,11 +597,17 @@ export class FusionOrchestrator {
         { code: 'orchestration_failed', childCreated: false },
       );
     }
-    if (profile.contextKind === 'clean_task' && !isStrictCleanCanonicalInput(input.canonicalInput)) {
-      throw new FusionError('clean-task fusion input must not carry parent context fields and must match the strict clean canonical shape', {
-        code: 'orchestration_failed',
-        childCreated: false,
-      });
+    if (
+      profile.contextKind === 'clean_task' &&
+      !isStrictCleanCanonicalInput(input.canonicalInput)
+    ) {
+      throw new FusionError(
+        'clean-task fusion input must not carry parent context fields and must match the strict clean canonical shape',
+        {
+          code: 'orchestration_failed',
+          childCreated: false,
+        },
+      );
     }
     const candidateCapability = assertWorkflowCapability(profile, input.candidateCapability);
     const storeOptions: CreateFusionArtifactStoreOptions = {
@@ -483,16 +628,22 @@ export class FusionOrchestrator {
     try {
       serializedParsed = parseJsonText(input.canonicalInputSerialized);
     } catch (error) {
-      throw new FusionError(`fusion canonical input artifact is not valid JSON: ${errorText(error)}`, {
-        code: 'orchestration_failed',
-        childCreated: false,
-      });
+      throw new FusionError(
+        `fusion canonical input artifact is not valid JSON: ${errorText(error)}`,
+        {
+          code: 'orchestration_failed',
+          childCreated: false,
+        },
+      );
     }
     if (canonicalJson(serializedParsed) !== canonicalJson(input.canonicalInput)) {
-      throw new FusionError('fusion canonical input serialized bytes do not match canonical input object', {
-        code: 'orchestration_failed',
-        childCreated: false,
-      });
+      throw new FusionError(
+        'fusion canonical input serialized bytes do not match canonical input object',
+        {
+          code: 'orchestration_failed',
+          childCreated: false,
+        },
+      );
     }
     const store = await this.createArtifactStore(storeOptions);
     input.onProgress?.({ type: 'state', state: 'initializing' });
@@ -502,10 +653,13 @@ export class FusionOrchestrator {
       await store.writeCanonicalInput(input.canonicalInputSerialized);
       if (inputContextKind === 'session_projection') {
         if (input.contextLedger === undefined) {
-          throw new FusionError('session-projection fusion input requires an omission ledger artifact', {
-            code: 'orchestration_failed',
-            childCreated: false,
-          });
+          throw new FusionError(
+            'session-projection fusion input requires an omission ledger artifact',
+            {
+              code: 'orchestration_failed',
+              childCreated: false,
+            },
+          );
         }
         await store.writeContextLedger(input.contextLedger);
       } else if (input.contextLedger !== undefined) {
@@ -543,6 +697,17 @@ export class FusionOrchestrator {
           error: 'fusion budget utilization warning',
         });
       }
+      await input.onReady?.({
+        runId: store.runId,
+        artifactDir: store.artifactDir,
+        artifactDirAbs: store.artifactDirAbs,
+      });
+      if (input.signal?.aborted === true) {
+        throw new FusionError('fusion run cancelled before launch', {
+          code: 'child_cancelled',
+          childCreated: false,
+        });
+      }
       await store.transition('candidates_running');
       input.onProgress?.({ type: 'state', state: 'candidates_running' });
       const candidateResults = await this.runCandidates(
@@ -558,11 +723,17 @@ export class FusionOrchestrator {
       input.onProgress?.({ type: 'state', state: 'candidates_complete' });
 
       const shuffled = anonymousCandidates(candidateResults, shuffledSlots(this.randomBytes));
-      const validationData = profile.id === 'validate' ? validationSourceData(shuffled.candidates) : undefined;
+      // Persist the blind mapping before workflow-specific contract parsing
+      // so a failed validation remains attributable to its durable slot artifact.
       await store.setAnonymousMap(shuffled.map);
+      const validationData =
+        profile.id === 'validate'
+          ? await prepareValidationSourceData(shuffled.candidates, shuffled.map, store)
+          : undefined;
+      const evaluationCandidates = validationData?.candidates ?? shuffled.candidates;
       const blindInput = buildBlindEvaluationInput(
         input.canonicalInput,
-        shuffled.candidates,
+        evaluationCandidates,
         validationData?.findings,
       );
       await store.writeBlindCandidates(buildEvaluationPrompt(blindInput));
@@ -585,7 +756,7 @@ export class FusionOrchestrator {
 
       await store.transition('merging');
       input.onProgress?.({ type: 'state', state: 'merging' });
-      const mergeInput = buildMergeInput(input.canonicalInput, shuffled.candidates, evaluation);
+      const mergeInput = buildMergeInput(input.canonicalInput, evaluationCandidates, evaluation);
       const mergePrompt = buildMergePrompt(mergeInput);
       budget.assertStagePrompt('merge', profile.mergerSystemPrompt, mergePrompt);
       input.onProgress?.({ type: 'merge_started' });
@@ -604,7 +775,12 @@ export class FusionOrchestrator {
         'md',
       );
       addFusionUsage(usage, merged.usage);
-      await store.recordChildAttempt({ result: merged, prompt: mergePrompt, responseKind: 'md' });
+      await store.recordChildAttempt({
+        result: merged,
+        systemPrompt: profile.mergerSystemPrompt,
+        prompt: mergePrompt,
+        responseKind: 'md',
+      });
       await this.recordCalibrationObservation(
         input,
         store,
@@ -620,44 +796,54 @@ export class FusionOrchestrator {
       if (profile.id === 'validate') {
         const accounting = evaluation.validation_accounting;
         if (accounting === undefined) {
-          throw new FusionError('fusion_validate evaluation completed without validation accounting', {
-            code: 'evaluation_invalid',
-            stage: 'merge',
-          });
+          throw new FusionError(
+            'fusion_validate evaluation completed without validation accounting',
+            {
+              code: 'evaluation_invalid',
+              stage: 'merge',
+            },
+          );
         }
         finalMergedText = renderValidatedFusionValidationReport(accounting, validationData);
       }
-      if (finalMergedText !== merged.text) assertChildOutputWithinContract('merge', finalMergedText);
-      await store.writeMerged(finalMergedText);
+      if (finalMergedText !== merged.text)
+        assertChildOutputWithinContract('merge', finalMergedText);
+      const mergedRef = await store.writeMerged(finalMergedText);
       await store.setUsage(usage);
-      await store.transition('completed');
-      input.onProgress?.({ type: 'completed', runId: store.runId, artifactDir: store.artifactDir });
-      return {
-        mergedText: finalMergedText,
-        details: {
-          schema_version: FUSION_RESULT_SCHEMA_VERSION,
-          run_id: store.runId,
-          workflow: profile.id,
-          source: input.source,
-          status: 'completed',
-          artifact_dir: store.artifactDir,
-          context: { kind: inputContextKind, policy_id: input.canonicalInput.context?.policy_id ?? 'fusion-session-projection-v1' },
-          tool_policy: { candidate_tools: profile.candidateTools, evaluation_tools: [], merge_tools: [] },
-          models: store.snapshot().models,
-          evaluator_attempts: store
-            .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,
-          },
+      const details: FusionRunResult['details'] = {
+        schema_version: FUSION_RESULT_SCHEMA_VERSION,
+        run_id: store.runId,
+        workflow: profile.id,
+        source: input.source,
+        status: 'completed',
+        artifact_dir: store.artifactDir,
+        context: {
+          kind: inputContextKind,
+          policy_id: input.canonicalInput.context?.policy_id ?? 'fusion-session-projection-v1',
+        },
+        tool_policy: {
+          candidate_tools: profile.candidateTools,
+          evaluation_tools: [],
+          merge_tools: [],
+        },
+        models: store.snapshot().models,
+        evaluator_attempts: store
+          .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,
         },
       };
+      await store.writeCommittedResult(mergedRef, details);
+      await store.transition('completed');
+      input.onProgress?.({ type: 'completed', runId: store.runId, artifactDir: store.artifactDir });
+      return { mergedText: finalMergedText, details };
     } catch (error) {
       const cancelled =
         input.signal?.aborted === true ||
@@ -729,9 +915,14 @@ export class FusionOrchestrator {
           controller.signal,
           candidateCapability,
           slot,
-          'md',
+          profile.id === 'validate' ? 'txt' : 'md',
         ).then(async (result) => {
-          await store.recordChildAttempt({ result, prompt, responseKind: 'md' });
+          await store.recordChildAttempt({
+            result,
+            systemPrompt,
+            prompt,
+            responseKind: profile.id === 'validate' ? 'txt' : 'md',
+          });
           await this.recordCalibrationObservation(
             input,
             store,
@@ -866,7 +1057,7 @@ export class FusionOrchestrator {
       attempt,
     );
     addFusionUsage(usage, result.usage);
-    await store.recordChildAttempt({ result, prompt, responseKind: 'txt' });
+    await store.recordChildAttempt({ result, systemPrompt, prompt, responseKind: 'txt' });
     await this.recordCalibrationObservation(
       input,
       store,
@@ -943,9 +1134,7 @@ export class FusionOrchestrator {
           ? store.childToolCallLogPath(stage, slot, logicalAttempt)
           : undefined;
       const sourcePolicy =
-        capability === 'research'
-          ? store.sourcePolicyLaunchReference()
-          : undefined;
+        capability === 'research' ? store.sourcePolicyLaunchReference() : undefined;
       try {
         return await this.childRunner(
           childOptions(
@@ -966,7 +1155,15 @@ export class FusionOrchestrator {
         if (!signal.aborted && retryableSpawn(error, launchTry) && launchTry === 1) continue;
         addFailedChildUsage(usage, error);
         await store.recordFailedAttempt(
-          recordFailureInput(error, stage, slot, logicalAttempt, userPrompt, responseKind),
+          recordFailureInput(
+            error,
+            stage,
+            slot,
+            logicalAttempt,
+            systemPrompt,
+            userPrompt,
+            responseKind,
+          ),
         );
         await store.setUsage(usage);
         throw error;

package/src/core/fusion/pi-child.ts

@@ -1440,6 +1440,8 @@ export class FusionPiCompactResultParser {
   ): {
     text: string;
     usage: FusionUsage;
+    firstRequestUsage: FusionUsage;
+    providerRequestCount: number;
     provider: string;
     model: string;
     qualifiedId: string;
@@ -1474,6 +1476,8 @@ export class FusionPiCompactResultParser {
     return {
       text: reconstructFinalText(response, final),
       usage: observed.usage,
+      firstRequestUsage: cloneFusionUsage(parsed.records[0]?.usage ?? createEmptyFusionUsage()),
+      providerRequestCount: parsed.records.length,
       provider: final.provider,
       model: final.model,
       qualifiedId: `${final.provider}/${final.model}`,
@@ -2119,6 +2123,8 @@ export async function runPiChild(options: RunPiChildOptions): Promise<FusionChil
       qualifiedId: parsed.qualifiedId,
       text: parsed.text,
       usage: parsed.usage,
+      firstRequestUsage: parsed.firstRequestUsage,
+      providerRequestCount: parsed.providerRequestCount,
       events: parsed.events,
       stderr: parsed.diagnostics,
       exitCode: close.code,

package/src/core/fusion/prompts.ts

@@ -190,6 +190,7 @@ Return only JSON matching this exact closed schema:
   "limitations": ["non-blank statement of what you could not cover"]
 }
 Use an empty findings array when no issues were found; do not omit verified or limitations.
+Do not wrap the JSON in Markdown fences or prose. Emit exactly one bare JSON object.
 
 Do not inflate severity and do not invent issues to appear thorough. If the work is correct, say so plainly in verified/limitations. A report with no findings that names the evidence behind that conclusion is a valid and valuable result; a padded report is not.