@playform/plugin-dsh-queue
v0.2.1 - UNPUBLISHED - plan:
SUBAGENT-QUEUE-PLUGIN
The role
The subagent-queue plugin: subagent work becomes a queue - the tasks as data, not the agents as
contexts.
The third orchestration-layer plugin, next to the batch-state and routing-enforcer plugins.
Plan: Documentation/Plans/SUBAGENT-QUEUE-PLUGIN.md.
The model
| IDLE (the harness's own) | QUEUE (this plugin) |
|---|
| What holds the task | the agent's context | the queue store (data) |
| The slot cost | one agent per task | data only; agents spawn at dispatch |
| The resume | send_message activation | the dispatcher's next-slot assignment |
The user's capacity model is the law:
-
Main pool: 10.
The main conversation holds up to 10 subagents (reserved slots, IDLE-held lanes included).
-
Child cap: 2.
Every spawned agent's own child fan-out is capped at 2 - the two-active regime, so the workflow
fan-out flood is prevented structurally.
-
The harness's own maxActiveSubagents knob stays the backstop, and the plugin enforces its model
at the dispatch level.
What it does
-
Enqueue.
A task carries the id, the self-contained spec (never altered), the role for the routing, the
priority, the dependencies, the state, and the result hash (queue_enqueue tool or
dshQueue.Enqueue).
No agent context is consumed while it waits.
-
Dispatch.
The deterministic order is dependencies satisfied first, then priority descending, then FIFO by
enqueue sequence (dshQueue.Dispatch).
A seat is taken from the agent's pool, and the state flips to dispatched.
-
Spawn.
With autoSpawn on (off by default), an assignment actually starts a subagent through the
harness's own subagent service (ctx.subagents.startActivation) - never a private spawn,
never a shell.
The spec goes to the child verbatim, the resolved route goes as its agentOptions, the parent
is the exact live Agent from ctx.agents.currentInitiator(), and the child's own result settles
the task (completed, or failed for any other stop reason).
-
Idle-Slot Automation.
With autoDispatch and autoSpawn both on, an enqueue or a released seat pulls the next queued
task into the free slot - the queue runs itself.
-
Routed Dispatch.
When the routing enforcer (dshRoute) is present, the route is resolved per the user's policy,
silently; absent, the dispatch proceeds unrouted (a contained skip).
-
Settle.
The seat is released and the journal records the flip (Complete / Fail / Interrupt), and
Interrupt also fires the spawn's own abort signal, canceling the child.
-
Restart Reconcile.
The caller hands back the previous process's Snapshot().tasks
(dshQueue.Reconcile(persisted?)), and every active task whose agent is not live is
requeued once (attempts 0 -> 1) and failed honestly on the second detection - never
silently dropped.
-
The Board.
The queue's state compiles into the batch-state context block as one TOC line:
QUEUE: <n> pending - next: <id|none> - running: <m>/<limit>.
-
The Journal.
Every state flip writes a best-effort P5 journal record plus one byte-stable ledger line - the
restart reconciliation's raw data.
The service
The plugin registers the dshQueue service:
| Method | Meaning |
|---|
Enqueue(input) | Queue a task (spec verbatim). |
Dispatch(agent?) | The deterministic next assignment (main pool by default). |
Capacity(agent?) | The free slots for the main pool or an agent. |
Start(id) / Complete(id, hash?) / Fail(id) / Interrupt(id) | The state machine (settle releases the seat). |
Reconcile(persisted?) | The restart reconcile; the report of requeued/failed ids. |
Flush() | Join the in-flight spawns (tests/reconcile; never a hot-path wait). |
Board() / Snapshot() | The compiled line / the full queue record. |
The configuration (all volatile)
| Field | Default | Meaning |
|---|
enabled | false | Master switch (ships disabled). |
log / logFile | true / ~/.dsh/playform/ets-plugin-dsh-queue.log | The plugin's own ledger. |
capacity.main / capacity.child | 10 / 2 | The user's capacity model. |
autoDispatch | true | Freed slots trigger the next assignment. |
routedDispatch | true | Consult dshRoute at dispatch when present. |
autoSpawn | false | Actually start the subagent (the approval posture; see below). |
spawnProvider | spawn | The harness subagent backend name selected at spawn. |
policy.* | see below | The D6 per-action allowlist (the OUTER gate). |
autoSpawn (the approval posture)
autoSpawn is the switch between assigning and launching.
It ships false on purpose: a spawn is a privileged action (D6 of the completion spec), so the
queue assigns seats and ledgers until the user turns the launch on.
With autoSpawn: false there is no ctx.subagents call and no spawn ledger line, and the idle-slot
automation is off too (an automatic assignment that the plugin cannot launch would strand the task
with a held seat).
With autoSpawn: true the dispatcher launches, the child's result settles the task, and a released
seat pulls the next queued task.
The policy block (D6) - the outer gate
The config carries the shared per-action allowlist (policy: Policy(), composed from the factory's
block), mapped to State.Allow:
| action | default | action | default |
|---|
read | auto | write | approve |
index | auto | commit | approve |
record | auto | spawn | approve |
suggest | auto | message | auto |
The policy is the outer gate, and autoSpawn is the inner one.
An approve verdict for spawn refuses the launch even with the knob on: the task stays
dispatched with its seat held, and the ledger records the byte-exact
spawn held <id> (policy spawn=approve) line - the task waits for the user (flip policy.spawn
to auto to let the next assignment launch, or settle it explicitly with
Complete/Fail/Interrupt).
The precedence is policy approve > knob: the knob can never widen an approve verdict, while a
knob that is off still refuses on its own and writes no line at all.
The block is one volatile object, so a policy flip is hot-editable without a remount, and a resolved
pack's policy section overrides the defaults per action (the wiring is the next refinement).
The ledger lines of the spawn (documented in SCHEME.md section 3): spawned <id> -> <child>,
spawn held <id> (policy spawn=approve), spawn skipped <id> (<reason>),
spawn failed <id> (<error>), requeued <id> (<agent> gone).
The plan
The spawn, the idle-slot automation, and the restart reconcile are implemented and smoke-arbitrated
(Source/Test/Spawn-And-Reconcile), and the policy gate and its precedence are arbitrated by
Source/Test/Policy-Defaults.
The durable queue store is the remaining piece: the reconcile takes the caller's persisted record
because the family has no storage domain yet (the wave-3 storage migration is its home).
A spawn skipped task keeps its seat until the orchestrator settles it - an honest gap, never a
silent drop.
License
CC0-1.0.
