@astralyn/pi 0.84.5 → 0.84.7

package/docs/bundled/extensions/background.md

@@ -1,64 +1,99 @@
 # background — background bash tasks
 
-Adds `bg_bash`, `bg_logs`, and `bg_kill` tools plus the `/bg` command. Long-running commands (dev servers, watch builds, slow tests) run in the background while the agent keeps working; when a task ends, its status, exit code, and a tail of its output arrive automatically as a notification.
+Adds the `bg` tool (actions: `create`, `read`, `wait`, `kill`, `list`) plus the `/bg` command. Long-running commands (dev servers, watch builds, slow tests) run in the background while the agent keeps working; when a task ends, its status, exit code, and a tail of its output arrive automatically as a notification.
 
-## Tools
+## Tool
 
-`bg_bash` starts a command and returns immediately with a task id and output file path:
+All five operations share one tool. Every call sets `action`; the remaining parameters belong to that action.
+
+### create
+
+Starts a command in the background and returns immediately with a task id and an output file path:
 
 ```json
-{ "command": "npm run build", "timeout": 300 }
+{ "action": "create", "command": "npm run build", "description": "build", "timeout": 300 }
 ```
 
-The optional `timeout` is in seconds; on expiry the task is killed and reported as `timeout`. The tool result only reports the start — the completion notification is the single source of truth for the outcome, so there is never a need to poll with sleep loops or repeated `bg_logs` calls.
+- `description` is a short model-written label (e.g. `dev server`) shown in `/bg`, task listings, and the completion notification.
+- `timeout` is in seconds; on expiry the task is killed and reported as `timeout`.
+- The command runs detached — appending `&` is never needed and would lose exit-code tracking.
+
+The tool result only reports the start. The completion notification is the single source of truth for the outcome, so there is never a need to poll with sleep loops or repeated reads.
 
-`bg_logs` reads a bounded slice of a task's output file while it runs or after it ends:
+### read
+
+Reads a bounded slice of a task's output file while it runs or after it ends:
 
 ```json
-{ "taskId": "bg-3f2a91", "mode": "tail", "bytes": 8192 }
+{ "action": "read", "taskId": "bg-3f2a91", "mode": "tail", "bytes": 8192 }
 ```
 
-`mode` defaults to `tail`; `bytes` defaults to 8KB and clamps between 256 bytes and 50KB. Truncated reads state the omission up front and always include the full output path.
+`mode` defaults to `tail`; `bytes` defaults to 8KB and clamps between 256 bytes and 50KB. Truncated reads state the omission up front and always include the full output path; reads of a running task say `still running`. The output file is a plain file — the built-in read tool also works on it for line-based paging.
+
+### wait
 
-`bg_kill` stops a single running task by killing its whole process tree:
+Blocks until a task finishes, within a bound:
 
 ```json
-{ "taskId": "bg-3f2a91" }
+{ "action": "wait", "taskId": "bg-3f2a91", "waitMs": 20000, "sinceBytes": 4096 }
 ```
 
-Killing does not bypass the normal pipeline: the task still finalizes as `killed` and its completion notification still arrives.
+- `waitMs` defaults to 20000 and clamps between 1000 and 60000.
+- `sinceBytes` (taken from a previous read/wait result) restricts the returned output to what was written after that offset; without it the last 32KB is returned. Offsets past EOF (for example after output truncation) fall back to the tail and say so.
+
+If the task finishes within the window, the result is delivered inline — status, exit code, runtime, and the bounded output delta — and the followUp notification is suppressed, so the completion is delivered exactly once. If the window expires, the result says the task is still running, includes a small tail peek so progress stays visible, and the notification fires later as usual. This is the only sanctioned way to wait; sleeping to emulate it is never correct.
+
+### kill
+
+Stops a single running task by killing its whole process tree:
+
+```json
+{ "action": "kill", "taskId": "bg-3f2a91" }
+```
+
+Killing does not bypass the normal pipeline: the task still finalizes as `killed` and its completion is delivered wherever it was awaited — inline via `wait`, or as the notification otherwise.
+
+### list
+
+Lists currently known tasks — running tasks first, then the five most recently finished, with any overflow folded into a trailing note:
+
+```json
+{ "action": "list" }
+```
 
 Task ids accept a unique prefix (with or without the `bg-` part); an ambiguous prefix is an error listing the candidates.
 
 ## Completion delivery
 
-When a task ends, the extension sends a `background-task` notification: a small XML message carrying the task id, terminal status, exit code, runtime, output file path, and the sanitized last ~4KB of output. While the agent is streaming, the notification queues behind the current run and is delivered when the run settles; when the agent is idle, it wakes a new turn so the result is acted on immediately.
+When a task ends, the extension sends a `background-task` notification: a small XML message carrying the task id, terminal status, exit code, runtime, output file path, the optional description, and the sanitized last ~4KB of output. While the agent is streaming, the notification queues behind the current run and is delivered when the run settles; when the agent is idle, it wakes a new turn so the result is acted on immediately.
 
-The transcript renders this notification as a one-line summary (`✓ bg-3f2a91 npm run build — completed, exit 0 in 34s`) with the output path below; expanding it shows the embedded output tail.
+The transcript renders this notification as a one-line summary (`✓ bg-3f2a91 npm run build — completed, exit 0 in 34s`; with a description: `✓ bg-3f2a91 dev server (npm run build) — completed, exit 0 in 34s`) with the output file's name below; expanding it shows the full output path and the embedded output tail.
 
 ## /bg
 
-`/bg` opens an inline task menu in the editor slot (like `/model`); the chat transcript stays visible above it. The list shows each task's status glyph, id, duration, and command; `Enter` opens the selected task's live output view, which replaces the menu.
+`/bg` opens an inline task menu in the editor slot (like `/model`); the chat transcript stays visible above it. The list shows each task's status glyph, id, duration, and label (the description over the first command line); `Enter` opens the selected task's live output view, which replaces the menu.
 
 | Key | In the task list | In the output view |
 |---|---|---|
-| `↑` / `↓` | Select task | — |
+| `↑` / `↓` | Select task | Scroll one line (freezes following) |
 | `Enter` | Open the selected task's output | — |
 | `k` | Kill the selected running task | Kill the viewed task |
-| `PgUp` / `PgDn` | — | Scroll the output; `PgUp` freezes it, scrolling back to the bottom resumes following |
+| `PgUp` / `PgDn` | — | Scroll a page; `PgUp` freezes following, scrolling back to the bottom resumes it |
 | `Esc` | Close the menu | Back to the task list |
 
-The output view polls the output file once per second and only ever reads the last 128KB. Outside an interactive TUI, `/bg` prints a bounded task summary instead.
+While a `bg wait` call is pending, its transcript row refreshes once per second (`bg wait bg-3f · waiting 12s/20s · +3.2KB new output`) until the result settles. The task list separates running tasks from finished ones with a `── finished ──` divider and adapts its visible rows to short terminal windows. The output view polls the output file once per second and only ever reads the last 128KB — and only when the task's output actually grew; a finished task's output is read once. Outside an interactive TUI, `/bg` prints a bounded task summary instead.
 
 ## Statusline
 
-Running and finished counts appear in the footer as `bg 2 running · 1 done`; the segment disappears when no tasks exist.
+Running and finished counts appear in the footer as `bg 2 running · 1 done`; tasks the stall watchdog has flagged are reported separately as `bg 2 running · 1 waiting for input · 1 done` (flagged tasks are running tasks, so the counts add up); the segment disappears when no tasks exist.
 
 ## Limits and lifecycle
 
 - Background tasks inherit the session's `PI_*` environment variables (`PI_SESSION_ID`, `PI_MODEL`, …) just like the built-in bash tool, snapshotted when the task starts.
+- Tasks run through the session's configured shell (`shellPath`) and honor `shellCommandPrefix`, matching the built-in bash tool. The prefix is applied at execution time only — it never appears in task labels or notifications.
 - Output streams directly to a system-temp file (`pi-bg-<id>.log`), never into the project or into memory. Memory holds only a byte counter.
 - Output is capped at 20MB. Hitting the cap kills the task and marks it `failed` rather than silently truncating.
-- At most 8 tasks may run concurrently; `bg_bash` reports the running tasks when the limit is reached.
-- Aborting the current turn (Esc) does not kill background tasks — that is what `bg_kill` and `/bg` are for.
+- At most 8 tasks may run concurrently; `create` reports the running tasks when the limit is reached.
+- Aborting the current turn (Esc) does not kill background tasks — that is what `kill` and `/bg` are for.
 - Session shutdown, `/reload`, new sessions, and session switches kill all running tasks; those kills are silent (no notification flood). There is no restart reattachment: finished-task records live only for the current session.
+- Output files outlive the session for later inspection (the `read` action and notifications keep pointing at them); Pi never deletes them automatically — the system temp directory's own cleanup policy applies.

package/docs/extensions.md

@@ -1079,6 +1079,19 @@ ctx.compact({
 });
 ```
 
+### ctx.getShellSettings()
+
+Returns the session's shell settings (`shellPath`, `commandPrefix`) exactly as the built-in bash tool uses them. Returns `undefined` on hosts that do not provide shell settings; fall back to reading settings from disk if your extension must. Optional on `ExtensionContext` for the same reason.
+
+```typescript
+pi.on("session_start", (_event, ctx) => {
+  const shell = ctx.getShellSettings?.();
+  if (shell?.commandPrefix) {
+    // Commands spawned by this extension should honor the same prefix as bash.
+  }
+});
+```
+
 ### ctx.getSystemPrompt()
 
 Returns Pi's current system prompt string.

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
 	"name": "@astralyn/pi",
-	"version": "0.84.5",
+	"version": "0.84.7",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@astralyn/pi",
-			"version": "0.84.5",
+			"version": "0.84.7",
 			"license": "MIT",
 			"dependencies": {
 				"@earendil-works/pi-agent-core": "0.84.2",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@astralyn/pi",
-	"version": "0.84.5",
+	"version": "0.84.7",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"piConfig": {

package/dist/extensions/subagent/retry.d.ts

@@ -1,17 +0,0 @@
-import type { SubagentRunDetails } from "./types.ts";
-export interface BeginSubagentRetryOptions {
-    attempt: number;
-    maxAttempts: number;
-    delayMs: number;
-    error: string;
-}
-export interface SubagentRetryView {
-    attempt: number;
-    maxAttempts: number;
-    remainingSeconds: number;
-    error: string;
-}
-export declare function beginSubagentRetry(run: SubagentRunDetails, options: BeginSubagentRetryOptions): void;
-export declare function clearSubagentRetry(run: SubagentRunDetails): void;
-export declare function getSubagentRetryView(run: SubagentRunDetails, now?: number): SubagentRetryView | undefined;
-//# sourceMappingURL=retry.d.ts.map

package/dist/extensions/subagent/retry.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/extensions/subagent/retry.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,WAAW,yBAAyB;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACd;AAWD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,EAAE,OAAO,EAAE,yBAAyB,GAAG,IAAI,CAWpG;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAGhE;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,kBAAkB,EAAE,GAAG,SAAa,GAAG,iBAAiB,GAAG,SAAS,CAY7G"}

package/dist/extensions/subagent/retry.js

@@ -1,41 +0,0 @@
-import { boundText } from "./activity.js";
-import { RETRY_ERROR_TEXT_LIMIT } from "./constants.js";
-function positiveInteger(value, fallback) {
-    return Number.isFinite(value) ? Math.max(1, Math.floor(value)) : fallback;
-}
-function retryError(error) {
-    const normalized = error.replace(/\s+/gu, " ").trim();
-    return boundText(normalized, RETRY_ERROR_TEXT_LIMIT).replace(/\s+/gu, " ").trim();
-}
-export function beginSubagentRetry(run, options) {
-    const attempt = positiveInteger(options.attempt, 1);
-    const maxAttempts = Math.max(attempt, positiveInteger(options.maxAttempts, attempt));
-    const delayMs = Number.isFinite(options.delayMs) ? Math.max(0, options.delayMs) : 0;
-    run.retry = {
-        attempt,
-        maxAttempts,
-        deadline: Date.now() + delayMs,
-        error: retryError(options.error),
-    };
-    run.currentActivity = `Retrying (${attempt}/${maxAttempts})…`;
-}
-export function clearSubagentRetry(run) {
-    run.retry = undefined;
-    if (run.currentActivity?.startsWith("Retrying"))
-        run.currentActivity = undefined;
-}
-export function getSubagentRetryView(run, now = Date.now()) {
-    const retry = run.retry;
-    if (!retry || !Number.isFinite(retry.deadline))
-        return undefined;
-    const attempt = positiveInteger(retry.attempt, 1);
-    const maxAttempts = Math.max(attempt, positiveInteger(retry.maxAttempts, attempt));
-    const currentTime = Number.isFinite(now) ? now : retry.deadline;
-    return {
-        attempt,
-        maxAttempts,
-        remainingSeconds: Math.max(0, Math.ceil((retry.deadline - currentTime) / 1000)),
-        error: retryError(typeof retry.error === "string" ? retry.error : ""),
-    };
-}
-//# sourceMappingURL=retry.js.map

package/dist/extensions/subagent/retry.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../../src/extensions/subagent/retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAiBxD,SAAS,eAAe,CAAC,KAAa,EAAE,QAAgB;IACvD,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC3E,CAAC;AAED,SAAS,UAAU,CAAC,KAAa;IAChC,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACtD,OAAO,SAAS,CAAC,UAAU,EAAE,sBAAsB,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACnF,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,GAAuB,EAAE,OAAkC;IAC7F,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACpD,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;IACrF,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpF,GAAG,CAAC,KAAK,GAAG;QACX,OAAO;QACP,WAAW;QACX,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO;QAC9B,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC;KAChC,CAAC;IACF,GAAG,CAAC,eAAe,GAAG,aAAa,OAAO,IAAI,WAAW,IAAI,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,GAAuB;IACzD,GAAG,CAAC,KAAK,GAAG,SAAS,CAAC;IACtB,IAAI,GAAG,CAAC,eAAe,EAAE,UAAU,CAAC,UAAU,CAAC;QAAE,GAAG,CAAC,eAAe,GAAG,SAAS,CAAC;AAClF,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,GAAuB,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IAC7E,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;IACxB,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC;QAAE,OAAO,SAAS,CAAC;IACjE,MAAM,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAClD,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,eAAe,CAAC,KAAK,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;IACnF,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC;IAChE,OAAO;QACN,OAAO;QACP,WAAW;QACX,gBAAgB,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,QAAQ,GAAG,WAAW,CAAC,GAAG,IAAI,CAAC,CAAC;QAC/E,KAAK,EAAE,UAAU,CAAC,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;KACrE,CAAC;AACH,CAAC","sourcesContent":["import { boundText } from \"./activity.ts\";\nimport { RETRY_ERROR_TEXT_LIMIT } from \"./constants.ts\";\nimport type { SubagentRunDetails } from \"./types.ts\";\n\nexport interface BeginSubagentRetryOptions {\n\tattempt: number;\n\tmaxAttempts: number;\n\tdelayMs: number;\n\terror: string;\n}\n\nexport interface SubagentRetryView {\n\tattempt: number;\n\tmaxAttempts: number;\n\tremainingSeconds: number;\n\terror: string;\n}\n\nfunction positiveInteger(value: number, fallback: number): number {\n\treturn Number.isFinite(value) ? Math.max(1, Math.floor(value)) : fallback;\n}\n\nfunction retryError(error: string): string {\n\tconst normalized = error.replace(/\\s+/gu, \" \").trim();\n\treturn boundText(normalized, RETRY_ERROR_TEXT_LIMIT).replace(/\\s+/gu, \" \").trim();\n}\n\nexport function beginSubagentRetry(run: SubagentRunDetails, options: BeginSubagentRetryOptions): void {\n\tconst attempt = positiveInteger(options.attempt, 1);\n\tconst maxAttempts = Math.max(attempt, positiveInteger(options.maxAttempts, attempt));\n\tconst delayMs = Number.isFinite(options.delayMs) ? Math.max(0, options.delayMs) : 0;\n\trun.retry = {\n\t\tattempt,\n\t\tmaxAttempts,\n\t\tdeadline: Date.now() + delayMs,\n\t\terror: retryError(options.error),\n\t};\n\trun.currentActivity = `Retrying (${attempt}/${maxAttempts})…`;\n}\n\nexport function clearSubagentRetry(run: SubagentRunDetails): void {\n\trun.retry = undefined;\n\tif (run.currentActivity?.startsWith(\"Retrying\")) run.currentActivity = undefined;\n}\n\nexport function getSubagentRetryView(run: SubagentRunDetails, now = Date.now()): SubagentRetryView | undefined {\n\tconst retry = run.retry;\n\tif (!retry || !Number.isFinite(retry.deadline)) return undefined;\n\tconst attempt = positiveInteger(retry.attempt, 1);\n\tconst maxAttempts = Math.max(attempt, positiveInteger(retry.maxAttempts, attempt));\n\tconst currentTime = Number.isFinite(now) ? now : retry.deadline;\n\treturn {\n\t\tattempt,\n\t\tmaxAttempts,\n\t\tremainingSeconds: Math.max(0, Math.ceil((retry.deadline - currentTime) / 1000)),\n\t\terror: retryError(typeof retry.error === \"string\" ? retry.error : \"\"),\n\t};\n}\n"]}