pi-background-tasks 0.7.7 → 1.0.3

package/src/core/fusion/artifacts.ts

@@ -15,6 +15,7 @@ import {
   type FusionBudgetPlanV1,
   type FusionCalibrationViolation,
   type FusionCandidateId,
+  type FusionCapability,
   type FusionContextOmissionLedgerV2,
   type FusionChildRunResult,
   type FusionModelConfigV1,
@@ -23,14 +24,21 @@ import {
   type FusionState,
   type FusionTerminalState,
   type FusionUsage,
+  type FusionWorkflowId,
   type ResolvedFusionModels,
 } from './types.js';
+import { fusionWorkflowProfile, type FusionWorkflowProfile } from './workflows.js';
 
-const RUN_ID_PATTERN = /^f[0-9a-f]{32}$/;
+/**
+ * Run ids are prefixed by workflow so an artifact directory is self-describing.
+ * The prefix set is closed: an unknown prefix must fail rather than be accepted.
+ */
+const RUN_ID_PATTERN = /^(reason|investigate|research|validate)-[0-9a-f]{32}$/;
 
 interface MutableFusionArtifactManifest {
   schema_version: typeof FUSION_MANIFEST_SCHEMA_VERSION;
   run_id: string;
+  workflow: FusionWorkflowId;
   source: FusionSource;
   state: FusionState;
   created_at: string;
@@ -43,6 +51,13 @@ interface MutableFusionArtifactManifest {
     merger: string;
     thinking_level: string;
   };
+  capabilities: {
+    candidate: FusionCapability;
+    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 [] };
   usage: FusionUsage;
   attempts: FusionAttemptArtifactRecord[];
   artifacts: Record<string, FusionArtifactRef>;
@@ -54,9 +69,15 @@ export interface CreateFusionArtifactStoreOptions {
   cwd: string;
   sessionId?: string | undefined;
   runId?: string | undefined;
+  profile?: FusionWorkflowProfile | undefined;
   source: FusionSource;
   config: FusionModelConfigV1;
   models: ResolvedFusionModels;
+  capabilities?: {
+    candidate: FusionCapability;
+    evaluation: FusionCapability;
+    merge: FusionCapability;
+  };
   now?: () => Date;
 }
 
@@ -83,8 +104,8 @@ export interface RecordFusionFailedAttemptInput {
   usage?: FusionUsage;
 }
 
-function makeRunId(): string {
-  return `f${randomBytes(16).toString('hex')}`;
+function makeRunId(profile: FusionWorkflowProfile): string {
+  return `${profile.runIdPrefix}${randomBytes(16).toString('hex')}`;
 }
 
 function modelsForManifest(models: ResolvedFusionModels): MutableFusionArtifactManifest['models'] {
@@ -149,6 +170,7 @@ function publicManifest(manifest: MutableFusionArtifactManifest): FusionArtifact
   const out: FusionArtifactManifest = {
     schema_version: manifest.schema_version,
     run_id: manifest.run_id,
+    workflow: manifest.workflow,
     source: manifest.source,
     state: manifest.state,
     created_at: manifest.created_at,
@@ -156,6 +178,9 @@ function publicManifest(manifest: MutableFusionArtifactManifest): FusionArtifact
     cwd: manifest.cwd,
     config: manifest.config,
     models: manifest.models,
+    capabilities: manifest.capabilities,
+    context: { ...manifest.context },
+    tool_policy: { candidate_tools: [...manifest.tool_policy.candidate_tools], evaluation_tools: [], merge_tools: [] },
     usage: cloneFusionUsage(manifest.usage),
     attempts: [...manifest.attempts],
     artifacts: { ...manifest.artifacts },
@@ -183,6 +208,14 @@ function calibrationViolationName(prefix: string): string {
   return `${prefix}.calibration-violation.json`;
 }
 
+function artifactRefSha256Hex(value: string): string {
+  const hex = value.startsWith('sha256:') ? value.slice('sha256:'.length) : value;
+  if (!/^[0-9a-f]{64}$/u.test(hex)) {
+    throw errorForArtifact(`fusion artifact sha256 is not a lowercase hex digest: ${value}`);
+  }
+  return hex;
+}
+
 export class FusionArtifactStore {
   private readonly runDirAbs: string;
   private readonly runDirDisplay: string;
@@ -203,8 +236,14 @@ export class FusionArtifactStore {
   }
 
   static async create(options: CreateFusionArtifactStoreOptions): Promise<FusionArtifactStore> {
-    const runId = options.runId ?? makeRunId();
+    const profile = fusionWorkflowProfile(options.profile?.id ?? 'reason');
+    const runId = options.runId ?? makeRunId(profile);
     if (!RUN_ID_PATTERN.test(runId)) throw errorForArtifact(`invalid fusion run id: ${runId}`);
+    if (!runId.startsWith(profile.runIdPrefix)) {
+      throw errorForArtifact(
+        `fusion run id ${runId} does not carry the ${profile.id} workflow prefix ${profile.runIdPrefix}`,
+      );
+    }
     const sessionSegment = sanitizePathSegment(
       options.sessionId ?? `session-${String(process.pid)}`,
     );
@@ -217,6 +256,7 @@ export class FusionArtifactStore {
     const manifest: MutableFusionArtifactManifest = {
       schema_version: FUSION_MANIFEST_SCHEMA_VERSION,
       run_id: runId,
+      workflow: profile.id,
       source: options.source,
       state: 'initializing',
       created_at: timestamp,
@@ -224,6 +264,13 @@ export class FusionArtifactStore {
       cwd: options.cwd,
       config: options.config,
       models: modelsForManifest(options.models),
+      capabilities: options.capabilities ?? {
+        candidate: 'reason',
+        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: [] },
       usage: cloneFusionUsage(EMPTY_FUSION_USAGE),
       attempts: [],
       artifacts: {},
@@ -250,6 +297,10 @@ export class FusionArtifactStore {
     return this.runDirAbs;
   }
 
+  childToolCallLogPath(stage: FusionStage, slot: 1 | 2 | 3 | undefined, attempt: number): string {
+    return this.artifactPath(`${attemptPrefix(stage, slot, attempt)}.tool-calls.jsonl`);
+  }
+
   snapshot(): FusionArtifactManifest {
     return publicManifest(this.manifest);
   }
@@ -294,7 +345,23 @@ export class FusionArtifactStore {
    * while the full omission accounting stays locally auditable.
    */
   async writeContextLedger(ledger: FusionContextOmissionLedgerV2): Promise<void> {
-    await this.writeArtifact('context-omission-ledger.json', canonicalJson(ledger));
+    const ref = await this.writeArtifact('context-omission-ledger.json', canonicalJson(ledger));
+    await this.updateManifest((manifest) => {
+      manifest.context.ledger_artifact = ref.path;
+    });
+  }
+
+  async writeSourcePolicy(serialized: string): Promise<void> {
+    const ref = await this.writeArtifact('source-policy.private.json', serialized);
+    await this.updateManifest((manifest) => {
+      manifest.context.source_policy_artifact = ref.path;
+    });
+  }
+
+  sourcePolicyLaunchReference(): { path: string; sha256: string } {
+    const ref = this.manifest.artifacts['source-policy.private.json'];
+    if (ref === undefined) throw errorForArtifact('research source policy has not been written');
+    return { path: this.artifactPath(ref.path), sha256: artifactRefSha256Hex(ref.sha256) };
   }
 
   /** Route capacities and the pre-candidate whole-workflow feasibility decision. */
@@ -338,6 +405,10 @@ export class FusionArtifactStore {
       responseName(prefix, input.responseKind),
       input.result.text,
     );
+    const toolCallsRef =
+      input.result.toolCallTrace === undefined
+        ? undefined
+        : await this.writeArtifact(`${prefix}.tool-calls.jsonl`, input.result.toolCallTrace.bytes);
     await this.updateManifest((manifest) => {
       const record: FusionAttemptArtifactRecord = {
         stage: input.result.stage,
@@ -352,6 +423,10 @@ export class FusionArtifactStore {
         qualifiedId: input.result.qualifiedId,
         usage: cloneFusionUsage(input.result.usage),
       };
+      if (toolCallsRef !== undefined && input.result.toolCallTrace !== undefined) {
+        record.tool_calls_path = toolCallsRef.path;
+        record.tool_calls = { ...input.result.toolCallTrace.summary };
+      }
       if (input.result.slot !== undefined) record.slot = input.result.slot;
       manifest.attempts.push(record);
     });

package/src/core/fusion/budget.ts

@@ -14,10 +14,6 @@ import {
   isUsableContextWindow,
 } from '../context/token-budget.js';
 import {
-  FUSION_CANDIDATE_SYSTEM_PROMPT,
-  FUSION_EVALUATION_REPAIR_SYSTEM_PROMPT,
-  FUSION_EVALUATOR_SYSTEM_PROMPT,
-  FUSION_MERGER_SYSTEM_PROMPT,
   buildBlindEvaluationInput,
   buildCandidatePrompt,
   buildEvaluationPrompt,
@@ -26,6 +22,7 @@ import {
   buildMergePrompt,
   type AnonymousFusionCandidate,
 } from './prompts.js';
+import { FUSION_REASON_WORKFLOW, type FusionWorkflowProfile } from './workflows.js';
 import {
   FUSION_BUDGET_PLAN_SCHEMA_VERSION,
   FUSION_CALIBRATION_VIOLATION_SCHEMA_VERSION,
@@ -45,6 +42,7 @@ import {
   type FusionBudgetWarning,
   type FusionCalibrationViolation,
   type FusionCanonicalInputV3,
+  type FusionCapability,
   type FusionEvaluationV1,
   type FusionRouteCapacity,
   type FusionStage,
@@ -103,18 +101,61 @@ export const FUSION_BUDGET_POLICY: FusionBudgetPolicyDescriptor = {
   utilization_warning_threshold_basis_points: FUSION_UTILIZATION_WARNING_THRESHOLD_BASIS_POINTS,
 };
 
-const EMPTY_REMEDIATION: readonly string[] = Object.freeze([
-  'Start a fresh Pi conversation, or run Fusion earlier in the session.',
-  "Raise the route's context window with a larger-context model via /fusion-models.",
-  'Restate only the required prior findings as visible conversation text.',
+const REASON_EMPTY_REMEDIATION: readonly string[] = Object.freeze([
+  'Start a fresh Pi conversation, or run fusion_reason earlier in the session.',
+  "Raise the route's context window with a larger-context subscription model via /fusion-models.",
+  'Restate only the required prior findings in the fusion_reason prompt.',
 ]);
 
-const REQUEST_REMEDIATION: readonly string[] = Object.freeze([
-  'Provide a shorter, self-contained fusion_brainstorm prompt.',
-  'Start a fresh Pi conversation, or run Fusion earlier in the session.',
-  "Raise the route's context window with a larger-context model via /fusion-models.",
+const REASON_REQUEST_REMEDIATION: readonly string[] = Object.freeze([
+  'Provide a shorter fusion_reason prompt.',
+  'Start a fresh Pi conversation, or run fusion_reason earlier in the session.',
+  "Raise the route's context window with a larger-context subscription model via /fusion-models.",
 ]);
 
+const INVESTIGATE_EMPTY_REMEDIATION: readonly string[] = Object.freeze([
+  'Split the repository investigation into smaller independently complete path or subsystem scopes.',
+  "Raise the route's context window with a larger-context subscription model via /fusion-models.",
+]);
+const INVESTIGATE_REQUEST_REMEDIATION: readonly string[] = Object.freeze([
+  'Narrow the fusion_investigate objective, repository scope, or required evidence.',
+  "Raise the route's context window with a larger-context subscription model via /fusion-models.",
+]);
+const RESEARCH_EMPTY_REMEDIATION: readonly string[] = Object.freeze([
+  'Split the research into smaller independently complete source sets.',
+  "Raise the route's context window with a larger-context subscription model via /fusion-models.",
+]);
+const RESEARCH_REQUEST_REMEDIATION: readonly string[] = Object.freeze([
+  'Narrow the fusion_research question or split large declared-source sets across independent runs.',
+  "Raise the route's context window with a larger-context subscription model via /fusion-models.",
+]);
+const VALIDATE_EMPTY_REMEDIATION: readonly string[] = Object.freeze([
+  'Split validation into smaller independently complete change or acceptance-criterion scopes.',
+  "Raise the route's context window with a larger-context subscription model via /fusion-models.",
+]);
+const VALIDATE_REQUEST_REMEDIATION: readonly string[] = Object.freeze([
+  'Narrow the fusion_validate scope, acceptance criteria, or supplied verification evidence.',
+  "Raise the route's context window with a larger-context subscription model via /fusion-models.",
+]);
+
+function cleanRemediation(
+  profile: FusionWorkflowProfile,
+  requestDeterminesFeasibility: boolean,
+): readonly string[] {
+  if (profile.id === 'investigate') {
+    return requestDeterminesFeasibility
+      ? INVESTIGATE_REQUEST_REMEDIATION
+      : INVESTIGATE_EMPTY_REMEDIATION;
+  }
+  if (profile.id === 'research') {
+    return requestDeterminesFeasibility ? RESEARCH_REQUEST_REMEDIATION : RESEARCH_EMPTY_REMEDIATION;
+  }
+  if (profile.id === 'validate') {
+    return requestDeterminesFeasibility ? VALIDATE_REQUEST_REMEDIATION : VALIDATE_EMPTY_REMEDIATION;
+  }
+  return requestDeterminesFeasibility ? REASON_REQUEST_REMEDIATION : REASON_EMPTY_REMEDIATION;
+}
+
 const RESERVATION_REMEDIATION: readonly string[] = Object.freeze([
   'Route the blocking stage to a model with larger byte capacity.',
   'Keep producer output contracts intact; do not shrink or truncate child answers.',
@@ -456,16 +497,28 @@ function replaceRequestText(input: FusionCanonicalInputV3, text: string): Fusion
 }
 
 function visibleTextBytes(input: FusionCanonicalInputV3): number {
+  const projection = input.context?.kind === 'session_projection'
+    ? input.context.conversation_projection
+    : 'conversation_projection' in input
+      ? input.conversation_projection
+      : undefined;
+  if (projection === undefined) return 0;
   let total = 0;
-  for (const entry of input.conversation_projection.entries) {
+  for (const entry of projection.entries) {
     if (entry[0] === 't') total += utf8Bytes(JSON.stringify(entry[4]));
   }
   return total;
 }
 
 function omissionReceiptBytes(input: FusionCanonicalInputV3): number {
+  const projection = input.context?.kind === 'session_projection'
+    ? input.context.conversation_projection
+    : 'conversation_projection' in input
+      ? input.conversation_projection
+      : undefined;
+  if (projection === undefined) return 0;
   let total = 0;
-  for (const entry of input.conversation_projection.entries) {
+  for (const entry of projection.entries) {
     if (entry[0] === 'o') total += utf8Bytes(JSON.stringify(entry));
   }
   return total;
@@ -526,10 +579,11 @@ function dominantRemediation(
   verdict: FusionBudgetEmptyRequestVerdict,
   composition: FusionBudgetStageComposition | undefined,
   dominantByteClass: string,
+  profile: FusionWorkflowProfile,
 ): readonly string[] {
   if (dominantByteClass === 'dense_ascii') return DENSE_REMEDIATION;
   if (dominantByteClass === 'multibyte') return MULTIBYTE_REMEDIATION;
-  if (composition === undefined) return remediationFor(verdict);
+  if (composition === undefined) return remediationFor(verdict, profile);
   const entries = [
     { name: 'visible', bytes: composition.visible_text_bytes },
     { name: 'request', bytes: composition.request_bytes },
@@ -538,13 +592,24 @@ function dominantRemediation(
   const dominant = entries[0];
   if (dominant?.name === 'reservation') return RESERVATION_REMEDIATION;
   if (dominant?.name === 'request' && !verdict.still_fails_with_empty_request) {
-    return REQUEST_REMEDIATION;
+    return profile.contextKind === 'clean_task'
+      ? cleanRemediation(profile, true)
+      : REASON_REQUEST_REMEDIATION;
   }
-  return EMPTY_REMEDIATION;
+  if (profile.contextKind === 'clean_task') return cleanRemediation(profile, false);
+  return REASON_EMPTY_REMEDIATION;
 }
 
-function remediationFor(verdict: FusionBudgetEmptyRequestVerdict): readonly string[] {
-  return verdict.still_fails_with_empty_request ? EMPTY_REMEDIATION : REQUEST_REMEDIATION;
+function remediationFor(
+  verdict: FusionBudgetEmptyRequestVerdict,
+  profile: FusionWorkflowProfile,
+): readonly string[] {
+  if (profile.contextKind === 'clean_task') {
+    return cleanRemediation(profile, !verdict.still_fails_with_empty_request);
+  }
+  return verdict.still_fails_with_empty_request
+    ? REASON_EMPTY_REMEDIATION
+    : REASON_REQUEST_REMEDIATION;
 }
 
 function formatEmptyRequestVerdict(verdict: FusionBudgetEmptyRequestVerdict): string {
@@ -677,11 +742,20 @@ export class FusionBudget {
   readonly routes: readonly FusionRouteCapacity[];
   readonly limiting: FusionRouteCapacity;
   private readonly contextPolicyId: string;
-
-  constructor(models: ResolvedFusionModels, contextPolicyId: string) {
+  private readonly candidateCapability: FusionCapability;
+  private readonly profile: FusionWorkflowProfile;
+
+  constructor(
+    models: ResolvedFusionModels,
+    contextPolicyId: string,
+    candidateCapability: FusionCapability = FUSION_REASON_WORKFLOW.candidateCapability,
+    profile: FusionWorkflowProfile = FUSION_REASON_WORKFLOW,
+  ) {
     this.routes = fusionRouteCapacities(models);
     this.limiting = fusionLimitingRoute(this.routes);
     this.contextPolicyId = contextPolicyId;
+    this.candidateCapability = candidateCapability;
+    this.profile = profile;
   }
 
   get allowedInputTokens(): number {
@@ -708,6 +782,7 @@ export class FusionBudget {
   }
 
   private drafts(input: FusionCanonicalInputV3): readonly StageForecastDraft[] {
+    const candidateSystemPrompt = this.profile.candidateSystemPrompt(this.candidateCapability);
     const candidatePrompt = buildCandidatePrompt(input);
     const blindInput = buildBlindEvaluationInput(input, EMPTY_CANDIDATES);
     const evaluationPrompt = buildEvaluationPrompt(blindInput);
@@ -724,7 +799,7 @@ export class FusionBudget {
         slot: 1,
         route: this.routeForStage('candidate', 1),
         conditional: false,
-        system_prompt: FUSION_CANDIDATE_SYSTEM_PROMPT,
+        system_prompt: candidateSystemPrompt,
         empty_user_prompt: candidatePrompt,
         upstream_output_contract_bytes: 0,
       },
@@ -733,7 +808,7 @@ export class FusionBudget {
         slot: 2,
         route: this.routeForStage('candidate', 2),
         conditional: false,
-        system_prompt: FUSION_CANDIDATE_SYSTEM_PROMPT,
+        system_prompt: candidateSystemPrompt,
         empty_user_prompt: candidatePrompt,
         upstream_output_contract_bytes: 0,
       },
@@ -742,7 +817,7 @@ export class FusionBudget {
         slot: 3,
         route: this.routeForStage('candidate', 3),
         conditional: false,
-        system_prompt: FUSION_CANDIDATE_SYSTEM_PROMPT,
+        system_prompt: candidateSystemPrompt,
         empty_user_prompt: candidatePrompt,
         upstream_output_contract_bytes: 0,
       },
@@ -750,7 +825,7 @@ export class FusionBudget {
         budget_stage: 'evaluation',
         route: this.routeForStage('evaluation'),
         conditional: false,
-        system_prompt: FUSION_EVALUATOR_SYSTEM_PROMPT,
+        system_prompt: this.profile.evaluatorSystemPrompt,
         empty_user_prompt: evaluationPrompt,
         upstream_output_contract_bytes: 3 * FUSION_CANDIDATE_MAX_OUTPUT_BYTES,
       },
@@ -758,7 +833,7 @@ export class FusionBudget {
         budget_stage: 'merge',
         route: this.routeForStage('merge'),
         conditional: false,
-        system_prompt: FUSION_MERGER_SYSTEM_PROMPT,
+        system_prompt: this.profile.mergerSystemPrompt,
         empty_user_prompt: mergePrompt,
         upstream_output_contract_bytes:
           3 * FUSION_CANDIDATE_MAX_OUTPUT_BYTES + FUSION_EVALUATION_MAX_OUTPUT_BYTES,
@@ -767,7 +842,7 @@ export class FusionBudget {
         budget_stage: 'evaluation_repair',
         route: this.routeForStage('evaluation_repair'),
         conditional: true,
-        system_prompt: FUSION_EVALUATION_REPAIR_SYSTEM_PROMPT,
+        system_prompt: this.profile.evaluationRepairSystemPrompt,
         empty_user_prompt: repairPrompt,
         upstream_output_contract_bytes:
           3 * FUSION_CANDIDATE_MAX_OUTPUT_BYTES +
@@ -842,7 +917,12 @@ export class FusionBudget {
   ): FusionError {
     const composition = plan.primary_blocker_composition;
     const dominantByteClass = primary.input_only_estimate.rateSource.dominant_byte_class;
-    const remediation = dominantRemediation(plan.empty_request, composition, dominantByteClass);
+    const remediation = dominantRemediation(
+      plan.empty_request,
+      composition,
+      dominantByteClass,
+      this.profile,
+    );
     const tokensOver = primary.input_only_input_tokens_upper_bound - primary.allowed_input_tokens;
     const budget: FusionBudgetErrorDetail = {
       budget_stage: primary.budget_stage,
@@ -916,6 +996,25 @@ export class FusionBudget {
     return new FusionError(message, details);
   }
 
+  private planMetadata(input?: FusionCanonicalInputV3): Pick<FusionBudgetPlanV1, 'workflow' | 'context' | 'fixed_candidate_policy' | 'tool_policy'> {
+    return {
+      workflow: this.profile.id,
+      context: {
+        kind: this.profile.contextKind,
+        policy_id: input?.context?.policy_id ?? this.contextPolicyId,
+      },
+      fixed_candidate_policy: {
+        capability: this.candidateCapability,
+        tools: this.profile.candidateTools,
+      },
+      tool_policy: {
+        candidate_tools: this.profile.candidateTools,
+        evaluation_tools: [] as readonly [],
+        merge_tools: [] as readonly [],
+      },
+    };
+  }
+
   plan(input: FusionCanonicalInputV3): FusionBudgetPlanV1 {
     const stages = this.entries(input);
     const blockers = selectBlockers(stages);
@@ -923,6 +1022,7 @@ export class FusionBudget {
     const emptyRequest = this.emptyRequestVerdict(input, stages);
     const base: FusionBudgetPlanV1 = {
       schema_version: FUSION_BUDGET_PLAN_SCHEMA_VERSION,
+      ...this.planMetadata(input),
       policy: FUSION_BUDGET_POLICY,
       routes: this.routes,
       stages,
@@ -985,6 +1085,7 @@ export class FusionBudget {
     const blocker = blockerFromEntry(entry);
     const plan: FusionBudgetPlanV1 = {
       schema_version: FUSION_BUDGET_PLAN_SCHEMA_VERSION,
+      ...this.planMetadata(),
       policy: FUSION_BUDGET_POLICY,
       routes: this.routes,
       stages: [entry],

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

@@ -0,0 +1,82 @@
+import { createHash } from 'node:crypto';
+import type { Usage } from '@earendil-works/pi-ai';
+
+export const FUSION_CHILD_RESULT_SCHEMA_VERSION =
+  'pi-background-tasks.fusion-child-result.v2' as const;
+export const FUSION_CHILD_RESULT_PREFIX = '\u001ePI_FUSION_CHILD_RESULT ';
+export const FUSION_TOOL_CALL_LOG_PATH_ENV = 'PI_FUSION_TOOL_CALL_LOG_PATH';
+export const FUSION_RESEARCH_ENABLED_ENV = 'PI_FUSION_RESEARCH_ENABLED';
+export const FUSION_SOURCE_POLICY_PATH_ENV = 'PI_FUSION_SOURCE_POLICY_PATH';
+export const FUSION_SOURCE_POLICY_SHA256_ENV = 'PI_FUSION_SOURCE_POLICY_SHA256';
+export const FUSION_TOOL_CALL_SEAL_SCHEMA_VERSION =
+  'pi-background-tasks.fusion-tool-call-seal.v1' as const;
+export const FUSION_TOOL_CALL_SEAL_SUFFIX = '.seal.json';
+
+/**
+ * Aggregate ceiling on tool-result bytes a single candidate child may accumulate.
+ *
+ * v1 deliberately has no tool-call-count cap, so this byte budget is the only bound on
+ * how much a read-only candidate can pull into its context. 8 MiB is generous for
+ * targeted grep/read investigation while still preventing an unbounded read loop from
+ * degrading into an opaque provider-side context failure.
+ */
+export const FUSION_CHILD_MAX_TOTAL_TOOL_RESULT_BYTES = 8 * 1024 * 1024;
+
+export interface FusionChildTextBlockMetadata {
+  utf8_bytes: number;
+  sha256: string;
+}
+
+export type FusionChildResultUsageMetadata = Usage;
+
+export interface FusionChildResultMetadata {
+  schema_version: typeof FUSION_CHILD_RESULT_SCHEMA_VERSION;
+  provider: string;
+  model: string;
+  stop_reason: string;
+  text_blocks: FusionChildTextBlockMetadata[];
+  text_sha256: string;
+  usage: FusionChildResultUsageMetadata;
+}
+
+function protocolSha256(value: string | Buffer): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+export function buildFusionChildResultMetadata(message: {
+  provider: string;
+  model: string;
+  stopReason: string;
+  content: ReadonlyArray<{ type: string; text?: string }>;
+  usage: Usage;
+}): FusionChildResultMetadata {
+  const textBlocks = message.content.flatMap((part) =>
+    part.type === 'text' && typeof part.text === 'string' ? [part.text] : [],
+  );
+  const usage: FusionChildResultUsageMetadata = {
+    input: message.usage.input,
+    output: message.usage.output,
+    cacheRead: message.usage.cacheRead,
+    cacheWrite: message.usage.cacheWrite,
+    totalTokens: message.usage.totalTokens,
+    cost: {
+      input: message.usage.cost.input,
+      output: message.usage.cost.output,
+      cacheRead: message.usage.cost.cacheRead,
+      cacheWrite: message.usage.cost.cacheWrite,
+      total: message.usage.cost.total,
+    },
+  };
+  return {
+    schema_version: FUSION_CHILD_RESULT_SCHEMA_VERSION,
+    provider: message.provider,
+    model: message.model,
+    stop_reason: message.stopReason,
+    text_blocks: textBlocks.map((text) => ({
+      utf8_bytes: Buffer.byteLength(text, 'utf8'),
+      sha256: protocolSha256(text),
+    })),
+    text_sha256: protocolSha256(textBlocks.join('')),
+    usage,
+  };
+}

package/src/core/fusion/clean-context.ts

@@ -0,0 +1,91 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from '../attested-pi-run.js';
+import { normalizeFusionDeclaredSources, type DeclaredFusionSourceInput } from './source-policy.js';
+import {
+  FUSION_INPUT_SCHEMA_VERSION,
+  FusionError,
+  type FusionCanonicalRequestV3,
+  type FusionCleanTaskCanonicalInputV5,
+  type FusionDeclaredSourceV1,
+  type FusionSource,
+  type FusionWorkflowId,
+} from './types.js';
+
+export interface BuildFusionCleanTaskInputOptions {
+  cwd: string;
+  source: FusionSource;
+  request: string;
+  workflow: Exclude<FusionWorkflowId, 'reason'>;
+  declaredSources?: readonly DeclaredFusionSourceInput[] | undefined;
+}
+
+/**
+ * Public v1 clean builder. It is deliberately pure: callers provide cwd and
+ * normalized request text explicitly, and this module has no dependency on Pi
+ * session, snapshot, parent-context, or visible-conversation APIs.
+ */
+export const buildCleanFusionCanonicalInput = buildFusionCleanTaskCanonicalInput;
+
+export interface BuiltFusionCleanTaskCanonicalInput {
+  input: FusionCleanTaskCanonicalInputV5;
+  serialized: string;
+  declaredSources: readonly FusionDeclaredSourceV1[];
+  transcriptLeafId: null;
+}
+
+function sha256Text(value: string): string {
+  return createHash('sha256').update(Buffer.from(value, 'utf8')).digest('hex');
+}
+
+export function buildFusionCleanTaskCanonicalInput(
+  options: BuildFusionCleanTaskInputOptions,
+): BuiltFusionCleanTaskCanonicalInput {
+  if (options.request.trim().length === 0) {
+    throw new FusionError('fusion request must not be blank', {
+      code: 'context_capture_failed',
+      childCreated: false,
+    });
+  }
+  if (!['investigate', 'research', 'validate'].includes(options.workflow)) {
+    throw new FusionError('clean-task fusion input is available only to investigate, research, and validate workflows', {
+      code: 'context_capture_failed',
+      childCreated: false,
+    });
+  }
+  const declaredSources = normalizeFusionDeclaredSources(options.declaredSources ?? []);
+  if (options.workflow === 'research' && declaredSources.length === 0) {
+    throw new FusionError('fusion research requires at least one declared source URL and purpose', {
+      code: 'context_capture_failed',
+      childCreated: false,
+    });
+  }
+  if (options.workflow !== 'research' && declaredSources.length > 0) {
+    throw new FusionError('declared sources are accepted only by the research workflow', {
+      code: 'context_capture_failed',
+      childCreated: false,
+    });
+  }
+  const request: FusionCanonicalRequestV3 = {
+    source: options.source,
+    authority: 'explicit_text',
+    text: options.request,
+    sha256: sha256Text(options.request),
+  };
+  const input: FusionCleanTaskCanonicalInputV5 = {
+    schema_version: FUSION_INPUT_SCHEMA_VERSION,
+    workflow: options.workflow,
+    cwd: options.cwd,
+    request,
+    context: {
+      kind: 'clean_task',
+      policy_id: 'fusion-clean-task-v1',
+      declared_sources: declaredSources,
+    },
+  };
+  return {
+    input,
+    serialized: canonicalJson(input),
+    declaredSources,
+    transcriptLeafId: null,
+  };
+}