Overview
T3 Code server architecture is built on Effect’s service layer pattern, providing composable, type-safe service contracts for orchestration, provider management, and persistence.Orchestration Services
OrchestrationEngineService
Command and event orchestration engine that owns command validation, dispatch, and read-model management. Service Tag:t3/orchestration/Services/OrchestrationEngine/OrchestrationEngineService
Source: apps/server/src/orchestration/Services/OrchestrationEngine.ts:77
Methods
Read the current in-memory orchestration read modelReturns: Latest read model snapshot containing projects, threads, turns, and messages.Errors: Never fails
readEvents
(fromSequenceExclusive: number) => Stream<OrchestrationEvent, OrchestrationEventStoreError>
Replay persisted orchestration events from an exclusive sequence cursorParameters:
fromSequenceExclusive: Sequence cursor (exclusive start)
OrchestrationEventStoreError on persistence failuresdispatch
(command: OrchestrationCommand) => Effect<{ sequence: number }, OrchestrationDispatchError>
Dispatch a validated orchestration commandDispatch is serialized through an internal queue and deduplicated via command receipts.Parameters:
command: Valid orchestration command
OrchestrationDispatchError on validation or persistence failuresStream persisted domain events in dispatch orderThis is a hot runtime stream (new events only), not a historical replay.Returns: Live stream of orchestration events
Example Usage
ProjectionSnapshotQuery
Read-model snapshot query service for retrieving the latest orchestration projection state. Service Tag:t3/orchestration/Services/ProjectionSnapshotQuery
Source: apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts:31
Methods
Read the latest orchestration projection snapshotRehydrates from projection tables and derives snapshot sequence from projector cursor state.Returns: Complete read model with projects, threads, turns, messages, and checkpointsErrors:
ProjectionRepositoryError on database failuresExample Usage
OrchestrationProjectionPipeline
Event projection pipeline that coordinates projection bootstrap and per-event projection updates. Service Tag:t3/orchestration/Services/ProjectionPipeline/OrchestrationProjectionPipeline
Source: apps/server/src/orchestration/Services/ProjectionPipeline.ts:39
Methods
Bootstrap projections by replaying persisted eventsResumes each projector from its stored projection-state cursor.Errors:
ProjectionRepositoryError on database failuresProject a single orchestration event into projection repositoriesProjectors are executed sequentially to preserve deterministic ordering.Parameters:
event: Orchestration event to project
ProjectionRepositoryError on database failuresProviderRuntimeIngestionService
Background workers that consume provider runtime streams and emit orchestration commands/events. Service Tag:t3/orchestration/Services/ProviderRuntimeIngestion/ProviderRuntimeIngestionService
Source: apps/server/src/orchestration/Services/ProviderRuntimeIngestion.ts:31
Methods
Start ingesting provider runtime events into orchestration commandsMust be run in a scope so all worker fibers can be finalized on shutdown. Uses an internal queue and continues after non-interrupt failures by logging warnings.Requires:
Scope.Scope contextCheckpointReactor
Background workers that react to orchestration checkpoint lifecycle events and apply checkpoint side effects. Service Tag:t3/orchestration/Services/CheckpointReactor
Source: apps/server/src/orchestration/Services/CheckpointReactor.ts:31
Methods
Start the checkpoint reactorMust be run in a scope so all worker fibers can be finalized on shutdown. Consumes both orchestration-domain and provider-runtime events via an internal queue.Requires:
Scope.Scope contextProviderCommandReactor
Background workers that react to orchestration intent events and dispatch provider-side command execution. Service Tag:t3/orchestration/Services/ProviderCommandReactor
Source: apps/server/src/orchestration/Services/ProviderCommandReactor.ts:31
Methods
Start reacting to provider-intent orchestration domain eventsMust be run in a scope so all worker fibers can be finalized on shutdown. Filters orchestration domain events to provider-intent types before processing.Requires:
Scope.Scope contextProvider Services
ProviderService
Cross-provider facade for provider sessions, turns, and checkpoints. Routes session-scoped calls viaProviderSessionDirectory and exposes one unified provider event stream.
Service Tag: t3/provider/Services/ProviderService
Source: apps/server/src/provider/Services/ProviderService.ts:113
Methods
startSession
(threadId: ThreadId, input: ProviderSessionStartInput) => Effect<ProviderSession, ProviderServiceError>
Start a provider sessionParameters:
threadId: Thread identifierinput: Session configuration including provider, model, and runtime settings
ProviderServiceError on adapter resolution or session startup failuresSend a provider turnParameters:
input: Turn configuration including thread ID, messages, and sampling parameters
ProviderServiceError on session not found or turn dispatch failuresInterrupt a running provider turnParameters:
input: Thread ID and optional turn ID
ProviderServiceError on session not found or interrupt failuresRespond to a provider approval requestParameters:
input: Request ID, thread ID, and approval decision
ProviderServiceError on session not found or response failuresRespond to a provider structured user-input requestParameters:
input: Request ID, thread ID, and user input answers
ProviderServiceError on session not found or response failuresStop a provider sessionParameters:
input: Thread ID to stop
ProviderServiceError on session not found or stop failuresList active provider sessionsAggregates runtime session lists from all registered adapters.Returns: Array of active provider sessions
getCapabilities
(provider: ProviderKind) => Effect<ProviderAdapterCapabilities, ProviderServiceError>
Read static capabilities for a provider adapterParameters:
provider: Provider kind (e.g.,"codex")
ProviderServiceError on unsupported providerrollbackConversation
(input: { threadId: ThreadId, numTurns: number }) => Effect<void, ProviderServiceError>
Roll back provider conversation state by a number of turnsParameters:
threadId: Thread identifiernumTurns: Number of turns to roll back
ProviderServiceError on session not found or rollback failuresCanonical provider runtime event streamFan-out is owned by ProviderService (not by a standalone event-bus service).Returns: Live stream of provider runtime events
Example Usage
ProviderAdapter
Provider-specific runtime adapter contract defining session and protocol operations. Source:apps/server/src/provider/Services/ProviderAdapter.ts
ProviderAdapterCapabilities
Declares whether changing the model on an existing session is supported
"in-session": Model can be changed without restarting"restart-session": Model change requires session restart"unsupported": Model switching not supported
ProviderAdapterShape Interface
Provider adapters must implement:startSession: Start a provider-backed sessionsendTurn: Send a turn to an active sessioninterruptTurn: Interrupt an active turnrespondToRequest: Respond to an approval requestrespondToUserInput: Respond to a user-input requeststopSession: Stop one provider sessionlistSessions: List active sessions for this adapterhasSession: Check if adapter owns a sessionreadThread: Read provider thread snapshotrollbackThread: Roll back thread by N turnsstopAll: Stop all sessions owned by adapterstreamEvents: Canonical runtime event stream
Layer Construction
makeServerProviderLayer
Constructs the provider service layer with adapter registry and session management. Source:apps/server/src/serverLayers.ts:39
SqlClient.SqlClientServerConfigFileSystem.FileSystemAnalyticsService
ProviderService
May Error: ProviderUnsupportedError
makeServerRuntimeServicesLayer
Constructs all runtime service layers including orchestration, git, terminal, and keybindings. Source:apps/server/src/serverLayers.ts:70
OrchestrationReactorGitCoreGitManagerTerminalManagerKeybindings
