feat(coding-agent): rewrote the task tool to spawn one persistent subagent per call
The task tool now takes a single { agent, assignment, description, ... } and always runs the subagent in the background — the batch tasks[] array and shared context parameter are gone. Fan-out is parallel task calls; shared background flows through a '/Users/can/.omp/agent/sessions/-Projects-.tree-pi-commit/2026-06-10T15-36-32-782Z_019eb22d-970e-7000-8964-72c98becf3e8/local' file referenced in each assignment.\n\nIntroduces a persistent subagent lifecycle: finished subagents stay live as idle, the lifecycle manager parks them to disk after task.agentIdleTtlMs (default 7 minutes; 0 keeps them live until exit), and they revive automatically when prompted from the Agent Hub, messaged on IRC, or resumed via task. New task(resume: "<id>") revives an idle or parked subagent and runs a follow-up assignment in its existing session.\n\nAdds soft request budgets (explore/quick_task 40, others 90, configurable via task.softRequestBudget, 0 disables): crossing the budget injects a one-time wrap-up steer into the child; crossing 1.5× aborts the run gracefully. Cancelled/aborted subagent salvage replaces the old (no output) with the child's last activity snippet plus request/token stats; SingleResult tracks a per-child requests counter (assistant message_end events) used to sort agent lists in runtime-ascending order in both the live progress view (finished agents above pending/running) and the finalized result view, so rows no longer reshuffle on finalize. Adds a task gallery fixture variant for the resume path (renderer key separated from fixture key).\n\nAll task tests are reshaped around the single-call contract; tests for the discarded shared-context flow are removed, and new task-guards/task-resume/task-schema tests pin the new contract surface.
This commit is contained in:
can1357
+112
-166
@@ -1,6 +1,6 @@
|
||||
# task
|
||||
|
||||
> Launch subagents for parallel, optionally isolated work.
|
||||
> Spawn one subagent per call to work in the background, or resume an existing one.
|
||||
|
||||
## Source
|
||||
- Entry: `packages/coding-agent/src/task/index.ts`
|
||||
@@ -9,217 +9,163 @@
|
||||
- `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/executor.ts` — create child sessions, run/resume subagents, collect output, hand finished sessions to the lifecycle manager.
|
||||
- `packages/coding-agent/src/registry/agent-lifecycle.ts` — idle-TTL parking and revival of finished subagents.
|
||||
- `packages/coding-agent/src/registry/agent-registry.ts` — process-global agent directory (`running | idle | parked | aborted`).
|
||||
- `packages/coding-agent/src/async/job-manager.ts` — background job registration, progress, and result delivery.
|
||||
- `packages/coding-agent/src/task/parallel.ts` — `Semaphore` used for the session-scoped concurrency bound.
|
||||
- `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/task/name-generator.ts` — default AdjectiveNoun agent ids.
|
||||
- `packages/coding-agent/src/task/simple-mode.ts` — `default` / `schema-free` / `independent` schema gating.
|
||||
- `packages/coding-agent/src/internal-urls/agent-protocol.ts` — resolve `agent://<id>` to saved subagent output.
|
||||
- `packages/coding-agent/src/internal-urls/history-protocol.ts` — resolve `history://<id>` to a concise transcript.
|
||||
- `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"`)
|
||||
One call spawns (or resumes) exactly one subagent. There is no batch parameter and no shared `context` parameter — shared background goes into a `local://` file (e.g. `local://ctx.md`) that each assignment references; subagents share the parent's `local://` root.
|
||||
|
||||
| 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. |
|
||||
| `agent` | `string` | Conditional | Agent type to spawn. Required unless `resume` is set; providing both is a validation error. |
|
||||
| `resume` | `string` | Conditional | Existing agent id — revive the agent if parked and run a follow-up assignment in its existing session. Cannot be combined with `agent` or `isolated`. |
|
||||
| `id` | `string` | No | Stable agent id, schema max length 48. Defaults to a generated AdjectiveNoun name. Uniquified per session by `AgentOutputManager`. |
|
||||
| `description` | `string` | No | UI label only; the subagent never sees it. |
|
||||
| `assignment` | `string` | Yes | The work — complete, self-contained instructions. Empty-after-trim is rejected. |
|
||||
| `schema` | `string` | No | JSON-encoded JTD schema for the expected `yield` payload. Field exists only when `task.simple = "default"`. |
|
||||
| `isolated` | `boolean` | No | Run in an isolated workspace and return patches. Field exists only when `task.isolation.mode` is not `none`. Isolated agents are NOT resumable. |
|
||||
|
||||
`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.
|
||||
Simple-mode gating (`task.simple`, one axis): `default` accepts the per-call `schema` override; `schema-free` and `independent` reject it (`validateTaskModeParams(...)`). `independent` additionally renders the subagent user prompt with the independent-mode flag. Agent frontmatter and inherited session schemas work in every mode.
|
||||
|
||||
## 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.
|
||||
Immediate (async) response — the normal case:
|
||||
- `content`: `` Spawned agent `<id>` (job `<jobId>`). The result will be delivered when it yields. ... `` (or `Resumed agent ...`), plus a coordination hint (`irc` DM when enabled, otherwise `job`).
|
||||
- `details`: `{ projectAgentsDir: null, results: [], totalDurationMs: 0, progress: [<seeded AgentProgress>], async: { state: "running", jobId, type: "task" } }`.
|
||||
- Live progress keeps streaming into the same tool block via `onUpdate(...)`; the final result arrives later as an async-result injection into the parent conversation. The delivery text appends a resume hint: `` <id> is now idle — task(resume:"<id>") to continue it, transcript at history://<id> `` (aborted variant points at the transcript only).
|
||||
|
||||
Settled (sync-fallback or job-body) response:
|
||||
- `content`: summary rendered from `packages/coding-agent/src/prompts/tools/task-summary.md` with a preview capped at 5000 chars; `agent://<id>` holds the full output.
|
||||
- `details.results`: at most one `SingleResult`; `usage`, `outputPaths` populated.
|
||||
|
||||
`SingleResult` includes:
|
||||
- identity: `index`, `id`, `agent`, `agentSource`, `description`, optional `assignment`
|
||||
- status: `exitCode`, optional `error`, optional `aborted`, optional `abortReason`
|
||||
- output: `output`, `stderr`, `truncated`, `durationMs`, `tokens`
|
||||
- status: `exitCode`, optional `error`, optional `aborted`, optional `abortReason`, optional `retryFailure`
|
||||
- output: `output`, `stderr`, `truncated`, `durationMs`, `tokens`, `requests`, optional `contextTokens`/`contextWindow`
|
||||
- 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.
|
||||
- Every subagent with an artifacts dir writes `<id>.md`; `agent://<id>` resolves to that file. Resumes overwrite it per assignment.
|
||||
- If the output file is JSON, `agent://<id>/<path>` and `agent://<id>?q=<query>` perform JSON extraction.
|
||||
- Each subagent gets `<id>.jsonl` session history when the parent persists artifacts; `history://<id>` renders it as a concise transcript (works for live and parked agents).
|
||||
- Isolated patch mode writes `<id>.patch` before merge.
|
||||
|
||||
## 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` 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.
|
||||
1. `TaskTool.create(...)` discovers agents once per cwd through a process-level memo (`discoverAgentsForCreate`) to render the dynamic prompt description.
|
||||
2. `execute(...)` repairs raw params (`repairTaskParams`), then validates: schema gating per `task.simple`, `agent` XOR `resume`, `resume` excludes `isolated`, non-empty `assignment`.
|
||||
3. Sync fallback only when the session has no `AsyncJobManager` (orphaned host) or the selected agent definition declares `blocking: true`; the call then runs `#executeSync(...)` inline under the session-scoped semaphore.
|
||||
4. Otherwise execution is always async:
|
||||
- the agent id is resolved up front — `resume` must name a registered agent (else `ToolError` pointing at `irc` op:"list" and `history://<id>`); spawns allocate via `AgentOutputManager.allocate(params.id || generateTaskName())`;
|
||||
- one `type: "task"` job is registered with `session.asyncJobManager` (`id` = agent id, `queued: true`, `ownerId` = caller agent id) and the tool returns immediately;
|
||||
- the job body acquires the session-scoped `Semaphore` (one per `TaskTool` instance, sized from `task.maxConcurrency` at first use), marks the job running, runs `#executeSync(...)`, and reports progress through `buildAsyncDetails`/`onUpdate`;
|
||||
- a failed or aborted run throws `TaskJobError` so the job lands `failed`, but the agent itself stays registered and interrogable.
|
||||
5. `#executeSync(...)` dispatches: `resume` → `#executeResume(...)`, else `#runSpawn(...)`.
|
||||
6. Resume path (`#executeResume`):
|
||||
- `AgentLifecycleManager.global().ensureLive(resumeId)` returns the live session, reviving a parked one from its session JSONL; unknown ids or parked-without-reviver throw a `ToolError`;
|
||||
- `resumeSubprocess(...)` in `packages/coding-agent/src/task/executor.ts` injects the rendered follow-up through the session's normal prompt path and drives it through the same monitor/yield/finalize pipeline as a spawn;
|
||||
- the session is never disposed here — registry status settles back to `idle` (even on failure/abort) and the lifecycle manager re-arms the idle TTL.
|
||||
7. Spawn path (`#runSpawn`) rediscovers agents from disk, so runtime resolution can differ from the create-time description.
|
||||
8. It resolves the requested agent, rejects unknown or settings-disabled agents, and enforces parent spawn policy plus `PI_BLOCKED_AGENT` self-recursion prevention.
|
||||
9. Output schema priority: task call `schema` (when `task.simple` allows) → agent frontmatter `output` → inherited parent session schema.
|
||||
10. Plan mode swaps in an `effectiveAgent` with a read-only tool subset and plan-mode prompt; `runSubprocess(...)` receives the effective agent.
|
||||
11. If `isolated`, it requires a git repo (`getRepoRoot(...)` / `captureBaseline(...)`) and resolves the backend through isolation-backend resolution with platform fallback.
|
||||
12. Artifacts dir comes from the parent session file when available, otherwise a temp dir. When the session is executing an approved plan, the plan reference is handed to the subagent.
|
||||
13. Non-isolated spawns call `runSubprocess(...)` directly with parent cwd; isolated spawns run inside the isolation workspace, then commit to a branch (`mergeMode === "branch"`) or capture a patch, and always clean up the workspace.
|
||||
14. `runSubprocess(...)` creates a child agent session with an isolated settings snapshot (forcing `async.enabled = false` and `bash.autoBackground.enabled = false` — subagents are internally synchronous), child `agentId` equal to the allocated id, child internal URL router/`AgentOutputManager`, output schema, and the IRC peer roster in the system prompt.
|
||||
15. Child tool availability: explicit `agent.tools` if provided; auto-add `task` when the agent has `spawns` and depth allows; strip `task` at `task.maxRecursionDepth`; expand `exec` to `eval` + `bash`; strip parent-owned `todo`.
|
||||
16. The child must finish through the hidden `yield` tool; up to 3 reminder prompts, the last forcing `toolChoice = yield` when supported. `finalizeSubprocessOutput(...)` reconciles raw text, `yield` payloads, structured schemas, `report_finding` data, and abort states.
|
||||
17. End-of-run lifecycle (keep-alive, in `runSubprocess`'s finalizer):
|
||||
- hard abort (caller signal / wall-clock / budget) → registry status `aborted`, session disposed — terminal;
|
||||
- isolated run → status `parked` without a reviver (workspace is merged + cleaned, so the session is not resumable; transcript stays readable via `history://`), then session disposed and detached;
|
||||
- everything else (success and failure alike) → status `idle` with the live session attached, and `AgentLifecycleManager.global().adopt(id, { idleTtlMs, revive })` arms the park timer. The reviver reopens the session JSONL (park closed the writer, so the single-writer lock is taken cleanly).
|
||||
18. Lifecycle thereafter: `idle` agents are parked after `task.agentIdleTtlMs` (session disposed; `AgentRef` + session file retained); messaging (`irc`), `task(resume:)`, or the Agent Hub revives them back to `idle`. `"Main"` is never parked.
|
||||
|
||||
## 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.
|
||||
- `oracle` — senior-engineer implementation/debugging/general consultation agent.
|
||||
- Always-async background job — default; spawn and resume both go through `AsyncJobManager`.
|
||||
- Sync inline fallback — only when no job manager exists or the agent definition has `blocking: true`.
|
||||
- Spawn vs resume
|
||||
- `agent: "<type>"` — fresh subagent with a new (or caller-provided) id.
|
||||
- `resume: "<id>"` — follow-up assignment in an existing session; revives a parked agent first. Transcript accretes; `agent://<id>` is overwritten per assignment.
|
||||
- Simple mode (`task.simple`)
|
||||
- `default` — accepts per-call `schema`.
|
||||
- `schema-free` / `independent` — reject `schema`; `independent` also flags the subagent user prompt as independent-mode.
|
||||
- Isolation backend: `none`, `worktree`, `fuse-overlay`, `fuse-projfs`.
|
||||
- Isolation merge strategy: patch mode (capture/apply root patches) or branch mode (commit to `omp/task/<id>`, cherry-pick into parent).
|
||||
- Agent source precedence: project custom agents, then user custom agents, then bundled agents (`explore`, `plan`, `designer`, `reviewer`, `task`, `quick_task`, `librarian`, `oracle`).
|
||||
|
||||
## 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.
|
||||
- Writes `<id>.jsonl` and `<id>.md` under the session artifacts dir or a temp task dir; isolated patch mode writes `<id>.patch`.
|
||||
- Creates/removes worktrees or overlay mount directories; 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.
|
||||
- `fuse-overlayfs` and `fusermount`/`fusermount3` for FUSE isolation; ProjFS native bindings 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.
|
||||
- Creates child `AgentSession` instances with isolated settings snapshots; finished sessions stay registered in the process-global `AgentRegistry` as `idle`/`parked` until process teardown or explicit release.
|
||||
- Registers one async job per call in `session.asyncJobManager`; completion is injected into the parent as an async-result message.
|
||||
- Arms idle-TTL timers in `AgentLifecycleManager` (unref'd; they never hold the process open).
|
||||
- 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.
|
||||
- Allocates session-scoped output ids through `AgentOutputManager` so `agent://` stays unique across invocations and resumes.
|
||||
- Shares the parent `local://` root and `ArtifactManager` with subagents.
|
||||
- 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`.
|
||||
- `job cancel` (or parent tool-call abort) cancels the job; a hard-aborted run lands `aborted` and is torn down.
|
||||
- Missing-`yield` recovery sends up to three internal reminder prompts to the child session.
|
||||
|
||||
## 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.
|
||||
- Concurrency: one session-scoped `Semaphore` sized from `task.maxConcurrency` at first use (later setting changes do not resize it) bounds concurrent subagents across parallel `task` calls — both async job bodies and the sync fallback acquire it.
|
||||
- Idle TTL: `task.agentIdleTtlMs`, default `420_000` ms (7 min); `<= 0` disables parking and keeps idle sessions live until exit.
|
||||
- Per-subagent output truncation: `MAX_OUTPUT_BYTES = 500_000` and `MAX_OUTPUT_LINES = 5000` in `packages/coding-agent/src/task/types.ts` (overridable via `PI_TASK_MAX_OUTPUT_BYTES` / `PI_TASK_MAX_OUTPUT_LINES`). Full raw output is still written to `<id>.md`.
|
||||
- Progress coalescing: `PROGRESS_COALESCE_MS = 150`; recent-output tail: `RECENT_OUTPUT_TAIL_BYTES = 8 * 1024` (last 8 non-empty lines).
|
||||
- Missing-`yield` reminder retries: `MAX_YIELD_RETRIES = 3`; MCP proxy timeout: `MCP_CALL_TIMEOUT_MS = 60_000` — both in `packages/coding-agent/src/task/executor.ts`.
|
||||
- Agent id schema cap: `id` `maxLength: 48` in `packages/coding-agent/src/task/types.ts`. Prompt text says ids should be `≤32` chars; this mismatch is real.
|
||||
- Soft request budget (`task.softRequestBudget`) and wall clock (`task.maxRuntimeMs`) apply to spawns and resumes alike.
|
||||
- Recursion depth gate: `task.maxRecursionDepth`; `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 uses `fullOutputThreshold = 5000` chars in `packages/coding-agent/src/task/index.ts`; `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.
|
||||
- Parameter validation failures are returned as normal tool text with empty `results`:
|
||||
- `schema` outside `task.simple = "default"`
|
||||
- both or neither of `agent` / `resume`
|
||||
- `resume` combined with `isolated`
|
||||
- missing/empty `assignment`
|
||||
- unknown or settings-disabled agent, spawn-policy denial, requesting `isolated` while isolation mode is `none`
|
||||
- `resume` of an id not in the registry throws a `ToolError` naming `irc` op:"list" and `history://<id>`.
|
||||
- `ensureLive(...)` failures (agent parked without a reviver — e.g. an isolated run — or torn down) surface as `` Cannot resume "<id>": ... `` `ToolError`s.
|
||||
- Isolated execution without a git repo returns `Isolated task execution requires a git repository. ...`; backend resolution can hard-error (ProjFS init) or warn and fall back to `worktree`.
|
||||
- Job registration failure returns `Failed to start background task job: ...`.
|
||||
- Child failures surface as `SingleResult.exitCode = 1` with `stderr`/`error` populated; the async job is marked failed but the delivery text still carries the output plus a resume/transcript hint.
|
||||
- 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 name-based (`Task` first, `Task-2`/`Task-3` only when the name repeats, nested like `Parent.Child`) by `AgentOutputManager`; this is what prevents artifact collisions across repeated or nested task invocations.
|
||||
- Parallelism is parallel `task` calls in one assistant message; the session-scoped semaphore bounds the fan-out. There is no batch array.
|
||||
- Shared background convention: write it once to a `local://` file and reference that path in each assignment — subagents share the parent's `local://` root. This replaces the removed `context` parameter.
|
||||
- Prefer `resume` over a fresh spawn for follow-up work: the resumed agent already holds the relevant context. `irc` op:"list" shows idle/parked candidates; `history://<id>` shows what an agent has done.
|
||||
- Subagents are internally synchronous: the executor forces `async.enabled = false` and `bash.autoBackground.enabled = false` in the child settings snapshot, so there are no fire-and-forget grandchildren.
|
||||
- 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. Create-time discovery is memoized per cwd for the prompt description; execution-time discovery stays fresh.
|
||||
- Child sessions do not inherit conversation history. Built-in carry-over is the workspace tree/skills/context files, the shared `local://` root, and the approved-plan reference when one exists.
|
||||
- When the parent passes `mcpManager`, child sessions disable standalone MCP discovery and get proxy tools that reuse parent connections.
|
||||
- Branch-mode merge temporarily stashes the parent repo before cherry-picking; a stash-pop conflict is treated as merge failure and leaves recovery state behind. Patch mode only applies the combined root patch when `git.patch.canApplyText(...)` succeeds; failures leave the `.patch` artifact for manual handling.
|
||||
- Nested git repos are diffed independently inside isolated workspaces and merged separately with `applyNestedPatches(...)`.
|
||||
- `agent://` ids are name-based (`Task` first, `Task-2`/`Task-3` only when the name repeats, nested like `Parent.Child`) by `AgentOutputManager`; this is what prevents artifact collisions across repeated or nested invocations.
|
||||
|
||||
Reference in New Issue
Block a user