pi-background-tasks

Keep Pi moving while long jobs, delegated investigations, and fixed-purpose multi-model Fusion work run in the background.

pi-background-tasks adds background jobs, delegated agents, and multi-model Fusion for Pi:

• Run long work without blocking: start named shell jobs, keep talking to Pi, and get durable completion notifications when they finish.
• Delegate context-aware investigation: launch one route-pinned, inspect-only child Pi agent seeded with a frozen projection of the current conversation, then retrieve a hash-verified result.
• Combine model perspectives through fixed-purpose Fusion: run three candidate children, blind evaluation, optional bounded evaluator repair, and merger for reasoning, investigation, targeted URL research, or validation review.
• Keep Anthropic subscription traffic attributed and compatible: by default, apply the package-owned Claude Code OAuth attribution, cache policy, and SPS-derived line-start prompt sanitization to parent Anthropic routes without an external sanitizer dependency; isolated package children retain mandatory attribution even when ambient parent attribution is disabled.

| Fact | Value | | --- | --- | | Package | pi-background-tasks | | Version | 2.6.10 | | Node engine | >=22.19.0 | | Pi entrypoints | ./dist/extensions/anthropic-attribution.js, ./dist/extensions/background-tasks.js | | Package image | logo.png |

| Surface kind | Configured variants | Available by default | | --- | --- | --- | | command | 11 | 11 | | tool | 11 | 11 | | shortcut | 3 | 2 | | renderer | 2 | 2 | | eventbus | 2 | 2 | | workflow | 4 | 4 |

Public commands: /bg, /bg-clear, /bg-tasks, /bg-update, /claude-cache, /fusion, /fusion-models, /jobs, /kill, /logs, /tasks.

Public tools: bg_delegate, bg_kill, bg_logs, bg_result, bg_run, bg_run_pi_attested, bg_status, fusion_investigate, fusion_reason, fusion_research, fusion_validate.

Configuration-dependent surfaces

| Surface | Availability | Default | | --- | --- | --- | | command:claude-cache | feature:attribution | yes | | command:fusion | feature:fusion | yes | | command:fusion-models | feature:fusion | yes | | tool:bg_delegate | feature:delegate | yes | | tool:bg_result | any(feature:delegate,feature:fusion) | yes | | tool:bg_run_pi_attested | feature:attested | yes | | tool:fusion_investigate | feature:fusion | yes | | tool:fusion_reason | feature:fusion | yes | | tool:fusion_research | feature:fusion | yes | | tool:fusion_validate | feature:fusion | yes | | shortcut:ctrl+alt+b | dock:ctrl+alt+b | no | | shortcut:shift+down | dock:shift+down | yes | | renderer:fusion-result | feature:fusion | yes | | workflow:investigate | feature:fusion | yes | | workflow:reason | feature:fusion | yes | | workflow:research | feature:fusion | yes | | workflow:validate | feature:fusion | yes |

Full owner map and generated contracts live in docs/INDEX.md.

“Available by default” means after Pi has initialized extensions. Normal TUI/RPC/print/JSON modes do this; SDK embedders must provide a counted bindExtensions() binding and ensure post-reload binding. Bare createAgentSession() and empty/mode-only reload are blocked by the current public host lifecycle API. See Getting started.

Why use it?

| You want to... | Use this package because... | |---|---| | Start a dev server, watch build, migration dry run, or long check | bg_run and /bg return immediately, write durable output files, show a footer dock, and notify on terminal state. Ordinary isAgent:false jobs can explicitly keep the same live execution across a real same-process reload. | | Let Pi keep working instead of sleeping or polling | Default bg_run completion delivery sends a durable terminal notification and can wake a follow-up turn. | | Ask a second agent to inspect the repo with the current conversation as context | bg_delegate starts one read/search/list child, isolated from ambient extensions by default; bg_result verifies the committed result before returning it. | | Compare model perspectives without exposing arbitrary parent context | Fusion children receive only the workflow input and fixed tool policy; no silent route substitution or fallback is used on delegate/Fusion paths. | | Produce local evidence for a direct Pi run | bg_run_pi_attested records local same-user-writable artifacts and hashes after a successful structured child Pi task. | | Use Anthropic subscription OAuth consistently | The default ambient provider applies attribution and SPS-derived line-start sanitization; /claude-cache shows or changes session cache retention. Isolated package-owned Anthropic children always use the mandatory child entrypoint. |

Install

Version information comes from package.json. Use npm @latest for normal installs; use git main only when you intentionally want the current repository state.

# Global install from npm
pi install npm:pi-background-tasks@latest

# Project-local install from npm
pi install npm:pi-background-tasks@latest -l

# Git main branch; not a release tag
pi install git:github.com/ismailsaleekh/pi-background-tasks@main

# Project-local git main install
pi install git:github.com/ismailsaleekh/pi-background-tasks@main -l

# Local checkout/package path, run from this package directory
pi install .
pi install . -l

Local paths are loaded from disk without copying; use the path to this package from your current directory.

Quick start: useful in under five minutes

1. Install and start Pi in a project.

2. Launch a background command:

   /bg --name "Typecheck watch" npm run typecheck -- --watch

   /bg starts a tracked shell task and returns the task id plus output path. User-launched /bg tasks notify in the UI but do not automatically wake a follow-up model turn. Add one leading --survive-reload only when this ordinary shell process must keep running across a real same-process /reload; default tasks are still killed.

3. Open the footer dock with the default Shift↓ binding or list tasks:

   /jobs

4. Read bounded output only when you need it:

   /logs b12ab34c 20000

5. Let a child agent inspect while you continue:

   {"name":"Config reader","prompt":"Inspect the repository configuration files and report where background task settings are documented. Include file paths and quote only the relevant lines.","capability":"inspect"}

   Call this with bg_delegate. When its terminal notification arrives, retrieve the answer deliberately:

   {"taskId":"<task id from bg_delegate>","delivery":"inline"}

   Call this with bg_result. Retrieval is hash-verified and never silently truncated.

6. For a self-contained synthesis, start Fusion in the background:

   {"prompt":"Compare the tradeoffs between a watcher, a one-shot build, and a delegated repo inspection for a large refactor."}

   Call this with fusion_reason, or use /fusion <prompt> interactively. The launch returns after durable preflight; wait for its terminal notification, then retrieve the verified result with bg_result.

More walkthrough detail: Getting started.

Select capabilities and avoid shortcut conflicts

The default remains the complete historical surface. To run only process tasks, set:

PI_BG_FEATURES=process pi

PI_BG_FEATURES accepts a strict unique comma-separated set from process,delegate,fusion,attested,attribution; process is mandatory. bg_result is derived and appears exactly once when delegate or Fusion is enabled. Disabled tools, commands, renderers, and ambient attribution are absent from registration and remain absent after reload.

Choose the dock key independently:

PI_BG_DOCK_SHORTCUT=ctrl+alt+b pi  # avoid a Shift+Down owner
PI_BG_DOCK_SHORTCUT=off pi         # use /tasks or /bg-tasks

Accepted values are exactly shift+down (default), ctrl+alt+b, and off. Invalid settings fail startup with pi_bg_config_invalid; they do not silently restore defaults. /tasks, /bg-tasks, and the separate Ctrl+Alt+C clear fallback remain available. These flags select functionality; they do not claim a cold-start performance improvement.

Full contract: Configuration and Shortcuts and dock.

Pick the right workflow

| Workflow | Blocking? | Context | Tools/network/write boundary | Best for | Expected behavior | |---|---:|---|---|---|---| | Ordinary foreground Pi work | Yes | Full current session | Whatever tools the active session has | Short reads/edits/commands where you want live back-and-forth | Pi waits for the work before responding. | | /bg | No | No model child unless your command starts one | Runs your shell command; not sandboxed | User-started local commands, servers, watches | UI notification and footer tracking; /bg uses notification-only by default. Optional --survive-reload is ordinary-shell-only. | | bg_run | No | No model child unless command starts one | Runs your shell command; not sandboxed | Agent-started long commands | Returns task id/output path; defaults to notification plus automatic follow-up wake. Optional surviveReload:true requires isAgent:false. For an Anthropic child pi, do not pass --no-extensions unless you also explicitly load this package's attribution extension. | | bg_delegate + bg_result | No launch; retrieval is point-in-time | Frozen visible conversation projection | Inspect-only child: read, grep, find, ls, artifact read; no shell, writes, network, recursion | Context-aware read-only investigation while parent continues | Launch returns immediately; result is committed by child and hash-verified by retrieval. | | bg_run_pi_attested | No | Prompt passed to one direct child Pi run | Direct pi --mode json; no shell command; writes requested report path | Evidence-oriented direct Pi task | Emits local attestation sidecar only after successful completion. | | /fusion / fusion_reason | Background launch; point-in-time bg_result retrieval | Versioned conversation projection plus prompt | Candidates/evaluator/repair/merger run with no tools | Self-contained reasoning and synthesis | Returns after durable preflight; three candidates → blind evaluator → optional bounded repair → merger. | | fusion_investigate | Background launch; point-in-time bg_result retrieval | Clean task input only | Candidate read-only repo tools; evaluator/repair/merger no tools | Independent repo investigation | Restate needed facts; continue only independent work while the live repository is inspected. | | fusion_research | Background launch; point-in-time bg_result retrieval | Clean task input only | Candidate read-only repo tools plus targeted fetch of caller-supplied public URLs only | URL-backed synthesis | Targeted URL retrieval, not web search. | | fusion_validate | Background launch; point-in-time bg_result retrieval | Clean task input only | Advisory read-only validation review | Second-opinion review of completed work | Do not mutate the reviewed scope while it runs; not a substitute for mechanical gates. |

See Choose a workflow for a decision tree and tradeoffs.

Copy-paste examples

bg_run: start long shell work

{
  "name": "Docs preview",
  "command": "npm run docs:dev",
  "isAgent": false,
  "timeoutSeconds": 3600,
  "surviveReload": true
}

Expected: returns immediately with a task id, PID when available, and .pi/tasks/...output. Here the explicit flag retains that exact child/id/PID/nonce/path, launch policy, absolute timeout, and cumulative cap across a supported real reload. Omit it for compatible kill-on-reload behavior. New/resume/fork/clone/quit, hard crash, process restart, empty/mode-only SDK reload, and direct AgentSession.dispose() are not supported survival paths. The command runs as an ordinary local shell command with your user permissions; it can invoke networked tools or paid services if the command itself does so.

If bg_run starts an Anthropic child pi, keep normal extension discovery enabled when ambient attribution is enabled. Do not add --no-extensions unless the command also supplies this package's always-on extensions/anthropic-attribution-child.ts via -e/--extension; bg_run does not rewrite arbitrary shell argv.

bg_delegate: context-seeded read-only investigation

{
  "name": "Route audit",
  "prompt": "Inspect the package source and identify where delegate route pinning is enforced. Return file paths, function names, and a short explanation. If a fact exists only in omitted parent tool output, say it is unavailable rather than guessing.",
  "capability": "inspect",
  "extensionMode": "isolated",
  "autoDeliver": "never"
}

Then retrieve:

{
  "taskId": "<delegate task id>",
  "delivery": "inline"
}

Expected: bg_delegate returns a launch receipt immediately. bg_result returns a typed not-ready result while running; after commit it verifies package identity, seed hash, route, block hashes, and aggregate hash before returning bytes. Oversized answers become explicit artifact references, not truncated inline text.

extensionMode defaults to "isolated", which disables ambient extension discovery. If the pinned provider exists only because a user/project Pi extension registers it, opt into "ambient". Ambient mode still loads the delegate guard and keeps the inspect tool allowlist plus skill/template/theme/context restrictions, but it executes arbitrary discovered extension code. Tool allowlists do not sandbox that code, so ambient mode weakens inspect-only process isolation. The call never accepts extension paths and never substitutes the pinned route.

bg_run_pi_attested: local evidence for one Pi child

{
  "name": "Migration report",
  "provider": "openai-codex",
  "model": "gpt-5.5",
  "prompt": "Inspect the repository and write a concise migration report to reports/migration.md.",
  "reportPath": "reports/migration.md",
  "timeoutSeconds": 1800
}

Expected: launches exactly one direct pi --mode json child using structured provider/model fields. It rejects direct API-key/auth-file launch arguments and only writes the attestation sidecar after successful completion and durable hashes. The attestation is local evidence, not cryptographic proof against a compromised machine or provider.

Fusion tools

{"prompt":"Design a rollback strategy for a risky database migration. Include assumptions and failure modes."}

Use with fusion_reason for self-contained synthesis.

{
  "objective": "Find how background task output is capped and surfaced.",
  "background": ["We are evaluating pi-background-tasks behavior for long-running commands."],
  "deliverable": "File paths, constants, defaults, and user-visible behavior.",
  "scope": ["src"],
  "constraints": ["Read-only inspection only."]
}

Use with fusion_investigate.

{
  "objective": "Summarize the installation syntax Pi documents for packages.",
  "background": ["We need package README install examples to match Pi package docs."],
  "deliverable": "A short summary with caveats.",
  "sources": [
    {"url":"https://github.com/earendil-works/pi-coding-agent","purpose":"Pi package documentation repository"}
  ]
}

Use with fusion_research. Only declared public http(s) URLs may be fetched; this is not a search tool.

{
  "objective": "Review whether a documentation-only change is ready to ship.",
  "background": ["The change edits README and package-local docs only."],
  "changeSummary": "Replaced monolithic README with landing page and moved operational details into docs.",
  "scope": ["README.md", "docs/getting-started.md", "docs/choose-a-workflow.md"],
  "acceptanceCriteria": ["Install commands are accurate", "Safety limitations are explicit", "Examples match public schemas"],
  "verification": {
    "status": "provided",
    "evidence": [{"check":"Focused link check", "outcome":"All local README links resolve"}]
  }
}

Use with fusion_validate for advisory read-only review.

Footer dock

When tasks are running or unseen completions exist, the footer shows a compact bg ... segment. Press the configured Shift↓ (default) or Ctrl+Alt+B binding to open the focused bottom dock, or use /tasks when the key is off. Use /bg-clear to acknowledge finished-task footer notices in any terminal.

| Control | Action | |---|---| | configured Shift↓ / Ctrl+Alt+B, or /tasks | Open the dock | | /bg-clear | Clear finished-task notices | | ↑ / ↓, PageUp / PageDown | Move through list or scroll output tail | | Enter / → | Inspect details | | ← | Return to list | | k | Stop selected running task | | R | Rerun selected command | | c | Show copyable output path | | x / Esc / q | Close dock |

Agent tasks launched through pi -p ... or pi --mode json ... and marked isAgent:true can show task-owned model/context/token/tool telemetry. Missing child telemetry is shown as unavailable, not synthesized as zero.

Architecture, trust, and safety

• Runtime task files live under .pi/tasks/<session-id>-<pid>/; Fusion artifacts under .pi/fusion/...; delegate artifacts under .pi/delegate/....
• Delegate launch budgeting uses backed route-family calibration for eligible large prompts and records a provable conservative counter-forecast across every byte class. During investigation, text and image-bearing tool output spill losslessly when retaining them would consume protected final-answer runway—even below the normal 64 KiB per-result threshold. Exact artifact ranges return as base64, final capture excludes intermediate tool-use narration, and near the runway boundary tools are disabled for graceful finalization. Runtime token estimates are advisory; Pi/provider own live context admission, avoiding Fusion BUG-185-style false refusals.
• Shell jobs are tracked by the package, but they are not sandboxed. Treat commands as local processes with your permissions and credentials.
• Delegate and Fusion child Pi processes are route-pinned where applicable; delegate/Fusion paths do not silently substitute routes.
• Fusion uses direct child pi --mode text processes, not direct completion APIs. Frontier Fusion routes are admitted only through Pi Anthropic or Codex subscription OAuth; metered frontier API credentials are rejected before child creation.
• Normal installations load a feature-aware ambient Claude Code OAuth attribution/sanitization entrypoint for parent Anthropic sessions; non-Anthropic sessions are unchanged. The default enables it, while omitting attribution removes its provider/hooks and /claude-cache. Isolated Fusion, delegate, and attested Anthropic children load the separate always-on child entrypoint explicitly before their guard/governor, regardless of that ambient flag. It requests ttl: "1h" on system/tool/conversation cache breakpoints before serialization and preserves provider-reported cacheWrite1h evidence. Set PI_CACHE_RETENTION=short|none|long or use /claude-cache when ambient attribution is enabled; malformed attribution, policy, cache evidence, or non-OAuth credentials fail before transport. Provider usage is preserved verbatim, but subscription OAuth can report cacheWrite1h = 0 even when a unique cache remains readable beyond five minutes; treat positive cacheWrite1h as definitive and zero as inconclusive on that channel. Anthropic budgeting follows the provider's 200K subscription policy.
• Fusion research fetches only caller-supplied public http(s) URLs with bounded retrieval. It is not web search and not a secret-exfiltration boundary.
• Attestation sidecars are local, unsigned, same-user-writable evidence. They are useful for downstream local gates, but not cryptographic proof against local compromise, a compromised Pi binary, or a compromised provider.
• Metadata, attestations, delegate/Fusion artifacts, and configuration replacements use write/fsync/rename durability patterns. Failed/cancelled stored Fusion runs also have a manifest-bound failure-summary.json containing bounded no-answer evidence metadata and artifact refs only; bg_result returns it as an answer-free typed terminal view after integrity checks. Ordinary task output is closed and drained before terminal publication but is not explicitly fsynced. POSIX directory entries are fsynced after atomic replacement; Windows lacks the same portable directory-entry crash-durability guarantee.

Detailed operations: Configuration.

EventBus and Autopilot integration

Other Pi extensions can control the same BackgroundTaskRegistry through Pi's events bus instead of shelling out or maintaining a second task manager. The public channels are:

| Purpose | Channel | |---|---| | Request | pi-background-tasks:request:v1 | | Response | pi-background-tasks:response:v1 | | Terminal task event | pi-background-tasks:terminal:v1 |

Operations are capabilities, run, status, logs, and kill. This is the integration point for orchestrators such as Autopilot that need non-blocking package-managed work with bounded logs and correlated terminal events. Consumers must deduplicate terminal frames by task.id: an EventBus listener failure can cause a retried publication.

Native front ends that show a background-jobs panel can use the separate, optional host interface EventBus API v1 (pi-background-tasks:host:request:v1, pi-background-tasks:host:response:v1, pi-background-tasks:host:changed:v1). It adds leased, sequence-fenced, paginated list/detail, bounded UTF-8-safe log windows, exact-id stop/confirmed stop-all, shell-only rerun, read-only verified delegate/Fusion result views that never claim usage, shared seen state, and coalesced change frames over the same registry. It changes nothing in the v1 service, tools, commands, dock, notifications, or wake-up behavior, and does no change-publication work while no client is subscribed.

Documentation map

| Need | Read | |---|---| | First install and first task | Getting started | | Which workflow/tool to choose | Choose a workflow | | Environment variables, shells, output caps, model config, offline behavior | Configuration | | Package QA expectations | TESTING.md and TEST_PLAN.md | | Publishing notes | PUBLISHING.md | | License and derived-rule notice | LICENSE and THIRD_PARTY_NOTICES.md |

Contributing

Keep user-facing claims tied to source. If you change public schemas, command behavior, durability, model routing, or environment variables, update these package-local docs in the same change and run focused checks appropriate to the edit.

For startup work, use scripts/benchmark-cold-load.mjs with an owned output/scratch root, explicit --runtime source|compiled, and at least 30 fresh-process samples; the exact command and interpretation rules are in Testing operations. Its “cold” result means an empty JavaScript/Jiti module cache, not a flushed filesystem cache. It is distribution evidence, not a flaky CI threshold. Published Pi entrypoints use precompiled JavaScript; disabled delegate/Fusion/attribution lanes, the dock UI, and attested execution stay outside process-only static startup. Load those entrypoints through Pi; dist/src/** contains private implementation chunks and is not a set of standalone Node entrypoints. Native-Windows and vendor compiled-Bun timing still require their own evidence.