feat(delegation): add opt-in synchronous sequential execution

[midhatn]

What does this PR do?

Adds opt-in delegation.sequential: true for workflows that need one delegated child to finish before another starts, with the parent waiting for the completed batch. This can be useful when sharing a constrained inference endpoint, controlling overlapping requests to a hosted provider, or intentionally serializing delegated work. It works as a Hermes execution policy and does not depend on a specific model, backend or hardware configuration. Normal background delegation stays the default.

Limiting max_concurrent_children to 1 does not make a background call synchronous: the parent can still issue model requests while its child runs. This option overrides background dispatch at the common batch entry point, suppresses independent completion delivery, and advertises the actual behavior in the tool description. The existing maximum still bounds the number of tasks accepted in a call.

The policy is profile-scoped. It is not a global lock across sessions/processes, an API rate limiter, or a dependency scheduler; it does not automatically pass one child's results into the next child's task. It makes no universal throughput claim. Start a new session after changing it to preserve prompt-cache stability.

Related work

Related to #62392, which proposes foreground-by-default delegation and has maintainer feedback about session-stable policy. This PR also forces a multi-child batch to one worker, and snapshots that sequential policy together with the agent's tool definitions. A foreground join alone can still run its children concurrently. These proposals overlap on the parent-waits behavior; consolidating the public configuration surface is a maintainer decision. #122815 separately addresses a wall-clock bound on synchronous joins; this PR does not replace timeout/liveness handling.

Design and overlap review: general collaborative-agent scheduling across local models, hosted APIs and multiple endpoints, using the Centralized MAS / Hybrid MAS terminology from Towards a Science of Scaling Agent Systems. Existing Kanban graphs already express parallel-then-sequential and sequential-then-parallel phases. Existing A2A/Bot paths and open PRs #106423, #123218, #106268 and #98824 cover related messaging/orchestration work. This PR documents those boundaries and does not introduce a duplicate swarm runtime.

Type of Change

• New feature (opt-in; existing defaults preserved)

Changes Made

• Register and document delegation.sequential in defaults and the example config.
• Keep each enabled batch synchronous with one worker.
• Capture the sequential policy during agent tool setup and include it in tool-definition memoization, so profile edits do not silently change existing agents' dispatch behavior or cached descriptions.
• Update model-facing descriptions and delegation documentation.
• Add two behavior tests: real registry dispatch joins children in order; real profile config switches A → B → A, with existing agents retaining their policy across config edits/tool reloads and fresh agents adopting the changed setting.

How to Test

Tested on Windows/Python 3.14.7, rebased onto main 3cf2eb1c94.

• Both new regressions fail on the original unmodified base (e85706cba7) and pass with this patch. The subsequent c2f3192929 update changes desktop/web code, not the delegation implementation.
• Canonical scripts/run_tests.sh run over the 40 test_delegate*.py / test_async_delegation*.py files: 320 passed, 0 failed, 2 platform skips.
• That suite ran on base c2f3192929. The final two upstream commits only change gateway slash-command completion and its tests; after rebasing onto ef2013231d, the sequential regression and gateway completion test files were rerun through the canonical runner and passed.
• Follow-up session-policy reproduction: changing the real profile after agent tool setup returned background dispatch under a sequential schema before the fix; it passes after the fix, including tool reloads and new-agent adoption across profile A → B → A.
• Expanded canonical run over 44 delegation, initialization and tool-cache test files: 357 passed, 1 failed, 2 skipped. The failure is test_tool_defs_cache_key_sees_config_replacement_with_pinned_mtime on Windows. It also fails with the unchanged upstream model_tools.py restored: a same-size copy2 overwrite with pinned mtime leaves the tested file signature unchanged. This unrelated existing case is not fixed or claimed green here.
• The expanded run used upstream ef2013231d; the final rebase adds only upstream's web/vitest.config.ts development-mode change. Python implementation and test contents are unchanged by that rebase.
• The full repository suite and a new full-model performance benchmark were not run.

Checklist

• Read contribution/development guidance and searched existing PRs.
• Only changes related to this option; conventional commit.
• Added behavior tests and ran the relevant suite through the canonical runner.
• Updated config defaults, example config, documentation and tool descriptions.
• Full repository test suite run (not claimed).

[midhatn]

After checking current code, documentation and open PRs, much of the broader collaboration idea already has an implementation or an existing owner. This PR should remain focused on truly sequential ordinary delegation while the parent waits, rather than introduce another swarm runtime.

Existing work to build on:

• Kanban Swarm v1 already creates parallel workers followed by a verifier and synthesizer. Kanban dependencies, handoffs and dispatch limits support ordered phases and resource bounds.
• A2A and the existing Bot/room paths cover other forms of agent collaboration. Ordinary delegated children and independently addressable sessions are different lifecycles.
• feat(tools): peer session messaging — one session can warn or unblock another (inspired by Muse Code) #106423 implements opt-in local session messaging; feat(peer-messaging): project discovery, tool-data inbox, replies and ACKs #123218 builds on that branch with inbox reads, replies and ACKs. feat(delegation): configurable worker orchestration with durable lifecycle #106268 covers retained workers and policy-controlled sibling messaging. These are open proposals, not features this PR adds or claims are merged.
• Add multi-agent orchestration tool #98824 proposes an orchestration layer on delegation. feat(delegation): add configurable foreground execution #62392 proposes foreground-by-default execution; it overlaps the parent-waits part of this PR, but does not itself force a multi-child batch to use one worker. Maintainer guidance on consolidating the execution-policy surface would be welcome.

The broader use case includes local models, shared inference servers, hosted APIs and teams using different models, with different concurrency, memory, rate and cost limits.

The terminology comes from Towards a Science of Scaling Agent Systems (architectural comparison in Table 2 of v1). It is useful to separate two choices:

• Topology: Centralized MAS means an orchestrator coordinates workers. Hybrid MAS adds directed worker-to-worker communication while retaining the orchestrator.
• Schedule: Either topology could execute sequentially, concurrently, or in phases. Switching between parallel and sequential phases alone does not make it Hybrid MAS.

Two useful phased schedules, already expressible with Kanban dependency graphs:

1. Parallel first, sequential second: start independent research/tool work together, then join, integrate and verify in order.
2. Sequential first, parallel second: establish shared requirements, dependencies and file ownership first, then dispatch independent implementation or verification branches, followed by a final integration check.

The scheduler should distinguish concurrent agent lifetimes, tool execution and model requests. A worker waiting on a build or web request may leave useful room for another worker. A shared model endpoint may benefit from serialized requests and prompt reuse; separate endpoints or a batching-capable server may benefit from concurrent requests. Hosted APIs add rate and cost budgets. These should be configurable capabilities and limits, rather than assumptions tied to a particular machine or provider.

The paper evaluates multiple agent architectures and finds task-dependent benefits and coordination costs. It motivates comparing approaches; it does not establish that Hybrid MAS or more agents will always be faster or more reliable, nor does it validate either phased scheduling policy proposed here.

For a Hybrid MAS experiment, the existing messaging and worker PRs above are the appropriate starting points. Desirable constraints are explicit recipients, compact findings/artifact references, clear queued-versus-delivered status, message/round limits, and an orchestrator that resolves conflicts and owns final verification. Peer messages should retain their sender identity rather than being treated as user instructions. Workers need explicit artifact ownership and bounded dependency waits. Peer communication does not require all agents to generate simultaneously. A shared Kanban blackboard is useful coordination, but should not automatically be labelled the paper's directed peer-message topology.

I would reuse and document these existing mechanisms before proposing any new scheduler or peer tool. This PR is not an adaptive scheduler or peer-messaging implementation. Our earlier bounded experiments only varied scheduling in Centralized MAS.

Evaluation should compare a single-agent baseline, Centralized MAS and Hybrid MAS on the same tasks and budgets, across representative backends. Useful outcomes are independently verified success, completion time including failures/retries, tokens and API cost, prompt reuse, tool/model overlap, peak memory and clean cancellation. That would show when collaboration helps instead of assuming one topology or schedule is best for every Hermes user.

[kvnloo]

Static execution-policy review: the sequential mode keeps model-facing schema and runtime behavior on the same frozen decision, which is the important invariant here.

I checked the A→B→A/profile-change case in particular:

• _snapshot_sequential_policy(agent) captures the profile value on the parent;
• dynamic schema generation sees the same ContextVar while the tool definitions are built;
• the tool-definition cache key includes that policy, so a cached parallel schema cannot leak into a sequential parent;
• later rebuilds of the same parent use agent._delegation_sequential, keeping its advertised contract stable;
• fresh parents pick up changed config;
• dispatch forces background=False and max_children=1 before the shared executor, so independent_completions / background admission cannot silently re-parallelize the call.

That is a good pattern for policy-bearing agent tools: snapshot once per runtime and make the schema/cache key carry the same policy.

No blocker found in this pass; I did not execute the suite here.

[midhatn]

Updated the branch against current main while preserving the existing sequential-delegation behavior and the newer session toolset exclusions.

The session still captures its delegation policy once; schema construction and dispatch use that same snapshot. The merge also keeps agent-specific tool drops and one-shot pruning in their current order. I moved the small schema-loading block and delegation defaults into existing/new sibling helpers to satisfy the repository's file-size checks.

Validation on Windows: 19 selected tests passed with no failures, skips or retries, including the original sequential-dispatch tests, the new merge regressions, and existing config load/save checks. All 12 repository checks passed. These are scoped native-code and fixture checks; this update does not claim a live-model or performance result.