Platform Services

Diminuendo is a pure gateway. It does not execute agent code, does not invoke tools, and does not call language models. Those responsibilities belong to three upstream platform services — Podium, Chronicle, and Ensemble — each accessed through an Effect service with circuit-breaker resilience, exponential retry, and health probing. The gateway’s role is to mediate: it translates between the client-facing wire protocol and the platform services’ internal APIs, maps events from one vocabulary to another, and ensures that transient failures in any upstream service degrade gracefully rather than cascading into the client connection.

Podium
Chronicle
Ensemble

Podium: Agent Orchestration

Podium is the agent orchestration platform that manages compute instances, agent lifecycles, and message routing. Diminuendo connects to Podium as an upstream service — creating compute instances for coding agents, establishing WebSocket connections to stream events, and proxying file operations to agent workspaces.

PodiumClient

The PodiumClient is an Effect service (Context.Tag) that encapsulates all communication with the Podium coordinator. It provides five core operations:

export class PodiumClient extends Context.Tag("PodiumClient")<PodiumClient, {
  readonly createInstance: (params: {
    agentType: string
    agentId?: string
    secrets?: Record<string, string>
    environment?: Record<string, string>
  }) => Effect.Effect<{ instanceId: string; deploymentId: string }, PodiumConnectionError>

  readonly connect: (instanceId: string) =>
    Effect.Effect<PodiumConnection, PodiumConnectionError>

  readonly isAlive: (instanceId: string) => Effect.Effect<boolean>

  readonly stopInstance: (instanceId: string) =>
    Effect.Effect<void, PodiumConnectionError>

  readonly listFiles: (instanceId: string, path?: string, depth?: number) =>
    Effect.Effect<FileEntry[], PodiumConnectionError>
  readonly readFile: (instanceId: string, path: string) =>
    Effect.Effect<FileContent, PodiumConnectionError>
  readonly fileHistory: (instanceId: string, path: string) =>
    Effect.Effect<IterationMeta[], PodiumConnectionError>
  readonly fileAtIteration: (instanceId: string, path: string, iteration: number) =>
    Effect.Effect<FileContent, PodiumConnectionError>
}>() {}

The PodiumClientLive layer reads PODIUM_URL and PODIUM_API_KEY from the application config and provides the concrete implementation.

Instance Lifecycle

The lifecycle of an agent instance follows a predictable four-phase pattern:

Create Instance

When a user starts a session or an inactive session is reactivated, the gateway calls createInstance with the agent type, deployment descriptor, secrets, and environment variables.

POST /api/v1/instances
{
  "deployment_id": "coding-agent:1.0.0@local",
  "agent_id": "optional-agent-id",
  "secrets": { ... },
  "environment": { ... }
}
--> { "instance_id": "inst-abc123", "deployment_id": "..." }

The deployment ID is constructed as {agentType}:1.0.0@local from the session’s agent type.

Connect via WebSocket

After instance creation, the gateway establishes a WebSocket connection to the instance’s event stream:

ws://{PODIUM_URL}/api/v1/instances/{instanceId}/connect

This returns a PodiumConnection object with methods to send messages, access the event stream, and close the connection.

Stream Events and Send Messages

The connection remains open for the duration of the session. Messages from the user are sent via sendMessage(content). Events from the agent arrive through the events stream (Stream.Stream<PodiumEvent>).

Stop Instance

When a session is deactivated or the gateway shuts down, the instance is stopped:

DELETE /api/v1/instances/{instanceId}

A 404 response is treated as success — the instance may have already been reclaimed by Podium.

PodiumConnection

The PodiumConnection interface represents an active WebSocket connection to a Podium instance:

export interface PodiumConnection {
  readonly instanceId: string
  readonly sendMessage: (content: string, metadata?: Record<string, unknown>) =>
    Effect.Effect<void, PodiumConnectionError>
  readonly sendRaw: (data: string) =>
    Effect.Effect<void, PodiumConnectionError>
  readonly events: Stream.Stream<PodiumEvent, PodiumConnectionError>
  readonly close: Effect.Effect<void>
}

Messages are sent as JSON with a process_message envelope:

{
  "type": "process_message",
  "content": {
    "text": "Fix the authentication bug in auth.ts",
    ...metadata
  }
}

PodiumEvent and Event Mapping

Events arriving from Podium carry a messageType field and an optional content object:

export interface PodiumEvent {
  readonly messageType: string
  readonly content?: Record<string, unknown>
  readonly agentId?: string
}

The PodiumEventMapper (src/domain/PodiumEventMapper.ts) is a pure function that translates Podium’s 30+ message types into Diminuendo’s 51-event wire protocol. Each Podium event is transformed into one or more client events with session-scoped sequence numbers and timestamps.

Turn Lifecycle

Podium Message	Client Event	Description
`created` / `stream_start`	`turn_started`	Agent begins processing
`update` / `stream_update`	`text_delta`	Incremental text output
`complete` / `stream_end` / `stream_complete`	`turn_complete`	Agent finishes processing
`error`	`turn_error`	Agent encountered an error

Tool Events

Podium Message	Client Event	Description
`tool.call_start`	`tool_call_start`	Tool invocation begins
`tool.call_delta`	`tool_call_delta`	Streaming tool arguments
`tool.call`	`tool_call`	Complete tool invocation with args
`tool.result`	`tool_result`	Tool execution result
`tool.error`	`tool_error`	Tool execution failed

Interactive Events

Podium Message	Client Event	Description
`tool.question_requested`	`question_requested`	Agent needs user input
`tool.permission_requested`	`permission_requested`	Agent needs action permission
`tool.approval_resolved`	`approval_resolved`	Permission request resolved

Thinking Events

Podium Message	Client Event	Description
`thinking.start`	`thinking_start`	Agent begins reasoning
`thinking.progress` / `thinking_update`	`thinking_progress`	Incremental thinking text
`thinking.complete`	`thinking_complete`	Reasoning phase complete

Terminal Events

Podium Message	Client Event	Description
`terminal.stream`	`terminal_stream`	Terminal output data
`terminal.complete`	`terminal_complete`	Command finished (with exit code)

Sandbox Events

Podium Message	Client Event	Description
`sandbox.provisioning`	`sandbox_provisioning`	Sandbox environment being set up
`sandbox.init`	`sandbox_ready`	Sandbox ready for use
`sandbox.removed`	`sandbox_removed`	Sandbox torn down

Session Lifecycle

Podium Message	Client Event	Description
`terminating`	`session_state` (state: `terminated`)	Agent shutting down
`terminated`	`session_state` (state: `terminated`)	Agent process exited

Usage Events

Podium Message	Client Event	Description
`usage` / `usage.update`	`usage_update`	Token counts, model, cost per turn
`context` / `usage.context`	`usage_context`	Total token usage and context window

Any Podium event that does not match a known message type but contains text content is treated as a text_delta fallback. Events with no matching type and no content are silently dropped (mapped to an empty array).

File Operations Proxy

File access messages from clients are proxied through to Podium’s REST file API:

Client Message	Podium API
`list_files`	`GET /api/v1/instances/{id}/files?path={path}&depth={depth}`
`read_file`	`GET /api/v1/instances/{id}/files/{path}`
`file_history`	`GET /api/v1/instances/{id}/files/{path}/history`
`file_at_iteration`	`GET /api/v1/instances/{id}/files/{path}/at/{iteration}`

All file API calls use a 15-second timeout and propagate PodiumConnectionError on failure. File operations require an active Podium instance for the session — if the session is inactive, the gateway must first activate it before file operations can proceed.

Resilience

Circuit Breaker

The createInstance method is protected by a circuit breaker:

Parameter	Value
Failure threshold	5 consecutive failures
Cooldown period	30 seconds
Reset behavior	Half-open after cooldown; first success closes the breaker

When the circuit breaker is open, createInstance calls fail immediately with a PodiumConnectionError rather than attempting the HTTP request.

Exponential Retry

Failed requests are retried with exponential backoff and jitter:

Parameter	Value
Initial delay	500ms
Backoff schedule	500ms, 1s, 2s, 4s
Max retries	3
Jitter	Applied to each delay

Connection Deduplication

The gateway prevents parallel createInstance calls for the same session. If a session is already in the activating state (meaning a createInstance call is in flight), a second activation request for the same session will wait for the first call to complete rather than issuing a duplicate request to Podium.

Health Probe

The isAlive(instanceId) method checks whether a Podium instance is still running via a 5-second timeout HTTP probe:

isAlive: (instanceId) => Effect.tryPromise({
  try: async () => {
    const res = await fetch(`${podiumUrl}/api/v1/instances/${instanceId}`, {
      headers: authHeaders,
      signal: AbortSignal.timeout(5000),
    })
    return res.ok
  },
  catch: () => false,
})

This probe is used by the /health endpoint to assess Podium availability, and by the stale session recovery mechanism to determine whether a session’s Podium instance survived a gateway restart (it never does — Podium connections do not survive process death).

Chronicle: Versioned Filesystem

Chronicle is a versioned filesystem that provides each agent session with an isolated, content-addressable workspace. Every file change creates a new iteration, enabling clients to browse version history, view files at any point in time, and synchronize workspaces to local directories for editing in a native IDE.

Role in the Architecture

Chronicle sits behind Podium in the service hierarchy. The gateway does not communicate with Chronicle directly. All file operations are routed through Podium’s REST API, which manages the mapping between compute instances and their associated Chronicle workspaces:

Client --> Gateway --> Podium --> Chronicle
  list_files        GET /files         Content-addressable store
  read_file         GET /files/{path}  Versioned iterations
  file_history      GET /files/{path}/history
  file_at_iteration GET /files/{path}/at/{n}

File Versioning

Chronicle tracks every modification to every file in an agent’s workspace as a discrete iteration — an immutable snapshot of a file at a specific point in time, identified by:

Iteration number — monotonically increasing integer, scoped to the file path within a workspace
Timestamp — epoch milliseconds when the change was persisted
Size — byte count of the file content at this iteration
Hash — content-addressable hash for deduplication and integrity verification

Clients can browse a file’s complete history using the file_history message and retrieve any past version using file_at_iteration:

// Get version history
const history = await client.fileHistory(sessionId, "src/auth.ts")
// [
//   { iteration: 1, timestamp: 1709312400000, size: 1234, hash: "abc..." },
//   { iteration: 2, timestamp: 1709312460000, size: 1456, hash: "def..." },
//   { iteration: 3, timestamp: 1709312520000, size: 1389, hash: "ghi..." },
// ]

// Read the file at iteration 1 (before the agent's changes)
const original = await client.fileAtIteration(sessionId, "src/auth.ts", 1)

Local-Sync Mode

Chronicle’s local-sync mode replaces FUSE or NFS-based filesystem abstractions with real files on the local filesystem, synchronized bidirectionally using platform-native file watching. This enables users to open agent workspace files in their preferred IDE while the agent is actively modifying them.

Local-sync is a desktop-only feature. It requires filesystem access from the Tauri Rust backend and is enabled via the local-sync Cargo feature flag in Chronicle.

Local-sync consists of three cooperating components:

LocalMaterializer

Writes files from the upstream replication stream to the local filesystem. Implements the EventHandler trait. Includes echo suppression to prevent its own writes from being detected as local changes.

FsWatcher

Monitors the local directory for changes using notify::RecommendedWatcher (FSEvents on macOS). Changes are debounced via notify-debouncer-full and filtered to exclude editor temp files, .git directories, and other noise.

WriteJournal

Tracks all changes (both local and upstream) in a journal for replication. Provides the mechanism for conflict detection when both local and remote changes affect the same file.

Bidirectional Sync Flow

Upstream (agent changes)                     Local (user changes)
         |                                            |
    Replication stream                         FSEvents / inotify
         |                                            |
    LocalMaterializer                            FsWatcher
    (write to local)                        (detect local change)
         |                                            |
    Echo suppression <---------------------------> Change filtering
         |                                            |
    WriteJournal -------------------------------------> WriteJournal
         |                                            |
    Local filesystem <------------------------------ Local filesystem

Echo suppression is the critical invariant: when the LocalMaterializer writes a file, the FsWatcher will detect that write as a local change. Without suppression, this would create an infinite sync loop. The materializer registers each write in a short-lived “echo set,” and the watcher ignores any change events for paths currently in the echo set.Debouncing prevents rapid successive changes (common during agent file writes or IDE auto-save) from generating a flood of upstream sync operations. The watcher uses notify-debouncer-full with a configurable debounce interval.

Conflict Resolution

When both the agent (upstream) and the user (local) modify the same file within the same debounce window, a conflict is detected. The desktop client surfaces this conflict to the user via the Tauri IPC resolve_conflict command, presenting options to keep the local version, accept the upstream version, or merge manually.

Tauri Integration

The desktop client provides four IPC commands for managing local-sync:

#[tauri::command]
async fn start_sync(session_id: String, local_dir: String) -> Result<(), String>;

#[tauri::command]
async fn stop_sync(session_id: String) -> Result<(), String>;

#[tauri::command]
async fn sync_status(session_id: String) -> Result<SyncStatus, String>;

#[tauri::command]
async fn resolve_conflict(
    session_id: String,
    path: String,
    resolution: ConflictResolution,
) -> Result<(), String>;

These commands are exposed to the React frontend through the TauriGatewayAdapter and can be invoked from the session management UI.

Building with Local-Sync

Chronicle’s local-sync feature is behind a Cargo feature flag:

# Build Chronicle with local-sync support
cargo build --no-default-features --features local-sync

# Run with local-sync enabled
chronicle /path/to/workspace --local-sync --ws-connect ws://podium:5082/sync

The local-sync feature pulls in the notify (v7) and notify-debouncer-full crates, which provide the platform-native file watching implementation. On macOS, this uses FSEvents. Files are materialized directly on APFS, so workspaces appear as real files in Finder and editors — no FUSE layer or kernel extension required.

Ensemble: LLM Inference

Ensemble is the LLM inference proxy that handles model routing, rate limiting, and cost tracking. Diminuendo connects to Ensemble as an upstream service for any gateway-level inference needs that are separate from the agent’s own LLM calls (which flow through Podium).

EnsembleClient

The EnsembleClient is an Effect service (Context.Tag) that provides two inference methods and a health probe:

export class EnsembleClient extends Context.Tag("EnsembleClient")<EnsembleClient, {
  readonly generate: (params: GenerateParams) =>
    Effect.Effect<GenerateResult, EnsembleError>
  readonly generateStream: (params: GenerateParams) =>
    Effect.Effect<ReadableStream<string>, EnsembleError>
  readonly isHealthy: Effect.Effect<boolean>
}>() {}

generate()

Sends a synchronous inference request and returns the complete response:

interface GenerateParams {
  readonly model: string
  readonly messages: ReadonlyArray<{ readonly role: string; readonly content: string }>
  readonly maxTokens?: number
  readonly temperature?: number
}

interface GenerateResult {
  readonly content: string
  readonly usage: {
    readonly inputTokens: number
    readonly outputTokens: number
  }
}

The request is sent as a POST to {ENSEMBLE_URL}/api/v1/generate with a 60-second timeout.

generateStream()

Sends a streaming inference request and returns a ReadableStream<string> that yields text chunks as they arrive:

const stream = await Effect.runPromise(ensemble.generateStream({
  model: "claude-3.5-sonnet",
  messages: [{ role: "user", content: "Explain quicksort" }],
}))

const reader = stream.getReader()
while (true) {
  const { done, value } = await reader.read()
  if (done) break
  process.stdout.write(value)
}

The request is sent as a POST to {ENSEMBLE_URL}/api/v1/generate/stream with a 120-second timeout. The response body is piped through a TextDecoderStream.

Configuration

The EnsembleClientLive layer reads two environment variables:

Variable	Default	Description
`ENSEMBLE_URL`	`http://localhost:5180`	Base URL for the Ensemble API
`ENSEMBLE_API_KEY`	(empty)	Bearer token for authentication

If ENSEMBLE_URL is set to a non-default value but ENSEMBLE_API_KEY is empty, the gateway logs a warning at startup: “ENSEMBLE_URL is set but ENSEMBLE_API_KEY is empty — Ensemble integration will fail.” This catches a common misconfiguration where the URL is set but the secret was not provisioned.

No-Op Fallback

If either ENSEMBLE_URL or ENSEMBLE_API_KEY is missing, the EnsembleClient falls back to a no-op implementation. Both generate and generateStream return Effect.fail(new EnsembleError({ message: "Ensemble unavailable: ..." })). The isHealthy probe returns false.This ensures the gateway starts successfully even without Ensemble configured — it degrades gracefully rather than failing to boot. Ensemble is an optional dependency, not a hard prerequisite.

Resilience

Both generate and generateStream are wrapped with the same resilience patterns used across all platform services.

Circuit Breaker

Parameter	Value
Failure threshold	5 consecutive failures
Cooldown period	30 seconds
Reset behavior	Half-open after cooldown; first success closes the breaker

When the circuit breaker opens, all inference calls fail immediately with EnsembleError (status code 503) rather than attempting the HTTP request. This prevents a failing Ensemble service from consuming gateway resources with timeout-bound requests.

const breaker = yield* makeCircuitBreaker({ failureThreshold: 5, cooldownMs: 30_000 })

const wrapWithResilience = <A>(
  effect: Effect.Effect<A, EnsembleError>,
  breaker: CircuitBreaker,
): Effect.Effect<A, EnsembleError> =>
  breaker.execute(effect).pipe(
    Effect.retry(ensembleRetry),
    Effect.catchTag("CircuitBreakerOpen", (err: CircuitBreakerOpen) =>
      Effect.fail(new EnsembleError({ message: err.message, statusCode: 503 })),
    ),
  )

Exponential Retry

Parameter	Value
Backoff schedule	1s, 2s, 4s
Max retries	2

Retries are applied after circuit breaker execution. After 2 retries (3 total attempts), the error propagates to the caller.

Health Probe

The isHealthy property sends a GET request to {ENSEMBLE_URL}/health with a 2-second timeout:

const isHealthy: Effect.Effect<boolean> = Effect.tryPromise({
  try: () => fetch(`${ensembleUrl}/health`, { signal: AbortSignal.timeout(2000) }),
  catch: () => false as never,
}).pipe(
  Effect.map((res) => res.ok),
  Effect.catchAll(() => Effect.succeed(false)),
)

This probe is used by the gateway’s /health endpoint. Unlike Podium (which is critical), an unhealthy Ensemble degrades the overall health status but does not mark the gateway as unhealthy. The gateway continues to function for all operations that do not require direct inference.

Usage Tracking

Agent LLM usage is tracked through the gateway’s event system. When an agent consumes tokens during a turn, the gateway maps Podium’s usage events to two client-facing event types.

usage_update

Emitted per-inference call within a turn:

{
  "type": "usage_update",
  "sessionId": "...",
  "turnId": "...",
  "model": "claude-3.5-sonnet",
  "inputTokens": 1500,
  "outputTokens": 350,
  "cachedTokens": 200,
  "costMicroDollars": 4200,
  "seq": 42,
  "ts": 1709312400000
}

Field	Description
`model`	The model identifier used for this inference
`inputTokens`	Number of input tokens consumed
`outputTokens`	Number of output tokens generated
`cachedTokens`	Number of tokens served from cache
`costMicroDollars`	Cost in micro-dollars (1/1,000,000 of a dollar)

usage_context

Emitted to report the agent’s context window utilization:

{
  "type": "usage_context",
  "sessionId": "...",
  "turnId": "...",
  "totalTokens": 45000,
  "maxTokens": 200000,
  "percentUsed": 22.5,
  "seq": 43,
  "ts": 1709312400000
}

Field	Description
`totalTokens`	Total tokens currently in the context window
`maxTokens`	Maximum context window size for the active model
`percentUsed`	Percentage of context window consumed

Frontend clients use usage_context events to render a context window utilization indicator, helping users understand how much context capacity remains before the agent needs to summarize or truncate its working memory.

Diminuendo

Protocol

Clients

Operations

​Platform Services

​Podium: Agent Orchestration

​PodiumClient

​Instance Lifecycle

​PodiumConnection

​PodiumEvent and Event Mapping

​Turn Lifecycle

​Tool Events

​Interactive Events

​Thinking Events

​Terminal Events

​Sandbox Events

​Session Lifecycle

​Usage Events

​File Operations Proxy

​Resilience

​Circuit Breaker

​Exponential Retry

​Connection Deduplication

​Health Probe

​Chronicle: Versioned Filesystem

​Role in the Architecture

​File Versioning

​Local-Sync Mode

LocalMaterializer

FsWatcher

WriteJournal

​Bidirectional Sync Flow

​Conflict Resolution

​Tauri Integration

​Building with Local-Sync

​Ensemble: LLM Inference

​EnsembleClient

​generate()

​generateStream()

​Configuration

​No-Op Fallback

​Resilience

​Circuit Breaker

​Exponential Retry

​Health Probe

​Usage Tracking

​usage_update

​usage_context

Platform Services

Podium: Agent Orchestration

PodiumClient

Instance Lifecycle

PodiumConnection

PodiumEvent and Event Mapping

Turn Lifecycle

Tool Events

Interactive Events

Thinking Events

Terminal Events

Sandbox Events

Session Lifecycle

Usage Events

File Operations Proxy

Resilience

Circuit Breaker

Exponential Retry

Connection Deduplication

Health Probe

Chronicle: Versioned Filesystem

Role in the Architecture

File Versioning

Local-Sync Mode

Bidirectional Sync Flow

Conflict Resolution

Tauri Integration

Building with Local-Sync

Ensemble: LLM Inference

EnsembleClient

generate()

generateStream()

Configuration

No-Op Fallback

Resilience

Circuit Breaker

Exponential Retry

Health Probe

Usage Tracking

usage_update

usage_context