Agents Documentation

ℹMental model

A thread is the durable conversation. A session is one executable run. Trace events are the timeline that make the run understandable in the dashboard.

In agents, a thread is the durable conversation container and a session is an executable run attached to that thread. Trace events are the lifecycle feed that make the dashboard readable.

Mental model

Thread

Conversation container, title, status, project, and first message.

packages/backend/convex/agentSystem/threads.ts

Session

Concrete run on a machine with agent, status, timestamps, and optional thread binding.

packages/backend/convex/agentSystem/sessions.ts

Trace event

Timeline event used to reconstruct progress, state transitions, and transcript-like playback.

packages/backend/convex/agentSystem/traceEvents.ts

Dispatch flow

1. Web UI creates or selects a thread
2. Web UI calls agentSystem.dispatch.dispatch
3. Convex creates a queued session and active trace
4. agents work polls listQueued
5. Local ActiveSessionManager starts the real agent process
6. Sync and trace events feed the dashboard transcript

Key source files

Thread creation: packages/backend/convex/agentSystem/threads.ts
Web dispatch mutation: packages/backend/convex/agentSystem/dispatch.ts
Local poller: packages/cli/src/cli/commands/work.ts
Thread transcript renderer: apps/app/src/components/thread-conversation.tsx
Session detail surface: apps/app/src/components/session-detail-overlay.tsx

UI surfaces

Thread detail

/threads/[id] renders the full transcript for a thread and replays user messages, assistant output, system lifecycle markers, and typing state.

Project detail

/projects/[name] shows sessions scoped to a project. Clicking a session opens a detail surface:

if the session is linked to a thread, the drawer shows the conversation transcript
if not, it falls back to recent session trace events

That behavior keeps session rows from feeling dead, even when transcript data is missing.

Practical operator loop

dispatch work from the dashboard
keep agents work running locally
watch queued sessions turn into running or completed sessions
inspect the transcript or trace fallback when something goes wrong

Sessions