@signalridge/pi-subagents 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,86 @@
 # 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
+
+- fabe89a: Document how a workflow now reaches this catalogue.
+  
+  The "One catalogue, including for workflows" section said a workflow script names
+  a key from `agentTiers` directly, with "no second workflow-tier vocabulary and no
+  mapping layer" and `agent({ tier: "low" })` examples. pi-workflows scripts now
+  name a *strength* and a table on that side chooses the tier, so every claim in
+  that section was inverted and its example is rejected before dispatch.
+  
+  The claim it was protecting is still true and is now stated where it belongs:
+  there is no second tier catalogue and no second resolver, a `strengths` value is
+  a key in this catalogue and never carries its own `model`/`thinking`, and a
+  request arriving here is indistinguishable from a spawn that named the key
+  itself. Also notes that the shipped `low`/`medium`/`high` profiles are what
+  pi-workflows' default table maps onto, so renaming them leaves workflows on the
+  ordinary untiered path rather than breaking them.
+  
+  Drops a stale pointer to `workflow.tiers`, a settings key this package no longer
+  reads.
+
 ## 1.9.0
 ### Minor Changes
 

package/README.md

@@ -443,16 +443,39 @@ defaults to the key; it is what the host reads when choosing between Agent tiers
 
 ### One catalogue, including for workflows
 
-A managed `pi-workflows` call names a key from this same `agentTiers` catalogue.
-There is no second workflow-tier vocabulary and no mapping layer: a workflow that
-wants cheap work asks for the tier you defined for cheap work.
+A managed `pi-workflows` call arrives naming a key from this same `agentTiers`
+catalogue. There is no second tier catalogue and no second resolver: this package
+still owns every model, every thinking level, and the only `resolveAgentTier()`.
+
+What a workflow *script* writes is not that key. A script names a **strength** —
+`low`, `medium`, `high`, pi-workflows' own word for how much effort a step
+deserves — and a `strengths` table on that side chooses which of your tiers it
+runs on:
 
 ```js
 // in a workflow script
-await agent("summarize this diff", { tier: "low" })
-await agent("design the migration", { tier: "high" })
+await agent("summarize this diff", { strength: "low" })
+await agent("design the migration", { strength: "high" })
+```
+
+```jsonc
+// pi-workflows' own settings, edited with `/workflows strength`
+{ "strengths": { "low": "cheap-search", "high": "deep" } }
 ```
 
+The indirection exists so that re-pricing workflow work does not re-price
+everything else. Workflow fan-outs ask for cheap work by the dozen, and so does
+the `Explore` agent and every spawn that names no tier of its own; if the
+workflow side reached your catalogue directly, making a 26-agent fan-out
+affordable would mean editing the tier all of them share. Pointing a strength
+elsewhere leaves your tiers alone.
+
+Nothing about that reaches this side. By the time a request arrives it carries
+one tier key, and this package cannot tell a mapped call apart from a spawn that
+named the key itself. Nor is it a second *policy*: a `strengths` value is a key
+in this catalogue and never carries a `model` or `thinking` of its own — that is
+the line between it and the retired `workflow.tiers` key, which did.
+
 The tier is resolved by the same `resolveAgentTier()` path an ordinary Agent
 spawn uses — same precedence, same model lookup, same thinking clamping, same
 availability checks, same immutable resolution snapshot. A tier the host does not
@@ -464,9 +487,12 @@ could silently win or be silently ignored.
 
 Fresh installs ship an effort ladder: `low`, `medium`, `high`. Every shipped
 profile inherits its model, so a new machine gets a working vocabulary without
-this package ever choosing a vendor for you. A managed call that names no tier
-uses the agent's own tier, then `agentTiers.defaultTier`, and finally falls back
-to `medium` so a workflow runs on an unconfigured machine.
+this package ever choosing a vendor for you. Those names are also what
+pi-workflows' shipped default table maps its strengths onto — identity, and only
+where you define the name — so a stock machine runs workflows at the strengths
+their scripts asked for. Rename or remove them and that default simply yields
+nothing: a managed call that names no tier uses the agent's own tier, then
+`agentTiers.defaultTier`, and finally falls back to `medium`.
 
 `medium` inherits its model, so on an unconfigured machine that fallback runs on
 the parent session's model. What it buys is a call with a *named* policy, a
@@ -577,7 +603,7 @@ the global file defines. The menu writes the merged catalogue back to the
 project file, so deleting one of several works, but deleting the last one — or
 clearing a `defaultTier` that only global sets — leaves no `agentTiers` key
 behind, and the global value is inherited again on the next start. Remove it
-from `~/.pi/agent/subagents.json` instead. The same is true of `workflow.tiers`.
+from `~/.pi/agent/subagents.json` instead.
 
 ### Refusals
 
@@ -645,7 +671,7 @@ Runtime tuning values set via `/agents` → Settings (max concurrency, default m
 
 **Precedence:** project overrides global on any field present in both. Missing fields fall back to the hardcoded defaults (max concurrency `4`, default max turns unlimited, grace turns `5`, nested depth `2`, join mode `smart`, defaults enabled).
 
-The `workflow` settings key is **retired**. Managed `pi-workflows` calls name an `agentTiers` key directly, so there is no separate workflow routing table; a file that still has one is ignored with a warning naming the key. `agentTiers.defaultTier` replaces what `workflow.defaultTier` used to do. See [One catalogue, including for workflows](#one-catalogue-including-for-workflows).
+The `workflow` settings key is **retired**; a file that still has one is ignored with a warning naming the key. This file holds no workflow routing of its own: a managed `pi-workflows` call arrives naming a key from `agentTiers`, and which key that is was decided on the pi-workflows side by its own `strengths` table — a table of keys into this catalogue, never a second catalogue and never its own `model`/`thinking`. `agentTiers.defaultTier` replaces what `workflow.defaultTier` used to do. See [One catalogue, including for workflows](#one-catalogue-including-for-workflows).
 
 **Default model** (`defaultModel`, unset): the model a non-tiered ordinary subagent runs — see [`defaultModel`](#defaultmodel) for where it sits in precedence, why an unresolvable value falls back instead of failing, and how `"inherit"` lets a project cancel a global default. **Default tier** (`agentTiers.defaultTier`, unset) is the tier applied when neither the caller nor the agent names one; the profiles it selects from live under [`agentTiers`](#model-tiers). It has three settings — a tier name, `unset`, and `none` — which the menu offers separately because the last two behave differently for managed workflow calls; see [Model tiers](#model-tiers) for the table.
 
@@ -741,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.0",
+  "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.