docs: tool behaviour
This commit is contained in:
can1357
@@ -0,0 +1,224 @@
|
||||
# task
|
||||
|
||||
> Launch subagents for parallel, optionally isolated work.
|
||||
|
||||
## Source
|
||||
- Entry: `packages/coding-agent/src/task/index.ts`
|
||||
- Model-facing prompt: `packages/coding-agent/src/prompts/tools/task.md`
|
||||
- Key collaborators:
|
||||
- `packages/coding-agent/src/task/types.ts` — dynamic schema, progress/result types, output caps.
|
||||
- `packages/coding-agent/src/task/discovery.ts` — discover project/user/plugin/bundled agents.
|
||||
- `packages/coding-agent/src/task/agents.ts` — bundled agent definitions and frontmatter parsing.
|
||||
- `packages/coding-agent/src/task/executor.ts` — create child sessions, run subagents, collect output.
|
||||
- `packages/coding-agent/src/task/parallel.ts` — concurrency-limited scheduling and async semaphore.
|
||||
- `packages/coding-agent/src/task/isolation-backend.ts` — isolation backend resolution and platform fallback.
|
||||
- `packages/coding-agent/src/task/worktree.ts` — worktree / FUSE / ProjFS setup, patch capture, branch merge.
|
||||
- `packages/coding-agent/src/task/output-manager.ts` — session-scoped `agent://` id allocation.
|
||||
- `packages/coding-agent/src/task/simple-mode.ts` — `default` / `schema-free` / `independent` field gating.
|
||||
- `packages/coding-agent/src/internal-urls/agent-protocol.ts` — resolve `agent://<id>` to saved subagent output.
|
||||
- `packages/coding-agent/src/tools/index.ts` — tool registration and recursion-depth gating.
|
||||
- `packages/coding-agent/src/sdk.ts` — child-session router/tool wiring and per-subagent `AgentOutputManager`.
|
||||
- `docs/task-agent-discovery.md` — deeper discovery and precedence notes.
|
||||
- `docs/handoff-generation-pipeline.md` — session artifact/handoff persistence patterns used by the wider session layer.
|
||||
|
||||
## Inputs
|
||||
|
||||
### Default mode (`task.simple = "default"`)
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `agent` | `string` | Yes | Exact agent name for every task item. Resolved at execution time through `discoverAgents(...)`. |
|
||||
| `tasks` | `Array<{ id: string; description: string; assignment: string }>` | Yes | Batch of small, self-contained task items. `id` max length 48 in schema; duplicate ids are rejected case-insensitively at runtime. |
|
||||
| `context` | `string` | No | Shared background prepended to every subagent system prompt. Trimmed before use. |
|
||||
| `schema` | `string` | No | JSON-encoded JTD schema. Overrides agent/session output schema when this mode allows task-level schemas. |
|
||||
| `isolated` | `boolean` | No | Only present when the tool is created with isolation enabled. Requests isolated execution for the whole batch. |
|
||||
|
||||
`tasks[].description` is UI-only. `tasks[].assignment` is the actual per-task instruction.
|
||||
|
||||
### Schema-free mode (`task.simple = "schema-free"`)
|
||||
|
||||
Same as default, except `schema` is rejected by `validateTaskModeParams(...)` in `packages/coding-agent/src/task/index.ts`.
|
||||
|
||||
### Independent mode (`task.simple = "independent"`)
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| `agent` | `string` | Yes | Exact agent name. |
|
||||
| `tasks` | `Array<{ id: string; description: string; assignment: string }>` | Yes | Same item shape, but each `assignment` must carry all required background because shared `context` is disabled. |
|
||||
| `isolated` | `boolean` | No | Same conditional field as above. |
|
||||
|
||||
In this mode both `context` and `schema` are rejected.
|
||||
|
||||
## Outputs
|
||||
The tool returns one text block plus `details: TaskToolDetails`.
|
||||
|
||||
`details` fields:
|
||||
- `projectAgentsDir: string | null` — nearest discovered project `agents/` dir.
|
||||
- `results: SingleResult[]` — one entry per task in input order for synchronous execution; empty for async-launch responses.
|
||||
- `totalDurationMs: number`
|
||||
- `usage?: Usage` — sum of per-subagent assistant-message usage.
|
||||
- `outputPaths?: string[]` — written `.md` artifact paths for completed subagent outputs.
|
||||
- `progress?: AgentProgress[]` — live or final per-task progress snapshots.
|
||||
- `async?: { state: "running" | "completed" | "failed"; jobId: string; type: "task" }` — present for background execution updates/results.
|
||||
|
||||
`SingleResult` includes:
|
||||
- identity: `index`, `id`, `agent`, `agentSource`, `description`, optional `assignment`
|
||||
- status: `exitCode`, optional `error`, optional `aborted`, optional `abortReason`
|
||||
- output: `output`, `stderr`, `truncated`, `durationMs`, `tokens`
|
||||
- artifact metadata: `outputPath?`, `patchPath?`, `branchName?`, `nestedPatches?`, `outputMeta?`
|
||||
- extracted tool data: `extractedToolData?` from registered subprocess tool handlers such as `yield` and `report_finding`
|
||||
|
||||
Artifacts and side channels:
|
||||
- Every subagent with an artifacts dir writes `<id>.md`; `agent://<id>` resolves to that file.
|
||||
- If the output file is JSON, `agent://<id>/<path>` and `agent://<id>?q=<query>` perform JSON extraction in `packages/coding-agent/src/internal-urls/agent-protocol.ts`.
|
||||
- When the parent session persists artifacts, each subagent also gets `<id>.jsonl` session history.
|
||||
- Isolated patch mode writes `<id>.patch` per successful task before merge.
|
||||
- Async mode returns immediately after job registration, then emits `onUpdate(...)` progress snapshots and later hands completion to the session async-job pipeline.
|
||||
|
||||
## Flow
|
||||
1. `TaskTool.create(...)` in `packages/coding-agent/src/task/index.ts` calls `discoverAgents(session.cwd)` once to build the dynamic prompt description from current agents and `task.simple` capabilities.
|
||||
2. `execute(...)` validates mode-gated fields with `validateTaskModeParams(...)`.
|
||||
3. It decides async vs sync:
|
||||
- sync when `async.enabled` is false
|
||||
- sync when the selected cached agent has `blocking === true`
|
||||
- sync when `tasks.length === 0`
|
||||
- otherwise async job scheduling
|
||||
4. Async path:
|
||||
- allocate unique output ids with `AgentOutputManager.allocateBatch(...)`
|
||||
- create one async job per task through `session.asyncJobManager.register(...)`
|
||||
- limit concurrent job bodies with `Semaphore(task.maxConcurrency)` from `packages/coding-agent/src/task/parallel.ts`
|
||||
- each job body calls `#executeSync(...)` with a one-task batch and the preallocated id
|
||||
- `onUpdate(...)` emits aggregate `progress` snapshots and `details.async`
|
||||
5. Sync path (`#executeSync(...)`) rediscovers agents from disk via `discoverAgents(...)`, so runtime resolution can differ from the earlier prompt description.
|
||||
6. It resolves the requested agent with `getAgent(...)`, rejects unknown or disabled agents, and enforces parent spawn policy plus `PI_BLOCKED_AGENT` self-recursion prevention.
|
||||
7. It derives the effective output schema in priority order: task call `schema` (if allowed) → agent frontmatter `output` → inherited parent session schema.
|
||||
8. It validates task ids: missing ids and case-insensitive duplicates are immediate errors.
|
||||
9. If `isolated` was requested, it requires a git repo (`getRepoRoot(...)` / `captureBaseline(...)`) and resolves the actual backend through `resolveIsolationBackendForTaskExecution(...)`.
|
||||
10. It chooses an artifacts dir from the parent session when available, otherwise a temp dir, and writes `context.md` there when `session.getCompactContext?.()` returns content.
|
||||
11. It allocates unique ids again if the caller did not preallocate them, then builds `tasksWithUniqueIds`.
|
||||
12. For each task, it seeds an `AgentProgress` entry and runs `runTask(...)` through `mapWithConcurrencyLimit(...)` using `task.maxConcurrency`.
|
||||
13. Non-isolated `runTask(...)` calls `runSubprocess(...)` directly with parent cwd.
|
||||
14. Isolated `runTask(...)`:
|
||||
- creates an isolation workspace (`ensureWorktree(...)`, `ensureFuseOverlay(...)`, or `ensureProjfsOverlay(...)`)
|
||||
- applies the captured baseline for worktrees
|
||||
- runs `runSubprocess(...)` inside that workspace
|
||||
- on success, either commits to a per-task branch (`mergeMode === "branch"`) or captures a patch with `captureDeltaPatch(...)`
|
||||
- always cleans up the isolation workspace/backend
|
||||
15. `runSubprocess(...)` in `packages/coding-agent/src/task/executor.ts` creates a child agent session with:
|
||||
- isolated settings snapshot via `Settings.isolated(...)`, forcing `async.enabled = false` and `bash.autoBackground.enabled = false`
|
||||
- child `agentId` / `parentTaskPrefix` equal to the allocated task id
|
||||
- child internal URL router and `AgentOutputManager` from `packages/coding-agent/src/sdk.ts`
|
||||
- the shared `context`, optional `context.md` reference, optional isolation worktree path, output schema, and IRC peer roster in the system prompt template
|
||||
16. Child tool availability is derived from the agent definition plus runtime guards:
|
||||
- explicit `agent.tools` if provided
|
||||
- auto-add `task` when the agent has `spawns` and recursion depth allows it
|
||||
- remove `task` at or past `task.maxRecursionDepth`
|
||||
- expand `exec` to `eval` and `bash`
|
||||
- strip parent-owned `todo_write` after session creation
|
||||
17. `runSubprocess(...)` subscribes to child agent events, coalesces progress updates every 150 ms, forwards lifecycle/progress events on the parent event bus, and extracts tool data through `subprocessToolRegistry`.
|
||||
18. The child must finish through the hidden `yield` tool. If it does not, `runSubprocess(...)` sends up to 3 reminder prompts; the last reminder forces `toolChoice = yield` when supported.
|
||||
19. Finalization uses `finalizeSubprocessOutput(...)` to reconcile raw assistant text, `yield` payloads, structured schemas, `report_finding` data, and abort states. Output is truncated with `MAX_OUTPUT_BYTES` / `MAX_OUTPUT_LINES` before returning to the parent, but the full raw output is still written to `<id>.md`.
|
||||
20. After all sync tasks finish, `#executeSync(...)` aggregates usage, collects artifact paths, and if isolation was used merges results back:
|
||||
- branch mode: cherry-pick per-task branches with `mergeTaskBranches(...)`, then delete merged branches with `cleanupTaskBranches(...)`
|
||||
- patch mode: combine non-empty patch artifacts, dry-check with `git.patch.canApplyText(...)`, then apply or leave manual artifacts
|
||||
- nested repo patches are applied separately with `applyNestedPatches(...)`
|
||||
21. The final text summary is rendered from `packages/coding-agent/src/prompts/tools/task-summary.md` and includes `agent://<id>` handles for outputs that exist.
|
||||
|
||||
## Modes / Variants
|
||||
- Execution mode
|
||||
- Sync inline execution — default path.
|
||||
- Async background execution — one async job per task item when `async.enabled` is on and the chosen agent is not marked `blocking`.
|
||||
- Simple mode
|
||||
- `default` — accepts shared `context` and per-call `schema`.
|
||||
- `schema-free` — accepts `context`, rejects `schema`.
|
||||
- `independent` — rejects `context` and `schema`; each assignment stands alone.
|
||||
- Isolation backend
|
||||
- `none` — no isolation.
|
||||
- `worktree` — detached git worktree plus baseline replay.
|
||||
- `fuse-overlay` — Unix FUSE overlay mount.
|
||||
- `fuse-projfs` — Windows ProjFS overlay.
|
||||
- Isolation merge strategy
|
||||
- Patch mode — capture/apply root patches, keep patch artifacts when application fails.
|
||||
- Branch mode — commit each task onto `omp/task/<id>` branch, cherry-pick into parent, preserve failed branches for manual resolution.
|
||||
- Agent source
|
||||
- Project custom agents — nearest project config/plugin agent directories, first by source-family precedence.
|
||||
- User custom agents — user config/plugin agent directories after project dirs of the same source family.
|
||||
- Bundled agents — appended last from `packages/coding-agent/src/task/agents.ts`.
|
||||
- Bundled agent types
|
||||
- `explore` — read-only scout with structured handoff output.
|
||||
- `plan` — architecture/planning agent; may spawn `explore`.
|
||||
- `designer` — UI/UX specialist.
|
||||
- `reviewer` — review agent with `report_finding` extraction.
|
||||
- `task` — general-purpose worker with full capabilities.
|
||||
- `quick_task` — low-reasoning mechanical worker using the same task prompt body.
|
||||
- `librarian` — source-grounded external API/library researcher.
|
||||
|
||||
## Side Effects
|
||||
- Filesystem
|
||||
- Writes `context.md`, `<id>.jsonl`, and `<id>.md` under the session artifacts dir or a temp task dir.
|
||||
- In isolated patch mode writes `<id>.patch` artifacts.
|
||||
- Creates/removes worktrees or overlay mount directories.
|
||||
- In branch mode creates temporary worktrees and task branches.
|
||||
- Network
|
||||
- Child sessions may use whichever networked tools/models their active tool set permits.
|
||||
- MCP proxy tools can call existing parent MCP connections with a 60_000 ms timeout.
|
||||
- Subprocesses / native bindings
|
||||
- `fuse-overlayfs` and `fusermount`/`fusermount3` for FUSE isolation.
|
||||
- ProjFS native bindings via `@oh-my-pi/pi-natives` on Windows.
|
||||
- Git operations for baseline capture, patch apply, worktrees, branches, stash, cherry-pick, commits.
|
||||
- Session state (transcript, memory, jobs, checkpoints, registries)
|
||||
- Creates child `AgentSession` instances with isolated settings snapshots.
|
||||
- Registers async jobs in `session.asyncJobManager` for background task mode.
|
||||
- Emits `task:subagent:event`, `task:subagent:progress`, and `task:subagent:lifecycle` on the parent event bus.
|
||||
- Allocates session-scoped output ids through `AgentOutputManager` so `agent://` remains unique across invocations and resumes.
|
||||
- Shares the parent `local://` root with subagents by passing `localProtocolOptions` through `createAgentSession(...)`.
|
||||
- User-visible prompts / interactive UI
|
||||
- Async mode streams aggregate progress updates.
|
||||
- Missing-`yield` recovery sends up to three internal reminder prompts to the child session.
|
||||
- Final summaries include `<system-notification>` blocks for isolation fallbacks or merge failures.
|
||||
- Background work / cancellation
|
||||
- Parent abort stops scheduling new work, aborts active child sessions, and marks unscheduled tasks as skipped.
|
||||
- Async jobs keep their own cancellation via `AsyncJobManager`.
|
||||
|
||||
## Limits & Caps
|
||||
- Per-subagent output truncation: `MAX_OUTPUT_BYTES = 500_000` and `MAX_OUTPUT_LINES = 5000` in `packages/coding-agent/src/task/types.ts`. Full raw output is still written to `<id>.md` before truncation is returned to the caller.
|
||||
- Progress coalescing in child execution: `PROGRESS_COALESCE_MS = 150` in `packages/coding-agent/src/task/executor.ts`.
|
||||
- Recent output tail for progress: `RECENT_OUTPUT_TAIL_BYTES = 8 * 1024` and `recentOutput` keeps the last 8 non-empty lines in `packages/coding-agent/src/task/executor.ts`.
|
||||
- Missing-`yield` reminder retries: `MAX_YIELD_RETRIES = 3` in `packages/coding-agent/src/task/executor.ts`.
|
||||
- MCP proxy timeout: `MCP_CALL_TIMEOUT_MS = 60_000` in `packages/coding-agent/src/task/executor.ts`.
|
||||
- Task id schema cap: `tasks[].id` `maxLength: 48` in `packages/coding-agent/src/task/types.ts`.
|
||||
- Prompt text says ids should be `≤32` chars, but the runtime schema allows 48; this mismatch is real.
|
||||
- Async/full sync parallelism both use `task.maxConcurrency` from settings:
|
||||
- sync path: `mapWithConcurrencyLimit(...)`
|
||||
- async path: `Semaphore(...)` around job bodies
|
||||
- Recursion depth gate: `task.maxRecursionDepth` from settings; `packages/coding-agent/src/tools/index.ts` hides the `task` tool at or beyond the limit, and `runSubprocess(...)` also strips child `task` access at max depth.
|
||||
- Final inline summary preview per task uses `fullOutputThreshold = 5000` chars in `packages/coding-agent/src/task/index.ts`; longer outputs are summarized while `agent://<id>` points to the full artifact.
|
||||
|
||||
## Errors
|
||||
- Most validation failures are returned as normal tool text with empty `results`, not thrown:
|
||||
- invalid simple-mode fields
|
||||
- unknown/disabled agent
|
||||
- missing tasks
|
||||
- missing/duplicate task ids
|
||||
- spawn-policy denial
|
||||
- requesting `isolated` while isolation mode is `none`
|
||||
- Isolated execution without a git repo returns `Isolated task execution requires a git repository. ...`.
|
||||
- Backend resolution can return a hard error (`ProjFS isolation initialization failed...`) or a non-fatal warning with fallback to `worktree`.
|
||||
- `mapWithConcurrencyLimit(...)` fails fast on non-abort worker exceptions; already completed results are preserved only in the thrown path’s local state, not surfaced unless the caller catches and converts them.
|
||||
- Child-session failures surface as `SingleResult.exitCode = 1` with `stderr`/`error` populated.
|
||||
- If the child omits `yield`, `finalizeSubprocessOutput(...)` injects warnings such as `SYSTEM WARNING: Subagent exited without calling yield tool after 3 reminders.`
|
||||
- Async scheduling failures are accumulated per task; if no jobs start, the tool returns `Failed to start background task jobs: ...`.
|
||||
- `agent://<id>` resolution errors are model-visible when another tool reads them: no session, no artifacts dir, missing id, conflicting extraction syntax, or invalid JSON for extraction.
|
||||
|
||||
## Notes
|
||||
- Agent discovery precedence is first-wins by exact name: project dirs before user dirs within a source family, plugin agent dirs after config dirs, bundled agents last. See `packages/coding-agent/src/task/discovery.ts` and `docs/task-agent-discovery.md`.
|
||||
- `TaskTool.create(...)` caches discovered agents only for description rendering and the async blocking-agent decision. `#executeSync(...)` rediscovers agents each call.
|
||||
- Custom agent frontmatter can override bundled agents by name. Bundled definitions are embedded at build time in `packages/coding-agent/src/task/agents.ts`.
|
||||
- Child sessions do not inherit conversation history automatically. The only built-in carry-over is shared `context`, optional `context.md`, workspace tree/skills/context files, and shared `local://` root.
|
||||
- `Settings.isolated(...)` gives each child a session-isolated settings snapshot; tool enablement is recomputed inside the child session rather than sharing mutable parent tool state.
|
||||
- When the parent passes `mcpManager`, child sessions disable standalone MCP discovery and instead get proxy tools that reuse the parent connections.
|
||||
- Plan mode mutates an `effectiveAgent` with a read-only tool subset and plan-mode prompt text, but `runSubprocess(...)` is still invoked with `agent` rather than `effectiveAgent`. Model/thinking/schema overrides use the effective agent; prompt/tool/spawn restrictions do not fully flow through this call path.
|
||||
- Branch-mode merge temporarily stashes the parent repo before cherry-picking task branches. A stash-pop conflict is treated as merge failure and leaves recovery state behind.
|
||||
- Patch-mode only applies combined root patches if every successful task produced a patch and `git.patch.canApplyText(...)` succeeds.
|
||||
- Nested git repos are handled separately from the root repo. They are copied into isolated worktrees, diffed independently, and merged later with `applyNestedPatches(...)` because parent git cannot track their file-level changes.
|
||||
- `agent://` ids are numeric-prefixed (`0-Task`, `1-Task`, nested like `0-Parent.0-Child`) by `AgentOutputManager`; this is what prevents artifact collisions across repeated or nested task invocations.
|
||||
Reference in New Issue
Block a user