Skip to content

Add profile-aware parallel subagent fleets / 新增可配置并行子智能体 Fleet#6636

Merged
SivanCola merged 3 commits into
esengine:main-v2from
SivanCola:feature/subagent-fleet-parallel
Jul 18, 2026
Merged

Add profile-aware parallel subagent fleets / 新增可配置并行子智能体 Fleet#6636
SivanCola merged 3 commits into
esengine:main-v2from
SivanCola:feature/subagent-fleet-parallel

Conversation

@SivanCola

Copy link
Copy Markdown
Collaborator

Summary

  • Add runtime-resolved profile and write_paths support to task; profile bodies become the complete child system prompt instead of inheriting the concise default.
  • Add fleet for 2–64 independently reported subagent tasks, with foreground or background execution and fixed registration order: taskparallel_tasksfleet.
  • Add a session-wide scheduler with total concurrency, writer concurrency, normalized write-path claims, nested fail-fast behavior, and asynchronous background queueing.
  • Enforce writer claims across task, fleet, parallel skill entry points, parent tools, Bash sandbox roots, and dynamically loaded Economy/MCP tools.
  • Add Desktop controls for concurrency limits and read-only profile editing, plus English and Chinese documentation.

Why

Custom subagent profiles were only directly runnable through the serial skill path. A workload such as ten independent documents therefore queued one child after another even when the work and output paths were independent.

This change makes profile execution available to the parallel task surface while keeping write safety explicit. Writers with disjoint declared paths can run concurrently; a writer that omits write_paths conservatively claims the whole workspace.

Safety and behavior

  • max_subagent_concurrency defaults to 6; max_parallel_writers defaults to 3. Both normalize to 1–32 and writers never exceed total concurrency.
  • Fleet preflight rejects overlapping, parent/child, case-equivalent, glob, symlink-escape, and workspace-escape claims before starting any item.
  • Parent writes take an atomic reservation before PreToolUse and hold it through execution, closing check-before-write races with background subagents.
  • Bash is retained for path-bound writers only when its enforced sandbox roots can be rebound to the claim; otherwise it is removed.
  • Background task returns its job id before waiting for a scheduler slot.
  • Item failures are isolated and reported in the aggregate rather than cancelling unrelated fleet items.

Backward compatibility

Surface Old data/caller behavior after upgrade Conclusion
Existing task calls New fields are optional. Writer calls without write_paths remain valid and now take a conservative whole-workspace scheduling claim. Compatible; safer serialization.
Existing TOML config Missing concurrency keys resolve to 6/3. The new scalar keys are additive, and older TOML decoders ignore unknown keys. Backward-safe.
Existing subagent profile frontmatter Missing read-only remains the legacy writable default. CLI/Desktop round-trip the managed field without dropping unrelated frontmatter. Backward-safe.
Desktop Wails settings payload New frontend code falls back to 6/3 when fields are absent; older frontends ignore added response fields. Cross-version safe.
Persisted subagent transcripts Stored data remains readable. As with any tool-schema change, continuation safely rejects a registry-hash mismatch instead of replaying under a different capability set. Safe failure; no data corruption.

Verification

  • go test ./...
  • cd desktop && go test ./...
  • go test -race ./internal/agent ./internal/boot ./internal/config ./internal/skill
  • cd desktop/frontend && pnpm typecheck && pnpm test:typecheck && pnpm test
  • ./scripts/cache-guard.sh
  • Focused coverage for path conflicts, parent-write TOCTOU, scheduler queues, nested fail-fast, profile prompt ownership, fleet parallelism, schema stability, and read-only round trips
  • Real-provider ten-document paid scenario was not run; deterministic fleet concurrency tests cover the scheduler behavior.

Integration notes

Cache impact

Cache-impact: medium — the upgrade intentionally adds the fleet tool and extends the task schema, causing one prompt-cache cold start. After that, tool order is fixed and profile names never enter tool schemas or the parent system prompt.

Cache-guard: ./scripts/cache-guard.sh passed, including all release cache-hit scenarios.

System-prompt-review: required — custom and named built-in profile bodies now intentionally become the complete child system prompt. Ordinary task and read_only_task defaults are unchanged.

Problem:
Custom subagent profiles could only be run serially through skill execution, making multi-document workloads unnecessarily slow and leaving concurrent writers without one session-wide safety boundary.

Root cause:
Task execution had no runtime profile selector or shared fleet scheduler, and write coordination was split across entry points without atomic parent reservations or enforceable path claims.

Fix:
- add profile-aware task and fleet execution with session-wide total/writer concurrency limits
- normalize and enforce write path claims, including sandboxed Bash roots and parent write reservations
- make background tasks queue asynchronously and keep parallel_tasks on the shared scheduler
- expose concurrency and read-only profile controls in Desktop and document the contracts

Verification:
- go test ./...
- cd desktop && go test ./...
- go test -race ./internal/agent ./internal/boot ./internal/config ./internal/skill
- cd desktop/frontend && pnpm typecheck && pnpm test:typecheck && pnpm test
- ./scripts/cache-guard.sh
@github-actions github-actions Bot added desktop Wails desktop app (desktop/**) tui Terminal UI / CLI (internal/cli, internal/control) skills Skill system (internal/skill, internal/tool) agent Core agent loop (internal/agent, internal/control) config Configuration & setup (internal/config) v2 Go rewrite (1.x) — main-v2 branch, active development labels Jul 18, 2026
Problem:
Path-bound Bash retained sandbox cache and temporary-directory write lanes, wildcard tool allowlists could reject valid narrowed calls, and stale scheduler code blocked lint.

Root cause:
Bash root rebinding did not enable minimal-write confinement, tool lists were intersected before live-registry pattern expansion, and obsolete control flow remained after scheduler unification.

Fix:
Restrict rebound Bash to claim roots, expand both allowlists before intersection, remove stale scheduler parameters and helpers, and add focused execution regressions.

Verification:
- golangci-lint v2.12.2: 0 issues
- go test ./...
- go test -race ./internal/agent ./internal/tool/builtin ./internal/boot ./internal/config ./internal/skill
- cd desktop && go test ./...
- ./scripts/cache-guard.sh
Problem:
Cancelled fleet writers could be reported as skipped after they had started, and preflight conflicts could cite the wrong task numbers when read-only items were interleaved.

Root cause:
The cancellation path stopped draining terminal worker results after waiting, while write claims were compacted into a writer-only slice before indexed validation.

Fix:
Drain every started worker result after cancellation, reserve skipped for tasks that never started, and retain one claim slot per original fleet item. Add deterministic cancellation and mixed-task indexing regressions.

Verification:
- go test -race ./internal/agent -run '^TestFleet' -count=1
- go test ./internal/agent
- go test ./...
- golangci-lint v2.12.2: 0 issues
- ./scripts/cache-guard.sh
- git diff --check
@SivanCola
SivanCola marked this pull request as ready for review July 18, 2026 14:18
@SivanCola
SivanCola requested a review from esengine as a code owner July 18, 2026 14:18
@SivanCola
SivanCola merged commit 2335d0d into esengine:main-v2 Jul 18, 2026
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent Core agent loop (internal/agent, internal/control) config Configuration & setup (internal/config) desktop Wails desktop app (desktop/**) skills Skill system (internal/skill, internal/tool) tui Terminal UI / CLI (internal/cli, internal/control) v2 Go rewrite (1.x) — main-v2 branch, active development

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant