Agent Orchestration

Agent Orchestration

ClusterSpace gives every pane an agent state: a role, status, current task, queue, and shared context. The AI can read and modify this state across panes — wait for one agent to finish before another starts, share findings, track progress.

Backend: src/main/agent-store.ts (per-pane state) and src/main/orchestration-store.ts (multi-pane goals + event log). UI: Fleet-Dashboard + PaneLabelWithAgent on every pane.

---

Per-pane agent state

Each pane gets a PaneAgentState:

{
  paneId: string,
  role: 'Builder' | 'Monitor' | 'Tester' | 'Deployer' | 'General',
  purpose: string,         // free-form description ("Build the dark mode toggle")
  status: 'idle' | 'working' | 'blocked' | 'complete' | 'error',
  currentTask: AgentTask | null,
  taskQueue: AgentTask[],
  taskHistory: AgentTask[],
  progress: { current: number, total: number, percentage: number },
  context: string[]        // snippets from sibling agents via share_context
}

State transitions are driven by AI tool calls (set_agent_role, assign_task, complete_task, fail_task, wait_for_agent, share_context) and surface in the pane label as a colored status dot + role badge + progress bar + current task preview.

Status dot color:

• gray — idle
• pulsing blue — working
• yellow — blocked (waiting for another agent)
• green — complete
• red — error

---

Roles

Role	Typical persona	Typical use
Builder	builder	Code writing, builds
Monitor	monitor	Watching logs, health
Tester	tester	Running test suites
Deployer	admin	Deployment steps
General	any	Default; mixed-use

Roles are advisory metadata — they don't restrict tool access. The actual tool restriction comes from Goal-Policy-and-Risk-Levels when running under a goal.

---

Multi-pane orchestration goals

Beyond per-pane agents, an OrchestrationGoal represents a higher-level objective that spans multiple panes:

{
  id: string,
  description: string,
  status: 'planning' | 'executing' | 'paused' | 'complete' | 'failed',
  assignedPanes: string[],
  taskBreakdown: AgentTask[],
  timeline: OrchestrationEvent[]
}

The model creates one via the create_goal tool, optionally assigning specific panes. The dashboard shows the active orchestration goal in its top-right card.

(Note: this is the multi-pane orchestration goal, separate from a single-pane Goal-Runner-Overview. The names are confusing but they live in different stores and address different use cases.)

---

Coordination primitives

wait_for_agent(waiting_pane_id, target_pane_id)

Marks the waiting agent as blocked. When the target completes a task, the waiting agent gets unblocked and resumes. Used for sequential dependencies (e.g., "tester waits until builder finishes").

complete_task(pane_id, task_id, result)

Marks the current task as complete, advances the queue, and unblocks every agent waiting on this pane.

share_context(from_pane_id, to_pane_id, context)

Pushes a formatted snippet into the destination agent's context array. The destination sees it on its next conversation turn as injected context. Useful for "builder, here's what tester found."

assign_task(pane_id, task)

Push a task onto a pane's queue. If the pane is idle, the task becomes currentTask immediately.

---

Event log

Every orchestration action emits an OrchestrationEvent (kept as a 500-entry ring buffer):

Type	Icon	Color
goal_created	+	gray
task_assigned	>	gray
task_started	▶	gray
task_completed	V	green
task_failed	X	red
pane_waiting	.	yellow
pane_unblocked	↑	yellow
coordination	⇄	gray
status_change	◇	gray

Live-streamed to the renderer via the ORCHESTRATION_EVENT IPC channel. Visible in the Fleet-Dashboard timeline.

---

Per-pane label rendering

PaneLabelWithAgent.tsx shows:

• Status dot (color-coded)
• Role badge (skipped if "General")
• Progress percentage (skipped if no current task)
• Current task title (truncated, hover for full)
• Waiting-for indicator (when blocked)

Reads state from AgentContext.getAgent(paneId).

---

When you'd use orchestration

Scenario	Pattern
Sequential work	builder writes code in pane A → wait_for_agent blocks tester pane B until builder finishes → builder calls complete_task → tester resumes and runs the suite
Parallel work with merge	three panes start in parallel; a fourth "merger" pane waits for all three; uses wait_for_agent × 3, then runs once unblocked
Information passing	scanner pane finds a bug; calls share_context to push the finding to the fixer pane; fixer's next turn sees it in context
Long-running monitor	monitor pane runs continuously with wait_for_output regex matching; on error fires share_context to alert another pane

---

See also

• Personas — what role each pane plays
• Task-Templates — multi-step workflows that assign roles
• Fleet-Dashboard — UI for watching it all happen
• AI-Tools-Reference — full tool signatures for orchestration
• Goal-Runner-Overview — single-pane autonomous mode (different system)