pi-background-tasks 0.9.0 → 1.0.4

package/docs/commands/bg-clear.md

@@ -0,0 +1,70 @@
+---
+doc_id: commands/bg-clear
+audience: user
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [command:bg-clear]
+covers_sources: []
+---
+# `/bg-clear`
+
+<!-- pi-docs:begin name="command-contract-bg-clear" generator="scripts/docs/generate.mjs" -->
+| Command | Description | Provenance |
+| --- | --- | --- |
+| `/bg-clear` | Clear finished background task footer notices | `src/extension.ts:548` |
+<!-- pi-docs:end name="command-contract-bg-clear" -->
+
+Clear finished background task footer notices.
+
+## Synopsis
+
+
+`/bg-clear`
+
+## When to use
+
+Use this after you have seen completed, failed, or killed task badges in the footer and want to remove those finished counts from the dock status.
+
+## Defaults
+
+No arguments. It only marks currently unseen finished tasks as seen.
+
+## Lifecycle
+
+A finished task's footer badge is marked seen when its detail view opens. `/bg-clear` or the equivalent shortcut marks every currently unseen finished task seen at once. Merely opening the list view or closing the task manager does not clear badges. Running task counts remain visible after clearing finished notices.
+
+## Examples
+
+```text
+/bg-clear
+```
+
+## Output/result
+
+Interactive notification:
+
+- `Cleared N finished background task notice(s).` when at least one unseen finished task was marked seen.
+- `No finished background task notices to clear.` when none were pending.
+
+## Errors
+
+No task-resolution errors; the command operates on the in-memory task registry.
+
+## Runtime artifacts
+
+No task files are deleted. Output and metadata under `.pi/tasks/...` remain intact.
+
+## Safety boundaries
+
+`/bg-clear` does not kill, prune, or modify tasks. It only updates the host UI's seen set for this extension runtime.
+
+## Related docs
+
+- [Shortcuts and dock](../reference/shortcuts-and-dock.md)
+- [`/tasks` and `/bg-tasks`](task-manager.md)
+- [Host UI and telemetry](../subsystems/host-ui-and-telemetry.md)
+
+## Source ownership/reference
+
+Surface registration lives in `src/extension.ts`; footer behavior is owned by [host-ui-and-telemetry](../subsystems/host-ui-and-telemetry.md).

package/docs/commands/bg-update.md

@@ -0,0 +1,82 @@
+---
+doc_id: commands/bg-update
+audience: user
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [command:bg-update]
+covers_sources: []
+---
+# `/bg-update`
+
+<!-- pi-docs:begin name="command-contract-bg-update" generator="scripts/docs/generate.mjs" -->
+| Command | Description | Provenance |
+| --- | --- | --- |
+| `/bg-update` | Show how to update pi-background-tasks to the latest published version | `src/extension.ts:556` |
+<!-- pi-docs:end name="command-contract-bg-update" -->
+
+Show update instructions for `pi-background-tasks`.
+
+## Synopsis
+
+
+`/bg-update`
+
+## When to use
+
+Use this when the footer shows an update segment such as `⬆ v999.0.0 /bg-update`, or whenever you want the package's install/update commands printed without performing an install.
+
+## Defaults
+
+No arguments. The command reads the installed package name/version and any latest version found by the session update check.
+
+## Lifecycle
+
+The update check is one-shot per extension runtime, started after `session_start`, and is not awaited on the session-start path. It is skipped when:
+
+- `PI_BG_DISABLE_UPDATE_CHECK=1`,
+- `PI_OFFLINE=1`, or
+- the installed package version is unavailable.
+
+The registry request is time-boxed by `fetchLatestVersion` and failures resolve to no update segment. `/bg-update` itself only prints instructions; it never installs, self-updates, or mutates package files.
+
+## Examples
+
+```text
+/bg-update
+```
+
+## Output/result
+
+The notification includes current installed version and, when known, latest published version, then prints:
+
+```text
+pi install npm:pi-background-tasks@latest
+pi install npm:pi-background-tasks@<version>
+pi install git:github.com/ismailsaleekh/pi-background-tasks@main
+For a pinned git release, first verify the tag exists, then use git:github.com/ismailsaleekh/pi-background-tasks@<existing-tag>.
+This command only prints update instructions; it does not install or self-update.
+```
+
+If no latest npm version is known, `<version>` is printed for the pinned npm command. The command never derives a git tag from the npm version: npm releases and repository tags are independent, and a pinned git tag must be verified separately.
+
+## Errors
+
+The command has no task-resolution errors. Update-check network, timeout, bad status, and malformed payload failures are offline-safe and do not throw into the UI.
+
+## Runtime artifacts
+
+No task artifacts. The footer segment is UI state only.
+
+## Safety boundaries
+
+Instruction-only. It does not run `pi install`, `npm`, `git`, or any package manager.
+
+## Related docs
+
+- [Shortcuts and dock](../reference/shortcuts-and-dock.md)
+- [Host UI and telemetry](../subsystems/host-ui-and-telemetry.md)
+
+## Source ownership/reference
+
+Surface registration lives in `src/extension.ts`; update lookup is implemented in `src/core/update-check.ts` and owned by [host-ui-and-telemetry](../subsystems/host-ui-and-telemetry.md).

package/docs/commands/bg.md

@@ -0,0 +1,90 @@
+---
+doc_id: commands/bg
+audience: user
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [command:bg]
+covers_sources: []
+---
+# `/bg`
+
+<!-- pi-docs:begin name="command-contract-bg" generator="scripts/docs/generate.mjs" -->
+| Command | Description | Provenance |
+| --- | --- | --- |
+| `/bg` | Start a shell command as a tracked background task: /bg [--agent] [--name "Task name"] <command> | `src/extension.ts:506` |
+<!-- pi-docs:end name="command-contract-bg" -->
+
+Start a shell command as a tracked background task from the command line.
+
+## Synopsis
+
+
+`/bg [--agent|--llm-agent] [--script|--no-agent] [--name <name>|-n <name>] [--] <command>`
+
+`--name=<name>` and `-n=<name>` are also accepted. Quoted names are parsed by the extension before the remaining bytes become the shell command.
+
+## When to use
+
+Use `/bg` for user-driven long-running commands where you want a footer entry, output file, and display notification, but **not** an automatic agent follow-up turn. For agent-driven launches, prefer [`bg_run`](../tools/bg_run.md) because its default completion delivery wakes the agent.
+
+## Defaults
+
+- `isAgent`: `false`; set `--agent`/`--llm-agent` only when the command launches a Pi/LLM agent whose telemetry should be wrapped.
+- `--script`/`--no-agent`: forces `isAgent:false` after earlier flags.
+- `notifyOnCompletion`: `true`.
+- `triggerOnCompletion`: `false` for `/bg`, so completion is display-only by default.
+- Task name: explicit `--name` if present, otherwise derived from the command.
+
+## Lifecycle
+
+The command returns after the child process is spawned and reports task id, output path, and command. Terminal statuses are exactly `running`, `completed`, `failed`, or `killed`. A finished footer badge remains visible until that task's detail view is opened or [`/bg-clear`](bg-clear.md) marks unseen finished tasks seen.
+
+## Examples
+
+```text
+/bg --name "Docs build" npm run docs
+/bg --agent --name "Child Pi" pi -p "summarize this repo"
+/bg --name="Server" -- npm run dev -- --host 127.0.0.1
+```
+
+## Output/result
+
+Start notification:
+
+```text
+Started <task-name> (<task-id>)
+Output: .pi/tasks/<session>-<pid>/<task-id>.output
+Command: <command>
+```
+
+Completion is delivered as a durable `background-task-notification` custom message when notifications are enabled, but `/bg` sets `triggerOnCompletion:false` so it does not start a provider follow-up turn.
+
+## Errors
+
+- Empty command: `Background command is empty`.
+- Missing or unterminated `--name`: `requires a task name`.
+- Shell/spawn errors fail the task loudly and write failure metadata.
+- Unknown shell policy on Windows can reject the launch before a task is created.
+
+## Runtime artifacts
+
+Outputs and metadata are written under `.pi/tasks/<session-id>-<pid>/` as `<task-id>.output` and `<task-id>.json`. Model-visible log reads are bounded; the full output path is preserved in notices.
+
+## Safety boundaries
+
+Shell commands are **not sandboxed**. They run in the current project cwd through the platform shell selected by the runtime. `/bg` tracks and kills the child process/tree, but does not restrict filesystem, network, or subprocess behavior.
+
+## Related docs
+
+- [`bg_run`](../tools/bg_run.md)
+- [`/jobs`](jobs.md)
+- [`/logs`](logs.md)
+- [`/kill`](kill.md)
+- [`/bg-clear`](bg-clear.md)
+- [Background task runtime](../subsystems/background-task-runtime.md)
+- [Completion delivery](../concepts/completion-delivery.md)
+
+## Source ownership/reference
+
+Surface registration lives in `src/extension.ts`; argument parsing and lifecycle behavior are owned by [background-task-runtime](../subsystems/background-task-runtime.md).

package/docs/commands/fusion-models.md

@@ -0,0 +1,70 @@
+---
+doc_id: commands/fusion-models
+audience: user
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [command:fusion-models]
+covers_sources: []
+---
+# `/fusion-models`
+
+<!-- pi-docs:begin name="command-contract-fusion-models" generator="scripts/docs/generate.mjs" -->
+| Command | Description | Provenance |
+| --- | --- | --- |
+| `/fusion-models` | Open the five-slot global fusion model selector. | `src/fusion-extension.ts:914` |
+<!-- pi-docs:end name="command-contract-fusion-models" -->
+
+Open the global Fusion model selector.
+
+## Availability
+
+`/fusion-models` is **TUI-only**. RPC, JSON, print, and other non-TUI modes reject it; non-UI command contexts throw an error instead of relying on a no-op notification path.
+
+## Slots
+
+The selector edits exactly five global slots:
+
+1. `Candidate 1`
+2. `Candidate 2`
+3. `Candidate 3`
+4. `Evaluator`
+5. `Merger`
+
+Duplicate model selections are allowed. `$current` is the default for every slot and resolves at run time to Pi's current model; it is available only when a current model exists and is available to child Pi. Slash-containing model ids are stored as `provider/model-id` strings.
+
+## UI behavior
+
+The selector starts from the loaded config or the default all-`$current` config. It lists:
+
+- `$current` first, with the current provider/model in the description when known;
+- currently available registry models sorted by `provider/model`;
+- configured-but-unavailable selections, marked unavailable, so stale configs can still be seen and replaced.
+
+In the five-slot view, arrow keys move, Enter opens the model list, `r` resets the draft to defaults, `s` saves, and Esc or `q` cancels without saving. In the model-choice view, arrow keys move, typed text—including `q`—filters the list, Backspace edits the filter, Enter chooses and returns to the slots, and Esc returns to the slots without changing that slot.
+
+## Persistence and conflicts
+
+The config file is `fusion-models.json` in Pi's agent directory (`fusionModelConfigPath()`). Its schema is closed:
+
+```json
+{
+  "schema_version": "pi-background-tasks.fusion-models.v1",
+  "candidates": ["$current", "$current", "$current"],
+  "evaluator": "$current",
+  "merger": "$current"
+}
+```
+
+Loads reject invalid JSON, unknown keys, wrong schema version, blank selections, surrounding whitespace, unqualified configured selections, and candidate arrays that do not contain exactly three entries.
+
+Saves are durable and revision-safe: the parent captures the file revision hash on load, takes a lock next to the config, verifies the on-disk revision still matches, then atomically replaces the file. If another process changes the file first, the save fails with a config-conflict error shown inside the selector; it does not overwrite concurrent work. Lock acquisition times out loudly after 10 seconds.
+
+## Route admission
+
+At run time every slot is resolved through the available model registry. Frontier routes are accepted only through the Pi subscription OAuth path for `anthropic` or `openai-codex` and only on trusted subscription endpoints. Direct OpenAI/OpenRouter/Azure/frontier API-key routes, endpoint/header overrides of subscription auth, unavailable models, missing current model, and missing positive context windows fail before child creation. There is no fallback, model substitution, or tier bump.
+
+## Related
+
+- Command using the selected routes: [`fusion.md`](fusion.md)
+- Behavioral owner/troubleshooting: [`../subsystems/fusion.md`](../subsystems/fusion.md)

package/docs/commands/fusion.md

@@ -0,0 +1,69 @@
+---
+doc_id: commands/fusion
+audience: user
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [command:fusion]
+covers_sources: []
+---
+# `/fusion`
+
+<!-- pi-docs:begin name="command-contract-fusion" generator="scripts/docs/generate.mjs" -->
+| Command | Description | Provenance |
+| --- | --- | --- |
+| `/fusion` | Run fixed-purpose Fusion reason (no candidate tools) and append the merged result directly. | `src/fusion-extension.ts:891` |
+<!-- pi-docs:end name="command-contract-fusion" -->
+
+Run the fixed-purpose Fusion **reason** workflow from the command line.
+
+## Synopsis
+
+`/fusion <prompt>`
+
+`/fusion` with no arguments opens Pi's multiline editor in UI-capable modes. If the editor is cancelled or the edited text is blank after trimming, Fusion returns without spawning children.
+
+## Current v1 behavior
+
+`/fusion` is shorthand for `fusion_reason({prompt})`:
+
+- the public workflow is always `reason`;
+- there is no capability or mode argument;
+- candidate children run without tools;
+- evaluator, conditional evaluator-repair, and merger children also run without tools;
+- the request is captured as a versioned visible-conversation projection, not as a raw transcript.
+
+The retired `fusion_brainstorm` public tool is not registered and is removed from active tools on session start. Historical completed v4 result messages can still render, but `/fusion` never reactivates the retired surface.
+
+## Conversation input
+
+Reason/session-projection input uses schema `pi-background-tasks.fusion-input.v5`. The child-facing input contains:
+
+- `request.text` with the exact command prompt;
+- request authority `directive_over_projected_conversation` for the command path;
+- the parent system prompt inside the versioned session-projection context;
+- visible user/assistant text entries preserved verbatim;
+- deterministic omission receipts for assistant thinking, tool calls, and text/image tool results.
+
+Omitted payload bytes are not summarized or previewed for the children. If a fact exists only inside omitted tool output, restate it in the prompt.
+
+## Result delivery
+
+After a successful run, `/fusion` appends two custom messages without asking the parent model to rewrite the answer:
+
+1. a hidden `fusion-request` record for the command request/run id;
+2. a visible `fusion-result` record whose content is the merger's exact text and whose details include run id, artifact directory, model summary, usage/cost, evaluator-attempt count, and budget metadata.
+
+In TUI mode `/fusion` uses a cancellable loader. Cancelling aborts the active child process tree and records a cancelled run when a run directory exists.
+
+## Calls and failure shape
+
+A successful run uses three candidate children, one blind evaluator, and one merger. If the first evaluator response is invalid JSON or violates the closed evaluation schema, Fusion performs exactly one evaluator-repair attempt before failing or continuing. Therefore a successful run may have five or six child invocations; preflight failures launch zero children, and candidate/evaluator/merge failures stop the workflow rather than substituting another model.
+
+Failures are reported as `Fusion failed: ...`; tool/stage errors include the artifact directory when one exists. Prompt-budget forecast failures happen before child creation. Child cancellation, timeout, output caps, model-route admission failures, invalid evaluator JSON after repair, invalid compact child metadata, and invalid tool-call audits are loud failures.
+
+## Related
+
+- Tool equivalent: [`../tools/fusion_reason.md`](../tools/fusion_reason.md)
+- Model selector: [`fusion-models.md`](fusion-models.md)
+- Behavioral owner/troubleshooting: [`../subsystems/fusion.md`](../subsystems/fusion.md)

package/docs/commands/jobs.md

@@ -0,0 +1,74 @@
+---
+doc_id: commands/jobs
+audience: user
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [command:jobs]
+covers_sources: []
+---
+# `/jobs`
+
+<!-- pi-docs:begin name="command-contract-jobs" generator="scripts/docs/generate.mjs" -->
+| Command | Description | Provenance |
+| --- | --- | --- |
+| `/jobs` | List running and recent background tasks | `src/extension.ts:594` |
+<!-- pi-docs:end name="command-contract-jobs" -->
+
+List running and recent background tasks.
+
+## Synopsis
+
+
+`/jobs`
+
+## When to use
+
+Use `/jobs` for a point-in-time textual snapshot when the interactive task manager is unavailable or unnecessary.
+
+## Defaults
+
+No arguments. It lists all tasks currently retained by this extension runtime: running tasks plus recent finished tasks not pruned from the in-memory registry.
+
+## Lifecycle
+
+Tasks have exactly these statuses: `running`, `completed`, `failed`, `killed`. Finished tasks are kept as recent history up to the runtime's recent-task retention limit; running tasks are preserved when pruning old finished tasks.
+
+## Examples
+
+```text
+/jobs
+```
+
+## Output/result
+
+If no tasks exist:
+
+```text
+No background tasks in this Pi extension runtime.
+```
+
+Otherwise each task line includes status icon, id, status, age, optional exit code, optional pid, task-owned telemetry summaries when reported, display name, optional error, and a following `output: <path>` line.
+
+## Errors
+
+No task-resolution errors; it formats the current registry contents.
+
+## Runtime artifacts
+
+`/jobs` reads in-memory task snapshots. It points at `.pi/tasks/<session-id>-<pid>/<task-id>.output` but does not read output bytes.
+
+## Safety boundaries
+
+Read-only inspection. It does not wait, poll, kill, or modify tasks.
+
+## Related docs
+
+- [`/logs`](logs.md)
+- [`/kill`](kill.md)
+- [`bg_status`](../tools/bg_status.md)
+- [Background task runtime](../subsystems/background-task-runtime.md)
+
+## Source ownership/reference
+
+Surface registration lives in `src/extension.ts`; snapshot formatting is owned by [background-task-runtime](../subsystems/background-task-runtime.md).

package/docs/commands/kill.md

@@ -0,0 +1,82 @@
+---
+doc_id: commands/kill
+audience: user
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [command:kill]
+covers_sources: []
+---
+# `/kill`
+
+<!-- pi-docs:begin name="command-contract-kill" generator="scripts/docs/generate.mjs" -->
+| Command | Description | Provenance |
+| --- | --- | --- |
+| `/kill` | Stop a running background task: /kill <id> | `src/extension.ts:638` |
+<!-- pi-docs:end name="command-contract-kill" -->
+
+Stop a running background task.
+
+## Synopsis
+
+
+`/kill <task-id-or-prefix>`
+
+## When to use
+
+Use `/kill` when a tracked background task is no longer needed or is hung. Use [`bg_kill`](../tools/bg_kill.md) for the same operation from an agent tool call.
+
+## Defaults
+
+No defaults beyond task id/prefix resolution. Prefixes must be unambiguous.
+
+## Lifecycle
+
+Only `running` tasks can be killed. A successful user kill sets terminal status `killed` and records the task output path. Trying to kill a `completed`, `failed`, or already `killed` task fails loudly.
+
+## Examples
+
+```text
+/kill b12345678
+/kill b1234
+```
+
+## Output/result
+
+```text
+Killed <task-name> (<task-id>). Output: .pi/tasks/.../<task-id>.output
+```
+
+## Errors
+
+- Missing id: `Task ID is required`.
+- Unknown id/prefix: `Unknown background task ID: <id>`.
+- Ambiguous prefix: lists matching task ids.
+- Non-running task: `Task <id> is <status>, not running`.
+- Kill failure: platform-specific loud error.
+
+Errors are shown as `Background kill error: ...`.
+
+## Runtime artifacts
+
+The task's output file and metadata remain in `.pi/tasks/...`. Termination notices and errors may be appended to the output and metadata.
+
+## Safety boundaries
+
+Process termination differs by platform:
+
+- POSIX first targets the detached process group with `SIGTERM`, falls back to the child handle, and escalates to `SIGKILL` after the grace window.
+- Windows uses `taskkill.exe /PID <pid> /T`, then `/F` after the grace window. Force failure is surfaced loudly because descendant processes may have leaked.
+
+Shell commands are not sandboxed; killing controls only tracked process handles/trees.
+
+## Related docs
+
+- [`bg_kill`](../tools/bg_kill.md)
+- [`/jobs`](jobs.md)
+- [`/logs`](logs.md)
+- [Background task runtime](../subsystems/background-task-runtime.md)
+
+## Source ownership/reference
+
+Surface registration lives in `src/extension.ts`; process termination is owned by [background-task-runtime](../subsystems/background-task-runtime.md).

package/docs/commands/logs.md

@@ -0,0 +1,90 @@
+---
+doc_id: commands/logs
+audience: user
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [command:logs]
+covers_sources: []
+---
+# `/logs`
+
+<!-- pi-docs:begin name="command-contract-logs" generator="scripts/docs/generate.mjs" -->
+| Command | Description | Provenance |
+| --- | --- | --- |
+| `/logs` | Show bounded output from a background task: /logs <id> [maxBytes] | `src/extension.ts:607` |
+<!-- pi-docs:end name="command-contract-logs" -->
+
+Show bounded output from a background task.
+
+## Synopsis
+
+
+`/logs <task-id-or-prefix> [maxBytes]`
+
+Slash-command logs always read the tail.
+
+## When to use
+
+Use `/logs` when you need task output in the host UI. For agent tool calls, use [`bg_logs`](../tools/bg_logs.md) and avoid repeated calls as a waiting loop.
+
+## Defaults
+
+- `maxBytes`: defaults to the model-safe log cap, currently up to 50 KiB.
+- Values are normalized to an integer in `[1, MAX_LOG_BYTES]`; invalid numbers use the default.
+- `tail`: always `true` for `/logs`.
+
+## Lifecycle
+
+`/logs` is a point-in-time read of the output file. It does not subscribe, follow, or poll. Running tasks may produce more output after the read.
+
+## Examples
+
+```text
+/logs b12345678
+/logs b1234 2000
+```
+
+## Output/result
+
+The notification contains output text. If truncated, a notice is prepended for tail reads:
+
+```text
+[Showing tail <bytes-read> of <total>; <omitted> omitted. Full output: .pi/tasks/.../<task-id>.output]
+```
+
+If not truncated, the result ends with:
+
+```text
+[Full output: .pi/tasks/.../<task-id>.output]
+```
+
+The full output path is preserved even when model-visible bytes are bounded.
+
+## Errors
+
+- Missing id: `Task ID is required`.
+- Unknown id/prefix: `Unknown background task ID: <id>`.
+- Ambiguous prefix: lists matching task ids.
+- Missing output file: `Output file does not exist for <id>: <path>`.
+
+Errors are shown as `Background logs error: ...`.
+
+## Runtime artifacts
+
+Reads `.pi/tasks/<session-id>-<pid>/<task-id>.output`; does not modify output or metadata.
+
+## Safety boundaries
+
+Read-only bounded inspection. It is not a polling primitive and should not be used merely to wait for completion.
+
+## Related docs
+
+- [`bg_logs`](../tools/bg_logs.md)
+- [`/jobs`](jobs.md)
+- [`/kill`](kill.md)
+- [Background task runtime](../subsystems/background-task-runtime.md)
+
+## Source ownership/reference
+
+Surface registration lives in `src/extension.ts`; bounded log reading is owned by [background-task-runtime](../subsystems/background-task-runtime.md).