@camerontaylor/paseo-client 0.8.0-fork.1 → 0.9.0-beta.2.fork.1

package/dist/daemon-client.js

@@ -1,12 +1,11 @@
+import { subscribeTimeline } from "./timeline-subscription/index.js";
 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";
@@ -76,6 +75,13 @@ function normalizeListCommandsOptions(input, legacyOptions) {
     }
     return { agentId: input, ...legacyOptions };
 }
+export class DaemonConnectionError extends Error {
+    constructor(message, code = "DAEMON_CONNECTION_LOST") {
+        super(message);
+        this.code = code;
+        this.name = "DaemonConnectionError";
+    }
+}
 class DaemonRpcError extends Error {
     constructor(params) {
         const parts = [params.error];
@@ -232,14 +238,29 @@ export class DaemonClient {
     constructor(config) {
         this.config = config;
         this.providerSnapshotUpdates = new ProviderSnapshotUpdates({
+            active: (message) => this.owned.owns(message),
             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.owned = new ConnectionSubscriptions({
+            send: (message) => this.sendSessionMessageOrThrow(SessionInboundMessageSchema.parse({ ...message, requestId: this.createRequestId() })),
+            release: async (subscriptionId) => {
+                if (!this.isConnected)
+                    return;
+                try {
+                    await this.sendCorrelatedSessionRequest({
+                        message: { type: "subscription.release.request", subscriptionId },
+                        responseType: "subscription.release.response",
+                    });
+                }
+                catch (error) {
+                    this.disposeTransport(1001, "Subscription release failed");
+                    this.scheduleReconnect({ reason: "Subscription release failed" });
+                    throw error;
+                }
+            },
+            failed: (error) => this.logger.error({ err: error }, "Subscription failed"),
         });
         this.transport = null;
         this.transportCleanup = [];
@@ -259,9 +280,6 @@ export class DaemonClient {
         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();
@@ -271,6 +289,7 @@ export class DaemonClient {
         this.runtimeMetricsInterval = null;
         this.runtimeMetrics = null;
         this.pingProbe = null;
+        this.connectionVerification = null;
         this.livenessHeartbeatTimer = null;
         this.lastLivenessRttMs = null;
         this.consecutiveLivenessFailures = 0;
@@ -278,8 +297,7 @@ export class DaemonClient {
         // Agent Lifecycle
         // ============================================================================
         this.creations = new CreationClient({
-            supports: () => this.lastServerInfoMessage?.features?.creationLifecycle === true,
-            connected: () => this.connectionState.status === "connected",
+            supports: (feature) => this.lastServerInfoMessage?.features?.[feature] === true,
             requestId: () => this.createRequestId(),
             request: (kind, input) => kind === "workspace"
                 ? this.sendCorrelatedSessionRequest({
@@ -294,18 +312,26 @@ export class DaemonClient {
                     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",
+            observe: (kind, idempotencyKey, next, error) => {
+                const observation = this.observe("creation.subscribe.response", {
+                    type: "creation.subscribe.request",
+                    kind,
+                    idempotencyKey,
                 });
-                if (result.error)
-                    throw new Error(result.error);
-                return result.snapshot;
+                observation.subscribe({
+                    snapshot: (result) => next(result.snapshot),
+                    update: (message) => {
+                        if (message.type === "workspace.create.update" || message.type === "agent.create.update")
+                            next(message.payload);
+                    },
+                    error,
+                });
+                return () => {
+                    void observation.release().catch(error);
+                };
             },
             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";
@@ -379,6 +405,12 @@ export class DaemonClient {
         if (this.connectionState.status === "connecting") {
             return;
         }
+        // This attempt supersedes any retry the last disconnect scheduled. Left
+        // armed, that retry would tear down the connection this attempt opens.
+        if (this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+            this.reconnectTimeout = null;
+        }
         const headers = {};
         const password = normalizePassword(this.config.password);
         if (password) {
@@ -494,7 +526,10 @@ export class DaemonClient {
                         reasonCode: "transport_error",
                     });
                 }),
-                transport.onMessage((data) => this.handleTransportMessage(data)),
+                transport.onMessage((data) => {
+                    if (this.transport === transport)
+                        this.handleTransportMessage(data);
+                }),
             ];
         }
         catch (error) {
@@ -530,7 +565,6 @@ export class DaemonClient {
             return;
         }
         this.shouldReconnect = false;
-        this.subscriptions.close();
         this.connectPromise = null;
         this.connectResolve = null;
         this.connectReject = null;
@@ -542,11 +576,11 @@ export class DaemonClient {
         this.disposeTransport(1000, "Client closed");
         this.providerSnapshotUpdates.clear();
         this.clearWaiters(new Error("Daemon client closed"));
+        await this.owned.close();
         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);
@@ -556,27 +590,50 @@ export class DaemonClient {
         }
         this.updateConnectionState({ status: "disposed" }, { event: "DISPOSE", reason: "Client closed", reasonCode: "disposed" });
     }
-    ensureConnected() {
+    ensureConnected(options) {
         if (this.connectionState.status === "disposed") {
             return;
         }
         if (!this.shouldReconnect) {
             this.shouldReconnect = true;
         }
-        if (this.connectionState.status === "connected" ||
-            this.connectionState.status === "connecting") {
+        if (this.connectionState.status === "connected") {
+            if (options?.verify)
+                this.verifyConnection();
             return;
         }
-        if (this.reconnectTimeout) {
-            clearTimeout(this.reconnectTimeout);
-            this.reconnectTimeout = null;
-        }
+        if (this.connectionState.status === "connecting")
+            return;
         if (this.connectPromise) {
             this.attemptConnect();
             return;
         }
         void this.connect();
     }
+    verifyConnection() {
+        const transport = this.transport;
+        if (!transport || this.connectionVerification === transport)
+            return;
+        this.connectionVerification = transport;
+        // A session probe has its own deadline, independent of a heartbeat that the OS
+        // may have suspended. A successful response also proves the session can serve RPCs.
+        void this.ping({ timeoutMs: 3000 })
+            .catch((error) => {
+            if (this.transport !== transport || this.connectionState.status !== "connected")
+                return;
+            this.disposeTransport(1001, "Connection verification failed");
+            this.scheduleReconnect({
+                reason: error instanceof Error ? error.message : String(error),
+                event: "CONNECTION_VERIFICATION_FAILED",
+                reasonCode: "liveness_timeout",
+            });
+            this.ensureConnected();
+        })
+            .finally(() => {
+            if (this.connectionVerification === transport)
+                this.connectionVerification = null;
+        });
+    }
     getConnectionState() {
         return this.connectionState;
     }
@@ -604,10 +661,8 @@ export class DaemonClient {
     // ============================================================================
     subscribe(handler) {
         this.eventListeners.add(handler);
-        this.updateEventSubscriptions();
         return () => {
             this.eventListeners.delete(handler);
-            this.updateEventSubscriptions();
         };
     }
     subscribeRawMessages(handler) {
@@ -626,7 +681,6 @@ export class DaemonClient {
             this.messageHandlers.set(type, new Set());
         }
         this.messageHandlers.get(type).add(handler);
-        this.updateEventSubscriptions();
         return () => {
             const handlers = this.messageHandlers.get(type);
             if (!handlers) {
@@ -636,7 +690,6 @@ export class DaemonClient {
             if (handlers.size === 0) {
                 this.messageHandlers.delete(type);
             }
-            this.updateEventSubscriptions();
         };
     }
     onAgentAttentionRequired(handler) {
@@ -690,7 +743,7 @@ export class DaemonClient {
     }
     sendTransportFrame(frame) {
         if (!this.transport) {
-            throw new Error("Transport not connected");
+            throw new DaemonConnectionError("Transport not connected");
         }
         const isOpen = this.beginTraceSection("paseo.ws.frame.outbound", {
             kind: typeof frame === "string" ? "text" : "binary",
@@ -770,13 +823,13 @@ export class DaemonClient {
                     if (idx !== -1) {
                         this.pendingSendQueue.splice(idx, 1);
                     }
-                    reject(new Error(`Timed out waiting for connection to send message`));
+                    reject(new DaemonConnectionError("Timed out waiting for connection to send message", "DAEMON_REQUEST_TIMEOUT"));
                 }, 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})`));
+        return Promise.reject(new DaemonConnectionError(`Transport not connected (status: ${status})`));
     }
     /**
      * Flush pending send queue - called when connection is established.
@@ -793,7 +846,7 @@ export class DaemonClient {
                     pending.resolve();
                 }
                 else {
-                    pending.reject(new Error("Connection lost before message could be sent"));
+                    pending.reject(new DaemonConnectionError("Connection lost before message could be sent"));
                 }
             }
             catch (error) {
@@ -813,6 +866,7 @@ export class DaemonClient {
         }
     }
     async sendRequest(params) {
+        const wire = this.owned.prepareRequest(params.message);
         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) {
@@ -826,14 +880,14 @@ export class DaemonClient {
                     }),
                 };
             }
-            const value = params.select(msg);
+            const value = params.select(wire.receive(msg));
             if (value === null) {
                 return null;
             }
             return { kind: "ok", value };
         }, timeout, { ...params.options, requestId: params.requestId });
         try {
-            await this.sendSessionMessageOrThrow(params.message);
+            await this.sendSessionMessageOrThrow(wire.message);
         }
         catch (error) {
             const err = error instanceof Error ? error : new Error(String(error));
@@ -841,11 +895,15 @@ export class DaemonClient {
             void promise.catch(() => undefined);
             throw err;
         }
-        const result = await promise;
-        if (result.kind === "error") {
-            throw result.error;
+        try {
+            const result = await promise;
+            if (result.kind === "error")
+                throw result.error;
+            return result.value;
+        }
+        finally {
+            await wire.finish();
         }
-        return result.value;
     }
     async sendCorrelatedRequest(params) {
         return this.sendRequest({
@@ -893,7 +951,7 @@ export class DaemonClient {
     }
     sendSessionMessageStrict(message) {
         if (!this.transport || this.connectionState.status !== "connected") {
-            throw new Error("Transport not connected");
+            throw new DaemonConnectionError("Transport not connected");
         }
         const payload = SessionInboundMessageSchema.parse(message);
         try {
@@ -1107,7 +1165,69 @@ export class DaemonClient {
     // ============================================================================
     // Agent RPCs (requestId-correlated)
     // ============================================================================
+    observe(responseType, message, options) {
+        let resetSource = false;
+        return this.owned.observeRequest(message, async (query, accept) => {
+            resetSource = false;
+            const requestId = this.createRequestId(options?.requestId);
+            const request = SessionInboundMessageSchema.parse({ ...query, requestId });
+            try {
+                return await this.sendCorrelatedRequest({
+                    message: request,
+                    responseType,
+                    requestId,
+                    timeout: options?.timeout,
+                    options: { skipQueue: true },
+                    selectPayload: (payload) => {
+                        if ("error" in payload && typeof payload.error === "string")
+                            throw new DaemonRpcError({
+                                requestId: payload.requestId,
+                                requestType: message.type,
+                                error: payload.error,
+                            });
+                        accept(payload);
+                        return payload;
+                    },
+                });
+            }
+            catch (error) {
+                resetSource = !(error instanceof DaemonRpcError) && this.isConnected;
+                throw error;
+            }
+        }, options?.signal, () => {
+            // Reject and release this handle before closing a source with an unknown bootstrap outcome.
+            // Closing first would classify the failure as a reconnect and replay the failed request.
+            if (resetSource) {
+                this.disposeTransport(1001, "Subscription request failed");
+                this.scheduleReconnect({ reason: "Subscription request failed" });
+            }
+        });
+    }
+    registerBrowserHost(registration, options) {
+        return this.observe("browser.host.register.response", { type: "browser.host.register.request", ...registration }, options);
+    }
+    observeEvents(events, options) {
+        return this.observe("session.events.set_subscription.response", {
+            type: "session.events.set_subscription.request",
+            events,
+            notifications: options?.notifications,
+        }, options);
+    }
+    observeAgents(options = {}) {
+        const { signal, requestId, timeout, ...query } = options;
+        return this.observe("fetch_agents_response", { ...query, type: "fetch_agents_request", subscribe: {} }, { signal, requestId, timeout });
+    }
+    observeWorkspaces(options = {}) {
+        const { signal, requestId, ...query } = options;
+        return this.observe("fetch_workspaces_response", { ...query, type: "fetch_workspaces_request", subscribe: {} }, { signal, requestId });
+    }
     async fetchAgents(options) {
+        if (options?.subscribe) {
+            if (options.subscribe.subscriptionId !== undefined)
+                throw new Error("Subscription IDs are assigned by the host");
+            const subscription = this.observeAgents(options);
+            return { ...(await subscription.ready), subscription };
+        }
         const resolvedRequestId = this.createRequestId(options?.requestId);
         const message = SessionInboundMessageSchema.parse({
             type: "fetch_agents_request",
@@ -1187,6 +1307,12 @@ export class DaemonClient {
         });
     }
     async fetchWorkspaces(options) {
+        if (options?.subscribe) {
+            if (options.subscribe.subscriptionId !== undefined)
+                throw new Error("Subscription IDs are assigned by the host");
+            const subscription = this.observeWorkspaces(options);
+            return { ...(await subscription.ready), subscription };
+        }
         const resolvedRequestId = this.createRequestId(options?.requestId);
         const message = SessionInboundMessageSchema.parse({
             type: "fetch_workspaces_request",
@@ -1212,16 +1338,18 @@ export class DaemonClient {
             },
         });
     }
-    listWorkspaceLabels(options) {
+    listWorkspaceLabels(options = {}) {
         return this.sendNamespacedCorrelatedSessionRequest({
             requestId: options.requestId,
             message: {
                 type: "workspace.label.list.request",
-                subscribe: { subscriptionId: options.subscriptionId },
                 ...(options.sync ? { sync: options.sync } : {}),
             },
         });
     }
+    observeWorkspaceLabels(options) {
+        return this.observe("workspace.label.list.response", { type: "workspace.label.list.request", subscribe: {} }, options);
+    }
     setWorkspaceLabel(options) {
         return this.sendNamespacedCorrelatedSessionRequest({
             requestId: options.requestId,
@@ -1422,50 +1550,6 @@ export class DaemonClient {
         }
         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,
@@ -1476,8 +1560,6 @@ export class DaemonClient {
         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({
@@ -1527,12 +1609,6 @@ export class DaemonClient {
         }
         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({
@@ -1832,6 +1908,17 @@ export class DaemonClient {
         });
         return { seq: payload.seq, epoch: payload.epoch };
     }
+    async searchAgentTimeline({ agentId, query, cursor, }) {
+        const requestId = this.createRequestId();
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "agent.timeline.search.request", requestId, agentId, query, cursor },
+            responseType: "agent.timeline.search.response",
+        });
+        if (payload.error)
+            throw new Error(payload.error);
+        return payload;
+    }
     async listAgentTimelinePrompts(agentId, options = {}) {
         const requestId = this.createRequestId(options.requestId);
         const message = SessionInboundMessageSchema.parse({
@@ -1877,6 +1964,10 @@ export class DaemonClient {
         return payload;
     }
     async fetchProviderSubagentTimeline(parentAgentId, subagentId, options = {}) {
+        // COMPAT(projectedSubagentTimeline): added after v0.8.0, remove after 2027-03-14.
+        if (this.lastServerInfoMessage?.features?.projectedSubagentTimeline !== true) {
+            throw new Error("Update the host to view subagent conversations.");
+        }
         const requestId = this.createRequestId(options.requestId);
         const message = SessionInboundMessageSchema.parse({
             type: "agent.provider_subagents.timeline.get.request",
@@ -1902,6 +1993,9 @@ export class DaemonClient {
         }
         return payload;
     }
+    observeTimeline(agentIds, options) {
+        return this.observe("agent.timeline.set_subscription.response", { type: "agent.timeline.set_subscription.request", agentIds }, options);
+    }
     async askSideConversation(parentAgentId, threadId, question, options = {}) {
         this.requireSideConversationSupport();
         const requestId = this.createRequestId(options.requestId);
@@ -1971,77 +2065,8 @@ export class DaemonClient {
             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;
-            },
-        });
+        return subscribeTimeline(agentId, this.observeTimeline([agentId]), handler, (error) => this.logger.error({ err: error }, "Timeline observation failed"));
     }
     async buildAgentForkContext(agentId, options = {}) {
         const resolvedRequestId = this.createRequestId(options.requestId);
@@ -2303,7 +2328,7 @@ export class DaemonClient {
         }
         return payload.notice ?? null;
     }
-    async restartServer(reason, requestId) {
+    async restartServer(reason, requestId, options) {
         const resolvedRequestId = this.createRequestId(requestId);
         const message = SessionInboundMessageSchema.parse({
             type: "restart_server_request",
@@ -2313,6 +2338,7 @@ export class DaemonClient {
         return this.sendRequest({
             requestId: resolvedRequestId,
             message,
+            timeout: options?.timeout,
             options: { skipQueue: true },
             select: (msg) => {
                 if (msg.type !== "status") {
@@ -2638,75 +2664,22 @@ export class DaemonClient {
             : { 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,
+        return this.sendCorrelatedSessionRequest({
+            message: {
+                type: "checkout.diff.get.request",
+                cwd,
+                compare: this.normalizeCheckoutDiffCompare(compare),
+            },
+            responseType: "checkout.diff.get.response",
+            requestId,
         });
-        const resolvedRequestId = this.createRequestId(options?.requestId);
-        const message = SessionInboundMessageSchema.parse({
+    }
+    observeCheckoutDiff(cwd, compare, options) {
+        return this.observe("subscribe_checkout_diff_response", {
             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,
-        });
+            compare: this.normalizeCheckoutDiffCompare(compare),
+        }, options);
     }
     async checkoutCommit(cwd, input, requestId) {
         return this.sendCorrelatedSessionRequest({
@@ -3020,17 +2993,16 @@ export class DaemonClient {
         };
     }
     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 } : {}),
+                // COMPAT(workspaceRequestReceipts): added in v0.8.0; remove after 2027-03-15 once the daemon floor supports workspace receipts.
+                ...(this.lastServerInfoMessage?.features?.workspaceRequestReceipts &&
+                    input.idempotencyKey !== undefined
+                    ? { idempotencyKey: input.idempotencyKey }
+                    : {}),
                 ...(input.title !== undefined ? { title: input.title } : {}),
                 ...(input.firstAgentContext !== undefined
                     ? { firstAgentContext: input.firstAgentContext }
@@ -3156,35 +3128,26 @@ export class DaemonClient {
             this.activeBinaryFileTransfers.delete(resolvedRequestId);
         }
     }
+    observeFile(input) {
+        return this.observe("fs.file.subscribe.response", { type: "fs.file.subscribe.request", cwd: input.cwd, path: input.path }, { signal: input.signal });
+    }
     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;
-        }
+        const subscription = this.observeFile(input);
+        let initial = true;
+        subscription.subscribe({
+            snapshot: (snapshot) => {
+                // The initial version is returned below. Subsequent snapshots repair reconnects.
+                if (!initial)
+                    onUpdate(snapshot.initial);
+                initial = false;
+            },
+            update: (message) => {
+                if (message.type === "fs.file.update")
+                    onUpdate(message.payload.version);
+            },
+        });
+        const snapshot = await subscription.ready;
+        return { initial: snapshot.initial, subscription, unsubscribe: subscription.release };
     }
     async writeFile(input) {
         const payload = await this.sendCorrelatedSessionRequest({
@@ -3223,6 +3186,7 @@ export class DaemonClient {
         if (!bytes) {
             throw new Error("File bytes are required.");
         }
+        const uploadTransport = this.transport;
         const resolvedRequestId = this.createRequestId(input.requestId);
         const modifiedAt = input.modifiedAt ?? new Date().toISOString();
         const responsePromise = this.sendCorrelatedRequest({
@@ -3238,29 +3202,51 @@ export class DaemonClient {
             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) {
+        let settled = false;
+        void responsePromise.then(() => {
+            settled = true;
+            return undefined;
+        }, () => {
+            settled = true;
+            return undefined;
+        });
+        try {
+            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 ?? 128 * 1024;
+            for (let offset = 0; offset < bytes.byteLength; offset += chunkSize) {
+                // Native WebSocket.send encodes binary synchronously. Let rendering and
+                // incoming messages run between bounded pieces on every platform.
+                await new Promise((resolve) => setTimeout(resolve, 0));
+                if (settled)
+                    return await responsePromise;
+                if (this.transport !== uploadTransport || this.connectionState.status !== "connected") {
+                    throw new DaemonConnectionError("Connection changed during file upload");
+                }
+                this.sendBinaryFrame(encodeFileTransferFrame({
+                    opcode: FileTransferOpcode.FileChunk,
+                    requestId: resolvedRequestId,
+                    payload: bytes.subarray(offset, Math.min(offset + chunkSize, bytes.byteLength)),
+                }));
+            }
             this.sendBinaryFrame(encodeFileTransferFrame({
-                opcode: FileTransferOpcode.FileChunk,
+                opcode: FileTransferOpcode.FileEnd,
                 requestId: resolvedRequestId,
-                payload: bytes.subarray(offset, Math.min(offset + chunkSize, bytes.byteLength)),
             }));
         }
-        this.sendBinaryFrame(encodeFileTransferFrame({
-            opcode: FileTransferOpcode.FileEnd,
-            requestId: resolvedRequestId,
-        }));
+        catch (error) {
+            this.rejectWaitersForRequestId(resolvedRequestId, error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
         return responsePromise;
     }
     async requestDownloadToken(cwd, path, requestId) {
@@ -3364,6 +3350,11 @@ export class DaemonClient {
         });
     }
     async getDaemonStatus(options) {
+        if (!this.lastServerInfoMessage)
+            throw new DaemonConnectionError("Transport not connected");
+        if (this.lastServerInfoMessage?.features?.daemonStatusRpc !== true) {
+            throw new Error("Update the host to read daemon status.");
+        }
         return this.sendCorrelatedSessionRequest({
             requestId: options?.requestId,
             message: {
@@ -3605,18 +3596,21 @@ export class DaemonClient {
     }
     async installPluginSource(input) {
         const requestId = this.createRequestId();
-        const reference = parsePluginSourceReference(input.source);
+        // COMPAT(pluginSourceInstallation): added in v0.8.0; remove after 2027-03-16 once daemon floor supports source identifiers.
+        if (this.getLastServerInfoMessage()?.features?.pluginSourceInstallation !== true) {
+            throw new Error("Update the host to install plugin sources.");
+        }
         const payload = await this.sendCorrelatedSessionRequest({
             requestId,
             message: {
                 type: "plugin.source.install.request",
                 requestId,
-                source: reference.source,
-                ...(reference.pluginPath ? { pluginPath: reference.pluginPath } : {}),
+                source: input.source,
                 ...(input.id ? { id: input.id } : {}),
                 ...(input.ref ? { ref: input.ref } : {}),
             },
             responseType: "plugin.source.install.response",
+            timeout: 5 * 60 * 1000,
         });
         return payload.plugin;
     }
@@ -3633,6 +3627,33 @@ export class DaemonClient {
         });
         return payload.plugins;
     }
+    requirePluginUpdates() {
+        // COMPAT(pluginSourceUpdates): added in v0.8.0; remove after 2027-03-16 once daemon floor supports reviewed updates.
+        if (this.getLastServerInfoMessage()?.features?.pluginSourceUpdates !== true)
+            throw new Error("Update the host to review plugin updates.");
+    }
+    async previewPluginUpdates(input = {}) {
+        this.requirePluginUpdates();
+        const requestId = this.createRequestId();
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "plugin.source.update.preview.request", requestId, ...input },
+            responseType: "plugin.source.update.preview.response",
+            timeout: 300000,
+        });
+        return payload.plugins;
+    }
+    async applyPluginUpdates(proposals) {
+        this.requirePluginUpdates();
+        const requestId = this.createRequestId();
+        const payload = await this.sendCorrelatedSessionRequest({
+            requestId,
+            message: { type: "plugin.source.update.apply.request", requestId, proposals },
+            responseType: "plugin.source.update.apply.response",
+            timeout: 300000,
+        });
+        return payload.plugins;
+    }
     async updatePluginSources(pluginId) {
         const requestId = this.createRequestId();
         const payload = await this.sendCorrelatedSessionRequest({
@@ -3840,30 +3861,9 @@ export class DaemonClient {
     // ============================================================================
     // 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 } : {}),
-        });
+    observeTerminals(input) {
+        const { signal, ...query } = input;
+        return this.observe("terminals_changed", { type: "subscribe_terminals_request", ...query }, { signal });
     }
     async listTerminals(cwd, requestId, options) {
         const resolvedRequestId = this.createRequestId(requestId);
@@ -3911,45 +3911,72 @@ export class DaemonClient {
             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({
+    /**
+     * Snapshot/restore and output arrive in receive. Subscribe to the returned handle
+     * for terminal_stream_exit: payload.error means observation failure, not PTY exit.
+     * Either outcome detaches this slot and releases the handle automatically.
+     */
+    observeTerminal(terminalId, receive, options) {
+        options?.signal?.throwIfAborted();
+        const observation = this.observe("subscribe_terminal_response", {
             type: "subscribe_terminal_request",
             terminalId,
-            requestId: resolvedRequestId,
-            ...(restore ? { restore } : {}),
-        });
-        const payload = await this.sendCorrelatedRequest({
-            requestId: resolvedRequestId,
-            message,
-            responseType: "subscribe_terminal_response",
-            options: { skipQueue: true },
+            ...(options?.restore ? { restore: options.restore } : {}),
+        }, options);
+        let detach = () => { };
+        let released = false;
+        const release = () => {
+            released = true;
+            detach();
+            options?.signal?.removeEventListener("abort", abort);
+            return observation.release();
+        };
+        const abort = () => {
+            void release().catch((error) => this.logger.error({ err: error }, "Terminal release failed"));
+        };
+        options?.signal?.addEventListener("abort", abort, { once: true });
+        observation.subscribe({
+            snapshot: (payload) => {
+                detach();
+                if (released || options?.signal?.aborted || payload.error !== null)
+                    return;
+                const subscriptionId = payload.subscriptionId;
+                detach = this.terminalStreams.attach(subscriptionId, terminalId, payload.slot, (event) => {
+                    if (released || observation.subscriptionId !== subscriptionId)
+                        return;
+                    try {
+                        receive(event);
+                    }
+                    catch (error) {
+                        this.logger.error({ err: error }, "Terminal observer failed");
+                    }
+                });
+            },
+            update: (message) => {
+                if (message.type === "terminal_stream_exit") {
+                    detach();
+                    queueMicrotask(abort);
+                }
+            },
+            error: () => {
+                detach();
+            },
         });
-        if (payload.error === null) {
-            this.terminalStreams.setSlot(terminalId, payload.slot);
-        }
-        return payload;
+        return {
+            get subscriptionId() {
+                return observation.subscriptionId;
+            },
+            ready: observation.ready,
+            subscribe: observation.subscribe,
+            release,
+        };
     }
-    unsubscribeTerminal(terminalId) {
-        this.terminalStreams.removeTerminal(terminalId);
-        this.sendSessionMessage({
-            type: "unsubscribe_terminal_request",
-            terminalId,
-        });
+    async subscribeTerminal(terminalId, options) {
+        const subscription = this.observeTerminal(terminalId, () => { }, options);
+        return { ...(await subscription.ready), subscription };
     }
     sendTerminalInput(terminalId, message) {
-        const frame = this.terminalStreams.encodeInput(terminalId, message);
-        if (frame) {
-            this.sendBinaryFrame(frame);
-            return;
-        }
-        this.sendSessionMessage({
-            type: "terminal_input",
-            terminalId,
-            message,
-        });
+        this.sendSessionMessage({ type: "terminal_input", terminalId, message });
     }
     async killTerminal(terminalId, requestId) {
         const resolvedRequestId = this.createRequestId(requestId);
@@ -4182,7 +4209,8 @@ export class DaemonClient {
         }
     }
     disposeTransport(code = 1001, reason = "Reconnecting") {
-        this.providerSnapshotUpdates.pause();
+        this.owned.disconnected();
+        this.providerSnapshotUpdates.clear();
         this.stopLivenessHeartbeat();
         this.cleanupTransport();
         if (this.transport) {
@@ -4223,10 +4251,12 @@ export class DaemonClient {
         if (typeof Blob !== "undefined" &&
             rawData instanceof Blob &&
             typeof rawData.arrayBuffer === "function") {
+            const transport = this.transport;
             void rawData
                 .arrayBuffer()
                 .then((buffer) => {
-                this.handleTransportMessage(buffer);
+                if (this.transport === transport)
+                    this.handleTransportMessage(buffer);
                 return;
             })
                 .catch(() => {
@@ -4455,12 +4485,13 @@ export class DaemonClient {
         if (typeof reason === "string" && reason.trim().length > 0) {
             this.lastErrorValue = reason.trim();
         }
-        this.providerSnapshotUpdates.pause();
+        this.owned.disconnected();
+        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 Error(reason ?? "Connection lost"));
-        this.rejectPendingSendQueue(new Error(reason ?? "Connection lost"));
-        this.rejectPingProbe(new Error(reason ?? "Connection lost"));
+        this.clearWaiters(new DaemonConnectionError(reason ?? "Connection lost"));
+        this.rejectPendingSendQueue(new DaemonConnectionError(reason ?? "Connection lost"));
+        this.rejectPingProbe(new DaemonConnectionError(reason ?? "Connection lost"));
         this.terminalStreams.clearSlots();
         this.lastServerInfoMessage = null;
         if (wasDisposed) {
@@ -4539,13 +4570,13 @@ export class DaemonClient {
         });
     }
     handleSessionMessage(msg) {
+        msg = this.owned.normalize(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) {
+            if (this.owned.owns(msg))
                 this.providerSnapshotUpdates.receive(msg);
-            }
             return;
         }
         this.deliverSessionMessage(msg);
@@ -4561,25 +4592,16 @@ export class DaemonClient {
                     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.owned.restore(serverInfo, {
+                        ...DEFAULT_CLIENT_CAPABILITIES,
+                        ...this.config.capabilities,
+                    });
                     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 {
@@ -4608,20 +4630,30 @@ export class DaemonClient {
             }
         }
         if (consumerMessage.type === "workspace.create.update" ||
-            consumerMessage.type === "agent.create.update")
-            this.creations.receive(consumerMessage.payload);
+            consumerMessage.type === "agent.create.update") {
+            if (!consumerMessage.payload.subscriptionId)
+                this.creations.receive(consumerMessage.payload);
+        }
         this.resolveWaiters(consumerMessage);
+        this.owned.receive(consumerMessage);
     }
     resolveWaiters(msg) {
         for (const waiter of Array.from(this.waiters)) {
-            const result = waiter.predicate(msg);
-            if (result !== null) {
+            try {
+                const result = waiter.predicate(msg);
+                if (result === null)
+                    continue;
                 this.waiters.delete(waiter);
-                if (waiter.timeoutHandle) {
+                if (waiter.timeoutHandle)
                     clearTimeout(waiter.timeoutHandle);
-                }
                 waiter.resolve(result);
             }
+            catch (error) {
+                this.waiters.delete(waiter);
+                if (waiter.timeoutHandle)
+                    clearTimeout(waiter.timeoutHandle);
+                waiter.reject(error instanceof Error ? error : new Error(String(error)));
+            }
         }
     }
     rejectWaitersForRequestId(requestId, error) {
@@ -4704,7 +4736,7 @@ export class DaemonClient {
     }
     waitForWithCancel(predicate, timeout = 30000, options) {
         // Capture stack trace at call site, not inside setTimeout
-        const timeoutError = new Error(`Timeout waiting for message (${timeout}ms)`);
+        const timeoutError = new DaemonConnectionError(`Timeout waiting for message (${timeout}ms)`, "DAEMON_REQUEST_TIMEOUT");
         let waiter = null;
         let settled = false;
         let rejectFn = null;