kandev/docs/agent-orchestration-ui.md

# Agent Orchestration + Session UI Data Flow

This document describes how a task session is created, how agentctl/agent lifecycle events flow through the backend, and how the session details page consumes those events.

## Overview (Actors)

- **Client UI**: Next.js app with session details page and panels (chat, terminal, git, files).
- **Backend**: Orchestrator + WebSocket gateway + task/session store.
- **agentctl**: Sidecar HTTP/WS server inside agent container (or standalone process) that manages the agent subprocess and exposes ACP + workspace streams.
- **Agent**: ACP-speaking process (JSON-RPC over stdin/stdout) that performs work.

## Orchestration Flow (Task Session Creation)

```
Client UI
  |  HTTP: POST /api/v1/tasks { start_agent: true, agent_profile_id }
  v
Backend Task Service
  |  create task + first session
  |  start agentctl orchestration
  |  create task_session (STARTING)
  |  launch agentctl (container or standalone)
  |  wait for /health
  |  POST /api/v1/start
  |  POST /api/v1/acp/call initialize
  |  POST /api/v1/acp/call session/new
  |  POST /api/v1/acp/call session/prompt
  v
agentctl
  |  spawns agent process
  |  streams ACP updates + workspace streams
  v
Agent
  |  ACP notifications (session/update)
  v
agentctl -> Backend
  |  ACP update stream -> backend
  |  backend updates task_session state + messages
  |  backend publishes WS notifications
  v
Client UI
  |  session.subscribe
  |  receive session-scoped events
```

## Backend Event Routing (Session Scoped)

Events are now routed primarily by **session_id**. The WS gateway maintains **session subscriber lists**. It broadcasts session events only to clients subscribed to that session.

```
agentctl WS /api/v1/acp/stream
  -> backend ACP handler
     -> task_session state update
     -> message persisted
     -> WS broadcast: session.channel

agentctl WS /api/v1/workspace/git-status/stream
  -> backend git-status handler
     -> attach to session
     -> WS broadcast: session.channel

agentctl WS /api/v1/output/stream
  -> backend shell handler
     -> session resolve (session_id -> task_id)
     -> WS broadcast: session.channel
```

Session notifications:
- `session.agentctl_starting`
- `session.agentctl_ready`
- `session.agentctl_error`
- `session.state_changed`
- `session.message.added`, `session.message.updated`
- `session.shell.output`, `session.shell.status`
- `session.git.status`
- `session.workspace.file.changes`

## Frontend Session Page Flow (SSR + WS)

```
Server (SSR)
  - fetch session by id
  - fetch parent task + workspace context
  - hydrate store (tasks, sessions, repos, agent profiles)

Client (Hydrated)
  - read sessionId from URL (/s/:sessionId)
  - set activeSessionId in store
  - subscribe to session events
  - child components read from store + hooks
```

### Component Subscriptions

Each component subscribes to the data it needs via hooks. The **WS client deduplicates subscriptions** so multiple components can safely request the same channel.

```
TaskSessionPage (/s/:sessionId)
  -> useSession(sessionId)
     -> subscribe: session.{sessionId}

  TaskChatPanel
    -> useSessionMessages(sessionId)
       -> subscribe: session.{sessionId}

  ShellTerminal
    -> useSessionAgentctl(sessionId)
       -> subscribe: session.{sessionId}
    -> useShellOutput(sessionId)
       -> subscribe: session.{sessionId}

  TaskChangesPanel (Git)
    -> useSessionGitStatus(sessionId)
       -> subscribe: session.{sessionId}

  TaskFilesPanel
    -> useSessionAgentctl(sessionId)
       -> wait for readiness
    -> useSessionWorktrees(sessionId)
       -> subscribe: session.{sessionId}
```

## Event + State Flow Diagram

```
Agent
  | ACP session/update
  v
agentctl
  | WS /api/v1/acp/stream
  v
Backend ACP handler
  | update session state/messages
  | emit session WS events
  v
WS Gateway (session subscribers)
  | broadcast to session.{sessionId}
  v
WebSocket Client (browser)
  | dedupe subscription
  | route to store slice
  v
Zustand Store
  | sessions, messages, shell, git, worktrees
  v
Session UI Panels
  | hook selectors
  | render
```

## Concrete Example: New Session -> Message Appears In Chat

Scenario: user starts a task session and the agent replies with a completion message that appears in the chat panel.

### Sequence (Calls + Events)

1) Client -> Backend (HTTP request)
```
POST /api/v1/tasks
body:
  title: "Example task"
  workspace_id: "workspace-1"
  repository_id: "repo-9"
  agent_profile_id: "profile-abc"
  start_agent: true
```

2) Backend (internal)
- creates task
- creates first task session
- starts agentctl orchestration for the new session
- returns session_id in the HTTP response

3) Backend -> agentctl (HTTP)
- `POST /api/v1/start`
- `POST /api/v1/acp/call` initialize
- `POST /api/v1/acp/call` session/new
- `POST /api/v1/acp/call` session/prompt

4) Backend -> Client (WS notification)
```
action: session.agentctl_starting
payload:
  task_id: "task-123"
  session_id: "session-789"
```

5) Client subscribes to session
```
action: session.subscribe
payload:
  session_id: "session-789"
```

6) agentctl -> Backend (ACP notification)
```
jsonrpc: "2.0"
method: "session/update"
params:
  type: "content"
  data:
    text: "Working on your request..."
    session_id: "session-789"
```

7) Backend -> Client (WS notification)
```
action: session.message.added
payload:
  session_id: "session-789"
  message:
    id: "msg-1"
    author_type: "agent"
    content: "Working on your request..."
```

8) Client store update (message handler)
```
messages.bySession["session-789"] += message
```

9) Chat panel render
```
TaskChatPanel -> useSessionMessages("session-789") -> messages list -> render
```

### Full Event List (Typical Session Start)

- HTTP request: `POST /api/v1/tasks` with `start_agent: true`
- WS notification: `session.agentctl_starting`
- WS request: `session.subscribe`
- WS notification: `session.agentctl_ready`
- ACP notifications from agent:
  - `session/update` (content/toolCall/complete/error)
- WS notifications:
  - `session.message.added`
  - `session.message.updated`
  - `session.state_changed`
  - `session.shell.status` / `session.shell.output` (if shell active)
  - `session.git.status` (if git watcher active)
  - `session.workspace.file.changes` (if watcher active)

## Notes / Guardrails

- Session is the source of truth; task id is derived from session when needed.
- No fallback to “active task” or “first message” for session ownership.
- Agentctl readiness is explicit; panels that require a live agent should wait for `agentctl_ready`.
- Store slices are keyed by session id (messages, shell output, git status, worktrees).
- WS subscriptions are **session-scoped** and **deduplicated** at the client level.