pi-background-tasks 1.0.7 → 2.1.1

package/docs/tools/fusion_investigate.md

@@ -11,8 +11,8 @@ covers_sources: []
 
 <!-- pi-docs:begin name="tool-contract-fusion_investigate" generator="scripts/docs/generate.mjs" -->
 - Label: **Fusion Investigate**
-- Source: `src/fusion-extension.ts:1049`
-- Description: Run a five-model Fusion investigation from a structured, self-contained objective/background/deliverable. Candidate children run in clean bounded read-only contexts.
+- Source: `src/fusion-extension.ts:1197`
+- Description: Start a five-model Fusion investigation as a tracked background task and return immediately after durable preflight. Retrieve the verified result with bg_result after notification. Candidate children run in clean bounded read-only contexts.
 - Root schema: `object`; additionalProperties: `false`
 
 | Field | Required | Type | Description | Constraints |
@@ -103,9 +103,11 @@ Investigate uses clean-task canonical input (`pi-background-tasks.fusion-input.v
 
 Candidate children run with the fixed inspect policy: `read`, `grep`, `find`, and `ls` only, with built-in tools disabled and Fusion/background/write/shell tools denied. Evaluator, evaluator-repair, and merger run with no tools.
 
-## Execution model
+## Execution and delivery model
 
-Three inspect candidates independently re-derive repository facts, a blind evaluator compares anonymous candidate answers, and a merger synthesizes the final answer. One evaluator-repair child is run only when the first evaluator response is invalid JSON or fails the evaluation schema.
+After durable no-child preflight, the tool returns a tracked background task receipt. Three inspect candidates independently re-derive repository facts, a blind evaluator compares anonymous candidate answers, and a merger synthesizes the final answer. One evaluator-repair child is run only when the first evaluator response is invalid JSON or fails the evaluation schema.
+
+Wait for the terminal notification, then call `bg_result({taskId})` once. Retrieval verifies the committed result and never truncates. Repository reads are live, so continue only independent work and do not mutate the investigated scope while the task runs.
 
 ## Failure behavior
 

package/docs/tools/fusion_reason.md

@@ -11,8 +11,8 @@ covers_sources: []
 
 <!-- pi-docs:begin name="tool-contract-fusion_reason" generator="scripts/docs/generate.mjs" -->
 - Label: **Fusion Reason**
-- Source: `src/fusion-extension.ts:1032`
-- Description: Run a five-model Fusion reason workflow. Candidate children receive the reason projection and no tools; evaluator and merger also run without tools.
+- Source: `src/fusion-extension.ts:1179`
+- Description: Start a five-model Fusion reason workflow as a tracked background task and return immediately after durable preflight. Retrieve the verified result with bg_result after notification. Candidate children receive the reason projection and no tools; evaluator and merger also run without tools.
 - Root schema: `object`; additionalProperties: `false`
 
 | Field | Required | Type | Description | Constraints |
@@ -59,11 +59,11 @@ The schema is closed: `prompt` is required, must trim to non-blank text, and no
 
 Candidate children run with `--no-tools`. The blind evaluator, conditional evaluator-repair, and merger also run with `--no-tools` by stage policy.
 
-## Execution model
+## Execution and delivery model
 
-A successful run starts three candidate children, then a blind evaluator, then a merger. If the evaluator output is not valid closed-schema JSON, Fusion performs one evaluator-repair attempt and revalidates. Do not assume exactly five child calls: repair, preflight refusal, cancellation, spawn retry, and failures change the observed attempt count.
+The tool freezes its input, completes durable no-child preflight, registers a managed background task, and returns its task/run id immediately. The workflow then starts three candidate children, a blind evaluator, optional evaluator repair, and a merger.
 
-The tool result returns the merger's exact text directly, with `details` containing the Fusion result metadata and `usage` cloning the complete Pi `Usage` object including all cost fields.
+Wait for the terminal notification and call `bg_result({taskId})` once. `bg_result` verifies `manifest.json`, `result.json`, and `merged.md` hashes before returning bytes; oversized output becomes an artifact reference, never truncation. Complete Fusion usage is attached to the first successful retrieval exactly once so repeated retrieval cannot double-count session cost.
 
 ## Limitations
 

package/docs/tools/fusion_research.md

@@ -11,8 +11,8 @@ covers_sources: []
 
 <!-- pi-docs:begin name="tool-contract-fusion_research" generator="scripts/docs/generate.mjs" -->
 - Label: **Fusion Research**
-- Source: `src/fusion-extension.ts:1066`
-- Description: Run a five-model Fusion research workflow over explicitly supplied public http(s) URLs. Targeted URL fetch is not web search; fetched pages and URLs are untrusted.
+- Source: `src/fusion-extension.ts:1216`
+- Description: Start a five-model Fusion research workflow as a tracked background task and return immediately after durable preflight. Retrieve the verified result with bg_result after notification. Targeted URL fetch is not web search; fetched pages and URLs are untrusted.
 - Root schema: `object`; additionalProperties: `false`
 
 | Field | Required | Type | Description | Constraints |
@@ -153,6 +153,10 @@ The private `fusion_web_fetch` schema is closed: `{url, extract?: 'text'|'markdo
 
 Failures use typed error codes such as `invalid_url`, `unsupported_scheme`, `blocked_address`, `dns_failure`, `redirect_limit`, `redirect_blocked`, `response_too_large`, `unsupported_content_type`, `request_timeout`, `network_error`, `extraction_failed`, and `http_error`.
 
+## Background delivery
+
+After durable no-child preflight, the tool returns a tracked background task receipt. Wait for the terminal notification, then call `bg_result({taskId})` once; retrieval verifies the committed result and never truncates. Repository reads are live, so do not mutate relevant files while the task runs.
+
 ## Audit
 
 Research candidates write sealed per-attempt tool-call logs. Logs persist tool names, byte counts, SHA-256 digests, status, duration, and fetch provenance (`url`/`final_url`/status/bytes/content hash for successful fetches; only a rejected URL hash for rejected fetches). Raw arguments, raw results, and page content are not written to the audit log.

package/docs/tools/fusion_validate.md

@@ -11,8 +11,8 @@ covers_sources: []
 
 <!-- pi-docs:begin name="tool-contract-fusion_validate" generator="scripts/docs/generate.mjs" -->
 - Label: **Fusion Validate**
-- Source: `src/fusion-extension.ts:1084`
-- Description: Run an advisory, read-only Fusion validation review from a structured contract. It is not a build/test/lint substitute and never modifies files.
+- Source: `src/fusion-extension.ts:1236`
+- Description: Start an advisory, read-only Fusion validation review as a tracked background task and return immediately after durable preflight. Retrieve the verified result with bg_result after notification. It is not a build/test/lint substitute and never modifies files.
 - Root schema: `object`; additionalProperties: `false`
 
 | Field | Required | Type | Description | Constraints |
@@ -197,7 +197,9 @@ Each candidate must return closed JSON (`pi-background-tasks.fusion-validation-c
 
 After the no-tool merger child runs, the host renders the final validation report from validated accounting so included findings are preserved, duplicate groups are merged deterministically, excluded findings are listed only as exclusions, and candidate labels/source ids are sanitized from rationale text.
 
-## Advisory limitation
+## Background delivery and advisory limitation
+
+After durable no-child preflight, the tool returns a tracked background task receipt. Wait for the terminal notification, then call `bg_result({taskId})` once; retrieval verifies the committed report and never truncates. The repository is read live, so do not mutate the reviewed scope while the task runs.
 
 `fusion_validate` never modifies files, never runs builds/tests/linters/security scanners, and does not gate anything. It is an advisory read-only review. Supply real verification evidence when available, and state known limitations/exclusions explicitly.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-background-tasks",
-  "version": "1.0.7",
+  "version": "2.1.1",
   "description": "Pi extension for durable background shell tasks, read-only delegated agents, local attested Pi runs, and fixed-purpose Fusion workflows through child Pi processes.",
   "type": "module",
   "license": "ISC",

package/src/core/common.ts

@@ -4,6 +4,7 @@ import { extname, isAbsolute, join, win32 } from 'node:path';
 import { DEFAULT_MAX_BYTES } from '@earendil-works/pi-coding-agent';
 import type { BackgroundTaskChildProcess } from './registry.js';
 import type { DelegateBudgetRouteSource } from './delegate/types.js';
+import type { FusionResultDetails, FusionUsage, FusionWorkflowId } from './fusion/types.js';
 
 export const TASK_STATUS_VALUES = ['running', 'completed', 'failed', 'killed'] as const;
 export const TERMINAL_TASK_STATUS_VALUES = ['completed', 'failed', 'killed'] as const;
@@ -62,6 +63,7 @@ export interface BgTaskSnapshot {
   telemetryUnavailableReason?: string | undefined;
   attestationPath?: string | undefined;
   delegate?: DelegateTaskFacts | undefined;
+  fusion?: FusionTaskFacts | undefined;
 }
 
 export interface AttestedPiTaskFiles {
@@ -99,6 +101,25 @@ export interface DelegateTaskOutcome {
   toolCalls?: number | undefined;
 }
 
+/** Fusion-specific task facts surfaced through snapshots and `bg_result`. */
+export interface FusionTaskFacts {
+  runId: string;
+  workflow: FusionWorkflowId;
+  artifactDir: string;
+  artifactDirAbs: string;
+  state: string;
+  outcome?: FusionTaskOutcome | undefined;
+  /** Durable once-only accounting claim made by the first successful bg_result retrieval. */
+  usageDelivered: boolean;
+}
+
+export interface FusionTaskOutcome {
+  status: 'committed' | 'failed' | 'cancelled';
+  resultDetails?: FusionResultDetails | undefined;
+  usage?: FusionUsage | undefined;
+  error?: string | undefined;
+}
+
 export interface BgTask extends Omit<BgTaskSnapshot, 'name'> {
   name: string;
   outputAbsPath: string;
@@ -129,6 +150,11 @@ export interface BgTask extends Omit<BgTaskSnapshot, 'name'> {
   attestationPath?: string | undefined;
   attestedPi?: AttestedPiTaskFiles | undefined;
   delegate?: DelegateTaskFacts | undefined;
+  fusion?: FusionTaskFacts | undefined;
+  /** Cancellation hook for an in-process managed task such as Fusion. */
+  managedCancel?: (() => void) | undefined;
+  managedCancelRequested?: boolean | undefined;
+  managedStopWaitMs?: number | undefined;
   metadataWriteChain?: Promise<void> | undefined;
   waiters: Array<() => void>;
 }
@@ -226,6 +252,22 @@ export interface StartTaskOptions {
 }
 
 /** Prepared delegate launch handed to the registry after preflight has succeeded. */
+export interface StartManagedTaskOptions {
+  id: string;
+  name: string;
+  command: string;
+  description?: string | undefined;
+  isAgent: boolean;
+  completion: Promise<void>;
+  cancel: () => void;
+  notifyOnCompletion: boolean;
+  triggerOnCompletion: boolean;
+  fusion: FusionTaskFacts;
+  stopWaitMs?: number | undefined;
+  /** Prevent terminal publication until the launch receipt handoff is observable. */
+  terminalPublicationGate?: Promise<void> | undefined;
+}
+
 export interface StartDelegateTaskOptions {
   name: string;
   argv: readonly string[];
@@ -687,10 +729,15 @@ export function shellInvocation(
     failShellInvocation('PI_BG_SHELL must be exactly cmd or bash');
   }
   const explicitPath =
-    requestedPath !== undefined ? validateWindowsShellPath(requestedPath, 'PI_BG_SHELL_PATH') : undefined;
+    requestedPath !== undefined
+      ? validateWindowsShellPath(requestedPath, 'PI_BG_SHELL_PATH')
+      : undefined;
   if (requestedShell === 'cmd') {
     const comSpec = env['ComSpec'];
-    return cmdShellInvocation(command, explicitPath ?? (comSpec && comSpec.length > 0 ? comSpec : 'cmd.exe'));
+    return cmdShellInvocation(
+      command,
+      explicitPath ?? (comSpec && comSpec.length > 0 ? comSpec : 'cmd.exe'),
+    );
   }
   return posixShellInvocation(command, explicitPath ?? resolveWindowsBash(env));
 }
@@ -728,6 +775,7 @@ export function snapshot(task: BgTask): BgTaskSnapshot {
     telemetryUnavailableReason: task.telemetryUnavailableReason,
     attestationPath: task.attestationPath,
     delegate: task.delegate,
+    fusion: task.fusion,
   };
 }