@tduyng/pi-shell 0.0.2 → 0.0.3

package/README.md

@@ -1,62 +1,64 @@
 # @tduyng/pi-shell
 
-Background shell execution for pi. One `bg` tool covers the full lifecycle: start, read output, kill, and list tasks.
+Park a long command in the background and get woken when it matters. One `bg` tool covers start, read, kill, and list.
 
-## The bg tool
+## What it costs
 
-A single tool with an `action` field. Each `bg` task runs in the current working directory with a fresh shell, like pi's own bash. There is no persistent shell session.
+`bg` is 197 tokens a request for the whole lifecycle, where four tools would have cost four schemas.
+
+The saving is in the wait, not the schema. A test suite, a build, or a dev server run for minutes and then return a log nobody reads whole. This tool holds the bytes and hands the model the tail it asked for, so a five minute build does not become a five minute stall in the transcript.
+
+## The tool
+
+One tool with an `action` field. Each task runs in the current working directory with a fresh shell, like pi's own bash. There is no persistent shell session.
 
 ### start
 
-Spawns a detached command. Returns `task_id` (8-char UUID prefix), `pid`, and the absolute `log` path. stdout and stderr stream to a log file at `<agentDir>/shell-logs/<taskId>.log`. The task runs silently until you ask about it. Optional `timeout` caps the task (max 600 seconds). Default is no timeout.
+Spawns a detached command and returns `task_id` (an 8-character UUID prefix), `pid`, and the absolute log `path`. stdout and stderr stream to `<agentDir>/shell-logs/<taskId>.log`. The task runs silently until you ask about it. An optional `timeout` caps it at 600 seconds, with no timeout by default.
 
 ### output
 
-Reads new bytes since the last read using a byte cursor. The `wait` parameter controls behavior:
+Reads new bytes since the last read, through a byte cursor.
 
-- `"now"`: returns immediately with whatever is available.
-- `"next_write"`: parks the agent until the first new byte appears, then wakes it with the new output.
-- `"exit"`: parks the agent until the process ends, then delivers the verdict plus the unread tail.
+| `wait` | Behaviour |
+| --- | --- |
+| `now` | Return whatever is available |
+| `next_write` | Park the agent until the first new byte, then wake it |
+| `exit` | Park the agent until the process ends, then deliver the verdict and the unread tail |
 
-The cursor never advances on wake reads, so a later `bg` output call still sees every byte from the stored offset onward.
+A wake read does not advance the cursor, so a later `output` still sees every byte from the stored offset.
 
 ### kill
 
-Sends SIGTERM to the process group, polls every 50ms for up to 1 second, then escalates to SIGKILL. Accepts `task_id`, raw `pid`, or `port` (resolved to a pid via `lsof -ti`).
+SIGTERM to the process group, polled every 50ms for up to a second, then SIGKILL. Takes a `task_id`, a raw `pid`, or a `port` resolved through `lsof -ti`.
 
 ### status
 
-Lists all tasks with id, pid, state (running, exited, killed), cursor offset, and the first 80 characters of the command.
-
-## Honest exits
-
-Pi 0.99 already reports a signal-killed command as a failure. Its bash backend returns `128 + signal` for a child that died without an exit code, and raises when a command ends with neither an exit code nor a signal. This extension does not override that backend.
-
-`shell-process.test.ts` runs `kill -9` against pi's own bash tool and asserts a nonzero result in the 128+n family, so a pi release that reintroduces the silent success fails here.
+Every task with id, pid, state (running, exited, killed), cursor offset, and the first 80 characters of the command.
 
-A `tool_result` handler annotates the two cases where the exit code alone cannot tell the model what happened. An exit 1 from `grep`, `rg`, or `find` means no matches, and a command killed by its timeout did not finish cleanly. Each note stops the model from retrying a search that already succeeded.
+## Waking only when asked
 
-## Middle-out output view
+Only a task the model parked on, through `wait: "exit"` or `wait: "next_write"`, injects a message when it finishes. A burst of exits coalesces into one message on a byte budget: 8 KB total by default, at least 1 KB per task. The wake carries the exit verdict, the unread tail, and the log path, so the model gets the result without a read-back.
 
-Large logs are truncated to a head and tail, defaulting to 8KB total, with an exact omitted-byte count in between. The read window per side is 16KB, split on UTF-8 sequence boundaries so characters are never cut mid-byte. The full log stays on disk at the path always shown in results.
+The wake fires from the `onExit` callback through `queueMicrotask` rather than polling. A wake that lands mid-turn goes to the follow-up queue and is delivered at the next `agent_settled`.
 
-## Wake on exit
+A task parked on `wait: "exit"` also gets a silence check. Every 30 seconds it reads the log size, and after 10 minutes with no new bytes the agent is woken once with the elapsed time and the log path. It fires again only after output resumes and stops again. No model call runs for the check.
 
-Only a task the model parked on (via `wait: "exit"` or `wait: "next_write"`) injects a user message when it finishes. A burst of exits coalesces into one message sharing a byte budget: default 8KB total, minimum 1KB per task. The wake carries the exit verdict, the unread tail, and the full log path per task, so the model gets the result without a read-back.
+## Reading a log without drowning in it
 
-The wake fires from the `onExit` callback via `queueMicrotask`, not from polling. If the agent is mid-turn, the wake lands in the follow-up queue and is delivered at the next `agent_settled` boundary.
+Large output is cut to a head and a tail, 8 KB total by default, with the exact omitted byte count between them. Each side reads up to 16 KB, split on UTF-8 sequence boundaries so a character is never cut mid-byte. The full log stays on disk at the path every result shows.
 
-## Stall check
+A `tool_result` handler annotates the two cases where an exit code cannot say what happened: exit 1 from `grep`, `rg`, or `find` means no matches, and a command killed by its timeout did not finish cleanly. Each note stops the model retrying a search that already succeeded.
 
-A task the model parked on with `wait: "exit"` also gets a silence check. Every 30 seconds it reads the log size. After 10 minutes with no new bytes, the agent is woken once with the elapsed time and the log path. The wake fires again only after output resumes and stops again. No model call runs for the check.
+pi already reports a signal-killed command as a failure: its bash backend returns `128 + signal` and raises when a command ends with neither an exit code nor a signal. `shell-process.test.ts` runs `kill -9` against pi's own bash tool and asserts a nonzero result in that family, so a pi release that reintroduces the silent success fails here.
 
-## Footer indicator
+## Footer
 
-The footer shows a dot and the live task count (e.g. "2 bg running") while any background task is active. It clears when the last task exits.
+A dot and the live count while any task runs, for example `2 bg running`. It clears when the last one exits.
 
-## Task lifecycle
+## Lifecycle
 
-Each `bg` task is in-memory only. It dies with the pi process. Persisted session entries record the command, log path, and start time so the model can read the log after a reload. The live process handle is gone. Detached grandchildren that inherit the shell's stdout keep writing to the log after the shell exits. The log stream stays open until both the stdout and stderr pipes close. Ending it on the first close would drop data the second pipe still delivers.
+Each task is in-memory and dies with the pi process. The session records the command, log path, and start time, so the model can still read the log after a reload, even though the process handle is gone. Detached grandchildren that inherit the shell's stdout keep writing after the shell exits, and the log stream closes only when both pipes close, since ending it on the first close would drop data the second one still delivers.
 
 ## Install
 
@@ -68,4 +70,4 @@ Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-shell`
 
 ## Configure
 
-- `SHELL`: set to `0`, `false`, `no`, or `off` to disable the extension entirely.
+`SHELL`, set to `0`, `false`, `no`, or `off`, disables the extension.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tduyng/pi-shell",
-  "version": "0.0.2",
-  "description": "Background processes the agent parks on: one bg tool with start/output/kill/status, cursor reads that never re-read bytes, and a runtime wake-up when a task exits.",
+  "version": "0.0.3",
+  "description": "One bg tool for background processes, woken on exit, with cursor reads that never re-read bytes.",
   "keywords": [
     "pi",
     "pi-package",