kandev/docs/task-session-turns.md

Task Session Turns: Table + Flow

This document describes how to add a turn table that groups all messages from a single agent turn, how messages link to a turn, and how turn updates propagate through the backend → event bus → WebSocket → frontend store.

Goals

• Add a task_session_turns table with at least id, started_at, completed_at.
• Ensure every task_session_message points to the turn it belongs to.
• Turn creation/completion follows existing app flow and broadcasts to subscribed clients.

Definitions

• Turn: A single prompt/response cycle for a task session, starting when a prompt is sent and ending when the agent completes/cancels/errors.
• Message: A persisted item in task_session_messages (user prompt, agent text, tool call, status, error).

Schema Changes (SQLite)

Add a new table and link messages to it.

New Table: task_session_turns

Suggested columns (minimum + useful metadata):

• id TEXT PRIMARY KEY (UUID).
• task_session_id TEXT NOT NULL (FK → task_sessions.id).
• task_id TEXT NOT NULL (denormalized for query fanout).
• started_at DATETIME NOT NULL.
• completed_at DATETIME (nullable).
• created_at DATETIME NOT NULL.
• updated_at DATETIME NOT NULL.
• metadata TEXT DEFAULT '{}' (optional, for provider-specific data like Codex turn_id).

Indexes:

• idx_turns_session_id on (task_session_id).
• idx_turns_session_started on (task_session_id, started_at).
• idx_turns_task_id on (task_id).
• Optional: partial index for active turn lookup (task_session_id) WHERE completed_at IS NULL.

Link Messages to Turns

Add a turn_id column to task_session_messages:

• turn_id TEXT (FK → task_session_turns.id).
• Index on (turn_id).
• Keep nullable for legacy messages; new writes should set it.

Files to update:

• apps/backend/internal/task/repository/sqlite.go (schema + migration via ensureColumn).
• apps/backend/internal/task/models/models.go (add Turn model, add TurnID to Message).
• apps/backend/pkg/api/v1/task.go and apps/web/lib/types/http.ts (API types include turn_id).

Backend Flow (Turn Lifecycle)

Turns should align with the prompt lifecycle already handled in the orchestrator and message services.

Create Turn

Create a turn when a prompt begins:

• Entry point: apps/backend/internal/orchestrator/service.go in PromptTask before calling executor.Prompt.
• Create task_session_turns row with started_at = now.
• Persist the new turn_id in memory for the rest of the prompt lifecycle.
  • Suggested: update task_sessions.metadata.active_turn_id and/or hold in the Executor/AgentExecution context.

Attach Messages to Turn

Ensure all messages created while a prompt is in-flight use the active turn_id.

Where messages are created today:

• User prompt: apps/backend/internal/task/handlers/message_handlers.go → MessageController.CreateMessage.
• Agent output + tool events: apps/backend/internal/orchestrator/service.go (saveAgentTextIfPresent, handleToolCallEvent, handleToolUpdateEvent, error/status creation).

Expected behavior:

• The user prompt message should reference the newly created turn_id.
• Subsequent agent/tool/status messages should use the same turn_id.
• If the session is resumed and no active turn exists, create a new turn before message creation.

Implementation sketch:

• Add TurnID to CreateMessageRequest (service/controller layers).
• Teach messageCreator.CreateAgentMessage/CreateToolCallMessage/CreateSessionMessage to accept a turn_id or resolve the current active turn by session_id.
• When the orchestrator receives agent stream events, it should pass turn_id to message creation calls.

Complete Turn

Close the turn when the agent finishes or the turn is cancelled:

• Completion: apps/backend/internal/orchestrator/service.go in handleAgentStreamEvent when eventType == "complete".
• Cancellation: apps/backend/internal/orchestrator/service.go in CancelAgent.
• Errors: Treat eventType == "error" as terminal if it ends the prompt; set completed_at.

Action:

• Update task_session_turns.completed_at = now, updated_at = now.
• Clear task_sessions.metadata.active_turn_id (if used).

Event Bus and WebSocket Broadcast

Turn updates should follow the same path as existing message/session events.

Event Types

Add new event types in apps/backend/internal/events/types.go:

• TurnStarted = "turn.started" (or task_session.turn.started).
• TurnCompleted = "turn.completed".
• Optional TurnUpdated = "turn.updated" for partial updates.

Publish Events

Publish turn events when you create/complete a turn:

• Location: task service or orchestrator service (same layer that writes to DB).
• Payload fields (minimum):
  • turn_id
  • session_id
  • task_id
  • started_at
  • completed_at

Broadcast to WebSocket Subscribers

Wire up in apps/backend/internal/gateway/websocket/task_notifications.go:

• Subscribe to the new event types.
• Broadcast to the session channel (same as session.message.added).

Add action constants in apps/backend/pkg/websocket/actions.go:

• ActionSessionTurnStarted = "session.turn.started"
• ActionSessionTurnCompleted = "session.turn.completed"
• Optional ActionSessionTurnUpdated = "session.turn.updated"

Frontend Flow

Frontend store and handlers should mirror the current message flow.

WebSocket Handlers

Add a new WS handler file (or extend existing):

• apps/web/lib/ws/handlers/turns.ts to handle:
  • session.turn.started
  • session.turn.completed
• Store updates should be keyed by session_id.

Store Shape

Add a turns slice in apps/web/lib/state/store.ts:

• turns.bySession[sessionId] = Turn[]
• turns.activeBySession[sessionId] = Turn | null (optional for UI)

Message Rendering

Messages already render from messages.bySession[sessionId]. With turn_id:

• Allow grouping in UI by turn.
• Allow filtering by active turn.
• Show turn duration in the UI (e.g., "running for 42s") by comparing started_at to now for active turns.

SSR Data

If needed for initial render:

• Add an HTTP endpoint to list turns for a session.
• SSR fetch in apps/web/app/task/[id]/page-client.tsx or equivalent (see docs/session-page-data-flow.md).

Migration / Backfill

Existing messages will not have turn_id:

• Keep turn_id nullable.
• Optional backfill: create one turn per session using min/max message timestamps and assign messages with NULL turn_id to that turn.

Edge Cases

• Multiple prompts queued: Ensure only one active turn per session. If prompts can overlap, add a state column or queue ID.
• Agent error before messages: Start turn on prompt, complete on error even if no agent messages.
• Permission requests: If the agent pauses for permission, the turn remains open; completion happens after prompt completion or cancellation.
• Concurrency: Multiple sessions can run in parallel without conflict as long as turns and broadcasts stay scoped by session_id (and active_turn_id is per session).

Touchpoints Summary

Backend:

• apps/backend/internal/task/models/models.go (Turn model, Message.TurnID)
• apps/backend/internal/task/repository/sqlite.go (schema + queries)
• apps/backend/internal/task/repository/interface.go (turn methods)
• apps/backend/internal/task/service/service.go (turn create/complete, message association)
• apps/backend/internal/orchestrator/service.go (prompt start/complete)
• apps/backend/internal/events/types.go (turn events)
• apps/backend/internal/gateway/websocket/task_notifications.go (broadcast)
• apps/backend/pkg/websocket/actions.go (actions)

Frontend:

• apps/web/lib/ws/handlers/turns.ts (WS handlers)
• apps/web/lib/state/store.ts (turns slice)
• apps/web/lib/types/http.ts (Turn + Message.turn_id)
• apps/web/components/task/chat/* (optional turn grouping UI)

Docs:

• docs/WEBSOCKET_API.md (document new turn actions and payloads).