dsh-remote-local-plugin 0.8.3 → 0.8.5

package/lib/index.js

@@ -1,4 +1,4 @@
-/* dsh-remote-local-plugin@0.8.3 — bundled host entry */
+/* dsh-remote-local-plugin@0.8.5 — bundled host entry */
 
 // src/index.ts
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
@@ -252,7 +252,7 @@ async function handleHostApi(ctx, service, mirrors, request) {
     });
   }
   try {
-    const value = await dispatch(ctx, service, mirrors, body.endpoint, body.payload);
+    const value = await dispatch(ctx, service, mirrors, body.endpoint, body.payload, request.signal);
     return jsonResult({ ok: true, value });
   } catch (error) {
     const failure = asLocalError(error);
@@ -266,7 +266,7 @@ async function handleHostApi(ctx, service, mirrors, request) {
     });
   }
 }
-async function dispatch(ctx, service, mirrors, endpoint, payload) {
+async function dispatch(ctx, service, mirrors, endpoint, payload, signal) {
   switch (endpoint) {
     case "state":
       return service.state();
@@ -295,6 +295,8 @@ async function dispatch(ctx, service, mirrors, endpoint, payload) {
       return service.refresh(requireStringField(payload, "hostId"));
     case "host/provision":
       return service.provision(requireStringField(payload, "hostId"));
+    case "host/restart":
+      return service.restart(requireStringField(payload, "hostId"));
     case "host/workspaces": {
       const hostId = requireStringField(payload, "hostId");
       const workspaces = await service.workspaces(hostId);
@@ -396,7 +398,6 @@ async function dispatch(ctx, service, mirrors, endpoint, payload) {
       const files = ctx.get("workspaceFiles");
       if (files === void 0) return { mirrored: false };
       const scope = { sessionId, workspaceRoot: root };
-      const signal = new AbortController().signal;
       if (endpoint === "host/files/list") return { mirrored: true, value: await files.list(scope, path, signal) };
       if (endpoint === "host/files/stat") return { mirrored: true, value: await files.stat(scope, path, signal) };
       if (endpoint === "host/files/bytes") return { mirrored: true, value: await files.readBytes(scope, path, {
@@ -574,6 +575,7 @@ var RemoteMirrorService = class {
   #syncing = false;
   #saveQueue = Promise.resolve();
   #timer;
+  #selectionOff;
   #disposed = false;
   constructor(ctx, hosts, config) {
     this.#ctx = ctx;
@@ -583,6 +585,9 @@ var RemoteMirrorService = class {
   /** Load mappings and begin periodic discovery. */
   async start() {
     await this.#load();
+    this.#selectionOff = this.#ctx.on("session/event", ((session, event) => {
+      this.#onLocalSessionEvent(session, event);
+    }), { global: true });
     if (!this.#config.mirrorSessions) return;
     this.#timer = setInterval(() => {
       void this.sync();
@@ -593,9 +598,13 @@ var RemoteMirrorService = class {
   async dispose() {
     this.#disposed = true;
     if (this.#timer !== void 0) clearInterval(this.#timer);
+    this.#selectionOff?.();
+    this.#selectionOff = void 0;
     for (const runtime of this.#runtimes.values()) {
       runtime.stopped = true;
       if (runtime.timer !== void 0) clearTimeout(runtime.timer);
+      runtime.stream?.abort();
+      runtime.assistant?.abort();
     }
     for (const dispose of this.#registrations.values()) dispose();
     this.#registrations.clear();
@@ -674,18 +683,26 @@ var RemoteMirrorService = class {
     const text = contentText(message);
     if (text === "") return;
     runtime.pendingUsers.push(message);
+    if (!runtime.running) {
+      runtime.awaitingTurn = runtime.latestTurn + 1;
+      runtime.awaitingStarted = false;
+    } else {
+      runtime.awaitingStarted = true;
+    }
     this.#setRunning(runtime, true);
     if (runtime.stopped || runtime.timer === void 0) {
       runtime.stopped = false;
       runtime.lastError = null;
       this.#schedule(runtime);
     }
+    const selection = this.#selectionFor(runtime);
+    if (selection !== void 0) Object.assign(runtime.agent.options, selection);
     void this.#hosts.promptSession(
       runtime.record.hostId,
       runtime.record.remoteSessionId,
       text,
       mode,
-      latestSelection(runtime.session)
+      selection
     ).catch((error) => {
       runtime.lastError = error instanceof Error ? error.message : String(error);
       runtime.pendingUsers.shift();
@@ -693,12 +710,32 @@ var RemoteMirrorService = class {
       this.#setRunning(runtime, false);
     });
   }
-  /** Route cancellation to the remote session. */
+  /** Route cancellation to the remote session only after the remote accepts it. */
   cancel(runtime) {
-    void this.#hosts.cancelSession(runtime.record.hostId, runtime.record.remoteSessionId).catch((error) => {
-      this.#ctx.logger.warn("dsh-remote-local: remote cancel failed: %s", String(error));
+    void this.#hosts.cancelSession(runtime.record.hostId, runtime.record.remoteSessionId).then(() => {
+      runtime.awaitingTurn = null;
+      runtime.awaitingStarted = false;
+      this.#setRunning(runtime, false);
+    }).catch((error) => {
+      runtime.lastError = error instanceof Error ? error.message : String(error);
+      this.#ctx.logger.warn("dsh-remote-local: remote cancel failed: %s", runtime.lastError);
+      this.#setRunning(runtime, true);
     });
-    this.#setRunning(runtime, false);
+  }
+  #selectionFor(runtime) {
+    const projections = this.#ctx.get("sessionProjections");
+    const state = projections?.stateOf?.(runtime.session, "modelSelection");
+    const read = (candidate) => {
+      if (typeof candidate !== "object" || candidate === null) return void 0;
+      const record = candidate;
+      if (typeof record.provider !== "string" || typeof record.model !== "string") return void 0;
+      return {
+        provider: record.provider,
+        model: record.model,
+        ...typeof record.reasoningEffort === "string" ? { reasoningEffort: record.reasoningEffort } : {}
+      };
+    };
+    return read(state?.pending) ?? latestSelection(runtime.session) ?? read(runtime.agent.options) ?? read(state?.lastUsed);
   }
   async #syncHost(host) {
     this.#ensureApprovalStream(host);
@@ -890,18 +927,32 @@ var RemoteMirrorService = class {
   async #ensureMirror(host, remote, workspace, _remotePath) {
     const ref = key(host.id, remote.sessionId);
     const existing = this.#state.sessions[ref];
+    let reuse;
     if (existing !== void 0) {
       const live = this.#sessions.get(existing.localSessionId);
-      const runtime2 = this.#runtimes.get(existing.localSessionId);
-      if (live !== void 0 && runtime2 !== void 0) {
+      const runtime = this.#runtimes.get(existing.localSessionId);
+      if (live !== void 0 && runtime !== void 0 && (!runtime.stopped || !remote.live)) {
         await this.#attach(workspace, live.id);
+        if (remote.live) {
+          this.#startStream(runtime);
+          this.#startAssistantStream(runtime);
+        }
         return existing;
       }
-      if (live !== void 0) {
-        await this.#archive(existing.localSessionId);
-      } else if (existing.localSessionId !== "") {
-        await this.#archive(existing.localSessionId);
+      const stalled = this.#runtimes.get(existing.localSessionId);
+      if (stalled !== void 0) {
+        stalled.stopped = true;
+        if (stalled.timer !== void 0) clearTimeout(stalled.timer);
+        stalled.stream?.abort();
+        stalled.assistant?.abort();
+        this.#runtimes.delete(existing.localSessionId);
       }
+      const registration = this.#registrations.get(existing.localSessionId);
+      if (registration !== void 0) {
+        registration();
+        this.#registrations.delete(existing.localSessionId);
+      }
+      if (live !== void 0) reuse = live;
     }
     const snapshot = await this.#hosts.snapshot(host.id, remote.sessionId, this.#config.mirrorMaxEvents);
     if (snapshot.truncated && (snapshot.events[0]?.seq ?? 0) > 0) {
@@ -914,11 +965,38 @@ var RemoteMirrorService = class {
     }
     const anchor = this.#anchorFor(workspace);
     await mkdir(anchor, { recursive: true });
-    const localId = `session-${randomUUID()}`;
+    const filtered = snapshot.events.filter((event) => !isMirrorNoise(event.type));
+    const seqMap = new Map(filtered.map((event, index) => [event.seq, index]));
+    let latestTurn = 0;
+    for (const event of filtered) {
+      if (event.type !== "turn/start") continue;
+      const turn = event.data.turn;
+      if (typeof turn === "number") latestTurn = Math.max(latestTurn, turn);
+    }
+    const remoteToLocalSeq = /* @__PURE__ */ new Map();
+    for (const [index, event] of filtered.entries()) remoteToLocalSeq.set(event.seq, index);
+    if (reuse !== void 0) {
+      const localEvents = reuse.snapshotEvents();
+      for (let index = 0; index < Math.min(localEvents.length, filtered.length); index += 1) {
+        const localEvent = localEvents[index];
+        const remoteEvent = filtered[index];
+        if (localEvent !== void 0 && remoteEvent !== void 0) {
+          remoteToLocalSeq.set(remoteEvent.seq, localEvent.seq);
+        }
+      }
+      const record2 = existing;
+      await this.#attach(workspace, reuse.id);
+      await this.#mountRuntime(record2, reuse, snapshot, remoteToLocalSeq, latestTurn, remote.live);
+      this.#ctx.logger.info(
+        "dsh-remote-local: reattached remote session %s to local %s",
+        remote.sessionId,
+        reuse.id
+      );
+      return record2;
+    }
+    const localId = existing?.localSessionId ?? `session-${randomUUID()}`;
     let session;
     try {
-      const filtered = snapshot.events.filter((event) => !isMirrorNoise(event.type));
-      const seqMap = new Map(filtered.map((event, index) => [event.seq, index]));
       const seed = filtered.map((event, index) => toSeedEvent(event, index, seqMap));
       session = this.#sessions.create(localId, {
         ...seed.length === 0 ? {} : { seed },
@@ -934,7 +1012,7 @@ var RemoteMirrorService = class {
     } catch (error) {
       this.#ctx.logger.debug("dsh-remote-local: mirror flush failed: %s", String(error));
     }
-    const record = {
+    const record = existing === void 0 ? {
       hostId: host.id,
       remoteSessionId: remote.sessionId,
       localSessionId: localId,
@@ -942,32 +1020,53 @@ var RemoteMirrorService = class {
       anchor,
       lastSeq: snapshot.cursor,
       updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    } : {
+      ...existing,
+      remoteWorkspaceId: remote.workspaceId,
+      anchor,
+      lastSeq: snapshot.cursor,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
     this.#state.sessions[ref] = record;
+    await this.#mountRuntime(record, session, snapshot, remoteToLocalSeq, latestTurn, remote.live);
+    this.#ctx.logger.info(
+      "dsh-remote-local: mirrored remote session %s as local %s",
+      remote.sessionId,
+      localId
+    );
+    return record;
+  }
+  async #mountRuntime(record, session, snapshot, remoteToLocalSeq, latestTurn, live) {
     const runtime = {
       record,
       agent: null,
       session,
       timer: void 0,
+      stream: void 0,
+      assistant: void 0,
+      remoteToLocalSeq,
+      pendingAssistantEnds: /* @__PURE__ */ new Map(),
+      latestTurn,
+      awaitingTurn: null,
+      awaitingStarted: false,
+      applyingRemote: false,
       running: false,
       stopped: false,
       lastError: null,
       pendingUsers: [],
       waiters: []
     };
-    const options = modelOptions(snapshot.events);
+    const options = this.#defaultSelection() ?? modelOptions(snapshot.events);
     const agent = new RemoteMirrorAgent(this, runtime, this.#ctx, options);
     runtime.agent = agent;
-    this.#runtimes.set(localId, runtime);
-    this.#registrations.set(localId, this.#agents.enter(agent, void 0));
+    this.#runtimes.set(record.localSessionId, runtime);
+    this.#registrations.set(record.localSessionId, this.#agents.enter(agent, void 0));
     await this.#save();
     this.#schedule(runtime);
-    this.#ctx.logger.info(
-      "dsh-remote-local: mirrored remote session %s as local %s",
-      remote.sessionId,
-      localId
-    );
-    return record;
+    if (live) {
+      this.#startStream(runtime);
+      this.#startAssistantStream(runtime);
+    }
   }
   #schedule(runtime) {
     if (runtime.stopped || this.#disposed) return;
@@ -981,6 +1080,8 @@ var RemoteMirrorService = class {
       const local = this.#sessions.get(runtime.session.id);
       if (local === void 0) {
         runtime.stopped = true;
+        runtime.stream?.abort();
+        runtime.assistant?.abort();
         return;
       }
       const snapshot = await this.#hosts.snapshot(
@@ -991,24 +1092,29 @@ var RemoteMirrorService = class {
       if (snapshot.truncated && (snapshot.events[0]?.seq ?? 0) > runtime.record.lastSeq) {
         runtime.lastError = "remote log grew past the mirror window";
         runtime.stopped = true;
+        runtime.stream?.abort();
+        runtime.assistant?.abort();
         return;
       }
-      let sawEnd = false;
       for (const event of snapshot.events) {
         if (event.seq < runtime.record.lastSeq) continue;
         if (event.seq !== runtime.record.lastSeq) {
           throw new Error(`remote event gap at ${event.seq}, mirror ${runtime.record.lastSeq}`);
         }
-        if (!isMirrorNoise(event.type)) appendRemoteEvent(local, event, runtime);
+        this.#appendEvent(runtime, event);
         runtime.record.lastSeq = event.seq + 1;
-        if (event.type === "turn/end") sawEnd = true;
       }
       runtime.record.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-      if (sawEnd) this.#setRunning(runtime, false);
       if (!snapshot.live && runtime.record.lastSeq >= snapshot.cursor) {
         runtime.stopped = true;
+        runtime.stream?.abort();
+        runtime.assistant?.abort();
       }
       await this.#save();
+      if (snapshot.live && !runtime.stopped) {
+        this.#startStream(runtime);
+        this.#startAssistantStream(runtime);
+      }
     } catch (error) {
       runtime.lastError = error instanceof Error ? error.message : String(error);
       this.#ctx.logger.warn(
@@ -1019,12 +1125,204 @@ var RemoteMirrorService = class {
     }
     this.#schedule(runtime);
   }
+  #startStream(runtime) {
+    if (runtime.stopped || this.#disposed || runtime.stream !== void 0) return;
+    const controller = new AbortController();
+    runtime.stream = controller;
+    void this.#followStream(runtime, controller.signal).finally(() => {
+      if (runtime.stream === controller) runtime.stream = void 0;
+    });
+  }
+  async #followStream(runtime, signal) {
+    try {
+      for await (const frame of this.#hosts.followSessionEvents(
+        runtime.record.hostId,
+        runtime.record.remoteSessionId,
+        runtime.record.lastSeq,
+        signal
+      )) {
+        if (runtime.stopped || this.#disposed || signal.aborted) return;
+        if (frame.type === "end") return;
+        if (frame.type !== "event") continue;
+        const event = frame.event;
+        if (event.seq < runtime.record.lastSeq) continue;
+        if (event.seq !== runtime.record.lastSeq) {
+          runtime.lastError = `remote event gap at ${event.seq}, mirror ${runtime.record.lastSeq}`;
+          return;
+        }
+        this.#appendEvent(runtime, event);
+        runtime.record.lastSeq = event.seq + 1;
+        runtime.record.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+        await this.#save();
+      }
+    } catch (error) {
+      if (signal.aborted || runtime.stopped || this.#disposed) return;
+      runtime.lastError = error instanceof Error ? error.message : String(error);
+      this.#ctx.logger.warn(
+        "dsh-remote-local: mirror stream %s failed: %s",
+        runtime.record.remoteSessionId,
+        runtime.lastError
+      );
+    }
+  }
+  #appendEvent(runtime, event) {
+    const before = runtime.session.seq;
+    runtime.applyingRemote = true;
+    try {
+      if (!isMirrorNoise(event.type)) {
+        appendRemoteEvent(runtime.session, remapRemoteEvent(event, runtime.remoteToLocalSeq), runtime);
+      }
+    } finally {
+      runtime.applyingRemote = false;
+    }
+    const after = runtime.session.seq;
+    if (after > before) {
+      runtime.remoteToLocalSeq.set(event.seq, after - 1);
+      this.#flushAssistantEnd(runtime, event.seq);
+    }
+    const turn = typeof event.data === "object" && event.data !== null ? event.data.turn : void 0;
+    if (typeof turn !== "number") return;
+    if (event.type === "turn/start") {
+      runtime.latestTurn = Math.max(runtime.latestTurn, turn);
+      return;
+    }
+    if (event.type !== "turn/end") return;
+    runtime.latestTurn = Math.max(runtime.latestTurn, turn);
+    if (runtime.awaitingTurn === null || turn >= runtime.awaitingTurn) {
+      runtime.awaitingTurn = null;
+      runtime.awaitingStarted = false;
+      this.#setRunning(runtime, false);
+    }
+  }
+  #onLocalSessionEvent(session, event) {
+    const candidate = event;
+    if (candidate.type !== "model/selection") return;
+    const runtime = [...this.#runtimes.values()].find((item) => item.session.id === session.id);
+    if (runtime === void 0 || runtime.stopped || runtime.applyingRemote) return;
+    const record = candidate.data;
+    if (typeof record.provider !== "string" || typeof record.model !== "string") return;
+    const selection = {
+      provider: record.provider,
+      model: record.model,
+      ...typeof record.reasoningEffort === "string" ? { reasoningEffort: record.reasoningEffort } : {}
+    };
+    Object.assign(runtime.agent.options, selection);
+    void this.#hosts.selectModel(runtime.record.hostId, runtime.record.remoteSessionId, selection).catch((error) => {
+      runtime.lastError = error instanceof Error ? error.message : String(error);
+      this.#ctx.logger.warn("dsh-remote-local: remote model selection failed: %s", runtime.lastError);
+    });
+  }
+  #defaultSelection() {
+    const defaults = this.#ctx.get("agentDefaultModel");
+    const candidate = defaults?.currentSelection?.();
+    if (typeof candidate !== "object" || candidate === null) return void 0;
+    const record = candidate;
+    if (typeof record.provider !== "string" || typeof record.model !== "string") return void 0;
+    return {
+      provider: record.provider,
+      model: record.model,
+      ...typeof record.reasoningEffort === "string" ? { reasoningEffort: record.reasoningEffort } : {}
+    };
+  }
+  #flushAssistantEnd(runtime, remoteSeq) {
+    const pending = runtime.pendingAssistantEnds.get(remoteSeq);
+    if (pending === void 0) return;
+    const localSeq = runtime.remoteToLocalSeq.get(remoteSeq);
+    if (localSeq === void 0) return;
+    runtime.pendingAssistantEnds.delete(remoteSeq);
+    if (pending.outcome?.kind !== "committed") {
+      this.#emitAssistant(runtime, pending);
+      return;
+    }
+    this.#emitAssistant(runtime, {
+      ...pending,
+      outcome: { ...pending.outcome, seq: localSeq }
+    });
+  }
+  #emitAssistant(runtime, frame) {
+    try {
+      const emit = this.#ctx.emit;
+      emit.call(this.#ctx, "agent/assistant-stream", { agent: runtime.agent, frame });
+    } catch (error) {
+      this.#ctx.logger.warn(
+        "dsh-remote-local: local assistant frame %s failed: %s",
+        runtime.record.remoteSessionId,
+        String(error)
+      );
+    }
+  }
+  #startAssistantStream(runtime) {
+    if (runtime.stopped || this.#disposed || runtime.assistant !== void 0) return;
+    const controller = new AbortController();
+    runtime.assistant = controller;
+    void this.#followAssistant(runtime, controller.signal).finally(() => {
+      if (runtime.assistant === controller) runtime.assistant = void 0;
+    });
+  }
+  async #followAssistant(runtime, signal) {
+    try {
+      for await (const frame of this.#hosts.followAssistantFrames(
+        runtime.record.hostId,
+        runtime.record.remoteSessionId,
+        signal
+      )) {
+        if (runtime.stopped || this.#disposed || signal.aborted) return;
+        if (frame.type === "start") {
+          runtime.awaitingStarted = true;
+          this.#setRunning(runtime, true);
+          const { startedAfterSeq: _startedAfterSeq, ...rest } = frame;
+          this.#emitAssistant(runtime, rest);
+          continue;
+        }
+        if (frame.type === "chunk") {
+          const chunkType = frame.chunk?.type;
+          if (chunkType !== "tool-call-delta") this.#emitAssistant(runtime, frame);
+          continue;
+        }
+        const outcome = frame.outcome;
+        if (outcome === void 0) return;
+        if (outcome.kind !== "committed") {
+          this.#emitAssistant(runtime, frame);
+          continue;
+        }
+        const localSeq = runtime.remoteToLocalSeq.get(outcome.seq);
+        if (localSeq === void 0) {
+          runtime.pendingAssistantEnds.set(outcome.seq, frame);
+          continue;
+        }
+        this.#emitAssistant(runtime, {
+          ...frame,
+          outcome: { ...outcome, seq: localSeq }
+        });
+      }
+    } catch (error) {
+      if (signal.aborted || runtime.stopped || this.#disposed) return;
+      this.#ctx.logger.warn(
+        "dsh-remote-local: assistant stream %s failed: %s",
+        runtime.record.remoteSessionId,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
   #setRunning(runtime, running) {
     if (runtime.running === running) return;
     runtime.running = running;
     if (!running) {
       for (const waiter of runtime.waiters.splice(0)) waiter();
     }
+    try {
+      const emit = this.#ctx.emit;
+      emit.call(this.#ctx, "agent/status", {
+        agent: runtime.agent,
+        status: running ? "running" : "idle"
+      });
+    } catch (error) {
+      this.#ctx.logger.warn(
+        "dsh-remote-local: local agent status %s failed: %s",
+        runtime.record.remoteSessionId,
+        String(error)
+      );
+    }
   }
   async #attach(workspace, sessionId) {
     try {
@@ -1074,6 +1372,19 @@ var RemoteMirrorService = class {
     return task;
   }
 };
+function remapRemoteEvent(event, remoteToLocal) {
+  const sourceEventSeqs = event.sourceEventSeqs?.map((seq) => remoteToLocal.get(seq)).filter((seq) => seq !== void 0);
+  const surfaceOp = typeof event.surfaceOp === "object" ? {
+    op: "replace",
+    startSeq: remoteToLocal.get(event.surfaceOp.startSeq) ?? 0,
+    endSeq: remoteToLocal.get(event.surfaceOp.endSeq) ?? 0
+  } : event.surfaceOp;
+  return {
+    ...event,
+    ...sourceEventSeqs === void 0 || sourceEventSeqs.length === 0 ? {} : { sourceEventSeqs },
+    ...surfaceOp === void 0 ? {} : { surfaceOp }
+  };
+}
 function isMirrorNoise(type) {
   return type === "agent/inbox/spliced";
 }
@@ -1189,6 +1500,7 @@ function safe(value) {
 // src/remote/files.ts
 import { spawn as spawn2 } from "node:child_process";
 import { isAbsolute as isAbsolute2, join as join4, relative, resolve as resolve3, sep } from "node:path";
+var HELPER_TIMEOUT_MS = 15e3;
 var HELPER = String.raw`
 import sys, json, os, base64
 req = json.load(sys.stdin)
@@ -1346,21 +1658,41 @@ function installRemoteWorkspaceFiles(ctx, mirrors, hosts) {
 function targetOf(mirrors, workspaceRoot, path) {
   const context = mirrors.remoteFileContext(workspaceRoot);
   if (context === void 0) return void 0;
-  const localPath = isAbsolute2(path) ? resolve3(path) : resolve3(workspaceRoot, path);
-  const rel = relative(workspaceRoot, localPath);
-  if (rel === "" || !rel.startsWith("..") && !isAbsolute2(rel)) {
-    const remotePath = rel === "" ? context.remoteRoot : join4(context.remoteRoot, rel);
+  const anchor = resolve3(workspaceRoot);
+  const remoteRoot = resolve3(context.remoteRoot);
+  const candidate = isAbsolute2(path) ? resolve3(path) : resolve3(anchor, path);
+  const contains = (root, value) => {
+    const rel = relative(root, value);
+    return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
+  };
+  if (isAbsolute2(path) && contains(remoteRoot, candidate)) {
+    const rel = relative(remoteRoot, candidate);
+    return {
+      hostId: context.hostId,
+      localPath: rel === "" ? anchor : resolve3(anchor, rel),
+      remotePath: candidate,
+      relativePath: rel.split(sep).join("/"),
+      workspaceRoot: anchor
+    };
+  }
+  if (contains(anchor, candidate)) {
+    const rel = relative(anchor, candidate);
+    const remotePath = rel === "" ? remoteRoot : join4(remoteRoot, rel);
     return {
       hostId: context.hostId,
-      localPath: localPath === "" ? workspaceRoot : localPath,
+      localPath: candidate,
       remotePath,
       relativePath: rel.split(sep).join("/"),
-      workspaceRoot
+      workspaceRoot: anchor
     };
   }
-  return void 0;
+  throw Object.assign(
+    new Error(`remote file path is outside the mirrored workspace: ${path}`),
+    { code: "workspace-file/not-found" }
+  );
 }
 async function helper(hosts, hostId, request, signal) {
+  if (signal.aborted) throw new Error("remote file helper aborted");
   const ssh = hosts.sshFor(hostId);
   const args = [
     "-o",
@@ -1380,7 +1712,7 @@ async function helper(hosts, hostId, request, signal) {
     const timer = setTimeout(() => {
       child.kill("SIGKILL");
       reject(new Error("remote file helper timed out"));
-    }, 3e4);
+    }, HELPER_TIMEOUT_MS);
     const abort = () => {
       child.kill("SIGKILL");
       reject(new Error("remote file helper aborted"));
@@ -1394,6 +1726,11 @@ async function helper(hosts, hostId, request, signal) {
     child.stderr.on("data", (chunk) => {
       stderr += chunk;
     });
+    child.stdin.on("error", (error) => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", abort);
+      reject(error);
+    });
     child.on("error", (error) => {
       clearTimeout(timer);
       signal.removeEventListener("abort", abort);
@@ -1840,6 +2177,35 @@ var RemoteProtocolError = class extends Error {
   }
 };
 
+// ../protocol/lib/types.js
+function isRemoteAssistantFrame(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const frame = value;
+  if (frame.type !== "start" && frame.type !== "chunk" && frame.type !== "end")
+    return false;
+  if (typeof frame.attemptId !== "string" || typeof frame.revision !== "number")
+    return false;
+  if (frame.type === "start") {
+    return typeof frame.turn === "number" && typeof frame.step === "number";
+  }
+  if (frame.type === "chunk") {
+    return typeof frame.index === "number" && typeof frame.time === "number" && "chunk" in frame;
+  }
+  if (typeof frame.index !== "number")
+    return false;
+  const outcome = frame.outcome;
+  if (typeof outcome !== "object" || outcome === null)
+    return false;
+  const kind = outcome.kind;
+  if (kind === "abandoned")
+    return true;
+  if (kind !== "committed")
+    return false;
+  const record = outcome;
+  return typeof record.eventType === "string" && typeof record.seq === "number";
+}
+
 // ../protocol/lib/routes.js
 var AGENT_ROUTES = {
   health: `${AGENT_API_PREFIX}/health`,
@@ -1856,6 +2222,9 @@ function workspaceSessionsPath(workspaceId) {
 function sessionPath(sessionId) {
   return `${AGENT_API_PREFIX}/sessions/${encodeURIComponent(sessionId)}`;
 }
+function sessionModelPath(sessionId) {
+  return `${sessionPath(sessionId)}/model`;
+}
 function sessionPromptPath(sessionId) {
   return `${sessionPath(sessionId)}/prompt`;
 }
@@ -1866,6 +2235,9 @@ function sessionEventsPath(sessionId, cursor) {
   const base = `${sessionPath(sessionId)}/events`;
   return cursor === void 0 ? base : `${base}?cursor=${encodeURIComponent(String(cursor))}`;
 }
+function sessionAssistantEventsPath(sessionId) {
+  return `${sessionPath(sessionId)}/assistant-events`;
+}
 var SESSION_PREFIX = `${AGENT_API_PREFIX}/sessions/`;
 var WORKSPACE_PREFIX = `${AGENT_API_PREFIX}/workspaces/`;
 
@@ -2108,6 +2480,13 @@ var RemoteAgentClient = class {
       body: request
     });
   }
+  /** Select the model and reasoning effort for one remote session. */
+  async selectModel(sessionId, request) {
+    await this.#request(sessionModelPath(sessionId), isAcceptedResult, {
+      method: "POST",
+      body: request
+    });
+  }
   /** Send a text prompt to a remote session. */
   async promptSession(sessionId, request) {
     await this.#request(sessionPromptPath(sessionId), isAcceptedResult, {
@@ -2192,6 +2571,38 @@ var RemoteAgentClient = class {
       yield frame;
     }
   }
+  /** Follow one session's dense process-local Assistant frames. */
+  async *followAssistantFrames(sessionId, signal) {
+    const response = await this.#openStream(sessionAssistantEventsPath(sessionId), signal);
+    const body = response.body;
+    if (body === null) {
+      throw new RemoteProtocolError({
+        code: "request/invalid",
+        message: "remote agent returned an empty assistant stream"
+      });
+    }
+    for await (const message of parseSseStream(body)) {
+      if (message.data === "")
+        continue;
+      let frame;
+      try {
+        frame = JSON.parse(message.data);
+      } catch (error) {
+        throw new RemoteProtocolError({
+          code: "request/invalid",
+          message: "remote agent sent malformed assistant JSON",
+          cause: error
+        });
+      }
+      if (!isRemoteAssistantFrame(frame)) {
+        throw new RemoteProtocolError({
+          code: "request/invalid",
+          message: "remote agent sent an unknown assistant frame"
+        });
+      }
+      yield frame;
+    }
+  }
   /** Validate an event sequence against a cursor. */
   static guardEvent(cursor, event) {
     return cursor.accept(event);
@@ -2656,6 +3067,7 @@ function renderSystemdUnit(options) {
     // $PATH is expanded by the bootstrap shell after nodePathPrelude(), so the
     // systemd unit sees the discovered nvm/Volta/fnm Node bin directory too.
     'Environment="PATH=$INSTALL_DIR/node/bin:$INSTALL_DIR/node_modules/.bin:/usr/local/bin:/usr/bin:/bin:$PATH"',
+    "${PROXY_ENV_LINES}",
     ...options.modelBaseUrl === void 0 ? [] : ['Environment="DEEPSEEK_BASE_URL=$MODEL_BASE_URL"'],
     ...options.modelApiKey === void 0 ? [] : ['Environment="DEEPSEEK_API_KEY=$MODEL_API_KEY"'],
     'ExecStart="$DSH_BIN" web --host 127.0.0.1 --port $PORT --no-open',
@@ -2795,6 +3207,9 @@ PNPM_VERSION=${shellLiteral(options.pnpmVersion)}
 NODE_VERSION=${shellLiteral(options.nodeVersion)}
 AUTO_INSTALL_NODE=${options.autoInstallNode ? "1" : "0"}
 AGENT_TARBALL=${shellLiteral(options.agentTarball)}
+AGENT_NPM_SPEC=${options.agentPackageSpec === void 0 ? "''" : shellLiteral(options.agentPackageSpec)}
+AGENT_ARTIFACT_DIR="$INSTALL_DIR/artifacts"
+AGENT_ARTIFACT="$AGENT_ARTIFACT_DIR/$(basename "$AGENT_TARBALL")"
 MODEL_BASE_URL=${options.modelBaseUrl === void 0 ? "''" : shellLiteral(options.modelBaseUrl)}
 MODEL_API_KEY=${options.modelApiKey === void 0 ? "''" : shellLiteral(options.modelApiKey)}
 PROXY_URL=${options.proxyUrl === void 0 ? "''" : shellLiteral(options.proxyUrl)}
@@ -2858,6 +3273,16 @@ if [ -n "$PROXY_URL" ]; then
   fi
   echo "dsh-remote: install proxy configured"
 fi
+PROXY_ENV_LINES=""
+if [ -n "$PROXY_URL" ]; then
+  PROXY_ENV_LINES="Environment=\\"HTTP_PROXY=$PROXY_URL\\"
+Environment=\\"HTTPS_PROXY=$PROXY_URL\\"
+Environment=\\"ALL_PROXY=$PROXY_URL\\""
+  if [ -n "$PROXY_NO_PROXY" ]; then
+    PROXY_ENV_LINES="$PROXY_ENV_LINES
+Environment=\\"NO_PROXY=$PROXY_NO_PROXY\\""
+  fi
+fi
 
 ${nodePathPrelude()}
 
@@ -2898,7 +3323,14 @@ if [ ! -x "$DSH_BIN" ]; then
 fi
 
 echo "dsh-remote: adding plugin to profile $PROFILE"
-"$DSH_BIN" plugin --profile "$PROFILE" add "$AGENT_TARBALL"
+mkdir -p "$AGENT_ARTIFACT_DIR"
+cp -f "$AGENT_TARBALL" "$AGENT_ARTIFACT"
+if [ -n "$AGENT_NPM_SPEC" ] && "$DSH_BIN" plugin --profile "$PROFILE" add "$AGENT_NPM_SPEC"; then
+  echo "dsh-remote: installed agent from npm"
+else
+  echo "dsh-remote: npm agent unavailable; installing the bundled agent" >&2
+  "$DSH_BIN" plugin --profile "$PROFILE" add "$AGENT_ARTIFACT"
+fi
 
 echo "dsh-remote: starting dsh web"
 ${startBlock}
@@ -3122,6 +3554,7 @@ async function provisionRemoteAgent(options) {
     agentTarball: remoteTarball,
     ...options.modelBaseUrl === void 0 ? {} : { modelBaseUrl: options.modelBaseUrl },
     ...options.modelApiKey === void 0 ? {} : { modelApiKey: options.modelApiKey },
+    ...options.agentPackageSpec === void 0 ? {} : { agentPackageSpec: options.agentPackageSpec },
     ...options.proxyUrl === void 0 ? {} : { proxyUrl: options.proxyUrl },
     ...options.noProxy === void 0 ? {} : { noProxy: options.noProxy }
   });
@@ -3283,6 +3716,8 @@ var RemoteProvisioner = class {
    */
   async ensureInstalled(target, options = {}) {
     const tarball = findAgentTarball();
+    const version = /dsh-remote-agent-(.+)\.tgz$/u.exec(tarball)?.[1];
+    const agentPackageSpec = version === void 0 ? void 0 : `@goldenpigeon/dsh-remote-agent@${version}`;
     options.onProgress?.("\u6B63\u5728\u51C6\u5907\u8FDC\u7AEF\u5B89\u88C5\u73AF\u5883\u2026");
     const proxyUrl = this.#config.remoteInstallProxy.trim() || void 0;
     if (proxyUrl !== void 0) options.onProgress?.("\u6B63\u5728\u914D\u7F6E\u8FDC\u7AEF\u5B89\u88C5\u4EE3\u7406\u2026");
@@ -3290,6 +3725,7 @@ var RemoteProvisioner = class {
       await provisionRemoteAgent({
         target: target.canonical,
         agentTarballPath: tarball,
+        ...agentPackageSpec === void 0 ? {} : { agentPackageSpec },
         sshBinary: this.#config.sshBinary,
         strictHostKeyChecking: this.#config.strictHostKeyChecking,
         profile: "web",
@@ -3395,6 +3831,40 @@ function findAgentTarball() {
   );
 }
 
+// src/remote/restart.ts
+import { execFile as execFile4 } from "node:child_process";
+import { promisify as promisify3 } from "node:util";
+var execFileAsync3 = promisify3(execFile4);
+var RESTART_COMMAND = [
+  "if command -v systemctl >/dev/null 2>&1 && systemctl --user cat dsh-remote-agent.service >/dev/null 2>&1; then",
+  "  systemctl --user restart dsh-remote-agent.service",
+  "else",
+  '  echo "dsh-remote: dsh-remote-agent.service was not found; use Reinstall or restart the remote DSH manually" >&2',
+  "  exit 4",
+  "fi"
+].join("\n");
+async function restartRemoteAgent(target, options) {
+  try {
+    await execFileAsync3(
+      options.sshBinary,
+      [
+        ...baseSshArgs(target, { timeoutMs: 6e4, strictHostKeyChecking: options.strictHostKeyChecking }),
+        target.destination,
+        RESTART_COMMAND
+      ],
+      { timeout: 75e3, maxBuffer: 64 * 1024, encoding: "utf8", windowsHide: true }
+    );
+  } catch (error) {
+    const failure = error;
+    const detail = (failure.stderr ?? "").trim().split("\n")[0] ?? "";
+    throw new LocalError(
+      "agent/unavailable",
+      failure.killed === true ? "remote DSH restart timed out" : detail !== "" ? `remote DSH restart failed: ${detail}` : `remote DSH restart failed: ${failure.message}`,
+      { details: { host: target.canonical }, retryable: true, cause: error }
+    );
+  }
+}
+
 // src/ssh/target.ts
 var USER_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,63}$/u;
 var HOST_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,252}[A-Za-z0-9])?$/u;
@@ -3858,6 +4328,60 @@ var RemoteHostsService = class {
     }
     return this.connect(id);
   }
+  /** Restart the remote DSH service and reconnect without reinstalling. */
+  async restart(id) {
+    this.#assertAlive();
+    const record = this.#requireRecord(id);
+    const target = parseSshTarget(record.sshTarget);
+    this.#manualDisconnect.delete(id);
+    this.#clearReconnect(id);
+    await this.#stopTransport(id);
+    this.#setRuntime(id, {
+      ...this.#runtimeFor(id),
+      phase: "connecting",
+      localPort: null,
+      localUrl: null,
+      hostInfo: null,
+      connectedAt: null,
+      error: null,
+      errorCode: null,
+      detail: "\u6B63\u5728\u91CD\u542F\u8FDC\u7AEF DSH\u2026"
+    });
+    try {
+      await restartRemoteAgent(target, {
+        sshBinary: this.config.sshBinary,
+        strictHostKeyChecking: this.config.strictHostKeyChecking
+      });
+    } catch (error) {
+      const failure2 = this.#markError(id, error, "agent/unavailable");
+      throw failure2;
+    }
+    const deadline = Date.now() + 9e4;
+    let lastError;
+    while (Date.now() < deadline) {
+      try {
+        const discovery = await this.#discover(target);
+        if (isAgentLive(discovery.state)) {
+          await this.#saveRecord(id, {
+            remoteAgentPort: discovery.state.port,
+            token: discovery.state.token
+          });
+          return this.connect(id);
+        }
+      } catch (error) {
+        lastError = error;
+      }
+      await new Promise((resolve4) => setTimeout(resolve4, 1e3));
+    }
+    const failure = new LocalError("agent/unavailable", "\u8FDC\u7AEF DSH \u91CD\u542F\u540E\u672A\u80FD\u5728 90 \u79D2\u5185\u5C31\u7EEA", {
+      details: {
+        host: target.canonical,
+        reason: lastError instanceof Error ? lastError.message : String(lastError ?? "state file not ready")
+      },
+      retryable: true
+    });
+    throw this.#markError(id, failure, "agent/unavailable");
+  }
   /** List remote workspaces. */
   async workspaces(id) {
     const client = this.#requireClient(id);
@@ -3879,6 +4403,16 @@ var RemoteHostsService = class {
       throw this.#remoteFailure(id, error);
     }
   }
+  /** Follow a live remote session from a cursor as an SSE-backed stream. */
+  async *followSessionEvents(id, sessionId, cursor, signal) {
+    const client = this.#requireClient(id);
+    try {
+      yield* client.followSession(sessionId, cursor, signal);
+    } catch (error) {
+      if (signal.aborted) return;
+      throw this.#remoteFailure(id, error);
+    }
+  }
   /** Read one session snapshot. */
   async snapshot(id, sessionId, limit) {
     const client = this.#requireClient(id);
@@ -3888,6 +4422,16 @@ var RemoteHostsService = class {
       throw this.#remoteFailure(id, error);
     }
   }
+  /** Follow dense remote Assistant frames for one live Session. */
+  async *followAssistantFrames(id, sessionId, signal) {
+    const client = this.#requireClient(id);
+    try {
+      yield* client.followAssistantFrames(sessionId, signal);
+    } catch (error) {
+      if (signal.aborted) return;
+      throw this.#remoteFailure(id, error);
+    }
+  }
   /** Register a remote workspace. */
   async createWorkspace(id, request) {
     const client = this.#requireClient(id);
@@ -3908,6 +4452,15 @@ var RemoteHostsService = class {
       throw this.#remoteFailure(id, error);
     }
   }
+  /** Install a model/reasoning-effort selection on a remote session. */
+  async selectModel(id, sessionId, selection) {
+    const client = this.#requireClient(id);
+    try {
+      await client.selectModel(sessionId, selection);
+    } catch (error) {
+      throw this.#remoteFailure(id, error);
+    }
+  }
   /** Send a prompt to a remote session. */
   async promptSession(id, sessionId, text, mode, selection) {
     const client = this.#requireClient(id);
@@ -4389,7 +4942,7 @@ var renderJson = (_args, value) => [
 function toJsonObject(value) {
   return JSON.parse(JSON.stringify(value));
 }
-var HOST_WRITE_TOOLS = /* @__PURE__ */ new Set(["remote_host_add", "remote_host_connect", "remote_host_provision"]);
+var HOST_WRITE_TOOLS = /* @__PURE__ */ new Set(["remote_host_add", "remote_host_connect", "remote_host_provision", "remote_host_restart"]);
 function installRemoteToolGuards(ctx) {
   ctx.effect(() => ctx.on("tools/pre-execute", (exec, next) => {
     if (!HOST_WRITE_TOOLS.has(exec.name)) return next();
@@ -4490,6 +5043,24 @@ function registerRemoteTools(ctx, service) {
       return { host: toJsonObject(await service.provision(args.hostId)) };
     }
   }));
+  ctx.tools.register(defineTool({
+    name: "remote_host_restart",
+    description: "Restart the remote DSH service without reinstalling it, preserving installed remote plugins, then reconnect. Requires the installer-owned systemd user unit; use remote_host_provision for nohup installs.",
+    parameters: {
+      hostId: { type: "string", required: true, description: "Registered host id." }
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: { host: { type: "object", additionalProperties: true, required: true } }
+      },
+      render: renderJson
+    },
+    async execute(args) {
+      return { host: toJsonObject(await service.restart(args.hostId)) };
+    }
+  }));
   ctx.tools.register(defineTool({
     name: "remote_workspaces_list",
     description: "List workspaces registered on a connected remote DSH host. Use the returned workspaceId with remote_sessions_list.",