pi-background-tasks 0.9.0 → 1.0.3

package/docs/commands/task-manager.md

@@ -0,0 +1,109 @@
+---
+doc_id: commands/task-manager
+audience: user
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [command:bg-tasks, command:tasks]
+covers_sources: []
+---
+# `/tasks` and `/bg-tasks`
+
+<!-- pi-docs:begin name="command-contract-tasks-bg-tasks" generator="scripts/docs/generate.mjs" -->
+| Command | Description | Provenance |
+| --- | --- | --- |
+| `/tasks` | Open the Claude-like background task manager UI | `src/extension.ts:532` |
+| `/bg-tasks` | Open the background task manager UI | `src/extension.ts:540` |
+<!-- pi-docs:end name="command-contract-tasks-bg-tasks" -->
+
+Open the interactive background task manager. `/tasks` and `/bg-tasks` are aliases.
+
+## Synopsis
+
+
+`/tasks [exact-task-id]`
+
+`/bg-tasks [exact-task-id]`
+
+## When to use
+
+Use the task manager when you want the host UI: select tasks, inspect a live output tail, stop one or all running tasks, rerun a task, copy/show an output path, or review recent finished task history.
+
+## Defaults
+
+- No argument opens the list view.
+- An exact task id opens detail view for that task and marks it seen in the footer. Unlike `/logs`, `/kill`, and the task tools, this optional UI argument is not prefix-resolved.
+- If there are no running tasks but finished history exists, the list opens in history mode.
+
+## Lifecycle
+
+The manager is an overlay dock. Opening it sets the footer hint to `focused` and temporarily hides the `/bg-clear` hint; closing returns the footer to the normal `Shift↓` hint. Opening a finished task's detail view marks that task seen. Merely opening the list or closing the dock does **not** clear other finished badges; use [`/bg-clear`](bg-clear.md) to clear them together.
+
+List view sorts tasks as running, failed, killed, then completed; within a status, newest terminal/start time appears first. Status labels shown in the UI are `running`, `error` for `failed`, `stopped` for `killed`, and `done` for `completed`.
+
+## Examples
+
+```text
+/tasks
+/bg-tasks b1234
+```
+
+## Output/result
+
+This command opens UI only. In non-interactive mode, it emits an error notification:
+
+```text
+Background task manager requires an interactive Pi UI. Use /jobs, /logs, or the bg_status/bg_logs tools in non-interactive mode.
+```
+
+## Controls
+
+List view:
+
+- `↑`/`↓`: select.
+- `PgUp`/`PgDn`: page selection.
+- `Enter`/`→`: open output detail.
+- `k`: stop selected running task.
+- `a`, `A`, or `K`: stop all running tasks; press again to confirm.
+- `h`: show/hide history.
+- `R`: rerun selected task with notification enabled and wake disabled.
+- `c`/`C`: show output path.
+- `Esc`, `q`, `Q`, `x`, `X`: close.
+
+Detail view:
+
+- `←`: return to list.
+- `↑`/`↓`/`PgUp`/`PgDn`: scroll output.
+- `r`: refresh and resume following tail.
+- `k`: stop running task.
+- `R`: rerun task.
+- `c`/`C`: show output path.
+- close keys are the same as list view.
+
+## Detail output tail semantics
+
+The detail view reads a UI-only tail buffer of 128 KiB once per second while following. It displays 12 output lines. Scrolling up pauses live following and freezes the buffer so the view stays stable. Scrolling/pageing back to the bottom resumes follow mode; `r` also resumes follow and refreshes. This UI tail is larger than the model-facing log cap and is separate from [`bg_logs`](../tools/bg_logs.md).
+
+## Errors
+
+Stop, stop-all, rerun, and output-read failures are reported inside the dock as action messages. A missing output file appears as `Output file not found: <path>`.
+
+## Runtime artifacts
+
+The manager reads task snapshots and output files from the current extension runtime. It does not reattach to detached historical OS processes after Pi shutdown/reload.
+
+## Safety boundaries
+
+Stopping uses the same runtime kill path as [`/kill`](kill.md) and [`bg_kill`](../tools/bg_kill.md). Shell commands are not sandboxed; the manager only controls tracked tasks.
+
+## Related docs
+
+- [Shortcuts and dock](../reference/shortcuts-and-dock.md)
+- [`/jobs`](jobs.md)
+- [`/logs`](logs.md)
+- [`/kill`](kill.md)
+- [Host UI and telemetry](../subsystems/host-ui-and-telemetry.md)
+
+## Source ownership/reference
+
+Surface registration and dock wiring live in `src/extension.ts`; UI behavior is implemented in `src/ui/background-tasks-manager.ts` and owned by [host-ui-and-telemetry](../subsystems/host-ui-and-telemetry.md).

package/docs/concepts/completion-delivery.md

@@ -0,0 +1,66 @@
+---
+doc_id: concepts/completion-delivery
+audience: agent
+mode: authored
+review_policy: contract
+stability: stable
+covers_surfaces: [renderer:background-task-notification]
+covers_sources: []
+---
+# Completion delivery
+
+Background tasks can finish silently, notify the terminal, or notify and wake the agent. The flags are task-owned.
+
+## Delivery modes
+
+| `notifyOnCompletion` | `triggerOnCompletion` | Actual mode |
+|---|---:|---|
+| `true` | `true` | Durable terminal notification and automatic follow-up turn. Default for [`bg_run`](../tools/bg_run.md). |
+| `true` | `false` | Durable terminal notification only; no provider follow-up. Default for [`/bg`](../commands/bg.md). |
+| `false` | `true` | Manual monitoring; `triggerOnCompletion` has no effect without a notification. |
+| `false` | `false` | Manual monitoring. |
+
+## Critical behavior
+
+- `/bg` is display-only by default: it sets `notifyOnCompletion:true` and `triggerOnCompletion:false`.
+- `bg_run` defaults to durable notification plus follow-up turn: `notifyOnCompletion:true` and `triggerOnCompletion:true`.
+- `bg_status` and `bg_logs` are point-in-time inspection tools, not polling primitives.
+- A received `<background-task-notification>` is metadata-backed terminal-status truth. The output stream has finished/closed, but ordinary `.output` bytes are not explicitly fsynced. Do not call `bg_status` only to reconfirm status; call `bg_logs` only if output bytes are needed.
+
+## Notification payload
+
+When enabled and not during shutdown, terminal completion sends a custom message with:
+
+- `<task-id>`
+- `<task-name>`
+- `<status>` (`completed`, `failed`, or `killed`)
+- optional `<exit-code>`
+- optional `<error>`
+- `<output-file>`
+- `<summary>`
+- `<guidance>` that says terminal state and output metadata are durable and not to reconfirm with `bg_status`.
+
+The structured details contain the task snapshot, including delivery flags and `notified` state.
+
+## Agent guidance
+
+After default `bg_run`, continue only independent useful work. If there is no such work, briefly acknowledge and end the turn; the follow-up notification will wake the agent. Do not sleep, poll `bg_status`, or repeatedly read `bg_logs` merely to wait.
+
+If either completion flag was intentionally disabled, manual inspection is allowed when deliberate, but still avoid tight polling.
+
+## Failures and suppression
+
+If notification send fails, the task resets `notified:false` and logs the error; it does not silently pretend delivery happened. During Pi session shutdown/reload, notifications are suppressed while running tasks are killed.
+
+## Related docs
+
+- [`bg_run`](../tools/bg_run.md)
+- [`bg_status`](../tools/bg_status.md)
+- [`bg_logs`](../tools/bg_logs.md)
+- [`/bg`](../commands/bg.md)
+- [Background task runtime](../subsystems/background-task-runtime.md)
+- [Host UI and telemetry](../subsystems/host-ui-and-telemetry.md)
+
+## Source ownership/reference
+
+Delivery receipt text is derived by runtime helpers and sent by extension registration; primary behavioral ownership is split between [background-task-runtime](../subsystems/background-task-runtime.md) and [host-ui-and-telemetry](../subsystems/host-ui-and-telemetry.md).

package/docs/concepts/context-projection-and-budgeting.md

@@ -0,0 +1,79 @@
+---
+doc_id: concepts/context-projection-and-budgeting
+audience: agent
+mode: authored
+review_policy: behavioral
+stability: evolving
+covers_surfaces: []
+covers_sources: [src/core/context/parent-snapshot.ts, src/core/context/token-budget.ts, src/core/context/visible-conversation-v2.ts]
+---
+# Context projection and budgeting
+
+Primary sources: `src/core/context/parent-snapshot.ts`, `src/core/context/visible-conversation-v2.ts`, and `src/core/context/token-budget.ts`.
+
+## Shared visible conversation transform
+
+`VISIBLE_CONVERSATION_TRANSFORM_ID` is `visible-conversation-ledger-v2`. It is shared by Fusion reason and delegate seeding so each consumer gets the same disposition for the same parent session bytes.
+
+The transform has no behavioral knobs:
+
+- user text: retained verbatim;
+- assistant text: retained verbatim;
+- assistant thinking: omitted into the ledger;
+- tool-call arguments: omitted into the ledger;
+- tool-result text: omitted into the ledger;
+- tool-result images: ledger-only;
+- user images: marker-only text (`[Image omitted from fusion text transcript: <mime>]`);
+- empty text blocks: counted, not serialized;
+- unknown roles/block types: loud `UnsupportedConversationBlockError`.
+
+Each omitted event records source ordinal, block ordinal, kind, payload byte length, payload SHA-256, and optional tool/mime metadata. The ledger root is hash-framed and independent of consumer envelopes, so Fusion and delegate can seal the same transform output into different schemas without changing the underlying omitted-event commitment.
+
+## Parent snapshot and branch exclusion
+
+`parent-snapshot.ts` adapts Pi `SessionManager` entries into LLM messages. Tool callers can exclude the active assistant leaf that contains the in-flight tool call; this prevents the child from seeing its own request and sibling calls as completed parent history. Commands do not exclude a leaf.
+
+Callers must snapshot once and complete downstream launch/admission from that frozen snapshot. Re-reading the parent session during launch would allow seed drift.
+
+## Reason input vs clean input
+
+- Fusion `reason` uses the parent visible-conversation projection. Its canonical input includes the system prompt, request authority, projection entries, accounting, and a separate `context-omission-ledger.json` artifact.
+- Fusion `investigate`, `research`, and `validate` use clean-task input. They carry the explicit request and declared sources where applicable; they intentionally do not carry parent system prompt, conversation projection, or omission ledger.
+- Delegate uses the shared projection inside its seed, but its directive text is marked authoritative and projected history is supporting/untrusted.
+
+No path silently truncates parent context. Oversized projections or prompts must be rejected with budget details or represented by hashed artifact receipts where that consumer defines a receipt protocol.
+
+## Token estimator concepts
+
+`token-budget.ts` is byte arithmetic, not a tokenizer. It produces upper-bound style estimates from UTF-8 byte classes:
+
+- `normal` known text/json bytes;
+- `multibyte` bytes;
+- `dense_ascii` bytes;
+- `unknown_output_contract` bytes.
+
+Families are `anthropic`, `openai-codex`, and `unknown`. Exact model overrides currently include Anthropic Opus/Fable routes and OpenAI Codex GPT routes. Unknown providers and unbacked models fall to a provable 1.00 B/token floor.
+
+Calibration facts in code:
+
+- calibration id: `pi-background-tasks.input-token-calibration.v1`;
+- large-prompt floor: 50 KiB;
+- affine fixed reserve: 512 tokens;
+- observed large Fusion prompt corpus: 882 prompts, dated 2026-08-02;
+- Anthropic configured rate: 1.73 B/token after haircut;
+- OpenAI Codex configured rate: 2.89 B/token after haircut;
+- conservative/floor rates are used for delegate scope, small prompts, unbacked models, unknown providers, capacity guards, and dense-ASCII out-of-domain cases.
+
+The dense-ASCII gate is explicitly a low-whitespace heuristic proxy, not a tokenizer guarantee. Calibration applies only when the input is in the measured domain and the route capacity can hold that domain.
+
+## Budget invariants
+
+- `allowedInputTokens()` returns a signed number and never clamps unusable routes to zero.
+- Callers must reject unusable or too-small context windows before spawning children.
+- Multibyte bytes cannot bypass accounting.
+- Unknown output contracts are charged separately; future output cannot be assumed to be cheap.
+- Rate-source warnings are part of the contract and should be surfaced in refusal details.
+
+## No silent truncation
+
+Model-visible context may be compacted only by explicit policy receipts with exact accounting and hashes. It must never be clipped, head/tail previewed, route-substituted, or hidden behind a fallback estimator without reporting the source and limitation.

package/docs/getting-started.md

@@ -0,0 +1,122 @@
+---
+doc_id: getting-started
+audience: user
+mode: authored
+review_policy: contract
+stability: stable
+covers_surfaces: []
+covers_sources: []
+---
+# Getting started
+
+This guide gets from install to useful background work in a few minutes.
+
+## 1. Install
+
+```bash
+pi install npm:pi-background-tasks@latest
+```
+
+For a project-local install:
+
+```bash
+pi install npm:pi-background-tasks@latest -l
+```
+
+For current repository state rather than a release tag:
+
+```bash
+pi install git:github.com/ismailsaleekh/pi-background-tasks@main
+```
+
+For a local checkout/package path:
+
+```bash
+pi install .
+pi install . -l
+```
+
+## 2. Start your first `/bg` task
+
+Inside a project, run:
+
+```text
+/bg --name "Docs server" npm run docs:dev
+```
+
+`/bg` starts a tracked shell command, returns a task id, and writes output under `.pi/tasks/...`. The command is still an ordinary local shell command; the package tracks it but does not sandbox it.
+
+## 3. Observe completion
+
+Use the footer dock or commands:
+
+```text
+/jobs
+/logs <task id> 20000
+```
+
+Press **Shift↓** to open the dock when the `bg ...` footer appears. `/bg-clear` acknowledges finished-task footer notices.
+
+## 4. Start an agent-launched background task
+
+When Pi itself should start a long command, use the `bg_run` tool with the strict schema:
+
+```json
+{
+  "name": "Typecheck",
+  "command": "npm run typecheck",
+  "isAgent": false
+}
+```
+
+`bg_run` defaults `notifyOnCompletion:true` and `triggerOnCompletion:true`, so Pi should not sleep or poll merely to wait. The terminal notification is the wake-up path.
+
+Set `isAgent:true` only when the shell command launches a child Pi/LLM agent, such as `pi -p ...` or `pi --mode json ...`.
+
+## 5. Delegate read-only investigation
+
+Use `bg_delegate` when the worker needs the current conversation as background but should not block the parent:
+
+```json
+{
+  "name": "Config audit",
+  "prompt": "Inspect package configuration and report where background-task output limits are defined. Include file paths and concise evidence.",
+  "capability": "inspect",
+  "autoDeliver": "never"
+}
+```
+
+The child receives a frozen visible-conversation projection, its own session id/session directory, and read/search/list tools only. It has no shell, no write/edit tools, no network, no recursive delegate, and no Fusion.
+
+After the completion notification, retrieve the committed answer:
+
+```json
+{
+  "taskId": "<task id from bg_delegate>",
+  "delivery": "inline"
+}
+```
+
+`bg_result` is point-in-time: a running task returns a typed not-ready state and never blocks. A committed answer is hash-verified before bytes are returned and is never silently truncated.
+
+## 6. Run first Fusion reasoning
+
+For self-contained synthesis:
+
+```json
+{"prompt":"Compare a foreground command, bg_run, and bg_delegate for a ten-minute repository audit."}
+```
+
+Call this with `fusion_reason`, or use:
+
+```text
+/fusion Compare a foreground command, bg_run, and bg_delegate for a ten-minute repository audit.
+```
+
+Fusion runs three candidates, blind evaluation, optional bounded repair only if evaluator JSON is invalid, and merger. `/fusion` and `fusion_reason` receive a versioned conversation projection; investigate/research/validate receive clean task input only.
+
+## Next links
+
+- [Choose a workflow](choose-a-workflow.md)
+- [Configuration](operations/configuration.md)
+- [README landing page](../README.md)