@camerontaylor/paseo-client 0.12.0-fork.1 → 0.13.0-fork.2

package/dist/daemon-client.js

@@ -1,3 +1,4 @@
+import { HOST_ROUTE_OPCODE, encodeHostRouteFrame, decodeHostRouteFrame, } from "@camerontaylor/paseo-protocol/binary-frames/index";
 import { messageTooLargeError } from "./daemon-client-transport-utils.js";
 import { legacyUsageIcon } from "./legacy-usage-icons.js";
 import { subscribeTimeline } from "./timeline-subscription/index.js";
@@ -10,7 +11,7 @@ import { AgentCreateFailedStatusPayloadSchema, AgentCreatedStatusPayloadSchema,
 import { validateWSOutboundMessage } from "@camerontaylor/paseo-protocol/validation/ws-outbound";
 import { isRelayClientWebSocketUrl } from "@camerontaylor/paseo-protocol/daemon-endpoints";
 import { asUint8Array, decodeFileTransferFrame, encodeFileTransferFrame, decodeTerminalStreamFrame, FileTransferOpcode, TerminalStreamOpcode, } from "@camerontaylor/paseo-protocol/binary-frames/index";
-import { createRelayE2eeTransportFactory, createRelayTransportFactory, createWebSocketTransportFactory, decodeMessageData, defaultWebSocketFactory, describeTransportClose, describeTransportError, } from "./daemon-client-transport.js";
+import { createRelayE2eeTransportFactory, createRelayUpgradeTransportFactory, createWebSocketTransportFactory, decodeMessageData, defaultWebSocketFactory, describeEndpointSecurityClose, 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";
@@ -128,9 +129,11 @@ function normalizeListCommandsOptions(input, legacyOptions) {
     return { agentId: input, ...legacyOptions };
 }
 export class DaemonConnectionError extends Error {
-    constructor(message, code = "DAEMON_CONNECTION_LOST") {
-        super(message);
+    constructor(message, code = "DAEMON_CONNECTION_LOST", context) {
+        super(message, context?.cause ? { cause: context.cause } : undefined);
         this.code = code;
+        this.serverId = context?.serverId;
+        this.outcome = context?.outcome;
         this.name = "DaemonConnectionError";
     }
 }
@@ -146,6 +149,8 @@ class DaemonRpcError extends Error {
         this.requestId = params.requestId;
         this.requestType = params.requestType;
         this.code = params.code;
+        this.serverId = params.serverId;
+        this.userMessage = params.error;
     }
 }
 class DaemonProtocolError extends Error {
@@ -261,15 +266,32 @@ function assertTransportFrameFits(frame) {
     if (size > MAX_WEBSOCKET_MESSAGE_BYTES)
         throw messageTooLargeError(size, MAX_WEBSOCKET_MESSAGE_BYTES);
 }
-function describeInboundTransportFrame(frame, rawBytes) {
+function describeInboundTransportFrame(frame) {
     if (typeof frame === "string") {
-        return { kind: "text", size: String(frame.length) };
+        return { kind: "text", size: String(frame.length), sizeUnit: "utf16-code-units" };
     }
-    if (rawBytes) {
-        return { kind: "binary", size: String(rawBytes.byteLength) };
+    if (frame instanceof ArrayBuffer || ArrayBuffer.isView(frame)) {
+        return { kind: "binary", size: String(frame.byteLength), sizeUnit: "bytes" };
     }
     return { kind: "unknown", size: "0" };
 }
+function describeRequestIdentity(value) {
+    if (!value || typeof value !== "object")
+        return {};
+    const message = "message" in value ? value.message : value;
+    if (!message || typeof message !== "object")
+        return {};
+    if ("requestId" in message && typeof message.requestId === "string")
+        return { requestId: message.requestId };
+    if ("payload" in message &&
+        message.payload &&
+        typeof message.payload === "object" &&
+        "requestId" in message.payload &&
+        typeof message.payload.requestId === "string") {
+        return { requestId: message.payload.requestId };
+    }
+    return {};
+}
 function hashForLog(value) {
     let hash = 0;
     for (let index = 0; index < value.length; index += 1) {
@@ -371,6 +393,7 @@ export class DaemonClient {
         this.connectTimeout = null;
         this.pendingGenericTransportErrorTimeout = null;
         this.reconnectAttempt = 0;
+        this.traceConnectionAttempt = 0;
         this.shouldReconnect = true;
         this.connectPromise = null;
         this.connectResolve = null;
@@ -391,11 +414,14 @@ export class DaemonClient {
         this.livenessHeartbeatTimer = null;
         this.lastLivenessRttMs = null;
         this.consecutiveLivenessFailures = 0;
+        this.hostFrameListeners = new Set();
         // ============================================================================
         // Agent Lifecycle
         // ============================================================================
         this.creations = new CreationClient({
-            supports: (feature) => this.lastServerInfoMessage?.features?.[feature] === true,
+            supports: (feature) => {
+                return this.lastServerInfoMessage?.features?.[feature] === true;
+            },
             requestId: () => this.createRequestId(),
             request: (kind, input) => kind === "workspace"
                 ? this.sendCorrelatedSessionRequest({
@@ -432,6 +458,7 @@ export class DaemonClient {
             legacyWorkspace: (input) => this.createLegacyWorkspace(input, input.requestId),
         });
         this.logger = config.logger ?? consoleLogger;
+        this.relaySecurityFloorValue = config.e2ee?.minimumMode;
         this.logConnectionPath = isRelayClientWebSocketUrl(this.config.url) ? "relay" : "direct";
         let parsedUrlForLog = null;
         try {
@@ -521,13 +548,14 @@ export class DaemonClient {
             const baseTransportFactory = this.config.transportFactory ??
                 createWebSocketTransportFactory(this.config.webSocketFactory ?? defaultWebSocketFactory);
             const isRelayTransport = isRelayClientWebSocketUrl(this.config.url);
-            const shouldUseRelayE2ee = this.config.e2ee?.enabled === true && isRelayTransport;
             this.assertEncryptedRelayAuth(selected.helloAuth, isRelayTransport);
+            // Relay upgrades are routing only: credentials never reach the relay socket.
             let transportFactory = isRelayTransport
-                ? createRelayTransportFactory(baseTransportFactory)
+                ? createRelayUpgradeTransportFactory(baseTransportFactory)
                 : baseTransportFactory;
-            if (shouldUseRelayE2ee) {
-                const daemonPublicKeyB64 = this.config.e2ee?.daemonPublicKeyB64;
+            // Endpoint security is selected by configuration, never inferred from the URL.
+            if (this.config.e2ee?.enabled === true) {
+                const daemonPublicKeyB64 = this.config.e2ee.daemonPublicKeyB64;
                 if (!daemonPublicKeyB64) {
                     throw new Error("daemonPublicKeyB64 is required for relay E2EE");
                 }
@@ -535,6 +563,12 @@ export class DaemonClient {
                     baseFactory: transportFactory,
                     daemonPublicKeyB64,
                     logger: this.logger,
+                    ...(this.relaySecurityFloorValue ? { minimumMode: this.relaySecurityFloorValue } : {}),
+                    onSecurityMode: (mode) => {
+                        if (mode === "protected")
+                            this.relaySecurityFloorValue = "protected";
+                        this.config.e2ee?.onSecurityMode?.(mode);
+                    },
                 });
             }
             const transportUrl = this.resolveTransportUrlForAttempt();
@@ -543,6 +577,7 @@ export class DaemonClient {
                 headers: selected.headers,
                 ...(selected.protocols ? { protocols: selected.protocols } : {}),
             });
+            this.traceConnectionAttempt += 1;
             this.transport = transport;
             this.lastServerInfoMessage = null;
             this.authFailureReasonValue = null;
@@ -566,6 +601,7 @@ export class DaemonClient {
             }, timeoutMs);
             this.transportCleanup = [
                 transport.onOpen(() => {
+                    this.traceInstant("paseo.connection.open");
                     if (this.pendingGenericTransportErrorTimeout) {
                         clearTimeout(this.pendingGenericTransportErrorTimeout);
                         this.pendingGenericTransportErrorTimeout = null;
@@ -574,25 +610,34 @@ export class DaemonClient {
                     void this.sendHelloMessage();
                 }),
                 transport.onClose((event) => {
+                    this.traceInstant("paseo.connection.close", {
+                        code: String(event && typeof event === "object" && "code" in event ? event.code : "unknown"),
+                    });
                     this.resetConnectTimeout();
                     if (this.pendingGenericTransportErrorTimeout) {
                         clearTimeout(this.pendingGenericTransportErrorTimeout);
                         this.pendingGenericTransportErrorTimeout = null;
                     }
                     this.authFailureReasonValue ?? (this.authFailureReasonValue = authFailureFromLegacyClose(event));
+                    // An endpoint security policy close cannot be fixed by retrying.
+                    const securityFailure = describeEndpointSecurityClose(event);
+                    if (securityFailure)
+                        this.setReconnectEnabled(false);
                     const reason = this.authFailureReasonValue
                         ? new DaemonAuthenticationError(this.authFailureReasonValue).message
-                        : describeTransportClose(event);
+                        : (securityFailure ?? describeTransportClose(event));
                     if (reason) {
                         this.lastErrorValue = reason;
                     }
                     this.scheduleReconnect({
                         reason,
+                        failure: event instanceof Error ? event : undefined,
                         event: "TRANSPORT_CLOSE",
                         reasonCode: "transport_closed",
                     });
                 }),
                 transport.onError((event) => {
+                    this.traceInstant("paseo.connection.error");
                     this.resetConnectTimeout();
                     const reason = describeTransportError(event);
                     const isGeneric = reason === "Transport error";
@@ -609,6 +654,7 @@ export class DaemonClient {
                                     this.lastErrorValue = reason;
                                     this.scheduleReconnect({
                                         reason,
+                                        failure: event instanceof Error ? event : undefined,
                                         event: "TRANSPORT_ERROR",
                                         reasonCode: "transport_error",
                                     });
@@ -624,6 +670,7 @@ export class DaemonClient {
                     this.lastErrorValue = reason;
                     this.scheduleReconnect({
                         reason,
+                        failure: event instanceof Error ? event : undefined,
                         event: "TRANSPORT_ERROR",
                         reasonCode: "transport_error",
                     });
@@ -673,9 +720,7 @@ export class DaemonClient {
             return;
         }
         this.shouldReconnect = false;
-        this.connectPromise = null;
-        this.connectResolve = null;
-        this.connectReject = null;
+        this.rejectConnect(new Error("Daemon client closed"));
         if (this.reconnectTimeout) {
             clearTimeout(this.reconnectTimeout);
             this.reconnectTimeout = null;
@@ -716,7 +761,7 @@ export class DaemonClient {
             this.attemptConnect();
             return;
         }
-        void this.connect();
+        void this.connect().catch((error) => this.logger.debug({ err: error }, "Connection attempt ended"));
     }
     verifyConnection() {
         const transport = this.transport;
@@ -742,6 +787,111 @@ export class DaemonClient {
                 this.connectionVerification = null;
         });
     }
+    requireConnectedHosts() {
+        if (!this.isConnected)
+            throw Object.assign(new Error("The managing daemon is offline"), {
+                code: "host_offline",
+                serverId: this.destinationServerId,
+            });
+        if (this.lastServerInfoMessage?.features?.connectedHosts !== true)
+            throw Object.assign(new Error("Update the managing daemon to use connected hosts"), {
+                code: "unsupported_capability",
+            });
+    }
+    async listHosts() {
+        this.requireConnectedHosts();
+        return (await this.sendCorrelatedSessionRequest({
+            message: { type: "hosts.list.request" },
+            responseType: "hosts.list.response",
+        })).directory;
+    }
+    observeHosts() {
+        this.requireConnectedHosts();
+        return this.owned.observe(async (accept) => {
+            const result = await this.sendCorrelatedSessionRequest({
+                message: { type: "hosts.list.request", observe: true },
+                responseType: "hosts.list.response",
+            });
+            if (!result.subscriptionId)
+                throw new Error("Host omitted subscription identity");
+            const snapshot = { ...result.directory, subscriptionId: result.subscriptionId };
+            accept(snapshot);
+            return snapshot;
+        });
+    }
+    async addHost(input) {
+        this.requireConnectedHosts();
+        return (await this.sendCorrelatedSessionRequest({
+            message: { type: "hosts.add.request", input },
+            responseType: "hosts.add.response",
+        })).host;
+    }
+    async updateHost(registrationId, patch) {
+        this.requireConnectedHosts();
+        return (await this.sendCorrelatedSessionRequest({
+            message: { type: "hosts.update.request", registrationId, patch },
+            responseType: "hosts.update.response",
+        })).host;
+    }
+    async removeHost(registrationId) {
+        this.requireConnectedHosts();
+        await this.sendCorrelatedSessionRequest({
+            message: { type: "hosts.remove.request", registrationId },
+            responseType: "hosts.remove.response",
+        });
+    }
+    async openHostRoute(serverId, scopeId) {
+        this.requireConnectedHosts();
+        try {
+            return (await this.sendCorrelatedSessionRequest({
+                message: { type: "hosts.route.open.request", serverId, scopeId },
+                responseType: "hosts.route.open.response",
+            })).routeId;
+        }
+        catch (error) {
+            throw Object.assign(error instanceof Error ? error : new Error("Host route failed"), {
+                serverId,
+            });
+        }
+    }
+    async openHostLink(channelId) {
+        this.requireConnectedHosts();
+        if (this.getLastServerInfoMessage()?.features?.hostMultiplexing !== true)
+            throw Object.assign(new Error("Update the destination daemon"), {
+                code: "unsupported_capability",
+            });
+        return (await this.sendCorrelatedSessionRequest({
+            message: { type: "hosts.link.open.request", channelId },
+            responseType: "hosts.link.open.response",
+        })).routeId;
+    }
+    sendHostFrame(routeId, data) {
+        if (typeof data === "string") {
+            this.sendSessionMessageStrict({
+                type: "hosts.route.frame.request",
+                routeId,
+                data,
+                binary: false,
+            });
+        }
+        else {
+            if (!this.isConnected || !this.transport)
+                throw this.unavailableError();
+            this.sendTransportFrame(encodeHostRouteFrame(routeId, data));
+        }
+    }
+    subscribeHostFrames(handler) {
+        this.hostFrameListeners.add(handler);
+        return () => this.hostFrameListeners.delete(handler);
+    }
+    cancelHostRoute(scopeId) {
+        if (this.isConnected && this.transport)
+            this.sendSessionMessageStrict({ type: "hosts.route.close.request", scopeId });
+    }
+    closeHostRoute(routeId) {
+        if (this.isConnected && this.transport)
+            this.sendSessionMessageStrict({ type: "hosts.route.close.request", routeId });
+    }
     getConnectionState() {
         return this.connectionState;
     }
@@ -758,6 +908,10 @@ export class DaemonClient {
     get isConnecting() {
         return this.connectionState.status === "connecting";
     }
+    /** The relay endpoint security this client requires on its next attempt. */
+    get relaySecurityFloor() {
+        return this.relaySecurityFloorValue;
+    }
     get lastError() {
         return this.lastErrorValue;
     }
@@ -833,7 +987,7 @@ export class DaemonClient {
         if (!trace?.isEnabled()) {
             return false;
         }
-        trace.beginSection(name, args);
+        trace.beginSection(name, { ...args, connectionAttempt: String(this.traceConnectionAttempt) });
         return true;
     }
     endTraceSection(isOpen) {
@@ -845,24 +999,50 @@ export class DaemonClient {
         const isOpen = this.beginTraceSection(name, args);
         this.endTraceSection(isOpen);
     }
-    sendJsonMessage(envelopeType, messageType, message) {
-        this.traceInstant("paseo.ws.message.outbound", {
-            envelopeType,
-            messageType,
+    beginSessionDispatchTrace(message) {
+        if (!this.config.trace?.isEnabled())
+            return false;
+        const fields = { messageType: message.type, ...describeRequestIdentity(message) };
+        this.traceInstant("paseo.ws.message.inbound", { envelopeType: "session", ...fields });
+        return this.beginTraceSection("paseo.ws.dispatch", fields);
+    }
+    sendJsonMessage(envelopeType, messageType, message, submitted) {
+        const isOpen = this.config.trace?.isEnabled() === true &&
+            this.beginTraceSection("paseo.ws.message.outbound", {
+                envelopeType,
+                messageType,
+                ...describeRequestIdentity(message),
+            });
+        try {
+            this.sendTransportFrame(JSON.stringify(message), submitted);
+        }
+        finally {
+            this.endTraceSection(isOpen);
+        }
+    }
+    sendSessionPayload(payload) {
+        this.sendJsonMessage("session", payload.type, { type: "session", message: payload }, () => {
+            if (!("requestId" in payload) || typeof payload.requestId !== "string")
+                return;
+            for (const waiter of this.waiters) {
+                if (waiter.requestId === payload.requestId)
+                    waiter.submitted = true;
+            }
         });
-        this.sendTransportFrame(JSON.stringify(message));
     }
-    sendTransportFrame(frame) {
+    sendTransportFrame(frame, submitted) {
         if (!this.transport) {
-            throw new DaemonConnectionError("Transport not connected");
+            throw this.unavailableError();
         }
         // The daemon closes the connection on an oversized message, and creations resubmit on reconnect.
         assertTransportFrameFits(frame);
         const isOpen = this.beginTraceSection("paseo.ws.frame.outbound", {
             kind: typeof frame === "string" ? "text" : "binary",
             size: String(getTransportFrameSize(frame)),
+            sizeUnit: typeof frame === "string" ? "utf16-code-units" : "bytes",
         });
         try {
+            submitted?.();
             this.transport.send(frame);
         }
         finally {
@@ -883,7 +1063,7 @@ export class DaemonClient {
         }
         const payload = SessionInboundMessageSchema.parse(message);
         try {
-            this.sendJsonMessage("session", payload.type, { type: "session", message: payload });
+            this.sendSessionPayload(payload);
         }
         catch (error) {
             if (this.config.suppressSendErrors) {
@@ -922,7 +1102,7 @@ export class DaemonClient {
     sendSessionMessageOrThrow(message) {
         return this.sendWhenConnected(() => {
             const payload = SessionInboundMessageSchema.parse(message);
-            this.sendJsonMessage("session", payload.type, { type: "session", message: payload });
+            this.sendSessionPayload(payload);
         });
     }
     /** Resolves once connected, waiting out a connection that is still being established. */
@@ -951,7 +1131,7 @@ export class DaemonClient {
             });
         }
         // Not connected and not connecting - fail immediately
-        return Promise.reject(new DaemonConnectionError(`Transport not connected (status: ${status})`));
+        return Promise.reject(this.unavailableError());
     }
     /**
      * Flush pending send queue - called when connection is established.
@@ -995,6 +1175,7 @@ export class DaemonClient {
                     kind: "error",
                     error: new DaemonRpcError({
                         requestId: msg.payload.requestId,
+                        serverId: this.destinationServerId,
                         error: msg.payload.error,
                         requestType: msg.payload.requestType,
                         code: msg.payload.code,
@@ -1070,13 +1251,19 @@ export class DaemonClient {
             responseType,
         });
     }
+    unavailableError() {
+        return new DaemonConnectionError("Transport not connected", "DAEMON_CONNECTION_LOST", {
+            serverId: this.destinationServerId,
+            cause: this.connectionFailure,
+        });
+    }
     sendSessionMessageStrict(message) {
         if (!this.transport || this.connectionState.status !== "connected") {
-            throw new DaemonConnectionError("Transport not connected");
+            throw this.unavailableError();
         }
         const payload = SessionInboundMessageSchema.parse(message);
         try {
-            this.sendJsonMessage("session", payload.type, { type: "session", message: payload });
+            this.sendSessionPayload(payload);
         }
         catch (error) {
             throw error instanceof Error ? error : new Error(String(error));
@@ -1290,6 +1477,8 @@ export class DaemonClient {
         let resetSource = false;
         return this.owned.observeRequest(message, async (query, accept) => {
             resetSource = false;
+            if (query.type === "workspace.setup.subscribe.request")
+                this.requireWorkspaceSetupObservation();
             const requestId = this.createRequestId(options?.requestId);
             const prepared = options?.prepare ? options.prepare({ ...query }) : query;
             const request = SessionInboundMessageSchema.parse({ ...prepared, requestId });
@@ -1636,6 +1825,16 @@ export class DaemonClient {
             responseType: "archive_workspace_response",
         });
     }
+    observeWorkspaceSetup(workspaceId, options) {
+        return this.observe("workspace.setup.subscribe.response", { type: "workspace.setup.subscribe.request", workspaceId }, options);
+    }
+    requireWorkspaceSetupObservation() {
+        if (this.lastServerInfoMessage?.features?.workspaceSetupObservation !== true ||
+            this.lastServerInfoMessage.features.ownedSubscriptions !== true ||
+            this.config.capabilities?.[CLIENT_CAPS.workspaceSetupObservation] === false ||
+            this.config.capabilities?.[CLIENT_CAPS.ownedSubscriptions] === false)
+            throw new Error("Update the host to view workspace setup details");
+    }
     async fetchWorkspaceSetupStatus(workspaceId, requestId) {
         return this.sendCorrelatedSessionRequest({
             requestId,
@@ -1693,6 +1892,9 @@ export class DaemonClient {
         return this.lastServerInfoMessage?.features?.backgroundWorkspaces === true;
     }
     async createAgent(options) {
+        if (options.git !== undefined || options.worktreeName !== undefined) {
+            throw new Error("Legacy git/worktreeName agent placement was removed. Use createWorkspace({ source, agent, idempotencyKey }) or create a workspace first and pass workspaceId.");
+        }
         if (options.background !== undefined)
             this.requireBackgroundWorkspaces();
         const result = await this.creations.createAgent({
@@ -2280,23 +2482,29 @@ export class DaemonClient {
     // ============================================================================
     // Agent Interaction
     // ============================================================================
-    async sendAgentMessage(agentId, text, options) {
-        if (options?.sourceAgentId &&
+    async sendAgentMessage(agentId, text, options = {}) {
+        if (options.sourceAgentId &&
             this.lastServerInfoMessage?.features?.agentMessageProvenance !== true) {
             throw new Error("Update the Paseo host to send messages with agent provenance.");
         }
+        if (options.sourceAgentServerId &&
+            this.lastServerInfoMessage?.features?.agentMessageBatching !== true) {
+            throw new Error("Update the Paseo host to send messages with a qualified agent address.");
+        }
         const requestId = this.createRequestId();
-        const messageId = options?.messageId ?? crypto.randomUUID();
+        const messageId = options.messageId ?? crypto.randomUUID();
         const message = SessionInboundMessageSchema.parse({
             type: "send_agent_message_request",
             requestId,
             agentId,
             text,
-            sourceAgentId: options?.sourceAgentId,
+            sourceAgentId: options.sourceAgentId,
+            sourceAgentServerId: options.sourceAgentServerId,
+            sessionMode: options.sessionMode,
             ...(messageId ? { messageId } : {}),
-            ...(options?.activeTurnBehavior ? { activeTurnBehavior: options.activeTurnBehavior } : {}),
-            ...(options?.images ? { images: options.images } : {}),
-            ...(options?.attachments ? { attachments: options.attachments } : {}),
+            activeTurnBehavior: options.activeTurnBehavior,
+            images: options.images,
+            attachments: options.attachments,
         });
         const payload = await this.sendRequest({
             requestId,
@@ -2315,9 +2523,10 @@ export class DaemonClient {
         if (!payload.accepted) {
             throw new Error(payload.error ?? "sendAgentMessage rejected");
         }
+        return payload.deliveryStatus ? { deliveryStatus: payload.deliveryStatus } : {};
     }
     async sendMessage(agentId, text, options) {
-        await this.sendAgentMessage(agentId, text, options);
+        return this.sendAgentMessage(agentId, text, options);
     }
     // ==========================================================================
     // Durable agent message queue — see docs/queue-mirroring.md.
@@ -2958,12 +3167,12 @@ export class DaemonClient {
         const trimmedBaseRef = compare.baseRef?.trim();
         if (!trimmedBaseRef) {
             return compare.ignoreWhitespace === true
-                ? { mode: "base", ignoreWhitespace: true }
-                : { mode: "base" };
+                ? { mode: compare.mode, ignoreWhitespace: true }
+                : { mode: compare.mode };
         }
         return compare.ignoreWhitespace === true
-            ? { mode: "base", baseRef: trimmedBaseRef, ignoreWhitespace: true }
-            : { mode: "base", baseRef: trimmedBaseRef };
+            ? { mode: compare.mode, baseRef: trimmedBaseRef, ignoreWhitespace: true }
+            : { mode: compare.mode, baseRef: trimmedBaseRef };
     }
     async getCheckoutDiff(cwd, compare, requestId) {
         return this.sendCorrelatedSessionRequest({
@@ -4629,6 +4838,9 @@ export class DaemonClient {
             const auth = this.helloAuth;
             this.sendJsonMessage("hello", "hello", {
                 type: "hello",
+                ...(this.config.sessionPermissions
+                    ? { sessionPermissions: this.config.sessionPermissions }
+                    : {}),
                 clientId: this.config.clientId,
                 clientType: this.config.clientType ?? "cli",
                 protocolVersion: 1,
@@ -4708,9 +4920,10 @@ export class DaemonClient {
             });
             return;
         }
-        const rawBytes = asUint8Array(rawData);
-        const isOpen = this.beginTraceSection("paseo.ws.frame.inbound", describeInboundTransportFrame(rawData, rawBytes));
+        const isOpen = this.beginTraceSection("paseo.ws.frame.inbound", describeInboundTransportFrame(rawData));
         try {
+            // Record arrival before conversion: encoding a large text frame is JS work too.
+            const rawBytes = asUint8Array(rawData);
             if (rawBytes && this.tryHandleBinaryFrame(rawBytes)) {
                 return;
             }
@@ -4730,18 +4943,28 @@ export class DaemonClient {
         let parsedJson;
         const parseTraceOpen = this.beginTraceSection("paseo.ws.json.parse", {
             size: String(bytes),
+            sizeUnit: rawBytesLength === undefined ? "utf16-code-units" : "bytes",
         });
         try {
             parsedJson = JSON.parse(payload);
         }
         catch {
+            this.traceInstant("paseo.ws.json.invalid");
             return;
         }
         finally {
             this.endTraceSection(parseTraceOpen);
         }
-        const parsed = validateWSOutboundMessage(parsedJson);
+        const validationTrace = this.beginTraceSection("paseo.ws.validate");
+        let parsed;
+        try {
+            parsed = validateWSOutboundMessage(parsedJson);
+        }
+        finally {
+            this.endTraceSection(validationTrace);
+        }
         if (!parsed.success) {
+            this.traceInstant("paseo.ws.validation.failed");
             const responseIdentity = extractCorrelatedResponseIdentity(parsedJson);
             const envelopeType = parsedJson != null &&
                 typeof parsedJson === "object" &&
@@ -4767,6 +4990,7 @@ export class DaemonClient {
             return;
         }
         if (parsed.data.type === "hello.rejected") {
+            this.traceInstant("paseo.connection.rejected", { reason: parsed.data.reason });
             const reasonMessage = {
                 password_required: "Password required",
                 incorrect_password: "Incorrect password",
@@ -4777,11 +5001,13 @@ export class DaemonClient {
                 parsed.data.reason === "incompatible_protocol" ? null : parsed.data.reason;
             return;
         }
-        this.traceInstant("paseo.ws.message.inbound", {
-            envelopeType: "session",
-            messageType: parsed.data.message.type,
-        });
-        this.handleSessionMessage(parsed.data.message);
+        const dispatchTrace = this.beginSessionDispatchTrace(parsed.data.message);
+        try {
+            this.handleSessionMessage(parsed.data.message);
+        }
+        finally {
+            this.endTraceSection(dispatchTrace);
+        }
         const msgType = parsed.data.message.type;
         this.runtimeMetrics?.recordMessage(msgType, bytes, perfNow() - startMs);
         if (parsed.data.message.type === "agent_stream") {
@@ -4789,12 +5015,24 @@ export class DaemonClient {
         }
     }
     tryHandleBinaryFrame(rawBytes) {
+        const hostFrame = decodeHostRouteFrame(rawBytes);
+        if (rawBytes[0] === HOST_ROUTE_OPCODE && !hostFrame) {
+            this.disposeTransport(1008, "Invalid host routing frame");
+            this.scheduleReconnect({ reason: "Invalid host routing frame", event: "INVALID_HOST_FRAME" });
+            return true;
+        }
+        if (hostFrame) {
+            for (const handler of this.hostFrameListeners)
+                handler(hostFrame);
+            return true;
+        }
         const fileFrame = decodeFileTransferFrame(rawBytes);
         if (fileFrame) {
             this.traceInstant("paseo.ws.message.inbound", {
                 envelopeType: "binary",
                 messageType: "file",
                 opcode: String(fileFrame.opcode),
+                requestId: fileFrame.requestId,
             });
             this.consecutiveLivenessFailures = 0;
             this.handleFileTransferFrame(fileFrame);
@@ -4809,6 +5047,7 @@ export class DaemonClient {
             envelopeType: "binary",
             messageType: "terminal",
             opcode: String(frame.opcode),
+            slot: String(frame.slot),
         });
         this.consecutiveLivenessFailures = 0;
         const binaryStartMs = perfNow();
@@ -4909,6 +5148,12 @@ export class DaemonClient {
         const reasonFromNext = next.status === "disconnected" && typeof next.reason === "string" ? next.reason : null;
         const reason = metadata?.reason ?? reasonFromNext;
         const reasonCode = metadata?.reasonCode ?? toReasonCode(reason);
+        this.traceInstant("paseo.connection.state", {
+            from: previous.status,
+            to: next.status,
+            event: metadata?.event ?? "STATE_UPDATE",
+            reasonCode: reasonCode ?? "none",
+        });
         this.logger.debug({
             serverId: this.logServerId,
             clientIdHash: this.logClientIdHash,
@@ -4950,9 +5195,14 @@ export class DaemonClient {
         this.providerSnapshotUpdates.clear();
         // Clear all pending waiters and queued sends since the connection was lost
         // and responses from the previous connection will never arrive.
-        this.clearWaiters(new DaemonConnectionError(reason ?? "Connection lost"));
-        this.rejectPendingSendQueue(new DaemonConnectionError(reason ?? "Connection lost"));
-        this.rejectPingProbe(new DaemonConnectionError(reason ?? "Connection lost"));
+        const connectionError = new DaemonConnectionError(reason ?? "Connection lost", "DAEMON_CONNECTION_LOST", {
+            serverId: this.destinationServerId,
+            cause: input?.failure,
+        });
+        this.connectionFailure = input?.failure;
+        this.clearWaiters(connectionError, true);
+        this.rejectPendingSendQueue(connectionError);
+        this.rejectPingProbe(connectionError);
         this.terminalStreams.clearSlots();
         this.lastServerInfoMessage = null;
         if (this.authFailureReasonValue)
@@ -4965,7 +5215,7 @@ export class DaemonClient {
         if (!this.shouldReconnect || this.config.reconnect?.enabled === false) {
             this.rejectConnect(this.authFailureReasonValue
                 ? new DaemonAuthenticationError(this.authFailureReasonValue)
-                : new Error(reason ?? "Transport disconnected before connect"));
+                : (input?.failure ?? new Error(reason ?? "Transport disconnected before connect")));
             return;
         }
         this.armReconnectTimer();
@@ -4973,6 +5223,16 @@ export class DaemonClient {
     emitDisconnectedStateForReconnect(reason, input) {
         this.updateConnectionState({
             status: "disconnected",
+            ...(input?.failure && "code" in input.failure && typeof input.failure.code === "string"
+                ? { failureCode: input.failure.code }
+                : {}),
+            ...(this.shouldReconnect && this.config.reconnect?.enabled !== false
+                ? {
+                    nextRetryAt: new Date(Date.now() +
+                        Math.min((this.config.reconnect?.baseDelayMs ?? DEFAULT_RECONNECT_BASE_DELAY_MS) *
+                            2 ** this.reconnectAttempt, this.config.reconnect?.maxDelayMs ?? DEFAULT_RECONNECT_MAX_DELAY_MS)).toISOString(),
+                }
+                : {}),
             ...(reason ? { reason } : {}),
         }, {
             event: input?.event ?? "TRANSPORT_CLOSE",
@@ -4985,6 +5245,10 @@ export class DaemonClient {
         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.traceInstant("paseo.connection.reconnect", {
+            attempt: String(attempt),
+            delayMs: String(delay),
+        });
         this.reconnectAttempt = attempt + 1;
         this.reconnectTimeout = setTimeout(() => {
             this.reconnectTimeout = null;
@@ -5052,6 +5316,8 @@ export class DaemonClient {
             const serverInfo = parseServerInfoStatusPayload(consumerMessage.payload);
             if (serverInfo) {
                 this.lastServerInfoMessage = serverInfo;
+                this.destinationServerId = serverInfo.serverId;
+                this.connectionFailure = undefined;
                 if (this.connectionState.status === "connecting") {
                     this.resetConnectTimeout();
                     this.reconnectAttempt = 0;
@@ -5133,12 +5399,18 @@ export class DaemonClient {
             waiter.reject(error);
         }
     }
-    clearWaiters(error) {
+    clearWaiters(error, connectionLost = false) {
         for (const waiter of Array.from(this.waiters)) {
             if (waiter.timeoutHandle) {
                 clearTimeout(waiter.timeoutHandle);
             }
-            waiter.reject(error);
+            waiter.reject(connectionLost && waiter.submitted && error instanceof DaemonConnectionError
+                ? new DaemonConnectionError(error.message, error.code, {
+                    serverId: error.serverId,
+                    outcome: "unknown",
+                    cause: error.cause instanceof Error ? error.cause : undefined,
+                })
+                : error);
         }
         this.waiters.clear();
     }
@@ -5233,6 +5505,7 @@ export class DaemonClient {
                 reject: wrappedReject,
                 timeoutHandle,
                 requestId: options?.requestId,
+                submitted: false,
             };
             this.waiters.add(waiter);
         });