@clanker-code/pi-subagents 0.10.5

package/.plans/PLAN-next-changes.md

@@ -0,0 +1,183 @@
+# Plan: Next pi-subagents improvements
+
+This plan covers four coordinated changes:
+1. **Abort-detach + interruptible/timeout wait** for `get_subagent_result wait:true` (Escape no longer wedges the turn; default 4.5 min timeout).
+2. Configurable `waitTimeoutSeconds` setting (default 270s) exposed in `/agents → Settings`.
+3. `get_subagent_result` peek/tail capability with line numbers, regex filter, and `after` line offset.
+4. Description polish for `inherit_context` and `isolation: "worktree"`.
+
+All changes are scoped to keep diffs minimal and upstream-merge-friendly.
+
+### Key finding (abort-detach)
+Background spawns already do NOT pass the parent abort signal to `manager.spawn()` — only the now-dead foreground path did. So background subagents are already detached from Escape. The Escape-wedge symptom comes from `get_subagent_result wait:true`, which awaits `record.promise` and ignores the parent `signal`. Fix: race the wait against (a) the parent abort `signal` and (b) the configurable timeout, returning current status on either WITHOUT aborting the subagent.
+
+---
+
+## 1. Settings foundation: configurable `waitTimeoutSeconds`
+
+### Motivation
+Users want to avoid typical 5-minute LLM cache expiry; 4.5 minutes is a safe default. We also want this exposed in `/agents → Settings` so it is discoverable and adjustable per project.
+
+### Files touched
+- `src/types.ts` — add `waitTimeoutSeconds` to `AgentRecord`? No, this is runtime/config, not per-agent. Keep it in settings only.
+- `src/settings.ts`:
+  - Add `waitTimeoutSeconds?: number` to `SubagentsSettings`.
+  - Add `setWaitTimeoutSeconds: (seconds: number) => void` to `SettingsAppliers`.
+  - Add sanitize rule: integer, min 30, max 3600 (30s–1h). Default 270 (4.5m) when absent.
+  - Add `applySettings` wiring.
+- `src/index.ts`:
+  - Add `let waitTimeoutSeconds = 270` and getter/setter.
+  - Add to `snapshotSettings()`.
+  - Add `/agents → Settings` item with id `waitTimeoutSeconds`.
+  - Wire `applyValue` for `waitTimeoutSeconds` (numeric prompt, 30–3600).
+  - Add to `applyAndEmitLoaded` appliers object.
+  - Pass timeout value into `get_subagent_result` execute closure.
+
+### Return value / UI impact
+- `get_subagent_result` `wait` description: mention current configured timeout.
+- On timeout, return message:
+  ```
+  Agent is still running after 4 minutes 30 seconds.
+  This wait timed out to avoid blocking the parent session longer than the configured limit.
+  Call get_subagent_result with wait: true again to keep waiting, or omit wait to check status.
+  ```
+
+### Tests
+- `test/settings.test.ts` (if exists) or new assertions in `test/settings.test.ts`: sanitize boundaries.
+- New/updated test for `get_subagent_result` timeout behavior using a mocked promise and fake timers.
+
+---
+
+## 2. `get_subagent_result` peek parameter
+
+### Motivation
+Agents should be able to cheaply check recent output / logs without fetching the full result or conversation.
+
+### Proposed schema
+```ts
+peek: Type.Optional(
+  Type.Object({
+    lines: Type.Optional(Type.Number({ minimum: 1, description: "Number of trailing lines to return. Default: 20." })),
+    regex: Type.Optional(Type.String({ description: "Optional regex filter. Only lines matching this regex are included." })),
+    after: Type.Optional(Type.Number({ minimum: 0, description: "Return all lines after this 0-based line index. Overrides lines when set." })),
+  }, {
+    description: "Return a peek (tail/filter/update) of the agent result or streaming output file. Ignored when verbose is true.",
+  }),
+),
+```
+
+### Behavior
+- `peek` is ignored when `verbose: true`.
+- If `after` is set, return all lines with index > `after` (or >= `after+1`). Include line numbers.
+- Else, return the last `lines` lines (default 20). Include line numbers.
+- If `regex` is provided, filter matching lines **first**, then apply tail/after semantics. Include line numbers of the original source.
+- Source precedence:
+  1. If agent is running and `record.outputFile` exists, read from the streaming output file. Parse JSONL and extract assistant/toolResult text (most useful live content).
+  2. Else if `record.result` exists, split it into lines.
+  3. Else return: "No output yet."
+
+### Return format
+```
+Showing last 20 lines of agent output (line numbers from full output):
+
+[42] some line
+[43] another line
+...
+
+---
+Use verbose: true for the full conversation, or omit peek for the complete result.
+```
+
+If `regex` is used, add: `(filtered by regex: /.../)`.
+If `after` is used, add: `(lines after index N)`.
+
+### Implementation notes
+- Add helper `peekAgentOutput(record, peek)` in a new file or in `src/index.ts` near `get_subagent_result`.
+- For output-file JSONL parsing, reuse/extract from `output-file.ts` or read the file line-by-line.
+- Handle regex parse errors gracefully — return a clear error message.
+- Avoid reading the whole file into memory if possible; for now `readFileSync` is acceptable because output files are bounded by session length and the tail case is common.
+
+### Tests
+- New test file `test/get-subagent-result-peek.test.ts` or extend existing `status-note-wiring.test.ts`:
+  - Peek tail of result.
+  - Peek with regex.
+  - Peek `after` offset.
+  - Peek ignored when verbose true.
+  - Peek on running agent with output file.
+  - Regex parse error handling.
+
+---
+
+## 3. Description polish
+
+### `inherit_context`
+Current:
+> "If true, fork parent conversation into the agent. Default: false (fresh context)."
+
+New:
+> "If true, fork the parent conversation into the agent so it sees the chat history. Recommended for questions or requests that require current context. Default: false (fresh context)."
+
+Also update the eject template line in `src/index.ts`.
+
+### `isolation: "worktree"`
+Current:
+> "Set to 'worktree' to run the agent in a temporary git worktree (isolated copy of the repo). Changes are saved to a branch on completion."
+
+New:
+> "Set to 'worktree' to run the agent in a temporary git worktree that is automatically created from the current repo state at HEAD and removed on completion. Changes are saved to a branch. Requires the working directory to be a git repo with at least one commit."
+
+Also update README.md and `examples/agent-tool-description.md` to match.
+
+---
+
+## 4. Coordination / cross-cutting concerns
+
+- `get_subagent_result` description must mention the configurable timeout, e.g.:
+  > "If true, wait for the agent to complete before returning. Blocks up to the configured wait timeout (default 4.5 minutes). If the agent is still running when the timeout is reached, returns current status with instructions to call again. Default: false."
+
+- The settings UI should present `waitTimeoutSeconds` as "Wait timeout (30–3600s, default 270 = 4m30s)".
+
+- Tests for the timeout should use Vitest fake timers so they run fast and deterministically.
+
+- Peek should not duplicate verbose. Keep the contract: `verbose` = full conversation, `peek` = lightweight tail/filter.
+
+---
+
+## 5. Things to consider removing / avoiding
+
+Before jumping in, review whether any existing code becomes dead weight:
+
+- The foreground execution path in `src/index.ts` is now dead code after the background-by-default change. We currently left it in place but unreachable. Consider whether to remove it in a separate cleanup pass (it complicates future changes).
+- `run_in_background` param is deprecated but still in the schema. Keep it for prompt compatibility; do not remove.
+- `AgentConfig.runInBackground` frontmatter default is still consulted by `resolveAgentInvocationConfig`. Since `index.ts` now forces `runInBackground = true`, the frontmatter field is effectively ignored. Consider whether to deprecate it in docs or leave it as a no-op.
+
+---
+
+## 6. Acceptance criteria
+
+- [ ] `get_subagent_result wait:true` times out after the configured number of seconds and returns a clear message.
+- [ ] Timeout duration is configurable via `/agents → Settings` and persists to `.pi/subagents.json`.
+- [ ] `get_subagent_result` supports `peek` with `lines`, `regex`, and `after`.
+- [ ] `peek` returns line numbers and respects `verbose: true` (is ignored).
+- [ ] `inherit_context` and `isolation` descriptions are updated in tool schema, eject template, README, and example template.
+- [ ] All existing tests pass; new tests cover timeout + peek.
+- [ ] `npm run typecheck` and `npm run lint` clean.
+
+---
+
+## 7. Implementation order
+
+1. Add `waitTimeoutSeconds` setting (settings.ts + index.ts wiring).
+2. Implement wait timeout in `get_subagent_result` execute.
+3. Add `peek` parameter + helper.
+4. Update descriptions for `inherit_context` and `isolation`.
+5. Update README + example template.
+6. Write tests.
+7. Run full test/typecheck/lint.
+
+--- SUMMARY ---
+
+- Add a configurable `waitTimeoutSeconds` setting (default 270s) wired into `/agents → Settings` and `get_subagent_result wait:true`.
+- Add a `peek` object param to `get_subagent_result` for tail/filter/offset access to result/output-file with line numbers, ignored when `verbose` is true.
+- Polish `inherit_context` and `isolation: "worktree"` descriptions across schema, template, README, and example.
+- Tests, typecheck, lint.

package/.plans/README.md

@@ -0,0 +1,14 @@
+# `.plans/` — local planning scratch
+
+This directory holds ad-hoc plans, notes, and design sketches for this fork. It is gitignored so it does not pollute upstream diffs.
+
+## Conventions
+
+- One plan per file: `PLAN-<short-name>.md`.
+- Plans should include: motivation, files touched, behavior changes, UI/message changes, tests, acceptance criteria, implementation order, and a summary.
+- When a plan graduates to implementation, update the plan file with progress or archive it.
+- Delete obsolete plans to avoid stale guidance.
+
+## Active plans
+
+- `PLAN-next-changes.md` — configurable `get_subagent_result` wait timeout, peek/tail/regex/after parameter, and description polish for `inherit_context` / `isolation: "worktree"`.

package/AGENTS.md

@@ -0,0 +1,31 @@
+# CLAUDE.md — Notes for Claude / Coding Agents
+
+This is a fork of [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents).
+
+## Fork Relationship
+
+- We track upstream for useful changes but do **not** auto-merge.
+- This is a pseudo-fork: cherry-pick upstream commits when they apply cleanly and fit our direction; otherwise reimplement the same behavior in our own commits.
+- `package.json`, `README.md`, and `CHANGELOG.md` must reflect this fork (`@clanker-code/pi-subagents`).
+
+## Release Checklist
+
+Every release must:
+
+1. Bump `version` in `package.json`.
+2. Update `CHANGELOG.md` with a dated `[x.y.z]` section under `[Unreleased]`.
+3. **Update `README.md` to document any new or changed user-facing features.**
+4. Run and pass: `npm run lint`, `npm run typecheck`, `npm test`, `npm run build`.
+5. Commit and push.
+6. User publishes with `npm publish` from a clean `master` checkout.
+
+## Keeping Upstream In Sync
+
+Periodically run:
+
+```bash
+git fetch upstream
+git log --oneline --right-only --no-merges HEAD...upstream/master
+```
+
+Cherry-pick commits that are wanted and clean; reimplement anything that conflicts with fork-specific changes.