Skip to content

feat(supervise): max-live-workers concurrency cap + explicit worker metering opt-in #360

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
drewstone merged 1 commit into from
Jun 22, 2026
Merged

feat(supervise): max-live-workers concurrency cap + explicit worker metering opt-in #360

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 22 additions & 10 deletions docs/api/mcp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4059,11 +4059,23 @@ Analyst kind ids to run AUTOMATICALLY when a worker settles `done` (the analyst-
and queued for the driver to pull via `await_event`. Omit/empty = no auto-analysis (default;
the driver can still run lenses on demand via `run_analyst`). Requires `analysts`.

##### maxLiveWorkers?

> `readonly` `optional` **maxLiveWorkers?**: `number`

Defined in: [mcp/tools/coordination.ts:112](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L112)

Hard cap on how many workers may be LIVE (spawned but not yet settled) at once. `spawn_agent`
counts the scope's non-terminal nodes and fails closed (`error: 'max-live-workers'`) BEFORE
reserving from the pool when the cap is already met — a concurrency fence on top of the
conserved-budget fence (the pool bounds total work; this bounds simultaneous work, e.g. live
sandboxes/boxes). Omit or `<= 0` = no cap (the prior behavior; the pool stays the only fence).

***

### CoordinationTools

Defined in: [mcp/tools/coordination.ts:116](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L116)
Defined in: [mcp/tools/coordination.ts:122](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L122)

The supervisor-side toolbox returned by [createCoordinationTools](#createcoordinationtools): the MCP tool
descriptors a driver `AgentProfile` calls to spawn, steer, observe, and settle workers
Expand All @@ -4077,15 +4089,15 @@ choice, steerable counterpart to the one-shot own-sandbox delegation MCP.

> `readonly` **tools**: [`McpToolDescriptor`](#mcptooldescriptor)[]

Defined in: [mcp/tools/coordination.ts:117](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L117)
Defined in: [mcp/tools/coordination.ts:123](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L123)

#### Methods

##### isStopped()

> **isStopped**(): `boolean`

Defined in: [mcp/tools/coordination.ts:118](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L118)
Defined in: [mcp/tools/coordination.ts:124](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L124)

###### Returns

Expand All @@ -4095,7 +4107,7 @@ Defined in: [mcp/tools/coordination.ts:118](https://github.com/tangle-network/ag

> **stopReason**(): `string` \| `undefined`

Defined in: [mcp/tools/coordination.ts:119](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L119)
Defined in: [mcp/tools/coordination.ts:125](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L125)

###### Returns

Expand All @@ -4105,7 +4117,7 @@ Defined in: [mcp/tools/coordination.ts:119](https://github.com/tangle-network/ag

> **settled**(): readonly [`SettledWorker`](#settledworker)[]

Defined in: [mcp/tools/coordination.ts:120](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L120)
Defined in: [mcp/tools/coordination.ts:126](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L126)

###### Returns

Expand All @@ -4115,7 +4127,7 @@ readonly [`SettledWorker`](#settledworker)[]

> **questions**(): readonly [`QuestionRecord`](#questionrecord)[]

Defined in: [mcp/tools/coordination.ts:121](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L121)
Defined in: [mcp/tools/coordination.ts:127](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L127)

###### Returns

Expand All @@ -4125,7 +4137,7 @@ readonly [`QuestionRecord`](#questionrecord)[]

> **history**(): readonly [`BusRecord`](runtime.md#busrecord)\<[`CoordinationEvent`](runtime.md#coordinationevent)\>[]

Defined in: [mcp/tools/coordination.ts:125](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L125)
Defined in: [mcp/tools/coordination.ts:131](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L131)

The full ordered log of every bus event — UP (settled / question / finding) and DOWN
(steer / answer) — the observability audit + replay trail. Each record carries seq,
Expand All @@ -4139,7 +4151,7 @@ readonly [`BusRecord`](runtime.md#busrecord)\<[`CoordinationEvent`](runtime.md#c

> **stats**(): [`BusStats`](runtime.md#busstats)

Defined in: [mcp/tools/coordination.ts:127](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L127)
Defined in: [mcp/tools/coordination.ts:133](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L133)

Bus throughput counters (published / pulled / by-kind) for live dashboards.

Expand All @@ -4151,7 +4163,7 @@ Bus throughput counters (published / pulled / by-kind) for live dashboards.

> **raiseFinding**(`finding`): `Promise`\<`void`\>

Defined in: [mcp/tools/coordination.ts:131](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L131)
Defined in: [mcp/tools/coordination.ts:137](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L137)

Raise a `finding` on the bus from outside the settle hook — the seam an ONLINE detector
(mid-run, on the worker pipe) uses to tell the driver "this worker is looping/erroring" the
Expand Down Expand Up @@ -7374,7 +7386,7 @@ passed in because replay-safe paths must not read `Date.now`.

> **createCoordinationTools**(`opts`): [`CoordinationTools`](#coordinationtools)

Defined in: [mcp/tools/coordination.ts:154](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L154)
Defined in: [mcp/tools/coordination.ts:160](https://github.com/tangle-network/agent-runtime/blob/main/src/mcp/tools/coordination.ts#L160)

Build the driver's MCP tools over a live scope.

Expand Down
Loading
Loading