@herbertgao/pi-subagents 0.22.0-local.2 → 0.22.1-local.1

package/docs/rpc.md

@@ -1,6 +1,6 @@
 # Driving subagents from another extension
 
-Another pi extension can spawn a subagent, listen for subagent completion, read the result and stop the run — all over the `pi.events` bus, without importing this package directly. Four request/reply channels (`subagents:rpc:ping`, `subagents:rpc:spawn`, `subagents:rpc:stop`, `subagents:rpc:consume`), eleven lifecycle events, and one in-process registry at `Symbol.for("pi-subagents:manager")`.
+Another pi extension can spawn a subagent, listen for subagent completion, read the result, steer and stop the run — all over the `pi.events` bus, without importing this package directly. Five request/reply channels (`subagents:rpc:ping`, `subagents:rpc:spawn`, `subagents:rpc:stop`, `subagents:rpc:consume`, `subagents:rpc:steer`), the lifecycle events in README's [event table](../README.md#events), one per-message usage event (`subagents:usage`), one terminal `subagents:disposed`, and one in-process registry at `Symbol.for("pi-subagents:manager")`.
 
 The thing worth understanding up front is that **the bus is in-process.** Every "RPC" call here is a synchronous `pi.events.emit` into the same event loop, and every reply comes back the same way. That single fact explains most of what follows: why `signal` and the `on*` callbacks work on a spawn payload at all, why a `consume` fired inside a `subagents:completed` handler lands _before_ the notification decision has been made, and why none of this survives a real process boundary.
 
@@ -88,6 +88,8 @@ Every failure reaches the caller as `{ success: false, error }`, where `error` i
 | `Agent is owned by another agent or workflow`                                                                                                                           | stop handler                                                                                                                                                              |
 | `Agent is not running`                                                                                                                                                  | stop handler. The record exists, so it has already settled                                                                                                                |
 | `Agent not found or still running`                                                                                                                                      | consume handler                                                                                                                                                           |
+| `Steer message must be a non-empty string`                                                                                                                              | steer handler — `message` missing, not a string, or whitespace                                                                                                            |
+| `Agent not found` / `Agent is owned by another agent or workflow` / `Agent is not running`                                                                              | steer handler — same lookup, ownership guard and settled check as stop                                                                                                    |
 
 Three things the table cannot show:
 
@@ -97,14 +99,16 @@ Three things the table cannot show:
 
 ## Ownership
 
-`isTopLevelAgent(record)` is `parentAgentId === undefined && workflowId === undefined` (`src/agent-manager.ts`). `subagents:rpc:stop` enforces it in its handler (`src/cross-extension-rpc.ts`): a nested child or a workflow's agent is owned by something that is _waiting on it_, and aborting it out from under that owner turns another extension's stop into a failed step. It is defence in depth rather than a live hole — no RPC hands out agent ids, so a caller has no ordinary way to name one it does not own.
+`isTopLevelAgent(record)` is `parentAgentId === undefined && workflowId === undefined` (`src/agent-manager.ts`). `subagents:rpc:stop` and `subagents:rpc:steer` enforce it through one shared check (`assertOwned` in `src/cross-extension-rpc.ts`): a nested child or a workflow's agent is owned by something that is _waiting on it_, and aborting or redirecting it out from under that owner turns another extension's request into a failed step. It is defence in depth rather than a live hole — no RPC hands out agent ids, so a caller has no ordinary way to name one it does not own.
 
 Two asymmetries to know about, stated as they are:
 
 - **Stop takes an id only**: its `getRecord` is the manager's plain lookup. Consume takes an id _or_ an `@handle`: its `consumeResult` (both wired in the `session_start` handler, `src/index.ts`) goes through `resolveAgentRef`.
 - **Consume checks `parentAgentId` but not `workflowId`** (`consumeResult`, `src/index.ts`). A workflow-owned agent's result can be marked consumed over the bus even though the same agent cannot be stopped.
 
-The same predicate silently scopes the events. **Every lifecycle event is top-level only** — `subagents:started`, `:completed`, `:failed` and `:compacted` all return early for nested and workflow-owned agents (the `isTopLevelAgent` checks in the `AgentManager` callbacks, `src/index.ts`). A workflow's children are invisible on the bus: you will see the workflow's own agents come and go without a single event.
+The same predicate silently scopes the events. **Every lifecycle event is top-level only** — `subagents:started`, `:completed`, `:failed`, `:steered` and `:compacted` all return early for nested and workflow-owned agents (the `isTopLevelAgent` checks in the `AgentManager` callbacks, `src/index.ts`). `subagents:usage` is the one event that is not scoped: it fires for every agent's messages, nested and workflow-owned included, so a ledger sees a workflow's children spend even though it never sees them start or finish.
+
+**`subagents:disposed` is the last event of a session.** It is emitted at the end of this extension's `session_shutdown`, after every agent is stopped and every child session has shut down, so no `subagents:usage` can follow it. A listener gets only its synchronous prefix on quit: `pi.events.emit` does not await listeners, and pi calls `process.exit` once the shutdown handlers return. Flush with `writeFileSync`, not `fs.promises`. Fields, and the other events, are in README's [event table](../README.md#events).
 
 ## The notification race
 
@@ -128,6 +132,12 @@ Consumption is not terminal. An `@handle` steer un-consumes the record (the ment
 
 One related thing that lives nowhere else: on every top-level settle, pi-subagents writes a session entry — not an event — via `pi.appendEntry("subagents:record", …)` (the manager's completion callback, `src/index.ts`), carrying `id`, `type`, `description`, `status`, `result`, `error`, `startedAt` and `completedAt`. It exists for cross-extension history reconstruction. It is append-only history, not something to react to.
 
+## Steering a running agent
+
+`subagents:rpc:steer` `{ requestId, agentId, message }` delivers `message` into a running or queued agent's conversation, the bus-side half of the `steer_subagent` tool. It exists for the caller that spawned an agent over the bus and then learns something that agent needs mid-run — a second CI failure on the head it is already fixing, a review that landed while it works — and would otherwise have to choose between spawning a duplicate agent for the same work and dropping the fact.
+
+It takes an id only, enforces the same top-level ownership guard as stop, and answers `Agent is not running` for a record that has settled. A message queued before the agent's session exists is flushed when the session is created, exactly as the tool's steer is. A successful steer emits `subagents:steered` `{ id, message }`, as every steer path does. Like `consume`, it is outside the `ping` version handshake: an older build has no handler and the request times out on your side, so give it a timeout and treat expiry as "not available here".
+
 ## The manager registry
 
 `globalThis[Symbol.for("pi-subagents:manager")]` (`MANAGER_KEY` and `registryEntry`, `src/index.ts`) is a second integration surface — the standard Node cross-package singleton pattern, no bus involved:
@@ -147,9 +157,9 @@ Prefer the bus. The registry has no reply envelope, no version, and no availabil
 
 `subagents:rpc:ping` replies `{ version: PROTOCOL_VERSION }`, currently `2` (`src/cross-extension-rpc.ts`). The constant was introduced already equal to `2` in 0.5.0; "v1" is a retroactive name for the pre-envelope contract, where spawn replied with a bare `{ id }` or `{ error }`, stop replied `{ success: boolean }` with no message, and each handler caught its own errors.
 
-Everything added since shipped **without a bump**, because all of it is additive: stop's ownership refusal, string-`model` resolution ([#59](https://github.com/tintinweb/pi-subagents/pull/59)/[#60](https://github.com/tintinweb/pi-subagents/issues/60)), `scopeModels` enforcement ([#240](https://github.com/tintinweb/pi-subagents/issues/240)), and the whole `consume` channel.
+Everything added since shipped **without a bump**, because all of it is additive: stop's ownership refusal, string-`model` resolution ([#59](https://github.com/tintinweb/pi-subagents/pull/59)/[#60](https://github.com/tintinweb/pi-subagents/issues/60)), `scopeModels` enforcement ([#240](https://github.com/tintinweb/pi-subagents/issues/240)), and the whole `consume` and `steer` channels.
 
-> A `ping` that answers `2` does not tell you whether `consume` exists, whether model scope is enforced, or whether stop checks ownership.
+> A `ping` that answers `2` does not tell you whether `consume` or `steer` exists, whether model scope is enforced, or whether stop checks ownership.
 
 So: send `consume` unconditionally and ignore the outcome — an older build has no handler and simply keeps notifying, which is exactly why it was left outside the handshake. And treat every error envelope as authoritative rather than trying to predict which checks are in force.
 
@@ -167,7 +177,7 @@ This document has no test of its own, so it is worth knowing which claims are ac
 
 | Test                                  | Level                  | Pins                                                                                                                                                                                                                                 |
 | ------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `test/cross-extension-rpc.test.ts`    | Mocked `SpawnCapable`  | Envelope shape, per-channel error strings, model resolution and scope enforcement                                                                                                                                                    |
+| `test/cross-extension-rpc.test.ts`    | Mocked `SpawnCapable`  | Envelope shape, per-channel error strings (including steer's), model resolution and scope enforcement                                                                                                                                |
 | `test/rpc-lifecycle-gating.test.ts`   | Real extension factory | Nothing wired at factory time, everything once at `session_start`, and live widget activity for RPC spawns ([#142](https://github.com/tintinweb/pi-subagents/issues/142)/[#181](https://github.com/tintinweb/pi-subagents/pull/181)) |
 | `test/rpc-result-consumption.test.ts` | Real delivery path     | The notification firing, and not firing, around `consume`                                                                                                                                                                            |
 
@@ -179,4 +189,4 @@ Not pinned anywhere, so treat them as descriptions rather than contracts: the `S
 
 Read it for the shape of the whole loop: waiting on `subagents:ready`, keeping an id-keyed map of outstanding spawns, resolving each from the `subagents:completed` / `subagents:failed` handler, and consuming the result in the same synchronous handler that reports it.
 
-If what you want is many coordinated agents rather than one, hand a script to [`SubagentWorkflow`](workflows.md) instead of fanning out over `subagents:rpc:spawn` — and note that a workflow's agents are not yours: they emit no lifecycle events, and `subagents:rpc:stop` refuses them.
+If what you want is many coordinated agents rather than one, hand a script to [`SubagentWorkflow`](workflows.md) instead of fanning out over `subagents:rpc:spawn` — and note that a workflow's agents are not yours: they emit no lifecycle events — only `subagents:usage` — and `subagents:rpc:stop` refuses them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herbertgao/pi-subagents",
-  "version": "0.22.0-local.2",
+  "version": "0.22.1-local.1",
   "description": "Claude Code-style autonomous subagents and workflow orchestration for Pi, with HerbertGao-maintained UI extensions.",
   "keywords": [
     "agent",
@@ -69,10 +69,10 @@
   },
   "x-upstream": {
     "package": "@tintinweb/pi-subagents",
-    "version": "0.22.0",
-    "reviewedVersion": "0.22.0",
+    "version": "0.22.1",
+    "reviewedVersion": "0.22.1",
     "repository": "https://github.com/tintinweb/pi-subagents",
-    "commit": "85a704cb8f35c96c0cabfa665b572bab296942e5",
+    "commit": "fc089c4b7ab0f1185453b2e53027997c1f637e38",
     "trackVersion": true
   }
 }

package/src/agent-manager.ts

@@ -49,6 +49,12 @@ import {
 
 export type OnAgentComplete = (record: AgentRecord) => void
 export type OnAgentStart = (record: AgentRecord) => void
+/**
+ * Fired by `steer()` once a message is delivered or queued. Every steer path
+ * goes through it except the steer tools (`steer_subagent` in index.ts, and its
+ * nested twin in nested-tools.ts), which await the session directly.
+ */
+export type OnAgentSteered = (record: AgentRecord, message: string) => void
 export type OnAgentCompact = (record: AgentRecord, info: CompactionInfo) => void
 /**
  * Fired once per assistant `message_end`, for EVERY agent this manager owns —
@@ -351,6 +357,14 @@ interface ResumeOptions {
    * record — the historical behavior.
    */
   isBackground?: boolean
+  /**
+   * Explicit turn limit for the resumed run: this, else the limit the agent
+   * was spawned with, else its type's own `max_turns`, else the default —
+   * counted afresh from the resume prompt (#368).
+   */
+  maxTurns?: number
+  /** Called at the end of each resumed turn with the count since the resume. */
+  onTurnEnd?: (turnCount: number) => void
   /** Called on tool start/end with activity info (for streaming progress to UI). */
   onToolActivity?: (activity: ToolActivity) => void
   /** Called once per assistant message_end with that message's usage delta. */
@@ -420,6 +434,7 @@ export class AgentManager {
   private onStart?: OnAgentStart
   private onCompact?: OnAgentCompact
   private onUsage?: OnAgentUsage
+  private onSteered?: OnAgentSteered
   private maxConcurrent: number
   private maxConcurrentForeground = DEFAULT_MAX_CONCURRENT_FOREGROUND
   /** Base repos worktrees were created from — so dispose() can prune them all,
@@ -476,11 +491,13 @@ export class AgentManager {
     onStart?: OnAgentStart,
     onCompact?: OnAgentCompact,
     onUsage?: OnAgentUsage,
+    onSteered?: OnAgentSteered,
   ) {
     this.onComplete = onComplete
     this.onStart = onStart
     this.onCompact = onCompact
     this.onUsage = onUsage
+    this.onSteered = onSteered
     this.maxConcurrent = maxConcurrent
     // Cleanup consumed completed agents after 10 minutes
     this.cleanupInterval = setInterval(() => this.cleanup(), 60_000)
@@ -972,28 +989,18 @@ export class AgentManager {
           structuredJson,
           structuredRetried,
         }) => {
-          // Don't overwrite status if externally stopped via abort()
-          if (record.status !== "stopped") {
-            // Precedence: a hard abort keeps "aborted"; then a failed final turn
-            // (provider error that pi resolved instead of rejecting, #144) is an
-            // honest "error" — not a completion with an empty or stale result.
-            if (aborted) {
-              record.status = "aborted"
-            } else if (failure) {
-              record.status = "error"
-              record.error = failure
-            } else {
-              record.status = steered ? "steered" : "completed"
-            }
-          }
-          record.result = responseText
+          this.settleOutcome(record, {
+            text: responseText,
+            failure,
+            aborted,
+            steered,
+          })
           // Kept beside `result`, never inside it: `result` is prose meant for a
           // reader — it is previewed, transcribed, and appended to below — while
           // this is a machine-readable payload one caller asked for by schema.
           record.structuredJson = structuredJson
           record.structuredRetried = structuredRetried
           record.session = session
-          record.completedAt ??= Date.now()
 
           detach()
 
@@ -1383,36 +1390,46 @@ export class AgentManager {
     record.completedAt = undefined
     record.result = undefined
     record.error = undefined
+    // Fresh controller, as on the detached path: `abort()` fires whatever
+    // `record.abortController` holds, and the spawn's has long settled — so a
+    // stop from `/agents` or the caller's Esc would mark the record stopped
+    // while the resumed prompt ran on to completion.
+    const abortController = new AbortController()
+    record.abortController = abortController
+    this.armParentAbort(record, signal)
+    // `addEventListener` never fires on a signal that is already aborted, and
+    // the runner skips the prompt only when ITS signal is — stop now, so that
+    // holds for a resume issued on a call that was cancelled first.
+    if (signal?.aborted) this.abort(id)
 
     try {
-      const { text, failure } = await resumeAgent(record.session, prompt, {
-        onToolActivity: (activity) => {
-          if (activity.type === "end") record.toolUses++
-          options?.onToolActivity?.(activity)
-        },
-        onAssistantUsage: (usage) => {
-          addUsage(record.lifetimeUsage, usage)
-          this.onUsage?.(record, usage)
-          options?.onAssistantUsage?.(usage)
-        },
-        onCompaction: (info) => {
-          record.compactionCount++
-          this.onCompact?.(record, info)
-          options?.onCompaction?.(info)
-        },
-        signal,
-      })
-      // Same contract as the spawn path (#144): a failed final turn is an
-      // error, not a completion — but the resumed text stays available.
-      record.status = failure ? "error" : "completed"
-      if (failure) record.error = failure
-      record.result = text
-      record.completedAt = Date.now()
+      this.settleOutcome(
+        record,
+        await resumeAgent(record.session, prompt, {
+          type: record.type,
+          maxTurns: options?.maxTurns ?? record.invocation?.maxTurns,
+          onTurnEnd: options?.onTurnEnd,
+          onToolActivity: (activity) => {
+            if (activity.type === "end") record.toolUses++
+            options?.onToolActivity?.(activity)
+          },
+          onAssistantUsage: (usage) => {
+            addUsage(record.lifetimeUsage, usage)
+            this.onUsage?.(record, usage)
+            options?.onAssistantUsage?.(usage)
+          },
+          onCompaction: (info) => {
+            record.compactionCount++
+            this.onCompact?.(record, info)
+            options?.onCompaction?.(info)
+          },
+          signal: abortController.signal,
+        }),
+      )
     } catch (err) {
-      record.status = "error"
-      record.error = err instanceof Error ? err.message : String(err)
-      record.completedAt = Date.now()
+      this.failResume(record, err)
     }
+    this.detachParentAbort(record)
 
     // Same contract as the spawn settle paths: children spawned during the
     // resumed turn must not outlive it — nothing else can see or reach them.
@@ -1421,6 +1438,46 @@ export class AgentManager {
     return record
   }
 
+  /**
+   * Write a run's outcome onto its record — a spawn's or a resume's, with one
+   * precedence: an external stop keeps "stopped"; a hard abort (turn limit +
+   * grace) is "aborted"; a failed final turn (a provider error pi resolved
+   * instead of rejecting, #144) is an "error", not a completion with an empty
+   * or stale result; otherwise "steered" or "completed". The run's text stays
+   * available in every case.
+   */
+  private settleOutcome(
+    record: AgentRecord,
+    {
+      text,
+      failure,
+      aborted,
+      steered,
+    }: Awaited<ReturnType<typeof resumeAgent>>,
+  ): void {
+    if (record.status !== "stopped") {
+      if (aborted) {
+        record.status = "aborted"
+      } else if (failure) {
+        record.status = "error"
+        record.error = failure
+      } else {
+        record.status = steered ? "steered" : "completed"
+      }
+    }
+    record.result = text
+    record.completedAt ??= Date.now()
+  }
+
+  /** A resume whose runner rejected: an error, unless an external stop got there first. */
+  private failResume(record: AgentRecord, err: unknown): void {
+    if (record.status !== "stopped") {
+      record.status = "error"
+      record.error = err instanceof Error ? err.message : String(err)
+    }
+    record.completedAt ??= Date.now()
+  }
+
   /**
    * Start a background resume run: detached, settling and notifying like
    * startAgent's background path. Invoked immediately, or from drainQueue when
@@ -1490,6 +1547,9 @@ export class AgentManager {
     }
 
     const promise = resumeAgent(record.session, prompt, {
+      type: record.type,
+      maxTurns: options.maxTurns ?? record.invocation?.maxTurns,
+      onTurnEnd: options.onTurnEnd,
       onToolActivity: (activity) => {
         if (activity.type === "end") record.toolUses++
         options.onToolActivity?.(activity)
@@ -1506,25 +1566,13 @@ export class AgentManager {
       },
       signal: abortController.signal,
     })
-      .then(({ text, failure }) => {
-        // Don't overwrite status if externally stopped via abort().
-        if (record.status !== "stopped") {
-          // Same contract as the spawn path (#144): a failed final turn is an
-          // error, not a completion — but the resumed text stays available.
-          record.status = failure ? "error" : "completed"
-          if (failure) record.error = failure
-        }
-        record.result = text
-        record.completedAt ??= Date.now()
+      .then((outcome) => {
+        this.settleOutcome(record, outcome)
         settle()
-        return text
+        return outcome.text
       })
       .catch((err) => {
-        if (record.status !== "stopped") {
-          record.status = "error"
-          record.error = err instanceof Error ? err.message : String(err)
-        }
-        record.completedAt ??= Date.now()
+        this.failResume(record, err)
         settle()
         return ""
       })
@@ -1538,7 +1586,10 @@ export class AgentManager {
    * current tool execution and appears as a user message. If the session isn't
    * ready yet, the message is queued on `pendingSteers` and flushed when the
    * session is created. Returns false if the agent can't accept steering
-   * (unknown id, or no longer running/queued).
+   * (unknown id, or no longer running/queued). Fires `onSteered` on either
+   * accepted path, so the UI viewers, an `@handle` and the RPC all report
+   * the steer the same way without each emitting by hand. The steer tools
+   * bypass this method because they await delivery.
    */
   steer(id: string, message: string): boolean {
     const record = this.agents.get(id)
@@ -1550,6 +1601,7 @@ export class AgentManager {
       if (!record.pendingSteers) record.pendingSteers = []
       record.pendingSteers.push(message)
     }
+    this.onSteered?.(record, message)
     return true
   }