Skip to content

feat: session-native subagents runtime v1 (spawn/list/info/kill)#217

Merged
everettjf merged 14 commits intomainfrom
feat/subagents-runtime-v1
Mar 9, 2026
Merged

feat: session-native subagents runtime v1 (spawn/list/info/kill)#217
everettjf merged 14 commits intomainfrom
feat/subagents-runtime-v1

Conversation

@everettjf
Copy link
Contributor

Summary

This PR replaces the legacy in-tool sub_agent loop with a session-native asynchronous subagents runtime.

What shipped in v1

  • Removed legacy sub_agent tool entirely.
  • Added new tool family:
    • sessions_spawn
    • subagents_list
    • subagents_info
    • subagents_kill
  • Added subagent_runs persistence in SQLite with lifecycle + token accounting.
  • Added configurable subagent runtime limits in config:
    • subagents.max_concurrent
    • subagents.max_active_per_chat
    • subagents.run_timeout_secs
    • subagents.announce_to_chat
  • Added async runtime lane with non-blocking spawn semantics.
  • Added cancellation support (kill one or all) via cooperative cancel checks.
  • Added completion announce back to parent chat (best effort in v1).
  • Updated system prompt capability text to point to new tool family.
  • Added RFC: docs/rfcs/0005-subagents-runtime-v1.md.

Why this direction

This is a practical and safer architecture than tool-embedded delegation:

  • session-native run lifecycle (accepted/queued/running/completed/failed/timed_out/cancelled)
  • explicit management controls
  • persistent diagnostics
  • bounded concurrency and per-chat limits

It aligns with OpenClaw/Spacebot subagent direction while keeping MicroClaw implementation lean and production-friendly.

Validation

  • cargo test -q

Follow-up (v2+)

  • nested orchestrator depth/fan-out-fan-in
  • thread-bound subagent sessions
  • durable announce retry queue across restarts
  • richer run observability/event timeline

Related: #205

@everettjf
Copy link
Contributor Author

Progress update: completed the requested 5 incremental commits on this PR.

New commits:

  1. 1c438a9 feat(subagents): add nested depth and parent-child fanout controls
  2. f042081 feat(subagents): persist announce queue with retry and manual flush
  3. bbfe51d feat(subagents): add event timeline and run log inspection tool
  4. 3d9f471 feat(subagents): add focus binding and follow-up send workflow
  5. e8e6edd docs(subagents): refresh generated artifacts and 5-step delivery plan

Validation:

  • cargo test -q passed after each functional increment.

I’ll keep this PR as the single integration branch unless you want me to split follow-up stabilization into separate PRs.

@everettjf
Copy link
Contributor Author

继续同一个 PR 完成了你提的下一阶段 3 项能力,已推送:

  1. thread-bound 真路由(Discord)
  • 在 时,如果当前 chat/thread 已有 focused run,会优先把用户新消息直接路由到 ,生成 continuation child run。
  • 路由成功后立即回执并写入会话消息;路由失败则回退到原主 agent 流程(不影响可用性)。
  1. 回传队列重启恢复
  • 新增启动期 announce relay:进程启动先 flush 一次,再按固定间隔轮询 pending/retry 队列并重试投递。
  • 提升为可复用入口;手动工具和自动 relay 共用同一逻辑。
  1. depth=2 编排模板
  • 在系统提示中加入 depth-2 orchestration 模板(orchestrator -> workers -> merge + guardrails),让主代理在允许嵌套时更稳定地使用 subagents。

配置补充(已在同 PR 中):

  • (默认 )
  • (默认 ,归一化到 )

验证:
running 611 tests
....................................................................................... 87/611
....................................................................................... 174/611
....................................................................................... 261/611
....................................................................................... 348/611
....................................................................................... 435/611
....................................................................................... 522/611
....................................................................................... 609/611
..
test result: ok. 611 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 10.96s

running 7 tests
.......
test result: ok. 7 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

running 6 tests
......
test result: ok. 6 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

running 8 tests
........
test result: ok. 8 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.07s

running 17 tests
.................
test result: ok. 17 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s 全量通过。

@everettjf
Copy link
Contributor Author

继续同一个 PR 完成了你提的下一阶段 3 项能力,已推送:

  1. 2e21514 thread-bound 真路由(Discord)
  • subagents.thread_bound_routing_enabled=true 时,如果当前 chat/thread 已有 focused run,会优先把用户新消息直接路由到 subagents_send,生成 continuation child run。
  • 路由成功后立即回执并写入会话消息;路由失败则回退到原主 agent 流程(不影响可用性)。
  1. 8b40714 回传队列重启恢复
  • 新增启动期 announce relay:进程启动先 flush 一次,再按固定间隔轮询 pending/retry 队列并重试投递。
  • flush_pending_announces_once 提升为可复用入口;手动工具和自动 relay 共用同一逻辑。
  1. 90d8fff depth=2 编排模板
  • 在系统提示中加入 depth-2 orchestration 模板(orchestrator -> workers -> merge + guardrails),让主代理在允许嵌套时更稳定地使用 subagents。

配置补充(已在同 PR 中):

  • subagents.thread_bound_routing_enabled(默认 true
  • subagents.announce_relay_interval_secs(默认 15,归一化到 1..=300

验证:cargo test -q 全量通过。

@everettjf everettjf marked this pull request as draft March 9, 2026 08:52
@everettjf everettjf marked this pull request as ready for review March 9, 2026 18:55
@everettjf everettjf merged commit 58ff374 into main Mar 9, 2026
1 of 4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant