@heretyc/subagent-mcp 2.10.3 → 2.12.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +158 -187
- package/directives/carryover-codex.md +4 -2
- package/directives/reminder-on.md +1 -1
- package/directives/short-on.md +1 -1
- package/dist/advanced-ruleset.py +67 -67
- package/dist/concurrency.js +12 -6
- package/dist/config-scaffold.js +1 -1
- package/dist/drivers.js +106 -0
- package/dist/global-concurrency.jsonc +29 -28
- package/dist/index.js +171 -56
- package/dist/orchestration/hook-core.js +16 -6
- package/dist/routing-table.json +3561 -3561
- package/dist/ruleset-scaffold.js +1 -1
- package/dist/setup.js +2 -0
- package/dist/zombie.js +35 -5
- package/package.json +69 -69
- package/scripts/postinstall.mjs +102 -102
package/README.md
CHANGED
|
@@ -1,187 +1,158 @@
|
|
|
1
|
-
# subagent-mcp
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/@heretyc/subagent-mcp)
|
|
4
|
-
[](LICENSE)
|
|
5
|
-
[](https://www.npmjs.com/package/@heretyc/subagent-mcp)
|
|
6
|
-
[](https://github.com/Heretyc/subagent-mcp/actions/workflows/claude-routine.yml)
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
subagent-mcp
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
|
107
|
-
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
|
145
|
-
|---|---|
|
|
146
|
-
|
|
|
147
|
-
|
|
|
148
|
-
|
|
|
149
|
-
|
|
|
150
|
-
|
|
|
151
|
-
|
|
|
152
|
-
|
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
Each agent transitions through these states:
|
|
160
|
-
|
|
161
|
-
| Status | Meaning |
|
|
162
|
-
|---|---|
|
|
163
|
-
| `processing` | Driver alive with a visible provider-stream heartbeat in the last 10 minutes — actively working. Launch time counts as the initial heartbeat |
|
|
164
|
-
| `stalled` | Driver STILL ALIVE but no parsed visible provider stream item for >= 10 minutes — working, thinking, or awaiting a temp-file handoff (not a failure). Recovers to `processing` if the visible stream resumes |
|
|
165
|
-
| `finished` | Current turn completed, or driver exited with code 0 |
|
|
166
|
-
| `errored` | Process exited with non-zero code |
|
|
167
|
-
| `stopped` | Terminated by `kill_agent` |
|
|
168
|
-
|
|
169
|
-
`processing` and `stalled` are live. `stalled` means the driver is alive but quiet (>= 10 min no visible stream); it recovers automatically and is never auto-killed — do not `kill_agent` a stalled agent. `wait` does not return on `stalled`. Full semantics: [docs/reference/status-lifecycle.md](docs/reference/status-lifecycle.md).
|
|
170
|
-
|
|
171
|
-
## Documentation
|
|
172
|
-
|
|
173
|
-
| Document | Contents |
|
|
174
|
-
|---|---|
|
|
175
|
-
| [docs/registration.md](docs/registration.md) | Per-platform setup: Claude Code, Codex, Gemini CLI, Claude Desktop; manual wiring; developer install from source |
|
|
176
|
-
| [docs/tools.md](docs/tools.md) | Full tool reference — all eight tools, parameters, return shapes |
|
|
177
|
-
| [docs/usage.md](docs/usage.md) | Model & effort matrix, ultracode mode, CLI invocations, usage examples |
|
|
178
|
-
| [docs/SPEC.md](docs/SPEC.md) | Full technical specification — architecture, schemas, status lifecycle, error catalogue |
|
|
179
|
-
| [docs/spec/interactive-drivers.md](docs/spec/interactive-drivers.md) | Always-interactive Claude/Codex driver model |
|
|
180
|
-
| [docs/release-notes.md](docs/release-notes.md) | Operator-facing release notes |
|
|
181
|
-
| [CONTRIBUTING.md](CONTRIBUTING.md) | Contributor guide — dev environment, build, test, publish |
|
|
182
|
-
|
|
183
|
-
## License
|
|
184
|
-
|
|
185
|
-
Apache-2.0 — Copyright 2026 Lexi Blackburn
|
|
186
|
-
|
|
187
|
-
See [LICENSE](LICENSE).
|
|
1
|
+
# subagent-mcp
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@heretyc/subagent-mcp)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
[](https://www.npmjs.com/package/@heretyc/subagent-mcp)
|
|
6
|
+
[](https://github.com/Heretyc/subagent-mcp/actions/workflows/claude-routine.yml)
|
|
7
|
+
|
|
8
|
+
Turn any AI coding assistant into a **manager of other AI agents**. subagent-mcp
|
|
9
|
+
lets your Claude Code or Codex session start, watch, message, and stop a whole
|
|
10
|
+
team of AI sub-agents — on macOS, Linux, and Windows. **No direct API calls. No
|
|
11
|
+
API keys.** It drives the `claude` and `codex` command-line tools you already
|
|
12
|
+
signed into.
|
|
13
|
+
|
|
14
|
+
## What it does
|
|
15
|
+
|
|
16
|
+
Normally one AI assistant does all the work in one conversation. That
|
|
17
|
+
conversation fills up, slows down, and eventually forgets its early context. As
|
|
18
|
+
of a certain size it "compacts" — summarizing and dropping detail.
|
|
19
|
+
|
|
20
|
+
subagent-mcp changes the shape of the work. Your assistant becomes an
|
|
21
|
+
**orchestrator**: it hands each task to a fresh sub-agent, watches the results,
|
|
22
|
+
and moves on — without ever doing the reading or writing itself.
|
|
23
|
+
|
|
24
|
+
## Why it works this way
|
|
25
|
+
|
|
26
|
+
Four bets drive the whole design. The full reasoning lives in
|
|
27
|
+
[docs/spec/arch-rationale.md](docs/spec/arch-rationale.md); the short version:
|
|
28
|
+
|
|
29
|
+
- **The effective memory grows geometrically.** Because the orchestrator only
|
|
30
|
+
ever holds *summaries* of what its sub-agents did — never the raw files — its
|
|
31
|
+
own memory fills up far more slowly. That means **very long tasks with little
|
|
32
|
+
or no compaction**.
|
|
33
|
+
- **Mixed providers avoid blind spots.** Using Claude *and* Codex together means
|
|
34
|
+
one vendor's weak spot or outage doesn't blind or block the whole job — and
|
|
35
|
+
you're never locked in to a single vendor.
|
|
36
|
+
- **Ruthless token efficiency.** Every hand-off is compressed and every read is
|
|
37
|
+
kept small, so the system stays fast and cheap even on marathon tasks.
|
|
38
|
+
- **Durable, authoritative reminders.** The operating rules are re-injected every
|
|
39
|
+
turn through official host hooks, so the assistant doesn't drift off-task or
|
|
40
|
+
start making things up over a long run.
|
|
41
|
+
|
|
42
|
+
## Install
|
|
43
|
+
|
|
44
|
+
### What you need first
|
|
45
|
+
|
|
46
|
+
- Node.js 18 or newer (`node --version`)
|
|
47
|
+
- `claude` CLI — installed and signed in (`claude --version`)
|
|
48
|
+
- `codex` CLI — installed and signed in (`codex --version`; optional if you
|
|
49
|
+
only use Claude)
|
|
50
|
+
|
|
51
|
+
Building from source needs extra developer tools — see
|
|
52
|
+
[CONTRIBUTING.md](CONTRIBUTING.md).
|
|
53
|
+
|
|
54
|
+
### Install the package
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
npm install -g @heretyc/subagent-mcp
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
This is the standard install for everyone. (Organizations pinning the package
|
|
61
|
+
through GitHub Packages should see [docs/registration.md](docs/registration.md).)
|
|
62
|
+
|
|
63
|
+
### Wire it into your assistant
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
subagent-mcp setup
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Installing the package only ships the program — it does **not** connect anything
|
|
70
|
+
on its own. `subagent-mcp setup` finds your Claude Code / Codex install and
|
|
71
|
+
registers both the server and the per-turn orchestration hooks. Preview first
|
|
72
|
+
with `subagent-mcp setup --dry-run`.
|
|
73
|
+
|
|
74
|
+
### Restart, then turn on the invariant
|
|
75
|
+
|
|
76
|
+
Restart your Claude Code or Codex session so it picks up the new tools. On Codex,
|
|
77
|
+
run `/hooks` and trust the new hook. Then (recommended):
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
subagent-mcp init --global
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
This writes a small managed "always delegate" rule block into your global
|
|
84
|
+
assistant config once, so it works across every project. For a single project
|
|
85
|
+
instead, use `subagent-mcp init --root /path/to/project`. Full per-platform
|
|
86
|
+
wiring (Gemini CLI, Claude Desktop, manual setup) is in
|
|
87
|
+
[docs/registration.md](docs/registration.md).
|
|
88
|
+
|
|
89
|
+
## How to operate it
|
|
90
|
+
|
|
91
|
+
### Orchestration mode: ON vs OFF
|
|
92
|
+
|
|
93
|
+
- **ON** — your assistant acts as a pure manager. It never reads or writes files
|
|
94
|
+
directly; it delegates every step to sub-agents. Best for big, long-running
|
|
95
|
+
jobs.
|
|
96
|
+
- **OFF** — your assistant works normally, on its own, with no delegation rules.
|
|
97
|
+
|
|
98
|
+
Flip it with the `orchestration-mode` tool. (Desktop apps can toggle the mode
|
|
99
|
+
but don't receive the per-turn hook reminders.)
|
|
100
|
+
|
|
101
|
+
### The 8 tools at a glance
|
|
102
|
+
|
|
103
|
+
| Tool | What it does |
|
|
104
|
+
|---|---|
|
|
105
|
+
| `launch_agent` | Start a sub-agent on a task (just give a prompt + a task category) |
|
|
106
|
+
| `poll_agent` | Check how an agent is doing and read its latest output |
|
|
107
|
+
| `kill_agent` | Stop a running or quiet agent |
|
|
108
|
+
| `send_message` | Send a follow-up message to a live agent |
|
|
109
|
+
| `list_agents` | See every agent and its current status |
|
|
110
|
+
| `wait` | Pause until a specific agent finishes |
|
|
111
|
+
| `orchestration-mode` | Turn manager-mode ON or OFF |
|
|
112
|
+
| `model-selection-mode` | Let the server auto-pick the model, or allow manual overrides |
|
|
113
|
+
|
|
114
|
+
You never have to choose a model. Give `launch_agent` a plain-English prompt and
|
|
115
|
+
a **task category** (e.g. "coding", "debugging", "security_review") and the
|
|
116
|
+
server picks the best provider, model, and effort for that kind of work.
|
|
117
|
+
|
|
118
|
+
### How many run at once
|
|
119
|
+
|
|
120
|
+
There is a single machine-wide limit on how many sub-agents run at the same time
|
|
121
|
+
across everything on your computer. The **default is 20**. When the limit is
|
|
122
|
+
reached, a new `launch_agent` is turned down right away — it does not wait in a
|
|
123
|
+
queue. You change the number in the `global-concurrency.jsonc` file in the
|
|
124
|
+
install folder (minimum 10); the file is re-read on every launch, so no restart
|
|
125
|
+
is needed.
|
|
126
|
+
|
|
127
|
+
## Basic debugging
|
|
128
|
+
|
|
129
|
+
- **"An agent looks stuck."** A quiet agent is usually **still alive**, not
|
|
130
|
+
dead. After ~10 minutes with no output an agent is marked `stalled` — it's
|
|
131
|
+
thinking or waiting on a hand-off. It recovers on its own. **Do not kill a
|
|
132
|
+
stalled agent**, and `wait` will not return on one.
|
|
133
|
+
- **"It won't start a new agent (cap reached)."** You've hit the concurrent
|
|
134
|
+
limit. Use `list_agents` to see what's running and `kill_agent` on anything
|
|
135
|
+
you no longer need — that frees a slot immediately. Raising the number in
|
|
136
|
+
`global-concurrency.jsonc` also works.
|
|
137
|
+
- **"Where are the logs?"** Each agent's recent output is available any time via
|
|
138
|
+
`poll_agent`. The server's own diagnostics go to your host's normal MCP
|
|
139
|
+
server log (your Claude Code or Codex session logs) — all server logging goes
|
|
140
|
+
to stderr, never mixed into results.
|
|
141
|
+
|
|
142
|
+
## Documentation
|
|
143
|
+
|
|
144
|
+
| Document | Contents |
|
|
145
|
+
|---|---|
|
|
146
|
+
| [docs/spec/arch-rationale.md](docs/spec/arch-rationale.md) | Why it's built this way — the full design rationale |
|
|
147
|
+
| [docs/registration.md](docs/registration.md) | Per-platform setup: Claude Code, Codex, Gemini CLI, Claude Desktop |
|
|
148
|
+
| [docs/tools.md](docs/tools.md) | Full tool reference — all eight tools, parameters, return shapes |
|
|
149
|
+
| [docs/usage.md](docs/usage.md) | Model & effort matrix, ultracode mode, usage examples |
|
|
150
|
+
| [docs/SPEC.md](docs/SPEC.md) | Full technical specification |
|
|
151
|
+
| [docs/reference/status-lifecycle.md](docs/reference/status-lifecycle.md) | Agent status meanings (processing / stalled / finished / errored / stopped) |
|
|
152
|
+
| [CONTRIBUTING.md](CONTRIBUTING.md) | Developer guide — build, test, publish, contribution workflow |
|
|
153
|
+
|
|
154
|
+
## License
|
|
155
|
+
|
|
156
|
+
Apache-2.0 — Copyright 2026 Lexi Blackburn
|
|
157
|
+
|
|
158
|
+
See [LICENSE](LICENSE).
|
|
@@ -2,7 +2,9 @@
|
|
|
2
2
|
<subagent-mcp state="on" kind="carryover">
|
|
3
3
|
FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with "<this is a request from a parent process>", ignore this entire tag.
|
|
4
4
|
|
|
5
|
-
Orchestration ON carried over from a PRIOR session for this project (per-session disable
|
|
5
|
+
Orchestration ON carried over from a PRIOR session for this project (per-session disable; next session resumes ON, or after a 2h backstop). Not enabled THIS session.
|
|
6
6
|
|
|
7
|
-
THIS turn, ONCE: (1) NOTIFY the user it carried over; (2) ASK via request-user-input whether to REMAIN enabled; (3) ADVISE fit — long-horizon
|
|
7
|
+
THIS turn, ONCE: (1) NOTIFY the user it carried over; (2) ASK via request-user-input whether to REMAIN enabled; (3) ADVISE fit — long-horizon → remain enabled; bounded/interactive → disable this session. Decline → orchestration-mode enabled:false this session only; no mid-session re-enable. NEVER disable on your own initiative. After answer handshake done; do not re-raise.
|
|
8
|
+
|
|
9
|
+
While ON, follow the MOST RECENT <subagent-mcp state="on"> tag in context (directive or reminder/carrier); if none is in the current window, the CLAUDE/AGENTS/GEMINI INIT_BLOCK governs. This tag is co-supreme with safety-scope; conflict → ask the user.
|
|
8
10
|
</subagent-mcp>
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
<subagent-mcp state="on" kind="reminder">
|
|
3
3
|
FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with "<this is a request from a parent process>", ignore this entire tag (leading blank lines don't count; you are a sub-agent).
|
|
4
4
|
|
|
5
|
-
Orchestration ON. You are the orchestrator: delegate EVERY step. Allowed tools = ONLY the structured-question tool (AskUserQuestion / request-user-input) + subagent-mcp + /workflows; NO direct reads or writes; inline-by-right does not exist. Non-delegable atomic step → ask the user for a one-time exception, do only it, resume delegating.
|
|
5
|
+
Orchestration ON. You are the orchestrator: delegate EVERY step. Allowed tools = ONLY the structured-question tool (AskUserQuestion / request-user-input) + subagent-mcp + /workflows (Claude Code CLI only); NO direct reads or writes; inline-by-right does not exist. Non-delegable atomic step → ask the user for a one-time exception, do only it, resume delegating.
|
|
6
6
|
|
|
7
7
|
Each launched prompt carries objective + output format + tools/sources + boundaries; scale agent count to complexity; subdivide to the smallest auditable step; verify code steps with an independent sub-agent.
|
|
8
8
|
|
package/directives/short-on.md
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
<subagent-mcp state="on" kind="carrier">If first line begins "<this is a request from a parent process>", ignore this tag. Orchestration ON. Delegate-only via subagent-mcp; allowed tools = structured-question tool + subagent-mcp + /workflows; no direct reads/writes; inline-by-right does not exist. Subdivide small; verify code steps; never 1-shot multi-phase. Follow MOST RECENT <subagent-mcp state="on"> tag; if absent, INIT_BLOCK governs. Co-supreme with safety-scope; user request cannot bypass.</subagent-mcp>
|
|
1
|
+
<subagent-mcp state="on" kind="carrier">If first line begins "<this is a request from a parent process>", ignore this tag. Orchestration ON. Delegate-only via subagent-mcp; allowed tools = structured-question tool + subagent-mcp + /workflows (Claude Code CLI only); no direct reads/writes; inline-by-right does not exist. Subdivide small; verify code steps; never 1-shot multi-phase. Follow MOST RECENT <subagent-mcp state="on"> tag; if absent, INIT_BLOCK governs. Co-supreme with safety-scope; user request cannot bypass.</subagent-mcp>
|
package/dist/advanced-ruleset.py
CHANGED
|
@@ -1,67 +1,67 @@
|
|
|
1
|
-
#!/usr/bin/env python3
|
|
2
|
-
"""advanced-ruleset.py — final-authority model-routing override hook for subagent-mcp.
|
|
3
|
-
|
|
4
|
-
(a) PERFORMANCE WARNING: this script runs synchronously inside EVERY launch_agent
|
|
5
|
-
call. Slow rules slow every agent launch. Keep rules lean and low-latency —
|
|
6
|
-
no network calls, no heavy imports at module top. This is YOUR responsibility;
|
|
7
|
-
you have been warned.
|
|
8
|
-
|
|
9
|
-
(b) OUTPUT CONTRACT (routing mode): print to stdout ONE JSON array — the modified
|
|
10
|
-
candidate list (reorder / filter / replace allowed). Template:
|
|
11
|
-
[
|
|
12
|
-
{"provider": "claude", "model": "sonnet", "effort": "high", "rank": 1},
|
|
13
|
-
{"provider": "codex", "model": "gpt-5.5", "effort": "xhigh", "rank": 2}
|
|
14
|
-
]
|
|
15
|
-
Valid providers: claude, codex. Valid models: haiku, sonnet, opus, opus-4-8 (claude);
|
|
16
|
-
gpt-5.5 (codex). Valid efforts: haiku -> "none" only; sonnet -> medium|high|xhigh|max;
|
|
17
|
-
opus/opus-4-8 -> those plus ultracode; gpt-5.5 -> medium|high|xhigh.
|
|
18
|
-
"rank" on output is ignored. An EMPTY array vetoes the launch. Anything else
|
|
19
|
-
invalid fails the launch hard — the server validates strictly.
|
|
20
|
-
|
|
21
|
-
(c) INPUT CONTRACT (routing mode, invoked as: <python> advanced-ruleset.py route):
|
|
22
|
-
stdin receives one JSON object:
|
|
23
|
-
{ "candidates": [ {"provider","model","effort","rank"} ... ], # rank 1..N best->worst
|
|
24
|
-
"context": { "task_category": str, "cwd": str,
|
|
25
|
-
"selection_mode": "auto"|"provider"|"provider_model"|"explicit",
|
|
26
|
-
"provider": str|None, "model": str|None, "effort": str|None } }
|
|
27
|
-
OS environment variables are visible natively (os.environ).
|
|
28
|
-
|
|
29
|
-
ENV-CHECK MODE (no arguments): prints {"ready": true|false, "load-rules": true|false}.
|
|
30
|
-
Runs once per MCP server process. load-rules false => ruleset silently disabled
|
|
31
|
-
for the rest of the process. Set LOAD_RULES = True below to activate.
|
|
32
|
-
"""
|
|
33
|
-
import json
|
|
34
|
-
import sys
|
|
35
|
-
|
|
36
|
-
LOAD_RULES = False
|
|
37
|
-
|
|
38
|
-
# --- Requirements stub (scaffold itself is stdlib-only) ----------------------
|
|
39
|
-
# List third-party distributions your rules import, e.g.:
|
|
40
|
-
# REQUIREMENTS = ["requests", "pyyaml"]
|
|
41
|
-
# Install with: <python> -m pip install <name> ...
|
|
42
|
-
REQUIREMENTS = []
|
|
43
|
-
|
|
44
|
-
def missing_requirements():
|
|
45
|
-
"""pip-check helper: returns the REQUIREMENTS entries not importable here."""
|
|
46
|
-
import importlib.util
|
|
47
|
-
return [r for r in REQUIREMENTS
|
|
48
|
-
if importlib.util.find_spec(r.replace("-", "_")) is None]
|
|
49
|
-
|
|
50
|
-
def env_check():
|
|
51
|
-
missing = missing_requirements()
|
|
52
|
-
json.dump({"ready": not missing, "load-rules": bool(LOAD_RULES)}, sys.stdout)
|
|
53
|
-
|
|
54
|
-
def apply_rules(candidates, context):
|
|
55
|
-
"""YOUR RULES HERE. Default: passthrough (returns the list unchanged)."""
|
|
56
|
-
return candidates
|
|
57
|
-
|
|
58
|
-
def route():
|
|
59
|
-
payload = json.load(sys.stdin)
|
|
60
|
-
out = apply_rules(payload.get("candidates", []), payload.get("context", {}))
|
|
61
|
-
json.dump(out, sys.stdout)
|
|
62
|
-
|
|
63
|
-
if __name__ == "__main__":
|
|
64
|
-
if len(sys.argv) > 1 and sys.argv[1] == "route":
|
|
65
|
-
route()
|
|
66
|
-
else:
|
|
67
|
-
env_check()
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""advanced-ruleset.py — final-authority model-routing override hook for subagent-mcp.
|
|
3
|
+
|
|
4
|
+
(a) PERFORMANCE WARNING: this script runs synchronously inside EVERY launch_agent
|
|
5
|
+
call. Slow rules slow every agent launch. Keep rules lean and low-latency —
|
|
6
|
+
no network calls, no heavy imports at module top. This is YOUR responsibility;
|
|
7
|
+
you have been warned.
|
|
8
|
+
|
|
9
|
+
(b) OUTPUT CONTRACT (routing mode): print to stdout ONE JSON array — the modified
|
|
10
|
+
candidate list (reorder / filter / replace allowed). Template:
|
|
11
|
+
[
|
|
12
|
+
{"provider": "claude", "model": "sonnet", "effort": "high", "rank": 1},
|
|
13
|
+
{"provider": "codex", "model": "gpt-5.5", "effort": "xhigh", "rank": 2}
|
|
14
|
+
]
|
|
15
|
+
Valid providers: claude, codex. Valid models: haiku, sonnet, opus, opus-4-8 (claude);
|
|
16
|
+
gpt-5.5 (codex). Valid efforts: haiku -> "none" only; sonnet -> medium|high|xhigh|max;
|
|
17
|
+
opus/opus-4-8 -> those plus ultracode; gpt-5.5 -> medium|high|xhigh.
|
|
18
|
+
"rank" on output is ignored. An EMPTY array vetoes the launch. Anything else
|
|
19
|
+
invalid fails the launch hard — the server validates strictly.
|
|
20
|
+
|
|
21
|
+
(c) INPUT CONTRACT (routing mode, invoked as: <python> advanced-ruleset.py route):
|
|
22
|
+
stdin receives one JSON object:
|
|
23
|
+
{ "candidates": [ {"provider","model","effort","rank"} ... ], # rank 1..N best->worst
|
|
24
|
+
"context": { "task_category": str, "cwd": str,
|
|
25
|
+
"selection_mode": "auto"|"provider"|"provider_model"|"explicit",
|
|
26
|
+
"provider": str|None, "model": str|None, "effort": str|None } }
|
|
27
|
+
OS environment variables are visible natively (os.environ).
|
|
28
|
+
|
|
29
|
+
ENV-CHECK MODE (no arguments): prints {"ready": true|false, "load-rules": true|false}.
|
|
30
|
+
Runs once per MCP server process. load-rules false => ruleset silently disabled
|
|
31
|
+
for the rest of the process. Set LOAD_RULES = True below to activate.
|
|
32
|
+
"""
|
|
33
|
+
import json
|
|
34
|
+
import sys
|
|
35
|
+
|
|
36
|
+
LOAD_RULES = False
|
|
37
|
+
|
|
38
|
+
# --- Requirements stub (scaffold itself is stdlib-only) ----------------------
|
|
39
|
+
# List third-party distributions your rules import, e.g.:
|
|
40
|
+
# REQUIREMENTS = ["requests", "pyyaml"]
|
|
41
|
+
# Install with: <python> -m pip install <name> ...
|
|
42
|
+
REQUIREMENTS = []
|
|
43
|
+
|
|
44
|
+
def missing_requirements():
|
|
45
|
+
"""pip-check helper: returns the REQUIREMENTS entries not importable here."""
|
|
46
|
+
import importlib.util
|
|
47
|
+
return [r for r in REQUIREMENTS
|
|
48
|
+
if importlib.util.find_spec(r.replace("-", "_")) is None]
|
|
49
|
+
|
|
50
|
+
def env_check():
|
|
51
|
+
missing = missing_requirements()
|
|
52
|
+
json.dump({"ready": not missing, "load-rules": bool(LOAD_RULES)}, sys.stdout)
|
|
53
|
+
|
|
54
|
+
def apply_rules(candidates, context):
|
|
55
|
+
"""YOUR RULES HERE. Default: passthrough (returns the list unchanged)."""
|
|
56
|
+
return candidates
|
|
57
|
+
|
|
58
|
+
def route():
|
|
59
|
+
payload = json.load(sys.stdin)
|
|
60
|
+
out = apply_rules(payload.get("candidates", []), payload.get("context", {}))
|
|
61
|
+
json.dump(out, sys.stdout)
|
|
62
|
+
|
|
63
|
+
if __name__ == "__main__":
|
|
64
|
+
if len(sys.argv) > 1 and sys.argv[1] == "route":
|
|
65
|
+
route()
|
|
66
|
+
else:
|
|
67
|
+
env_check()
|
package/dist/concurrency.js
CHANGED
|
@@ -79,20 +79,26 @@ export function reserveSlot(agentId, max, dir = slotDir(), cullDeps) {
|
|
|
79
79
|
mkdirSync(dir, { recursive: true, mode: 0o1777 });
|
|
80
80
|
cullStaleSlots(dir, cullDeps);
|
|
81
81
|
const slotPath = slotPathForAgent(dir, agentId);
|
|
82
|
+
const before = countSlots(dir);
|
|
83
|
+
if (before >= max) {
|
|
84
|
+
return { ok: false, current: before, max };
|
|
85
|
+
}
|
|
86
|
+
// ponytail: count->write->recount narrows the TOCTOU; a cross-process lock would close it fully.
|
|
82
87
|
writeSlotMetadata(slotPath, { agent_id: agentId });
|
|
83
|
-
const
|
|
84
|
-
if (
|
|
88
|
+
const after = countSlots(dir);
|
|
89
|
+
if (after > max) {
|
|
85
90
|
try {
|
|
86
91
|
unlinkSync(slotPath);
|
|
87
92
|
}
|
|
88
93
|
catch { }
|
|
89
|
-
return { ok: false, current:
|
|
94
|
+
return { ok: false, current: countSlots(dir), max };
|
|
90
95
|
}
|
|
91
|
-
return { ok: true, slotPath, current:
|
|
96
|
+
return { ok: true, slotPath, current: after, max };
|
|
92
97
|
}
|
|
93
98
|
catch (e) {
|
|
94
|
-
|
|
95
|
-
|
|
99
|
+
const error = e instanceof Error ? e.message : String(e);
|
|
100
|
+
console.error(`[concurrency] reserve failed, rejecting launch: ${error}`);
|
|
101
|
+
return { ok: false, current: -1, max, error };
|
|
96
102
|
}
|
|
97
103
|
}
|
|
98
104
|
export function releaseSlot(slotPath) {
|
package/dist/config-scaffold.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
// GENERATED by scripts/gen-ruleset-scaffold.mjs from src/global-concurrency.jsonc — DO NOT EDIT.
|
|
2
|
-
export const CONCURRENCY_SCAFFOLD = "// subagent-mcp — Global Concurrent Subagent Cap\
|
|
2
|
+
export const CONCURRENCY_SCAFFOLD = "// subagent-mcp — Global Concurrent Subagent Cap\n// ------------------------------------------------------------------\n// SOLE source of truth for the machine-wide limit on how many subagents\n// may be ALIVE AT ONCE across EVERY session, process, and user on this\n// machine. There is NO environment-variable override.\n//\n// The whole recursive descendant tree counts toward this ONE number: a\n// subagent that itself launches subagents adds to the same machine-wide\n// total, and OTHER active agentic sessions count too.\n//\n// RE-READ on every launch_agent call — edits take effect immediately, no\n// server restart required.\n//\n// Value rules (forcibly applied to the number below):\n// - missing / unset / non-integer / 0 / negative -> reset to default 20\n// - 1 through 9 -> forced UP to minimum 10\n// - 10 or greater -> used as-is\n//\n// Zombie culling is always enabled. There is no config knob. Before cap\n// rejection, launch/tool/hook paths refresh live owned slots, preserve stale\n// slots whose owner server is still alive, and cull stale slots whose owner is\n// gone. Managed stale slots terminate the child process tree, then force-kill\n// after 20s when needed; unmanaged stale slots are only unlinked.\n//\n// When the cap is reached after culling, launch_agent is REJECTED (never\n// queued). Free a slot with list_agents + kill_agent, then retry.\n{\n \"globalConcurrentSubagents\": 20\n}\n";
|