90 lines
5.7 KiB
Markdown
90 lines
5.7 KiB
Markdown
---
|
|
status: resolved
|
|
claimed-by: 019fbffd-0114-7f56-bce9-2c4e67bb7d52
|
|
claimed-at: 2026-08-01T21:01:01-04:00
|
|
parent: "[[083-pi-subagent-result-delivery-map|Pi subagent result delivery]]"
|
|
blocked-by: []
|
|
tags:
|
|
- ticket/task/afk
|
|
---
|
|
|
|
# Pi subagent result delivery current extension inventory
|
|
|
|
## Question
|
|
|
|
Inventory the current dotfiles-managed Pi subagent extension's result, status, wait, lifecycle, storage, and UI behavior so the design decisions are grounded in the deployed implementation rather than memory.
|
|
|
|
## Canonical result
|
|
|
|
The deployed extension is `modules/agents/pi/extensions/subagents`, copied by `modules/agents/pi/pi.nix` into the Home Manager managed `~/.pi/agent/extensions` tree.
|
|
It exposes tools and slash commands for spawn, batch spawn, list, status, result, wait, cancel, clear, diagnostics, and UI toggling.
|
|
|
|
`subagent_spawn` and `subagent_batch` are non-blocking.
|
|
They create in-memory child records, return accepted ids immediately, and start children through a bounded supervisor queue.
|
|
The default concurrency is three children.
|
|
The default context is independent.
|
|
The default tool profile is `read-only`, with built-in profiles for no tools, read-only, read-only plus safe bash, and full tools.
|
|
Named agents and config are read from `~/.pi/agent/agents`, trusted project `.pi/agents`, `~/.pi/agent/subagents.json`, and trusted project `.pi/subagents.json`.
|
|
|
|
The lifecycle states are `queued`, `starting`, `running`, `settling`, `completed`, `failed`, `cancelled`, `timed_out`, and `orphaned`.
|
|
The supervisor currently drives queued, starting, running, settling, completed, failed, cancelled, and timed_out.
|
|
`orphaned` exists in the type model but is not assigned by the current supervisor path.
|
|
Startup timeout defaults to 30 seconds.
|
|
Runtime timeout defaults to disabled.
|
|
Cancellation and shutdown mark active children cancelled.
|
|
Timeout marks children timed_out and attempts to cancel the process.
|
|
|
|
A child is a separate Pi RPC process launched with `--mode rpc`, `--no-extensions`, and an explicit `--extension` pointing back to the subagents extension.
|
|
Forked children receive the parent session file through `--fork`.
|
|
Independent children do not.
|
|
The child environment strips parent `PI_SESSION_ID`, `PI_SESSION_FILE`, `PI_PROVIDER`, `PI_MODEL`, and `PI_REASONING_LEVEL`.
|
|
Completion is detected from the child RPC `agent_settled` event, after which the runner asks the child for `get_last_assistant_text` and stores that text as the result.
|
|
|
|
`subagent_status` returns the current lifecycle record for one id.
|
|
The record includes id, label, agent, ad-hoc flag, context, state, cwd, model, thinking, tools, timestamps, elapsed time, last event, stop reason, result availability, child session, and error.
|
|
`subagent_list` returns all active records plus terminal records that have not been explicitly cleared.
|
|
Terminal records remain visible and addressable by id while the supervisor lives, until `subagent_clear` or `/subagent-clear` removes them from the visible current-session work set.
|
|
|
|
`subagent_result` is polling-friendly.
|
|
Before completion it returns a result object with `running: true`, `resultAvailable: false`, and no result text.
|
|
After successful completion it returns `running: false`, `resultAvailable: true`, and the final assistant text.
|
|
Failed terminal states return `running: false`, the terminal state, and the error when one exists.
|
|
The result object is not marked read, acknowledged, consumed, or hidden by retrieval.
|
|
|
|
`subagent_wait` is blocking by design.
|
|
It accepts ids, optional timeout, and mode `all` or `any`.
|
|
It returns ids, mode, ready flag, result objects for all requested ids, pending statuses, timedOut flag, and elapsed time.
|
|
A timeout returns pending data but does not cancel children.
|
|
An abort rejects the wait and also does not cancel children.
|
|
Unknown ids and empty id sets are errors.
|
|
|
|
Storage is process-local.
|
|
The supervisor and all child records live in module-level memory for the extension process.
|
|
Terminal results are retained in the in-memory child map until explicit clear.
|
|
On `session_shutdown`, the supervisor cancels active children and is cleared.
|
|
There is no durable result store, unread queue, acknowledgment state, or cross-session recovery.
|
|
The only durable transcript-adjacent output is `pi.appendEntry("subagent_milestone", { event, status })` for accepted, completed, failed, cancelled, and timed_out milestones.
|
|
|
|
The UI behavior is a small Pi widget plus notifications.
|
|
When UI is available and enabled, the widget is registered as `subagents`.
|
|
Collapsed mode shows one summary line with running, queued, and terminal counts.
|
|
Expanded mode adds one line per listed status with id, label, context, state, elapsed seconds, model, tool profile, last event, and whether a result is available.
|
|
The `subagent-ui` command toggles expanded mode.
|
|
Spawn and UI commands notify the user.
|
|
List, status, result, wait, batch, diagnostics, cancel, and clear commands display JSON through notifications.
|
|
Milestones update the transcript via `appendEntry`, but they do not inject an ordinary assistant message into the active conversation.
|
|
There is no visible unread result model or reconciliation workflow beyond polling status, polling result, waiting, clearing terminal work, or using the widget.
|
|
|
|
## Source files inventoried
|
|
|
|
- `modules/agents/pi/pi.nix`
|
|
- `modules/agents/pi/extensions/subagents/index.ts`
|
|
- `modules/agents/pi/extensions/subagents/supervisor.ts`
|
|
- `modules/agents/pi/extensions/subagents/runner.ts`
|
|
- `modules/agents/pi/extensions/subagents/types.ts`
|
|
- `modules/agents/pi/extensions/subagents/status.ts`
|
|
- `modules/agents/pi/extensions/subagents/ui.ts`
|
|
- `modules/agents/pi/extensions/subagents/config.ts`
|
|
- `modules/agents/pi/extensions/subagents/agents.ts`
|
|
- `modules/agents/pi/extensions/subagents/supervisor.test.ts`
|