Skip to content

Consolidate the seven-module agent lifecycle cycle behind an orchestrator facade #3450

Description

@atomantic

Problem

Seven modules in the core agent-orchestration path form one tightly-coupled circular cluster (confirmed via madge --circular):

server/services/cos.jscosAgents.jscosAgentLifecycle.jsagentManagement.jsagents.jssubAgentSpawner.jsagentLifecycle.js, with several edges reaching back up the chain.

There is no correctness bug today — the team has already broken the static cycle at the load-bearing edges with await import(...), and cosAgentLifecycle.js:453-526 documents exactly why ("a static import here would invert the layering").

The cost is comprehension and change-safety: no module clearly owns agent lifecycle, so changing any one module's exported surface risks a ripple through the other six, and reasoning about a lifecycle transition means holding all seven files in mind at once.

Work

Consolidate the mutually-recursive lifecycle transitions (pause / kill / complete / spawn) behind a single agentOrchestrator facade that owns the state machine, with the current seven modules becoming leaf implementations it calls one-directionally.

This is a Complex refactor in the most load-bearing path in the app, which is why the audit that found it deliberately did not attempt it automatically. It should be done deliberately, with the existing cosAgents.test.js / cleanupAgentWorktree.test.js coverage as the regression net, and probably in more than one PR.

Suggested sequencing:

  1. Map every current cross-module call and classify it as "lifecycle transition" vs "leaf operation"
  2. Introduce the facade with the transitions, leaving leaves in place
  3. Migrate call sites one module at a time
  4. Remove the dynamic-import workarounds that exist only to break the cycle

Found by a /do:better audit sweep.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions