pi-background-tasks 1.0.6 → 2.0.0

package/src/core/fusion/artifacts.ts

@@ -6,7 +6,9 @@ import { sanitizePathSegment } from '../common.js';
 import { replaceFileDurable } from '../durable-fs.js';
 import {
   EMPTY_FUSION_USAGE,
+  FUSION_COMMITTED_RESULT_SCHEMA_VERSION,
   FUSION_MANIFEST_SCHEMA_VERSION,
+  FUSION_VALIDATE_CANDIDATE_CONTRACT_EVENT_SCHEMA_VERSION,
   FusionError,
   cloneFusionUsage,
   type FusionArtifactManifest,
@@ -18,6 +20,8 @@ import {
   type FusionCapability,
   type FusionContextOmissionLedgerV2,
   type FusionChildRunResult,
+  type FusionCommittedResultV1,
+  type FusionResultDetails,
   type FusionModelConfigV1,
   type FusionSource,
   type FusionStage,
@@ -56,8 +60,17 @@ interface MutableFusionArtifactManifest {
     evaluation: FusionCapability;
     merge: FusionCapability;
   };
-  context: { kind: import('./types.js').FusionContextKind; policy_id: string; ledger_artifact?: string; source_policy_artifact?: string };
-  tool_policy: { candidate_tools: readonly string[]; evaluation_tools: readonly []; merge_tools: readonly [] };
+  context: {
+    kind: import('./types.js').FusionContextKind;
+    policy_id: string;
+    ledger_artifact?: string;
+    source_policy_artifact?: string;
+  };
+  tool_policy: {
+    candidate_tools: readonly string[];
+    evaluation_tools: readonly [];
+    merge_tools: readonly [];
+  };
   usage: FusionUsage;
   attempts: FusionAttemptArtifactRecord[];
   artifacts: Record<string, FusionArtifactRef>;
@@ -83,14 +96,39 @@ export interface CreateFusionArtifactStoreOptions {
 
 export interface RecordFusionChildAttemptInput {
   result: FusionChildRunResult;
+  systemPrompt: string;
   prompt: string;
   responseKind: 'md' | 'txt';
 }
 
+export type RecordValidationCandidateContractEventInput =
+  | {
+      candidateId: FusionCandidateId;
+      slot: 1 | 2 | 3;
+      status: 'normalized';
+      detail: {
+        normalization: 'markdown_json_fence' | 'prose_then_markdown_json_fence';
+        original_sha256: string;
+        forwarded_sha256: string;
+        warning: string;
+      };
+    }
+  | {
+      candidateId: FusionCandidateId;
+      slot: 1 | 2 | 3;
+      status: 'dropped';
+      detail: {
+        response_sha256: string;
+        error: string;
+        warning: string;
+      };
+    };
+
 export interface RecordFusionFailedAttemptInput {
   stage: FusionStage;
   slot?: 1 | 2 | 3;
   attempt: number;
+  systemPrompt: string;
   prompt: string;
   events: Buffer;
   partialResponse: Buffer;
@@ -180,7 +218,11 @@ function publicManifest(manifest: MutableFusionArtifactManifest): FusionArtifact
     models: manifest.models,
     capabilities: manifest.capabilities,
     context: { ...manifest.context },
-    tool_policy: { candidate_tools: [...manifest.tool_policy.candidate_tools], evaluation_tools: [], merge_tools: [] },
+    tool_policy: {
+      candidate_tools: [...manifest.tool_policy.candidate_tools],
+      evaluation_tools: [],
+      merge_tools: [],
+    },
     usage: cloneFusionUsage(manifest.usage),
     attempts: [...manifest.attempts],
     artifacts: { ...manifest.artifacts },
@@ -269,8 +311,18 @@ export class FusionArtifactStore {
         evaluation: 'reason',
         merge: 'reason',
       },
-      context: { kind: profile.contextKind, policy_id: profile.contextKind === 'session_projection' ? 'fusion-session-projection-v1' : 'fusion-clean-task-v1' },
-      tool_policy: { candidate_tools: profile.candidateTools, evaluation_tools: [], merge_tools: [] },
+      context: {
+        kind: profile.contextKind,
+        policy_id:
+          profile.contextKind === 'session_projection'
+            ? 'fusion-session-projection-v1'
+            : 'fusion-clean-task-v1',
+      },
+      tool_policy: {
+        candidate_tools: profile.candidateTools,
+        evaluation_tools: [],
+        merge_tools: [],
+      },
       usage: cloneFusionUsage(EMPTY_FUSION_USAGE),
       attempts: [],
       artifacts: {},
@@ -313,11 +365,18 @@ export class FusionArtifactStore {
           childCreated: false,
         });
       }
-      if (to === 'completed' && manifest.artifacts['merged.md'] === undefined) {
-        throw new FusionError('fusion cannot complete before merged.md is durable', {
-          code: 'state_transition_invalid',
-          childCreated: false,
-        });
+      if (
+        to === 'completed' &&
+        (manifest.artifacts['merged.md'] === undefined ||
+          manifest.artifacts['result.json'] === undefined)
+      ) {
+        throw new FusionError(
+          'fusion cannot complete before merged.md and result.json are durable',
+          {
+            code: 'state_transition_invalid',
+            childCreated: false,
+          },
+        );
       }
       manifest.state = to;
     });
@@ -377,8 +436,21 @@ export class FusionArtifactStore {
     await this.writeArtifact('evaluation.json', canonicalJson(value));
   }
 
-  async writeMerged(text: string): Promise<void> {
-    await this.writeArtifact('merged.md', text);
+  async writeMerged(text: string): Promise<FusionArtifactRef> {
+    return this.writeArtifact('merged.md', text);
+  }
+
+  async writeCommittedResult(
+    merged: FusionArtifactRef,
+    details: FusionResultDetails,
+  ): Promise<FusionArtifactRef> {
+    const value: FusionCommittedResultV1 = {
+      schema_version: FUSION_COMMITTED_RESULT_SCHEMA_VERSION,
+      run_id: this.runId,
+      merged,
+      details,
+    };
+    return this.writeArtifact('result.json', `${canonicalJson(value)}\n`);
   }
 
   async writeError(state: Exclude<FusionTerminalState, 'completed'>, error: string): Promise<void> {
@@ -398,6 +470,7 @@ export class FusionArtifactStore {
 
   async recordChildAttempt(input: RecordFusionChildAttemptInput): Promise<void> {
     const prefix = attemptPrefix(input.result.stage, input.result.slot, input.result.attempt);
+    await this.writeArtifact(`${prefix}.system-prompt.txt`, input.systemPrompt);
     const promptRef = await this.writeArtifact(`${prefix}.prompt.txt`, input.prompt);
     const eventsRef = await this.writeArtifact(`${prefix}.events.jsonl`, input.result.events);
     const stderrRef = await this.writeArtifact(`${prefix}.stderr.txt`, input.result.stderr);
@@ -439,11 +512,31 @@ export class FusionArtifactStore {
     violation: FusionCalibrationViolation;
   }): Promise<FusionArtifactRef> {
     const prefix = attemptPrefix(input.stage, input.slot, input.attempt);
-    return this.writeArtifact(calibrationViolationName(prefix), `${canonicalJson(input.violation)}\n`);
+    return this.writeArtifact(
+      calibrationViolationName(prefix),
+      `${canonicalJson(input.violation)}\n`,
+    );
+  }
+
+  async recordValidationCandidateContractEvent(
+    input: RecordValidationCandidateContractEventInput,
+  ): Promise<FusionArtifactRef> {
+    const name = `candidate-${String(input.slot)}.output-contract-${input.status}.json`;
+    return this.writeArtifact(
+      name,
+      `${canonicalJson({
+        schema_version: FUSION_VALIDATE_CANDIDATE_CONTRACT_EVENT_SCHEMA_VERSION,
+        ...input.detail,
+        candidate_id: input.candidateId,
+        slot: input.slot,
+        status: input.status,
+      })}\n`,
+    );
   }
 
   async recordFailedAttempt(input: RecordFusionFailedAttemptInput): Promise<void> {
     const prefix = attemptPrefix(input.stage, input.slot, input.attempt);
+    await this.writeArtifact(`${prefix}.system-prompt.txt`, input.systemPrompt);
     const promptRef = await this.writeArtifact(`${prefix}.prompt.txt`, input.prompt);
     const eventsRef = await this.writeArtifact(`${prefix}.events.jsonl`, input.events);
     const stderrRef = await this.writeArtifact(`${prefix}.stderr.txt`, input.stderr);

package/src/core/fusion/budget.ts

@@ -1122,7 +1122,13 @@ export class FusionBudget {
     const inputSegments = [knownTextSegment(systemPrompt), knownTextSegment(userPrompt)];
     const promptUtf8Bytes = inputSegments.reduce((sum, segment) => sum + segment.bytes, 0);
     const estimate = estimateRouteInput(route, inputSegments);
-    const billedInput = result.usage.input + result.usage.cacheRead + result.usage.cacheWrite;
+    // The forecast is a one-request admission estimate. Compare it only with
+    // the first provider request, never with aggregate agent-loop/cache usage.
+    // Custom child runners predating this observation field remain compatible,
+    // but cannot produce a calibration verdict without like-for-like evidence.
+    const observedUsage = result.firstRequestUsage;
+    if (observedUsage === undefined) return undefined;
+    const billedInput = observedUsage.input + observedUsage.cacheRead + observedUsage.cacheWrite;
     if (billedInput <= estimate.tokens) return undefined;
     const violation: FusionCalibrationViolation = {
       schema_version: FUSION_CALIBRATION_VIOLATION_SCHEMA_VERSION,
@@ -1137,12 +1143,14 @@ export class FusionBudget {
       rate_source: estimate.rateSource,
       prompt_utf8_bytes: promptUtf8Bytes,
       prompt_sha256: sha256Hex(`${systemPrompt}\u0000${userPrompt}`),
+      observation_scope: 'first_provider_request',
+      provider_request_count: result.providerRequestCount ?? 1,
       forecast_input_tokens: estimate.tokens,
       billed_input_tokens: billedInput,
       billed_input_breakdown: {
-        input: result.usage.input,
-        cache_read: result.usage.cacheRead,
-        cache_write: result.usage.cacheWrite,
+        input: observedUsage.input,
+        cache_read: observedUsage.cacheRead,
+        cache_write: observedUsage.cacheWrite,
       },
       under_forecast_tokens: billedInput - estimate.tokens,
       byte_class_breakdown: estimate.byte_class_breakdown,

package/src/core/fusion/evaluation.ts

@@ -525,6 +525,67 @@ export interface ParsedFusionValidationCandidateReport {
   limitations: readonly string[];
 }
 
+export type FusionValidationCandidateNormalization =
+  | 'markdown_json_fence'
+  | 'prose_then_markdown_json_fence';
+
+export interface RecoveredFusionValidationCandidateReport {
+  report: ParsedFusionValidationCandidateReport;
+  /** Bare JSON forwarded to the evaluator after explicit, audited recovery. */
+  response: string;
+  normalization: FusionValidationCandidateNormalization;
+}
+
+/**
+ * Recognize exactly one complete Markdown JSON fence, optionally preceded by a
+ * short prose preamble. This is deliberately narrower than generic substring
+ * extraction: trailing prose, nested fences, unlabelled fences, and oversized
+ * preambles remain contract failures.
+ */
+function fencedValidationCandidateJson(text: string): {
+  payload: string;
+  normalization: FusionValidationCandidateNormalization;
+} | undefined {
+  const trimmed = text.trim();
+  const openingPattern = /```json[ \t]*\r?\n/giu;
+  const openings = [...trimmed.matchAll(openingPattern)];
+  if (openings.length !== 1) return undefined;
+  const opening = openings[0];
+  if (opening === undefined) return undefined;
+  const headerEnd = opening.index + opening[0].length;
+  const closing = trimmed.indexOf('```', headerEnd);
+  if (closing < 0 || trimmed.slice(closing + 3).includes('```')) return undefined;
+  if (trimmed.slice(closing + 3).trim().length > 0) return undefined;
+  const preamble = trimmed.slice(0, opening.index).trim();
+  if (Buffer.byteLength(preamble, 'utf8') > 2_000 || preamble.includes('```')) return undefined;
+  const payload = trimmed.slice(headerEnd, closing).trim();
+  if (payload.length === 0 || payload.includes('```')) return undefined;
+  return {
+    payload,
+    normalization: preamble.length === 0
+      ? 'markdown_json_fence'
+      : 'prose_then_markdown_json_fence',
+  };
+}
+
+/**
+ * Defensive recovery for the one observed contract violation shape. Callers
+ * must persist/surface the returned normalization; this function intentionally
+ * does not make the strict parser permissive.
+ */
+export function recoverFencedFusionValidationCandidateReport(
+  text: string,
+  candidateId: FusionCandidateId,
+): RecoveredFusionValidationCandidateReport | undefined {
+  const recovered = fencedValidationCandidateJson(text);
+  if (recovered === undefined) return undefined;
+  return {
+    report: parseFusionValidationCandidateReport(recovered.payload, candidateId),
+    response: recovered.payload,
+    normalization: recovered.normalization,
+  };
+}
+
 export function parseFusionValidationCandidateReport(text: string, candidateId: FusionCandidateId): ParsedFusionValidationCandidateReport {
   let parsed: unknown;
   try {