SDKs

Diminuendo ships four official client SDKs that cover the full surface of the wire protocol — all 21 client message types and all 51 server event types — with no exceptions, no partial implementations, and no event silently dropped. Each SDK is a standalone library with zero gateway dependencies: it defines its own types from the wire protocol specification, connects over a standard WebSocket, and can be published and consumed independently. The SDKs are not generated from a shared schema; they are handcrafted in each language’s native idiom, because a Rust developer should not have to think in TypeScript abstractions, and a Swift developer should not encounter Python’s naming conventions.

Design Principles

Full Protocol Parity

Every client message type and every server event type is represented in each SDK. No event is silently dropped. No message type is missing. The SDKs are functionally equivalent — anything one can do, all can do.

Zero Gateway Dependencies

The SDKs do not import gateway code, do not share types via monorepo packages, and do not require code generation. Each SDK defines its own types from the wire protocol specification. This ensures they can be published and used independently.

Native Idioms

TypeScript uses Promises and typed event handlers. Rust uses async channels and serde. Python uses asyncio and dataclasses. Swift uses async/await and Codable. Each SDK feels native to its language — no lowest-common-denominator abstraction.

Adversarial Test Suites

Every SDK has a comprehensive test suite that does not merely verify happy paths, but actively attempts to break the client with malformed data, concurrent operations, timeouts, and edge cases.

SDK Comparison

Aspect	TypeScript	Rust	Python	Swift
Runtime	Node.js, Bun, Deno, browsers	tokio (async runtime)	asyncio + websockets	Swift Concurrency + `URLSessionWebSocketTask`
Dependencies	Zero runtime deps	tokio, serde, tokio-tungstenite, futures-util, thiserror, tracing	websockets	None (Foundation only)
Async Model	Promises + event callbacks	`mpsc::UnboundedReceiver<ServerEvent>`	`async`/`await` + event callbacks	async/await + `AsyncStream<ServerEvent>`
Type System	TypeScript interfaces (compile-time)	Rust enums with `#[serde(tag = "type")]` (compile + runtime)	Dataclasses with `from_dict` parsers	`Codable` enums/structs with `CodingKeys`
Event Delivery	`.on(type, handler)` with unsubscribe	Channel-based (`events.recv().await`)	`.on(type, handler)` with unsubscribe	`AsyncStream` consumption in a `for await` loop
Wildcard Events	`.on("*", handler)`	`ServerEvent::Unknown` catch-all	`.on("*", handler)`	`.unknown` catch-all case
Wire Mapping	camelCase (native)	`#[serde(rename)]` from snake_case	`from_dict` with explicit key mapping	`CodingKeys` with camelCase
Connection Management	Auto-reconnect, ping timer	Manual (application controls lifecycle)	Auto-reconnect, ping timer	Auto-reconnect, ping timer
Primary Use Case	Web apps, Node.js services	Tauri desktop apps, CLI tools	Scripts, testing, notebooks	macOS/iOS apps, SwiftUI clients
Test Count	137 tests	178 tests	173 tests	193 tests

TypeScript
Rust
Python
Swift

TypeScript SDK

The TypeScript SDK is a zero-dependency WebSocket client that works in any JavaScript runtime with a standard WebSocket global — browsers, Node.js 21+, Bun, and Deno. It provides a Promise-based API for request-response operations and typed event handlers for streaming events.

Installation

npm install @igentai/diminuendo-sdk

Quick Start

import { DiminuendoClient } from "@igentai/diminuendo-sdk"

const client = new DiminuendoClient({
  url: "ws://localhost:8080/ws",
  token: "eyJ...",
})

await client.connect()
const session = await client.createSession("coding-agent", "My Session")
const snapshot = await client.joinSession(session.id)

client.runTurn(session.id, "Explain the architecture")

client.on("text_delta", (event) => {
  process.stdout.write(event.text)
})

client.on("turn_complete", () => {
  console.log("\nDone.")
  client.disconnect()
})

Connection Lifecycle

const client = new DiminuendoClient({
  url: "ws://localhost:8080/ws",
  token: "your-jwt-token",        // Optional in dev mode
  autoReconnect: true,             // Default: true
  reconnectDelay: 1000,            // Default: 1000ms
  pingInterval: 30000,             // Default: 30000ms (0 to disable)
})

// connect() waits for the authentication handshake to complete
await client.connect()
console.log(client.authenticated)  // true
console.log(client.identity)       // { userId, email, tenantId }

// Disconnect and disable auto-reconnect
client.disconnect()

Option	Type	Default	Description
`url`	`string`	(required)	Gateway WebSocket URL
`token`	`string`	`""`	JWT or API key for authentication
`autoReconnect`	`boolean`	`true`	Automatically reconnect on disconnect
`reconnectDelay`	`number`	`1000`	Milliseconds between reconnection attempts
`pingInterval`	`number`	`30000`	Keepalive ping interval in ms. Set to `0` to disable

When autoReconnect is enabled, the client automatically re-establishes the connection and re-authenticates using the original token. Listen for lifecycle events to track reconnection:

client.on("connected", () => console.log("WebSocket opened"))
client.on("authenticated", () => console.log("Authenticated"))
client.on("disconnected", () => console.log("Disconnected -- will reconnect"))

Session Management

All session management methods return Promises and use request/response correlation — the SDK sends a typed message and waits for the corresponding server event.

// List all sessions
const sessions = await client.listSessions()
const allSessions = await client.listSessions(true)  // include archived

// Create a session
const session = await client.createSession("coding-agent", "My Session")

// Rename, archive, unarchive, delete
const renamed = await client.renameSession(session.id, "New Name")
const archived = await client.archiveSession(session.id)
const restored = await client.unarchiveSession(session.id)
await client.deleteSession(session.id)

Each method that modifies a session returns the updated SessionMeta:

interface SessionMeta {
  id: string
  tenantId: string
  name: string | null
  agentType: string
  status: SessionStatus
  archived: boolean
  createdAt: number
  updatedAt: number
  lastActivityAt: number | null
}

Session Interaction

// Join a session (subscribe to events, receive state snapshot)
const snapshot = await client.joinSession(sessionId)
console.log(snapshot.session.status)     // "inactive" | "ready" | "running" | ...
console.log(snapshot.recentHistory)      // Last N messages
console.log(snapshot.subscriberCount)    // Connected viewers

// Resume from a known sequence number (for reconnection)
const snapshot2 = await client.joinSession(sessionId, lastKnownSeq)

// Leave a session (fire-and-forget)
client.leaveSession(sessionId)

// Start an agent turn
client.runTurn(sessionId, "Fix the bug in auth.ts")
client.runTurn(sessionId, "Add tests", "client-turn-123")  // with client correlation ID

// Cancel an in-progress turn
client.stopTurn(sessionId)

// Mid-turn guidance
client.steer(sessionId, "Focus on the error handling, not the tests")

// Answer a question from the agent
client.answerQuestion(sessionId, requestId, {
  "preferred_language": "TypeScript",
  "framework": "React",
})

// Retrieve paginated history and events
const history = await client.getHistory(sessionId, 0, 50)
const events = await client.getEvents(sessionId, 0, 200)

// Measure round-trip latency
const { latencyMs } = await client.ping()

runTurn and stopTurn are fire-and-forget — they send the message immediately and return void. The response arrives as a stream of events (turn_started, text_delta, tool_call, turn_complete, etc.).

Event Handling

The SDK provides a type-safe event subscription system. The on() method accepts an event type string and a handler function, with TypeScript narrowing the event payload to the correct type.

// Type-safe event handler -- event is narrowed to TextDeltaEvent
const unsub = client.on("text_delta", (event) => {
  console.log(event.text)       // string
  console.log(event.turnId)     // string
  console.log(event.sessionId)  // string
})

// Wildcard handler -- receives all events
client.on("*", (event) => {
  console.log(event.type, event)
})

// One-shot handler
client.once("turn_complete", (event) => {
  console.log("Turn finished:", event.finalText)
})

// Remove all handlers for a type
client.off("text_delta")

// Unsubscribe a specific handler
unsub()

File Access

// List files in the agent's workspace
const files = await client.listFiles(sessionId)
const nested = await client.listFiles(sessionId, "src/", 2)

// Read a file
const content = await client.readFile(sessionId, "src/main.ts")

// Version history
const history = await client.fileHistory(sessionId, "src/main.ts")

// Read at a specific iteration
const oldVersion = await client.fileAtIteration(sessionId, "src/main.ts", 3)

Error Handling

Errors arise in two contexts:

Connection errors — connect() rejects if the WebSocket fails to open, authentication fails, or the 10-second timeout is reached.
Request errors — methods like listSessions() or joinSession() reject if the gateway returns an error event, or if the 10-second request timeout is reached.

Sending a message on a closed WebSocket throws a synchronous Error("WebSocket not connected").

try {
  await client.connect()
} catch (err) {
  // "Connection timeout while waiting for authentication"
  // "Authentication required but no token was provided"
  // "AUTH_FAILED: Authentication failed"
}

try {
  await client.joinSession("nonexistent-id")
} catch (err) {
  // "SESSION_NOT_FOUND: Session does not exist"
  // "Request timeout for join_session"
}

Complete Example

import { DiminuendoClient } from "@igentai/diminuendo-sdk"

async function main() {
  const client = new DiminuendoClient({
    url: "ws://localhost:8080/ws",
    token: process.env.GATEWAY_TOKEN,
  })

  await client.connect()
  console.log(`Authenticated as ${client.identity?.email}`)

  const session = await client.createSession("coding-agent", "Bug Fix Session")
  const snapshot = await client.joinSession(session.id)
  console.log(`Session status: ${snapshot.session.status}`)

  client.on("turn_started", (e) => console.log(`Turn started: ${e.turnId}`))
  client.on("text_delta", (e) => process.stdout.write(e.text))
  client.on("tool_call", (e) => console.log(`\nTool: ${e.toolName}(${JSON.stringify(e.args)})`))
  client.on("tool_result", (e) => console.log(`Result [${e.status}]: ${e.output}`))
  client.on("turn_complete", () => {
    console.log("\nTurn complete.")
    client.disconnect()
  })
  client.on("turn_error", (e) => {
    console.error(`Turn error: ${e.message}`)
    client.disconnect()
  })

  client.runTurn(session.id, "Fix the authentication bug in src/auth.ts")
}

main().catch(console.error)

Rust SDK

The Rust SDK is a fully async WebSocket client built on tokio, designed primarily for Tauri v2 desktop applications and CLI tools. It is Send + Sync safe, non-blocking, and uses an mpsc channel pair for event delivery — the client sends messages via methods on DiminuendoClient, and events arrive on an UnboundedReceiver<ServerEvent>.

Installation

Add the SDK to your Cargo.toml:

[dependencies]
diminuendo-sdk = { path = "sdk/rust" }

Crate	Purpose
`tokio`	Async runtime
`tokio-tungstenite`	WebSocket client
`serde` / `serde_json`	JSON serialization with snake_case to camelCase mapping
`thiserror`	Typed error derivation
`tracing`	Structured logging
`futures-util`	Stream/Sink extensions for WebSocket I/O

Quick Start

use diminuendo_sdk::{DiminuendoClient, ClientOptions, ServerEvent};

let options = ClientOptions {
    url: "ws://localhost:8080/ws".into(),
    token: "eyJ...".into(),
};

let (client, mut events) = DiminuendoClient::connect(options).await?;

client.create_session("coding-agent", Some("My Session"))?;

while let Some(event) = events.recv().await {
    match event {
        ServerEvent::TextDelta { text, .. } => print!("{text}"),
        ServerEvent::TurnComplete { .. } => {
            println!("\nDone.");
            break;
        }
        _ => {}
    }
}

client.close();

Connection Lifecycle

The client is constructed via the async connect() associated function, which returns a tuple of (DiminuendoClient, mpsc::UnboundedReceiver<ServerEvent>). The connect() function spawns a background tokio task that handles all WebSocket I/O — the task reads from the WebSocket, deserializes events via serde, and forwards them to the events channel. Commands sent via client methods are forwarded to the WebSocket write half via an internal command channel.

let options = ClientOptions {
    url: "ws://localhost:8080/ws".to_string(),
    token: "your-jwt-token".to_string(),  // Empty string for dev mode
};

let (client, mut events) = DiminuendoClient::connect(options).await?;

// Close the connection
client.close();

The Rust SDK does not provide built-in auto-reconnect or ping keepalive. The application controls the connection lifecycle. In a Tauri application, the Rust backend manages reconnection logic and holds the client in managed state.

Session Management

All client methods are fire-and-forget — they serialize the message to JSON and send it to the background WebSocket task via an internal command channel. Each returns Result<(), ClientError>. Responses arrive as events on the receiver channel.

// List sessions
client.list_sessions(false)?;
client.list_sessions(true)?;  // include archived

// Create a session
client.create_session("coding-agent", Some("My Session"))?;

// Rename, archive, unarchive, delete
client.rename_session("session-id", "New Name")?;
client.archive_session("session-id")?;
client.unarchive_session("session-id")?;
client.delete_session("session-id")?;

Session Interaction

// Join a session (subscribe to events)
client.join_session("session-id", None)?;
client.join_session("session-id", Some(42))?;  // Resume from seq 42

// Leave a session
client.leave_session("session-id")?;

// Start a turn
client.run_turn("session-id", "Fix the bug", None)?;
client.run_turn("session-id", "Add tests", Some("client-turn-123"))?;

// Stop the current turn
client.stop_turn("session-id")?;

// Mid-turn guidance
client.steer("session-id", "Focus on error handling")?;

// Answer a question from the agent
let mut answers = std::collections::HashMap::new();
answers.insert("language".to_string(), "Rust".to_string());
client.answer_question("session-id", "request-id", answers, false)?;

// Get history and events
client.get_history("session-id", Some(0), Some(50))?;
client.get_events("session-id", Some(0), Some(200))?;

// Ping
client.ping()?;

Event Handling

All server events arrive through the mpsc::UnboundedReceiver<ServerEvent> channel. The consumer should spawn a dedicated task to process events:

tokio::spawn(async move {
    while let Some(event) = events.recv().await {
        match event {
            ServerEvent::Authenticated { identity } => {
                println!("Authenticated as {}", identity.email);
            }
            ServerEvent::StateSnapshot { session, .. } => {
                println!("Session status: {}", session.status);
            }
            ServerEvent::TextDelta { text, .. } => print!("{text}"),
            ServerEvent::ToolCall { tool_name, args, .. } => {
                println!("Tool: {}({:?})", tool_name, args);
            }
            ServerEvent::ToolResult { status, output, .. } => {
                println!("Result [{}]: {:?}", status, output);
            }
            ServerEvent::TurnComplete { .. } => println!("\nTurn complete."),
            ServerEvent::TurnError { message, .. } => eprintln!("Error: {}", message),
            ServerEvent::Unknown => {} // Forward-compatible catch-all
            _ => {}
        }
    }
});

The ServerEvent enum uses #[serde(tag = "type", rename_all = "snake_case")] for deserialization. The #[serde(other)] Unknown variant ensures that future event types added to the protocol do not cause deserialization failures — they are silently absorbed rather than producing errors.Rust fields use snake_case while the JSON wire format uses camelCase. This mapping is handled transparently by #[serde(rename)] attributes:

Rust Field	JSON Field
`session_id`	`sessionId`
`agent_type`	`agentType`
`tool_call_id`	`toolCallId`
`after_seq`	`afterSeq`
`client_turn_id`	`clientTurnId`

File Access

client.list_files("session-id", None, None)?;
client.list_files("session-id", Some("src/"), Some(2))?;
client.read_file("session-id", "src/main.rs")?;
client.file_history("session-id", "src/main.rs")?;
client.file_at_iteration("session-id", "src/main.rs", 3)?;

Error Types

#[derive(Debug, thiserror::Error)]
pub enum ClientError {
    #[error("WebSocket error: {0}")]
    WebSocket(String),

    #[error("Connection failed: {0}")]
    Connection(String),

    #[error("Authentication timed out")]
    AuthTimeout,

    #[error("Request timed out: {0}")]
    RequestTimeout(String),

    #[error("Not connected")]
    NotConnected,

    #[error("Serialization error: {0}")]
    Serde(#[from] serde_json::Error),
}

Complete Example

use diminuendo_sdk::{DiminuendoClient, ClientOptions, ServerEvent};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let options = ClientOptions {
        url: "ws://localhost:8080/ws".to_string(),
        token: std::env::var("GATEWAY_TOKEN").unwrap_or_default(),
    };

    let (client, mut events) = DiminuendoClient::connect(options).await?;

    tokio::spawn(async move {
        while let Some(event) = events.recv().await {
            match event {
                ServerEvent::Authenticated { identity } => {
                    println!("Authenticated as {}", identity.email);
                }
                ServerEvent::SessionCreated { session } => {
                    println!("Created session: {}", session.id);
                }
                ServerEvent::TurnStarted { turn_id, .. } => {
                    println!("Turn started: {}", turn_id);
                }
                ServerEvent::TextDelta { text, .. } => print!("{text}"),
                ServerEvent::ToolCall { tool_name, args, .. } => {
                    println!("\nTool: {}({:?})", tool_name, args);
                }
                ServerEvent::ToolResult { status, output, .. } => {
                    println!("Result [{}]: {:?}", status, output);
                }
                ServerEvent::TurnComplete { .. } => println!("\nTurn complete."),
                ServerEvent::TurnError { message, .. } => eprintln!("Error: {}", message),
                _ => {}
            }
        }
    });

    // Wait for authentication, then create and join a session
    tokio::time::sleep(tokio::time::Duration::from_secs(1)).await;
    client.create_session("coding-agent", Some("Bug Fix"))?;

    // Keep alive until Ctrl+C
    tokio::signal::ctrl_c().await?;
    client.close();
    Ok(())
}

In a Tauri application, the DiminuendoClient is held in Tauri’s managed state. Tauri commands invoke client methods, and the event receiver task emits Tauri events via app_handle.emit("gateway-event", &event) for the React frontend to consume.

Python SDK

The Python SDK is an asyncio-based WebSocket client using the websockets library. It provides a callback-based event model with wildcard support, dataclass-based types with from_dict class methods for parsing wire data, and predicate-based request/response matching that allows the client to wait for specific response types without blocking other event processing.

Installation

pip install diminuendo-sdk

Requires Python 3.11 or later. The SDK uses type union syntax (str | None), asyncio improvements, and other features introduced in Python 3.11.

Quick Start

from diminuendo_sdk import DiminuendoClient, ClientOptions

client = DiminuendoClient(ClientOptions(
    url="ws://localhost:8080/ws",
    token="eyJ...",
))

await client.connect()
session = await client.create_session("coding-agent", "My Session")
snapshot = await client.join_session(session.id)

await client.run_turn(session.id, "Explain the architecture")

client.on("text_delta", lambda e: print(e.text, end="", flush=True))
client.on("turn_complete", lambda e: print(f"\nDone: {e.final_text[:100]}"))

Connection Lifecycle

client = DiminuendoClient(ClientOptions(
    url="ws://localhost:8080/ws",
    token="your-jwt-token",       # Optional in dev mode
    auto_reconnect=True,           # Default: True
    reconnect_delay=1.0,           # Default: 1.0 seconds
    ping_interval=30.0,            # Default: 30.0 seconds (0 to disable)
))

await client.connect()
print(client.authenticated)  # True
print(client.identity)       # {"userId": "...", "email": "...", "tenantId": "..."}

await client.disconnect()

Option	Type	Default	Description
`url`	`str`	(required)	Gateway WebSocket URL
`token`	`str`	`""`	JWT or API key for authentication
`auto_reconnect`	`bool`	`True`	Automatically reconnect on disconnect
`reconnect_delay`	`float`	`1.0`	Seconds between reconnection attempts
`ping_interval`	`float`	`30.0`	Keepalive ping interval in seconds. `0` to disable

Authentication must complete within 10 seconds or a ConnectionError is raised.

Session Management

# List sessions
sessions = await client.list_sessions()
all_sessions = await client.list_sessions(include_archived=True)

# Create a session
session = await client.create_session("coding-agent", "My Session")

# Rename, archive, unarchive, delete
renamed = await client.rename_session(session.id, "New Name")
archived = await client.archive_session(session.id)
restored = await client.unarchive_session(session.id)
await client.delete_session(session.id)

Returns SessionMeta dataclass instances:

@dataclass
class SessionMeta:
    id: str
    tenant_id: str
    name: str | None
    agent_type: str
    status: SessionStatus  # Literal["inactive", "activating", "ready", "running", "waiting", "deactivating", "error"]
    archived: bool
    created_at: int
    updated_at: int
    last_activity_at: int | None = None

Session Interaction

# Join a session (returns StateSnapshot)
snapshot = await client.join_session(session_id)
print(snapshot.session.status)       # "inactive" | "ready" | ...
print(snapshot.recent_history)       # List of recent HistoryItem
print(snapshot.subscriber_count)     # Connected viewers

# Resume from a known sequence number
snapshot = await client.join_session(session_id, after_seq=42)

# Leave (fire-and-forget)
await client.leave_session(session_id)

# Start a turn
await client.run_turn(session_id, "Fix the bug in auth.py")
await client.run_turn(session_id, "Add tests", client_turn_id="turn-123")

# Cancel an in-progress turn
await client.stop_turn(session_id)

# Mid-turn guidance
await client.steer(session_id, "Focus on the error handling path")

# Answer a question from the agent
await client.answer_question(
    session_id, request_id,
    answers={"language": "Python", "framework": "FastAPI"},
)

# Retrieve paginated history and events
history = await client.get_history(session_id, after_seq=0, limit=50)
events = await client.get_events(session_id, after_seq=0, limit=200)

# Measure latency
latency_ms = await client.ping()

Event Handling

def on_text_delta(event):
    print(event.text, end="", flush=True)

def on_turn_complete(event):
    print(f"\nTurn complete: {event.final_text[:50]}...")

unsub_delta = client.on("text_delta", on_text_delta)
unsub_complete = client.on("turn_complete", on_turn_complete)

# Wildcard handler -- receives all events
client.on("*", lambda e: print(f"[{e.type}]"))

# Unsubscribe
unsub_delta()

The ServerEvent dataclass wraps all events with convenience properties:

@dataclass
class ServerEvent:
    type: str
    data: dict[str, Any]

    # Convenience properties
    session_id: str | None     # data["sessionId"]
    turn_id: str | None        # data["turnId"]
    text: str                  # data["text"]
    final_text: str            # data["finalText"]
    error_message: str         # data["message"]
    error_code: str            # data["code"]
    seq: int | None
    ts: int | None

    # Category checks
    is_turn_event: bool        # turn_started, text_delta, turn_complete, turn_error
    is_tool_event: bool        # tool_call, tool_result, tool_call_start, tool_call_delta, tool_error
    is_thinking_event: bool    # thinking_start, thinking_progress, thinking_complete
    is_terminal_event: bool    # terminal_stream, terminal_complete
    is_sandbox_event: bool     # sandbox_init, sandbox_provisioning, sandbox_ready, sandbox_removed
    is_interactive_event: bool # question_requested, permission_requested, approval_resolved

File Access

# List files
files = await client.list_files(session_id)
nested = await client.list_files(session_id, path="src/", depth=2)

# Read a file
content = await client.read_file(session_id, "src/main.py")

# Version history
history = await client.file_history(session_id, "src/main.py")

# Read at a specific iteration
old = await client.file_at_iteration(session_id, "src/main.py", iteration=3)

All file types provide from_dict class methods that map camelCase JSON to snake_case Python attributes:

@dataclass
class FileEntry:
    path: str
    name: str
    is_directory: bool
    size: int | None = None
    modified_at: int | None = None

@dataclass
class FileContent:
    session_id: str
    path: str
    content: str
    encoding: str
    size: int

@dataclass
class IterationMeta:
    iteration: int
    timestamp: int
    size: int
    hash: str | None = None

Error Handling

connect() raises ConnectionError if authentication fails or the 10-second timeout is reached.
Request methods raise TimeoutError if the gateway does not respond within 10 seconds.
Sending on a closed connection raises ConnectionError.

Complete Example

import asyncio
from diminuendo_sdk import DiminuendoClient, ClientOptions

async def main():
    client = DiminuendoClient(ClientOptions(
        url="ws://localhost:8080/ws",
        token="",  # Empty for dev mode
    ))

    await client.connect()
    print(f"Authenticated: {client.authenticated}")

    session = await client.create_session("coding-agent", "Bug Fix Session")
    snapshot = await client.join_session(session.id)
    print(f"Status: {snapshot.session.status}")

    turn_complete = asyncio.Event()

    client.on("text_delta", lambda e: print(e.text, end="", flush=True))
    client.on("tool_call", lambda e: print(f"\n[tool] {e.tool_name}({e.tool_args})"))
    client.on("tool_result", lambda e: print(f"[result] {e.tool_status}: {e.tool_output}"))
    client.on("turn_complete", lambda e: (print("\n--- Turn complete ---"), turn_complete.set()))
    client.on("turn_error", lambda e: (print(f"\n[error] {e.error_message}"), turn_complete.set()))

    await client.run_turn(session.id, "Fix the authentication bug in auth.py")
    await turn_complete.wait()

    await client.leave_session(session.id)
    await client.disconnect()

if __name__ == "__main__":
    asyncio.run(main())

Swift SDK

The Swift SDK is an actor-based client built on Swift Concurrency and URLSessionWebSocketTask. It delivers events through an AsyncStream<ServerEvent>, uses Codable for all wire types, and carries zero third-party dependencies. Designed for macOS 26+ SwiftUI applications, with backward compatibility to macOS 13+ and iOS 16+. Targets Swift 6.0 with strict concurrency checking — all public types are Sendable.

Installation

Add the SDK to your Swift Package Manager dependencies:

// Package.swift
dependencies: [
    .package(path: "../sdk/swift")
    // Or: .package(url: "https://github.com/iGentAI/diminuendo-swift", from: "0.1.0")
],
targets: [
    .target(name: "MyApp", dependencies: ["DiminuendoSDK"])
]

Quick Start

import DiminuendoSDK

let client = DiminuendoClient(options: .init(
    url: "ws://localhost:8080/ws",
    token: ""  // Empty for dev mode
))

try await client.connect()

Task {
    for await event in await client.events {
        switch event {
        case .textDelta(_, _, let text, _, _):
            print(text, terminator: "")
        case .turnComplete(_, _, let finalText, _, _):
            print("\nDone: \(finalText)")
        case .error(let code, let message):
            print("Error [\(code)]: \(message)")
        default:
            break
        }
    }
}

let session = try await client.createSession(agentType: "coding-agent", name: "My Session")
let snapshot = try await client.joinSession(sessionId: session.id)
try await client.runTurn(sessionId: session.id, text: "Explain this codebase")

Connection Lifecycle

The client is implemented as a Swift actor, providing inherent thread safety for all mutable state. The WebSocket connection runs on a background Task, delivering events via an AsyncStream<ServerEvent> backed by a continuation.

public struct ClientOptions: Sendable {
    public let url: String              // Gateway WebSocket URL
    public let token: String            // Auth token (empty for dev mode)
    public let autoReconnect: Bool      // Default: true
    public let reconnectDelay: TimeInterval  // Default: 1.0s
    public let pingInterval: TimeInterval    // Default: 30.0s (0 to disable)
}

let client = DiminuendoClient(options: .init(url: "ws://localhost:8080/ws"))

try await client.connect()
print(await client.isConnected)      // true
print(await client.isAuthenticated)  // true
print(await client.identity)         // Identity(userId:, email:, tenantId:)

await client.disconnect()

Session Management

let sessions = try await client.listSessions(includeArchived: false)

let session = try await client.createSession(agentType: "coding-agent", name: "My Session")
let renamed = try await client.renameSession(sessionId: session.id, name: "Better Name")
let archived = try await client.archiveSession(sessionId: session.id)
let restored = try await client.unarchiveSession(sessionId: session.id)
try await client.deleteSession(sessionId: session.id)

Session Interaction

// Join a session (returns full state snapshot)
let snapshot = try await client.joinSession(sessionId: session.id)
let resumed = try await client.joinSession(sessionId: session.id, afterSeq: 42)

// Run a turn
try await client.runTurn(sessionId: session.id, text: "Explain this code")

// Mid-turn controls
try await client.stopTurn(sessionId: session.id)
try await client.steer(sessionId: session.id, content: "Focus on error handling")

// Answer agent questions
try await client.answerQuestion(
    sessionId: session.id,
    requestId: "req-123",
    answers: ["choice": "option-a"]
)

// Retrieve history and events
let history = try await client.getHistory(sessionId: session.id)
let events = try await client.getEvents(sessionId: session.id, afterSeq: 10, limit: 100)

// Ping for latency
let latencyMs = try await client.ping()

Event Handling

Events are delivered via AsyncStream<ServerEvent>. The ServerEvent enum has 51+ variants covering the full protocol, plus an .unknown catch-all for forward compatibility:

Task {
    for await event in await client.events {
        switch event {
        case .turnStarted(let sid, let tid, _, _):
            print("Turn \(tid) started in \(sid)")
        case .textDelta(_, _, let text, _, _):
            print(text, terminator: "")
        case .turnComplete(_, _, let finalText, _, _):
            print("\n--- Complete: \(finalText.prefix(100))...")
        case .toolCall(_, _, let id, let name, _, _, _):
            print("Tool: \(name) (\(id))")
        case .toolResult(_, _, _, let status, let output, _, _):
            print("Result: \(status) -- \(output ?? "")")
        case .thinkingStart(_, _, _, _):
            print("[thinking...]")
        case .questionRequested(_, let reqId, let questions, _):
            print("Question \(reqId): \(questions)")
        case .error(let code, let message):
            print("Error [\(code)]: \(message)")
        case .unknown(let type, _):
            print("Unknown event: \(type)")
        default:
            break
        }
    }
}

File Access

let files = try await client.listFiles(sessionId: session.id, path: "/src", depth: 2)
let content = try await client.readFile(sessionId: session.id, path: "/src/main.swift")
let versions = try await client.fileHistory(sessionId: session.id, path: "/src/main.swift")
let oldVersion = try await client.fileAtIteration(
    sessionId: session.id, path: "/src/main.swift", iteration: 3
)

Error Types

public enum ClientError: Error, Sendable {
    case notConnected
    case connectionFailed(String)
    case authenticationFailed
    case authenticationTimeout
    case requestTimeout(String)
    case serializationError(String)
    case webSocketError(String)
}

do {
    try await client.connect()
    let sessions = try await client.listSessions()
} catch DiminuendoClient.ClientError.authenticationTimeout {
    print("Auth timed out -- check token")
} catch DiminuendoClient.ClientError.requestTimeout(let msg) {
    print("Request timed out: \(msg)")
} catch DiminuendoClient.ClientError.notConnected {
    print("Not connected -- call connect() first")
} catch {
    print("Unexpected: \(error)")
}

Types

All types conform to Codable, Sendable, and Equatable:

Type	Description
`SessionMeta`	Session metadata (id, status, agentType, timestamps)
`SessionStatus`	7-state enum: inactive, activating, ready, running, waiting, deactivating, error
`Identity`	Authenticated user (userId, email, tenantId)
`StateSnapshot`	Full session state on join
`FileEntry`	File/directory in agent workspace
`FileContent`	File content with encoding and size
`IterationMeta`	File version metadata
`HistoryItem`	Conversation message
`MemberRecord`	Tenant member with role
`AnyCodable`	Type-erased JSON value wrapper
`ClientMessage`	21-variant enum (Encodable)
`ServerEvent`	51-variant enum (Decodable) with `.unknown` catch-all

Complete Example

import DiminuendoSDK

@main
struct Main {
    static func main() async throws {
        let client = DiminuendoClient(options: .init(
            url: "ws://localhost:8080/ws",
            token: ProcessInfo.processInfo.environment["GATEWAY_TOKEN"] ?? ""
        ))

        try await client.connect()
        print("Authenticated as \(await client.identity?.email ?? "unknown")")

        let eventTask = Task {
            for await event in await client.events {
                switch event {
                case .textDelta(_, _, let text, _, _):
                    print(text, terminator: "")
                case .toolCall(_, _, _, let name, _, _, _):
                    print("\nTool: \(name)")
                case .turnComplete(_, _, _, _, _):
                    print("\nTurn complete.")
                    return
                case .turnError(_, _, let message, _, _, _):
                    print("\nError: \(message)")
                    return
                default:
                    break
                }
            }
        }

        let session = try await client.createSession(
            agentType: "coding-agent", name: "Bug Fix Session"
        )
        let snapshot = try await client.joinSession(sessionId: session.id)
        print("Session status: \(snapshot.session.status)")

        try await client.runTurn(
            sessionId: session.id,
            text: "Fix the authentication bug"
        )

        await eventTask.value
        await client.disconnect()
    }
}

Protocol Coverage Matrix

Every client message and server event is implemented in all four SDKs. The following tables confirm full parity across the entire wire protocol surface.

21 Client Messages

Message Type	TypeScript	Rust	Python	Swift
`authenticate`	Yes	Yes	Yes	Yes
`list_sessions`	Yes	Yes	Yes	Yes
`create_session`	Yes	Yes	Yes	Yes
`rename_session`	Yes	Yes	Yes	Yes
`archive_session`	Yes	Yes	Yes	Yes
`unarchive_session`	Yes	Yes	Yes	Yes
`delete_session`	Yes	Yes	Yes	Yes
`join_session`	Yes	Yes	Yes	Yes
`leave_session`	Yes	Yes	Yes	Yes
`run_turn`	Yes	Yes	Yes	Yes
`stop_turn`	Yes	Yes	Yes	Yes
`steer`	Yes	Yes	Yes	Yes
`answer_question`	Yes	Yes	Yes	Yes
`get_history`	Yes	Yes	Yes	Yes
`get_events`	Yes	Yes	Yes	Yes
`ping`	Yes	Yes	Yes	Yes
`list_files`	Yes	Yes	Yes	Yes
`read_file`	Yes	Yes	Yes	Yes
`file_history`	Yes	Yes	Yes	Yes
`file_at_iteration`	Yes	Yes	Yes	Yes
`manage_members`	Yes	Yes	Yes	Yes

51 Server Events

Event Type	TypeScript	Rust	Python	Swift
`welcome`	Yes	Yes	Yes	Yes
`connected`	Yes	Yes	Yes	Yes
`authenticated`	Yes	Yes	Yes	Yes
`heartbeat`	Yes	Yes	Yes	Yes
`session_list`	Yes	Yes	Yes	Yes
`session_created`	Yes	Yes	Yes	Yes
`session_updated`	Yes	Yes	Yes	Yes
`session_archived`	Yes	Yes	Yes	Yes
`session_unarchived`	Yes	Yes	Yes	Yes
`session_deleted`	Yes	Yes	Yes	Yes
`session_state`	Yes	Yes	Yes	Yes
`state_snapshot`	Yes	Yes	Yes	Yes
`stream_snapshot`	Yes	Yes	Yes	Yes
`turn_started`	Yes	Yes	Yes	Yes
`text_delta`	Yes	Yes	Yes	Yes
`turn_complete`	Yes	Yes	Yes	Yes
`turn_error`	Yes	Yes	Yes	Yes
`message.delta`	Yes	Yes	Yes	Yes
`message.complete`	Yes	Yes	Yes	Yes
`tool_call`	Yes	Yes	Yes	Yes
`tool_result`	Yes	Yes	Yes	Yes
`tool_call_start`	Yes	Yes	Yes	Yes
`tool_call_delta`	Yes	Yes	Yes	Yes
`tool_error`	Yes	Yes	Yes	Yes
`question_requested`	Yes	Yes	Yes	Yes
`permission_requested`	Yes	Yes	Yes	Yes
`approval_resolved`	Yes	Yes	Yes	Yes
`thinking_start`	Yes	Yes	Yes	Yes
`thinking_progress`	Yes	Yes	Yes	Yes
`thinking_complete`	Yes	Yes	Yes	Yes
`terminal_stream`	Yes	Yes	Yes	Yes
`terminal_complete`	Yes	Yes	Yes	Yes
`sandbox_init`	Yes	Yes	Yes	Yes
`sandbox_provisioning`	Yes	Yes	Yes	Yes
`sandbox_ready`	Yes	Yes	Yes	Yes
`sandbox_removed`	Yes	Yes	Yes	Yes
`usage_update`	Yes	Yes	Yes	Yes
`usage_context`	Yes	Yes	Yes	Yes
`gap`	Yes	Yes	Yes	Yes
`replay_complete`	Yes	Yes	Yes	Yes
`file_list`	Yes	Yes	Yes	Yes
`file_content`	Yes	Yes	Yes	Yes
`file_history_result`	Yes	Yes	Yes	Yes
`file_changed`	Yes	Yes	Yes	Yes
`steer_sent`	Yes	Yes	Yes	Yes
`stop_acknowledged`	Yes	Yes	Yes	Yes
`server_shutdown`	Yes	Yes	Yes	Yes
`history`	Yes	Yes	Yes	Yes
`events`	Yes	Yes	Yes	Yes
`member_list`	Yes	Yes	Yes	Yes
`member_updated`	Yes	Yes	Yes	Yes
`member_removed`	Yes	Yes	Yes	Yes
`error`	Yes	Yes	Yes	Yes
`pong`	Yes	Yes	Yes	Yes

Testing Methodology

The SDK test suites do not exist to demonstrate that the code works. They exist to demonstrate that aggressive, systematic attempts to break the code have failed. This distinction — between confirmation and refutation — is the foundation of the testing methodology. The approach draws from Karl Popper’s philosophy of science: a claim is only as credible as the severity of the tests it has survived. A test that passes trivially provides no evidence of correctness.

Tests are Adversarial

Every test is written from the perspective of an attacker. What input would cause a crash? What timing would cause a race condition? What encoding would corrupt deserialization?

Claims are Falsifiable

“The client handles text_delta events” is not falsifiable. “A text_delta event with a 1MB text field is delivered to the handler without truncation” is falsifiable — and tested.

Mock Oracles, Not Mock Implementations

Each SDK test suite runs against a mock gateway that speaks the actual wire protocol. The mock is an oracle that validates conformance, not a stub returning canned responses.

No Confirmation Bias

Tests do not confirm expected behavior by feeding expected inputs. They probe boundaries: empty strings, null fields, maximum-size payloads, negative numbers, concurrent mutations.

Test Architecture per SDK

TypeScript: Runs a real Bun.serve WebSocket server implementing the full wire protocol. The mock gateway sends welcome, connected, and authenticated on connection, responds to all 21 message types, and simulates streaming event sequences.
Rust: Relies on serde’s compile-time guarantees plus runtime JSON round-trip verification. Every variant of ClientMessage (21) and ServerEvent (51) is tested for exact wire format conformance with explicit camelCase field assertions.
Python: Uses websockets.serve to run a mock gateway in the same asyncio event loop. Tests cover connection lifecycle, all session methods, dataclass parsing, ServerEvent properties, category predicates, and the event handler system.
Swift: Uses Swift Testing framework (@Test, #expect) with Codable round-trip verification. All 51 ServerEvent and 21 ClientMessage variants are tested for exact wire format conformance via CodingKeys.

Adversarial Patterns Tested

All four SDKs are tested against these adversarial scenarios:

Malformed server data: Invalid JSON, wrong field types, missing required fields, extra unknown fields
Request timeouts: Server never responds; pending promises/futures must reject, not hang
Large payloads: 1MB text fields, deeply nested JSON in tool args, thousands of sessions in a list
Unicode edge cases: Emoji, CJK, RTL, combining characters, zero-width characters, surrogate pairs
Numeric edge cases: seq: 0, seq: -1, seq: 9007199254740991 (JS MAX_SAFE_INTEGER), i64::MAX
Unknown event types: Forward-compatible handling via Unknown variant, wildcard handlers, or .unknown case
Concurrent operations: Multiple in-flight requests resolve to correct responses without cross-contamination

Coverage Statistics

SDK	Tests	Assertions	Message Types	Event Types	Error Types
TypeScript	137	~600	21/21	51/51	All
Rust	178	~800	21/21	51/51	All
Python	173	~800	21/21	51/51	All
Swift	193	~900	21/21	51/51	All
Total (SDKs)	681	~3,100	21/21	51/51	All

The gateway itself has an additional 9 integration tests that validate server-side protocol handling, session lifecycle, event mapping, and error paths against an in-process gateway instance with SQLite in-memory databases and mock Podium connections.

Running the Tests

bun test

Run the full test suite across all SDKs in a single command:

bun test && \
(cd sdk/typescript && bun test) && \
(cd sdk/rust && cargo test) && \
(cd sdk/python && python -m pytest tests/ -v) && \
(cd sdk/swift && swift test)

This is the complete validation that must pass before any code is merged.

Diminuendo

Protocol

Clients

Operations

​SDKs

​Design Principles

Full Protocol Parity

Zero Gateway Dependencies

Native Idioms

Adversarial Test Suites

​SDK Comparison

​TypeScript SDK

​Installation

​Quick Start

​Connection Lifecycle

​Session Management

​Session Interaction

​Event Handling

​File Access

​Error Handling

​Complete Example

​Rust SDK

​Installation

​Quick Start

​Connection Lifecycle

​Session Management

​Session Interaction

​Event Handling

​File Access

​Error Types

​Complete Example

​Python SDK

​Installation

​Quick Start

​Connection Lifecycle

​Session Management

​Session Interaction

​Event Handling

​File Access

​Error Handling

​Complete Example

​Swift SDK

​Installation

​Quick Start

​Connection Lifecycle

​Session Management

​Session Interaction

​Event Handling

​File Access

​Error Types

​Types

​Complete Example

​Protocol Coverage Matrix

​Testing Methodology

Tests are Adversarial

Claims are Falsifiable

Mock Oracles, Not Mock Implementations

No Confirmation Bias

​Test Architecture per SDK

​Adversarial Patterns Tested

​Coverage Statistics

​Running the Tests

SDKs

Design Principles

SDK Comparison

TypeScript SDK

Installation

Quick Start

Connection Lifecycle

Session Management

Session Interaction

Event Handling

File Access

Error Handling

Complete Example

Rust SDK

Installation

Quick Start

Connection Lifecycle

Session Management

Session Interaction

Event Handling

File Access

Error Types

Complete Example

Python SDK

Installation

Quick Start

Connection Lifecycle

Session Management

Session Interaction

Event Handling

File Access

Error Handling

Complete Example

Swift SDK

Installation

Quick Start

Connection Lifecycle

Session Management

Session Interaction

Event Handling

File Access

Error Types

Types

Complete Example

Protocol Coverage Matrix

Testing Methodology

Test Architecture per SDK

Adversarial Patterns Tested

Coverage Statistics

Running the Tests