@signalridge/pi-subagents 1.9.1 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 1.10.0
+### Minor Changes
+
+- f05185e: A workflow now runs at the width of the host's subagent pool rather than a
+  number it picked blind, and stops charging queue time against the agent waiting
+  in it.
+  
+  Two facts were missing on the pi-workflows side, and they compounded. It had no
+  way to learn `maxConcurrent`, so its own width was a constant guess. And a
+  dispatched agent was treated as a running one, though a managed spawn takes a
+  background slot like any other and waits when the pool is full, so a batch
+  dispatched behind a busy pool could fail as timeouts with none of it having run.
+  
+  - The ping reply can now carry the peer's live `maxConcurrent`, and pi-workflows
+    makes it both the default width and the ceiling: an unnamed `concurrency` takes
+    the pool size, and a named one is clamped to it, with the clamp recorded in the
+    run log so a caller who asked for a number learns why it got another. It is
+    read at each start and resume rather than frozen onto the run, because the pool
+    is a setting the user can change in between. One setting therefore governs the
+    whole fleet, which is what the ownership boundary already said and what the
+    code can now honour.
+  - **This narrows the common case, and that is the point.** The pool defaults to
+    4 background slots, so a default pair now runs a fan-out four at a time where
+    it used to dispatch `hardwareConcurrency - 2`. Nothing runs slower for it —
+    dispatching twelve into four slots only ever queued eight, ahead of the host's
+    own spawns — but the width a run reports is now the width it actually has, and
+    `maxConcurrent` is the single place to raise it for workflows and every other
+    background agent at once. A host that had already raised it gets the wide
+    fan-outs its setting always implied.
+  - The field is **requested by name** (`include: ["maxConcurrent"]`) rather than
+    volunteered. A ping envelope is parsed with `rejectUnknownKeys`, so a peer that
+    simply added a field would make every already-published caller reject the
+    handshake and lose workflows entirely. Asking keeps both directions working: an
+    older peer answers without it and the caller falls back to 16, and a caller that
+    never asks gets the v4 envelope unchanged. No version bump, no capability, no
+    lockstep release. Both READMEs document the mechanism, since `include` is now
+    part of the public cross-extension contract.
+  - `agentTimeoutMs` now counts from the moment the host reports the agent left its
+    queue. The clock is still armed at dispatch and restarted on that report, not
+    armed only by it, so a report that never arrives degrades to the old behaviour
+    rather than to an agent that can hang forever. A report that arrives *after* the
+    agent settled is ignored, so a late or duplicate one cannot leave a live timer
+    behind to abort a finished agent.
+  
+  The engine already subscribed to `subagents:started` and already filtered it by
+  workflow owner, so the start signal is the event it was discarding.
+  
+  `getMaxConcurrent` is required on the RPC bridge rather than optional. The other
+  bridge members are capabilities, advertised in the ping and rejected outright
+  when missing, so forgetting one fails loudly; a missing pool size has no
+  capability bit and no failure — the caller would silently fall back to its own
+  guess and run at the wrong width. Required is what makes that omission a compile
+  error instead of a quiet wrong answer.
+
+### Patch Changes
+
+- Updated dependencies [f05185e]
+  - @signalridge/pi-subagents-protocol@1.5.0
+
 ## 1.9.1
 ### Patch Changes
 

package/README.md

@@ -767,6 +767,16 @@ const unsub = pi.events.on(`subagents:rpc:ping:reply:${requestId}`, (reply) => {
 pi.events.emit("subagents:rpc:ping", { requestId });
 ```
 
+The reply always carries `version`, `capabilities`, and `routingPolicy`. Anything beyond those is **requested by name** through an optional `include` array, and is sent only to a caller that asked:
+
+```typescript
+pi.events.emit("subagents:rpc:ping", { requestId, include: ["maxConcurrent"] });
+```
+
+`include` accepts up to 8 names; unknown ones are ignored. Today the only one is `maxConcurrent`, the live background-agent pool size — the number of background slots a spawn competes for, which `/subagents` can change mid-session, so read it per operation rather than caching it at session start.
+
+Opt-in rather than volunteered, because the envelope is validated with `rejectUnknownKeys`: a field added unconditionally would make every already-published caller reject the handshake and lose the peer entirely. Asking keeps both directions working without a version bump — an older peer answers without the field, and a caller that never asks gets the same envelope it has always parsed. Treat an absent field as "this peer does not publish it" and fall back to your own default; it is not an error.
+
 ### Managed spawn (protocol v4)
 
 Workflow-owned orchestration uses the `subagents:rpc:spawn-managed` channel. Its request may include the core identity fields plus an optional Agent `tier`, `toolset`, `excludeTools`, `thread`, and `isolation: "worktree"`. There is no per-call `model` or `thinking` — the wire validator rejects them:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-subagents",
-  "version": "1.9.1",
+  "version": "1.10.0",
   "description": "Signalridge's managed subagent runtime with workflow-owned orchestration RPC.",
   "author": "tintinweb and signalridge contributors",
   "license": "MIT",
@@ -32,7 +32,7 @@
   "dependencies": {
     "@sinclair/typebox": "^0.34.50",
     "croner": "^10.0.1",
-    "@signalridge/pi-subagents-protocol": "^1.4.0",
+    "@signalridge/pi-subagents-protocol": "^1.5.0",
     "@signalridge/pi-ui": "^1.3.0",
     "nanoid": "^5.0.0"
   },

package/src/cross-extension-rpc.ts

@@ -12,6 +12,7 @@ import {
   PROTOCOL_CAPABILITIES,
   PROTOCOL_VERSION,
   parseManagedSpawnRequest,
+  parsePingIncludes,
 } from "@signalridge/pi-subagents-protocol";
 
 export { CHILD_CONTEXT_CAPABILITY, PROTOCOL_CAPABILITIES, PROTOCOL_VERSION };
@@ -44,6 +45,17 @@ export interface SpawnCapable {
   abortOwned?(id: string, owner: AgentOwner): boolean;
   quiesceOwned?(runId: string, agentIds: string[], timeoutMs: number, owners?: AgentOwner[]): Promise<{ settled: boolean; pending: string[] }>;
   reconcileManaged?(spawnKey: string, owner: AgentOwner): ManagedSpawnResult | undefined;
+  /**
+   * Live background-agent pool size, published to a peer that asks for it.
+   *
+   * Required, unlike the capability members above. Those are advertised in the
+   * ping's `capabilities` and a peer missing one is rejected outright, so a
+   * bridge that forgets to forward one fails loudly. A missing pool size has no
+   * capability bit and no failure: the caller would silently fall back to its
+   * own guess and run at the wrong width. Making it required is what stops a
+   * bridge from omitting it by accident.
+   */
+  getMaxConcurrent(): number;
 }
 
 export interface RpcDeps {
@@ -170,11 +182,22 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
   const { events, pi, getCtx, manager } = deps;
   const getRoutingPolicy = deps.getRoutingPolicy ?? getRoutingPolicySnapshot;
 
-  const unsubPing = handleRpc(events, "subagents:rpc:ping", () => ({
-    version: PROTOCOL_VERSION,
-    capabilities: PROTOCOL_CAPABILITIES,
-    routingPolicy: getRoutingPolicy(),
-  }));
+  const unsubPing = handleRpc(events, "subagents:rpc:ping", (params) => {
+    // Additive fields are opt-in by name. The reply envelope is parsed with
+    // rejectUnknownKeys on the caller's side, so volunteering a field would
+    // make every already-published peer reject the handshake; a peer that asks
+    // for one is by construction a peer that knows how to parse it.
+    const include = parsePingIncludes(params.include);
+    const maxConcurrent = include.has("maxConcurrent") ? manager.getMaxConcurrent() : undefined;
+    return {
+      version: PROTOCOL_VERSION,
+      capabilities: PROTOCOL_CAPABILITIES,
+      routingPolicy: getRoutingPolicy(),
+      ...(typeof maxConcurrent === "number" && Number.isInteger(maxConcurrent) && maxConcurrent >= 1
+        ? { maxConcurrent }
+        : {}),
+    };
+  });
 
   const unsubSpawn = handleRpc(events, "subagents:rpc:spawn", (params) => {
     const ctx = getCtx();

package/src/index.ts

@@ -1234,6 +1234,10 @@ function activateRootRuntime(
           quiesceOwned: (runId, agentIds, timeoutMs, owners) =>
             manager.quiesceOwned(runId, agentIds, timeoutMs, owners),
           reconcileManaged: (spawnKey, owner) => manager.reconcileManaged(spawnKey, owner),
+          // The live pool size, not a snapshot: `/subagents` can change it
+          // mid-session, and a peer that sizes its fan-out from this must see
+          // the value that is actually throttling it now.
+          getMaxConcurrent: () => manager.getMaxConcurrent(),
         },
       });
       // Emit only after RPC handlers are armed, and only for a bound session.