feat(delegation): async background subagents via delegate_task(background=true) by teknium1 · Pull Request #40946 · NousResearch/hermes-agent

teknium1 · 2026-06-07T02:52:17Z

Summary

delegate_task(background=true) now dispatches a subagent that runs in the background and returns a handle immediately — the user and the model keep working while it runs, and the full result re-enters the conversation as a new turn when the subagent finishes.

It rides the same completion-queue rail as terminal background processes (notify_on_complete), so we never splice a result mid-loop. The re-injected message is a self-contained block carrying the original task source (goal, the context the parent supplied, toolsets, role, model, dispatch time, status) plus the result — because by the time it lands, the agent may be deep in unrelated context and won't remember why the subagent existed.

Changes

tools/async_delegation.py (new): daemon-executor registry; capacity cap (rejects, doesn't queue); pushes a rich type="async_delegation" event onto the shared process_registry.completion_queue; interrupt_all() for shutdown.
tools/delegate_tool.py: background param + single-task dispatch branch (captures session_key on the parent thread, hands _run_single_child to the dispatcher as a runner). Batch async rejected in v1.
tools/process_registry.py: format_process_notification renders the self-contained task-source block for the new event type.
gateway/run.py: dedicated _async_delegation_watcher drains + injects results into the originating session (covers the idle case), session_key → routing enrichment, shutdown interrupt of dangling delegations.
hermes_cli/config.py: delegation.max_async_children (default 3).

Why this shape

The existing completion path (completion_queue → CLI _pending_input / gateway synthetic internal=True MessageEvent) surfaces results as a new turn when the agent is idle, never between a tool result and an assistant message. That's load-bearing — it keeps message-role alternation legal and the prompt cache intact (hard invariant: never mutate past context). Async delegation reuses that rail rather than reaching into a running loop, so it inherits the idle-drain wiring, de-dup, and crash-recovery checkpointing already present in cli.py and gateway/run.py.

v1 is single-task only; async batch (N handles, partial completion) is a follow-up.

Validation

	Result
13 targeted tests (`tests/tools/test_async_delegation.py`)	pass
137 existing delegate tests	pass (sync path intact)
Non-blocking proof	`delegate_task(background=true)` returns in 2ms while the child is gated closed; a sync impl would hang 5s
CLI E2E	dispatch → background run → completion event on shared queue → rich re-injection block
Gateway E2E	`session_key` parsed → routable `SessionSource` → injected; foreign watch events requeued untouched
Rebased onto current `origin/main`	clean

Test plan

delegate_task(goal=..., background=true) returns {status: dispatched, delegation_id, mode: background} immediately.
When the subagent finishes, an [ASYNC DELEGATION COMPLETE — deleg_xxxx] message re-enters the chat with the original goal/context + result.
At capacity (max_async_children), further async dispatches are rejected with a fall-back-to-sync hint.
background=true + multi-item tasks → rejected ("single-task only").

Infographic

github-actions · 2026-06-07T02:53:10Z

🔎 Lint report: `hermes/hermes-b1109a1a` vs `origin/main`

ruff

Total: 0 on HEAD, 0 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 0 pre-existing issues carried over.

ty (type checker)

Total: 10924 on HEAD, 10914 on base (🆕 +10)

🆕 New issues (9):

Rule	Count
`invalid-argument-type`	6
`invalid-assignment`	1
`unresolved-import`	1
`unresolved-attribute`	1

First entries

tools/delegate_tool.py:2273: [invalid-argument-type] invalid-argument-type: Argument to function `_run_single_child` is incorrect: Expected `str`, found `Unknown | str | None | list[str]`
tools/delegate_tool.py:2286: [invalid-argument-type] invalid-argument-type: Argument to function `dispatch_async_delegation` is incorrect: Expected `str | None`, found `Any | None | str | list[str]`
tools/delegate_tool.py:2285: [invalid-argument-type] invalid-argument-type: Argument to function `dispatch_async_delegation` is incorrect: Expected `str`, found `Any | str | None | list[str]`
hermes_cli/cli_commands_mixin.py:246: [invalid-assignment] invalid-assignment: Object of type `None` is not assignable to `def interrupt_all(reason: str = "shutdown") -> int`
tools/async_delegation.py:65: [invalid-argument-type] invalid-argument-type: Argument to bound method `SimpleQueue.put` is incorrect: Expected `_WorkItem[Any]`, found `None`
tests/tools/test_async_delegation.py:12: [unresolved-import] unresolved-import: Cannot resolve imported module `pytest`
tools/delegate_tool.py:2287: [invalid-argument-type] invalid-argument-type: Argument to function `dispatch_async_delegation` is incorrect: Expected `list[str] | None`, found `(Any & ~AlwaysFalsy) | (str & ~AlwaysFalsy) | list[str] | None`
tests/tools/test_delegate.py:2272: [invalid-argument-type] invalid-argument-type: Argument to function `delegate_task` is incorrect: Expected `bool | None`, found `str | Unknown`
tools/async_delegation.py:82: [unresolved-attribute] unresolved-attribute: Object of type `AbstractSet[Thread]` has no attribute `add`

✅ Fixed issues: none

Unchanged: 5747 pre-existing issues carried over.

Diagnostics are surfaced as warnings — this check never fails the build.

…ound=true) delegate_task(background=true) dispatches a subagent that runs in the background and returns a handle immediately, so the user and model keep working while it runs. The full result — plus the original task source — re-enters the conversation as a new turn when the subagent finishes, riding the same completion-queue rail as terminal background processes. - tools/async_delegation.py: daemon-executor registry, capacity cap, rich self-contained completion event pushed onto the shared process_registry.completion_queue (type='async_delegation'). - delegate_tool.py: background param + single-task dispatch branch; batch async rejected (v1). - process_registry.py: format_process_notification renders the rich task-source block (goal/context/toolsets/model/status/result). - gateway/run.py: dedicated _async_delegation_watcher drains + injects results into the originating session (idle + post-turn), session_key routing enrichment, shutdown interrupt of dangling delegations. - config: delegation.max_async_children (default 3). Reuses the existing idle-drain wiring rather than mutating a running agent loop, preserving message-role alternation and prompt-cache invariants. 13 targeted tests; CLI + gateway paths E2E-verified.

CI 'test (5)' flaked on a cold, 8-worker runner: the first delegate_task(background=true) call measured 2.27s of one-time setup (config load + child-agent construction + imports), tripping the elapsed < 1.0 wall-clock assertion. That assertion was testing setup overhead, not blocking. Replace the wall-clock thresholds with the real invariant: dispatch returns while the child is still gated (active_count == 1, completion queue empty), which a synchronous impl could not do. Keep only a loose 4s sanity backstop well under the runner's 5s gate.

Follow-up review fixes: - Detach background child from parent._active_children at dispatch — otherwise parent-turn interrupts (Ctrl+C, mid-turn steering), cache evicts (release_clients), and session close (/new) kill/close the detached subagent mid-run, defeating the point of background mode. Lifecycle is owned by the async registry's interrupt_fn. - Make the capacity check atomic with the record insert (TOCTOU: two concurrent dispatches could both pass active_count() and exceed the cap). - TUI dedup: key async_delegation events by delegation_id — the fallthrough keyed them all as ("", type), suppressing every completion after the first in the desktop/TUI status feed. - CLI /stop now interrupts running background delegations and /agents lists them (they live outside the process registry and were invisible). - Drop stray unbalanced ']' line from the re-injection block and the unused _ASYNC_DEFAULT import. Tests: detach-at-dispatch + concurrent-capacity race added (15 total in test_async_delegation.py); 137 delegate + 140 process-registry/notify/watch + 7 TUI dedup tests pass.

…#40946

…async background delegation

chadsm-sys · 2026-06-15T19:04:22Z

Follow-up patch opened: #46838

Summary:

Preserves raw background process/delegation notification events alongside formatted CLI text.
Adds regression coverage for raw event preservation and backward-compatible plain input handling.

Validation from sandbox:

.venv/bin/python -m pytest tests/test_cli_process_notification_input.py tests/tools/test_process_registry.py tests/gateway/test_background_process_notifications.py -q
104 passed in 3.71s

I could not push directly to this PR head branch with the current account, so #46838 targets this PR's branch.

…ation" This reverts commit 500dc0f, reversing changes made to 70f93c5.

…m merge

…kfile-fix.yml) Upstream advanced from 5bfed0f (Jun 15) to 3e7e9b2 (Jun 16). Major upstream changes since last merge: - feat(skills): add optional payments skills (Stripe Link, MPP, Projects) NousResearch#31343 - feat(delegation): async background subagents via delegate_task(background=true) NousResearch#40946 - fix(desktop): read HERMES_HOME from Windows registry when env is stale NousResearch#46772 - fix(desktop): let explicit model switches escape broken config providers NousResearch#46796 - fix(dump): report effective terminal backend in hermes debug - fix(inventory): deduplicate models between user-defined and aggregator providers - fix(doctor): recognize nvidia as vendor-slug-accepting provider - fix(discord): cap slash commands at Discord's 100-command limit - fix(teams): package Microsoft Teams SDK as an installable extra NousResearch#46764 - fix(dashboard): scope chat sidebar model card to selected profile NousResearch#46665 - fix(deps): declare websockets as core dep + relax dev setuptools pin NousResearch#46744 - fix(desktop): pin @assistant-ui/store so the cluster shares one tap - fix(install): make npm install -g packages reachable on PATH - feat(honcho-setup): replace deployment-shape prompt with gateway-gated identity tree - refactor(honcho): canonicalize identity-mapping on pinUserPeer, migrate legacy key - mattermost: preserve thread-local delivery hygiene - ci: rip out nix ci for now - ...plus desktop Electron changes, web UI updates, website docs, honcho docs Fork customizations preserved (all 22 verified intact): - run_agent.py: max_iterations: int = 200 - agent/conversation_loop.py: _force_final_threshold, _build_tools_summary, _current_turn_tool_calls, _pending_tool_summary, tool_summary flow - agent/turn_finalizer.py: 'tool_summary' key in result dict - tools/web_tools.py: tiered fetcher (curl_cffi→scrapling→httpx), MAX_OUTPUT_SIZE=10000, _get_extract_backend, max_result_size_chars=500_000, LLM-summarization disabled, NCBI/PubMed/PMC hardening - tools/budget_config.py: 400_000 / 500_000 - gateway/run.py: HERMES_MAX_ITERATIONS, "200" - hermes_cli/config.py: max_turns: 200 - cli.py: result.get('tool_summary') display - gateway/config.py: Platform.LINE = "line" - gateway/authz_mixin.py: Platform.LINE: "LINE_ALLOWED_GROUPS" - plugins/platforms/line/adapter.py: reply_only_mention, build_source Conflict resolution: - .github/workflows/nix-lockfile-fix.yml: removed by upstream. Was fork-only (disabled with if:false, requires APP_ID/APP_PRIVATE_KEY secrets the fork does not have). Upstream deletion is correct. Backup branch: backup-main-pre-merge-20260616-063126

…ound=true) (NousResearch#40946) * feat(delegation): async background subagents via delegate_task(background=true) delegate_task(background=true) dispatches a subagent that runs in the background and returns a handle immediately, so the user and model keep working while it runs. The full result — plus the original task source — re-enters the conversation as a new turn when the subagent finishes, riding the same completion-queue rail as terminal background processes. - tools/async_delegation.py: daemon-executor registry, capacity cap, rich self-contained completion event pushed onto the shared process_registry.completion_queue (type='async_delegation'). - delegate_tool.py: background param + single-task dispatch branch; batch async rejected (v1). - process_registry.py: format_process_notification renders the rich task-source block (goal/context/toolsets/model/status/result). - gateway/run.py: dedicated _async_delegation_watcher drains + injects results into the originating session (idle + post-turn), session_key routing enrichment, shutdown interrupt of dangling delegations. - config: delegation.max_async_children (default 3). Reuses the existing idle-drain wiring rather than mutating a running agent loop, preserving message-role alternation and prompt-cache invariants. 13 targeted tests; CLI + gateway paths E2E-verified. * test(delegation): make async non-blocking tests environment-independent CI 'test (5)' flaked on a cold, 8-worker runner: the first delegate_task(background=true) call measured 2.27s of one-time setup (config load + child-agent construction + imports), tripping the elapsed < 1.0 wall-clock assertion. That assertion was testing setup overhead, not blocking. Replace the wall-clock thresholds with the real invariant: dispatch returns while the child is still gated (active_count == 1, completion queue empty), which a synchronous impl could not do. Keep only a loose 4s sanity backstop well under the runner's 5s gate. * fix(delegation): harden async background delegation Follow-up review fixes: - Detach background child from parent._active_children at dispatch — otherwise parent-turn interrupts (Ctrl+C, mid-turn steering), cache evicts (release_clients), and session close (/new) kill/close the detached subagent mid-run, defeating the point of background mode. Lifecycle is owned by the async registry's interrupt_fn. - Make the capacity check atomic with the record insert (TOCTOU: two concurrent dispatches could both pass active_count() and exceed the cap). - TUI dedup: key async_delegation events by delegation_id — the fallthrough keyed them all as ("", type), suppressing every completion after the first in the desktop/TUI status feed. - CLI /stop now interrupts running background delegations and /agents lists them (they live outside the process registry and were invisible). - Drop stray unbalanced ']' line from the re-injection block and the unused _ASYNC_DEFAULT import. Tests: detach-at-dispatch + concurrent-capacity race added (15 total in test_async_delegation.py); 137 delegate + 140 process-registry/notify/watch + 7 TUI dedup tests pass. * fix(delegation): harden async background completion drains

…utor + completion queue New tools/async_delegation.py daemon-executor registry: - dispatch() runs subagents in background threads, returns immediately - Capacity capped by delegation.max_async_children (default 3) - Completion events pushed to process_registry.completion_queue Modified files: - delegate_tool.py: added background=False param, early-dispatch branch - process_registry.py: format_process_notification handles async_delegation type - gateway/run.py: _async_delegation_watcher drains queue between idle turns - hermes_cli/config.py: delegation.max_async_children setting Partially implements NousResearch#40946 (v1: single-task only, no persistent state). Co-authored-by: Luna Selene <luna@hermes>

- When at max_async_children capacity, dispatch() now queues the item (status=queued) instead of rejecting it. - Promotion thread auto-dispatches queued items as slots free up (FIFO). - _promotion_cv Condition variable signals the promotion loop. New 'hermes delegation' subcommand: - hermes delegation list [--json] — running + queued overview - hermes delegation status <id> [--json] — per-delegation details New helpers in tools/async_delegation.py: - count_queued(), get_queued_details(), get_running_details(), get_detail() Partially implements NousResearch#40946 (v1). Co-authored-by: Luna Selene <luna@hermes>

…ound=true) (NousResearch#40946) * feat(delegation): async background subagents via delegate_task(background=true) delegate_task(background=true) dispatches a subagent that runs in the background and returns a handle immediately, so the user and model keep working while it runs. The full result — plus the original task source — re-enters the conversation as a new turn when the subagent finishes, riding the same completion-queue rail as terminal background processes. - tools/async_delegation.py: daemon-executor registry, capacity cap, rich self-contained completion event pushed onto the shared process_registry.completion_queue (type='async_delegation'). - delegate_tool.py: background param + single-task dispatch branch; batch async rejected (v1). - process_registry.py: format_process_notification renders the rich task-source block (goal/context/toolsets/model/status/result). - gateway/run.py: dedicated _async_delegation_watcher drains + injects results into the originating session (idle + post-turn), session_key routing enrichment, shutdown interrupt of dangling delegations. - config: delegation.max_async_children (default 3). Reuses the existing idle-drain wiring rather than mutating a running agent loop, preserving message-role alternation and prompt-cache invariants. 13 targeted tests; CLI + gateway paths E2E-verified. * test(delegation): make async non-blocking tests environment-independent CI 'test (5)' flaked on a cold, 8-worker runner: the first delegate_task(background=true) call measured 2.27s of one-time setup (config load + child-agent construction + imports), tripping the elapsed < 1.0 wall-clock assertion. That assertion was testing setup overhead, not blocking. Replace the wall-clock thresholds with the real invariant: dispatch returns while the child is still gated (active_count == 1, completion queue empty), which a synchronous impl could not do. Keep only a loose 4s sanity backstop well under the runner's 5s gate. * fix(delegation): harden async background delegation Follow-up review fixes: - Detach background child from parent._active_children at dispatch — otherwise parent-turn interrupts (Ctrl+C, mid-turn steering), cache evicts (release_clients), and session close (/new) kill/close the detached subagent mid-run, defeating the point of background mode. Lifecycle is owned by the async registry's interrupt_fn. - Make the capacity check atomic with the record insert (TOCTOU: two concurrent dispatches could both pass active_count() and exceed the cap). - TUI dedup: key async_delegation events by delegation_id — the fallthrough keyed them all as ("", type), suppressing every completion after the first in the desktop/TUI status feed. - CLI /stop now interrupts running background delegations and /agents lists them (they live outside the process registry and were invisible). - Drop stray unbalanced ']' line from the re-injection block and the unused _ASYNC_DEFAULT import. Tests: detach-at-dispatch + concurrent-capacity race added (15 total in test_async_delegation.py); 137 delegate + 140 process-registry/notify/watch + 7 TUI dedup tests pass. * fix(delegation): harden async background completion drains

teknium1 force-pushed the hermes/hermes-b1109a1a branch from 4202a8e to d8754a7 Compare June 7, 2026 02:59

alt-glitch added type/feature New feature or request P3 Low — cosmetic, nice to have comp/agent Core agent runtime: loop, agent_init, prompt builder, context-compression, responses endpoint comp/gateway Gateway runner, session dispatch, delivery tool/delegate Subagent delegation labels Jun 7, 2026

teknium1 force-pushed the hermes/hermes-b1109a1a branch from 67397d8 to 1c00cb6 Compare June 10, 2026 16:22

teknium1 added 4 commits June 15, 2026 07:32

fix(delegation): harden async background completion drains

b47e65d

teknium1 force-pushed the hermes/hermes-b1109a1a branch from 1c00cb6 to b47e65d Compare June 15, 2026 14:33

Codename-11 added a commit to Codename-11/hermes-agent that referenced this pull request Jun 15, 2026

chore(carry): trim trailing blank lines from upstream PR NousResearch…

5694d89

…#40946

Codename-11 added a commit to Codename-11/hermes-agent that referenced this pull request Jun 15, 2026

carry(upstream): PR NousResearch#40946 async background delegation

500dc0f

Codename-11 added a commit to Codename-11/hermes-agent that referenced this pull request Jun 15, 2026

docs(fork): record temporary carry of upstream PR NousResearch#40946 …

4132a1a

…async background delegation

chadsm-sys mentioned this pull request Jun 15, 2026

fix: preserve raw process notification events in CLI queue #46838

Closed

aneym mentioned this pull request Jun 15, 2026

fix(delegation): forward background flag from agent dispatcher #46849

Closed

teknium1 merged commit c66ecf0 into main Jun 15, 2026
30 checks passed

teknium1 deleted the hermes/hermes-b1109a1a branch June 15, 2026 20:33

Codename-11 added a commit to Codename-11/hermes-agent that referenced this pull request Jun 15, 2026

Revert "carry(upstream): PR NousResearch#40946 async background deleg…

1e16a11

…ation" This reverts commit 500dc0f, reversing changes made to 70f93c5.

Codename-11 added a commit to Codename-11/hermes-agent that referenced this pull request Jun 15, 2026

docs(fork): mark PR NousResearch#40946 carry as superseded by upstrea…

48859cd

…m merge

argus-metis mentioned this pull request Jun 16, 2026

fix: async subagent background=True drops user interrupts to queue (#46864) #46950

Closed

7 tasks

heathwhiteside30-arch mentioned this pull request Jun 16, 2026

Bug: delegate_task(background=true) parameter not reaching model — synchronous fallback #46960

Closed

felipegermano17 mentioned this pull request Jun 16, 2026

Model Hermes async subagents as reconciled factory lanes felipegermano17/overkill-factory#244

Closed

This was referenced Jun 16, 2026

[经验分享] Doer/Reviewer 双角色并行编排 + Hindsight 共享记忆实践 #34592

Open

[Showcase] Orchestrator v3 + delegate_task(background=true): Non-blocking Doer/Reviewer with Hindsight Shared Memory #47035

Closed

mlinquan mentioned this pull request Jun 16, 2026

fix: prevent silent message loss when state.db persistence fails #32805

Closed

BrewTestBot mentioned this pull request Jun 19, 2026

hermes-agent 2026.6.19 Homebrew/homebrew-core#288870

Merged

1 task

This was referenced Jun 20, 2026

chore: bump NousResearch/hermes-agent version from v2026.6.5 to v2026.6.19 Docker-Hub-sirmark/docker-hermes-agent#10

Merged

Upstream Hermes v2026.6.19 disponible (ultimo sync: v2026.6.5) samuelgradientai-sys/clawksis-agent#45

Closed

tomfuertes mentioned this pull request Jun 23, 2026

chore: bump Hermes to v2026.6.19 (0.17.0) notambourine/hermes-agent-template#15

Merged

teknium1 mentioned this pull request Jul 12, 2026

feat: non-blocking background agent delegation (async_delegation toolset) #5586

Closed

teknium1 mentioned this pull request Jul 14, 2026

test: remove flaky test_crashed_runner_produces_error_completion #64431

Merged

meiqinsi mentioned this pull request Aug 14, 2026

[Bug]: api_server wake self-POSTs async-delegation completion as a user turn after parent complete #85957

Open

1 task

Navigation Menu

Uh oh!

feat(delegation): async background subagents via delegate_task(background=true) - #40946

feat(delegation): async background subagents via delegate_task(background=true)#40946
teknium1 merged 4 commits into
mainfrom
hermes/hermes-b1109a1a

teknium1 commented Jun 7, 2026

Uh oh!

github-actions Bot commented Jun 7, 2026 •

edited

Loading

Uh oh!

chadsm-sys commented Jun 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

teknium1 commented Jun 7, 2026

Summary

Changes

Why this shape

Validation

Test plan

Infographic

Uh oh!

github-actions Bot commented Jun 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔎 Lint report: hermes/hermes-b1109a1a vs origin/main

ruff

ty (type checker)

Uh oh!

chadsm-sys commented Jun 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented Jun 7, 2026 •

edited

Loading

🔎 Lint report: `hermes/hermes-b1109a1a` vs `origin/main`