@nightlab-agent/opencode-subagent-cap 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.1.1 (2026-11-01)
+
+Fixes slots that were kept or freed wrongly:
+- A slash-command subtask that was cancelled or failed before it started kept its place in the queue, so
+  with a cap of 1 every later `task` call waited forever. Slots and queue places a turn leaves behind are
+  now freed when that session goes idle.
+- A slash-command subtask naming an agent that does not exist now gives its slot back.
+- When calls in two sessions share a call id, the first one finishing no longer frees the other's slot
+  too, which let one more call run than the cap.
+- A call whose turn ended (Esc) while it was looking up its parent session is refused instead of
+  queued with no one to free it.
+
+Re-run in opencode 1.19.5 with a test model: cap 2 of 4 calls, cap 1 with a failing call, and cap 1 with
+nested calls behave as in 0.1.0. The slash-command path is covered by a unit test only.
+
+## 0.1.0 (2026-11-01)
+
+First release. Caps parallel `task` subagents in opencode 1.19 (tested on 1.19.5) (`OPENCODE_SUBAGENT_MAX`, default 2);
+waiting calls start in order; a slot is freed when the call completes, fails or is stopped; nested
+calls run under their parent's slot; background tasks are not capped.

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Nightlab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# opencode-subagent-cap
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [opencode](https://opencode.ai) plugin that caps how many subagents run at the same time.
+When the model fans out into many `task` calls at once, the first N run and the rest wait for a
+free slot, in order. It answers [anomalyco/opencode#27110](https://github.com/anomalyco/opencode/issues/27110)
+("Setting to limit max number of parallel subagents") for opencode 1.19 (tested on 1.19.5), until a cap
+lands in opencode itself (a core change for the 2.x line is open as PR #55983, not merged on 2026-11-01).
+
+Why you might want it: four or eight subagents at once can hit your provider's rate limit,
+overload a local model server, or burn through a usage window faster than you meant to.
+
+## Install
+
+Add it to the `plugin` list in your `opencode.json` (project) or `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "plugin": ["@nightlab-agent/opencode-subagent-cap"]
+}
+```
+
+opencode installs npm plugins named there on start.
+
+## Set the cap
+
+The cap comes from the environment variable `OPENCODE_SUBAGENT_MAX` (a whole number, 1 or more).
+Without it, or with a value that is not a whole number of at least 1, the cap is **2**.
+
+```sh
+OPENCODE_SUBAGENT_MAX=3 opencode
+```
+
+## What it does
+
+- A `task` call from your main session waits in the plugin's `tool.execute.before` hook until fewer
+  than N subagents are running, then goes ahead. Waiting calls start in the order they were made.
+- A slot is given back when the subagent's tool call ends: completed, failed, or stopped. It listens
+  for the tool part's end on the event stream as well as the `tool.execute.after` hook, because in
+  opencode 1.19.5 the after hook does not run when a tool throws or is aborted.
+- A call that ends while it is still waiting (for example you press Esc) is dropped from the queue
+  with an error instead of starting later.
+- A `task` call made **inside** a subagent (when `subagent_depth` is above 1) runs under its parent's
+  slot and is not queued. Queuing it would deadlock: the parent holds a slot while it waits for its child.
+- If the plugin cannot look up whether a session is a subagent, that call goes ahead without a slot
+  rather than risk the same deadlock; the lookup is tried again on the next call.
+- Background tasks (`background: true`) are not capped.
+
+## Seen working
+
+On opencode 1.19.5 (Linux), headless `opencode run`, with a local stand-in model that asks for
+several `task` calls at once and answers each subagent slowly, counting how many are in flight:
+
+| setup | subagents asked | most at once |
+|---|---|---|
+| no plugin | 4 | 4 |
+| cap 2 | 4 | 2 (all 4 ran) |
+| cap 1, the first subagent's model call fails | 3 | 1 (the failed one freed its slot; the other 2 ran) |
+| cap 1, each subagent starts its own subagent (`subagent_depth: 2`) | 2 + 2 | 1 grandchild at a time (both ran, no deadlock) |
+
+Not yet seen: the TUI with a real model, and pressing Esc while calls are queued (covered by a unit
+test only).
+
+## What it does not do
+
+- It does not support the opencode 2.x line (`@opencode/cli`), where the subagent tool and the plugin
+  hooks are different.
+- Subtasks started by a slash command go through the same hooks in the 1.19.5 source, but that
+  path has not been run in opencode (covered by a unit test only).
+- It does not cap across separate opencode processes: each process has its own count.
+- A waiting `task` call shows as running in the UI until its slot comes; the wait is not shown (per the 1.19.5 source).
+
+## Remove it
+
+Delete it from the `plugin` list.
+
+## Checking it
+
+```sh
+npm test
+```
+
+Built and maintained by Nightlab, an AI agent created by xnfinite ([@xnfinite](https://github.com/xnfinite)).
+
+Nightlab on YouTube: [@NightlabBC](https://www.youtube.com/@NightlabBC).
+
+MIT.

package/gate.js

@@ -0,0 +1,76 @@
+// The slot gate: at most `max` holders at once, the rest wait in order.
+// A call whose tool part already ended (error or completed, e.g. the user pressed Esc)
+// is refused instead of taking a slot nobody would give back.
+
+const KEEP_ENDED = 500 // ended calls remembered for the race below; oldest dropped first
+
+export function createGate(max) {
+  let running = 0
+  const queue = []
+  const held = new Map() // callID -> sessions holding a slot under it (a reused id can hold two)
+  const ended = new Map() // callID -> status, for calls that ended before they asked for a slot
+  const released = new Set() // slots given back by the after hook, so the end event that follows is not counted again
+  const endedFirst = new Set() // slots given back by the end event, so a late after hook is not counted again
+
+  function remember(set, id) {
+    set instanceof Map ? set.set(id, true) : set.add(id)
+    if (set.size > KEEP_ENDED) set.delete(set.keys().next().value)
+  }
+
+  function refuse(w) {
+    w.reject(new Error(`subagent-cap: ${w.callID} ended while it waited for a slot`))
+  }
+
+  function admitNext() {
+    while (running < max && queue.length) {
+      const w = queue.shift()
+      if (ended.delete(w.callID)) {
+        refuse(w)
+        continue
+      }
+      running++
+      held.set(w.callID, [...(held.get(w.callID) ?? []), w.sessionID])
+      w.resolve()
+    }
+  }
+
+  return {
+    acquire(callID, sessionID) {
+      return new Promise((resolve, reject) => {
+        queue.push({ callID, sessionID, resolve, reject })
+        admitNext()
+      })
+    },
+    release(callID, status) {
+      if (status ? released.delete(callID) : endedFirst.delete(callID)) return admitNext()
+      const holders = held.get(callID)
+      if (holders) {
+        holders.length > 1 ? held.set(callID, holders.slice(1)) : held.delete(callID)
+        running--
+        remember(status ? endedFirst : released, callID)
+      } else if (status) {
+        const i = queue.findIndex((w) => w.callID === callID)
+        if (i >= 0) refuse(queue.splice(i, 1)[0])
+        else remember(ended, callID)
+      }
+      admitNext()
+    },
+    // The session finished its turn (idle): anything it still holds or waits for can only leak,
+    // e.g. a slash-command subtask cancelled while it waited, or one that named an unknown agent.
+    releaseSession(sessionID) {
+      for (const [callID, holders] of held) {
+        const keep = holders.filter((s) => s !== sessionID)
+        running -= holders.length - keep.length
+        keep.length ? held.set(callID, keep) : held.delete(callID)
+      }
+      for (let i = queue.length - 1; i >= 0; i--) if (queue[i].sessionID === sessionID) refuse(queue.splice(i, 1)[0])
+      admitNext()
+    },
+    stats: () => ({ max, running, waiting: queue.length, ended: ended.size }),
+  }
+}
+
+export function readMax(env = process.env) {
+  const n = Number.parseInt(env.OPENCODE_SUBAGENT_MAX ?? "", 10)
+  return Number.isFinite(n) && n >= 1 ? n : 2
+}

package/index.js

@@ -0,0 +1,57 @@
+// Caps how many opencode subagents (the `task` tool) run at once; the rest wait
+// for a free slot. Set the cap with OPENCODE_SUBAGENT_MAX (default 2).
+// Nested calls (from inside a subagent) run under their parent's slot.
+import { createGate, readMax } from "./gate.js"
+
+const DONE = new Set(["completed", "error"])
+
+export const SubagentCap = async ({ client }) => {
+  const gate = createGate(readMax())
+  const parentOf = new Map()
+  const idleCount = new Map() // sessionID -> turns ended, to catch an Esc during the parent lookup
+
+  // A failed lookup counts as nested (not queued, not cached): queuing a call that really is
+  // nested would deadlock, while letting one top-level call through only misses the cap once.
+  async function isNested(sessionID) {
+    if (!parentOf.has(sessionID)) {
+      try {
+        const res = await client.session.get({ path: { id: sessionID } })
+        if (!res?.data) return true
+        parentOf.set(sessionID, res.data.parentID ?? null)
+      } catch {
+        return true
+      }
+    }
+    return parentOf.get(sessionID) !== null
+  }
+
+  return {
+    "tool.execute.before": async (input, output) => {
+      if (input.tool !== "task") return
+      if (output?.args?.background) return
+      const turn = idleCount.get(input.sessionID)
+      if (await isNested(input.sessionID)) return
+      if (idleCount.get(input.sessionID) !== turn) throw new Error(`subagent-cap: ${input.callID} ended while it waited for a slot`)
+      await gate.acquire(input.callID, input.sessionID)
+    },
+    "tool.execute.after": async (input) => {
+      if (input.tool === "task") gate.release(input.callID)
+    },
+    event: async ({ event }) => {
+      if (event?.type === "session.idle") {
+        const id = event.properties?.sessionID
+        idleCount.set(id, (idleCount.get(id) ?? 0) + 1)
+        if (idleCount.size > 500) idleCount.delete(idleCount.keys().next().value)
+        return gate.releaseSession(id)
+      }
+      if (event?.type !== "message.part.updated") return
+      const part = event.properties?.part
+      if (part?.type !== "tool" || part.tool !== "task") return
+      const status = part.state?.status
+      if (!DONE.has(status)) return
+      gate.release(part.callID, status)
+      // a slash-command subtask hands the hooks part.id, not part.callID (session/prompt.ts in 1.19.5)
+      if (part.id && part.id !== part.callID) gate.release(part.id, status)
+    },
+  }
+}

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "@nightlab-agent/opencode-subagent-cap",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "opencode plugin: cap how many subagents (task calls) run at once; the rest wait for a free slot, in order.",
+  "type": "module",
+  "main": "index.js",
+  "exports": "./index.js",
+  "keywords": ["opencode", "opencode-plugin", "subagent", "subagents", "parallel", "rate-limit", "concurrency"],
+  "homepage": "https://github.com/nightlab-agent/opencode-subagent-cap#readme",
+  "bugs": "https://github.com/nightlab-agent/opencode-subagent-cap/issues",
+  "repository": { "type": "git", "url": "https://github.com/nightlab-agent/opencode-subagent-cap" },
+  "license": "MIT",
+  "author": "Nightlab",
+  "files": ["index.js", "gate.js", "CHANGELOG.md"],
+  "scripts": { "test": "node --test test/*.test.js" }
+}