pi-background-tasks 0.7.7 → 1.0.3

package/docs/tools/bg_result.md

@@ -0,0 +1,120 @@
+---
+doc_id: tools/bg_result
+audience: agent
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [tool:bg_result]
+covers_sources: []
+---
+# `bg_result`
+
+<!-- pi-docs:begin name="tool-contract-bg_result" generator="scripts/docs/generate.mjs" -->
+- Label: **Delegate Result**
+- Source: `src/delegate-extension.ts:428`
+- 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.
+- Root schema: `object`; additionalProperties: `false`
+
+| Field | Required | Type | Description | Constraints |
+| --- | --- | --- | --- | --- |
+| `delivery` | no | `string` | inline returns the verified answer text; artifact returns metadata plus the artifact reference. Oversized answers are never truncated. |  |
+| `taskId` | yes | `string` | Delegate task id returned by bg_delegate. |  |
+
+<details>
+<summary>Normalized TypeBox contract</summary>
+
+
+```json
+{
+  "additionalProperties": false,
+  "properties": {
+    "delivery": {
+      "description": "inline returns the verified answer text; artifact returns metadata plus the artifact reference. Oversized answers are never truncated.",
+      "type": "string"
+    },
+    "taskId": {
+      "description": "Delegate task id returned by bg_delegate.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "taskId"
+  ],
+  "type": "object"
+}
+```
+
+</details>
+<!-- pi-docs:end name="tool-contract-bg_result" -->
+
+`bg_result` retrieves the result of a `bg_delegate` task. It never blocks: a running task returns a typed not-ready view, and a terminal task is verified before any answer bytes are returned.
+
+## Public arguments
+
+Required:
+
+- `taskId: string` — task id or unambiguous prefix resolved by the background-task registry. Must be non-empty after trimming.
+
+Optional:
+
+- `delivery: "inline" | "artifact"` — if omitted, answers at or below `48 KiB` are returned inline and larger answers are returned as an artifact reference. `artifact` always returns metadata/reference. `inline` for an oversized answer fails loudly.
+
+The TypeBox schema is closed (`additionalProperties: false`).
+
+## Not-ready behavior
+
+If the delegate task is still running, `bg_result` returns successfully with details:
+
+- `schema_version: "pi-background-tasks.delegate-result-view.v1"`;
+- `state: "running"`;
+- `delivery: "none"`;
+- artifact dir and budget facts when available.
+
+This is not an error and does not wait. End the turn or do other independent work until the terminal notification arrives.
+
+## Verification before return
+
+For terminal tasks, the parent evaluates the child artifacts. `result.json` is the child-written commit point. If it is absent, the task has no accepted answer even if the child exited `0`.
+
+A present package is accepted only after verifying:
+
+1. JSON shape and schema version;
+2. `task_id` and `launch_nonce`;
+3. `seed_sha256`;
+4. route object and every route attestation against the pinned provider/model;
+5. answer encoding (`utf-8`);
+6. strict base64 for every answer block;
+7. every block byte length and SHA-256;
+8. aggregate answer byte length and SHA-256;
+9. well-formed UTF-8 round trip.
+
+The returned text is decoded from the same aggregate buffer that was hashed. Corruption, stale packages, missing attestations, route drift, or invalid UTF-8 produce typed failures and no answer bytes.
+
+## Inline/artifact delivery and no truncation
+
+`bg_result` never truncates an answer.
+
+- Default delivery: inline when `answer.byte_length <= 48 KiB`, artifact reference otherwise.
+- `delivery: "artifact"`: returns metadata and points to `.pi/delegate/.../result.json` even for small answers.
+- `delivery: "inline"`: returns the full verified answer only if it fits the inline cap; otherwise fails with `result_too_large_for_inline` and names the preserved artifact.
+
+Large answers remain complete in `result.json` as base64 blocks plus aggregate hash.
+
+## Failure classes users see
+
+Common retrieval outcomes:
+
+- `task_unknown` — unknown id/prefix or not a delegate task.
+- `result_unavailable` / `child_exited_without_commit` — terminal task produced no committed result package.
+- `child_cancelled`, `child_timeout`, `child_turn_limit`, `child_tool_call_limit` — child did not complete cleanly.
+- `provider_context_budget_exhausted`, `aggregate_tool_output_cap`, `child_model_output_limit` — budget/limit refusal.
+- `route_attestation_missing`, `route_mismatch` — route evidence missing or not the pinned route.
+- `seed_hash_mismatch`, `answer_hash_mismatch`, `child_result_invalid`, `child_result_encoding_invalid` — integrity or encoding failure.
+- `artifact_read_failed`, `artifact_spill_failed`, `artifact_error` — artifact I/O failure.
+- `result_too_large_for_inline` — explicit inline request exceeded the inline cap.
+
+Delegate errors include whether a child process was created, preserved artifact hints when known, and remediation text. Usage missing from the provider is reported as `unavailable`, not synthesized as zero.
+
+## Parent outcome separation
+
+After evaluation, the parent attempts a durable `outcome.json` write separately from child-written `result.json`. This avoids either writer overwriting the other's evidence, but the write is best-effort: its failure is ignored and does not change the returned adjudication, so `outcome.json` may be absent.

package/docs/tools/bg_run.md

@@ -0,0 +1,168 @@
+---
+doc_id: tools/bg_run
+audience: agent
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [tool:bg_run]
+covers_sources: []
+---
+# `bg_run`
+
+<!-- pi-docs:begin name="tool-contract-bg_run" generator="scripts/docs/generate.mjs" -->
+- Label: **Background Run**
+- Source: `src/extension.ts:671`
+- Description: Start a named long-running shell command in the background and return immediately with a task ID and output path. By default, completed, failed, or killed terminal state is delivered automatically as <background-task-notification> and starts a follow-up agent turn; do not sleep or poll merely to wait. Output is written to .pi/tasks and model-visible logs are bounded to 50.0KB.
+- Root schema: `object`
+
+| Field | Required | Type | Description | Constraints |
+| --- | --- | --- | --- | --- |
+| `command` | yes | `string` | Shell command to start in the background |  |
+| `description` | no | `string` | Optional longer human-readable context for the task |  |
+| `isAgent` | yes | `boolean` | Required. Set true only when this background task launches an LLM/agent process, such as a child `pi -p ...` or `pi --mode json ...`, so Pi-agent telemetry can be collected. Set false for scripts, tests, servers, sleeps, and ordinary shell commands. |  |
+| `name` | yes | `string` | Short human-readable task name shown in the bg footer dock. Required; use 2-6 words, not the raw command. |  |
+| `notifyOnCompletion` | no | `boolean` | Whether to deliver the durable terminal notification. Default: true; disable only when deliberately taking over completion monitoring. |  |
+| `timeoutSeconds` | no | `number` | Optional timeout; task is failed and killed when exceeded |  |
+| `triggerOnCompletion` | no | `boolean` | Whether that notification should automatically trigger a follow-up agent turn. Default: true for bg_run; requires notifyOnCompletion. |  |
+
+<details>
+<summary>Normalized TypeBox contract</summary>
+
+
+```json
+{
+  "properties": {
+    "command": {
+      "description": "Shell command to start in the background",
+      "type": "string"
+    },
+    "description": {
+      "description": "Optional longer human-readable context for the task",
+      "type": "string"
+    },
+    "isAgent": {
+      "description": "Required. Set true only when this background task launches an LLM/agent process, such as a child `pi -p ...` or `pi --mode json ...`, so Pi-agent telemetry can be collected. Set false for scripts, tests, servers, sleeps, and ordinary shell commands.",
+      "type": "boolean"
+    },
+    "name": {
+      "description": "Short human-readable task name shown in the bg footer dock. Required; use 2-6 words, not the raw command.",
+      "type": "string"
+    },
+    "notifyOnCompletion": {
+      "description": "Whether to deliver the durable terminal notification. Default: true; disable only when deliberately taking over completion monitoring.",
+      "type": "boolean"
+    },
+    "timeoutSeconds": {
+      "description": "Optional timeout; task is failed and killed when exceeded",
+      "type": "number"
+    },
+    "triggerOnCompletion": {
+      "description": "Whether that notification should automatically trigger a follow-up agent turn. Default: true for bg_run; requires notifyOnCompletion.",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "command",
+    "isAgent",
+    "name"
+  ],
+  "type": "object"
+}
+```
+
+</details>
+<!-- pi-docs:end name="tool-contract-bg_run" -->
+
+Start a named long-running shell command in the background and return immediately.
+
+## Schema
+
+
+Required public fields:
+
+- `name: string` — concise 2-6 word task name for the footer dock.
+- `command: string` — shell command to run.
+- `isAgent: boolean` — explicit telemetry control; `true` only for LLM/agent processes such as child `pi -p ...` or `pi --mode json ...`.
+
+Optional fields:
+
+- `description: string`
+- `timeoutSeconds: number`
+- `notifyOnCompletion: boolean`
+- `triggerOnCompletion: boolean`
+
+Legacy argument preparation can derive a missing `name` from `description` or `command`, but the public schema remains strict and requires `name`, `command`, and `isAgent`.
+
+## When to use
+
+Use for long-running tests, builds, servers, watchers, sleeps, and child agent work. Do not use normal foreground shell tools for commands expected to outlive the current turn.
+
+## Defaults
+
+- `notifyOnCompletion`: `true`.
+- `triggerOnCompletion`: `true`.
+- `timeoutSeconds`: absent means no timeout.
+- `isAgent`: no default in the tool contract; callers must provide a boolean. It is not inferred from command text.
+
+## Lifecycle
+
+The tool returns a task id, current `running` status, pid if known, output path, and completion-delivery guidance. Terminal statuses are exactly `completed`, `failed`, or `killed`. With default delivery, terminal state is sent as `<background-task-notification>` and starts a follow-up agent turn; after launching, do not sleep or poll merely to wait.
+
+## Examples
+
+```json
+{"name":"Docs build","command":"npm run docs","isAgent":false}
+```
+
+```json
+{"name":"Child summary","command":"pi -p 'summarize changes'","isAgent":true,"timeoutSeconds":600}
+```
+
+```json
+{"name":"Manual server","command":"npm run dev","isAgent":false,"notifyOnCompletion":false,"triggerOnCompletion":false}
+```
+
+## Output/result
+
+Text result:
+
+```text
+Started background task <name> (<id>)
+Status: running
+PID: <pid|unknown>
+Output: .pi/tasks/.../<id>.output
+Terminal notification: enabled.
+Automatic follow-up turn: enabled.
+...
+```
+
+Structured details include `task`, a snapshot with command, status, output path, cwd, timing, pid, byte count, `isAgent`, delivery flags, telemetry fields when available, and error when present.
+
+## Errors
+
+- Missing/non-object args in preparation: `bg_run arguments must be an object`.
+- Missing command: `bg_run requires command string`.
+- Missing `isAgent`: loud error explaining true/false use.
+- Empty command at execution: `Background command is empty`.
+- Shell/spawn/timeout/output-cap failures become loud task failures.
+
+## Runtime artifacts
+
+Creates `.pi/tasks/<session-id>-<pid>/<task-id>.output` and `.json`. If `isAgent:true` and the command matches an interceptable POSIX `pi -p`, `pi --print`, or `pi --mode json` invocation, a temporary telemetry wrapper file is also written in the task directory.
+
+## Safety boundaries
+
+The command runs through the platform shell and is not sandboxed. Use `isAgent:true` only to request Pi-agent telemetry wrapping; setting it does not make execution safer. Model-visible logs are bounded and point to the full output path.
+
+## Related docs
+
+- [Completion delivery](../concepts/completion-delivery.md)
+- [`bg_status`](bg_status.md)
+- [`bg_logs`](bg_logs.md)
+- [`bg_kill`](bg_kill.md)
+- [`/bg`](../commands/bg.md)
+- [Background task runtime](../subsystems/background-task-runtime.md)
+
+## Source ownership/reference
+
+Tool registration lives in `src/extension.ts`; runtime lifecycle is owned by [background-task-runtime](../subsystems/background-task-runtime.md).

package/docs/tools/bg_run_pi_attested.md

@@ -0,0 +1,170 @@
+---
+doc_id: tools/bg_run_pi_attested
+audience: agent
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [tool:bg_run_pi_attested]
+covers_sources: []
+---
+# `bg_run_pi_attested`
+
+<!-- pi-docs:begin name="tool-contract-bg_run_pi_attested" generator="scripts/docs/generate.mjs" -->
+- Label: **Attested Pi Run**
+- Source: `src/extension.ts:756`
+- Description: Opt-in evidence-oriented direct Pi spawn. Launches exactly one `pi --mode json` child, records raw Pi events/stderr, hashes prompt/report/output, observes OAuth through ModelRegistry, and emits a strict attestation sidecar only after successful completion.
+- Root schema: `object`
+
+| Field | Required | Type | Description | Constraints |
+| --- | --- | --- | --- | --- |
+| `extraPiArgs` | no | `string[]` |  |  |
+| `model` | yes | `string` | Exact provider-local Pi model id to launch. |  |
+| `name` | yes | `string` | Short human-readable name for this attested Pi task. |  |
+| `prompt` | yes | `string` | Prompt bytes passed as the single user prompt to Pi. |  |
+| `provider` | yes | `string` | Exact Pi provider to launch, for example openai-codex or anthropic. |  |
+| `reportPath` | yes | `string` | Relative path, inside the task cwd, that the child Pi run must write as its report. |  |
+| `thinking` | no | `string` | Optional Pi thinking level argument. |  |
+| `timeoutSeconds` | no | `number` | Optional timeout; task is failed and killed when exceeded |  |
+
+<details>
+<summary>Normalized TypeBox contract</summary>
+
+
+```json
+{
+  "properties": {
+    "extraPiArgs": {
+      "items": {
+        "description": "Additional literal Pi argv entries; mode/provider/model/api-key args are rejected.",
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "model": {
+      "description": "Exact provider-local Pi model id to launch.",
+      "type": "string"
+    },
+    "name": {
+      "description": "Short human-readable name for this attested Pi task.",
+      "type": "string"
+    },
+    "prompt": {
+      "description": "Prompt bytes passed as the single user prompt to Pi.",
+      "type": "string"
+    },
+    "provider": {
+      "description": "Exact Pi provider to launch, for example openai-codex or anthropic.",
+      "type": "string"
+    },
+    "reportPath": {
+      "description": "Relative path, inside the task cwd, that the child Pi run must write as its report.",
+      "type": "string"
+    },
+    "thinking": {
+      "description": "Optional Pi thinking level argument.",
+      "type": "string"
+    },
+    "timeoutSeconds": {
+      "description": "Optional timeout; task is failed and killed when exceeded",
+      "type": "number"
+    }
+  },
+  "required": [
+    "model",
+    "name",
+    "prompt",
+    "provider",
+    "reportPath"
+  ],
+  "type": "object"
+}
+```
+
+</details>
+<!-- pi-docs:end name="tool-contract-bg_run_pi_attested" -->
+
+`bg_run_pi_attested` is an opt-in evidence-producing Pi run. It is separate from `bg_run`: it never accepts a shell command and launches exactly one direct child Pi invocation in JSON mode.
+
+## Public arguments
+
+Required:
+
+- `name: string` — concise task name; later validation rejects blank names.
+- `provider: string` — exact Pi provider; later validation rejects blank provider.
+- `model: string` — provider-local model id; later validation rejects blank model.
+- `prompt: string` — prompt passed as the single Pi user prompt; empty string is rejected.
+- `reportPath: string` — relative path inside task cwd that the child prompt/run is expected to write; blank, absolute, escaping, `.git/...`, and `.pi/tasks/...` targets are rejected.
+
+Optional:
+
+- `extraPiArgs: string[]` — literal extra Pi argv entries. Entries must be strings.
+- `thinking: string` — structured Pi thinking level; if non-blank, emitted as `--thinking <value>`.
+- `timeoutSeconds: number` — optional timeout; positive finite values are floored by the registry, non-positive/non-finite values are effectively not used as a timeout.
+
+There are no provider/model/prompt defaults and no notification parameters on this tool. The registry creates attested tasks with background completion notification/wake disabled (`notifyOnCompletion:false`, `triggerOnCompletion:false`) while still publishing terminal snapshots through the task system. The current TypeBox declaration does not set `additionalProperties:false`; preparation reads only the fields above and validates their types.
+
+Forbidden in `extraPiArgs`: `--api-key`, `--auth-file`, `-p`, `--print`, `--mode`, structured duplicates of `--provider`, `--model`, and `--thinking`.
+
+## Launch shape
+
+The logical argv is:
+
+```text
+pi --mode json --provider <provider> --model <model> [--thinking <thinking>] [...extraPiArgs] <prompt>
+```
+
+The registry resolves the platform-specific Pi executable and spawns without a shell (`shell:false`). On POSIX this is normally the `pi` executable; on Windows the package may launch Pi through the resolved Node/CLI path while the attested logical argv remains `['pi', ...]`.
+
+The child environment strips metered/direct API variables including OpenAI, Anthropic, OpenRouter, `PI_API_KEY`, base URL overrides, and `PI_AUTH_FILE`. Authentication is not accepted from tool arguments.
+
+## OAuth and route observation
+
+Before spawn, the producer asks the model registry for the exact `provider/model` and requires `ModelRegistry.isUsingOAuth`. Supported observed OAuth classes are:
+
+- `openai-codex` → `pi-codex-oauth`, channel `subscription-codex`;
+- `anthropic` → `pi-anthropic-oauth`, channel `subscription-anthropic`.
+
+The child Pi JSON event stream must later contain exactly one session, one `agent_start`, at least one assistant message, and one `agent_end`; assistant messages must report a stable provider/model, and the last assistant `stopReason` value reported in the stream must be `stop`. A later assistant message that omits `stopReason` does not clear an earlier reported value. The observed provider/model must match the selected registry model before attestation is accepted.
+
+## Runtime files
+
+Files live under the background task runtime directory:
+
+```text
+.pi/tasks/<session-id>-<pid>/<task-id>.output
+.pi/tasks/<session-id>-<pid>/<task-id>.json
+.pi/tasks/<session-id>-<pid>/<task-id>.pi-events.jsonl
+.pi/tasks/<session-id>-<pid>/<task-id>.stderr
+.pi/tasks/<session-id>-<pid>/<task-id>.pi-telemetry-wrapper.cjs
+.pi/tasks/<session-id>-<pid>/<task-id>.attestation.json
+```
+
+For attested runs the wrapper file is an evidence note (`direct-spawn attested Pi task; no shell telemetry wrapper is used`), not a shell wrapper. Raw child stdout is captured as Pi JSON events; raw stderr is captured separately. Human-readable task output is reconstructed from assistant/tool events on success, or from stderr/error text on failure.
+
+## Sidecar contents
+
+Successful attestation sidecars use schema `phase2.pi_task_attestation.v1` and include:
+
+- locator: session dir, task id, metadata/output/events/stderr/wrapper refs;
+- source hashes for metadata, output, events, stderr, wrapper;
+- lifecycle: status, agent flag, times, exit code/signal, bytes written;
+- invocation: Pi session id, logical argv, cwd realpath, provider, model id, provider-scoped model id, API identity, auth class, credential kind, route class, channel, `direct_api_key:false`, final stop reason;
+- authority: repo root realpath, start/finish commit and tree OIDs, clean-worktree booleans;
+- artifacts: prompt hash, task output hash, stderr hash, transcript hash, report hash;
+- `attestation_sha256`: hash of the canonical sidecar without that self field.
+
+The worktree must be clean at start and finish, and the commit/tree must not change during the task.
+
+## Durability and failure behavior
+
+The sidecar is written only after successful child completion, event parsing, report hashing, git authority checks, and attestation construction. The final sidecar write uses durable same-directory replacement. In-memory terminal completion (`task.status = completed` plus terminal publication) happens after the sidecar write returns; the metadata file may have a completed snapshot staged earlier as part of the sidecar construction path.
+
+If the child fails, times out, is killed, emits malformed/incomplete events, writes no required report, changes git authority, uses non-OAuth/unsupported auth, or fails attestation construction, the task is failed/killed and no successful sidecar is emitted. Existing raw evidence files (`*.pi-events.jsonl`, `*.stderr`, `*.output`, metadata) remain for diagnosis.
+
+## Trust boundary
+
+This is local, unsigned, same-user-writable evidence. It is useful for local auditability and reproducibility of what this extension observed, but it is not a remote cryptographic proof, not a signature, and not tamper-resistant against a user or process that can write the working tree or `.pi/tasks` directory.
+
+## Intended use
+
+Use `bg_run_pi_attested` when the user explicitly asks for an evidence-producing Pi child with local hashes and route/auth observation. Use ordinary `bg_run` for normal background commands or agent jobs that do not need this sidecar contract.

package/docs/tools/bg_status.md

@@ -0,0 +1,111 @@
+---
+doc_id: tools/bg_status
+audience: agent
+mode: mixed
+review_policy: contract
+stability: stable
+covers_surfaces: [tool:bg_status]
+covers_sources: []
+---
+# `bg_status`
+
+<!-- pi-docs:begin name="tool-contract-bg_status" generator="scripts/docs/generate.mjs" -->
+- Label: **Background Status**
+- Source: `src/extension.ts:821`
+- Description: Inspect one background task or list all running/recent background tasks. This is a point-in-time inspection tool, not a waiting primitive.
+- Root schema: `object`
+
+| Field | Required | Type | Description | Constraints |
+| --- | --- | --- | --- | --- |
+| `taskId` | no | `string` | Optional task ID or unambiguous prefix. If omitted, all running/recent tasks are returned. |  |
+
+<details>
+<summary>Normalized TypeBox contract</summary>
+
+
+```json
+{
+  "properties": {
+    "taskId": {
+      "description": "Optional task ID or unambiguous prefix. If omitted, all running/recent tasks are returned.",
+      "type": "string"
+    }
+  },
+  "required": [],
+  "type": "object"
+}
+```
+
+</details>
+<!-- pi-docs:end name="tool-contract-bg_status" -->
+
+Inspect one background task or list all running/recent tasks.
+
+## Schema
+
+
+Optional fields:
+
+- `taskId: string` — exact task id or unambiguous prefix. If omitted, all retained tasks are returned.
+
+## When to use
+
+Use for deliberate point-in-time inspection: the user asks for an update, completion handling was disabled, or there is concrete evidence a task is hung.
+
+Do **not** use `bg_status` as a polling or waiting primitive. A `running` result is not an instruction to call it again, and a terminal notification does not need reconfirmation.
+
+## Defaults
+
+No `taskId` means list all tasks retained by this extension runtime.
+
+## Lifecycle
+
+Returns current snapshots. Status values are exactly `running`, `completed`, `failed`, and `killed`.
+
+## Examples
+
+```json
+{}
+```
+
+```json
+{"taskId":"b1234"}
+```
+
+## Output/result
+
+Text content uses the same snapshot formatting as [`/jobs`](../commands/jobs.md), including output path. Structured details are:
+
+```ts
+{ tasks: BgTaskSnapshot[] }
+```
+
+Each snapshot includes delivery flags, notification state, optional telemetry reported by the task, and optional error.
+
+## Errors
+
+- Missing id is only possible when an empty string is supplied: `Task ID is required`.
+- Unknown id/prefix: `Unknown background task ID: <id>`.
+- Ambiguous prefix: lists matching task ids.
+
+Tool execution rejects loudly; there is no silent fallback to an empty list.
+
+## Runtime artifacts
+
+Read-only in-memory snapshots. It does not read or write `.pi/tasks` files.
+
+## Safety boundaries
+
+Inspection only. Not a polling primitive, not a wait loop, and not a task-control operation.
+
+## Related docs
+
+- [`/jobs`](../commands/jobs.md)
+- [`bg_logs`](bg_logs.md)
+- [`bg_run`](bg_run.md)
+- [Completion delivery](../concepts/completion-delivery.md)
+- [Background task runtime](../subsystems/background-task-runtime.md)
+
+## Source ownership/reference
+
+Tool registration lives in `src/extension.ts`; snapshots and task resolution are owned by [background-task-runtime](../subsystems/background-task-runtime.md).