pi-background-tasks 0.7.0 → 0.7.3

package/src/core/fusion/types.ts

@@ -1,10 +1,12 @@
+import type { Usage } from '@earendil-works/pi-ai';
+
 export type FusionThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 
 export const FUSION_MODEL_CONFIG_SCHEMA_VERSION = 'pi-background-tasks.fusion-models.v1';
 export const FUSION_INPUT_SCHEMA_VERSION = 'pi-background-tasks.fusion-input.v1';
 export const FUSION_EVALUATION_SCHEMA_VERSION = 'pi-background-tasks.fusion-evaluation.v1';
-export const FUSION_RESULT_SCHEMA_VERSION = 'pi-background-tasks.fusion-result.v1';
-export const FUSION_MANIFEST_SCHEMA_VERSION = 'pi-background-tasks.fusion-manifest.v1';
+export const FUSION_RESULT_SCHEMA_VERSION = 'pi-background-tasks.fusion-result.v2';
+export const FUSION_MANIFEST_SCHEMA_VERSION = 'pi-background-tasks.fusion-manifest.v2';
 
 export const FUSION_CANDIDATE_IDS = ['A', 'B', 'C'] as const;
 export type FusionCandidateId = (typeof FUSION_CANDIDATE_IDS)[number];
@@ -124,14 +126,16 @@ export interface FusionEvaluationV1 {
   synthesis_plan: FusionSynthesisPlan;
 }
 
-export interface FusionUsage {
-  input: number;
-  output: number;
-  cacheRead: number;
-  cacheWrite: number;
-  totalTokens: number;
-  costTotal?: number;
-}
+/** Exact Pi usage contract used at the child, artifact, and host tool-result boundaries. */
+export type FusionUsage = Usage;
+
+const EMPTY_FUSION_COST: Usage['cost'] = Object.freeze({
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  total: 0,
+});
 
 export const EMPTY_FUSION_USAGE: FusionUsage = Object.freeze({
   input: 0,
@@ -139,8 +143,43 @@ export const EMPTY_FUSION_USAGE: FusionUsage = Object.freeze({
   cacheRead: 0,
   cacheWrite: 0,
   totalTokens: 0,
+  cost: EMPTY_FUSION_COST,
 });
 
+export function createEmptyFusionUsage(): FusionUsage {
+  return cloneFusionUsage(EMPTY_FUSION_USAGE);
+}
+
+export function cloneFusionUsage(usage: FusionUsage): FusionUsage {
+  return {
+    input: usage.input,
+    output: usage.output,
+    cacheRead: usage.cacheRead,
+    cacheWrite: usage.cacheWrite,
+    totalTokens: usage.totalTokens,
+    cost: {
+      input: usage.cost.input,
+      output: usage.cost.output,
+      cacheRead: usage.cost.cacheRead,
+      cacheWrite: usage.cost.cacheWrite,
+      total: usage.cost.total,
+    },
+  };
+}
+
+export function addFusionUsage(target: FusionUsage, delta: FusionUsage): void {
+  target.input += delta.input;
+  target.output += delta.output;
+  target.cacheRead += delta.cacheRead;
+  target.cacheWrite += delta.cacheWrite;
+  target.totalTokens += delta.totalTokens;
+  target.cost.input += delta.cost.input;
+  target.cost.output += delta.cost.output;
+  target.cost.cacheRead += delta.cost.cacheRead;
+  target.cost.cacheWrite += delta.cost.cacheWrite;
+  target.cost.total += delta.cost.total;
+}
+
 export interface FusionResultDetails {
   schema_version: typeof FUSION_RESULT_SCHEMA_VERSION;
   run_id: string;
@@ -232,7 +271,7 @@ export interface FusionChildRunResult {
   qualifiedId: string;
   text: string;
   usage: FusionUsage;
-  stdout: Buffer;
+  events: Buffer;
   stderr: Buffer;
   exitCode: number;
   signal: NodeJS.Signals | null;
@@ -247,6 +286,7 @@ export interface FusionAttemptArtifactRecord {
   events_path?: string;
   stderr_path?: string;
   response_path?: string;
+  partial_response_path?: string;
   provider?: string;
   model?: string;
   qualifiedId?: string;

package/src/core/registry.ts

@@ -1538,6 +1538,7 @@ export class BackgroundTaskRegistry {
       error,
       `  <output-file>${escapeXml(task.outputPath)}</output-file>`,
       `  <summary>${escapeXml(`Background task ${JSON.stringify(taskName)} ${task.status}`)}</summary>`,
+      '  <guidance>Terminal state and output metadata are durable. Do not call bg_status to reconfirm; use bg_logs only if output is needed.</guidance>',
       '</background-task-notification>',
     ]
       .filter(Boolean)

package/src/extension.ts

@@ -12,6 +12,7 @@ import { Type, type Static } from 'typebox';
 import {
   DEFAULT_LOG_BYTES,
   MAX_LOG_BYTES,
+  deriveCompletionDeliveryGuidance,
   deriveTaskNameFromCommand,
   formatSnapshotList,
   formatUpdateSegment,
@@ -125,12 +126,15 @@ const BgRunParams = Type.Object({
     Type.Number({ description: 'Optional timeout; task is failed and killed when exceeded' }),
   ),
   notifyOnCompletion: Type.Optional(
-    Type.Boolean({ description: 'Whether to show a completion notification. Default: true.' }),
+    Type.Boolean({
+      description:
+        'Whether to deliver the durable terminal notification. Default: true; disable only when deliberately taking over completion monitoring.',
+    }),
   ),
   triggerOnCompletion: Type.Optional(
     Type.Boolean({
       description:
-        'Whether completion should trigger a follow-up agent turn. Default: true for bg_run.',
+        'Whether that notification should automatically trigger a follow-up agent turn. Default: true for bg_run; requires notifyOnCompletion.',
     }),
   ),
 });
@@ -657,15 +661,18 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
   pi.registerTool<typeof BgRunParams, BgRunDetails>({
     name: 'bg_run',
     label: 'Background Run',
-    description: `Start a named long-running shell command in the background and return immediately with a task ID and output path. Output is written to .pi/tasks and model-visible logs are bounded to ${formatSize(MAX_LOG_BYTES)}.`,
+    description: `Start a named long-running shell command in the background and return immediately with a task ID and output path. By default, completed, failed, or killed terminal state is delivered automatically as <background-task-notification> and starts a follow-up agent turn; do not sleep or poll merely to wait. Output is written to .pi/tasks and model-visible logs are bounded to ${formatSize(MAX_LOG_BYTES)}.`,
     promptSnippet:
-      'Start named long-running shell commands in the background and return a task ID plus output file path',
+      'Start a named long-running shell command; default terminal notification wakes a follow-up turn, so yield instead of polling',
     promptGuidelines: [
-      'Use bg_run instead of bash for commands expected to run for a long time, such as test suites, dev servers, watchers, builds, or sleeps.',
+      'Use bg_run instead of bash for commands expected to run for a long time, such as test suites, dev servers, watchers, or builds.',
       'Always set isAgent: true only when the background task launches an LLM/agent process; set isAgent: false for scripts, tests, dev servers, sleeps, and ordinary shell commands.',
       'When using bg_run, always set name to a concise 2-6 word human-readable label for the footer task dock; do not use the raw command as the name unless it is already short and meaningful.',
-      'After bg_run, use bg_status and bg_logs to inspect progress; do not assume the background task completed until status says completed, failed, or killed.',
-      'When a <background-task-notification> appears, react to it: inspect bg_status/bg_logs as needed, then report completion, failure, or next steps to the user.',
+      'bg_run returns immediately. With notifyOnCompletion:true and triggerOnCompletion:true (both defaults), completed, failed, or killed terminal state is delivered as <background-task-notification> and automatically starts a follow-up agent turn.',
+      'After a default bg_run launch, continue only independent useful work that does not merely wait for the task; otherwise briefly acknowledge it if useful, then end the current turn. Do not call sleep, bg_status, or bg_logs merely to wait; the terminal notification will wake you.',
+      'Treat <background-task-notification> as durable terminal truth. Do not call bg_status to reconfirm it; call bg_logs only when the task output is needed.',
+      'Use bg_status/bg_logs only when the user explicitly requests an update, automatic notification or wake-up was deliberately disabled, there is concrete evidence the task is hung, or a terminal notification arrived and output details are needed.',
+      'Do not set notifyOnCompletion:false or triggerOnCompletion:false unless intentionally opting out of automatic completion handling.',
     ],
     parameters: BgRunParams,
     prepareArguments(args): BgRunParamsValue {
@@ -708,9 +715,13 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
       if (params.description !== undefined) taskOptions.description = params.description;
       if (params.timeoutSeconds !== undefined) taskOptions.timeoutSeconds = params.timeoutSeconds;
       const task = await startTask(ctx, params.command, taskOptions);
+      const completionDelivery = deriveCompletionDeliveryGuidance(
+        task.notifyOnCompletion,
+        task.triggerOnCompletion,
+      );
       return {
         content: textContent(
-          `Started background task ${taskDisplayName(task)} (${task.id})\nStatus: ${task.status}\nPID: ${String(task.pid ?? 'unknown')}\nOutput: ${task.outputPath}`,
+          `Started background task ${taskDisplayName(task)} (${task.id})\nStatus: ${task.status}\nPID: ${String(task.pid ?? 'unknown')}\nOutput: ${task.outputPath}\n${completionDelivery.text}`,
         ),
         details: { task: registry.snapshot(task) },
       };
@@ -800,10 +811,14 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
   pi.registerTool<typeof BgStatusParams, BgStatusDetails>({
     name: 'bg_status',
     label: 'Background Status',
-    description: 'Inspect one background task or list all running/recent background tasks.',
-    promptSnippet: 'Inspect status for one or all background tasks',
+    description:
+      'Inspect one background task or list all running/recent background tasks. This is a point-in-time inspection tool, not a waiting primitive.',
+    promptSnippet:
+      'Inspect point-in-time status for one or all background tasks; never poll it as a wait loop',
     promptGuidelines: [
-      'Use bg_status before bg_logs when you need to know whether a background task is still running or has finished.',
+      'Use bg_status for deliberate point-in-time inspection, not as a waiting primitive.',
+      'A running result is not an instruction to poll again. Do not repeatedly call bg_status while an automatic terminal notification is pending.',
+      'Use bg_status when the user explicitly requests an update, automatic completion handling was disabled, or concrete evidence suggests a task is hung; terminal notifications do not need reconfirmation.',
     ],
     parameters: BgStatusParams,
     execute(_toolCallId, params) {
@@ -827,10 +842,12 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
   pi.registerTool<typeof BgLogsParams, BgLogsDetails>({
     name: 'bg_logs',
     label: 'Background Logs',
-    description: `Read bounded output from a background task. Output is capped at ${formatSize(MAX_LOG_BYTES)} for model safety and points to the full output file when truncated.`,
-    promptSnippet: 'Read bounded output from a background task log',
+    description: `Read bounded output from a background task for deliberate inspection; this is not a waiting primitive. Output is capped at ${formatSize(MAX_LOG_BYTES)} for model safety and points to the full output file when truncated.`,
+    promptSnippet: 'Read bounded task output when needed; never tail it repeatedly as a wait loop',
     promptGuidelines: [
-      'Use bg_logs with a modest maxBytes value to inspect background task progress without flooding context.',
+      'Use bg_logs with a modest maxBytes value only when task output is needed, without flooding context.',
+      'Do not repeatedly call bg_logs to wait for completion while an automatic terminal notification is pending.',
+      'Use bg_status first only when a deliberate inspection requires the current task state; do not reconfirm a terminal notification.',
     ],
     parameters: BgLogsParams,
     async execute(_toolCallId, params) {

package/src/fusion-child-extension.ts

@@ -0,0 +1,91 @@
+import { createHash } from 'node:crypto';
+import type { Usage } from '@earendil-works/pi-ai';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+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 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 sha256(value: string): string {
+  return createHash('sha256').update(value, 'utf8').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: sha256(text),
+    })),
+    text_sha256: sha256(textBlocks.join('')),
+    usage,
+  };
+}
+
+async function writeMetadata(record: FusionChildResultMetadata): Promise<void> {
+  const line = `${FUSION_CHILD_RESULT_PREFIX}${JSON.stringify(record)}\n`;
+  await new Promise<void>((resolve, reject) => {
+    process.stderr.write(line, (error) => {
+      if (error) reject(error);
+      else resolve();
+    });
+  });
+}
+
+/**
+ * Private Fusion child extension.
+ *
+ * Pi print mode writes only the final full text to stdout. This extension adds
+ * one compact, reasoning-free metadata record to stderr for each finalized
+ * assistant message so the parent can validate model identity, stop reason,
+ * exact text bytes, and usage without consuming cumulative JSON stream events.
+ */
+export default function fusionChildExtension(pi: ExtensionAPI): void {
+  pi.on('message_end', async (event) => {
+    if (event.message.role !== 'assistant') return;
+    await writeMetadata(buildFusionChildResultMetadata(event.message));
+  });
+}

package/src/fusion-extension.ts

@@ -1,3 +1,4 @@
+import type { Usage } from '@earendil-works/pi-ai';
 import type {
   AgentToolResult,
   ExtensionAPI,
@@ -26,6 +27,7 @@ import { FusionOrchestrator } from './core/fusion/orchestrator.js';
 import {
   FUSION_RESULT_SCHEMA_VERSION,
   FusionError,
+  cloneFusionUsage,
   type FusionModelConfigV1,
   type FusionModelSelection,
   type FusionProgressEvent,
@@ -49,7 +51,7 @@ const FUSION_MODEL_COMMAND_NAME = 'fusion-models';
 
 type FusionToolDetails = FusionResultDetails | FusionProgressDetails;
 type FusionToolResultWithUsage = AgentToolResult<FusionToolDetails> & {
-  usage: FusionResultDetails['usage'];
+  usage: Usage;
 };
 
 type CommandDialogResult =
@@ -124,6 +126,17 @@ function errorArtifactSuffix(error: unknown): string {
     : '';
 }
 
+function toolFailureMessage(error: unknown): string {
+  const coordinates: string[] = [];
+  if (error instanceof FusionError) {
+    if (error.stage !== undefined) coordinates.push(`stage=${error.stage}`);
+    if (error.slot !== undefined) coordinates.push(`slot=${String(error.slot)}`);
+    if (error.attempt !== undefined) coordinates.push(`attempt=${String(error.attempt)}`);
+  }
+  const location = coordinates.length === 0 ? '' : ` (${coordinates.join(', ')})`;
+  return `Fusion failed${location}: ${errorMessage(error)}${errorArtifactSuffix(error)}`;
+}
+
 function progressText(event: FusionProgressEvent): string {
   if (event.type === 'state') return `fusion: ${event.state.replace(/_/g, ' ')}`;
   if (event.type === 'candidate_started') return `fusion: candidate ${String(event.slot)} starting`;
@@ -149,8 +162,7 @@ function makeProgressDetails(event: FusionProgressEvent): FusionProgressDetails
 
 function usageSummary(details: FusionResultDetails): string {
   const tokens = details.usage.totalTokens;
-  const cost =
-    details.usage.costTotal === undefined ? '' : ` · $${details.usage.costTotal.toFixed(4)}`;
+  const cost = ` · $${details.usage.cost.total.toFixed(4)}`;
   return `${String(tokens)} tokens${cost}`;
 }
 
@@ -546,23 +558,28 @@ export function registerFusionExtension(pi: ExtensionAPI): void {
     prepareArguments: prepareFusionArguments,
     async execute(toolCallId, params, signal, onUpdate, ctx) {
       const prompt = normalizeToolPrompt(params.prompt);
-      const result = await runFusion({
-        source: 'tool',
-        ctx,
-        request: prompt,
-        signal,
-        toolCallId,
-        onProgress: (event) => {
-          onUpdate?.({
-            content: textContent(progressText(event)),
-            details: makeProgressDetails(event),
-          });
-        },
-      });
+      let result: FusionRunResult;
+      try {
+        result = await runFusion({
+          source: 'tool',
+          ctx,
+          request: prompt,
+          signal,
+          toolCallId,
+          onProgress: (event) => {
+            onUpdate?.({
+              content: textContent(progressText(event)),
+              details: makeProgressDetails(event),
+            });
+          },
+        });
+      } catch (error) {
+        throw new Error(toolFailureMessage(error), { cause: error });
+      }
       const toolResult: FusionToolResultWithUsage = {
         content: textContent(result.mergedText),
         details: result.details,
-        usage: result.details.usage,
+        usage: cloneFusionUsage(result.details.usage),
       };
       return toolResult;
     },