Agent Task
@maphew/agent-taskv2026.10.22.1
01README
Headless agent dispatch as a swamp behavior: filter the bd ready queue into a typed manifest, branch a target checkout and run one agent on a task, sweep every candidate under a single behavior lock, or run a single agent with no git work at all (run). Other extensions call run through runModel so there is one authority on how a headless agent is launched. Replaces the .kilo/agents ready-queue.sh / run-task.sh / bd-sweep.sh shell cluster.
02Behaviors
@maphew/agent-taskv2026.10.22.1src/agent_task.ts
fn filterQueue(workdirMap: preprocess, maxItems?: number, base?: string, bdCommand?: string, bdDir?: string, gitCommand?: string)
Filter the bd ready queue into a typed dispatch manifest, dropping blocked, non-implementation, and branch-covered issues
| Argument | Type | Description |
|---|---|---|
| workdirMap | preprocess | Map of issue-id prefix to local checkout path; issues with no mapping are reported, not dispatched |
| maxItems? | number | Optional cap on candidates (0 = unlimited) |
| base? | string | Base branch for new branches |
| bdCommand? | string | Path to the beads CLI |
| bdDir? | string | Project directory containing a .beads/ database |
| gitCommand? | string | Path to the git CLI |
fn dispatch(workdir: string, branch: string, task: string, mainBranch?: string, issueId?: string, sandboxRoot?: string, keepSandbox?: boolean, gitCommand?: string)
Branch a target checkout and run one headless agent on a task
| Argument | Type | Description |
|---|---|---|
| workdir | string | Local checkout the agent runs in |
| branch | string | Feature branch to create |
| task | string | Task prompt for the agent |
| mainBranch? | string | Base branch to branch from |
| issueId? | string | Bead id the task belongs to, for result naming and reporting |
| sandboxRoot? | string | Create a git worktree per dispatch under this root instead of running in the checkout; empty keeps the direct-checkout behaviour |
| keepSandbox? | boolean | Keep the sandbox worktree even after a successful run (failed runs are always kept) |
| gitCommand? | string | Path to the git CLI |
fn sweep(candidates?: array, sandboxRoot?: string, keepSandbox?: boolean, gitCommand?: string)
Dispatch every candidate in a manifest serially under one behavior lock
| Argument | Type | Description |
|---|---|---|
| candidates? | array | Candidates from filterQueue (wire from data.latest(...).attributes.candidates) |
| sandboxRoot? | string | Create a git worktree per candidate under this root; empty uses each candidate's mapped checkout |
| keepSandbox? | boolean | Keep sandbox worktrees even after a successful run (failed runs are always kept) |
| gitCommand? | string | Path to the git CLI |
fn run(prompt: string, systemPrompt?: string, workdir: string, actor?: string)
Run one headless agent on a prompt in a checkout, and nothing else: no branching, no source control, no plan. The runner primitive other extensions call through `runModel` when they own their own git workflow.
| Argument | Type | Description |
|---|---|---|
| prompt | string | The task prompt handed to the agent |
| systemPrompt? | string | Instruction prepended to the task prompt (the run contract); empty means the task prompt alone |
| workdir | string | Checkout the agent runs in |
| actor? | string | BEADS_ACTOR exported to the agent. Empty means no actor is exported, which is right for callers that do their own bookkeeping; dispatch/sweep derive one per branch. |
fn sandboxes(sandboxRoot: string, base?: string, gitCommand?: string, ghCommand?: string)
List the worktrees under a sandbox root with dirty state, commits ahead, and PR state; read-only
| Argument | Type | Description |
|---|---|---|
| sandboxRoot | string | Directory that holds sandbox worktrees, one per dispatch |
| base? | string | Base branch to compare against; empty detects origin/HEAD, falling back to main |
| gitCommand? | string | Path to the git CLI |
| ghCommand? | string | Path to the GitHub CLI, used to read PR state; a missing gh is not an error |
fn pruneSandboxes(sandboxRoot: string, dryRun?: boolean, base?: string, gitCommand?: string, ghCommand?: string)
Remove clean sandbox worktrees whose branch is merged or whose PR is closed/merged, then git worktree prune; dry-run by default
| Argument | Type | Description |
|---|---|---|
| sandboxRoot | string | Directory that holds sandbox worktrees, one per dispatch |
| dryRun? | boolean | Report what would be removed without removing anything |
| base? | string | Base branch to compare against; empty detects origin/HEAD, falling back to main |
| gitCommand? | string | Path to the git CLI |
| ghCommand? | string | Path to the GitHub CLI, used to read PR state; a missing gh is not an error |
Resources
run(30d)— Outcome of one raw agent invocation (`run`)
manifest(30d)— Filtered bd ready queue of dispatch candidates
dispatch(30d)— Outcome of one headless-agent dispatch
sweep(30d)— Aggregate outcome of a fan-out agent sweep
sandboxes(30d)— Read-only listing of worktrees under a sandbox root
prune(30d)— Outcome of a sandbox prune (dry-run by default)
Files
report(text/markdown)— Markdown dispatch report
03Previous Versions
2026.10.18.1MIT
Modified 1 behaviors
2026.10.15.1MIT
Initial release: filterQueue/dispatch/sweep extracted from the .kilo/agents ready-queue.sh, run-task.sh, and bd-sweep.sh shell dispatch cluster.
04Stats
A
100 / 100
Downloads
5
Archive size
28.6 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License2/2earned
- Verified public repository2/2earned
deno-command1 accepted
Spawns a subprocess with Deno.Command().
- models/src/agent_task.ts:814 — git, bd, and the agent CLIs are the dispatch contract.
06Platforms
07Labels