pi-background-tasks 2.1.3 → 2.3.0

package/src/core/fusion/types.ts

@@ -30,6 +30,8 @@ export const FUSION_CALIBRATION_VIOLATION_SCHEMA_VERSION =
 export const FUSION_VALIDATE_CANDIDATE_CONTRACT_EVENT_SCHEMA_VERSION =
   'pi-background-tasks.fusion-validation-candidate-contract-event.v1';
 export const FUSION_TOOL_CALL_LOG_SCHEMA_VERSION = 'pi-background-tasks.fusion-tool-call.v1';
+export const FUSION_FAILURE_SUMMARY_SCHEMA_VERSION =
+  'pi-background-tasks.fusion-failure-summary.v1';
 
 /**
  * Conversation-projection transform shared by every Fusion entry point.
@@ -877,6 +879,91 @@ export interface FusionArtifactRef {
   sha256: string;
 }
 
+export type FusionFailureArtifactClassification =
+  | 'complete_stage_output'
+  | 'partial_stage_output'
+  | 'oversized_original'
+  | 'empty_rejected_output'
+  | 'evidence_only';
+
+export interface FusionFailureEvidenceArtifact {
+  name: string;
+  classification: FusionFailureArtifactClassification;
+  ref: FusionArtifactRef;
+}
+
+export interface FusionFailureAttemptMetadata {
+  stage: FusionStage;
+  slot?: 1 | 2 | 3 | undefined;
+  attempt: number;
+  status: 'completed' | 'failed' | 'cancelled';
+  child_created: boolean;
+}
+
+export interface FusionFailureList<T> {
+  listed: readonly T[];
+  omitted_count: number;
+}
+
+export interface FusionFailureMessageMetadata {
+  byte_length: number;
+  sha256: string;
+  inline_message?: string | undefined;
+  omission_reason?: 'exceeds_inline_message_bytes_cap' | 'result_view_byte_budget' | undefined;
+}
+
+export interface FusionFailureSummaryV1 {
+  schema_version: typeof FUSION_FAILURE_SUMMARY_SCHEMA_VERSION;
+  run_id: string;
+  workflow: FusionWorkflowId;
+  source: FusionSource;
+  terminal_state: Exclude<FusionTerminalState, 'completed'>;
+  created_at: string;
+  answer: { present: false; reason: 'run_did_not_commit' };
+  failure: {
+    code: FusionErrorCode | null;
+    stage?: FusionStage | undefined;
+    slot?: 1 | 2 | 3 | undefined;
+    attempt?: number | undefined;
+    child_created: boolean;
+    message: FusionFailureMessageMetadata;
+  };
+  progress: FusionRunProgress;
+  usage_so_far: FusionUsage;
+  attempts: FusionFailureList<FusionFailureAttemptMetadata>;
+  evidence_artifacts: FusionFailureList<FusionFailureEvidenceArtifact>;
+  remediation_ids: readonly (
+    | 'inspect_manifest_bound_evidence'
+    | 'inspect_terminal_error'
+    | 'split_or_reduce_work'
+    | 'retry_same_route_after_operator_review'
+  )[];
+}
+
+export interface FusionFailureViewFailure {
+  code?: FusionErrorCode | null | undefined;
+  stage?: FusionStage | undefined;
+  slot?: 1 | 2 | 3 | undefined;
+  attempt?: number | undefined;
+  child_created?: boolean | undefined;
+  message: FusionFailureMessageMetadata;
+}
+
+export interface FusionFailureResultView {
+  schema_version: typeof FUSION_FAILURE_SUMMARY_SCHEMA_VERSION;
+  summary_status: 'verified' | 'legacy_manifest_only' | 'unavailable' | 'integrity_failed';
+  terminal_state: Exclude<FusionTerminalState, 'completed'>;
+  answer: { present: false; reason: 'run_did_not_commit' };
+  failure?: FusionFailureViewFailure | undefined;
+  progress?: FusionRunProgress | undefined;
+  usage_so_far?: FusionUsage | undefined;
+  attempts?: FusionFailureList<FusionFailureAttemptMetadata> | undefined;
+  evidence_artifacts?: FusionFailureList<FusionFailureEvidenceArtifact> | undefined;
+  remediation_ids?: FusionFailureSummaryV1['remediation_ids'] | undefined;
+  failure_summary_ref?: FusionArtifactRef | undefined;
+  summary_unavailable_reason?: 'no_durable_summary' | 'manifest_untrusted' | 'summary_integrity_failed' | undefined;
+}
+
 export interface FusionArtifactManifest {
   schema_version: typeof FUSION_MANIFEST_SCHEMA_VERSION;
   run_id: string;

package/src/core/registry.ts

@@ -58,6 +58,7 @@ import {
   resolvePiLaunch,
   type PiLaunchSpec,
 } from './pi-launch.js';
+import { resolveAnthropicAttributionExtensionPath } from './anthropic-attribution-path.js';
 import {
   runWindowsTaskkill,
   type TaskkillOutcome,
@@ -1234,7 +1235,9 @@ export class BackgroundTaskRegistry {
     if (this.shuttingDown)
       throw new Error('Cannot start an attested Pi task while Pi is shutting down');
 
-    const argv = buildAttestedPiArgv(request);
+    const attributionExtensionPath =
+      request.provider === 'anthropic' ? resolveAnthropicAttributionExtensionPath() : undefined;
+    const argv = buildAttestedPiArgv(request, attributionExtensionPath);
     const attestedPiLaunch = resolvePiLaunch({ platform: this.platform });
     assertWindowsCommandLineWithinLimit(
       attestedPiLaunch,

package/src/delegate-child-extension.ts

@@ -7,6 +7,7 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import type { Usage } from '@earendil-works/pi-ai';
 import {
   DELEGATE_RECEIPT_SCHEMA_VERSION,
+  DELEGATE_CAPABILITIES,
   type DelegateRouteAttestation,
   type DelegateSeedV1,
   type DelegateSpillReceipt,
@@ -23,8 +24,10 @@ import {
 /**
  * Package-owned delegate child extension.
  *
- * This runs inside the delegate child Pi process and is the only extension it
- * loads. It is responsible for every guarantee that cannot be enforced from the
+ * This runs inside every delegate child Pi process and is the package-owned
+ * child guard. Anthropic routes load attribution first, and ambient mode may
+ * also execute discovered extensions; this guard remains
+ * responsible for every isolation guarantee that cannot be enforced from the
  * parent:
  *
  * - verifying the frozen seed bytes before the first model call;
@@ -289,6 +292,10 @@ export default function delegateChildExtension(pi: ExtensionAPI): void {
     launchNonce: expectedNonce,
   });
 
+  if (!DELEGATE_CAPABILITIES.includes(seed.capability)) {
+    throw new Error(`delegate child cannot enforce capability ${seed.capability}`);
+  }
+
   const state: GuardState = {
     seed,
     artifactDirAbs,

package/src/delegate-extension.ts

@@ -11,11 +11,17 @@ import { Type, type Static } from 'typebox';
 import type { BgTask, BgTaskSnapshot, StartDelegateTaskOptions } from './core/common.js';
 import { truncateChars } from './core/common.js';
 import { sha256Buffer } from './core/attested-pi-run.js';
-import { readFusionCommittedResult } from './core/fusion/result-package.js';
-import { cloneFusionUsage, type FusionUsage, type FusionWorkflowId } from './core/fusion/types.js';
+import { readFusionCommittedResult, readFusionFailureResult } from './core/fusion/result-package.js';
+import {
+  cloneFusionUsage,
+  type FusionFailureResultView,
+  type FusionUsage,
+  type FusionWorkflowId,
+} from './core/fusion/types.js';
 import {
   DELEGATE_AUTO_DELIVER_MODES,
   DELEGATE_CAPABILITIES,
+  DELEGATE_EXTENSION_MODES,
   DELEGATE_RESULT_TOOL_NAME,
   DELEGATE_TOOL_NAME,
   DelegateError,
@@ -23,6 +29,7 @@ import {
   type DelegateCapability,
   type DelegateDeliveryMode,
   type DelegateBudgetRouteSource,
+  type DelegateExtensionMode,
   type DelegateRoute,
 } from './core/delegate/types.js';
 import {
@@ -62,7 +69,7 @@ const HOOK_EVIDENCE_PATH = fileURLToPath(
   new URL('./core/delegate/hook-contract-evidence.json', import.meta.url),
 );
 
-const DelegateParams = Type.Object(
+export const DelegateParams = Type.Object(
   {
     name: Type.String({
       description: 'Short human-readable task name shown in the bg footer dock. Use 2-6 words.',
@@ -88,6 +95,12 @@ const DelegateParams = Type.Object(
         description: `Capability profile. Only "inspect" (read/search/list, no shell, no writes, no network, no recursion) is supported.`,
       }),
     ),
+    extensionMode: Type.Optional(
+      Type.String({
+        description:
+          'Extension discovery: isolated | ambient. Default isolated. Ambient is for extension-registered providers and executes arbitrary discovered extension code, weakening process isolation.',
+      }),
+    ),
     maxTurns: Type.Optional(
       Type.Number({
         description: `Maximum agent turns. Default ${String(DELEGATE_DEFAULT_MAX_TURNS)}.`,
@@ -137,6 +150,20 @@ const ResultParams = Type.Object(
 type DelegateParamsValue = Static<typeof DelegateParams>;
 type ResultParamsValue = Static<typeof ResultParams>;
 
+const DELEGATE_PARAM_KEYS = new Set([
+  'name',
+  'prompt',
+  'route',
+  'capability',
+  'extensionMode',
+  'maxTurns',
+  'maxToolCalls',
+  'timeoutSeconds',
+  'autoDeliver',
+  'notifyOnCompletion',
+  'triggerOnCompletion',
+]);
+
 export interface DelegateLaunchDetails {
   schema_version: 'pi-background-tasks.delegate-launch.v1';
   task: BgTaskSnapshot;
@@ -146,6 +173,7 @@ export interface DelegateLaunchDetails {
   seed_sha256: string;
   seed_utf8_bytes: number;
   budget: DelegateBudgetRouteSource;
+  extension_mode: DelegateExtensionMode;
   auto_deliver: DelegateAutoDeliverMode;
   notify_on_completion: boolean;
   trigger_on_completion: boolean;
@@ -161,6 +189,16 @@ export interface FusionBackgroundResultDetails {
   answer_bytes?: number | undefined;
   answer_sha256?: string | undefined;
   usage_delivered?: boolean | undefined;
+  answer?: { present: false; reason: 'run_did_not_commit' } | undefined;
+  summary_status?: FusionFailureResultView['summary_status'] | undefined;
+  failure_summary_ref?: FusionFailureResultView['failure_summary_ref'] | undefined;
+  failure?: FusionFailureResultView['failure'] | undefined;
+  progress?: FusionFailureResultView['progress'] | undefined;
+  usage_so_far?: FusionFailureResultView['usage_so_far'] | undefined;
+  attempts?: FusionFailureResultView['attempts'] | undefined;
+  evidence_artifacts?: FusionFailureResultView['evidence_artifacts'] | undefined;
+  remediation_ids?: FusionFailureResultView['remediation_ids'] | undefined;
+  summary_unavailable_reason?: FusionFailureResultView['summary_unavailable_reason'] | undefined;
 }
 
 export type BackgroundResultDetails = DelegateResultDetails | FusionBackgroundResultDetails;
@@ -172,6 +210,7 @@ export interface DelegateResultDetails {
   delivery: DelegateDeliveryMode | 'none';
   route?: { provider: string; model: string } | undefined;
   budget?: DelegateBudgetRouteSource | undefined;
+  extension_mode?: DelegateExtensionMode | undefined;
   answer_bytes?: number | undefined;
   answer_sha256?: string | undefined;
   turns?: number | undefined;
@@ -198,6 +237,15 @@ function requireCapability(value: unknown): DelegateCapability {
   );
 }
 
+function requireExtensionMode(value: unknown): DelegateExtensionMode {
+  if (value === undefined) return 'isolated';
+  if (value === 'isolated' || value === 'ambient') return value;
+  throw new DelegateError(
+    `bg_delegate extensionMode must be one of ${DELEGATE_EXTENSION_MODES.join(', ')}`,
+    { code: 'invalid_arguments', childCreated: false },
+  );
+}
+
 function requireAutoDeliver(value: unknown): DelegateAutoDeliverMode {
   if (value === undefined) return 'never';
   if (value === 'never' || value === 'when_small' || value === 'always') return value;
@@ -293,13 +341,15 @@ export function registerDelegateExtension(
     name: DELEGATE_TOOL_NAME,
     label: 'Background Delegate',
     description:
-      'Launch one background Pi agent seeded with a frozen projection of the current conversation, then return a launch receipt immediately. The child has its own session, a route pinned at launch that is never substituted, and read-only tools. Retrieve its verified answer with bg_result.',
+      'Launch one background Pi agent seeded with a frozen projection of the current conversation, then return a launch receipt immediately. The child has its own session, a route pinned at launch that is never substituted, and read-only tools. Extension discovery is isolated by default; ambient mode supports extension-registered providers but executes arbitrary discovered extension code. Retrieve its verified answer with bg_result.',
     promptSnippet:
       'Delegate an investigation to a background agent that already has this conversation as context',
     promptGuidelines: [
       'Use bg_delegate when work should continue in the background and the worker needs what you already know: it is seeded with a projection of this conversation.',
       'The prompt is authoritative. State exactly what you want investigated and what the answer should contain.',
-      'The delegate is inspect-only: it can read, search, and list files, but cannot run shell commands, edit or write files, use the network, or delegate further.',
+      'The delegate is inspect-only at the model-visible tool boundary: it can read, search, and list files, but cannot run shell commands, edit or write files, use the network, or delegate further.',
+      'Extension discovery is isolated by default. Use extensionMode:"ambient" only when the pinned provider is registered by an ambient user/project extension.',
+      'Ambient mode executes arbitrary discovered extension code in the child process. Tool allowlists do not sandbox extension code, so ambient mode weakens inspect-only process isolation.',
       'Facts that exist only inside omitted tool output are not available to the delegate. Restate such findings in the prompt.',
       'bg_delegate returns immediately. Do not poll; retrieve the answer with bg_result after the terminal notification arrives.',
     ],
@@ -310,6 +360,13 @@ export function registerDelegateExtension(
           code: 'invalid_arguments',
           childCreated: false,
         });
+      const unknownKeys = Object.keys(args).filter((key) => !DELEGATE_PARAM_KEYS.has(key));
+      if (unknownKeys.length > 0) {
+        throw new DelegateError(
+          `bg_delegate contains unsupported key(s): ${unknownKeys.sort().join(', ')}`,
+          { code: 'invalid_arguments', childCreated: false },
+        );
+      }
       const name = args['name'];
       const prompt = args['prompt'];
       if (typeof name !== 'string' || name.trim().length === 0)
@@ -326,6 +383,7 @@ export function registerDelegateExtension(
       const route = requireRoute(args['route']);
       if (route !== undefined) prepared.route = route;
       prepared.capability = requireCapability(args['capability']);
+      prepared.extensionMode = requireExtensionMode(args['extensionMode']);
       prepared.autoDeliver = requireAutoDeliver(args['autoDeliver']);
       const maxTurns = optionalPositiveInteger(args['maxTurns'], 'maxTurns');
       if (maxTurns !== undefined) prepared.maxTurns = maxTurns;
@@ -341,6 +399,7 @@ export function registerDelegateExtension(
     },
     async execute(toolCallId, params, _signal, _onUpdate, ctx) {
       const capability = requireCapability(params.capability);
+      const extensionMode = requireExtensionMode(params.extensionMode);
       const autoDeliver = requireAutoDeliver(params.autoDeliver);
       const hookEvidence = await loadEvidence();
       const route = resolveDelegateRoute({
@@ -370,6 +429,7 @@ export function registerDelegateExtension(
         toolCallId,
         prompt: params.prompt,
         capability,
+        extensionMode,
         route,
         limitOverrides: {
           maxTurns: params.maxTurns,
@@ -408,6 +468,7 @@ export function registerDelegateExtension(
         seed_sha256: prepared.facts.seedSha256,
         seed_utf8_bytes: prepared.preflight.plan.seed_utf8_bytes,
         budget: prepared.facts.budget,
+        extension_mode: extensionMode,
         auto_deliver: autoDeliver,
         notify_on_completion: launchOptions.notifyOnCompletion,
         trigger_on_completion: launchOptions.triggerOnCompletion,
@@ -422,6 +483,7 @@ export function registerDelegateExtension(
             `Seed: ${String(prepared.preflight.plan.seed_utf8_bytes)} bytes, sha256 ${prepared.facts.seedSha256}`,
             `Estimator: family ${prepared.facts.budget.family}, source ${prepared.facts.budget.rate_source.source}, rate ${String(prepared.facts.budget.rate_source.effective_rate_bytes_per_token_x100)}/100 B/tok + ${String(prepared.facts.budget.rate_source.affine_f_tokens)} tokens${prepared.facts.budget.rate_source.warning === null ? '' : `; warning: ${prepared.facts.budget.rate_source.warning}`}`,
             `Capability: ${capability} (read/search/list only)`,
+            `Extension mode: ${extensionMode}${extensionMode === 'ambient' ? ' — WARNING: arbitrary discovered extension code executes in the child; the tool allowlist does not sandbox it, so inspect-only process isolation is weakened.' : ' (ambient extension discovery disabled)'}`,
             `Limits: ${String(prepared.preflight.limits.max_turns)} turns, ${String(prepared.preflight.limits.max_tool_calls)} tool calls, ${String(prepared.preflight.limits.timeout_seconds)}s`,
             `Auto-deliver: ${autoDeliver}`,
             launchOptions.notifyOnCompletion
@@ -443,7 +505,7 @@ export function registerDelegateExtension(
     renderResult(result, _options, theme) {
       const details = result.details;
       return new Text(
-        `${theme.fg('success', '✓ delegated')} ${theme.fg('accent', details.task.id)}\n${theme.fg('dim', `route ${details.route.qualified_id} · seed ${String(details.seed_utf8_bytes)}B · ${details.artifact_dir}`)}`,
+        `${theme.fg('success', '✓ delegated')} ${theme.fg('accent', details.task.id)}\n${theme.fg('dim', `route ${details.route.qualified_id} · extensions ${details.extension_mode} · seed ${String(details.seed_utf8_bytes)}B · ${details.artifact_dir}`)}`,
         0,
         0,
       );
@@ -508,9 +570,48 @@ export function registerDelegateExtension(
           };
         }
         if (task.status !== 'completed' || fusion.outcome?.status !== 'committed') {
-          throw new Error(
-            `Fusion ${task.id} did not commit a result (${task.status}): ${fusion.outcome?.error ?? task.error ?? 'no terminal detail'}`,
-          );
+          const terminal = await readFusionFailureResult({
+            artifactDirAbs: fusion.artifactDirAbs,
+            artifactDir: fusion.artifactDir,
+            runId: fusion.runId,
+            workflow: fusion.workflow,
+          });
+          const state =
+            fusion.outcome?.status === 'cancelled' || task.status === 'killed'
+              ? 'cancelled'
+              : 'failed';
+          const details: FusionBackgroundResultDetails = {
+            schema_version: 'pi-background-tasks.fusion-result-view.v1',
+            task_id: task.id,
+            state,
+            delivery: 'none',
+            workflow: fusion.workflow,
+            artifact_dir: fusion.artifactDir,
+            answer: terminal.answer,
+            summary_status: terminal.summary_status,
+            ...(terminal.failure_summary_ref === undefined
+              ? {}
+              : { failure_summary_ref: terminal.failure_summary_ref }),
+            ...(terminal.failure === undefined ? {} : { failure: terminal.failure }),
+            ...(terminal.progress === undefined ? {} : { progress: terminal.progress }),
+            ...(terminal.usage_so_far === undefined ? {} : { usage_so_far: terminal.usage_so_far }),
+            ...(terminal.attempts === undefined ? {} : { attempts: terminal.attempts }),
+            ...(terminal.evidence_artifacts === undefined
+              ? {}
+              : { evidence_artifacts: terminal.evidence_artifacts }),
+            ...(terminal.remediation_ids === undefined
+              ? {}
+              : { remediation_ids: terminal.remediation_ids }),
+            ...(terminal.summary_unavailable_reason === undefined
+              ? {}
+              : { summary_unavailable_reason: terminal.summary_unavailable_reason }),
+          };
+          return {
+            content: textContent(
+              `Fusion ${task.id} ${state}; no answer was committed. Terminal evidence status: ${terminal.summary_status}. Delivery is none; use only the manifest-bound artifact references in details.`,
+            ),
+            details,
+          };
         }
         const verified = await readFusionCommittedResult({
           artifactDirAbs: fusion.artifactDirAbs,
@@ -579,6 +680,7 @@ export function registerDelegateExtension(
           delivery: 'none',
           artifact_dir: facts.artifactDir,
           budget: facts.budget,
+          extension_mode: facts.extensionMode,
         };
         return {
           content: textContent(
@@ -632,6 +734,7 @@ export function registerDelegateExtension(
         delivery: decision.mode,
         route: verified.package.route,
         budget: facts.budget,
+        extension_mode: facts.extensionMode,
         answer_bytes: verified.package.answer.byte_length,
         answer_sha256: verified.package.answer.sha256,
         turns: verified.package.turns,
@@ -673,6 +776,13 @@ export function registerDelegateExtension(
           0,
           0,
         );
+      if (fusion && (details.state === 'failed' || details.state === 'cancelled')) {
+        return new Text(
+          theme.fg('warning', `${details.state} fusion; no committed answer · ${details.summary_status ?? 'unavailable'}`),
+          0,
+          0,
+        );
+      }
       return new Text(
         `${theme.fg('success', fusion ? '✓ fusion answer' : '✓ delegate answer')} ${theme.fg('dim', `${String(details.answer_bytes ?? 0)}B · ${details.delivery}`)}`,
         0,