@camerontaylor/paseo-client 0.8.0-fork.1

package/dist/daemon-client.js

@@ -0,0 +1,4783 @@
+import { ProviderSnapshotUpdates } from "./provider-snapshots/index.js";
+import { ConnectionSubscriptions, DEFAULT_CLIENT_CAPABILITIES, } from "./connection/index.js";
+import { CreationClient } from "./creation/index.js";
+import { CLIENT_CAPS } from "@camerontaylor/paseo-protocol/client-capabilities";
+import { parsePluginSourceReference } from "@camerontaylor/paseo-protocol/plugin-source-reference";
+import { AgentCreateFailedStatusPayloadSchema, AgentCreatedStatusPayloadSchema, AgentRefreshedStatusPayloadSchema, AgentResumedStatusPayloadSchema, parseServerInfoStatusPayload, RestartRequestedStatusPayloadSchema, ShutdownRequestedStatusPayloadSchema, DaemonUpdateResponseSchema, SessionInboundMessageSchema, } from "@camerontaylor/paseo-protocol/messages";
+import { validateWSOutboundMessage } from "@camerontaylor/paseo-protocol/validation/ws-outbound";
+import { isRelayClientWebSocketUrl } from "@camerontaylor/paseo-protocol/daemon-endpoints";
+import { terminalSubscriptionKey } from "@camerontaylor/paseo-protocol/terminal-subscription-key";
+import { asUint8Array, decodeFileTransferFrame, encodeFileTransferFrame, decodeTerminalStreamFrame, FileTransferOpcode, TerminalStreamOpcode, } from "@camerontaylor/paseo-protocol/binary-frames/index";
+import { createRelayE2eeTransportFactory, createWebSocketTransportFactory, decodeMessageData, defaultWebSocketFactory, describeTransportClose, describeTransportError, } from "./daemon-client-transport.js";
+import { DaemonClientRuntimeMetrics } from "./daemon-client-runtime-metrics.js";
+import { normalizeListProviderModelsPayload, normalizeProviderSnapshotUpdateMessage, normalizeProvidersSnapshotPayload, } from "./compat/normalize-provider-models.js";
+import { TerminalStreamRouter } from "./terminal-stream-router.js";
+const consoleLogger = {
+    debug: () => { },
+    info: (obj, msg) => console.log(msg, obj),
+    warn: (obj, msg) => console.warn(msg, obj),
+    error: (obj, msg) => console.error(msg, obj),
+};
+const perfNow = typeof performance !== "undefined" && typeof performance.now === "function"
+    ? () => performance.now()
+    : () => Date.now();
+const PROJECT_GITHUB_CLONE_TIMEOUT_MS = 5 * 60 * 1000;
+function normalizePassword(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    return value.length > 0 ? value : null;
+}
+function extractCorrelatedResponseIdentity(input) {
+    if (!input || typeof input !== "object") {
+        return null;
+    }
+    const envelope = input;
+    if (envelope.type !== "session" || !envelope.message || typeof envelope.message !== "object") {
+        return null;
+    }
+    const message = envelope.message;
+    if (typeof message.type !== "string" ||
+        !(message.type === "rpc_error" ||
+            message.type.endsWith("_response") ||
+            message.type.endsWith(".response") ||
+            message.type.endsWith("/response"))) {
+        return null;
+    }
+    if (!message.payload || typeof message.payload !== "object") {
+        return null;
+    }
+    const payload = message.payload;
+    if (typeof payload.requestId !== "string") {
+        return null;
+    }
+    return {
+        requestId: payload.requestId,
+        responseType: message.type,
+    };
+}
+// COMPAT(daemon-client-object-options): added in v0.1.102; remove after
+// 2026-12-29 once SDK callers have migrated to object parameters.
+function normalizeFetchAgentOptions(input, legacyOptions) {
+    if (typeof input !== "string") {
+        return input;
+    }
+    if (typeof legacyOptions === "string") {
+        return { agentId: input, requestId: legacyOptions };
+    }
+    return { agentId: input, ...legacyOptions };
+}
+function normalizeListCommandsOptions(input, legacyOptions) {
+    if (typeof input !== "string") {
+        return input;
+    }
+    if (typeof legacyOptions === "string") {
+        return { agentId: input, requestId: legacyOptions };
+    }
+    return { agentId: input, ...legacyOptions };
+}
+class DaemonRpcError extends Error {
+    constructor(params) {
+        const parts = [params.error];
+        if (params.requestType)
+            parts.push(`requestType=${params.requestType}`);
+        if (params.code)
+            parts.push(`code=${params.code}`);
+        super(parts.join(" "));
+        this.name = "DaemonRpcError";
+        this.requestId = params.requestId;
+        this.requestType = params.requestType;
+        this.code = params.code;
+    }
+}
+class DaemonProtocolError extends Error {
+    constructor(identity) {
+        const responseLabel = identity.responseType ?? "unknown response";
+        super(`Response validation failed for ${responseLabel}`);
+        this.code = "invalid_response";
+        this.name = "DaemonProtocolError";
+        this.requestId = identity.requestId;
+        this.responseType = identity.responseType;
+    }
+}
+class PingTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`Ping timed out (${timeoutMs}ms)`);
+        this.timeoutMs = timeoutMs;
+        this.name = "PingTimeoutError";
+    }
+}
+function toTimeoutError(error, label, timeoutMs) {
+    if (error instanceof PingTimeoutError) {
+        return new Error(`${label} timed out (${timeoutMs}ms)`);
+    }
+    return error instanceof Error ? error : new Error(String(error));
+}
+const DEFAULT_RECONNECT_BASE_DELAY_MS = 1500;
+const DEFAULT_RECONNECT_MAX_DELAY_MS = 30000;
+const DEFAULT_SESSION_RPC_TIMEOUT_MS = 60000;
+const PUSH_TOKEN_REVOCATION_TIMEOUT_MS = 2000;
+const DEFAULT_CONNECT_TIMEOUT_MS = 15000;
+const DEFAULT_LIVENESS_TIMEOUT_MS = 5000;
+const LIVENESS_HEARTBEAT_INTERVAL_MS = 10000;
+const LIVENESS_HEARTBEAT_TIMEOUT_MS = 15000;
+const LIVENESS_FAILURE_RECONNECT_THRESHOLD = 2;
+/** Default timeout for waiting for connection before sending queued messages */
+const DEFAULT_SEND_QUEUE_TIMEOUT_MS = DEFAULT_SESSION_RPC_TIMEOUT_MS;
+const DEFAULT_DICTATION_FINISH_ACCEPT_TIMEOUT_MS = DEFAULT_SESSION_RPC_TIMEOUT_MS;
+const DEFAULT_DICTATION_FINISH_FALLBACK_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_DICTATION_FINISH_TIMEOUT_GRACE_MS = 5000;
+function isWaiterTimeoutError(error) {
+    return error instanceof Error && error.message.startsWith("Timeout waiting for message");
+}
+function normalizeClientId(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function decodeBase64ToBytes(base64) {
+    const binary = globalThis.atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+}
+function legacyExplorerFileToBytes(file) {
+    let bytes;
+    if (file.encoding === "base64" && file.content) {
+        bytes = decodeBase64ToBytes(file.content);
+    }
+    else if (file.encoding === "utf-8" && file.content) {
+        bytes = new TextEncoder().encode(file.content);
+    }
+    else {
+        bytes = new Uint8Array();
+    }
+    return {
+        bytes,
+        mime: file.mimeType ?? "application/octet-stream",
+        size: file.size,
+        path: file.path,
+        kind: file.kind,
+        modifiedAt: file.modifiedAt,
+        revision: file.revision,
+    };
+}
+function binaryFileKind(mime, encoding) {
+    if (mime.startsWith("image/")) {
+        return "image";
+    }
+    if (encoding === "utf-8" || mime.startsWith("text/") || mime === "application/json") {
+        return "text";
+    }
+    return "binary";
+}
+function concatByteChunks(chunks, size) {
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+function getTransportFrameSize(frame) {
+    if (typeof frame === "string") {
+        return frame.length;
+    }
+    return frame.byteLength;
+}
+function describeInboundTransportFrame(frame, rawBytes) {
+    if (typeof frame === "string") {
+        return { kind: "text", size: String(frame.length) };
+    }
+    if (rawBytes) {
+        return { kind: "binary", size: String(rawBytes.byteLength) };
+    }
+    return { kind: "unknown", size: "0" };
+}
+function hashForLog(value) {
+    let hash = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        hash = (hash * 31 + value.charCodeAt(index)) | 0;
+    }
+    return `h_${Math.abs(hash).toString(16)}`;
+}
+function toReasonCode(reason) {
+    if (!reason) {
+        return null;
+    }
+    const normalized = reason.toLowerCase();
+    if (normalized.includes("timed out")) {
+        return "connect_timeout";
+    }
+    if (normalized.includes("disposed")) {
+        return "disposed";
+    }
+    if (normalized.includes("client closed")) {
+        return "client_closed";
+    }
+    if (normalized.includes("transport")) {
+        return "transport_error";
+    }
+    if (normalized.includes("failed to connect")) {
+        return "connect_failed";
+    }
+    return "unknown";
+}
+export class DaemonClient {
+    constructor(config) {
+        this.config = config;
+        this.providerSnapshotUpdates = new ProviderSnapshotUpdates({
+            fetch: (cwd) => this.requestProvidersSnapshot({ cwd }),
+            emit: (message) => this.deliverSessionMessage(message),
+            failed: (error) => this.logger.error({ err: error }, "Failed to resolve provider snapshot"),
+        });
+        this.subscriptions = new ConnectionSubscriptions({
+            timelines: (agentIds) => (this.isConnected ? this.sendTimelineSubscription(agentIds) : null),
+            events: (events) => this.sendEventSubscription(events),
+            failed: (error) => this.logger.error({ err: error }, "Failed to update connection subscriptions"),
+        });
+        this.transport = null;
+        this.transportCleanup = [];
+        this.rawMessageListeners = new Set();
+        this.messageHandlers = new Map();
+        this.eventListeners = new Set();
+        this.waiters = new Set();
+        this.checkoutStatusInFlight = new Map();
+        this.connectionListeners = new Set();
+        this.reconnectTimeout = null;
+        this.connectTimeout = null;
+        this.pendingGenericTransportErrorTimeout = null;
+        this.reconnectAttempt = 0;
+        this.shouldReconnect = true;
+        this.connectPromise = null;
+        this.connectResolve = null;
+        this.connectReject = null;
+        this.lastErrorValue = null;
+        this.connectionState = { status: "idle" };
+        this.checkoutDiffSubscriptions = new Map();
+        this.terminalDirectorySubscriptions = new Map();
+        this.fileSubscriptions = new Map();
+        this.terminalStreams = new TerminalStreamRouter();
+        this.pendingBinaryFileReads = new Map();
+        this.activeBinaryFileTransfers = new Map();
+        this.completedBinaryFileReads = new Map();
+        this.pendingSendQueue = [];
+        this.lastServerInfoMessage = null;
+        this.runtimeMetricsInterval = null;
+        this.runtimeMetrics = null;
+        this.pingProbe = null;
+        this.livenessHeartbeatTimer = null;
+        this.lastLivenessRttMs = null;
+        this.consecutiveLivenessFailures = 0;
+        // ============================================================================
+        // Agent Lifecycle
+        // ============================================================================
+        this.creations = new CreationClient({
+            supports: () => this.lastServerInfoMessage?.features?.creationLifecycle === true,
+            connected: () => this.connectionState.status === "connected",
+            requestId: () => this.createRequestId(),
+            request: (kind, input) => kind === "workspace"
+                ? this.sendCorrelatedSessionRequest({
+                    requestId: input.requestId,
+                    message: { ...input, type: "workspace.create.request" },
+                    responseType: "workspace.create.response",
+                    timeout: 0,
+                })
+                : this.sendCorrelatedSessionRequest({
+                    requestId: input.requestId,
+                    message: { ...input, type: "agent.create.request" },
+                    responseType: "agent.create.response",
+                    timeout: 0,
+                }),
+            subscribe: async (kind, idempotencyKey, subscribe = true) => {
+                const result = await this.sendCorrelatedSessionRequest({
+                    message: { type: "creation.subscribe.request", kind, idempotencyKey, subscribe },
+                    responseType: "creation.subscribe.response",
+                });
+                if (result.error)
+                    throw new Error(result.error);
+                return result.snapshot;
+            },
+            legacyAgent: (input) => this.createLegacyAgent(input),
+            legacyWorkspace: (input) => this.createLegacyWorkspace(input, input.requestId),
+            sendMessage: (id, text, options) => this.sendMessage(id, text, options),
+        });
+        this.logger = config.logger ?? consoleLogger;
+        this.logConnectionPath = isRelayClientWebSocketUrl(this.config.url) ? "relay" : "direct";
+        let parsedUrlForLog = null;
+        try {
+            parsedUrlForLog = new URL(this.config.url);
+        }
+        catch {
+            parsedUrlForLog = null;
+        }
+        const parsedServerIdForLog = normalizeClientId(parsedUrlForLog?.searchParams.get("serverId"));
+        this.logServerId = parsedServerIdForLog ?? parsedUrlForLog?.host ?? null;
+        const resolvedClientId = normalizeClientId(this.config.clientId);
+        if (!resolvedClientId) {
+            throw new Error("Daemon client requires a non-empty clientId");
+        }
+        this.config.clientId = resolvedClientId;
+        this.logClientIdHash = hashForLog(resolvedClientId);
+        this.logGeneration =
+            typeof this.config.runtimeGeneration === "number" &&
+                Number.isFinite(this.config.runtimeGeneration)
+                ? this.config.runtimeGeneration
+                : null;
+        const runtimeMetricsIntervalMs = typeof config.runtimeMetricsIntervalMs === "number" && config.runtimeMetricsIntervalMs > 0
+            ? config.runtimeMetricsIntervalMs
+            : 0;
+        if (runtimeMetricsIntervalMs > 0) {
+            const runtimeMetricsWindowMs = typeof config.runtimeMetricsWindowMs === "number" && config.runtimeMetricsWindowMs > 0
+                ? Math.max(config.runtimeMetricsWindowMs, runtimeMetricsIntervalMs)
+                : undefined;
+            this.runtimeMetrics = new DaemonClientRuntimeMetrics(this.logger, {
+                connectionPath: this.logConnectionPath,
+                serverId: this.logServerId,
+                getConnectionStatus: () => this.connectionState.status,
+            }, runtimeMetricsWindowMs ? { windowMs: runtimeMetricsWindowMs } : undefined);
+            this.runtimeMetricsInterval = setInterval(() => {
+                this.runtimeMetrics?.flush();
+            }, runtimeMetricsIntervalMs);
+        }
+    }
+    // ============================================================================
+    // Connection
+    // ============================================================================
+    async connect() {
+        if (this.connectionState.status === "disposed") {
+            throw new Error("Daemon client is disposed");
+        }
+        if (this.connectionState.status === "connected") {
+            return;
+        }
+        if (this.connectPromise) {
+            return this.connectPromise;
+        }
+        this.shouldReconnect = true;
+        this.connectPromise = new Promise((resolve, reject) => {
+            this.connectResolve = resolve;
+            this.connectReject = reject;
+            this.attemptConnect();
+        });
+        return this.connectPromise;
+    }
+    attemptConnect() {
+        if (this.connectionState.status === "disposed") {
+            this.rejectConnect(new Error("Daemon client is disposed"));
+            return;
+        }
+        if (!this.shouldReconnect) {
+            this.rejectConnect(new Error("Daemon client is closed"));
+            return;
+        }
+        if (this.connectionState.status === "connecting") {
+            return;
+        }
+        const headers = {};
+        const password = normalizePassword(this.config.password);
+        if (password) {
+            headers.Authorization = `Bearer ${password}`;
+        }
+        else if (this.config.authHeader) {
+            headers.Authorization = this.config.authHeader;
+        }
+        const protocols = password ? [`paseo.bearer.${password}`] : undefined;
+        try {
+            // Reconnect can overlap with browser close/error delivery ordering.
+            // Always dispose previous transport before constructing the next one.
+            this.disposeTransport();
+            const baseTransportFactory = this.config.transportFactory ??
+                createWebSocketTransportFactory(this.config.webSocketFactory ?? defaultWebSocketFactory);
+            const shouldUseRelayE2ee = this.config.e2ee?.enabled === true && isRelayClientWebSocketUrl(this.config.url);
+            let transportFactory = baseTransportFactory;
+            if (shouldUseRelayE2ee) {
+                const daemonPublicKeyB64 = this.config.e2ee?.daemonPublicKeyB64;
+                if (!daemonPublicKeyB64) {
+                    throw new Error("daemonPublicKeyB64 is required for relay E2EE");
+                }
+                transportFactory = createRelayE2eeTransportFactory({
+                    baseFactory: baseTransportFactory,
+                    daemonPublicKeyB64,
+                    logger: this.logger,
+                });
+            }
+            const transportUrl = this.resolveTransportUrlForAttempt();
+            const transport = transportFactory({
+                url: transportUrl,
+                headers,
+                ...(protocols ? { protocols } : {}),
+            });
+            this.transport = transport;
+            this.lastServerInfoMessage = null;
+            this.updateConnectionState({
+                status: "connecting",
+                attempt: this.reconnectAttempt,
+            }, { event: "CONNECT_REQUEST" });
+            this.resetConnectTimeout();
+            const timeoutMs = Math.max(1, this.config.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS);
+            this.connectTimeout = setTimeout(() => {
+                if (this.connectionState.status !== "connecting") {
+                    return;
+                }
+                this.lastErrorValue = "Connection timed out";
+                this.disposeTransport(1001, "Connection timed out");
+                this.scheduleReconnect({
+                    reason: "Connection timed out",
+                    event: "CONNECT_TIMEOUT",
+                    reasonCode: "connect_timeout",
+                });
+            }, timeoutMs);
+            this.transportCleanup = [
+                transport.onOpen(() => {
+                    if (this.pendingGenericTransportErrorTimeout) {
+                        clearTimeout(this.pendingGenericTransportErrorTimeout);
+                        this.pendingGenericTransportErrorTimeout = null;
+                    }
+                    this.lastErrorValue = null;
+                    this.sendHelloMessage();
+                }),
+                transport.onClose((event) => {
+                    this.resetConnectTimeout();
+                    if (this.pendingGenericTransportErrorTimeout) {
+                        clearTimeout(this.pendingGenericTransportErrorTimeout);
+                        this.pendingGenericTransportErrorTimeout = null;
+                    }
+                    const reason = describeTransportClose(event);
+                    if (reason) {
+                        this.lastErrorValue = reason;
+                    }
+                    this.scheduleReconnect({
+                        reason,
+                        event: "TRANSPORT_CLOSE",
+                        reasonCode: "transport_closed",
+                    });
+                }),
+                transport.onError((event) => {
+                    this.resetConnectTimeout();
+                    const reason = describeTransportError(event);
+                    const isGeneric = reason === "Transport error";
+                    // Browser WebSocket.onerror often provides no useful details and is followed
+                    // by a close event (often with code 1006). Prefer surfacing the close details
+                    // instead of immediately disconnecting with a generic "Transport error".
+                    if (isGeneric) {
+                        this.lastErrorValue ?? (this.lastErrorValue = reason);
+                        if (!this.pendingGenericTransportErrorTimeout) {
+                            this.pendingGenericTransportErrorTimeout = setTimeout(() => {
+                                this.pendingGenericTransportErrorTimeout = null;
+                                if (this.connectionState.status === "connected" ||
+                                    this.connectionState.status === "connecting") {
+                                    this.lastErrorValue = reason;
+                                    this.scheduleReconnect({
+                                        reason,
+                                        event: "TRANSPORT_ERROR",
+                                        reasonCode: "transport_error",
+                                    });
+                                }
+                            }, 250);
+                        }
+                        return;
+                    }
+                    if (this.pendingGenericTransportErrorTimeout) {
+                        clearTimeout(this.pendingGenericTransportErrorTimeout);
+                        this.pendingGenericTransportErrorTimeout = null;
+                    }
+                    this.lastErrorValue = reason;
+                    this.scheduleReconnect({
+                        reason,
+                        event: "TRANSPORT_ERROR",
+                        reasonCode: "transport_error",
+                    });
+                }),
+                transport.onMessage((data) => this.handleTransportMessage(data)),
+            ];
+        }
+        catch (error) {
+            this.resetConnectTimeout();
+            const message = error instanceof Error ? error.message : "Failed to connect";
+            this.lastErrorValue = message;
+            this.scheduleReconnect({
+                reason: message,
+                event: "CONNECT_FAILED",
+                reasonCode: "connect_failed",
+            });
+            this.rejectConnect(error instanceof Error ? error : new Error(message));
+        }
+    }
+    resolveConnect() {
+        if (this.connectResolve) {
+            this.connectResolve();
+        }
+        this.connectPromise = null;
+        this.connectResolve = null;
+        this.connectReject = null;
+    }
+    rejectConnect(error) {
+        if (this.connectReject) {
+            this.connectReject(error);
+        }
+        this.connectPromise = null;
+        this.connectResolve = null;
+        this.connectReject = null;
+    }
+    async close() {
+        if (this.connectionState.status === "disposed") {
+            return;
+        }
+        this.shouldReconnect = false;
+        this.subscriptions.close();
+        this.connectPromise = null;
+        this.connectResolve = null;
+        this.connectReject = null;
+        if (this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+            this.reconnectTimeout = null;
+        }
+        this.resetConnectTimeout();
+        this.disposeTransport(1000, "Client closed");
+        this.providerSnapshotUpdates.clear();
+        this.clearWaiters(new Error("Daemon client closed"));
+        this.creations.close();
+        this.rejectPendingSendQueue(new Error("Daemon client closed"));
+        this.rejectPingProbe(new Error("Daemon client closed"));
+        this.terminalStreams.clearSlots();
+        this.fileSubscriptions.clear();
+        this.lastServerInfoMessage = null;
+        if (this.runtimeMetricsInterval) {
+            clearInterval(this.runtimeMetricsInterval);
+            this.runtimeMetricsInterval = null;
+            this.runtimeMetrics?.flush({ final: true });
+            this.runtimeMetrics = null;
+        }
+        this.updateConnectionState({ status: "disposed" }, { event: "DISPOSE", reason: "Client closed", reasonCode: "disposed" });
+    }
+    ensureConnected() {
+        if (this.connectionState.status === "disposed") {
+            return;
+        }
+        if (!this.shouldReconnect) {
+            this.shouldReconnect = true;
+        }
+        if (this.connectionState.status === "connected" ||
+            this.connectionState.status === "connecting") {
+            return;
+        }
+        if (this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+            this.reconnectTimeout = null;
+        }
+        if (this.connectPromise) {
+            this.attemptConnect();
+            return;
+        }
+        void this.connect();
+    }
+    getConnectionState() {
+        return this.connectionState;
+    }
+    subscribeConnectionStatus(listener) {
+        this.connectionListeners.add(listener);
+        listener(this.connectionState);
+        return () => {
+            this.connectionListeners.delete(listener);
+        };
+    }
+    get isConnected() {
+        return this.connectionState.status === "connected";
+    }
+    get isConnecting() {
+        return this.connectionState.status === "connecting";
+    }
+    get lastError() {
+        return this.lastErrorValue;
+    }
+    getLastLivenessRttMs() {
+        return this.lastLivenessRttMs;
+    }
+    // ============================================================================
+    // Message Subscription
+    // ============================================================================
+    subscribe(handler) {
+        this.eventListeners.add(handler);
+        this.updateEventSubscriptions();
+        return () => {
+            this.eventListeners.delete(handler);
+            this.updateEventSubscriptions();
+        };
+    }
+    subscribeRawMessages(handler) {
+        this.rawMessageListeners.add(handler);
+        return () => {
+            this.rawMessageListeners.delete(handler);
+        };
+    }
+    on(arg1, arg2) {
+        if (typeof arg1 === "function") {
+            return this.subscribe(arg1);
+        }
+        const type = arg1;
+        const handler = arg2;
+        if (!this.messageHandlers.has(type)) {
+            this.messageHandlers.set(type, new Set());
+        }
+        this.messageHandlers.get(type).add(handler);
+        this.updateEventSubscriptions();
+        return () => {
+            const handlers = this.messageHandlers.get(type);
+            if (!handlers) {
+                return;
+            }
+            handlers.delete(handler);
+            if (handlers.size === 0) {
+                this.messageHandlers.delete(type);
+            }
+            this.updateEventSubscriptions();
+        };
+    }
+    onAgentAttentionRequired(handler) {
+        const unsubscribeLegacy = this.on("agent_stream", (message) => {
+            if (message.payload.event.type !== "attention_required") {
+                return;
+            }
+            const event = message.payload.event;
+            handler({
+                agentId: message.payload.agentId,
+                reason: event.reason,
+                timestamp: event.timestamp,
+                shouldNotify: event.shouldNotify,
+                ...(event.notification ? { notification: event.notification } : {}),
+            });
+        });
+        const unsubscribeDedicated = this.on("agent_attention_required", (message) => {
+            handler(message.payload);
+        });
+        return () => {
+            unsubscribeLegacy();
+            unsubscribeDedicated();
+        };
+    }
+    // ============================================================================
+    // Core Send Helpers
+    // ============================================================================
+    beginTraceSection(name, args) {
+        const trace = this.config.trace;
+        if (!trace?.isEnabled()) {
+            return false;
+        }
+        trace.beginSection(name, args);
+        return true;
+    }
+    endTraceSection(isOpen) {
+        if (isOpen) {
+            this.config.trace?.endSection();
+        }
+    }
+    traceInstant(name, args) {
+        const isOpen = this.beginTraceSection(name, args);
+        this.endTraceSection(isOpen);
+    }
+    sendJsonMessage(envelopeType, messageType, message) {
+        this.traceInstant("paseo.ws.message.outbound", {
+            envelopeType,
+            messageType,
+        });
+        this.sendTransportFrame(JSON.stringify(message));
+    }
+    sendTransportFrame(frame) {
+        if (!this.transport) {
+            throw new Error("Transport not connected");
+        }
+        const isOpen = this.beginTraceSection("paseo.ws.frame.outbound", {
+            kind: typeof frame === "string" ? "text" : "binary",
+            size: String(getTransportFrameSize(frame)),
+        });
+        try {
+            this.transport.send(frame);
+        }
+        finally {
+            this.endTraceSection(isOpen);
+        }
+    }
+    /**
+     * Send a session message. For fire-and-forget messages (heartbeats, etc.),
+     * failures are suppressed if `suppressSendErrors` is configured.
+     * For RPC methods that wait for responses, use `sendSessionMessageOrThrow` instead.
+     */
+    sendSessionMessage(message) {
+        if (!this.transport || this.connectionState.status !== "connected") {
+            if (this.config.suppressSendErrors) {
+                return;
+            }
+            throw new Error(`Transport not connected (status: ${this.connectionState.status})`);
+        }
+        const payload = SessionInboundMessageSchema.parse(message);
+        try {
+            this.sendJsonMessage("session", payload.type, { type: "session", message: payload });
+        }
+        catch (error) {
+            if (this.config.suppressSendErrors) {
+                return;
+            }
+            throw error instanceof Error ? error : new Error(String(error));
+        }
+    }
+    sendBinaryFrame(frame) {
+        if (!this.transport || this.connectionState.status !== "connected") {
+            if (this.config.suppressSendErrors) {
+                return;
+            }
+            throw new Error(`Transport not connected (status: ${this.connectionState.status})`);
+        }
+        try {
+            this.traceInstant("paseo.ws.message.outbound", {
+                envelopeType: "binary",
+                messageType: "binary",
+            });
+            this.sendTransportFrame(frame);
+        }
+        catch (error) {
+            if (this.config.suppressSendErrors) {
+                return;
+            }
+            throw error instanceof Error ? error : new Error(String(error));
+        }
+    }
+    /**
+     * Send a session message for RPC methods that create waiters.
+     * If the connection is still being established ("connecting"), the message
+     * is queued and will be sent once connected (or rejected after timeout).
+     * This prevents waiters from hanging forever when called during connection.
+     */
+    sendSessionMessageOrThrow(message) {
+        const status = this.connectionState.status;
+        // If connected, send immediately
+        if (this.transport && status === "connected") {
+            const payload = SessionInboundMessageSchema.parse(message);
+            this.sendJsonMessage("session", payload.type, { type: "session", message: payload });
+            return Promise.resolve();
+        }
+        // If connecting, queue the message to be sent once connected
+        if (status === "connecting") {
+            return new Promise((resolve, reject) => {
+                const timeoutHandle = setTimeout(() => {
+                    // Remove from queue
+                    const idx = this.pendingSendQueue.findIndex((p) => p.resolve === resolve);
+                    if (idx !== -1) {
+                        this.pendingSendQueue.splice(idx, 1);
+                    }
+                    reject(new Error(`Timed out waiting for connection to send message`));
+                }, DEFAULT_SEND_QUEUE_TIMEOUT_MS);
+                this.pendingSendQueue.push({ message, resolve, reject, timeoutHandle });
+            });
+        }
+        // Not connected and not connecting - fail immediately
+        return Promise.reject(new Error(`Transport not connected (status: ${status})`));
+    }
+    /**
+     * Flush pending send queue - called when connection is established.
+     */
+    flushPendingSendQueue() {
+        const queue = this.pendingSendQueue;
+        this.pendingSendQueue = [];
+        for (const pending of queue) {
+            clearTimeout(pending.timeoutHandle);
+            try {
+                if (this.transport && this.connectionState.status === "connected") {
+                    const payload = SessionInboundMessageSchema.parse(pending.message);
+                    this.sendJsonMessage("session", payload.type, { type: "session", message: payload });
+                    pending.resolve();
+                }
+                else {
+                    pending.reject(new Error("Connection lost before message could be sent"));
+                }
+            }
+            catch (error) {
+                pending.reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        }
+    }
+    /**
+     * Reject all pending sends - called when connection fails or is closed.
+     */
+    rejectPendingSendQueue(error) {
+        const queue = this.pendingSendQueue;
+        this.pendingSendQueue = [];
+        for (const pending of queue) {
+            clearTimeout(pending.timeoutHandle);
+            pending.reject(error);
+        }
+    }
+    async sendRequest(params) {
+        const timeout = params.timeout ?? DEFAULT_SESSION_RPC_TIMEOUT_MS;
+        const { promise, cancel } = this.waitForWithCancel((msg) => {
+            if (msg.type === "rpc_error" && msg.payload.requestId === params.requestId) {
+                return {
+                    kind: "error",
+                    error: new DaemonRpcError({
+                        requestId: msg.payload.requestId,
+                        error: msg.payload.error,
+                        requestType: msg.payload.requestType,
+                        code: msg.payload.code,
+                    }),
+                };
+            }
+            const value = params.select(msg);
+            if (value === null) {
+                return null;
+            }
+            return { kind: "ok", value };
+        }, timeout, { ...params.options, requestId: params.requestId });
+        try {
+            await this.sendSessionMessageOrThrow(params.message);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            cancel(err);
+            void promise.catch(() => undefined);
+            throw err;
+        }
+        const result = await promise;
+        if (result.kind === "error") {
+            throw result.error;
+        }
+        return result.value;
+    }
+    async sendCorrelatedRequest(params) {
+        return this.sendRequest({
+            requestId: params.requestId,
+            message: params.message,
+            timeout: params.timeout,
+            options: params.options,
+            select: (msg) => {
+                const correlated = msg;
+                if (correlated.type !== params.responseType) {
+                    return null;
+                }
+                const payload = correlated.payload;
+                if (payload.requestId !== params.requestId) {
+                    return null;
+                }
+                if (!params.selectPayload) {
+                    return payload;
+                }
+                return params.selectPayload(payload);
+            },
+        });
+    }
+    sendCorrelatedSessionRequest(params) {
+        const resolvedRequestId = this.createRequestId(params.requestId);
+        const message = SessionInboundMessageSchema.parse({
+            ...params.message,
+            requestId: resolvedRequestId,
+        });
+        return this.sendCorrelatedRequest({
+            requestId: resolvedRequestId,
+            message,
+            responseType: params.responseType,
+            timeout: params.timeout,
+            options: { skipQueue: true },
+            ...(params.selectPayload ? { selectPayload: params.selectPayload } : {}),
+        });
+    }
+    sendNamespacedCorrelatedSessionRequest(params) {
+        const responseType = params.message.type.replace(/\.request$/, ".response");
+        return this.sendCorrelatedSessionRequest({
+            ...params,
+            responseType,
+        });
+    }
+    sendSessionMessageStrict(message) {
+        if (!this.transport || this.connectionState.status !== "connected") {
+            throw new Error("Transport not connected");
+        }
+        const payload = SessionInboundMessageSchema.parse(message);
+        try {
+            this.sendJsonMessage("session", payload.type, { type: "session", message: payload });
+        }
+        catch (error) {
+            throw error instanceof Error ? error : new Error(String(error));
+        }
+    }
+    async clearAgentAttention(agentId) {
+        const requestId = this.createRequestId();
+        const message = SessionInboundMessageSchema.parse({
+            type: "clear_agent_attention",
+            agentId,
+            requestId,
+        });
+        await this.sendRequest({
+            requestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "clear_agent_attention_response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== requestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+    }
+    async clearWorkspaceAttention(workspaceId) {
+        const requestId = this.createRequestId();
+        const message = SessionInboundMessageSchema.parse({
+            type: "workspace.clear_attention.request",
+            workspaceId,
+            requestId,
+        });
+        const response = await this.sendRequest({
+            requestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "workspace.clear_attention.response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== requestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+        if (!response.success) {
+            throw new Error(response.error ?? "Failed to clear workspace attention");
+        }
+    }
+    async markWorkspaceUnread(workspaceId, requestId) {
+        const response = await this.sendNamespacedCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "workspace.mark_unread.request",
+                workspaceId,
+            },
+        });
+        if (!response.success) {
+            throw new Error(response.error ?? "Failed to mark workspace unread");
+        }
+    }
+    sendHeartbeat(params) {
+        this.sendSessionMessage({
+            type: "client_heartbeat",
+            deviceType: params.deviceType,
+            focusedAgentId: params.focusedAgentId,
+            focusedTerminalId: params.focusedTerminalId ?? null,
+            lastActivityAt: params.lastActivityAt,
+            appVisible: params.appVisible,
+            appVisibilityChangedAt: params.appVisibilityChangedAt,
+        });
+    }
+    registerPushToken(token) {
+        this.sendSessionMessage({
+            type: "register_push_token",
+            token,
+        });
+    }
+    async unregisterPushToken(token) {
+        const requestId = this.createRequestId();
+        await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "push.unregister.request", token, requestId },
+            responseType: "push.unregister.response",
+            timeout: PUSH_TOKEN_REVOCATION_TIMEOUT_MS,
+        });
+    }
+    async ping(params) {
+        const requestId = params?.requestId ?? `ping-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        const clientSentAt = Date.now();
+        const payload = await this.sendRequest({
+            requestId,
+            message: { type: "ping", requestId, clientSentAt },
+            timeout: params?.timeoutMs ?? 5000,
+            select: (msg) => {
+                if (msg.type !== "pong")
+                    return null;
+                if (msg.payload.requestId !== requestId)
+                    return null;
+                if (typeof msg.payload.serverReceivedAt !== "number")
+                    return null;
+                if (typeof msg.payload.serverSentAt !== "number")
+                    return null;
+                return msg.payload;
+            },
+        });
+        return {
+            requestId,
+            clientSentAt,
+            serverReceivedAt: payload.serverReceivedAt,
+            serverSentAt: payload.serverSentAt,
+            rttMs: Date.now() - clientSentAt,
+        };
+    }
+    measureLatency(params) {
+        const timeoutMs = Math.max(1, params?.timeoutMs ?? DEFAULT_LIVENESS_TIMEOUT_MS);
+        return this.sendPingAwaitRtt({ timeoutMs, drivesLivenessFailure: false }).catch((error) => {
+            throw toTimeoutError(error, "Latency measurement", timeoutMs);
+        });
+    }
+    async livenessPing(params) {
+        const timeoutMs = Math.max(1, params?.timeoutMs ?? DEFAULT_LIVENESS_TIMEOUT_MS);
+        try {
+            const rttMs = await this.sendPingAwaitRtt({ timeoutMs, drivesLivenessFailure: true });
+            this.lastLivenessRttMs = rttMs;
+            return rttMs;
+        }
+        catch (error) {
+            throw toTimeoutError(error, "Liveness check", timeoutMs);
+        }
+    }
+    sendPingAwaitRtt(params) {
+        if (this.connectionState.status !== "connected" || !this.transport) {
+            return Promise.reject(new Error(`Transport not connected (status: ${this.connectionState.status})`));
+        }
+        if (this.pingProbe) {
+            return this.pingProbe.promise;
+        }
+        const startedAt = perfNow();
+        const timeoutMs = params.timeoutMs;
+        let resolveProbe = null;
+        let rejectProbe = null;
+        const promise = new Promise((resolve, reject) => {
+            resolveProbe = resolve;
+            rejectProbe = reject;
+        });
+        const probe = {
+            promise,
+            resolve: (value) => resolveProbe?.(value),
+            reject: (error) => rejectProbe?.(error),
+            timeoutHandle: setTimeout(() => {
+                if (this.pingProbe !== probe) {
+                    return;
+                }
+                this.pingProbe = null;
+                const error = new PingTimeoutError(timeoutMs);
+                probe.reject(error);
+                if (probe.drivesLivenessFailure) {
+                    this.recordLivenessFailure(toTimeoutError(error, "Liveness check", timeoutMs));
+                }
+            }, timeoutMs),
+            startedAt,
+            drivesLivenessFailure: params.drivesLivenessFailure,
+        };
+        this.pingProbe = probe;
+        try {
+            this.sendJsonMessage("ping", "ping", { type: "ping" });
+        }
+        catch (error) {
+            this.clearPingProbe();
+            const sendError = error instanceof Error ? error : new Error(String(error));
+            if (probe.drivesLivenessFailure) {
+                this.recordLivenessFailure(sendError);
+            }
+            return Promise.reject(sendError);
+        }
+        return promise;
+    }
+    startLivenessHeartbeat() {
+        this.stopLivenessHeartbeat();
+        this.lastLivenessRttMs = null;
+        this.scheduleNextLivenessHeartbeat();
+    }
+    stopLivenessHeartbeat() {
+        if (!this.livenessHeartbeatTimer) {
+            return;
+        }
+        clearTimeout(this.livenessHeartbeatTimer);
+        this.livenessHeartbeatTimer = null;
+    }
+    scheduleNextLivenessHeartbeat() {
+        if (this.connectionState.status !== "connected" || this.livenessHeartbeatTimer) {
+            return;
+        }
+        this.livenessHeartbeatTimer = setTimeout(() => {
+            this.livenessHeartbeatTimer = null;
+            this.livenessPing({ timeoutMs: LIVENESS_HEARTBEAT_TIMEOUT_MS })
+                .catch(() => { })
+                .finally(() => {
+                this.scheduleNextLivenessHeartbeat();
+            });
+        }, LIVENESS_HEARTBEAT_INTERVAL_MS);
+    }
+    // ============================================================================
+    // Agent RPCs (requestId-correlated)
+    // ============================================================================
+    async fetchAgents(options) {
+        const resolvedRequestId = this.createRequestId(options?.requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "fetch_agents_request",
+            requestId: resolvedRequestId,
+            ...(options?.scope ? { scope: options.scope } : {}),
+            ...(options?.filter ? { filter: options.filter } : {}),
+            ...(options?.sort ? { sort: options.sort } : {}),
+            ...(options?.page ? { page: options.page } : {}),
+            ...(options?.subscribe ? { subscribe: options.subscribe } : {}),
+            ...(options?.sync ? { sync: options.sync } : {}),
+        });
+        return this.sendRequest({
+            requestId: resolvedRequestId,
+            message,
+            timeout: options?.timeout,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "fetch_agents_response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== resolvedRequestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+    }
+    async fetchAgentHistory(options) {
+        const resolvedRequestId = this.createRequestId(options?.requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "fetch_agent_history_request",
+            requestId: resolvedRequestId,
+            ...(options?.filter ? { filter: options.filter } : {}),
+            ...(options?.search ? { search: options.search } : {}),
+            ...(options?.sort ? { sort: options.sort } : {}),
+            ...(options?.page ? { page: options.page } : {}),
+        });
+        return this.sendRequest({
+            requestId: resolvedRequestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "fetch_agent_history_response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== resolvedRequestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+    }
+    async fetchRecentProviderSessions(options) {
+        const resolvedRequestId = this.createRequestId(options?.requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "fetch_recent_provider_sessions_request",
+            requestId: resolvedRequestId,
+            ...(options?.cwd ? { cwd: options.cwd } : {}),
+            ...(options?.providers ? { providers: options.providers } : {}),
+            ...(options?.since ? { since: options.since } : {}),
+            ...(options?.limit ? { limit: options.limit } : {}),
+            ...(options?.query !== undefined ? { query: options.query } : {}),
+        });
+        return this.sendRequest({
+            requestId: resolvedRequestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "fetch_recent_provider_sessions_response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== resolvedRequestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+    }
+    async fetchWorkspaces(options) {
+        const resolvedRequestId = this.createRequestId(options?.requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "fetch_workspaces_request",
+            requestId: resolvedRequestId,
+            ...(options?.filter ? { filter: options.filter } : {}),
+            ...(options?.sort ? { sort: options.sort } : {}),
+            ...(options?.page ? { page: options.page } : {}),
+            ...(options?.subscribe ? { subscribe: options.subscribe } : {}),
+            ...(options?.sync ? { sync: options.sync } : {}),
+        });
+        return this.sendRequest({
+            requestId: resolvedRequestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "fetch_workspaces_response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== resolvedRequestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+    }
+    listWorkspaceLabels(options) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            requestId: options.requestId,
+            message: {
+                type: "workspace.label.list.request",
+                subscribe: { subscriptionId: options.subscriptionId },
+                ...(options.sync ? { sync: options.sync } : {}),
+            },
+        });
+    }
+    setWorkspaceLabel(options) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            requestId: options.requestId,
+            message: {
+                type: "workspace.label.assignment.set.request",
+                workspaceId: options.workspaceId,
+                label: options.label,
+                assigned: options.assigned,
+            },
+        });
+    }
+    updateWorkspaceLabel(options) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            requestId: options.requestId,
+            message: {
+                type: "workspace.label.update.request",
+                name: options.name,
+                ...(options.newName === undefined ? {} : { newName: options.newName }),
+                ...(options.color === undefined ? {} : { color: options.color }),
+            },
+        });
+    }
+    deleteWorkspaceLabel(options) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            requestId: options.requestId,
+            message: { type: "workspace.label.delete.request", name: options.name },
+        });
+    }
+    inspectWorkspaceLabelDelete(options) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            requestId: options.requestId,
+            message: {
+                type: "workspace.label.delete.inspect.request",
+                name: options.name,
+            },
+        });
+    }
+    async listProjects(options) {
+        const requestId = typeof options === "string" ? options : options?.requestId;
+        const resolvedRequestId = this.createRequestId(requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "project.list.request",
+            requestId: resolvedRequestId,
+            ...(typeof options === "object" && options.sync ? { sync: options.sync } : {}),
+        });
+        return this.sendRequest({
+            requestId: resolvedRequestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "project.list.response")
+                    return null;
+                if (msg.payload.requestId !== resolvedRequestId)
+                    return null;
+                return msg.payload;
+            },
+        });
+    }
+    async openProject(cwd, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "open_project_request",
+                cwd,
+            },
+            responseType: "open_project_response",
+        });
+    }
+    async addProject(cwd, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "project.add.request",
+                cwd,
+            },
+            responseType: "project.add.response",
+        });
+    }
+    async createProjectDirectory(input, requestId) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "project.create_directory.request",
+                parentPath: input.parentPath,
+                name: input.name,
+            },
+        });
+    }
+    async searchGithubRepositories(input, requestId) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "workspace.github.search_repositories.request",
+                query: input.query,
+                limit: input.limit,
+            },
+        });
+    }
+    async cloneGithubProject(input, requestId) {
+        const message = {
+            type: "project.github.clone.request",
+            repo: input.repo,
+            targetDirectory: input.targetDirectory,
+            ...(input.cloneProtocol ? { cloneProtocol: input.cloneProtocol } : {}),
+        };
+        return this.sendNamespacedCorrelatedSessionRequest({
+            requestId,
+            message,
+            timeout: PROJECT_GITHUB_CLONE_TIMEOUT_MS,
+        });
+    }
+    async startWorkspaceScript(workspaceId, scriptName, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "start_workspace_script_request",
+                workspaceId,
+                scriptName,
+            },
+            responseType: "start_workspace_script_response",
+        });
+    }
+    async listWorkspaceScripts(workspaceId, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "workspace.script.list.request", workspaceId },
+            responseType: "workspace.script.list.response",
+        });
+    }
+    async startWorkspaceScriptWithStatus(workspaceId, scriptName, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "workspace.script.start.request", workspaceId, scriptName },
+            responseType: "workspace.script.start.response",
+        });
+    }
+    async stopWorkspaceScript(workspaceId, scriptName, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "workspace.script.stop.request", workspaceId, scriptName },
+            responseType: "workspace.script.stop.response",
+        });
+    }
+    async archiveWorkspace(workspaceId, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "archive_workspace_request",
+                workspaceId,
+            },
+            responseType: "archive_workspace_response",
+        });
+    }
+    async fetchWorkspaceSetupStatus(workspaceId, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "workspace_setup_status_request",
+                workspaceId,
+            },
+            responseType: "workspace_setup_status_response",
+        });
+    }
+    async runWorkspaceSetup(workspaceId, requestId) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            requestId,
+            message: { type: "workspace.setup.run.request", workspaceId },
+        });
+    }
+    async fetchAgent(input, legacyOptions) {
+        const options = normalizeFetchAgentOptions(input, legacyOptions);
+        const resolvedRequestId = this.createRequestId(options.requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "fetch_agent_request",
+            requestId: resolvedRequestId,
+            agentId: options.agentId,
+        });
+        const payload = await this.sendRequest({
+            requestId: resolvedRequestId,
+            message,
+            timeout: options.timeout,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "fetch_agent_response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== resolvedRequestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+        if (payload.error) {
+            throw new Error(payload.error);
+        }
+        if (!payload.agent) {
+            return null;
+        }
+        return { agent: payload.agent, project: payload.project ?? null };
+    }
+    resubscribeCheckoutDiffSubscriptions() {
+        if (this.checkoutDiffSubscriptions.size === 0) {
+            return;
+        }
+        for (const [subscriptionId, subscription] of this.checkoutDiffSubscriptions) {
+            const message = SessionInboundMessageSchema.parse({
+                type: "subscribe_checkout_diff_request",
+                subscriptionId,
+                cwd: subscription.cwd,
+                compare: subscription.compare,
+                requestId: this.createRequestId(),
+            });
+            this.sendSessionMessage(message);
+        }
+    }
+    resubscribeTerminalDirectorySubscriptions() {
+        if (this.terminalDirectorySubscriptions.size === 0) {
+            return;
+        }
+        for (const subscription of this.terminalDirectorySubscriptions.values()) {
+            this.sendSessionMessage({
+                type: "subscribe_terminals_request",
+                cwd: subscription.cwd,
+                ...(subscription.workspaceId !== undefined
+                    ? { workspaceId: subscription.workspaceId }
+                    : {}),
+            });
+        }
+    }
+    resubscribeFileSubscriptions() {
+        for (const [subscriptionId, subscription] of this.fileSubscriptions) {
+            void this.sendCorrelatedSessionRequest({
+                message: {
+                    type: "fs.file.subscribe.request",
+                    cwd: subscription.cwd,
+                    path: subscription.path,
+                    subscriptionId,
+                },
+                responseType: "fs.file.subscribe.response",
+            })
+                .then((payload) => subscription.onUpdate(payload.initial))
+                .catch(() => undefined);
+        }
+    }
+    async createAgent(options) {
+        const result = await this.creations.createAgent({
+            ...options,
+            config: resolveAgentConfig(options),
+        });
+        if (result.error || !result.agent)
+            throw new Error(result.error ?? "Agent creation failed");
+        return result.agent;
+    }
+    async createLegacyAgent(options) {
+        if (options.idempotencyKey !== undefined)
+            this.requireAgentRequestReceipts();
+        const requestId = this.createRequestId(options.requestId);
+        const config = resolveAgentConfig(options);
+        const message = SessionInboundMessageSchema.parse({
+            type: "create_agent_request",
+            requestId,
+            config,
+            ...(options.env ? { env: options.env } : {}),
+            ...(options.workspaceId !== undefined ? { workspaceId: options.workspaceId } : {}),
+            ...(options.callerAgentId !== undefined ? { callerAgentId: options.callerAgentId } : {}),
+            ...(options.initialPrompt ? { initialPrompt: options.initialPrompt } : {}),
+            idempotencyKey: options.idempotencyKey,
+            ...(options.clientMessageId ? { clientMessageId: options.clientMessageId } : {}),
+            ...(options.outputSchema ? { outputSchema: options.outputSchema } : {}),
+            ...(options.images && options.images.length > 0 ? { images: options.images } : {}),
+            ...(options.attachments && options.attachments.length > 0
+                ? { attachments: options.attachments }
+                : {}),
+            ...(options.git ? { git: options.git } : {}),
+            ...(options.worktree ? { worktree: options.worktree } : {}),
+            ...(options.autoArchive !== undefined ? { autoArchive: options.autoArchive } : {}),
+            ...(options.worktreeName ? { worktreeName: options.worktreeName } : {}),
+            ...(options.labels && Object.keys(options.labels).length > 0
+                ? { labels: options.labels }
+                : {}),
+        });
+        const status = await this.sendRequest({
+            requestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "status") {
+                    return null;
+                }
+                const created = AgentCreatedStatusPayloadSchema.safeParse(msg.payload);
+                if (created.success && created.data.requestId === requestId) {
+                    return created.data;
+                }
+                const failed = AgentCreateFailedStatusPayloadSchema.safeParse(msg.payload);
+                if (failed.success && failed.data.requestId === requestId) {
+                    return failed.data;
+                }
+                return null;
+            },
+        });
+        if (status.status === "agent_create_failed") {
+            throw new Error(status.error);
+        }
+        return status.agent;
+    }
+    requireAgentRequestReceipts() {
+        // COMPAT(agentRequestReceipts): added in v0.7.3; remove gate after 2027-03-05.
+        if (this.lastServerInfoMessage?.features?.agentRequestReceipts !== true) {
+            throw new Error("Update the host to use retry-safe agent creation.");
+        }
+    }
+    async deleteAgent(agentId) {
+        const requestId = this.createRequestId();
+        const message = SessionInboundMessageSchema.parse({
+            type: "delete_agent_request",
+            agentId,
+            requestId,
+        });
+        await this.sendRequest({
+            requestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "agent_deleted") {
+                    return null;
+                }
+                if (msg.payload.requestId !== requestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+    }
+    async archiveAgent(agentId) {
+        const requestId = this.createRequestId();
+        const message = SessionInboundMessageSchema.parse({
+            type: "archive_agent_request",
+            agentId,
+            requestId,
+        });
+        const result = await this.sendRequest({
+            requestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "agent_archived") {
+                    return null;
+                }
+                if (msg.payload.requestId !== requestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+        return { archivedAt: result.archivedAt };
+    }
+    async detachAgent(agentId) {
+        const payload = await this.sendNamespacedCorrelatedSessionRequest({
+            message: {
+                type: "agent.detach.request",
+                agentId,
+            },
+        });
+        if (!payload.accepted) {
+            throw new Error(payload.error ?? "detachAgent rejected");
+        }
+    }
+    async updateAgent(agentId, updates) {
+        const requestId = this.createRequestId();
+        const message = SessionInboundMessageSchema.parse({
+            type: "update_agent_request",
+            agentId,
+            ...(updates.name !== undefined ? { name: updates.name } : {}),
+            ...(updates.labels && Object.keys(updates.labels).length > 0
+                ? { labels: updates.labels }
+                : {}),
+            requestId,
+        });
+        const payload = await this.sendRequest({
+            requestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "update_agent_response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== requestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+        if (!payload.accepted) {
+            throw new Error(payload.error ?? "updateAgent rejected");
+        }
+    }
+    async renameProject(projectId, customName, requestId) {
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "project.rename.request",
+                projectId,
+                customName,
+            },
+            responseType: "project.rename.response",
+        });
+        if (!payload.accepted) {
+            throw new Error(payload.error ?? "renameProject rejected");
+        }
+        return { customName: payload.customName };
+    }
+    async setProjectIcon(projectId, source, requestId) {
+        const payload = await this.sendNamespacedCorrelatedSessionRequest({
+            requestId,
+            message: { type: "project.icon.set.request", projectId, source },
+        });
+        if (!payload.accepted)
+            throw new Error(payload.error ?? "setProjectIcon rejected");
+    }
+    async removeProject(projectId, requestId) {
+        const payload = await this.sendNamespacedCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "project.remove.request",
+                projectId,
+            },
+        });
+        if (!payload.accepted) {
+            throw new Error(payload.error ?? "removeProject rejected");
+        }
+        return { removedWorkspaceIds: payload.removedWorkspaceIds };
+    }
+    async setWorkspaceTitle(workspaceId, title, requestId) {
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "workspace.title.set.request",
+                workspaceId,
+                title,
+            },
+            responseType: "workspace.title.set.response",
+        });
+        if (!payload.accepted) {
+            throw new Error(payload.error ?? "setWorkspaceTitle rejected");
+        }
+        return { title: payload.title };
+    }
+    async setWorkspacePinned(workspaceId, pinned, requestId) {
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "workspace.pin.set.request",
+                workspaceId,
+                pinned,
+            },
+            responseType: "workspace.pin.set.response",
+        });
+        if (!payload.accepted) {
+            throw new Error(payload.error ?? "setWorkspacePinned rejected");
+        }
+        return { pinnedAt: payload.pinnedAt };
+    }
+    async inspectWorkspaceRecovery(workspaceId, requestId) {
+        const payload = await this.sendNamespacedCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "workspace.recovery.inspect.request",
+                workspaceId,
+            },
+        });
+        return payload.state;
+    }
+    async restoreWorkspace(workspaceId, requestId) {
+        const payload = await this.sendNamespacedCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "workspace.recovery.restore.request",
+                workspaceId,
+            },
+            timeout: 150000,
+        });
+        if (!payload.accepted) {
+            throw new Error(payload.error ?? "Workspace recovery was rejected by the host");
+        }
+    }
+    async resumeAgent(handle, overrides) {
+        const requestId = this.createRequestId();
+        const message = SessionInboundMessageSchema.parse({
+            type: "resume_agent_request",
+            requestId,
+            handle,
+            ...(overrides ? { overrides } : {}),
+        });
+        const status = await this.sendRequest({
+            requestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "status") {
+                    return null;
+                }
+                const resumed = AgentResumedStatusPayloadSchema.safeParse(msg.payload);
+                if (resumed.success && resumed.data.requestId === requestId) {
+                    return resumed.data;
+                }
+                return null;
+            },
+        });
+        return status.agent;
+    }
+    async importAgent(input) {
+        const requestId = this.createRequestId();
+        const message = SessionInboundMessageSchema.parse({
+            type: "import_agent_request",
+            requestId,
+            ...("providerId" in input
+                ? { providerId: input.providerId, providerHandleId: input.providerHandleId }
+                : { provider: input.provider, sessionId: input.sessionId }),
+            ...(input.cwd ? { cwd: input.cwd } : {}),
+            ...(input.workspaceId ? { workspaceId: input.workspaceId } : {}),
+            ...(input.labels && Object.keys(input.labels).length > 0 ? { labels: input.labels } : {}),
+        });
+        const status = await this.sendRequest({
+            requestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "status") {
+                    return null;
+                }
+                const resumed = AgentResumedStatusPayloadSchema.safeParse(msg.payload);
+                if (resumed.success && resumed.data.requestId === requestId) {
+                    return resumed.data;
+                }
+                const failed = AgentCreateFailedStatusPayloadSchema.safeParse(msg.payload);
+                if (failed.success && failed.data.requestId === requestId) {
+                    return failed.data;
+                }
+                return null;
+            },
+        });
+        if (status.status === "agent_create_failed") {
+            throw new Error(status.error);
+        }
+        return status.agent;
+    }
+    async refreshAgent(agentId, requestId) {
+        const resolvedRequestId = this.createRequestId(requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "refresh_agent_request",
+            agentId,
+            requestId: resolvedRequestId,
+        });
+        return this.sendRequest({
+            requestId: resolvedRequestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "status") {
+                    return null;
+                }
+                const refreshed = AgentRefreshedStatusPayloadSchema.safeParse(msg.payload);
+                if (refreshed.success && refreshed.data.requestId === resolvedRequestId) {
+                    return refreshed.data;
+                }
+                return null;
+            },
+        });
+    }
+    async fetchAgentTimeline(agentId, options = {}) {
+        const resolvedRequestId = this.createRequestId(options.requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "fetch_agent_timeline_request",
+            agentId,
+            requestId: resolvedRequestId,
+            ...(options.direction ? { direction: options.direction } : {}),
+            ...(options.cursor ? { cursor: options.cursor } : {}),
+            ...(typeof options.limit === "number" ? { limit: options.limit } : {}),
+            ...(options.projection ? { projection: options.projection } : {}),
+            ...(options.mergeWindow === true ? { mergeWindow: true } : {}),
+        });
+        const payload = await this.sendRequest({
+            requestId: resolvedRequestId,
+            message,
+            timeout: options.timeout,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "fetch_agent_timeline_response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== resolvedRequestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+        if (payload.error) {
+            throw new Error(payload.error);
+        }
+        return payload;
+    }
+    async appendAgentTimelineItem(agentId, item) {
+        const requestId = this.createRequestId();
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "agent.timeline.append.request", requestId, agentId, item },
+            responseType: "agent.timeline.append.response",
+        });
+        return { seq: payload.seq, epoch: payload.epoch };
+    }
+    async listAgentTimelinePrompts(agentId, options = {}) {
+        const requestId = this.createRequestId(options.requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "agent.timeline.list_prompts.request",
+            agentId,
+            requestId,
+        });
+        const payload = await this.sendRequest({
+            requestId,
+            message,
+            timeout: options.timeout,
+            options: { skipQueue: true },
+            select: (response) => response.type === "agent.timeline.list_prompts.response" &&
+                response.payload.requestId === requestId
+                ? response.payload
+                : null,
+        });
+        if (payload.error) {
+            throw new Error(payload.error);
+        }
+        return payload;
+    }
+    async listProviderSubagents(parentAgentId, options = {}) {
+        const requestId = this.createRequestId(options.requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "agent.provider_subagents.list.request",
+            parentAgentId,
+            requestId,
+        });
+        const payload = await this.sendRequest({
+            requestId,
+            message,
+            timeout: options.timeout,
+            options: { skipQueue: true },
+            select: (response) => response.type === "agent.provider_subagents.list.response" &&
+                response.payload.requestId === requestId
+                ? response.payload
+                : null,
+        });
+        if (payload.error) {
+            throw new Error(payload.error);
+        }
+        return payload;
+    }
+    async fetchProviderSubagentTimeline(parentAgentId, subagentId, options = {}) {
+        const requestId = this.createRequestId(options.requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "agent.provider_subagents.timeline.get.request",
+            parentAgentId,
+            subagentId,
+            requestId,
+            ...(options.direction ? { direction: options.direction } : {}),
+            ...(options.cursor ? { cursor: options.cursor } : {}),
+            ...(typeof options.limit === "number" ? { limit: options.limit } : {}),
+        });
+        const payload = await this.sendRequest({
+            requestId,
+            message,
+            timeout: options.timeout,
+            options: { skipQueue: true },
+            select: (response) => response.type === "agent.provider_subagents.timeline.get.response" &&
+                response.payload.requestId === requestId
+                ? response.payload
+                : null,
+        });
+        if (payload.error) {
+            throw new Error(payload.error);
+        }
+        return payload;
+    }
+    async askSideConversation(parentAgentId, threadId, question, options = {}) {
+        this.requireSideConversationSupport();
+        const requestId = this.createRequestId(options.requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "agent.side_conversation.ask.request",
+            parentAgentId,
+            threadId,
+            question,
+            requestId,
+        });
+        const payload = await this.sendRequest({
+            requestId,
+            message,
+            timeout: options.timeout,
+            options: { skipQueue: true },
+            select: (response) => response.type === "agent.side_conversation.ask.response" &&
+                response.payload.requestId === requestId
+                ? response.payload
+                : null,
+        });
+        if (payload.error)
+            throw new Error(payload.error);
+        return payload;
+    }
+    async fetchSideConversationTimeline(parentAgentId, threadId, options = {}) {
+        this.requireSideConversationSupport();
+        const requestId = this.createRequestId(options.requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "agent.side_conversation.timeline.get.request",
+            parentAgentId,
+            threadId,
+            requestId,
+        });
+        const payload = await this.sendRequest({
+            requestId,
+            message,
+            timeout: options.timeout,
+            options: { skipQueue: true },
+            select: (response) => response.type === "agent.side_conversation.timeline.get.response" &&
+                response.payload.requestId === requestId
+                ? response.payload
+                : null,
+        });
+        if (payload.error)
+            throw new Error(payload.error);
+        return payload;
+    }
+    async listSideConversations(parentAgentId, options = {}) {
+        this.requireSideConversationSupport();
+        const requestId = this.createRequestId(options.requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "agent.side_conversation.list.request",
+            parentAgentId,
+            requestId,
+        });
+        const payload = await this.sendRequest({
+            requestId,
+            message,
+            timeout: options.timeout,
+            options: { skipQueue: true },
+            select: (response) => response.type === "agent.side_conversation.list.response" &&
+                response.payload.requestId === requestId
+                ? response.payload
+                : null,
+        });
+        if (payload.error)
+            throw new Error(payload.error);
+        return payload;
+    }
+    setAgentTimelineSubscription(agentIds) {
+        return this.subscriptions.setViewed(agentIds);
+    }
+    subscribeAgentTimeline(agentId, handler) {
+        const stream = this.on("agent_stream", (message) => {
+            if (message.payload.agentId === agentId)
+                handler(message);
+        });
+        const replacement = this.on("agent.timeline.replacement", (message) => {
+            if (message.payload.agentId === agentId)
+                handler(message);
+        });
+        const release = this.subscriptions.observeTimeline(agentId);
+        return Object.assign(() => {
+            stream();
+            replacement();
+            release();
+        }, { ready: release.ready });
+    }
+    updateEventSubscriptions() {
+        const events = [
+            "project.update",
+            "providers_snapshot_update",
+            "agent_attention_required",
+            "agent_permission_request",
+            "agent_permission_resolved",
+        ];
+        if (this.eventListeners.size === 0 && !this.messageHandlers.has("providers_snapshot_update")) {
+            this.providerSnapshotUpdates.clear();
+        }
+        this.subscriptions.setEvents(events.filter((type) => this.eventListeners.size > 0 || (this.messageHandlers.get(type)?.size ?? 0) > 0));
+    }
+    async sendEventSubscription(events) {
+        if (this.connectionState.status !== "connected")
+            return;
+        // COMPAT(explicitEventSubscriptions): added in v0.8.0, remove legacy broadcast handling after 2027-03-08.
+        if (!this.lastServerInfoMessage?.features?.explicitEventSubscriptions ||
+            this.config.capabilities?.[CLIENT_CAPS.explicitEventSubscriptions] === false)
+            return;
+        await this.sendCorrelatedSessionRequest({
+            message: { type: "session.events.set_subscription.request", events },
+            responseType: "session.events.set_subscription.response",
+        });
+    }
+    async sendTimelineSubscription(agentIds) {
+        if (this.connectionState.status !== "connected")
+            return;
+        // COMPAT(selectiveAgentTimeline): added in v0.1.106. Old daemons keep their
+        // legacy global stream and do not understand this RPC. Remove after
+        // 2027-01-12 once the supported daemon floor is >= v0.1.106.
+        if (!this.lastServerInfoMessage?.features?.selectiveAgentTimeline) {
+            return;
+        }
+        const requestId = this.createRequestId();
+        const normalizedAgentIds = [...new Set(agentIds)].sort();
+        const message = SessionInboundMessageSchema.parse({
+            type: "agent.timeline.set_subscription.request",
+            agentIds: normalizedAgentIds,
+            requestId,
+        });
+        await this.sendRequest({
+            requestId,
+            message,
+            options: { skipQueue: true },
+            select: (response) => {
+                if (response.type !== "agent.timeline.set_subscription.response") {
+                    return null;
+                }
+                return response.payload.requestId === requestId ? response.payload : null;
+            },
+        });
+    }
+    async buildAgentForkContext(agentId, options = {}) {
+        const resolvedRequestId = this.createRequestId(options.requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "agent.fork_context.request",
+            agentId,
+            requestId: resolvedRequestId,
+            ...(options.boundaryCursor ? { boundaryCursor: options.boundaryCursor } : {}),
+            ...(options.boundaryMessageId ? { boundaryMessageId: options.boundaryMessageId } : {}),
+        });
+        const payload = await this.sendRequest({
+            requestId: resolvedRequestId,
+            message,
+            timeout: 15000,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "agent.fork_context.response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== resolvedRequestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+        if (payload.error) {
+            throw new Error(payload.error);
+        }
+        return payload;
+    }
+    // ============================================================================
+    // Agent Interaction
+    // ============================================================================
+    async sendAgentMessage(agentId, text, options) {
+        const requestId = this.createRequestId();
+        const messageId = options?.messageId ?? crypto.randomUUID();
+        const message = SessionInboundMessageSchema.parse({
+            type: "send_agent_message_request",
+            requestId,
+            agentId,
+            text,
+            ...(messageId ? { messageId } : {}),
+            ...(options?.activeTurnBehavior ? { activeTurnBehavior: options.activeTurnBehavior } : {}),
+            ...(options?.images ? { images: options.images } : {}),
+            ...(options?.attachments ? { attachments: options.attachments } : {}),
+        });
+        const payload = await this.sendRequest({
+            requestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "send_agent_message_response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== requestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+        if (!payload.accepted) {
+            throw new Error(payload.error ?? "sendAgentMessage rejected");
+        }
+    }
+    async sendMessage(agentId, text, options) {
+        await this.sendAgentMessage(agentId, text, options);
+    }
+    async rewindAgent(agentId, messageId, mode) {
+        const requestId = this.createRequestId();
+        const message = SessionInboundMessageSchema.parse({
+            type: "agent.rewind.request",
+            requestId,
+            agentId,
+            messageId,
+            mode,
+        });
+        const payload = await this.sendRequest({
+            requestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "agent.rewind.response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== requestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+        if (!payload.ok) {
+            throw new Error(payload.error ?? "Agent rewind failed");
+        }
+        return payload;
+    }
+    async cancelAgent(agentId) {
+        const requestId = this.createRequestId();
+        const message = SessionInboundMessageSchema.parse({
+            type: "cancel_agent_request",
+            agentId,
+            requestId,
+        });
+        const payload = await this.sendRequest({
+            requestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "cancel_agent_response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== requestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+        if (payload.error) {
+            throw new Error(payload.error);
+        }
+    }
+    async setAgentMode(agentId, modeId) {
+        const requestId = this.createRequestId();
+        const message = SessionInboundMessageSchema.parse({
+            type: "set_agent_mode_request",
+            agentId,
+            modeId,
+            requestId,
+        });
+        const payload = await this.sendRequest({
+            requestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "set_agent_mode_response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== requestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+        if (!payload.accepted) {
+            throw new Error(payload.error ?? "setAgentMode rejected");
+        }
+        return payload.notice ?? null;
+    }
+    async setAgentModel(agentId, modelId) {
+        const requestId = this.createRequestId();
+        const message = SessionInboundMessageSchema.parse({
+            type: "set_agent_model_request",
+            agentId,
+            modelId,
+            requestId,
+        });
+        const payload = await this.sendRequest({
+            requestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "set_agent_model_response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== requestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+        if (!payload.accepted) {
+            throw new Error(payload.error ?? "setAgentModel rejected");
+        }
+    }
+    async setAgentFeature(agentId, featureId, value) {
+        const requestId = this.createRequestId();
+        const message = SessionInboundMessageSchema.parse({
+            type: "set_agent_feature_request",
+            agentId,
+            featureId,
+            value,
+            requestId,
+        });
+        const payload = await this.sendRequest({
+            requestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "set_agent_feature_response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== requestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+        if (!payload.accepted) {
+            throw new Error(payload.error ?? "setAgentFeature rejected");
+        }
+    }
+    async setAgentThinkingOption(agentId, thinkingOptionId) {
+        const requestId = this.createRequestId();
+        const message = SessionInboundMessageSchema.parse({
+            type: "set_agent_thinking_request",
+            agentId,
+            thinkingOptionId,
+            requestId,
+        });
+        const payload = await this.sendRequest({
+            requestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "set_agent_thinking_response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== requestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+        if (!payload.accepted) {
+            throw new Error(payload.error ?? "setAgentThinkingOption rejected");
+        }
+        return payload.notice ?? null;
+    }
+    /**
+     * Applies a whole agent-config bundle in one request. Use this instead of
+     * chaining the single-field setters when the values belong together so client
+     * interruption and other mutations cannot interleave between steps. A
+     * provider rejection can still leave earlier steps applied.
+     * Gated on `server_info.features.agentConfigApply`.
+     */
+    async applyAgentConfig(agentId, config) {
+        const requestId = this.createRequestId();
+        const message = SessionInboundMessageSchema.parse({
+            type: "agent.config.apply.request",
+            agentId,
+            config,
+            requestId,
+        });
+        const payload = await this.sendRequest({
+            requestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "agent.config.apply.response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== requestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+        if (!payload.accepted) {
+            throw new Error(payload.error ?? "applyAgentConfig rejected");
+        }
+        return payload.notice ?? null;
+    }
+    async restartServer(reason, requestId) {
+        const resolvedRequestId = this.createRequestId(requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "restart_server_request",
+            ...(reason && reason.trim().length > 0 ? { reason } : {}),
+            requestId: resolvedRequestId,
+        });
+        return this.sendRequest({
+            requestId: resolvedRequestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "status") {
+                    return null;
+                }
+                const restarted = RestartRequestedStatusPayloadSchema.safeParse(msg.payload);
+                if (!restarted.success) {
+                    return null;
+                }
+                if (restarted.data.requestId !== resolvedRequestId) {
+                    return null;
+                }
+                return restarted.data;
+            },
+        });
+    }
+    async shutdownServer(options) {
+        const resolvedRequestId = this.createRequestId(options?.requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "shutdown_server_request",
+            requestId: resolvedRequestId,
+        });
+        return this.sendRequest({
+            requestId: resolvedRequestId,
+            message,
+            timeout: options?.timeout,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "status") {
+                    return null;
+                }
+                const shutdown = ShutdownRequestedStatusPayloadSchema.safeParse(msg.payload);
+                if (!shutdown.success) {
+                    return null;
+                }
+                if (shutdown.data.requestId !== resolvedRequestId) {
+                    return null;
+                }
+                return shutdown.data;
+            },
+        });
+    }
+    async updateDaemon(requestId) {
+        const resolvedRequestId = this.createRequestId(requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "daemon.update.request",
+            requestId: resolvedRequestId,
+        });
+        return this.sendRequest({
+            requestId: resolvedRequestId,
+            message,
+            timeout: 300000, // 5 minutes — npm update can be slow on remote machines
+            options: { skipQueue: true },
+            select: (msg) => {
+                const parsed = DaemonUpdateResponseSchema.safeParse(msg);
+                if (!parsed.success) {
+                    return null;
+                }
+                if (parsed.data.payload.requestId !== resolvedRequestId) {
+                    return null;
+                }
+                return parsed.data.payload;
+            },
+        });
+    }
+    // ============================================================================
+    // Audio / Voice
+    // ============================================================================
+    async setVoiceMode(enabled, agentId) {
+        const requestId = this.createRequestId();
+        const message = SessionInboundMessageSchema.parse({
+            type: "set_voice_mode",
+            enabled,
+            ...(agentId ? { agentId } : {}),
+            requestId,
+        });
+        const response = await this.sendRequest({
+            requestId,
+            message,
+            select: (msg) => {
+                if (msg.type !== "set_voice_mode_response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== requestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+        if (!response.accepted) {
+            const codeSuffix = typeof response.reasonCode === "string" && response.reasonCode.trim().length > 0
+                ? ` (${response.reasonCode})`
+                : "";
+            throw new Error((response.error ?? "Failed to set voice mode") + codeSuffix);
+        }
+        return response;
+    }
+    async sendVoiceAudioChunk(audio, format, isLast = false) {
+        this.sendSessionMessage({ type: "voice_audio_chunk", audio, format, isLast });
+    }
+    async startDictationStream(dictationId, format) {
+        const ack = this.waitForWithCancel((msg) => {
+            if (msg.type !== "dictation_stream_ack") {
+                return null;
+            }
+            if (msg.payload.dictationId !== dictationId) {
+                return null;
+            }
+            if (msg.payload.ackSeq !== -1) {
+                return null;
+            }
+            return msg.payload;
+        }, 30000, { skipQueue: true });
+        const ackPromise = ack.promise.then(() => undefined);
+        const streamError = this.waitForWithCancel((msg) => {
+            if (msg.type !== "dictation_stream_error") {
+                return null;
+            }
+            if (msg.payload.dictationId !== dictationId) {
+                return null;
+            }
+            return msg.payload;
+        }, 30000, { skipQueue: true });
+        const errorPromise = streamError.promise.then((payload) => {
+            throw new Error(payload.error);
+        });
+        const cleanupError = new Error("Cancelled dictation start waiter");
+        try {
+            this.sendSessionMessageStrict({ type: "dictation_stream_start", dictationId, format });
+            await Promise.race([ackPromise, errorPromise]);
+        }
+        finally {
+            ack.cancel(cleanupError);
+            streamError.cancel(cleanupError);
+            void ackPromise.catch(() => undefined);
+            void errorPromise.catch(() => undefined);
+        }
+    }
+    sendDictationStreamChunk(dictationId, seq, audio, format) {
+        this.sendSessionMessageStrict({
+            type: "dictation_stream_chunk",
+            dictationId,
+            seq,
+            audio,
+            format,
+        });
+    }
+    async finishDictationStream(dictationId, finalSeq) {
+        const final = this.waitForWithCancel((msg) => {
+            if (msg.type !== "dictation_stream_final") {
+                return null;
+            }
+            if (msg.payload.dictationId !== dictationId) {
+                return null;
+            }
+            return msg.payload;
+        }, 0, { skipQueue: true });
+        const streamError = this.waitForWithCancel((msg) => {
+            if (msg.type !== "dictation_stream_error") {
+                return null;
+            }
+            if (msg.payload.dictationId !== dictationId) {
+                return null;
+            }
+            return msg.payload;
+        }, 0, { skipQueue: true });
+        const finishAccepted = this.waitForWithCancel((msg) => {
+            if (msg.type !== "dictation_stream_finish_accepted") {
+                return null;
+            }
+            if (msg.payload.dictationId !== dictationId) {
+                return null;
+            }
+            return msg.payload;
+        }, DEFAULT_DICTATION_FINISH_ACCEPT_TIMEOUT_MS, { skipQueue: true });
+        const finalPromise = final.promise;
+        const errorPromise = streamError.promise.then((payload) => {
+            throw new Error(payload.error);
+        });
+        const finishAcceptedPromise = finishAccepted.promise;
+        const finalOutcomePromise = finalPromise.then((payload) => ({
+            kind: "final",
+            payload,
+        }));
+        const errorOutcomePromise = errorPromise.then(() => ({
+            kind: "error",
+            error: new Error("Unexpected dictation stream error state"),
+        }), (error) => ({
+            kind: "error",
+            error: error instanceof Error ? error : new Error(String(error)),
+        }));
+        const finishAcceptedOutcomePromise = finishAcceptedPromise.then((payload) => ({ kind: "accepted", payload }), (error) => {
+            if (isWaiterTimeoutError(error)) {
+                return { kind: "accepted_timeout" };
+            }
+            return {
+                kind: "accepted_error",
+                error: error instanceof Error ? error : new Error(String(error)),
+            };
+        });
+        const waitForFinalResult = async (timeoutMs) => {
+            if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+                const outcome = await Promise.race([finalOutcomePromise, errorOutcomePromise]);
+                if (outcome.kind === "error") {
+                    throw outcome.error;
+                }
+                return outcome.payload;
+            }
+            let timeoutHandle = null;
+            const timeoutPromise = new Promise((resolve) => {
+                timeoutHandle = setTimeout(() => resolve({ kind: "timeout" }), timeoutMs);
+            });
+            const outcome = await Promise.race([
+                finalOutcomePromise,
+                errorOutcomePromise,
+                timeoutPromise,
+            ]);
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+            }
+            if (outcome.kind === "timeout") {
+                throw new Error(`Timeout waiting for dictation finalization (${timeoutMs}ms)`);
+            }
+            if (outcome.kind === "error") {
+                throw outcome.error;
+            }
+            return outcome.payload;
+        };
+        const cleanupError = new Error("Cancelled dictation finish waiter");
+        try {
+            this.sendSessionMessageStrict({ type: "dictation_stream_finish", dictationId, finalSeq });
+            const firstOutcome = await Promise.race([
+                finalOutcomePromise,
+                errorOutcomePromise,
+                finishAcceptedOutcomePromise,
+            ]);
+            if (firstOutcome.kind === "final") {
+                return firstOutcome.payload;
+            }
+            if (firstOutcome.kind === "error") {
+                throw firstOutcome.error;
+            }
+            if (firstOutcome.kind === "accepted") {
+                return await waitForFinalResult(firstOutcome.payload.timeoutMs + DEFAULT_DICTATION_FINISH_TIMEOUT_GRACE_MS);
+            }
+            return await waitForFinalResult(DEFAULT_DICTATION_FINISH_FALLBACK_TIMEOUT_MS);
+        }
+        finally {
+            final.cancel(cleanupError);
+            streamError.cancel(cleanupError);
+            finishAccepted.cancel(cleanupError);
+            void finalPromise.catch(() => undefined);
+            void errorPromise.catch(() => undefined);
+            void finishAcceptedPromise.catch(() => undefined);
+        }
+    }
+    cancelDictationStream(dictationId) {
+        this.sendSessionMessageStrict({ type: "dictation_stream_cancel", dictationId });
+    }
+    async abortRequest() {
+        this.sendSessionMessage({ type: "abort_request" });
+    }
+    async audioPlayed(id) {
+        this.sendSessionMessage({ type: "audio_played", id });
+    }
+    // ============================================================================
+    // Git Operations
+    // ============================================================================
+    async getCheckoutStatus(cwd, options) {
+        const requestId = options?.requestId;
+        if (!requestId) {
+            const existing = this.checkoutStatusInFlight.get(cwd);
+            if (existing) {
+                return existing;
+            }
+        }
+        const resolvedRequestId = this.createRequestId(requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "checkout_status_request",
+            cwd,
+            requestId: resolvedRequestId,
+        });
+        const responsePromise = this.sendRequest({
+            requestId: resolvedRequestId,
+            message,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "checkout_status_response") {
+                    return null;
+                }
+                if (msg.payload.requestId !== resolvedRequestId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+        if (!requestId) {
+            this.checkoutStatusInFlight.set(cwd, responsePromise);
+            void responsePromise
+                .finally(() => {
+                if (this.checkoutStatusInFlight.get(cwd) === responsePromise) {
+                    this.checkoutStatusInFlight.delete(cwd);
+                }
+            })
+                .catch(() => undefined);
+        }
+        return responsePromise;
+    }
+    normalizeCheckoutDiffCompare(compare) {
+        if (compare.mode === "uncommitted") {
+            return compare.ignoreWhitespace === true
+                ? { mode: "uncommitted", ignoreWhitespace: true }
+                : { mode: "uncommitted" };
+        }
+        const trimmedBaseRef = compare.baseRef?.trim();
+        if (!trimmedBaseRef) {
+            return compare.ignoreWhitespace === true
+                ? { mode: "base", ignoreWhitespace: true }
+                : { mode: "base" };
+        }
+        return compare.ignoreWhitespace === true
+            ? { mode: "base", baseRef: trimmedBaseRef, ignoreWhitespace: true }
+            : { mode: "base", baseRef: trimmedBaseRef };
+    }
+    async getCheckoutDiff(cwd, compare, requestId) {
+        const oneShotSubscriptionId = `oneshot-checkout-diff:${crypto.randomUUID()}`;
+        try {
+            const payload = await this.subscribeCheckoutDiff(cwd, compare, {
+                subscriptionId: oneShotSubscriptionId,
+                requestId,
+            });
+            return {
+                cwd: payload.cwd,
+                files: payload.files,
+                error: payload.error,
+                diffTooLarge: payload.diffTooLarge,
+                requestId: payload.requestId,
+            };
+        }
+        finally {
+            try {
+                this.unsubscribeCheckoutDiff(oneShotSubscriptionId);
+            }
+            catch {
+                // Ignore disconnect races during one-shot cleanup.
+            }
+        }
+    }
+    async subscribeCheckoutDiff(cwd, compare, options) {
+        const subscriptionId = options?.subscriptionId ?? crypto.randomUUID();
+        const normalizedCompare = this.normalizeCheckoutDiffCompare(compare);
+        const previousSubscription = this.checkoutDiffSubscriptions.get(subscriptionId) ?? null;
+        this.checkoutDiffSubscriptions.set(subscriptionId, {
+            cwd,
+            compare: normalizedCompare,
+        });
+        const resolvedRequestId = this.createRequestId(options?.requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "subscribe_checkout_diff_request",
+            subscriptionId,
+            cwd,
+            compare: normalizedCompare,
+            requestId: resolvedRequestId,
+        });
+        try {
+            return await this.sendCorrelatedRequest({
+                requestId: resolvedRequestId,
+                message,
+                responseType: "subscribe_checkout_diff_response",
+                options: { skipQueue: true },
+                selectPayload: (payload) => {
+                    if (payload.subscriptionId !== subscriptionId) {
+                        return null;
+                    }
+                    return payload;
+                },
+            });
+        }
+        catch (error) {
+            if (previousSubscription) {
+                this.checkoutDiffSubscriptions.set(subscriptionId, previousSubscription);
+            }
+            else {
+                this.checkoutDiffSubscriptions.delete(subscriptionId);
+            }
+            throw error;
+        }
+    }
+    unsubscribeCheckoutDiff(subscriptionId) {
+        this.checkoutDiffSubscriptions.delete(subscriptionId);
+        this.sendSessionMessage({
+            type: "unsubscribe_checkout_diff_request",
+            subscriptionId,
+        });
+    }
+    async checkoutCommit(cwd, input, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "checkout_commit_request",
+                cwd,
+                message: input.message,
+                addAll: input.addAll,
+            },
+            responseType: "checkout_commit_response",
+        });
+    }
+    async checkoutMerge(cwd, input, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "checkout_merge_request",
+                cwd,
+                baseRef: input.baseRef,
+                strategy: input.strategy,
+                requireCleanTarget: input.requireCleanTarget,
+            },
+            responseType: "checkout_merge_response",
+        });
+    }
+    async checkoutMergeFromBase(cwd, input, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "checkout_merge_from_base_request",
+                cwd,
+                baseRef: input.baseRef,
+                requireCleanTarget: input.requireCleanTarget,
+            },
+            responseType: "checkout_merge_from_base_response",
+        });
+    }
+    async checkoutPull(cwd, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "checkout_pull_request",
+                cwd,
+            },
+            responseType: "checkout_pull_response",
+        });
+    }
+    async checkoutPush(cwd, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "checkout_push_request",
+                cwd,
+            },
+            responseType: "checkout_push_response",
+        });
+    }
+    async checkoutRefresh(cwd, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "checkout.refresh.request",
+                cwd,
+            },
+            responseType: "checkout.refresh.response",
+        });
+    }
+    async listCheckoutCommits(cwd, requestId) {
+        const payload = await this.sendNamespacedCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "checkout.commits.list.request",
+                cwd,
+            },
+            timeout: 60000,
+        });
+        if (payload.error) {
+            throw new Error(payload.error.message);
+        }
+        return { baseRef: payload.baseRef, commits: payload.commits };
+    }
+    async getCommitFileDiff(cwd, sha, path, requestId) {
+        const payload = await this.sendNamespacedCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "checkout.commits.file_diff.request",
+                cwd,
+                sha,
+                path,
+            },
+            timeout: 60000,
+        });
+        if (payload.error) {
+            throw new Error(payload.error.message);
+        }
+        return { file: payload.file };
+    }
+    async checkoutPrCreate(cwd, input, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "checkout_pr_create_request",
+                cwd,
+                title: input.title,
+                body: input.body,
+                baseRef: input.baseRef,
+            },
+            responseType: "checkout_pr_create_response",
+        });
+    }
+    async checkoutPrMerge(cwd, input, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "checkout_pr_merge_request",
+                cwd,
+                mergeMethod: input.method,
+            },
+            responseType: "checkout_pr_merge_response",
+        });
+    }
+    async checkoutForgeSetAutoMerge(cwd, input, requestId) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "checkout.forge.set_auto_merge.request",
+                cwd,
+                enabled: input.enabled,
+                ...(input.enabled ? { mergeMethod: input.method } : {}),
+            },
+            timeout: 60000,
+        });
+    }
+    async checkoutGithubSetAutoMerge(cwd, input, requestId) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "checkout.github.set_auto_merge.request",
+                cwd,
+                enabled: input.enabled,
+                ...(input.enabled ? { mergeMethod: input.method } : {}),
+            },
+        });
+    }
+    async checkoutForgeGetCheckDetails(input, requestId) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "checkout.forge.get_check_details.request",
+                cwd: input.cwd,
+                repoOwner: input.repoOwner,
+                repoName: input.repoName,
+                checkRunId: input.checkRunId,
+                workflowRunId: input.workflowRunId,
+                changeRequestNumber: input.changeRequestNumber,
+            },
+            timeout: 60000,
+        });
+    }
+    async checkoutGithubGetCheckDetails(input, requestId) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "checkout.github.get_check_details.request",
+                cwd: input.cwd,
+                repoOwner: input.repoOwner,
+                repoName: input.repoName,
+                checkRunId: input.checkRunId,
+                workflowRunId: input.workflowRunId,
+            },
+        });
+    }
+    async checkoutPrStatus(cwd, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "checkout_pr_status_request",
+                cwd,
+            },
+            responseType: "checkout_pr_status_response",
+        });
+    }
+    async pullRequestTimeline(input, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "pull_request_timeline_request",
+                cwd: input.cwd,
+                prNumber: input.prNumber,
+                repoOwner: input.repoOwner,
+                repoName: input.repoName,
+            },
+            responseType: "pull_request_timeline_response",
+        });
+    }
+    async checkoutSwitchBranch(cwd, branch, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "checkout_switch_branch_request",
+                cwd,
+                branch,
+            },
+            responseType: "checkout_switch_branch_response",
+        });
+    }
+    async renameBranch(input) {
+        return this.sendCorrelatedSessionRequest({
+            requestId: input.requestId,
+            message: {
+                type: "checkout.rename_branch.request",
+                cwd: input.cwd,
+                branch: input.branch,
+            },
+            responseType: "checkout.rename_branch.response",
+        });
+    }
+    async stashSave(cwd, options, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "stash_save_request",
+                cwd,
+                branch: options?.branch,
+            },
+            responseType: "stash_save_response",
+        });
+    }
+    async stashPop(cwd, stashIndex, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "stash_pop_request",
+                cwd,
+                stashIndex,
+            },
+            responseType: "stash_pop_response",
+        });
+    }
+    async stashList(cwd, options, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "stash_list_request",
+                cwd,
+                paseoOnly: options?.paseoOnly,
+            },
+            responseType: "stash_list_response",
+        });
+    }
+    async getPaseoWorktreeList(input, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "paseo_worktree_list_request",
+                cwd: input.cwd,
+                repoRoot: input.repoRoot,
+            },
+            responseType: "paseo_worktree_list_response",
+        });
+    }
+    async archivePaseoWorktree(input, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "paseo_worktree_archive_request",
+                worktreePath: input.worktreePath,
+                repoRoot: input.repoRoot,
+                branchName: input.branchName,
+                ...(input.workspaceId !== undefined ? { workspaceId: input.workspaceId } : {}),
+                ...(input.scope !== undefined ? { scope: input.scope } : {}),
+            },
+            responseType: "paseo_worktree_archive_response",
+        });
+    }
+    async createPaseoWorktree(input, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "create_paseo_worktree_request",
+                cwd: input.cwd,
+                ...(input.projectId !== undefined ? { projectId: input.projectId } : {}),
+                worktreeSlug: input.worktreeSlug,
+                ...(input.firstAgentContext !== undefined
+                    ? { firstAgentContext: input.firstAgentContext }
+                    : {}),
+                ...(input.refName !== undefined ? { refName: input.refName } : {}),
+                ...(input.action !== undefined ? { action: input.action } : {}),
+                ...(input.checkoutSource !== undefined ? { checkoutSource: input.checkoutSource } : {}),
+                ...(input.githubPrNumber !== undefined ? { githubPrNumber: input.githubPrNumber } : {}),
+            },
+            responseType: "create_paseo_worktree_response",
+        });
+    }
+    async createWorkspace(input, requestId) {
+        const resolvedRequestId = this.createRequestId(requestId ?? input.requestId);
+        const result = await this.creations.createWorkspace({
+            ...input,
+            requestId: resolvedRequestId,
+            ...(input.agent
+                ? { agent: { ...input.agent, config: resolveAgentConfig(input.agent) } }
+                : {}),
+        });
+        return {
+            ...result,
+            workspace: result.workspace ?? null,
+            agent: result.agent ?? undefined,
+            setupTerminalId: result.setupTerminalId ?? null,
+            requestId: result.requestId ?? resolvedRequestId,
+        };
+    }
+    async createLegacyWorkspace(input, requestId) {
+        // COMPAT(workspaceRequestReceipts): added in v0.8.0; remove gate after 2027-03-07.
+        if (input.idempotencyKey !== undefined &&
+            !this.lastServerInfoMessage?.features?.workspaceRequestReceipts) {
+            throw new Error("Update the host to use retry-safe workspace creation.");
+        }
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "workspace.create.request",
+                source: input.source,
+                ...(input.idempotencyKey !== undefined ? { idempotencyKey: input.idempotencyKey } : {}),
+                ...(input.title !== undefined ? { title: input.title } : {}),
+                ...(input.firstAgentContext !== undefined
+                    ? { firstAgentContext: input.firstAgentContext }
+                    : {}),
+            },
+            responseType: "workspace.create.response",
+        });
+    }
+    async validateBranch(options, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "validate_branch_request",
+                cwd: options.cwd,
+                branchName: options.branchName,
+            },
+            responseType: "validate_branch_response",
+        });
+    }
+    async getBranchSuggestions(options, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "branch_suggestions_request",
+                cwd: options.cwd,
+                query: options.query,
+                limit: options.limit,
+            },
+            responseType: "branch_suggestions_response",
+        });
+    }
+    async searchForge(options, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "forge.search.request",
+                cwd: options.cwd,
+                query: options.query,
+                limit: options.limit,
+                kinds: options.kinds,
+            },
+            responseType: "forge.search.response",
+            timeout: 15000,
+        });
+    }
+    async searchGitHub(options, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "github_search_request",
+                cwd: options.cwd,
+                query: options.query,
+                limit: options.limit,
+                kinds: options.kinds,
+            },
+            responseType: "github_search_response",
+        });
+    }
+    async getDirectorySuggestions(options, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "directory_suggestions_request",
+                query: options.query,
+                cwd: options.cwd,
+                includeFiles: options.includeFiles,
+                includeDirectories: options.includeDirectories,
+                matchMode: options.matchMode,
+                limit: options.limit,
+            },
+            responseType: "directory_suggestions_response",
+            // Home-tree scans on large home dirs can take several seconds; don't cut
+            // the suggestion request off early (it would surface as an empty list).
+        });
+    }
+    // ============================================================================
+    // File Explorer
+    // ============================================================================
+    async requestFileExplorer(cwd, path, mode, requestId, acceptBinary = false, maxBytes) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "file_explorer_request",
+                cwd,
+                path,
+                mode,
+                ...(acceptBinary ? { acceptBinary: true } : {}),
+                ...(maxBytes ? { maxBytes } : {}),
+            },
+            responseType: "file_explorer_response",
+        });
+    }
+    async listDirectory(cwd, path, requestId) {
+        const payload = await this.requestFileExplorer(cwd, path, "list", requestId);
+        if (payload.error) {
+            throw new Error(payload.error);
+        }
+        if (!payload.directory) {
+            throw new Error("Directory listing unavailable.");
+        }
+        return payload.directory;
+    }
+    async readFile(cwd, path, requestId, maxBytes) {
+        const resolvedRequestId = this.createRequestId(requestId);
+        this.pendingBinaryFileReads.set(resolvedRequestId, { cwd, path, maxBytes });
+        try {
+            const payload = await this.requestFileExplorer(cwd, path, "file", resolvedRequestId, true, maxBytes);
+            if (payload.error) {
+                throw new Error(payload.error);
+            }
+            const binaryResult = this.completedBinaryFileReads.get(resolvedRequestId);
+            if (binaryResult) {
+                this.completedBinaryFileReads.delete(resolvedRequestId);
+                return binaryResult;
+            }
+            if (!payload.file) {
+                throw new Error("File unavailable.");
+            }
+            return legacyExplorerFileToBytes(payload.file);
+        }
+        finally {
+            this.pendingBinaryFileReads.delete(resolvedRequestId);
+            this.activeBinaryFileTransfers.delete(resolvedRequestId);
+        }
+    }
+    async subscribeFile(input, onUpdate) {
+        const subscriptionId = this.createRequestId();
+        this.fileSubscriptions.set(subscriptionId, { ...input, onUpdate });
+        try {
+            const payload = await this.sendCorrelatedSessionRequest({
+                message: {
+                    type: "fs.file.subscribe.request",
+                    cwd: input.cwd,
+                    path: input.path,
+                    subscriptionId,
+                },
+                responseType: "fs.file.subscribe.response",
+            });
+            return {
+                initial: payload.initial,
+                unsubscribe: () => {
+                    if (!this.fileSubscriptions.delete(subscriptionId))
+                        return;
+                    void this.sendCorrelatedSessionRequest({
+                        message: { type: "fs.file.unsubscribe.request", subscriptionId },
+                        responseType: "fs.file.unsubscribe.response",
+                    }).catch(() => undefined);
+                },
+            };
+        }
+        catch (error) {
+            this.fileSubscriptions.delete(subscriptionId);
+            throw error;
+        }
+    }
+    async writeFile(input) {
+        const payload = await this.sendCorrelatedSessionRequest({
+            message: { type: "fs.file.write.request", ...input },
+            responseType: "fs.file.write.response",
+        });
+        return payload.result;
+    }
+    async createFileEntry(input) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            message: { type: "fs.entry.create.request", ...input },
+        });
+    }
+    async renameFileEntry(input) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            message: { type: "fs.entry.rename.request", ...input },
+        });
+    }
+    async duplicateFileEntry(input) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            message: { type: "fs.entry.duplicate.request", ...input },
+        });
+    }
+    async deleteFileEntry(input) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            message: { type: "fs.entry.delete.request", ...input },
+        });
+    }
+    async checkoutDiscardChanges(cwd, input) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            message: { type: "checkout.discard_changes.request", cwd, paths: input.paths },
+        });
+    }
+    async uploadFile(input) {
+        const bytes = asUint8Array(input.bytes);
+        if (!bytes) {
+            throw new Error("File bytes are required.");
+        }
+        const resolvedRequestId = this.createRequestId(input.requestId);
+        const modifiedAt = input.modifiedAt ?? new Date().toISOString();
+        const responsePromise = this.sendCorrelatedRequest({
+            requestId: resolvedRequestId,
+            message: {
+                type: "file.upload.request",
+                fileName: input.fileName,
+                mimeType: input.mimeType,
+                size: bytes.byteLength,
+                modifiedAt,
+                requestId: resolvedRequestId,
+            },
+            responseType: "file.upload.response",
+            options: { skipQueue: true },
+        });
+        this.sendBinaryFrame(encodeFileTransferFrame({
+            opcode: FileTransferOpcode.FileBegin,
+            requestId: resolvedRequestId,
+            metadata: {
+                mime: input.mimeType,
+                size: bytes.byteLength,
+                encoding: "binary",
+                modifiedAt,
+                fileName: input.fileName,
+            },
+        }));
+        const chunkSize = input.chunkSize ?? 1024 * 1024;
+        for (let offset = 0; offset < bytes.byteLength; offset += chunkSize) {
+            this.sendBinaryFrame(encodeFileTransferFrame({
+                opcode: FileTransferOpcode.FileChunk,
+                requestId: resolvedRequestId,
+                payload: bytes.subarray(offset, Math.min(offset + chunkSize, bytes.byteLength)),
+            }));
+        }
+        this.sendBinaryFrame(encodeFileTransferFrame({
+            opcode: FileTransferOpcode.FileEnd,
+            requestId: resolvedRequestId,
+        }));
+        return responsePromise;
+    }
+    async requestDownloadToken(cwd, path, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "file_download_token_request",
+                cwd,
+                path,
+            },
+            responseType: "file_download_token_response",
+        });
+    }
+    async requestProjectIcon(cwd, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "project_icon_request",
+                cwd,
+            },
+            responseType: "project_icon_response",
+        });
+    }
+    async getProjectIcon(projectId, requestId) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            requestId,
+            message: { type: "project.icon.get.request", projectId },
+        });
+    }
+    // ============================================================================
+    // Provider Models / Commands
+    // ============================================================================
+    async listProviderModels(provider, options) {
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId: options?.requestId,
+            message: {
+                type: "list_provider_models_request",
+                provider,
+                cwd: options?.cwd,
+            },
+            responseType: "list_provider_models_response",
+            // Provider SDK cold starts (especially model discovery) can exceed 60s.
+            timeout: 90000,
+        });
+        return normalizeListProviderModelsPayload(payload);
+    }
+    async listProviderModes(provider, options) {
+        return this.sendCorrelatedSessionRequest({
+            requestId: options?.requestId,
+            message: {
+                type: "list_provider_modes_request",
+                provider,
+                cwd: options?.cwd,
+            },
+            responseType: "list_provider_modes_response",
+            timeout: 90000,
+        });
+    }
+    async listProviderFeatures(draftConfig, options) {
+        return this.sendCorrelatedSessionRequest({
+            requestId: options?.requestId,
+            message: {
+                type: "list_provider_features_request",
+                draftConfig,
+            },
+            responseType: "list_provider_features_response",
+            timeout: 90000,
+        });
+    }
+    async listAvailableProviders(options) {
+        return this.sendCorrelatedSessionRequest({
+            requestId: options?.requestId,
+            message: {
+                type: "list_available_providers_request",
+            },
+            responseType: "list_available_providers_response",
+        });
+    }
+    async getProvidersSnapshot(options) {
+        const payload = await this.requestProvidersSnapshot(options);
+        return normalizeProvidersSnapshotPayload(payload, this.config.providerSnapshots !== "wire");
+    }
+    requestProvidersSnapshot(options) {
+        return this.sendCorrelatedSessionRequest({
+            requestId: options?.requestId,
+            message: {
+                type: "get_providers_snapshot_request",
+                cwd: options?.cwd,
+                ifNoneMatch: options?.ifNoneMatch,
+            },
+            responseType: "get_providers_snapshot_response",
+        });
+    }
+    async getDaemonConfig(requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "get_daemon_config_request",
+            },
+            responseType: "get_daemon_config_response",
+        });
+    }
+    async getDaemonStatus(options) {
+        return this.sendCorrelatedSessionRequest({
+            requestId: options?.requestId,
+            message: {
+                type: "daemon.get_status.request",
+            },
+            responseType: "daemon.get_status.response",
+            timeout: options?.timeout,
+        });
+    }
+    async reloadDaemonConfig(requestId) {
+        this.requireDaemonConfigReloadSupport();
+        return this.sendNamespacedCorrelatedSessionRequest({
+            requestId,
+            message: { type: "daemon.config.reload.request" },
+        });
+    }
+    async connectHub(hubUrl, token, permissions = [], requestId) {
+        this.requireHubRelationshipSupport();
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "hub.management.daemon.connect.request", hubUrl, token, permissions },
+            responseType: "hub.management.daemon.connect.response",
+        });
+    }
+    async updateHubPermissions(input, requestId) {
+        this.requireHubRelationshipSupport();
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "hub.management.daemon.permissions.update.request",
+                grant: input.grant ?? [],
+                revoke: input.revoke ?? [],
+            },
+            responseType: "hub.management.daemon.permissions.update.response",
+        });
+    }
+    async getHubStatus(requestId) {
+        this.requireHubRelationshipSupport();
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "hub.management.daemon.get_status.request" },
+            responseType: "hub.management.daemon.get_status.response",
+        });
+    }
+    async disconnectHub(force = false, requestId) {
+        this.requireHubRelationshipSupport();
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "hub.management.daemon.disconnect.request", force },
+            responseType: "hub.management.daemon.disconnect.response",
+        });
+    }
+    async getDaemonPairingOffer(options) {
+        return this.sendCorrelatedSessionRequest({
+            requestId: options?.requestId,
+            message: {
+                type: "daemon.get_pairing_offer.request",
+            },
+            responseType: "daemon.get_pairing_offer.response",
+            timeout: options?.timeout,
+        });
+    }
+    async collectDiagnostics(requestId) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "diagnostics.request",
+            },
+        });
+    }
+    async patchDaemonConfig(config, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "set_daemon_config_request",
+                config,
+            },
+            responseType: "set_daemon_config_response",
+        });
+    }
+    sendBrowserAutomationExecuteResponse(response) {
+        this.sendSessionMessageStrict(response);
+    }
+    async readProjectConfig(repoRoot, requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "read_project_config_request",
+                repoRoot,
+            },
+            responseType: "read_project_config_response",
+        });
+    }
+    async writeProjectConfig(input) {
+        return this.sendCorrelatedSessionRequest({
+            requestId: input.requestId,
+            message: {
+                type: "write_project_config_request",
+                repoRoot: input.repoRoot,
+                config: input.config,
+                expectedRevision: input.expectedRevision,
+            },
+            responseType: "write_project_config_response",
+        });
+    }
+    async refreshProvidersSnapshot(options) {
+        return this.sendCorrelatedSessionRequest({
+            requestId: options?.requestId,
+            message: {
+                type: "refresh_providers_snapshot_request",
+                cwd: options?.cwd,
+                providers: options?.providers,
+            },
+            responseType: "refresh_providers_snapshot_response",
+            timeout: 120000,
+        });
+    }
+    async getProviderDiagnostic(provider, options) {
+        return this.sendCorrelatedSessionRequest({
+            requestId: options?.requestId,
+            message: {
+                type: "provider_diagnostic_request",
+                provider,
+            },
+            responseType: "provider_diagnostic_response",
+            timeout: 180000,
+        });
+    }
+    async listProviderUsage(options) {
+        return this.sendNamespacedCorrelatedSessionRequest({
+            requestId: options?.requestId,
+            message: {
+                type: "provider.usage.list.request",
+            },
+        });
+    }
+    async listCommands(input, legacyOptions) {
+        const options = normalizeListCommandsOptions(input, legacyOptions);
+        return this.sendCorrelatedSessionRequest({
+            requestId: options.requestId,
+            message: {
+                type: "list_commands_request",
+                agentId: options.agentId,
+                ...(options.draftConfig ? { draftConfig: options.draftConfig } : {}),
+            },
+            responseType: "list_commands_response",
+        });
+    }
+    // ============================================================================
+    // Permissions
+    // ============================================================================
+    async respondToPermission(agentId, requestId, response) {
+        this.sendSessionMessage({
+            type: "agent_permission_response",
+            agentId,
+            requestId,
+            response,
+        });
+    }
+    async getPluginCatalog() {
+        const requestId = this.createRequestId();
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "plugin.catalog.get.request", requestId },
+            responseType: "plugin.catalog.get.response",
+        });
+        return payload.plugins;
+    }
+    async listPlugins() {
+        const requestId = this.createRequestId();
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "plugin.list.request", requestId },
+            responseType: "plugin.list.response",
+        });
+        return payload.plugins;
+    }
+    async getPluginLogs(pluginId) {
+        const requestId = this.createRequestId();
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "plugin.logs.get.request", requestId, pluginId },
+            responseType: "plugin.logs.get.response",
+        });
+        return payload.entries;
+    }
+    async getAgentSkillsStatus() {
+        const requestId = this.createRequestId();
+        return this.sendCorrelatedSessionRequest({
+            message: { type: "agent.skills.get_status.request", requestId },
+            responseType: "agent.skills.get_status.response",
+        });
+    }
+    async reconcileAgentSkills() {
+        const requestId = this.createRequestId();
+        return this.sendCorrelatedSessionRequest({
+            message: { type: "agent.skills.reconcile.request", requestId },
+            responseType: "agent.skills.reconcile.response",
+        });
+    }
+    async uninstallAgentSkills() {
+        const requestId = this.createRequestId();
+        return this.sendCorrelatedSessionRequest({
+            message: { type: "agent.skills.uninstall.request", requestId },
+            responseType: "agent.skills.uninstall.response",
+        });
+    }
+    async saveAgentSkillsSelection(selection, confirmedRemovals) {
+        const requestId = this.createRequestId();
+        return this.sendCorrelatedSessionRequest({
+            message: {
+                type: "agent.skills.save_selection.request",
+                requestId,
+                selection,
+                ...(confirmedRemovals ? { confirmedRemovals: [...confirmedRemovals] } : {}),
+            },
+            responseType: "agent.skills.save_selection.response",
+        });
+    }
+    async importLegacyAgentSkillsSelection(selection) {
+        const requestId = this.createRequestId();
+        return this.sendCorrelatedSessionRequest({
+            message: {
+                type: "agent.skills.import_legacy_selection.request",
+                requestId,
+                selection,
+            },
+            responseType: "agent.skills.import_legacy_selection.response",
+        });
+    }
+    async installDirectoryPlugin(path, id) {
+        const requestId = this.createRequestId();
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "plugin.directory.install.request", requestId, path, ...(id ? { id } : {}) },
+            responseType: "plugin.directory.install.response",
+        });
+        return payload.plugin;
+    }
+    async installPluginSource(input) {
+        const requestId = this.createRequestId();
+        const reference = parsePluginSourceReference(input.source);
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "plugin.source.install.request",
+                requestId,
+                source: reference.source,
+                ...(reference.pluginPath ? { pluginPath: reference.pluginPath } : {}),
+                ...(input.id ? { id: input.id } : {}),
+                ...(input.ref ? { ref: input.ref } : {}),
+            },
+            responseType: "plugin.source.install.response",
+        });
+        return payload.plugin;
+    }
+    async getPluginSourceStatus(pluginId) {
+        const requestId = this.createRequestId();
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "plugin.source.status.request",
+                requestId,
+                ...(pluginId ? { pluginId } : {}),
+            },
+            responseType: "plugin.source.status.response",
+        });
+        return payload.plugins;
+    }
+    async updatePluginSources(pluginId) {
+        const requestId = this.createRequestId();
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "plugin.source.update.request",
+                requestId,
+                ...(pluginId ? { pluginId } : {}),
+            },
+            responseType: "plugin.source.update.response",
+        });
+        return payload.plugins;
+    }
+    async inspectDirectoryPlugin(path) {
+        const requestId = this.createRequestId();
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "plugin.directory.inspect.request", requestId, path },
+            responseType: "plugin.directory.inspect.response",
+        });
+    }
+    async reloadPlugin(pluginId) {
+        return this.managePlugin("reload", pluginId);
+    }
+    async enablePlugin(pluginId) {
+        return this.managePlugin("enable", pluginId);
+    }
+    async disablePlugin(pluginId) {
+        return this.managePlugin("disable", pluginId);
+    }
+    async removePlugin(pluginId) {
+        const requestId = this.createRequestId();
+        await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "plugin.remove.request", requestId, pluginId },
+            responseType: "plugin.remove.response",
+        });
+    }
+    async managePlugin(action, pluginId) {
+        const requestId = this.createRequestId();
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: `plugin.${action}.request`, requestId, pluginId },
+            responseType: `plugin.${action}.response`,
+        });
+        return payload.plugin;
+    }
+    async invokePluginRpc(pluginId, method, input) {
+        const requestId = this.createRequestId();
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "plugin.rpc.invoke.request",
+                requestId,
+                pluginId,
+                method,
+                input,
+            },
+            responseType: "plugin.rpc.invoke.response",
+        });
+        return payload.output;
+    }
+    async respondToPermissionAndWait(agentId, requestId, response, timeout = 15000) {
+        const message = SessionInboundMessageSchema.parse({
+            type: "agent_permission_response",
+            agentId,
+            requestId,
+            response,
+        });
+        return this.sendRequest({
+            requestId,
+            message,
+            timeout,
+            options: { skipQueue: true },
+            select: (msg) => {
+                if (msg.type !== "agent_permission_resolved") {
+                    return null;
+                }
+                if (msg.payload.requestId !== requestId) {
+                    return null;
+                }
+                if (msg.payload.agentId !== agentId) {
+                    return null;
+                }
+                return msg.payload;
+            },
+        });
+    }
+    // ============================================================================
+    // Waiting / Streaming Helpers
+    // ============================================================================
+    async waitForAgentUpsert(agentId, predicate, timeout = 60000) {
+        const deadline = Date.now() + timeout;
+        const remainingTimeoutMs = () => Math.max(1, deadline - Date.now());
+        const timeoutError = () => new Error(`Timed out waiting for agent ${agentId}`);
+        const fetchAgentWithinDeadline = () => this.fetchAgent({ agentId, timeout: remainingTimeoutMs() }).catch(() => null);
+        const initialResult = await fetchAgentWithinDeadline();
+        if (initialResult && predicate(initialResult.agent)) {
+            return initialResult.agent;
+        }
+        if (Date.now() >= deadline) {
+            throw timeoutError();
+        }
+        return await new Promise((resolve, reject) => {
+            let settled = false;
+            let pollInFlight = false;
+            let pollTimer = null;
+            let timeoutTimer = null;
+            let unsubscribe = null;
+            const finish = (result) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                if (timeoutTimer) {
+                    clearTimeout(timeoutTimer);
+                    timeoutTimer = null;
+                }
+                if (pollTimer) {
+                    clearInterval(pollTimer);
+                    pollTimer = null;
+                }
+                if (unsubscribe) {
+                    unsubscribe();
+                    unsubscribe = null;
+                }
+                if (result.kind === "ok") {
+                    resolve(result.snapshot);
+                    return;
+                }
+                reject(result.error);
+            };
+            const maybeResolve = (snapshot) => {
+                if (!snapshot) {
+                    return false;
+                }
+                if (!predicate(snapshot)) {
+                    return false;
+                }
+                finish({ kind: "ok", snapshot });
+                return true;
+            };
+            const poll = async () => {
+                if (settled || pollInFlight) {
+                    return;
+                }
+                pollInFlight = true;
+                try {
+                    const result = await fetchAgentWithinDeadline();
+                    maybeResolve(result?.agent ?? null);
+                }
+                finally {
+                    pollInFlight = false;
+                }
+            };
+            unsubscribe = this.on("agent_update", (message) => {
+                if (settled) {
+                    return;
+                }
+                if (message.payload.kind !== "upsert") {
+                    return;
+                }
+                const snapshot = message.payload.agent;
+                if (snapshot.id !== agentId) {
+                    return;
+                }
+                maybeResolve(snapshot);
+            });
+            const remaining = Math.max(1, deadline - Date.now());
+            timeoutTimer = setTimeout(() => {
+                finish({
+                    kind: "error",
+                    error: timeoutError(),
+                });
+            }, remaining);
+            pollTimer = setInterval(() => {
+                void poll();
+            }, 250);
+            void poll();
+        });
+    }
+    async waitForFinish(agentId, timeout = 60000) {
+        const requestId = this.createRequestId();
+        const hasTimeout = Number.isFinite(timeout) && timeout > 0;
+        const message = SessionInboundMessageSchema.parse({
+            type: "wait_for_finish_request",
+            requestId,
+            agentId,
+            ...(hasTimeout ? { timeoutMs: timeout } : {}),
+        });
+        const payload = await this.sendCorrelatedRequest({
+            requestId,
+            message,
+            responseType: "wait_for_finish_response",
+            timeout: hasTimeout ? timeout + 5000 : 0,
+            options: { skipQueue: true },
+        });
+        return {
+            status: payload.status,
+            final: payload.final,
+            error: payload.error,
+            lastMessage: payload.lastMessage,
+        };
+    }
+    // ============================================================================
+    // Terminals
+    // ============================================================================
+    subscribeTerminals(input) {
+        this.terminalDirectorySubscriptions.set(terminalSubscriptionKey(input.cwd, input.workspaceId), {
+            cwd: input.cwd,
+            workspaceId: input.workspaceId,
+        });
+        if (!this.transport || this.connectionState.status !== "connected") {
+            return;
+        }
+        this.sendSessionMessage({
+            type: "subscribe_terminals_request",
+            cwd: input.cwd,
+            ...(input.workspaceId !== undefined ? { workspaceId: input.workspaceId } : {}),
+        });
+    }
+    unsubscribeTerminals(input) {
+        this.terminalDirectorySubscriptions.delete(terminalSubscriptionKey(input.cwd, input.workspaceId));
+        if (!this.transport || this.connectionState.status !== "connected") {
+            return;
+        }
+        this.sendSessionMessage({
+            type: "unsubscribe_terminals_request",
+            cwd: input.cwd,
+            ...(input.workspaceId !== undefined ? { workspaceId: input.workspaceId } : {}),
+        });
+    }
+    async listTerminals(cwd, requestId, options) {
+        const resolvedRequestId = this.createRequestId(requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "list_terminals_request",
+            ...(cwd === undefined ? {} : { cwd }),
+            ...(options?.workspaceId !== undefined ? { workspaceId: options.workspaceId } : {}),
+            requestId: resolvedRequestId,
+        });
+        return this.sendCorrelatedRequest({
+            requestId: resolvedRequestId,
+            message,
+            responseType: "list_terminals_response",
+            options: { skipQueue: true },
+        });
+    }
+    async createTerminal(cwd, name, requestId, options) {
+        const resolvedRequestId = this.createRequestId(requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "create_terminal_request",
+            cwd,
+            name,
+            agentId: options?.agentId,
+            command: options?.command,
+            args: options?.args,
+            ...(options?.workspaceId !== undefined ? { workspaceId: options.workspaceId } : {}),
+            ...(options?.size !== undefined ? { size: options.size } : {}),
+            requestId: resolvedRequestId,
+        });
+        return this.sendCorrelatedRequest({
+            requestId: resolvedRequestId,
+            message,
+            responseType: "create_terminal_response",
+            options: { skipQueue: true },
+        });
+    }
+    async renameTerminal(input) {
+        return this.sendCorrelatedSessionRequest({
+            requestId: input.requestId,
+            message: {
+                type: "terminal.rename.request",
+                terminalId: input.terminalId,
+                title: input.title,
+            },
+            responseType: "terminal.rename.response",
+        });
+    }
+    async subscribeTerminal(terminalId, optionsOrRequestId) {
+        const restore = typeof optionsOrRequestId === "object" ? optionsOrRequestId.restore : undefined;
+        const requestId = typeof optionsOrRequestId === "object" ? optionsOrRequestId.requestId : optionsOrRequestId;
+        const resolvedRequestId = this.createRequestId(requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "subscribe_terminal_request",
+            terminalId,
+            requestId: resolvedRequestId,
+            ...(restore ? { restore } : {}),
+        });
+        const payload = await this.sendCorrelatedRequest({
+            requestId: resolvedRequestId,
+            message,
+            responseType: "subscribe_terminal_response",
+            options: { skipQueue: true },
+        });
+        if (payload.error === null) {
+            this.terminalStreams.setSlot(terminalId, payload.slot);
+        }
+        return payload;
+    }
+    unsubscribeTerminal(terminalId) {
+        this.terminalStreams.removeTerminal(terminalId);
+        this.sendSessionMessage({
+            type: "unsubscribe_terminal_request",
+            terminalId,
+        });
+    }
+    sendTerminalInput(terminalId, message) {
+        const frame = this.terminalStreams.encodeInput(terminalId, message);
+        if (frame) {
+            this.sendBinaryFrame(frame);
+            return;
+        }
+        this.sendSessionMessage({
+            type: "terminal_input",
+            terminalId,
+            message,
+        });
+    }
+    async killTerminal(terminalId, requestId) {
+        const resolvedRequestId = this.createRequestId(requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "kill_terminal_request",
+            terminalId,
+            requestId: resolvedRequestId,
+        });
+        return this.sendCorrelatedRequest({
+            requestId: resolvedRequestId,
+            message,
+            responseType: "kill_terminal_response",
+            options: { skipQueue: true },
+        });
+    }
+    async closeItems(input, requestId) {
+        const resolvedRequestId = this.createRequestId(requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "close_items_request",
+            agentIds: input.agentIds ?? [],
+            terminalIds: input.terminalIds ?? [],
+            requestId: resolvedRequestId,
+        });
+        return this.sendCorrelatedRequest({
+            requestId: resolvedRequestId,
+            message,
+            responseType: "close_items_response",
+            options: { skipQueue: true },
+        });
+    }
+    async captureTerminal(terminalId, options, requestId) {
+        const resolvedRequestId = this.createRequestId(requestId);
+        const message = SessionInboundMessageSchema.parse({
+            type: "capture_terminal_request",
+            terminalId,
+            ...(options?.start === undefined ? {} : { start: options.start }),
+            ...(options?.end === undefined ? {} : { end: options.end }),
+            ...(options?.stripAnsi === undefined ? {} : { stripAnsi: options.stripAnsi }),
+            requestId: resolvedRequestId,
+        });
+        return this.sendCorrelatedRequest({
+            requestId: resolvedRequestId,
+            message,
+            responseType: "capture_terminal_response",
+            options: { skipQueue: true },
+        });
+    }
+    async scheduleCreate(options) {
+        return this.sendCorrelatedSessionRequest({
+            requestId: options.requestId,
+            message: {
+                type: "schedule/create",
+                prompt: options.prompt,
+                cadence: options.cadence,
+                target: options.target,
+                ...(options.name ? { name: options.name } : {}),
+                ...(typeof options.maxRuns === "number" ? { maxRuns: options.maxRuns } : {}),
+                ...(options.expiresAt ? { expiresAt: options.expiresAt } : {}),
+                ...(typeof options.runOnCreate === "boolean" ? { runOnCreate: options.runOnCreate } : {}),
+            },
+            responseType: "schedule/create/response",
+        });
+    }
+    async scheduleList(requestId) {
+        return this.sendCorrelatedSessionRequest({
+            requestId,
+            message: {
+                type: "schedule/list",
+            },
+            responseType: "schedule/list/response",
+        });
+    }
+    async scheduleInspect(options) {
+        return this.sendCorrelatedSessionRequest({
+            requestId: options.requestId,
+            message: {
+                type: "schedule/inspect",
+                scheduleId: options.id,
+            },
+            responseType: "schedule/inspect/response",
+        });
+    }
+    async scheduleLogs(options) {
+        return this.sendCorrelatedSessionRequest({
+            requestId: options.requestId,
+            message: {
+                type: "schedule/logs",
+                scheduleId: options.id,
+            },
+            responseType: "schedule/logs/response",
+        });
+    }
+    async schedulePause(options) {
+        return this.sendCorrelatedSessionRequest({
+            requestId: options.requestId,
+            message: {
+                type: "schedule/pause",
+                scheduleId: options.id,
+            },
+            responseType: "schedule/pause/response",
+        });
+    }
+    async scheduleResume(options) {
+        return this.sendCorrelatedSessionRequest({
+            requestId: options.requestId,
+            message: {
+                type: "schedule/resume",
+                scheduleId: options.id,
+            },
+            responseType: "schedule/resume/response",
+        });
+    }
+    async scheduleDelete(options) {
+        return this.sendCorrelatedSessionRequest({
+            requestId: options.requestId,
+            message: {
+                type: "schedule/delete",
+                scheduleId: options.id,
+            },
+            responseType: "schedule/delete/response",
+        });
+    }
+    async scheduleRunOnce(options) {
+        return this.sendCorrelatedSessionRequest({
+            requestId: options.requestId,
+            message: {
+                type: "schedule/run-once",
+                scheduleId: options.id,
+            },
+            responseType: "schedule/run-once/response",
+        });
+    }
+    async scheduleUpdate(options) {
+        return this.sendCorrelatedSessionRequest({
+            requestId: options.requestId,
+            message: {
+                type: "schedule/update",
+                scheduleId: options.id,
+                ...(options.name !== undefined ? { name: options.name } : {}),
+                ...(options.prompt !== undefined ? { prompt: options.prompt } : {}),
+                ...(options.cadence !== undefined ? { cadence: options.cadence } : {}),
+                ...(options.newAgentConfig !== undefined ? { newAgentConfig: options.newAgentConfig } : {}),
+                ...(options.maxRuns !== undefined ? { maxRuns: options.maxRuns } : {}),
+                ...(options.expiresAt !== undefined ? { expiresAt: options.expiresAt } : {}),
+            },
+            responseType: "schedule/update/response",
+        });
+    }
+    onTerminalStreamEvent(handler) {
+        return this.terminalStreams.onEvent(handler);
+    }
+    async waitForTerminalStreamEvent(predicate, timeout = 5000) {
+        return new Promise((resolve, reject) => {
+            const timeoutHandle = setTimeout(() => {
+                unsubscribe();
+                reject(new Error(`Timeout waiting for terminal stream event (${timeout}ms)`));
+            }, timeout);
+            const unsubscribe = this.onTerminalStreamEvent((event) => {
+                if (!predicate(event)) {
+                    return;
+                }
+                clearTimeout(timeoutHandle);
+                unsubscribe();
+                resolve(event);
+            });
+        });
+    }
+    // ============================================================================
+    // Internals
+    // ============================================================================
+    createRequestId(requestId) {
+        return requestId ?? crypto.randomUUID();
+    }
+    getLastServerInfoMessage() {
+        return this.lastServerInfoMessage;
+    }
+    requireHubRelationshipSupport() {
+        // COMPAT(hubRelationship): added in v0.1.X, drop the gate when floor >= v0.1.X.
+        if (this.lastServerInfoMessage?.features?.hubRelationship !== true) {
+            throw new Error("Update the host to use Hub relationship management.");
+        }
+    }
+    requireDaemonConfigReloadSupport() {
+        // COMPAT(daemonConfigReload): added in v0.4.0, remove gate after 2027-02-14.
+        if (this.lastServerInfoMessage?.features?.daemonConfigReload !== true) {
+            throw new Error("Update the host to reload daemon configuration.");
+        }
+    }
+    requireSideConversationSupport() {
+        // COMPAT(sideConversations): added in 0.7.0-beta.2.fork.1, fork-only — stock peers never gain it, so the gate lasts as long as stock peers are supported.
+        if (this.lastServerInfoMessage?.features?.sideConversations !== true) {
+            throw new Error("Update the host to use side conversations.");
+        }
+    }
+    resolveTransportUrlForAttempt() {
+        return this.config.url;
+    }
+    sendHelloMessage() {
+        if (!this.transport) {
+            this.scheduleReconnect({
+                reason: "Transport unavailable before hello",
+                event: "HELLO_TRANSPORT_MISSING",
+                reasonCode: "transport_error",
+            });
+            return;
+        }
+        try {
+            this.sendJsonMessage("hello", "hello", {
+                type: "hello",
+                clientId: this.config.clientId,
+                clientType: this.config.clientType ?? "cli",
+                protocolVersion: 1,
+                capabilities: {
+                    ...DEFAULT_CLIENT_CAPABILITIES,
+                    // COMPAT(sideConversations): added in 0.7.0-beta.2.fork.1, fork-only.
+                    [CLIENT_CAPS.sideConversations]: true,
+                    ...this.config.capabilities,
+                },
+                ...(this.config.appVersion ? { appVersion: this.config.appVersion } : {}),
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Failed to send hello message";
+            this.lastErrorValue = message;
+            this.scheduleReconnect({
+                reason: message,
+                event: "HELLO_SEND_FAILED",
+                reasonCode: "transport_error",
+            });
+        }
+    }
+    disposeTransport(code = 1001, reason = "Reconnecting") {
+        this.providerSnapshotUpdates.pause();
+        this.stopLivenessHeartbeat();
+        this.cleanupTransport();
+        if (this.transport) {
+            try {
+                this.transport.close(code, reason);
+            }
+            catch {
+                // no-op
+            }
+            this.transport = null;
+        }
+    }
+    cleanupTransport() {
+        this.resetConnectTimeout();
+        if (this.pendingGenericTransportErrorTimeout) {
+            clearTimeout(this.pendingGenericTransportErrorTimeout);
+            this.pendingGenericTransportErrorTimeout = null;
+        }
+        for (const cleanup of this.transportCleanup) {
+            try {
+                cleanup();
+            }
+            catch {
+                // no-op
+            }
+        }
+        this.transportCleanup = [];
+    }
+    resetConnectTimeout() {
+        if (!this.connectTimeout) {
+            return;
+        }
+        clearTimeout(this.connectTimeout);
+        this.connectTimeout = null;
+    }
+    handleTransportMessage(data) {
+        const rawData = data && typeof data === "object" && "data" in data ? data.data : data;
+        if (typeof Blob !== "undefined" &&
+            rawData instanceof Blob &&
+            typeof rawData.arrayBuffer === "function") {
+            void rawData
+                .arrayBuffer()
+                .then((buffer) => {
+                this.handleTransportMessage(buffer);
+                return;
+            })
+                .catch(() => {
+                // Ignore failed blob decoding and allow reconnect logic to recover.
+            });
+            return;
+        }
+        const rawBytes = asUint8Array(rawData);
+        const isOpen = this.beginTraceSection("paseo.ws.frame.inbound", describeInboundTransportFrame(rawData, rawBytes));
+        try {
+            if (rawBytes && this.tryHandleBinaryFrame(rawBytes)) {
+                return;
+            }
+            const payload = decodeMessageData(rawData);
+            if (!payload) {
+                return;
+            }
+            this.handleJsonPayload(payload, rawBytes?.byteLength);
+        }
+        finally {
+            this.endTraceSection(isOpen);
+        }
+    }
+    handleJsonPayload(payload, rawBytesLength) {
+        const bytes = rawBytesLength ?? payload.length;
+        const startMs = perfNow();
+        let parsedJson;
+        const parseTraceOpen = this.beginTraceSection("paseo.ws.json.parse", {
+            size: String(bytes),
+        });
+        try {
+            parsedJson = JSON.parse(payload);
+        }
+        catch {
+            return;
+        }
+        finally {
+            this.endTraceSection(parseTraceOpen);
+        }
+        const parsed = validateWSOutboundMessage(parsedJson);
+        if (!parsed.success) {
+            const responseIdentity = extractCorrelatedResponseIdentity(parsedJson);
+            const envelopeType = parsedJson != null &&
+                typeof parsedJson === "object" &&
+                "type" in parsedJson &&
+                typeof parsedJson.type === "string"
+                ? parsedJson.type
+                : "unknown";
+            const msgType = responseIdentity?.responseType ?? envelopeType;
+            this.logger.warn({ msgType, error: parsed.error.message }, "Message validation failed");
+            if (responseIdentity) {
+                this.rejectWaitersForRequestId(responseIdentity.requestId, new DaemonProtocolError(responseIdentity));
+            }
+            return;
+        }
+        this.consecutiveLivenessFailures = 0;
+        if (parsed.data.type === "pong") {
+            this.traceInstant("paseo.ws.message.inbound", {
+                envelopeType: "pong",
+                messageType: "pong",
+            });
+            this.resolvePingProbe();
+            this.runtimeMetrics?.recordMessage("pong", bytes, perfNow() - startMs);
+            return;
+        }
+        this.traceInstant("paseo.ws.message.inbound", {
+            envelopeType: "session",
+            messageType: parsed.data.message.type,
+        });
+        this.handleSessionMessage(parsed.data.message);
+        const msgType = parsed.data.message.type;
+        this.runtimeMetrics?.recordMessage(msgType, bytes, perfNow() - startMs);
+        if (parsed.data.message.type === "agent_stream") {
+            this.runtimeMetrics?.recordAgentStream(parsed.data.message.payload);
+        }
+    }
+    tryHandleBinaryFrame(rawBytes) {
+        const fileFrame = decodeFileTransferFrame(rawBytes);
+        if (fileFrame) {
+            this.traceInstant("paseo.ws.message.inbound", {
+                envelopeType: "binary",
+                messageType: "file",
+                opcode: String(fileFrame.opcode),
+            });
+            this.consecutiveLivenessFailures = 0;
+            this.handleFileTransferFrame(fileFrame);
+            this.runtimeMetrics?.recordBinaryFrame("other", rawBytes.byteLength, 0);
+            return true;
+        }
+        const frame = decodeTerminalStreamFrame(rawBytes);
+        if (!frame) {
+            return false;
+        }
+        this.traceInstant("paseo.ws.message.inbound", {
+            envelopeType: "binary",
+            messageType: "terminal",
+            opcode: String(frame.opcode),
+        });
+        this.consecutiveLivenessFailures = 0;
+        const binaryStartMs = perfNow();
+        this.terminalStreams.handleFrame(frame);
+        let frameKind = "other";
+        if (frame.opcode === TerminalStreamOpcode.Output) {
+            frameKind = "output";
+        }
+        else if (frame.opcode === TerminalStreamOpcode.Snapshot) {
+            frameKind = "snapshot";
+        }
+        else if (frame.opcode === TerminalStreamOpcode.Restore) {
+            frameKind = "output";
+        }
+        this.runtimeMetrics?.recordBinaryFrame(frameKind, rawBytes.byteLength, perfNow() - binaryStartMs);
+        return true;
+    }
+    handleFileTransferFrame(frame) {
+        if (frame.opcode === FileTransferOpcode.FileBegin) {
+            const pending = this.pendingBinaryFileReads.get(frame.requestId);
+            if (!pending) {
+                return;
+            }
+            this.activeBinaryFileTransfers.set(frame.requestId, {
+                ...pending,
+                mime: frame.metadata.mime,
+                size: frame.metadata.size,
+                encoding: frame.metadata.encoding,
+                modifiedAt: frame.metadata.modifiedAt,
+                revision: frame.metadata.revision,
+                chunks: [],
+            });
+            return;
+        }
+        const transfer = this.activeBinaryFileTransfers.get(frame.requestId);
+        if (!transfer) {
+            return;
+        }
+        if (frame.opcode === FileTransferOpcode.FileChunk) {
+            // COMPAT(fileReadByteBudget): added in v0.5.0, remove after 2027-02-21 once daemon floor >= v0.5.0.
+            // Old daemons stream despite maxBytes; discard before client-side accumulation.
+            if (transfer.maxBytes && transfer.size > transfer.maxBytes) {
+                return;
+            }
+            transfer.chunks.push(frame.payload);
+            return;
+        }
+        // COMPAT(fileReadByteBudget): added in v0.5.0, remove after 2027-02-21 once daemon floor >= v0.5.0.
+        if (transfer.maxBytes && transfer.size > transfer.maxBytes) {
+            this.activeBinaryFileTransfers.delete(frame.requestId);
+            this.handleSessionMessage({
+                type: "file_explorer_response",
+                payload: {
+                    cwd: transfer.cwd,
+                    path: transfer.path,
+                    mode: "file",
+                    directory: null,
+                    file: null,
+                    error: "File is too large to display",
+                    requestId: frame.requestId,
+                },
+            });
+            return;
+        }
+        const bytes = concatByteChunks(transfer.chunks, transfer.size);
+        this.activeBinaryFileTransfers.delete(frame.requestId);
+        this.completedBinaryFileReads.set(frame.requestId, {
+            bytes,
+            mime: transfer.mime,
+            size: transfer.size,
+            path: transfer.path,
+            kind: binaryFileKind(transfer.mime, transfer.encoding),
+            modifiedAt: transfer.modifiedAt,
+            revision: transfer.revision,
+        });
+        this.handleSessionMessage({
+            type: "file_explorer_response",
+            payload: {
+                cwd: transfer.cwd,
+                path: transfer.path,
+                mode: "file",
+                directory: null,
+                file: null,
+                error: null,
+                requestId: frame.requestId,
+            },
+        });
+    }
+    updateConnectionState(next, metadata) {
+        const previous = this.connectionState;
+        this.connectionState = next;
+        const reasonFromNext = next.status === "disconnected" && typeof next.reason === "string" ? next.reason : null;
+        const reason = metadata?.reason ?? reasonFromNext;
+        const reasonCode = metadata?.reasonCode ?? toReasonCode(reason);
+        this.logger.debug({
+            serverId: this.logServerId,
+            clientIdHash: this.logClientIdHash,
+            from: previous.status,
+            to: next.status,
+            event: metadata?.event ?? "STATE_UPDATE",
+            connectionPath: this.logConnectionPath,
+            generation: this.logGeneration,
+            reasonCode,
+            reason,
+        }, "DaemonClientTransition");
+        for (const listener of this.connectionListeners) {
+            try {
+                listener(next);
+            }
+            catch {
+                // no-op
+            }
+        }
+    }
+    setReconnectEnabled(enabled) {
+        this.config = { ...this.config, reconnect: { ...this.config.reconnect, enabled } };
+        if (!enabled && this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+            this.reconnectTimeout = null;
+        }
+    }
+    scheduleReconnect(input) {
+        if (this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+            this.reconnectTimeout = null;
+        }
+        const wasDisposed = this.connectionState.status === "disposed";
+        const reason = input?.reason;
+        if (typeof reason === "string" && reason.trim().length > 0) {
+            this.lastErrorValue = reason.trim();
+        }
+        this.providerSnapshotUpdates.pause();
+        // Clear all pending waiters and queued sends since the connection was lost
+        // and responses from the previous connection will never arrive.
+        this.clearWaiters(new Error(reason ?? "Connection lost"));
+        this.rejectPendingSendQueue(new Error(reason ?? "Connection lost"));
+        this.rejectPingProbe(new Error(reason ?? "Connection lost"));
+        this.terminalStreams.clearSlots();
+        this.lastServerInfoMessage = null;
+        if (wasDisposed) {
+            this.rejectConnect(new Error(reason ?? "Daemon client is disposed"));
+            return;
+        }
+        this.emitDisconnectedStateForReconnect(reason, input);
+        if (!this.shouldReconnect || this.config.reconnect?.enabled === false) {
+            this.rejectConnect(new Error(reason ?? "Transport disconnected before connect"));
+            return;
+        }
+        this.armReconnectTimer();
+    }
+    emitDisconnectedStateForReconnect(reason, input) {
+        this.updateConnectionState({
+            status: "disconnected",
+            ...(reason ? { reason } : {}),
+        }, {
+            event: input?.event ?? "TRANSPORT_CLOSE",
+            ...(reason ? { reason } : {}),
+            ...(input?.reasonCode ? { reasonCode: input.reasonCode } : {}),
+        });
+    }
+    armReconnectTimer() {
+        const attempt = this.reconnectAttempt;
+        const baseDelay = this.config.reconnect?.baseDelayMs ?? DEFAULT_RECONNECT_BASE_DELAY_MS;
+        const maxDelay = this.config.reconnect?.maxDelayMs ?? DEFAULT_RECONNECT_MAX_DELAY_MS;
+        const delay = Math.min(baseDelay * 2 ** attempt, maxDelay);
+        this.reconnectAttempt = attempt + 1;
+        this.reconnectTimeout = setTimeout(() => {
+            this.reconnectTimeout = null;
+            if (!this.shouldReconnect) {
+                return;
+            }
+            this.attemptConnect();
+        }, delay);
+    }
+    resolvePingProbe() {
+        const probe = this.pingProbe;
+        if (!probe) {
+            return;
+        }
+        this.pingProbe = null;
+        clearTimeout(probe.timeoutHandle);
+        probe.resolve(perfNow() - probe.startedAt);
+    }
+    clearPingProbe() {
+        const probe = this.pingProbe;
+        if (!probe) {
+            return;
+        }
+        this.pingProbe = null;
+        clearTimeout(probe.timeoutHandle);
+    }
+    rejectPingProbe(error) {
+        const probe = this.pingProbe;
+        if (!probe) {
+            return;
+        }
+        this.pingProbe = null;
+        clearTimeout(probe.timeoutHandle);
+        probe.reject(error);
+    }
+    recordLivenessFailure(error) {
+        this.consecutiveLivenessFailures += 1;
+        if (this.consecutiveLivenessFailures < LIVENESS_FAILURE_RECONNECT_THRESHOLD) {
+            return;
+        }
+        this.consecutiveLivenessFailures = 0;
+        this.lastErrorValue = error.message;
+        this.disposeTransport(1001, "Liveness check timed out");
+        this.scheduleReconnect({
+            reason: error.message,
+            event: "LIVENESS_TIMEOUT",
+            reasonCode: "liveness_timeout",
+        });
+    }
+    handleSessionMessage(msg) {
+        if (msg.type === "providers_snapshot_update" &&
+            this.config.providerSnapshots !== "wire" &&
+            msg.payload.snapshotHash &&
+            !msg.payload.compactSnapshot) {
+            if (this.messageHandlers.has(msg.type) || this.eventListeners.size > 0) {
+                this.providerSnapshotUpdates.receive(msg);
+            }
+            return;
+        }
+        this.deliverSessionMessage(msg);
+    }
+    deliverSessionMessage(msg) {
+        const consumerMessage = normalizeProviderSnapshotUpdateMessage(msg, this.config.providerSnapshots !== "wire");
+        if (consumerMessage.type === "status") {
+            const serverInfo = parseServerInfoStatusPayload(consumerMessage.payload);
+            if (serverInfo) {
+                this.lastServerInfoMessage = serverInfo;
+                if (this.connectionState.status === "connecting") {
+                    this.resetConnectTimeout();
+                    this.reconnectAttempt = 0;
+                    this.updateConnectionState({ status: "connected" }, { event: "HELLO_SERVER_INFO" });
+                    this.startLivenessHeartbeat();
+                    this.subscriptions.restore();
+                    this.providerSnapshotUpdates.resume();
+                    this.resubscribeCheckoutDiffSubscriptions();
+                    this.resubscribeTerminalDirectorySubscriptions();
+                    this.resubscribeFileSubscriptions();
+                    this.creations.reconnect();
+                    this.flushPendingSendQueue();
+                    this.resolveConnect();
+                }
+            }
+        }
+        if (consumerMessage.type === "terminal_stream_exit") {
+            this.terminalStreams.removeTerminal(consumerMessage.payload.terminalId);
+        }
+        if (consumerMessage.type === "fs.file.update") {
+            this.fileSubscriptions
+                .get(consumerMessage.payload.subscriptionId)
+                ?.onUpdate(consumerMessage.payload.version);
+        }
+        if (this.rawMessageListeners.size > 0) {
+            for (const handler of this.rawMessageListeners) {
+                try {
+                    handler(consumerMessage);
+                }
+                catch {
+                    // no-op
+                }
+            }
+        }
+        const handlers = this.messageHandlers.get(consumerMessage.type);
+        if (handlers) {
+            for (const handler of handlers) {
+                try {
+                    handler(consumerMessage);
+                }
+                catch {
+                    // no-op
+                }
+            }
+        }
+        const event = this.toEvent(consumerMessage);
+        if (event) {
+            for (const handler of this.eventListeners) {
+                handler(event);
+            }
+        }
+        if (consumerMessage.type === "workspace.create.update" ||
+            consumerMessage.type === "agent.create.update")
+            this.creations.receive(consumerMessage.payload);
+        this.resolveWaiters(consumerMessage);
+    }
+    resolveWaiters(msg) {
+        for (const waiter of Array.from(this.waiters)) {
+            const result = waiter.predicate(msg);
+            if (result !== null) {
+                this.waiters.delete(waiter);
+                if (waiter.timeoutHandle) {
+                    clearTimeout(waiter.timeoutHandle);
+                }
+                waiter.resolve(result);
+            }
+        }
+    }
+    rejectWaitersForRequestId(requestId, error) {
+        for (const waiter of Array.from(this.waiters)) {
+            if (waiter.requestId !== requestId) {
+                continue;
+            }
+            this.waiters.delete(waiter);
+            if (waiter.timeoutHandle) {
+                clearTimeout(waiter.timeoutHandle);
+            }
+            waiter.reject(error);
+        }
+    }
+    clearWaiters(error) {
+        for (const waiter of Array.from(this.waiters)) {
+            if (waiter.timeoutHandle) {
+                clearTimeout(waiter.timeoutHandle);
+            }
+            waiter.reject(error);
+        }
+        this.waiters.clear();
+    }
+    toEvent(msg) {
+        switch (msg.type) {
+            case "agent_update":
+                return {
+                    type: "agent_update",
+                    agentId: msg.payload.kind === "upsert" ? msg.payload.agent.id : msg.payload.agentId,
+                    payload: msg.payload,
+                };
+            case "workspace_update":
+                return {
+                    type: "workspace_update",
+                    workspaceId: msg.payload.kind === "upsert" ? msg.payload.workspace.id : msg.payload.id,
+                    payload: msg.payload,
+                };
+            case "project.update":
+                return { type: "project.update", payload: msg.payload };
+            case "workspace_setup_progress":
+                return {
+                    type: "workspace_setup_progress",
+                    workspaceId: msg.payload.workspaceId,
+                    payload: msg.payload,
+                };
+            case "agent_stream":
+                return {
+                    type: "agent_stream",
+                    agentId: msg.payload.agentId,
+                    event: msg.payload.event,
+                    timestamp: msg.payload.timestamp,
+                    ...(typeof msg.payload.seq === "number" ? { seq: msg.payload.seq } : {}),
+                    ...(typeof msg.payload.epoch === "string" ? { epoch: msg.payload.epoch } : {}),
+                };
+            case "status":
+                return { type: "status", payload: msg.payload };
+            case "agent_deleted":
+                return { type: "agent_deleted", agentId: msg.payload.agentId };
+            case "agent_permission_request":
+                return {
+                    type: "agent_permission_request",
+                    agentId: msg.payload.agentId,
+                    request: msg.payload.request,
+                };
+            case "agent_permission_resolved":
+                return {
+                    type: "agent_permission_resolved",
+                    agentId: msg.payload.agentId,
+                    requestId: msg.payload.requestId,
+                    resolution: msg.payload.resolution,
+                };
+            case "providers_snapshot_update":
+                return {
+                    type: "providers_snapshot_update",
+                    payload: msg.payload,
+                };
+            default:
+                return null;
+        }
+    }
+    waitForWithCancel(predicate, timeout = 30000, options) {
+        // Capture stack trace at call site, not inside setTimeout
+        const timeoutError = new Error(`Timeout waiting for message (${timeout}ms)`);
+        let waiter = null;
+        let settled = false;
+        let rejectFn = null;
+        const promise = new Promise((resolve, reject) => {
+            const wrappedResolve = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(value);
+            };
+            const wrappedReject = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(error);
+            };
+            rejectFn = wrappedReject;
+            const timeoutHandle = timeout > 0
+                ? setTimeout(() => {
+                    if (waiter) {
+                        this.waiters.delete(waiter);
+                    }
+                    wrappedReject(timeoutError);
+                }, timeout)
+                : null;
+            waiter = {
+                predicate,
+                resolve: wrappedResolve,
+                reject: wrappedReject,
+                timeoutHandle,
+                requestId: options?.requestId,
+            };
+            this.waiters.add(waiter);
+        });
+        const cancel = (error) => {
+            if (settled) {
+                return;
+            }
+            if (waiter) {
+                this.waiters.delete(waiter);
+                if (waiter.timeoutHandle) {
+                    clearTimeout(waiter.timeoutHandle);
+                }
+            }
+            if (rejectFn) {
+                rejectFn(error);
+                return;
+            }
+            // Extremely unlikely: cancel called before the Promise executor ran.
+            queueMicrotask(() => {
+                if (!settled && rejectFn) {
+                    rejectFn(error);
+                }
+            });
+        };
+        return { promise, cancel };
+    }
+}
+function resolveAgentConfig(options) {
+    const { config, provider, cwd, agentId: _agentId, onEvent: _onEvent, idempotencyKey: _idempotencyKey, clientMessageId: _clientMessageId, callerAgentId: _callerAgentId, outputSchema: _outputSchema, attachments: _attachments, worktree: _worktree, autoArchive: _autoArchive, env: _env, workspaceId: _workspaceId, initialPrompt: _initialPrompt, images: _images, git: _git, worktreeName: _worktreeName, requestId: _requestId, labels: _labels, ...overrides } = options;
+    const baseConfig = {
+        ...(provider ? { provider } : {}),
+        ...(cwd ? { cwd } : {}),
+        ...overrides,
+    };
+    const merged = config ? { ...baseConfig, ...config } : baseConfig;
+    if (!merged.provider || !merged.cwd) {
+        throw new Error("createAgent requires provider and cwd");
+    }
+    return {
+        ...merged,
+        provider: merged.provider,
+        cwd: merged.cwd,
+    };
+}
+//# sourceMappingURL=daemon-client.js.map