pi-background-tasks 0.7.6 → 0.9.0

package/src/delegate-extension.ts

@@ -0,0 +1,587 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  Theme,
+  ToolRenderResultOptions,
+} from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+import { Type, type Static } from 'typebox';
+import type { BgTask, BgTaskSnapshot, StartDelegateTaskOptions } from './core/common.js';
+import { truncateChars } from './core/common.js';
+import {
+  DELEGATE_AUTO_DELIVER_MODES,
+  DELEGATE_CAPABILITIES,
+  DELEGATE_RESULT_TOOL_NAME,
+  DELEGATE_TOOL_NAME,
+  DelegateError,
+  type DelegateAutoDeliverMode,
+  type DelegateCapability,
+  type DelegateDeliveryMode,
+  type DelegateBudgetRouteSource,
+  type DelegateRoute,
+} from './core/delegate/types.js';
+import {
+  DELEGATE_INLINE_ANSWER_BYTES,
+  DELEGATE_DEFAULT_MAX_TOOL_CALLS,
+  DELEGATE_DEFAULT_MAX_TURNS,
+  DELEGATE_DEFAULT_TIMEOUT_SECONDS,
+} from './core/delegate/budget.js';
+import { resolveDelegateRoute } from './core/delegate/launch.js';
+import {
+  decideDelegateDelivery,
+  evaluateDelegateTerminal,
+  inlineTooLarge,
+  prepareDelegateLaunch,
+} from './core/delegate/runner.js';
+import { loadDelegateHookContractEvidence } from './core/delegate/launch.js';
+import type { DelegateHookContractEvidence } from './core/delegate/hook-contract.js';
+
+/**
+ * `bg_delegate` and `bg_result` registration.
+ *
+ * `bg_delegate` launches one background child Pi agent seeded with a frozen
+ * projection of the current conversation. `bg_result` retrieves that child's
+ * hash-verified answer. They ship together: a delegate without a safe retrieval
+ * path would have no way to return its work.
+ */
+
+/**
+ * Shipped copy of the observed Pi hook-contract evidence.
+ *
+ * It is produced by executing a real Pi agent loop in
+ * `tests/scripted-provider/pi-hook-contract.test.ts`, and a package test asserts
+ * the shipped copy is byte-identical to the recorded one, so the runtime gate
+ * and the gate that proved it can never drift apart.
+ */
+const HOOK_EVIDENCE_PATH = fileURLToPath(
+  new URL('./core/delegate/hook-contract-evidence.json', import.meta.url),
+);
+
+const DelegateParams = Type.Object(
+  {
+    name: Type.String({
+      description: 'Short human-readable task name shown in the bg footer dock. Use 2-6 words.',
+    }),
+    prompt: Type.String({
+      description:
+        'Authoritative instruction for the delegate. The projected conversation is supporting background only.',
+    }),
+    route: Type.Optional(
+      Type.Object(
+        {
+          provider: Type.String({ description: 'Exact provider name to pin.' }),
+          model: Type.String({ description: 'Exact provider-local model id to pin.' }),
+        },
+        { additionalProperties: false, description: 'Explicit route. Defaults to the current model.' },
+      ),
+    ),
+    capability: Type.Optional(
+      Type.String({
+        description: `Capability profile. Only "inspect" (read/search/list, no shell, no writes, no network, no recursion) is supported.`,
+      }),
+    ),
+    maxTurns: Type.Optional(
+      Type.Number({ description: `Maximum agent turns. Default ${String(DELEGATE_DEFAULT_MAX_TURNS)}.` }),
+    ),
+    maxToolCalls: Type.Optional(
+      Type.Number({
+        description: `Maximum tool calls. Default ${String(DELEGATE_DEFAULT_MAX_TOOL_CALLS)}.`,
+      }),
+    ),
+    timeoutSeconds: Type.Optional(
+      Type.Number({
+        description: `Wall-clock timeout. Default ${String(DELEGATE_DEFAULT_TIMEOUT_SECONDS)}.`,
+      }),
+    ),
+    autoDeliver: Type.Optional(
+      Type.String({
+        description:
+          'Whether the completion notification carries the answer: never | when_small | always. Default never; retrieve with bg_result.',
+      }),
+    ),
+    notifyOnCompletion: Type.Optional(
+      Type.Boolean({ description: 'Deliver the durable terminal notification. Default true.' }),
+    ),
+    triggerOnCompletion: Type.Optional(
+      Type.Boolean({ description: 'Let that notification start a follow-up turn. Default true.' }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+const ResultParams = Type.Object(
+  {
+    taskId: Type.String({ description: 'Delegate task id returned by bg_delegate.' }),
+    delivery: Type.Optional(
+      Type.String({
+        description:
+          'inline returns the verified answer text; artifact returns metadata plus the artifact reference. Oversized answers are never truncated.',
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+type DelegateParamsValue = Static<typeof DelegateParams>;
+type ResultParamsValue = Static<typeof ResultParams>;
+
+export interface DelegateLaunchDetails {
+  schema_version: 'pi-background-tasks.delegate-launch.v1';
+  task: BgTaskSnapshot;
+  route: { provider: string; model: string; qualified_id: string; origin: string };
+  child_session_id: string;
+  artifact_dir: string;
+  seed_sha256: string;
+  seed_utf8_bytes: number;
+  budget: DelegateBudgetRouteSource;
+  auto_deliver: DelegateAutoDeliverMode;
+  notify_on_completion: boolean;
+  trigger_on_completion: boolean;
+}
+
+export interface DelegateResultDetails {
+  schema_version: 'pi-background-tasks.delegate-result-view.v1';
+  task_id: string;
+  state: 'running' | 'committed' | 'failed' | 'cancelled';
+  delivery: DelegateDeliveryMode | 'none';
+  route?: { provider: string; model: string } | undefined;
+  budget?: DelegateBudgetRouteSource | undefined;
+  answer_bytes?: number | undefined;
+  answer_sha256?: string | undefined;
+  turns?: number | undefined;
+  tool_calls?: number | undefined;
+  usage?: { status: string } | undefined;
+  artifact_dir?: string | undefined;
+  error_code?: string | undefined;
+}
+
+function textContent(text: string) {
+  return [{ type: 'text' as const, text }];
+}
+
+function isRecord(value: unknown): value is Record<PropertyKey, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function requireCapability(value: unknown): DelegateCapability {
+  if (value === undefined) return 'inspect';
+  if (value === 'inspect') return 'inspect';
+  throw new DelegateError(
+    `bg_delegate capability must be one of ${DELEGATE_CAPABILITIES.join(', ')}. Writable profiles are deliberately out of scope in this version.`,
+    { 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;
+  throw new DelegateError(
+    `bg_delegate autoDeliver must be one of ${DELEGATE_AUTO_DELIVER_MODES.join(', ')}`,
+    { code: 'invalid_arguments', childCreated: false },
+  );
+}
+
+function requireDelivery(value: unknown): DelegateDeliveryMode | undefined {
+  if (value === undefined) return undefined;
+  if (value === 'inline' || value === 'artifact') return value;
+  throw new DelegateError('bg_result delivery must be inline or artifact', {
+    code: 'invalid_arguments',
+    childCreated: false,
+  });
+}
+
+function requireRoute(value: unknown): DelegateRoute | undefined {
+  if (value === undefined) return undefined;
+  if (!isRecord(value)) {
+    throw new DelegateError('bg_delegate route must be an object', {
+      code: 'invalid_arguments',
+      childCreated: false,
+    });
+  }
+  const provider = value['provider'];
+  const model = value['model'];
+  if (typeof provider !== 'string' || provider.length === 0)
+    throw new DelegateError('bg_delegate route.provider must be a non-empty string', {
+      code: 'invalid_arguments',
+      childCreated: false,
+    });
+  if (typeof model !== 'string' || model.length === 0)
+    throw new DelegateError('bg_delegate route.model must be a non-empty string', {
+      code: 'invalid_arguments',
+      childCreated: false,
+    });
+  return { provider, model };
+}
+
+function optionalPositiveInteger(value: unknown, label: string): number | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isInteger(value) || value <= 0)
+    throw new DelegateError(`bg_delegate ${label} must be a positive integer`, {
+      code: 'invalid_arguments',
+      childCreated: false,
+    });
+  return value;
+}
+
+export interface DelegateExtensionDependencies {
+  startDelegateTask: (
+    ctx: ExtensionContext,
+    options: StartDelegateTaskOptions,
+  ) => Promise<BgTask>;
+  snapshot: (task: BgTask) => BgTaskSnapshot;
+  resolveTask: (idOrPrefix: string) => BgTask;
+  /** Overridable so tests can supply observed evidence without touching disk. */
+  loadHookEvidence?: (() => Promise<DelegateHookContractEvidence>) | undefined;
+}
+
+async function defaultHookEvidence(): Promise<DelegateHookContractEvidence> {
+  let raw: string;
+  try {
+    raw = await readFile(HOOK_EVIDENCE_PATH, 'utf8');
+  } catch (error) {
+    throw new DelegateError(
+      `bg_delegate cannot verify the Pi hook contract: the recorded evidence at ${HOOK_EVIDENCE_PATH} is unreadable (${error instanceof Error ? error.message : String(error)}). No child was created.`,
+      {
+        code: 'delegate_hook_contract_unsupported',
+        childCreated: false,
+        remediation: [
+          'Run the Pi hook characterisation gate to regenerate the evidence for this Pi build.',
+          'The guard is never bypassed when its evidence is missing.',
+        ],
+      },
+    );
+  }
+  return loadDelegateHookContractEvidence(raw);
+}
+
+export function registerDelegateExtension(
+  pi: ExtensionAPI,
+  deps: DelegateExtensionDependencies,
+): void {
+  const loadEvidence = deps.loadHookEvidence ?? defaultHookEvidence;
+
+  pi.registerTool<typeof DelegateParams, DelegateLaunchDetails>({
+    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.',
+    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.',
+      '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.',
+    ],
+    parameters: DelegateParams,
+    prepareArguments(args): DelegateParamsValue {
+      if (!isRecord(args))
+        throw new DelegateError('bg_delegate arguments must be an object', {
+          code: 'invalid_arguments',
+          childCreated: false,
+        });
+      const name = args['name'];
+      const prompt = args['prompt'];
+      if (typeof name !== 'string' || name.trim().length === 0)
+        throw new DelegateError('bg_delegate requires a non-empty name', {
+          code: 'invalid_arguments',
+          childCreated: false,
+        });
+      if (typeof prompt !== 'string' || prompt.trim().length === 0)
+        throw new DelegateError('bg_delegate requires a non-blank prompt', {
+          code: 'invalid_arguments',
+          childCreated: false,
+        });
+      const prepared: DelegateParamsValue = { name, prompt };
+      const route = requireRoute(args['route']);
+      if (route !== undefined) prepared.route = route;
+      prepared.capability = requireCapability(args['capability']);
+      prepared.autoDeliver = requireAutoDeliver(args['autoDeliver']);
+      const maxTurns = optionalPositiveInteger(args['maxTurns'], 'maxTurns');
+      if (maxTurns !== undefined) prepared.maxTurns = maxTurns;
+      const maxToolCalls = optionalPositiveInteger(args['maxToolCalls'], 'maxToolCalls');
+      if (maxToolCalls !== undefined) prepared.maxToolCalls = maxToolCalls;
+      const timeoutSeconds = optionalPositiveInteger(args['timeoutSeconds'], 'timeoutSeconds');
+      if (timeoutSeconds !== undefined) prepared.timeoutSeconds = timeoutSeconds;
+      const notify = args['notifyOnCompletion'];
+      if (typeof notify === 'boolean') prepared.notifyOnCompletion = notify;
+      const trigger = args['triggerOnCompletion'];
+      if (typeof trigger === 'boolean') prepared.triggerOnCompletion = trigger;
+      return prepared;
+    },
+    async execute(toolCallId, params, _signal, _onUpdate, ctx) {
+      const capability = requireCapability(params.capability);
+      const autoDeliver = requireAutoDeliver(params.autoDeliver);
+      const hookEvidence = await loadEvidence();
+      const route = resolveDelegateRoute({
+        requested: params.route,
+        currentModel:
+          ctx.model === undefined
+            ? undefined
+            : {
+                provider: ctx.model.provider,
+                id: ctx.model.id,
+                contextWindow: ctx.model.contextWindow,
+              },
+        availableModels: ctx.modelRegistry
+          .getAll()
+          .map((model) => ({
+            provider: model.provider,
+            id: model.id,
+            contextWindow: model.contextWindow,
+          })),
+        thinkingLevel: pi.getThinkingLevel(),
+      });
+
+      const prepared = await prepareDelegateLaunch({
+        ctx: {
+          cwd: ctx.cwd,
+          sessionManager: ctx.sessionManager,
+          getSystemPrompt: () => ctx.getSystemPrompt(),
+        },
+        toolCallId,
+        prompt: params.prompt,
+        capability,
+        route,
+        limitOverrides: {
+          maxTurns: params.maxTurns,
+          maxToolCalls: params.maxToolCalls,
+          timeoutSeconds: params.timeoutSeconds,
+        },
+        hookEvidence,
+        cwd: ctx.cwd,
+        sessionId: ctx.sessionManager.getSessionId(),
+        autoDeliver,
+      });
+
+      const launchOptions: StartDelegateTaskOptions = {
+        name: params.name,
+        argv: prepared.argv,
+        stdinBytes: prepared.stdinBytes,
+        env: prepared.env,
+        facts: prepared.facts,
+        notifyOnCompletion: params.notifyOnCompletion ?? true,
+        triggerOnCompletion: params.triggerOnCompletion ?? true,
+        timeoutSeconds: prepared.preflight.limits.timeout_seconds,
+      };
+      const task = await deps.startDelegateTask(ctx, launchOptions);
+
+      const details: DelegateLaunchDetails = {
+        schema_version: 'pi-background-tasks.delegate-launch.v1',
+        task: deps.snapshot(task),
+        route: {
+          provider: route.provider,
+          model: route.model,
+          qualified_id: route.qualified_id,
+          origin: route.origin,
+        },
+        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,
+        budget: prepared.facts.budget,
+        auto_deliver: autoDeliver,
+        notify_on_completion: launchOptions.notifyOnCompletion,
+        trigger_on_completion: launchOptions.triggerOnCompletion,
+      };
+      return {
+        content: textContent(
+          [
+            `Started delegate ${params.name} (${task.id})`,
+            `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}`,
+            `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)`,
+            `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
+              ? `Terminal notification: enabled.${launchOptions.triggerOnCompletion ? ' It will start a follow-up turn.' : ' It will not start a turn.'}`
+              : 'Terminal notification: disabled.',
+            `Retrieve the verified answer with ${DELEGATE_RESULT_TOOL_NAME}({taskId:"${task.id}"}). Do not poll.`,
+          ].join('\n'),
+        ),
+        details,
+      };
+    },
+    renderCall(args, theme) {
+      return new Text(
+        `${theme.fg('toolTitle', theme.bold('bg_delegate '))}${theme.fg('muted', truncateChars(args.name, 60))}`,
+        0,
+        0,
+      );
+    },
+    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}`)}`,
+        0,
+        0,
+      );
+    },
+  });
+
+  pi.registerTool<typeof ResultParams, DelegateResultDetails>({
+    name: DELEGATE_RESULT_TOOL_NAME,
+    label: 'Delegate Result',
+    description:
+      'Retrieve the hash-verified answer from a bg_delegate task. Never blocks: a running task returns a typed not-ready result. A completed answer is verified against its recorded SHA-256 before it is returned, and an oversized answer is never truncated.',
+    promptSnippet: 'Retrieve the verified answer from a completed bg_delegate task',
+    promptGuidelines: [
+      'Call bg_result once the delegate terminal notification has arrived. It never blocks and must not be polled.',
+      'A not-ready result means the delegate is still running; end the turn and wait for the notification.',
+    ],
+    parameters: ResultParams,
+    prepareArguments(args): ResultParamsValue {
+      if (!isRecord(args))
+        throw new DelegateError('bg_result arguments must be an object', {
+          code: 'invalid_arguments',
+          childCreated: false,
+        });
+      const taskId = args['taskId'];
+      if (typeof taskId !== 'string' || taskId.trim().length === 0)
+        throw new DelegateError('bg_result requires taskId', {
+          code: 'invalid_arguments',
+          childCreated: false,
+        });
+      const prepared: ResultParamsValue = { taskId };
+      const delivery = requireDelivery(args['delivery']);
+      if (delivery !== undefined) prepared.delivery = delivery;
+      return prepared;
+    },
+    async execute(_toolCallId, params) {
+      let task: BgTask;
+      try {
+        task = deps.resolveTask(params.taskId);
+      } catch (error) {
+        throw new DelegateError(
+          `bg_result does not know task ${params.taskId}: ${error instanceof Error ? error.message : String(error)}`,
+          { code: 'task_unknown', childCreated: false },
+        );
+      }
+      const facts = task.delegate;
+      if (facts === undefined) {
+        throw new DelegateError(
+          `bg_result task ${task.id} is not a bg_delegate task; use bg_logs for ordinary background tasks`,
+          { code: 'task_unknown', childCreated: false },
+        );
+      }
+      if (task.status === 'running') {
+        const details: DelegateResultDetails = {
+          schema_version: 'pi-background-tasks.delegate-result-view.v1',
+          task_id: task.id,
+          state: 'running',
+          delivery: 'none',
+          artifact_dir: facts.artifactDir,
+          budget: facts.budget,
+        };
+        return {
+          content: textContent(
+            `Delegate ${task.id} is still running. This is not an error and bg_result never blocks. End this turn; the terminal notification will wake you, then call bg_result again.`,
+          ),
+          details,
+        };
+      }
+
+      const terminal = await evaluateDelegateTerminal({
+        artifactDirAbs: facts.artifactDirAbs,
+        taskId: facts.taskId,
+        launchNonce: facts.launchNonce,
+        seedSha256: facts.seedSha256,
+        route: { provider: facts.route.provider, model: facts.route.model },
+        taskStatus: task.status === 'completed' ? 'completed' : task.status,
+        taskError: task.error,
+      });
+
+      if (terminal.error !== undefined || terminal.result === undefined) {
+        const failure =
+          terminal.error ??
+          new DelegateError(`delegate ${task.id} produced no verified answer`, {
+            code: 'result_unavailable',
+            childCreated: true,
+            taskId: task.id,
+            artifactDir: facts.artifactDir,
+          });
+        throw new Error(failure.describe(), { cause: failure });
+      }
+
+      const verified = terminal.result;
+      const requestedDelivery = requireDelivery(params.delivery);
+      const decision = decideDelegateDelivery(
+        verified.package.answer.byte_length,
+        requestedDelivery,
+      );
+      if (requestedDelivery === 'inline' && decision.mode === 'artifact') {
+        const failure = inlineTooLarge(
+          task.id,
+          facts.artifactDir,
+          verified.package.answer.byte_length,
+        );
+        throw new Error(failure.describe(), { cause: failure });
+      }
+
+      const details: DelegateResultDetails = {
+        schema_version: 'pi-background-tasks.delegate-result-view.v1',
+        task_id: task.id,
+        state: 'committed',
+        delivery: decision.mode,
+        route: verified.package.route,
+        budget: facts.budget,
+        answer_bytes: verified.package.answer.byte_length,
+        answer_sha256: verified.package.answer.sha256,
+        turns: verified.package.turns,
+        tool_calls: verified.package.tool_calls,
+        usage: { status: verified.package.usage.status },
+        artifact_dir: facts.artifactDir,
+      };
+      const header = [
+        `Delegate ${task.id} completed on ${verified.package.route.provider}/${verified.package.route.model}.`,
+        `Answer: ${String(verified.package.answer.byte_length)} bytes, sha256 ${verified.package.answer.sha256} (verified).`,
+        `Turns: ${String(verified.package.turns)} · tool calls: ${String(verified.package.tool_calls)} · usage: ${verified.package.usage.status}`,
+        `Artifacts: ${facts.artifactDir}`,
+        `Estimator: family ${facts.budget.family}, source ${facts.budget.rate_source.source}, rate ${String(facts.budget.rate_source.effective_rate_bytes_per_token_x100)}/100 B/tok + ${String(facts.budget.rate_source.affine_f_tokens)} tokens${facts.budget.rate_source.warning === null ? '' : `; warning: ${facts.budget.rate_source.warning}`}`,
+      ].join('\n');
+      if (decision.mode === 'artifact') {
+        return {
+          content: textContent(
+            `${header}\nDelivery: artifact (${decision.reason}). The complete verified answer is in ${facts.artifactDir}/result.json. It was not truncated.`,
+          ),
+          details,
+        };
+      }
+      return { content: textContent(`${header}\n\n${verified.answer}`), details };
+    },
+    renderCall(args, theme) {
+      return new Text(
+        `${theme.fg('toolTitle', theme.bold('bg_result '))}${theme.fg('accent', args.taskId)}`,
+        0,
+        0,
+      );
+    },
+    renderResult(result, options: ToolRenderResultOptions, theme: Theme) {
+      void options;
+      const details = result.details;
+      if (details.state === 'running')
+        return new Text(theme.fg('warning', `delegate ${details.task_id} still running`), 0, 0);
+      return new Text(
+        `${theme.fg('success', '✓ delegate answer')} ${theme.fg('dim', `${String(details.answer_bytes ?? 0)}B · ${details.delivery}`)}`,
+        0,
+        0,
+      );
+    },
+  });
+
+  pi.on('session_start', () => {
+    const active = pi.getActiveTools();
+    const missing = [DELEGATE_TOOL_NAME, DELEGATE_RESULT_TOOL_NAME].filter(
+      (name) => !active.includes(name),
+    );
+    if (missing.length > 0) pi.setActiveTools([...active, ...missing]);
+  });
+}
+
+export { DELEGATE_INLINE_ANSWER_BYTES };

package/src/extension.ts

@@ -47,6 +47,7 @@ import {
   type TaskManagerResult,
 } from './ui/background-tasks-manager.js';
 import { registerFusionExtension } from './fusion-extension.js';
+import { registerDelegateExtension } from './delegate-extension.js';
 
 /**
  * Project-local Pi background task manager.
@@ -232,6 +233,15 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
     isShuttingDown: () => registry.isShuttingDown(),
   });
 
+  registerDelegateExtension(pi, {
+    startDelegateTask: async (ctx, options) => {
+      currentCtx = ctx;
+      return registry.startDelegateTask(ctx, options);
+    },
+    snapshot: (task) => registry.snapshot(task),
+    resolveTask: (idOrPrefix) => registry.resolveTask(idOrPrefix),
+  });
+
   function unseenFinishedTasks(): BgTask[] {
     return registry
       .allTasks()