@signalridge/pi-subagents 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.13.0
+### Minor Changes
+
+- 2c7f8f1: Add user-controlled foreground-to-background handoff without restarting the child session, an adaptive conversation observer, and authoritative workflow Fleet rows through an optional validated UI protocol. Keep controls bound to an exact session and managed attempt, preserve steering drafts on native rejection, and retain cumulative activity and append-only transcripts across managed thread reuse.
+
+### Patch Changes
+
+- Updated dependencies [2c7f8f1]
+  - @signalridge/pi-subagents-protocol@1.6.0
+
 ## 1.12.0
 ### Minor Changes
 

package/README.md

@@ -11,7 +11,8 @@ A [pi](https://pi.dev) extension that brings **Claude Code-style autonomous sub-
 - **Parallel background agents** — spawn multiple agents that run concurrently with automatic queuing (configurable concurrency limit, default 4) and smart group join (consolidated notifications)
 - **Live FleetView UI** — one navigable list below the editor with a status mark per row, live tool activity, token counts, and text status labels. Enter opens the selected agent's conversation. Toggle via `/agents → Settings → Fleet view`
 - **FleetView** — Claude Code-style navigable list of `main` + every running subagent rendered below the editor (earliest-launched first). Press `↓` (or `←`) at an empty prompt to jump in, `↑`/`↓` to move the selection, `Enter` to open the selected agent's live, auto-updating conversation, `Esc` to return. Finished agents linger briefly before dropping out, and a viewer stays open through completion so you can read the final output. Toggle via `/agents → Settings → Fleet view`
-- **Conversation viewer** — select any retained agent with a session in `/agents` to open a live-scrolling, four-sided bordered overlay of its full conversation (auto-follows new content, scroll up to pause). Press `Enter` to chat: type a message, then `Enter` to send (`Esc` or an empty submit returns); it appears as a user message and redirects the agent after its current tool. Press `x` (then `x` again to confirm) to stop a running agent — this works for background agents too
+- **Conversation observer** — select a retained agent with a session in `/agents` to open a live observer. Public fullscreen hosts use the terminal-sized view; regular hosts keep the floating bordered view. Scroll up to pause following, use `Home` for the first available history and `End`/`Ctrl+End` for the latest. Bounded windows preserve older-message navigation; `]` pages available message text and `[` returns to its first text page. Press `Enter` to compose a steering message; native rejection retains the draft. Controls stay bound to the selected session and complete managed attempt, never a replacement that reuses its ID.
+- **Foreground handoff** — `Ctrl+B` at an empty, focused main prompt hands off one eligible foreground agent without restarting it. In its observer, `b` arms handoff and `y` confirms it; `x` similarly arms stop, `y` confirms, and Esc cancels. The ID, session, transcript and worktree remain the same; managed, nested, resumed and internal generation tasks are excluded. A full background pool refuses the transfer rather than exceeding its capacity.
 - **Custom agent types** — define agents in `.pi/agents/<name>.md` or `.agents/agents/<name>.md` (project) or globally, with YAML frontmatter: custom system prompts, model selection, thinking levels, tool restrictions
 - **Nested subagents** — opt-in, default-off delegation: a custom agent that sets `allowed_subagents` gets its own ownership-scoped `Agent`, `get_subagent_result`, and `steer_subagent` tools, depth-capped from the main session (default 2). It can control only its own children, they are stopped when it finishes, and their transcripts and token spend roll up to it. The allowlist is a privilege boundary — a child runs with its own tools, so pick it as carefully as `tools:` itself
 - **Mid-run chat** — inject messages into running or queued agents to redirect their work without restarting. From the main prompt, use `@handle message` (with `@` autocomplete); configure this under `/agents → Settings → Agent mentions`.
@@ -52,7 +53,7 @@ pi -e ./packages/pi-subagents
 
 Derived from [tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents); the upstream MIT license is preserved. The FleetView editor-focus fix from [commit `7da6bef828d7582ee33386ece9379c170e7742c4`](https://github.com/tintinweb/pi-subagents/commit/7da6bef828d7582ee33386ece9379c170e7742c4) (2026-10-09, #374; reported by @BarrMan) is selectively ported: callable `getText`/`setText` identifies non-inheriting custom editors without taking dialog or selector keys. No clone-parent-history behavior is imported; raw `inherit_context: true` remains refused. This fork also excludes `pi-background` from child resource loading until asynchronous child continuation has manager-owned lifecycle accounting.
 
-The container-first FleetView and bounded drill-down patterns are independently adapted from tintinweb/pi-subagents at [`221df02323c6b6350ea8474579e0ee0f6cc84cea`](https://github.com/tintinweb/pi-subagents/tree/221df02323c6b6350ea8474579e0ee0f6cc84cea/src/ui) and [`fd8d81618d80ae83a3faf40cb87dae99cca33264`](https://github.com/tintinweb/pi-subagents/tree/fd8d81618d80ae83a3faf40cb87dae99cca33264/src/ui). Collision-only child-label discriminators are inspired by [nicobailon/pi-subagents `69673c7fbf3351e54a5b0786a7e9d9fff625a749`](https://github.com/nicobailon/pi-subagents/blob/69673c7fbf3351e54a5b0786a7e9d9fff625a749/src/tui/render-helpers.ts). This is **not** the upstream workflow engine or full phase inspector: there are no inferred workflow names, phases, statuses, or workflow-wide controls, no new RPC, and no workflow source imports.
+The container-first FleetView and bounded drill-down patterns are independently adapted from tintinweb/pi-subagents at [`221df02323c6b6350ea8474579e0ee0f6cc84cea`](https://github.com/tintinweb/pi-subagents/tree/221df02323c6b6350ea8474579e0ee0f6cc84cea/src/ui) and [`fd8d81618d80ae83a3faf40cb87dae99cca33264`](https://github.com/tintinweb/pi-subagents/tree/fd8d81618d80ae83a3faf40cb87dae99cca33264/src/ui). Collision-only child-label discriminators are inspired by [nicobailon/pi-subagents `69673c7fbf3351e54a5b0786a7e9d9fff625a749`](https://github.com/nicobailon/pi-subagents/blob/69673c7fbf3351e54a5b0786a7e9d9fff625a749/src/tui/render-helpers.ts). The workflow engine and phase inspector remain owned by `pi-workflows`, not copied into this package. A separate optional, validated UI protocol supplies authoritative run names, statuses and observed phases and opens that owner's inspector. Without that peer, groups retain the observation-only child list. No workflow source imports, inferred DAG state or second queue/model policy are introduced. The managed protocol remains v4.
 
 The opt-in parent clarification broker is locally implemented. It uses the existing main session, not an upstream LLM arbitrator, cloned parent history, private UI automation, or an additional Agent per question. Permission gates remain human-owned.
 
@@ -183,9 +184,11 @@ The mark is a geometric shape rather than an emoji on purpose: an emoji invites
 font fallback, and a fallback glyph is usually double-width, which would push
 the rest of the row out of alignment on some terminals and not others.
 
-The list is ordered earliest-launched first, and only shows agents you can actually open (pending/queued agents with no session yet appear once they start). At an **empty prompt**, press down or left to move focus from the prompt into the list. Up and down move the selection, Enter opens the selected agent's live conversation overlay (it auto-updates as the agent works), and Esc (or up above `main`) returns to the prompt. Selecting `main` returns to the normal view. The conversation overlay uses a complete `╭─╮` / `│` / `╰─╯` border. Press Enter to chat with a running agent — type a message and Enter to send it (Esc or an empty submit returns). For a queued agent that has no session yet, type `@handle message` in the main prompt; the message is delivered when it starts. Press `x` twice to stop a running agent. A viewer stays open when its agent finishes so you can read the final output, and finished agents linger in the list for a few seconds before dropping out. Typing anything at a non-empty prompt behaves normally — the list only captures navigation keys when the prompt is empty. Disable it entirely via `/agents → Settings → Fleet view`.
+The list is ordered earliest-launched first, and only shows agents you can actually open (pending/queued agents with no session yet appear once they start). At an **empty prompt**, press down or left to move focus from the prompt into the list. Up and down move the selection, Enter opens the selected agent's live conversation overlay (it auto-updates as the agent works), and Esc (or up above `main`) returns to the prompt. Selecting `main` returns to the normal view. Regular-mode observers use a complete `╭─╮` / `│` / `╰─╯` border; public fullscreen hosts use a terminal-sized observer. Press Enter to chat with a running agent — type a message and Enter to send it (Esc or an empty submit returns). For a queued agent that has no session yet, type `@handle message` in the main prompt; the message is delivered when it starts. Press `x` and follow the displayed explicit confirmation to stop a running agent; holding one key must not confirm it. A viewer stays open when its agent finishes so you can read the final output, and finished agents linger in the list for a few seconds before dropping out. Typing anything at a non-empty prompt behaves normally — the list only captures navigation keys when the prompt is empty. Disable it entirely via `/agents → Settings → Fleet view`.
 
-Workflow-owned records appear in container rows **above ordinary agents**: `Workflow <runId> · N retained children`. These groups use only validated, already-available `owner.extension` and `owner.runId`; their counts describe records the manager still retains, not total workflow calls or authoritative run status. Opening one gives a terminal-height-bounded child list with stable-ID selection, Up/Down, PageUp/PageDown, Home/End and Enter to view a conversation; Esc returns from the conversation to the child list, then to FleetView. Sessionless queued children remain visible with an explicit unavailable-session message. Completed owned children remain inspectable while retained, independent of the ordinary four-second linger. Duplicate descriptions receive an ID discriminator only when needed. Detached records are excluded, and controls opened on an old thread attempt cannot steer/stop a replacement attempt.
+Workflow containers appear **above ordinary agents**. With the optional `pi-workflows` UI peer, a row shows the actual workflow name/status, observed current phase, call counts and available token totals; even a running workflow with no child yet can appear. Enter opens the workflow owner's inspector, where pause/resume/stop stay with that owner. Paused and interrupted childless runs remain available for explicit resume.
+
+Without the peer, the fallback is `Workflow <runId> · N retained children`. That count describes retained manager records, not total workflow calls or authoritative status. Opening it gives a terminal-height-bounded child list with stable-ID selection, Up/Down, PageUp/PageDown, Home/End and Enter to view a conversation; Esc returns from the conversation to the child list, then to FleetView. Sessionless queued children remain visible with an explicit unavailable-session message. Completed owned children remain inspectable while retained, independent of the ordinary four-second linger. Duplicate descriptions receive an ID discriminator only when needed. Detached records are excluded, and controls opened on an old thread attempt cannot steer/stop a replacement attempt.
 
 Steering rejection (including a child finishing while the composer is open) preserves the draft and shows an error; Esc explicitly discards it. Completed conversation headers fall back to the retained lifetime usage and compaction count when live activity has been removed.
 
@@ -438,7 +441,7 @@ Create new agent
 Settings
 ```
 
-- **Agent runs** — select any retained run with a session to open its conversation viewer. Queued runs without a session remain listed but are not openable until they start; selecting one offers a stop confirmation, and `@handle message` queues a chat message. The summary reports running, queued, completed, wrapped up, stopped, aborted, and failed buckets separately. While a run is still active, press Enter to open the chat composer, then Enter again to send a message that redirects the agent (same mechanism as the `steer_subagent` tool; Esc or an empty submit returns), or press `x` (then `x` again to confirm) to stop/abort it — including **background** agents, which a global Esc can't unambiguously target (Esc still stops a blocking foreground `Agent` call). A stopped agent reports its partial output flagged as incomplete, not as a completion.
+- **Agent runs** — select any retained run with a session to open its conversation viewer. Queued runs without a session remain listed but are not openable until they start; selecting one offers a stop confirmation, and `@handle message` queues a chat message. The summary reports running, queued, completed, wrapped up, stopped, aborted, and failed buckets separately. While a run is still active, press Enter to open the chat composer, then Enter again to send a message that redirects the agent (same mechanism as the `steer_subagent` tool; Esc or an empty submit returns), or press `x` and follow the displayed explicit confirmation to stop/abort it — including **background** agents, which a global Esc can't unambiguously target (Esc still stops a blocking foreground `Agent` call). A stopped agent reports its partial output flagged as incomplete, not as a completion.
 - **Agent types** — unified list with textual source labels (`project`, `global`, and `disabled`). Each row shows the agent's model, and the highlighted agent's full description appears below the list. The model column flags `(unavailable, fallback: inherit)` when a configured model can't be resolved (it would silently inherit the parent model), and shows `(resolved: provider/id)` when it resolves to a different provider or version than configured. Select an agent to manage it:
   - **Default agents** (no override): Eject (export as `.md`), Disable
   - **Default agents** (ejected/overridden): Edit, Disable, Reset to default, Delete
@@ -910,6 +913,14 @@ const unsub = pi.events.on(`subagents:rpc:stop:reply:${requestId}`, (reply) => {
 pi.events.emit("subagents:rpc:stop", { requestId, agentId: "agent-id-here" });
 ```
 
+### Optional workflow UI bridge
+
+`@signalridge/pi-subagents-protocol` declares a separate version-1 UI contract: `pi-workflows:ui:query`, `pi-workflows:ui:changed`, `pi-workflows:ui:open`, and `subagents:ui:open-owned`. These are not new required managed capabilities and do not grow the strict v4 ping envelope. Query/change payloads are bounded display projections, not DAG or journal storage. An open request is an explicit user UI action, not an agent dispatch or approval grant.
+
+The conversation opener requires the exact `agentId` plus `{ extension, runId, nodeId, attemptId }`, an active root TUI and a retained session. Admission is acknowledged before the dialog closes; unavailable, foreign, sessionless and stale attempts are refused. Reload, tree replacement and shutdown retire pending UI work. Other peers can remain absent without disabling managed execution.
+
+Owned lifecycle events may additionally carry `managedTokens`, the current attempt's usage. Existing `tokens` remains lifetime usage; Fleet never resets cumulative counters on thread reuse. Managed terminal `tokenCount` describes that attempt, including cache writes, so sequential thread calls do not bill earlier turns twice. Older stored terminal facts are not rewritten.
+
 Reply channels are scoped per `requestId`, so concurrent requests don't interfere.
 Workflow callers should pass a foreground signal only to their own wait. Managed child cancellation is explicit through the owner-scoped lifecycle RPC; aborting an RPC wait does not abort the child.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-subagents",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Signalridge's managed subagent runtime with workflow-owned orchestration RPC.",
   "author": "tintinweb and signalridge contributors",
   "license": "MIT",
@@ -32,7 +32,7 @@
   },
   "dependencies": {
     "croner": "^10.0.1",
-    "@signalridge/pi-subagents-protocol": "^1.5.1",
+    "@signalridge/pi-subagents-protocol": "^1.6.0",
     "@signalridge/pi-ui": "^1.4.0",
     "minimatch": "^10.2.6",
     "nanoid": "^5.1.16"