​
Client Messages

The Diminuendo protocol defines 21 distinct client-to-server message types. Every message is a JSON object with a type field that identifies the message kind. The gateway validates each inbound message against an Effect Schema union and rejects anything that does not match with an INVALID_MESSAGE error. Messages are organized into six functional categories:
CategoryMessagesCount
Authenticationauthenticate1
Session Managementlist_sessions, create_session, rename_session, archive_session, unarchive_session, delete_session6
Session Interactionjoin_session, leave_session, run_turn, stop_turn, steer, answer_question6
Data Retrievalget_history, get_events, ping3
File Accesslist_files, read_file, file_history, file_at_iteration4
Administrationmanage_members1

​
Authentication

​
authenticate

Authenticates the client with the gateway. Must be the first message sent when the welcome event indicates requiresAuth: true. The gateway validates the token (JWT via Auth0 JWKS in production) and responds with either authenticated or an error with code AUTH_FAILED.
​
type
string
required
Must be "authenticate".
​
token
string
required
A valid JWT or API key. In production, this is an Auth0-issued access token. In dev mode, any non-empty string is accepted (or authentication is bypassed entirely).
Response: authenticated on success; error (code AUTH_FAILED or AUTH_RATE_LIMITED) on failure. 
{
  "type": "authenticate",
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhdXRoMHwxMjM0NTY..."
}
Authentication attempts are rate-limited per IP address. Exceeding the limit returns an AUTH_RATE_LIMITED error with a retryAfterMs hint. Implement exponential backoff in your retry logic.

​
Session Management

​
list_sessions

Retrieves all sessions belonging to the authenticated user’s tenant.
​
type
string
required
Must be "list_sessions".
​
includeArchived
boolean
When true, includes archived sessions in the response. Defaults to false.
Response: session_list containing an array of SessionMeta objects. 
{
  "type": "list_sessions",
  "includeArchived": true
}

​
create_session

Creates a new session with the specified agent type. The session is created in inactive status and must be joined before events will flow.
​
type
string
required
Must be "create_session".
​
agentType
string
required
The type of agent to associate with this session (e.g., "coding-agent", "echo"). Determines which Podium agent template is instantiated when a turn is run.
​
name
string
An optional human-readable name for the session. If omitted, the session’s name field will be null.
​
metadata
object
An optional key-value map of arbitrary metadata to attach to the session. Stored but not interpreted by the gateway.
Response: session_created containing the full SessionMeta of the new session. 
{
  "type": "create_session",
  "agentType": "coding-agent",
  "name": "Refactoring Sprint",
  "metadata": { "project": "diminuendo", "priority": "high" }
}

​
rename_session

Updates the display name of an existing session.
​
type
string
required
Must be "rename_session".
​
sessionId
string
required
The UUID of the session to rename.
​
name
string
required
The new name for the session.
Response: session_updated containing the updated SessionMeta. 
{
  "type": "rename_session",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "Auth Module Refactor"
}

​
archive_session

Marks a session as archived. Archived sessions are hidden from list_sessions by default (unless includeArchived: true is specified) but retain all their data.
​
type
string
required
Must be "archive_session".
​
sessionId
string
required
The UUID of the session to archive.
Response: session_archived containing the updated SessionMeta with archived: true. 
{
  "type": "archive_session",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

​
unarchive_session

Restores a previously archived session to active status.
​
type
string
required
Must be "unarchive_session".
​
sessionId
string
required
The UUID of the session to unarchive.
Response: session_unarchived (or session_updated with archived: false). 
{
  "type": "unarchive_session",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

​
delete_session

Permanently deletes a session and all associated data — conversation history, events, and workspace files. This operation is irreversible.
​
type
string
required
Must be "delete_session".
​
sessionId
string
required
The UUID of the session to delete.
Response: session_deleted confirming the deletion. 
{
  "type": "delete_session",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
Deletion is destructive and immediate. The gateway flushes pending writes, closes all database handles for the session, tears down any active Podium agent connection, stops the agent instance, and removes the session’s data directory from disk. There is no undo.

​
Session Interaction

​
join_session

Joins a session and subscribes to its event stream. The gateway responds with a state_snapshot containing the session’s current state, any in-progress turn, recent conversation history, and sandbox status.
​
type
string
required
Must be "join_session".
​
sessionId
string
required
The UUID of the session to join.
​
afterSeq
number
If provided, the gateway replays all persistent events with seq > afterSeq before switching to real-time streaming. Used for reconnection. Omit for a fresh join.
Response: state_snapshot on success; error with code SessionNotFound if the session does not exist. 
{
  "type": "join_session",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "afterSeq": 142
}
When reconnecting after a disconnection, always pass the last seq you received as afterSeq. This ensures you receive any events that occurred while you were disconnected, without duplicating events you already have.

​
leave_session

Unsubscribes from a session’s event stream. The client will no longer receive events for this session. This is a fire-and-forget message — no response is sent.
​
type
string
required
Must be "leave_session".
​
sessionId
string
required
The UUID of the session to leave.
Response: None. The gateway unsubscribes the client silently. 
{
  "type": "leave_session",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

​
run_turn

Initiates a new agent turn. The gateway reserves billing credits, persists the user message, establishes a Podium agent connection (if not already active), and sends the text to the agent. Events from the agent’s execution stream to all subscribed clients.
​
type
string
required
Must be "run_turn".
​
sessionId
string
required
The UUID of the session in which to run the turn.
​
text
string
required
The user’s message text to send to the agent.
​
clientTurnId
string
An optional client-generated turn ID for idempotency and correlation. If omitted, the gateway generates a UUID.
Response: No direct response. The turn produces a stream of events: turn_started, followed by text_delta / tool_call / thinking.start events, and concluding with turn_complete or turn_error. 
{
  "type": "run_turn",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "text": "Refactor the authentication module to use dependency injection",
  "clientTurnId": "turn-20240301-001"
}
The gateway checks billing credits before starting the turn. If the tenant has insufficient credits, an INSUFFICIENT_CREDITS error is returned immediately, and no agent interaction occurs. A credit reservation is held for the estimated cost of the turn and settled when the turn completes.

​
stop_turn

Requests that the currently running turn be stopped. The gateway forwards the stop signal to the Podium agent, transitions the session state to ready, and broadcasts a session_state event with reason user_stopped.
​
type
string
required
Must be "stop_turn".
​
sessionId
string
required
The UUID of the session whose turn should be stopped.
Response: No direct response. A session_state event with state: "idle" and reason: "user_stopped" is broadcast to the session. A stop_acknowledged event may also be sent. 
{
  "type": "stop_turn",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

​
steer

Sends a steering message to the agent while a turn is in progress. Steering allows the user to redirect the agent’s behavior mid-turn without stopping and restarting. The gateway assigns a steerId and broadcasts a steer_sent event to confirm delivery.
​
type
string
required
Must be "steer".
​
sessionId
string
required
The UUID of the session.
​
content
string
required
The steering instruction text.
Response: A steer_sent event is broadcast to the session, confirming the steer was delivered to the agent. 
{
  "type": "steer",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "content": "Focus on the database layer first, skip the API routes for now"
}

​
answer_question

Responds to a question_requested event from the agent. The agent may ask interactive questions during a turn (e.g., “Which database migration strategy do you prefer?”). This message provides the answers and resumes the turn.
​
type
string
required
Must be "answer_question".
​
sessionId
string
required
The UUID of the session.
​
requestId
string
required
The requestId from the corresponding question_requested event. Correlates the answer to the specific question.
​
answers
Record<string, string>
required
A map of question IDs to answer strings. Each key corresponds to a question id from the questions array in the question_requested event.
​
dismissed
boolean
When true, indicates the user dismissed the question without answering. The agent receives “Question dismissed” and proceeds accordingly. Defaults to false.
Response: No direct response. The session transitions back to running state as the agent resumes processing with the provided answers. 
{
  "type": "answer_question",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "requestId": "q-abc123",
  "answers": {
    "migration-strategy": "incremental",
    "backup-first": "yes"
  },
  "dismissed": false
}

​
Data Retrieval

​
get_history

Retrieves the conversation message history for a session. Returns messages (user and assistant) ordered by creation time, with optional pagination.
​
type
string
required
Must be "get_history".
​
sessionId
string
required
The UUID of the session.
​
afterSeq
number
Return only messages after this sequence number. Defaults to 0 (return from the beginning).
​
limit
number
Maximum number of messages to return. Defaults to 50.
Response: history containing an array of message items. 
{
  "type": "get_history",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "afterSeq": 0,
  "limit": 100
}

​
get_events

Retrieves the raw event log for a session. Returns persisted events (turn lifecycle, tool calls, etc.) with their sequence numbers, enabling full event replay.
​
type
string
required
Must be "get_events".
​
sessionId
string
required
The UUID of the session.
​
afterSeq
number
Return only events after this sequence number. Defaults to 0.
​
limit
number
Maximum number of events to return. Defaults to 200.
Response: events containing an array of event objects with seq, type, data, and createdAt fields. 
{
  "type": "get_events",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "afterSeq": 50,
  "limit": 200
}

​
ping

Measures round-trip latency between the client and gateway. The gateway echoes back the client’s timestamp alongside its own, enabling latency calculation and clock skew estimation.
​
type
string
required
Must be "ping".
​
ts
number
required
The client’s current Unix timestamp in milliseconds.
Response: pong containing both clientTs (echoed) and serverTs (gateway’s timestamp). 
{
  "type": "ping",
  "ts": 1709312400000
}
The TypeScript and Python SDKs automatically send periodic pings (default every 30 seconds) to detect stale connections. The round-trip latency is available via client.ping() in both SDKs.

​
File Access

​
list_files

Lists files and directories in the agent’s workspace. Requires an active Podium agent connection for the session.
​
type
string
required
Must be "list_files".
​
sessionId
string
required
The UUID of the session.
​
path
string
The directory path to list. Defaults to the workspace root if omitted.
​
depth
number
Maximum directory traversal depth. Omit for single-level listing.
Response: file_list containing an array of FileEntry objects. 
{
  "type": "list_files",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "path": "src/",
  "depth": 2
}

​
read_file

Reads the contents of a file from the agent’s workspace.
​
type
string
required
Must be "read_file".
​
sessionId
string
required
The UUID of the session.
​
path
string
required
The file path relative to the workspace root.
Response: file_content containing the file’s content, encoding, and size. 
{
  "type": "read_file",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "path": "src/main.ts"
}

​
file_history

Retrieves the version history (iterations) of a file in the agent’s workspace. Each iteration represents a snapshot of the file at a point in time.
​
type
string
required
Must be "file_history".
​
sessionId
string
required
The UUID of the session.
​
path
string
required
The file path relative to the workspace root.
Response: file_history_result containing an array of IterationMeta objects with iteration number, timestamp, size, and optional hash. 
{
  "type": "file_history",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "path": "src/auth/AuthService.ts"
}

​
file_at_iteration

Reads the contents of a file at a specific historical iteration, enabling diff views and rollback.
​
type
string
required
Must be "file_at_iteration".
​
sessionId
string
required
The UUID of the session.
​
path
string
required
The file path relative to the workspace root.
​
iteration
number
required
The iteration number to retrieve (from file_history results).
Response: file_content containing the file’s content at the specified iteration. 
{
  "type": "file_at_iteration",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "path": "src/auth/AuthService.ts",
  "iteration": 3
}

​
Administration

​
manage_members

Manages tenant membership: listing members, assigning roles, and removing members. Available actions depend on the caller’s role — listing requires member:read permission, role assignment requires member:write, and removal requires member:delete.
​
type
string
required
Must be "manage_members".
​
action
string
required
One of "list", "set_role", or "remove".
​
userId
string
Required for set_role and remove actions. The user ID of the member to modify.
​
role
string
Required for set_role. The new role to assign. Valid roles: "owner", "admin", "member".
Response: Depends on the action:
  • "list" returns member_list with an array of MemberRecord objects.
  • "set_role" returns member_updated with the user ID and new role.
  • "remove" returns member_removed with the user ID.
{
  "type": "manage_members",
  "action": "list"
}
The gateway protects the last owner of a tenant from demotion. If you attempt to change the role of the sole owner, the gateway returns a LAST_OWNER_PROTECTED error. Promote another member to owner first.