kandev/docs/relation-events.md

Relationship Events LLD

This document defines backend-driven state propagation and how WS notifications mirror those changes to the UI. Clients do not emit these events.

Core Rules

1. Session state changes drive task state changes.
2. Agentctl lifecycle changes drive session state changes, which then drive task state changes.
3. Task state changes may move columns, but only between In Progress and Review for now.

All state propagation happens server-side on internal events. WebSocket events are outbound mirrors for UI synchronization.

---

1) Session State -> Task State

Trigger (backend only)

• events.TaskSessionStateChanged (internal event bus)

Flow

1. Resolve task_id from session_id.
2. Map TaskSessionState -> TaskState (table below).
3. If task state changes, call taskSvc.UpdateTaskState(taskID, newState).
4. Emit events.TaskStateChanged and WS task.state_changed.
5. Emit WS session.state_changed for clients.

Mapping Table

TaskSessionState	TaskState	Board Column
CREATED	SCHEDULING	In Progress (if any)
STARTING	SCHEDULING	In Progress (if any)
RUNNING	IN_PROGRESS	In Progress
WAITING_FOR_INPUT	REVIEW	Review
COMPLETED	REVIEW	Review
ERROR	ERROR	(no auto-move)
CANCELLED	CANCELLED	(no auto-move)

Notes:

• WAITING_FOR_INPUT -> REVIEW and COMPLETED -> REVIEW are the default paths. If a board has no Review column, keep task in its current column.
• If the mapped task state equals current task state, do nothing.

---

2) Agentctl State -> Session State -> Task State

Triggers (backend only)

• events.AgentctlStarting
• events.AgentctlReady
• events.AgentctlError

Agentctl -> Session Mapping

Agentctl Event	Session State
AgentctlStarting	STARTING
AgentctlReady	RUNNING
AgentctlError	FAILED

Flow

1. On Agentctl event, update session state in DB.
2. Emit events.TaskSessionStateChanged (which triggers session->task mapping).
3. Emit WS session.agentctl_* and session.state_changed.

---

3) Task State -> Column Move

Trigger (backend only)

• events.TaskStateChanged

Policy (for now)

• Only move tasks between In Progress and Review.
• Do not auto-move for other states.

Flow

1. When task state changes:
   • If new state is IN_PROGRESS, move to column mapped to In Progress (if exists).
   • If new state is REVIEW, move to column mapped to Review (if exists).
2. If column lookup fails or column already matches, do nothing.
3. Emit events.TaskUpdated and WS task.updated with new column_id.

---

WebSocket Notifications (Outbound Only)

• session.state_changed
• session.agentctl_starting
• session.agentctl_ready
• session.agentctl_error
• task.state_changed
• task.updated

Clients should treat these as read-only state mirrors.

---

E2E Flow (Client-Initiated)

Edge Trigger (Client)	Backend Action	Internal Event(s)	WS Notification(s)
POST /api/v1/tasks (start_agent: true)	Create task + create session + start agentctl	task.created, task_session.created	task.created, session.agentctl_starting
POST /api/v1/tasks (start_agent: false)	Create task + create session (idle)	task.created, task_session.created	task.created
message.add (session message)	Persist message + prompt agent via ACP	message.added	session.message.added
task.state (manual update)	Update task state	task.state_changed	task.state_changed, task.updated (column move)
task.session.resume	Resume session + start agentctl	task_session.state_changed	session.agentctl_starting, session.state_changed

Notes:

• Column move only occurs for IN_PROGRESS / REVIEW transitions.

---

E2E Flow (Agent / agentctl-Initiated)

Edge Trigger (Agent/agentctl)	Backend Action	Internal Event(s)	WS Notification(s)
Agentctl starting	Update session state → STARTING	task_session.state_changed	session.agentctl_starting, session.state_changed
Agentctl ready	Update session state → RUNNING	task_session.state_changed	session.agentctl_ready, session.state_changed
Agentctl error	Update session state → ERROR	task_session.state_changed	session.agentctl_error, session.state_changed
ACP content/progress	Create/append message chunks	message.added / message.updated	session.message.added / session.message.updated
ACP input_required	Create message (requests_input=true)	message.added	session.message.added + session.waiting_for_input
Git status stream update	Update session git status	git.status.updated	session.git.status
Workspace file change stream	Update session file activity	workspace.file.changed	session.workspace.file.changes
Shell output stream	Append shell output	shell.output	session.shell.output