pi-background-tasks 2.1.4 → 2.4.0

package/src/delegate-extension.ts

@@ -21,6 +21,7 @@ import {
 import {
   DELEGATE_AUTO_DELIVER_MODES,
   DELEGATE_CAPABILITIES,
+  DELEGATE_EXTENSION_MODES,
   DELEGATE_RESULT_TOOL_NAME,
   DELEGATE_TOOL_NAME,
   DelegateError,
@@ -28,6 +29,7 @@ import {
   type DelegateCapability,
   type DelegateDeliveryMode,
   type DelegateBudgetRouteSource,
+  type DelegateExtensionMode,
   type DelegateRoute,
 } from './core/delegate/types.js';
 import {
@@ -67,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.',
@@ -93,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)}.`,
@@ -142,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;
@@ -151,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;
@@ -187,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;
@@ -213,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;
@@ -308,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.',
     ],
@@ -325,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)
@@ -341,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;
@@ -356,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({
@@ -385,6 +429,7 @@ export function registerDelegateExtension(
         toolCallId,
         prompt: params.prompt,
         capability,
+        extensionMode,
         route,
         limitOverrides: {
           maxTurns: params.maxTurns,
@@ -421,8 +466,9 @@ export function registerDelegateExtension(
         child_session_id: prepared.preflight.childSessionId,
         artifact_dir: prepared.facts.artifactDir,
         seed_sha256: prepared.facts.seedSha256,
-        seed_utf8_bytes: prepared.preflight.plan.seed_utf8_bytes,
+        seed_utf8_bytes: Buffer.byteLength(prepared.preflight.seed.serialized, 'utf8'),
         budget: prepared.facts.budget,
+        extension_mode: extensionMode,
         auto_deliver: autoDeliver,
         notify_on_completion: launchOptions.notifyOnCompletion,
         trigger_on_completion: launchOptions.triggerOnCompletion,
@@ -434,9 +480,11 @@ export function registerDelegateExtension(
             `Route pinned: ${route.qualified_id} (${route.origin}); it is never substituted.`,
             `Child session: ${prepared.preflight.childSessionId} (separate from this session)`,
             `Artifacts: ${prepared.facts.artifactDir}`,
-            `Seed: ${String(prepared.preflight.plan.seed_utf8_bytes)} bytes, sha256 ${prepared.facts.seedSha256}`,
+            `Seed: ${String(Buffer.byteLength(prepared.preflight.seed.serialized, 'utf8'))} bytes, sha256 ${prepared.facts.seedSha256}`,
+            `Child prompt: ${String(prepared.preflight.plan.child_prompt_utf8_bytes)} bytes; launch estimate ${String(prepared.preflight.plan.launch_input_tokens_upper_bound)} / ${String(prepared.preflight.plan.route.allowed_input_tokens)} allowed input tokens; protected retained-growth runway ${String(prepared.preflight.plan.retained_growth_budget_tokens)} tokens.`,
             `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
@@ -458,7 +506,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,
       );
@@ -633,6 +681,7 @@ export function registerDelegateExtension(
           delivery: 'none',
           artifact_dir: facts.artifactDir,
           budget: facts.budget,
+          extension_mode: facts.extensionMode,
         };
         return {
           content: textContent(
@@ -650,6 +699,8 @@ export function registerDelegateExtension(
         route: { provider: facts.route.provider, model: facts.route.model },
         taskStatus: task.status === 'completed' ? 'completed' : task.status,
         taskError: task.error,
+        taskOutputPath: task.outputPath,
+        taskOutputAbsPath: task.outputAbsPath,
       });
 
       if (terminal.error !== undefined || terminal.result === undefined) {
@@ -686,6 +737,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,