Events - T3 Code

Overview

Domain events represent facts about what has happened in the system. They are the single source of truth and are persisted to the event store. The read model is derived by projecting these events.

Event Structure

All events share these base fields:

sequence

number

required

Global event sequence number (monotonically increasing)

eventId

string

required

Unique event identifier (UUID)

aggregateKind

'project' | 'thread'

required

Type of aggregate root

aggregateId

string

required

Aggregate instance identifier (projectId or threadId)

type

string

required

Event type discriminator (e.g., "project.created")

occurredAt

string

required

ISO 8601 timestamp when event occurred

commandId

string | null

required

Command that caused this event (null for spontaneous events)

causationEventId

string | null

required

Event that caused this event (for cascading effects)

correlationId

string | null

required

Original command ID for tracking related events

metadata

object

required

Additional event metadata

Show Metadata structure

providerTurnId

string

Provider’s internal turn identifier

providerItemId

string

Provider’s item/tool identifier

adapterKey

string

Provider adapter key

requestId

string

Approval/user-input request ID

ingestedAt

string

When event was ingested by server

payload

object

required

Event-specific data

Push Event Format

Events are broadcast to clients via the orchestration.domainEvent channel:

{
  "type": "push",
  "channel": "orchestration.domainEvent",
  "data": {
    "sequence": 43,
    "eventId": "evt-abc123",
    "aggregateKind": "thread",
    "aggregateId": "thread-789",
    "type": "thread.created",
    "occurredAt": "2026-03-07T12:00:00.000Z",
    "commandId": "cmd-xyz",
    "causationEventId": null,
    "correlationId": "cmd-xyz",
    "metadata": {},
    "payload": {
      "threadId": "thread-789",
      "projectId": "proj-456",
      "title": "New conversation",
      "model": "gpt-5-codex",
      "runtimeMode": "full-access",
      "interactionMode": "default",
      "branch": null,
      "worktreePath": null,
      "createdAt": "2026-03-07T12:00:00.000Z",
      "updatedAt": "2026-03-07T12:00:00.000Z"
    }
  }
}

Project Events

project.created

A new project has been created.

Show Payload fields

projectId

string

required

title

string

required

workspaceRoot

string

required

defaultModel

string | null

required

scripts

array

required

createdAt

string

required

updatedAt

string

required

project.meta-updated

Project metadata has been updated.

Show Payload fields

projectId

string

required

title

string

New title (if changed)

workspaceRoot

string

New workspace root (if changed)

defaultModel

string | null

New default model (if changed)

scripts

array

New scripts (if changed)

updatedAt

string

required

project.deleted

A project has been soft-deleted.

Show Payload fields

projectId

string

required

deletedAt

string

required

Thread Lifecycle Events

thread.created

A new thread has been created.

Show Payload fields

threadId

string

required

projectId

string

required

title

string

required

model

string

required

runtimeMode

'approval-required' | 'full-access'

required

interactionMode

'default' | 'plan'

required

branch

string | null

required

worktreePath

string | null

required

createdAt

string

required

updatedAt

string

required

thread.deleted

A thread has been soft-deleted.

Show Payload fields

threadId

string

required

deletedAt

string

required

thread.meta-updated

Thread metadata has been updated.

Show Payload fields

threadId

string

required

title

string

New title (if changed)

model

string

New model (if changed)

branch

string | null

New branch (if changed)

worktreePath

string | null

New worktree path (if changed)

updatedAt

string

required

thread.runtime-mode-set

Thread runtime mode has changed.

Show Payload fields

threadId

string

required

runtimeMode

'approval-required' | 'full-access'

required

updatedAt

string

required

thread.interaction-mode-set

Thread interaction mode has changed.

Show Payload fields

threadId

string

required

interactionMode

'default' | 'plan'

required

updatedAt

string

required

Message Events

thread.message-sent

A message has been added to the thread.

Show Payload fields

threadId

string

required

messageId

string

required

role

'user' | 'assistant' | 'system'

required

text

string

required

Message content

attachments

array

Image attachments

turnId

string | null

required

Associated turn ID

streaming

boolean

required

Whether message is still streaming

createdAt

string

required

updatedAt

string

required

Assistant messages may be sent incrementally with streaming: true, followed by a final event with streaming: false.

Turn Events

thread.turn-start-requested

A user has requested to start a new turn.

Show Payload fields

threadId

string

required

messageId

string

required

provider

'codex'

Provider to use

model

string

Model override

serviceTier

'fast' | 'flex' | null

Service tier

modelOptions

object

Provider-specific model options

assistantDeliveryMode

'buffered' | 'streaming'

Delivery mode

runtimeMode

'approval-required' | 'full-access'

required

interactionMode

'default' | 'plan'

required

createdAt

string

required

thread.turn-interrupt-requested

A user has requested to interrupt the active turn.

Show Payload fields

threadId

string

required

turnId

string

Specific turn to interrupt

createdAt

string

required

thread.turn-diff-completed

A turn has completed and its checkpoint/diff has been recorded.

Show Payload fields

threadId

string

required

turnId

string

required

checkpointTurnCount

number

required

Total turns at this checkpoint

checkpointRef

string

required

Git reference (commit SHA, branch, or tag)

status

'ready' | 'missing' | 'error'

required

Checkpoint status

files

array

required

Array of changed files

Show File structure

path

string

Relative file path

kind

string

Change type (added/modified/deleted)

additions

number

Lines added

deletions

number

Lines deleted

assistantMessageId

string | null

required

Associated assistant message

completedAt

string

required

Session Events

thread.session-set

Provider session state has been updated.

Show Payload fields

threadId

string

required

session

object

required

Session state object

Show Session structure

threadId

string

required

status

string

required

One of: idle, starting, running, ready, interrupted, stopped, error

providerName

string | null

required

Provider name (e.g., “codex”)

runtimeMode

'approval-required' | 'full-access'

required

activeTurnId

string | null

required

Currently active turn

lastError

string | null

required

Last error message

updatedAt

string

required

thread.session-stop-requested

A user has requested to stop the session.

Show Payload fields

threadId

string

required

createdAt

string

required

Approval & User Input Events

thread.approval-response-requested

A user has responded to a provider approval request.

Show Payload fields

threadId

string

required

requestId

string

required

decision

'accept' | 'acceptForSession' | 'decline' | 'cancel'

required

createdAt

string

required

thread.user-input-response-requested

A user has responded to a provider user input request.

Show Payload fields

threadId

string

required

requestId

string

required

answers

object

required

Key-value map of answers

createdAt

string

required

Checkpoint Events

thread.checkpoint-revert-requested

A user has requested to revert to a previous checkpoint.

Show Payload fields

threadId

string

required

turnCount

number

required

Number of turns to revert

createdAt

string

required

thread.reverted

A checkpoint revert has been completed.

Show Payload fields

threadId

string

required

turnCount

number

required

Number of turns reverted

Activity Events

thread.activity-appended

A new activity log entry has been added to the thread.

Show Payload fields

threadId

string

required

activity

object

required

Activity log entry

Show Activity structure

string

required

Activity event ID

tone

'info' | 'tool' | 'approval' | 'error'

required

Visual tone/severity

kind

string

required

Activity kind (e.g., “tool_call”, “approval_requested”)

summary

string

required

Human-readable summary

payload

unknown

required

Activity-specific data

turnId

string | null

required

Associated turn

sequence

number

Sequence within turn

createdAt

string

required

thread.proposed-plan-upserted

A provider has proposed or updated a plan.

Show Payload fields

threadId

string

required

proposedPlan

object

required

Proposed plan object

Show Plan structure

string

required

Plan identifier

turnId

string | null

required

Associated turn

planMarkdown

string

required

Plan description in markdown

createdAt

string

required

updatedAt

string

required

Event Ordering

Events are guaranteed to be:

Globally ordered by sequence number
Per-aggregate ordered within their stream
Causally ordered via causationEventId and correlationId

Event Replay

Use the orchestration.replayEvents method to replay events:

const request = {
  id: crypto.randomUUID(),
  body: {
    _tag: 'orchestration.replayEvents',
    fromSequenceExclusive: 0, // Start from beginning
  },
};

ws.send(JSON.stringify(request));

This is useful for:

Building read models
Catching up after reconnection
Debugging state issues
Implementing event handlers

Source Code

Event schemas are defined in:

Contracts: packages/contracts/src/orchestration.ts:557-982
Event Store: apps/server/src/orchestration/Services/EventStore.ts
Projections: apps/server/src/orchestration/Projections/
Push Broadcast: apps/server/src/wsServer.ts:577-583

Next Steps

Commands

Learn about commands that generate events

Orchestration API

Explore the full orchestration API

WebSocket Protocol

Understand the transport layer

WebSocket API

Contracts

Server API

​Overview

​Event Structure

​Push Event Format

​Project Events

​project.created

​project.meta-updated

​project.deleted

​Thread Lifecycle Events

​thread.created

​thread.deleted

​thread.meta-updated

​thread.runtime-mode-set

​thread.interaction-mode-set

​Message Events

​thread.message-sent

​Turn Events

​thread.turn-start-requested

​thread.turn-interrupt-requested

​thread.turn-diff-completed

​Session Events

​thread.session-set

​thread.session-stop-requested

​Approval & User Input Events

​thread.approval-response-requested

​thread.user-input-response-requested

​Checkpoint Events

​thread.checkpoint-revert-requested

​thread.reverted

​Activity Events

​thread.activity-appended

​thread.proposed-plan-upserted

​Event Ordering

​Event Replay

​Source Code

​Next Steps

Commands

Orchestration API

WebSocket Protocol

Build docs developers (and LLMs) love

Overview

Event Structure

Push Event Format

Project Events

project.created

project.meta-updated

project.deleted

Thread Lifecycle Events

thread.created

thread.deleted

thread.meta-updated

thread.runtime-mode-set

thread.interaction-mode-set

Message Events

thread.message-sent

Turn Events

thread.turn-start-requested

thread.turn-interrupt-requested

thread.turn-diff-completed

Session Events

thread.session-set

thread.session-stop-requested

Approval & User Input Events

thread.approval-response-requested

thread.user-input-response-requested

Checkpoint Events

thread.checkpoint-revert-requested

thread.reverted

Activity Events

thread.activity-appended

thread.proposed-plan-upserted

Event Ordering

Event Replay

Source Code

Next Steps