Role of the Coordinator in Two-Model Collaboration: DeepSeek-Reasonix Architecture

The Coordinator acts as the central orchestrator that decouples planning and execution by isolating sessions between a low-frequency planner model and a full-capability executor agent while managing their hand-off through explicit guard mechanisms.

The Coordinator in the esengine/DeepSeek-Reasonix repository solves the fundamental challenge of running two distinct language models in tandem without polluting their respective contexts. By managing the role of the Coordinator in two-model collaboration, the system preserves cache-stable prompts for each agent, reduces redundant token usage, and creates a clean pipeline where a lightweight planner delegates to a tool-enabled executor.

What Is the Coordinator?

The Coordinator is not merely a message router—it is a stateful orchestrator defined in internal/agent/coordinator.go that instantiates and manages the lifecycle of two separate agents. It creates a planner session (plannerSess) distinct from the executor's session, ensuring that each model retains a stable system-prompt prefix that remains unpolluted by the other model's turns.

This architectural pattern allows Reasonix to deploy a low-frequency model for high-level planning while reserving a full-capability model for actual tool execution and implementation details.

How the Coordinator Orchestrates Two-Model Collaboration

Isolating Planner and Executor Sessions

The Coordinator enforces strict session separation to prevent context leakage. In internal/agent/coordinator.go (lines 43-47), the constructor initializes a dedicated planner session using agent.NewSession("planner"), which operates independently from the executor's existing session.

// The Coordinator creates isolated sessions for each model
coord := agent.NewCoordinator(
    plannerProv,               // planner provider (low-frequency model)
    agent.NewSession("planner"), // separate planner session
    nil,                       // optional pricing info
    nil,                       // planner can use read-only tools via Options
    agent.Options{
        MaxSteps:    4,        // limit planner turns
        Temperature: 0.2,
    },
    execAgent,                 // executor agent (full-capability)
    0.0,                       // temperature for coordinator (unused)
    event.Discard,             // sink for usage events
    nil,                       // shouldPlan callback
)

This isolation ensures that the planner's reasoning steps do not contaminate the executor's tool-calling context, preserving cache stability for both models.

Managing the Hand-Off Between Models

The hand-off mechanism is triggered when the planner produces a concise, ordered plan. The Coordinator signals this transition using the marker Reasonix executor handoff and enables the executorHandoffGuard to prevent the executor from inadvertently invoking its own planner logic.

According to the source in internal/agent/coordinator.go (lines 31-33), this guard ensures that the executor, despite being a more capable model with tool access, cannot recursively trigger planning logic during its execution phase. The Coordinator explicitly manages this boundary, ensuring the executor implements only the plan provided.

Gating Planning with Conditional Logic

The Coordinator exposes a shouldPlan callback that allows fine-grained control over when to invoke the planner. As implemented in internal/agent/coordinator.go (lines 56-59), this callback can gate the planner on a per-turn basis, allowing trivial interactions (such as greetings or simple queries) to bypass the planner entirely and route directly to the executor.

// Example: conditional planning logic
shouldPlan := func(input string) bool {
    // Skip planner for simple greetings
    return len(input) > 50 || strings.Contains(input, "implement")
}

coord := agent.NewCoordinator(
    plannerProv,
    plannerSess,
    nil, nil, plannerOpts,
    execAgent,
    0.0,
    eventSink,
    shouldPlan, // Injected here
)

This optimization reduces latency and token consumption for interactions that do not require complex planning.

Unifying Configuration and Telemetry

Despite the session separation, the Coordinator ensures consistent configuration propagation. It forwards temperature, pricing, and language settings to the planner agent while maintaining the executor's independent configuration. Additionally, it forwards usage events to a shared event.Sink (lines 66-80 in internal/agent/coordinator.go), ensuring both models are accounted for uniformly in logging and billing systems.

Implementation Details in the Codebase

The Coordinator is instantiated in the CLI entry point defined in internal/boot/boot.go when a planner model is configured. The high-level command-line interface in internal/cli/cli.go references the Coordinator, noting that it "lives in internal/boot."

When running a task, the Coordinator's Run method executes the planning phase first, then hands the resulting plan to the executor:

ctx := context.Background()
if err := coord.Run(ctx, "Refactor the HTTP handler to use middleware"); err != nil {
    log.Fatalf("run failed: %v", err)
}

The unit tests in internal/agent/coordinator_test.go demonstrate typical behaviors including the plan-to-executor handoff, gating logic, and language reset scenarios.

Summary

• The Coordinator in esengine/DeepSeek-Reasonix acts as the central orchestrator for two-model collaboration, managing a planner and executor pair.
• It creates isolated sessions (plannerSess vs. executor session) to prevent prompt pollution and maintain cache stability.
• The hand-off mechanism uses the Reasonix executor handoff marker and executorHandoffGuard to prevent recursive planning.
• A shouldPlan callback allows conditional bypassing of the planner for trivial queries, optimizing token usage.
• Configuration and telemetry are unified through a shared event.Sink while keeping model-specific parameters distinct.

Frequently Asked Questions

How does the Coordinator prevent the executor from calling the planner recursively?

The Coordinator enables an executorHandoffGuard when handing the plan to the executor. As implemented in internal/agent/coordinator.go, this guard specifically prevents the executor—which has tool access and broader capabilities—from triggering planning logic during its execution phase, ensuring strict separation of concerns.

Can I skip the planner for simple queries?

Yes. The Coordinator accepts a shouldPlan callback parameter that evaluates each input before invoking the planner. If the callback returns false (for example, during greetings or simple questions), the Coordinator routes the request directly to the executor, bypassing the planner entirely to save tokens and reduce latency.

What is the difference between the planner session and the executor session?

The planner session is created fresh via agent.NewSession("planner") and maintains its own system prompt and cache state, separate from the executor's existing session. This isolation ensures that the planner's reasoning steps and the executor's tool-calling history do not interfere with each other, preserving context stability for both models.

Where is the Coordinator instantiated in the Reasonix codebase?

The Coordinator is constructed in internal/boot/boot.go when the CLI detects a planner model configuration. This boot logic wires together the planner provider, session, and executor agent, then exposes the Coordinator to the high-level CLI interface defined in internal/cli/cli.go.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}