chainlesschain 0.162.154 → 0.162.155

package/src/gateways/ws/background-agent-protocol.js

@@ -0,0 +1,337 @@
+/**
+ * background-agent WS protocol — exposes the background-session transport to
+ * web-panel / IDE clients so a "background agents" panel can list sessions,
+ * live-follow their logs, and interactively take a session over (follow-up
+ * prompts / stop-turn), reusing the exact same NDJSON pipe protocol that
+ * `cc attach` speaks.
+ *
+ * Routes (request → reply):
+ *   bg-list      {all?}            → {type:"bg-list", sessions}
+ *   bg-view      {bgId, lines?}    → {type:"bg-view", session, log}
+ *   bg-attach    {bgId, lines?}    → {type:"bg-attach", bgId, hello, log}
+ *   bg-prompt    {bgId, text}      → {type:"bg-prompt", bgId, sent}
+ *   bg-stop-turn {bgId}            → {type:"bg-stop-turn", bgId, sent}
+ *   bg-detach    {bgId}            → {type:"bg-detach", bgId}
+ *   bg-stop      {bgId}            → {type:"bg-stop", session}   (kill whole session)
+ *
+ * While attached, the server pushes unsolicited frames to that client:
+ *   {type:"bg-event", bgId, event}   worker lifecycle events (turn-started /
+ *                                    turn-ended / idle / accepted / error /
+ *                                    transport-closed)
+ *   {type:"bg-log",   bgId, chunk}   log-file delta (500ms poll)
+ *
+ * The state file's `transport.token` is the local takeover capability — it is
+ * NEVER sent over WS. Sessions are serialized with `interactive: true/false`
+ * instead; the server process (same user) performs the pipe handshake itself.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+
+const LOG_POLL_MS = 500;
+
+async function loadSupervisor() {
+  return import("../../lib/background-agent-supervisor.js");
+}
+
+/** Strip the takeover token before a session state crosses the WS boundary. */
+export function sanitizeBackgroundSession(state) {
+  if (!state) return state;
+  const { transport, ...rest } = state;
+  return { ...rest, interactive: Boolean(transport?.pipe) };
+}
+
+function sendError(server, id, ws, code, message) {
+  server._send(ws, { id, type: "error", code, message });
+}
+
+function attachments(client) {
+  if (!client._bgAttachments) client._bgAttachments = new Map();
+  return client._bgAttachments;
+}
+
+function dropAttachment(client, bgId) {
+  const map = client?._bgAttachments;
+  const entry = map?.get(bgId);
+  if (!entry) return false;
+  map.delete(bgId);
+  clearInterval(entry.poll);
+  try {
+    entry.conn.close();
+  } catch {
+    /* worker side already gone */
+  }
+  return true;
+}
+
+/** Tear down every transport relay a client holds (called on ws close). */
+export function cleanupBgAttachments(client) {
+  const map = client?._bgAttachments;
+  if (!map) return;
+  for (const bgId of [...map.keys()]) dropAttachment(client, bgId);
+}
+
+export async function handleBgList(server, id, ws, message) {
+  try {
+    const { listBackgroundAgents } = await loadSupervisor();
+    const sessions = listBackgroundAgents({ all: message.all === true }).map(
+      sanitizeBackgroundSession,
+    );
+    server._send(ws, { id, type: "bg-list", sessions });
+  } catch (err) {
+    sendError(server, id, ws, "BG_LIST_FAILED", err.message);
+  }
+}
+
+export async function handleBgView(server, id, ws, message) {
+  try {
+    const {
+      readBackgroundAgentState,
+      effectiveBackgroundAgentState,
+      readBackgroundAgentLog,
+    } = await loadSupervisor();
+    if (!message.bgId) {
+      return sendError(server, id, ws, "NO_BG_ID", "bgId required");
+    }
+    const session = effectiveBackgroundAgentState(
+      readBackgroundAgentState(message.bgId),
+    );
+    if (!session) {
+      return sendError(
+        server,
+        id,
+        ws,
+        "BG_NOT_FOUND",
+        `Background agent not found: ${message.bgId}`,
+      );
+    }
+    const log = readBackgroundAgentLog(message.bgId, {
+      lines: Number(message.lines) || 100,
+    });
+    server._send(ws, {
+      id,
+      type: "bg-view",
+      session: sanitizeBackgroundSession(session),
+      log,
+    });
+  } catch (err) {
+    sendError(server, id, ws, "BG_VIEW_FAILED", err.message);
+  }
+}
+
+export async function handleBgAttach(server, clientId, id, ws, message) {
+  try {
+    const client = server.clients.get(clientId);
+    if (!client) {
+      return sendError(server, id, ws, "NO_CLIENT", "client not registered");
+    }
+    if (!message.bgId) {
+      return sendError(server, id, ws, "NO_BG_ID", "bgId required");
+    }
+    const bgId = message.bgId;
+    const {
+      readBackgroundAgentState,
+      effectiveBackgroundAgentState,
+      readBackgroundAgentLog,
+      logPath,
+    } = await loadSupervisor();
+
+    const existing = attachments(client).get(bgId);
+    if (existing) {
+      // Idempotent re-attach: reply with the live handshake instead of
+      // stacking a second relay (a reconnecting panel re-sends bg-attach).
+      server._send(ws, {
+        id,
+        type: "bg-attach",
+        bgId,
+        hello: existing.hello,
+        log: "",
+        reattached: true,
+      });
+      return;
+    }
+
+    const session = effectiveBackgroundAgentState(
+      readBackgroundAgentState(bgId),
+    );
+    if (!session) {
+      return sendError(
+        server,
+        id,
+        ws,
+        "BG_NOT_FOUND",
+        `Background agent not found: ${bgId}`,
+      );
+    }
+    if (session.status !== "running" || !session.transport?.pipe) {
+      return sendError(
+        server,
+        id,
+        ws,
+        "BG_NOT_INTERACTIVE",
+        `Background agent ${bgId} is ${session.status} and has no live session transport`,
+      );
+    }
+
+    const { connectBackgroundSession } =
+      await import("../../lib/background-session-transport.js");
+    let conn;
+    try {
+      conn = await connectBackgroundSession({
+        pipePath: session.transport.pipe,
+        token: session.transport.token,
+        onEvent: (event) => {
+          server._send(ws, { type: "bg-event", bgId, event });
+        },
+        onClose: () => {
+          if (dropAttachment(client, bgId)) {
+            server._send(ws, {
+              type: "bg-event",
+              bgId,
+              event: { type: "transport-closed" },
+            });
+          }
+        },
+      });
+    } catch (err) {
+      return sendError(
+        server,
+        id,
+        ws,
+        "BG_ATTACH_FAILED",
+        `session transport unavailable: ${err.message}`,
+      );
+    }
+
+    const logFile = logPath(bgId);
+    let offset = existsSync(logFile) ? readFileSync(logFile, "utf8").length : 0;
+    const poll = setInterval(() => {
+      try {
+        if (!existsSync(logFile)) return;
+        const text = readFileSync(logFile, "utf8");
+        if (offset > text.length) offset = 0; // truncated/rotated
+        if (text.length > offset) {
+          const chunk = text.slice(offset);
+          offset = text.length;
+          server._send(ws, { type: "bg-log", bgId, chunk });
+        }
+      } catch {
+        /* transient read failures skip one tick */
+      }
+    }, LOG_POLL_MS);
+    poll.unref?.();
+
+    attachments(client).set(bgId, { conn, poll, hello: conn.hello });
+    server._send(ws, {
+      id,
+      type: "bg-attach",
+      bgId,
+      hello: conn.hello,
+      log: readBackgroundAgentLog(bgId, {
+        lines: Number(message.lines) || 100,
+      }),
+    });
+  } catch (err) {
+    sendError(server, id, ws, "BG_ATTACH_FAILED", err.message);
+  }
+}
+
+function requireAttachment(server, clientId, id, ws, message) {
+  const client = server.clients.get(clientId);
+  const entry = client?._bgAttachments?.get(message.bgId);
+  if (!message.bgId) {
+    sendError(server, id, ws, "NO_BG_ID", "bgId required");
+    return null;
+  }
+  if (!entry) {
+    sendError(
+      server,
+      id,
+      ws,
+      "BG_NOT_ATTACHED",
+      `not attached to ${message.bgId} — send bg-attach first`,
+    );
+    return null;
+  }
+  return entry;
+}
+
+export async function handleBgPrompt(server, clientId, id, ws, message) {
+  const entry = requireAttachment(server, clientId, id, ws, message);
+  if (!entry) return;
+  const text = String(message.text || "").trim();
+  if (!text) {
+    return sendError(server, id, ws, "NO_TEXT", "prompt text required");
+  }
+  const sent = entry.conn.send({ type: "prompt", text });
+  server._send(ws, { id, type: "bg-prompt", bgId: message.bgId, sent });
+}
+
+export async function handleBgStopTurn(server, clientId, id, ws, message) {
+  const entry = requireAttachment(server, clientId, id, ws, message);
+  if (!entry) return;
+  const sent = entry.conn.send({ type: "stop" });
+  server._send(ws, { id, type: "bg-stop-turn", bgId: message.bgId, sent });
+}
+
+export async function handleBgDetach(server, clientId, id, ws, message) {
+  if (!message.bgId) {
+    return sendError(server, id, ws, "NO_BG_ID", "bgId required");
+  }
+  const client = server.clients.get(clientId);
+  const dropped = dropAttachment(client, message.bgId);
+  server._send(ws, { id, type: "bg-detach", bgId: message.bgId, dropped });
+}
+
+export async function handleBgRename(server, id, ws, message) {
+  try {
+    if (!message.bgId) {
+      return sendError(server, id, ws, "NO_BG_ID", "bgId required");
+    }
+    const { renameBackgroundAgent } = await loadSupervisor();
+    const session = renameBackgroundAgent(message.bgId, message.title);
+    server._send(ws, {
+      id,
+      type: "bg-rename",
+      session: sanitizeBackgroundSession(session),
+    });
+  } catch (err) {
+    sendError(server, id, ws, "BG_RENAME_FAILED", err.message);
+  }
+}
+
+export async function handleBgResume(server, id, ws, message) {
+  try {
+    if (!message.bgId) {
+      return sendError(server, id, ws, "NO_BG_ID", "bgId required");
+    }
+    const { resumeBackgroundAgent } = await loadSupervisor();
+    const session = resumeBackgroundAgent(message.bgId, message.text);
+    server._send(ws, {
+      id,
+      type: "bg-resume",
+      session: sanitizeBackgroundSession(session),
+    });
+  } catch (err) {
+    sendError(server, id, ws, "BG_RESUME_FAILED", err.message);
+  }
+}
+
+export async function handleBgStop(server, clientId, id, ws, message) {
+  try {
+    if (!message.bgId) {
+      return sendError(server, id, ws, "NO_BG_ID", "bgId required");
+    }
+    // Kill the whole session: drop our relay first so the worker's
+    // "no clients" finalize path doesn't race the stop.
+    dropAttachment(server.clients.get(clientId), message.bgId);
+    const { stopBackgroundAgent } = await loadSupervisor();
+    const session = stopBackgroundAgent(message.bgId);
+    server._send(ws, {
+      id,
+      type: "bg-stop",
+      session: sanitizeBackgroundSession(session),
+    });
+  } catch (err) {
+    sendError(server, id, ws, "BG_STOP_FAILED", err.message);
+  }
+}

package/src/gateways/ws/message-dispatcher.js

@@ -175,6 +175,16 @@ export function createWsMessageDispatcher(server) {
         "task-graph-advance": () =>
           server._handleTaskGraphAdvance(id, ws, message),
         "task-graph-state": () => server._handleTaskGraphState(id, ws, message),
+        "bg-list": () => server._handleBgList(id, ws, message),
+        "bg-view": () => server._handleBgView(id, ws, message),
+        "bg-attach": () => server._handleBgAttach(clientId, id, ws, message),
+        "bg-prompt": () => server._handleBgPrompt(clientId, id, ws, message),
+        "bg-stop-turn": () =>
+          server._handleBgStopTurn(clientId, id, ws, message),
+        "bg-detach": () => server._handleBgDetach(clientId, id, ws, message),
+        "bg-stop": () => server._handleBgStop(clientId, id, ws, message),
+        "bg-rename": () => server._handleBgRename(id, ws, message),
+        "bg-resume": () => server._handleBgResume(id, ws, message),
         "chat.intent.understand": () =>
           server._handleChatIntentUnderstand(id, ws, message),
         "chat.intent.understand-stream": () =>

package/src/gateways/ws/remote-session-protocol.js

@@ -7,6 +7,7 @@ import {
   RemoteSessionCryptoContext,
   createRemotePairingUri,
 } from "../../harness/remote-session-crypto.js";
+import { isApprovalRequestEvent } from "../../harness/remote-session-push.js";
 import { RemoteCommandLedger } from "../../harness/remote-command-ledger.js";
 
 const CLIENT_EVENT_SCOPES = Object.freeze({
@@ -462,12 +463,75 @@ export async function handleRemoteSessionPublish(
       ) {
         throw new Error("prompt content is required");
       }
+      // CLIENT-HOSTED sessions (第四阶段 #2): when the agent session does not
+      // live in THIS server's sessionManager — e.g. a REPL/headless process
+      // that connected as a WS client and registered its own local session id —
+      // the server cannot dispatch the control event itself. Forward it to the
+      // HOST connection instead; the host's approval bridge resolves its local
+      // permission gate / prompt queue. Checked BEFORE the idempotency ledger
+      // so "host unreachable" never consumes a commandId slot (stays retryable
+      // after the host reconnects). Server-hosted sessions are byte-identical.
+      let serverHosted = false;
+      try {
+        serverHosted = Boolean(
+          server.sessionManager?.getSession?.(session.agentSessionId),
+        );
+      } catch {
+        serverHosted = false;
+      }
+      let hostTarget = null;
+      if (!serverHosted) {
+        hostTarget = server.clients.get(session.hostClientId);
+        if (!hostTarget) {
+          throw new Error(
+            "Remote session host is not reachable for this control event",
+          );
+        }
+      }
       // Idempotent forward: a control event with a stable commandId runs its
       // side effect (audit + dispatch into the host agent) AT MOST ONCE, so a
       // reconnecting device re-sending the same prompt/approval/interrupt gets a
       // `replayed` ack instead of a second agent turn. No commandId → forwarded
       // directly, byte-identical to before.
       await applyControlIdempotent(server, clientId, ws, message, async () => {
+        if (!serverHosted) {
+          // Audit the control action with the same taxonomy as server-hosted
+          // dispatch, then hand the event to the host process.
+          const auditAction =
+            message.event.type === "prompt"
+              ? "control.prompt"
+              : message.event.type === "approval.resolve"
+                ? "control.approval"
+                : "control.interrupt";
+          audit(server, {
+            sessionId: message.remoteSessionId,
+            actor: clientId,
+            action: auditAction,
+            detail:
+              message.event.type === "prompt"
+                ? { chars: message.event.content.length, forwarded: true }
+                : message.event.type === "approval.resolve"
+                  ? {
+                      requestId:
+                        message.event.requestId || message.event.approvalId,
+                      approved: message.event.answer ?? message.event.approved,
+                      forwarded: true,
+                    }
+                  : { forwarded: true },
+          });
+          server._send(hostTarget.ws, {
+            type: "remote-session-control",
+            remoteSessionId: message.remoteSessionId,
+            agentSessionId: session.agentSessionId,
+            from: clientId,
+            event: message.event,
+          });
+          reply(server, ws, message.id, "remote-session-published", {
+            delivered: 1,
+            forwardedToHost: true,
+          });
+          return;
+        }
         if (message.event.type === "prompt") {
           // Record the shape, not the content — the audit trail must stay
           // useful without hoarding potentially sensitive session prompts.
@@ -514,8 +578,45 @@ export async function handleRemoteSessionPublish(
       message.remoteSessionId,
     )) {
       if (member.clientId === clientId) continue;
+      // Wake a backgrounded device for approval/permission requests — parity
+      // with the server-hosted mirror path (_mirrorRemoteSessionEvent). A
+      // client-hosted session publishing `permission.request` must reach a
+      // suspended phone the same way (第四阶段 #2).
+      if (
+        member.pushToken &&
+        isApprovalRequestEvent(message.event.type) &&
+        typeof server._dispatchApprovalPush === "function"
+      ) {
+        server._dispatchApprovalPush(session, member, message.event);
+      }
       const target = server.clients.get(member.clientId);
-      if (!target) continue;
+      if (!target) {
+        // Relay-paired mobiles have no local socket — deliver over the E2EE
+        // relay like the mirror path does; without this, host-published
+        // events silently skipped every relay member.
+        if (server.remoteSessionRelay) {
+          const crypto = server.remoteSessionCrypto?.get(
+            message.remoteSessionId,
+          );
+          if (crypto) {
+            try {
+              server.remoteSessionRelay.sendEncrypted(
+                member.clientId,
+                crypto.encrypt(member.clientId, {
+                  type: "remote-session-event",
+                  remoteSessionId: message.remoteSessionId,
+                  agentSessionId: session.agentSessionId,
+                  event: message.event,
+                }),
+              );
+              delivered += 1;
+            } catch {
+              // Peer key may be gone — best-effort, same as revocation notice.
+            }
+          }
+        }
+        continue;
+      }
       server._send(target.ws, {
         type: "remote-session-event",
         remoteSessionId: message.remoteSessionId,

package/src/gateways/ws/ws-server.js

@@ -94,6 +94,18 @@ import {
   handleChatIntentClassifyFollowup,
 } from "./chat-intent-protocol.js";
 import { handleLlmChat } from "./llm-chat-protocol.js";
+import {
+  cleanupBgAttachments,
+  handleBgAttach,
+  handleBgDetach,
+  handleBgList,
+  handleBgPrompt,
+  handleBgRename,
+  handleBgResume,
+  handleBgStop,
+  handleBgStopTurn,
+  handleBgView,
+} from "./background-agent-protocol.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -469,6 +481,10 @@ export class ChainlessChainWSServer extends EventEmitter {
         clearTimeout(client.authTimer);
         client.authTimer = null;
       }
+      // Close any background-session transport relays this client held —
+      // mirrors the CLI attach detach semantics (an idle worker with no
+      // remaining clients finalizes itself).
+      cleanupBgAttachments(client);
       this.clients.delete(clientId);
       for (const affected of this.remoteSessions.removeClient(clientId)) {
         if (affected.closed)
@@ -656,6 +672,51 @@ export class ChainlessChainWSServer extends EventEmitter {
     return handleWorktreeList(this, id, ws);
   }
 
+  /** @private — list background agent sessions (token-stripped) */
+  async _handleBgList(id, ws, message) {
+    return handleBgList(this, id, ws, message);
+  }
+
+  /** @private — background agent detail view (state + log tail) */
+  async _handleBgView(id, ws, message) {
+    return handleBgView(this, id, ws, message);
+  }
+
+  /** @private — attach to a background session transport (event/log relay) */
+  async _handleBgAttach(clientId, id, ws, message) {
+    return handleBgAttach(this, clientId, id, ws, message);
+  }
+
+  /** @private — send a follow-up prompt into an attached background session */
+  async _handleBgPrompt(clientId, id, ws, message) {
+    return handleBgPrompt(this, clientId, id, ws, message);
+  }
+
+  /** @private — stop the current turn of an attached background session */
+  async _handleBgStopTurn(clientId, id, ws, message) {
+    return handleBgStopTurn(this, clientId, id, ws, message);
+  }
+
+  /** @private — drop this client's background session relay */
+  async _handleBgDetach(clientId, id, ws, message) {
+    return handleBgDetach(this, clientId, id, ws, message);
+  }
+
+  /** @private — kill a whole background session */
+  async _handleBgStop(clientId, id, ws, message) {
+    return handleBgStop(this, clientId, id, ws, message);
+  }
+
+  /** @private — rename a background session's title */
+  async _handleBgRename(id, ws, message) {
+    return handleBgRename(this, id, ws, message);
+  }
+
+  /** @private — continue a finished session as a new background run */
+  async _handleBgResume(id, ws, message) {
+    return handleBgResume(this, id, ws, message);
+  }
+
   /** @private */
   async _handleCompressionStats(id, ws, message) {
     return handleCompressionStats(this, id, ws, message);

package/src/harness/mcp-client.js

@@ -411,6 +411,13 @@ export class MCPClient extends EventEmitter {
       entry.state = ServerState.CONNECTED;
       entry.serverInfo = initResult?.serverInfo || {};
       entry.capabilities = initResult?.capabilities || {};
+      // Optional top-level usage instructions from the server's initialize
+      // response (previously discarded). Surfaced by tool search so a deferred
+      // server's guidance still reaches the model on demand.
+      entry.instructions =
+        typeof initResult?.instructions === "string"
+          ? initResult.instructions
+          : null;
 
       // Fetch available tools. Per MCP a server advertises a `tools` capability
       // in its initialize response; if it does and tools/list then fails, that
@@ -469,6 +476,7 @@ export class MCPClient extends EventEmitter {
         resources: entry.resources,
         prompts: entry.prompts,
         serverInfo: entry.serverInfo,
+        instructions: entry.instructions,
       };
     } catch (err) {
       entry.state = ServerState.ERROR;

package/src/index.js

@@ -21,6 +21,7 @@ import { registerHubCommand } from "./commands/hub.js";
 import { registerAndroidCommand } from "./commands/android.js";
 import { registerEvalCommand } from "./commands/eval.js";
 import { registerTeamCommand } from "./commands/team.js";
+import { registerAutoModeCommand } from "./commands/auto-mode.js";
 import {
   registerAgentCommand,
   registerSubAgentV2Command,
@@ -67,6 +68,7 @@ import { registerCheckpointCommand } from "./commands/checkpoint.js";
 import { registerGoalCommand } from "./commands/goal.js";
 import { registerCommandCommand } from "./commands/command.js";
 import { registerAgentsCommand } from "./commands/agents.js";
+import { registerBackgroundSessionCommands } from "./commands/background-session.js";
 import { registerCompactCommand } from "./commands/compact.js";
 import { registerLoopCommand } from "./commands/loop.js";
 import { registerReviewCommand } from "./commands/review.js";
@@ -151,6 +153,9 @@ import { registerCliAnythingCommand } from "./commands/cli-anything.js";
 // WebSocket Server Interface
 import { registerServeCommand } from "./commands/serve.js";
 
+// Remote Control unified entry (第四阶段 #1)
+import { registerRemoteControlCommand } from "./commands/remote-control.js";
+
 // Web UI
 import { registerUiCommand } from "./commands/ui.js";
 import { registerPackCommand } from "./commands/pack.js";
@@ -434,6 +439,7 @@ export function createProgram(opts = {}) {
   registerLlmCommand(program);
   registerHubCommand(program);
   registerAndroidCommand(program);
+  registerAutoModeCommand(program);
   registerAgentCommand(program);
   registerEvalCommand(program);
   registerTeamCommand(program);
@@ -482,6 +488,7 @@ export function createProgram(opts = {}) {
   registerGoalCommand(program);
   registerCommandCommand(program);
   registerAgentsCommand(program);
+  registerBackgroundSessionCommands(program);
   registerCompactCommand(program);
   registerLoopCommand(program);
   registerReviewCommand(program);
@@ -576,6 +583,9 @@ export function createProgram(opts = {}) {
   // WebSocket Server Interface
   registerServeCommand(program);
 
+  // Remote Control unified entry
+  registerRemoteControlCommand(program);
+
   // Web UI
   registerUiCommand(program);