chainlesschain 0.162.154 → 0.162.156

package/src/commands/remote-control.js

@@ -0,0 +1,407 @@
+/**
+ * `cc remote-control` — unified cross-device entry (gap-analysis 第四阶段 #1).
+ *
+ * One command composes the existing remote-session stack (WS server + E2EE
+ * relay + registry + push + audit) into the Claude-Code `/remote-control`
+ * shape:
+ *
+ *   cc remote-control                 # start host + print pairing URI/QR
+ *   cc remote-control start --relay-url wss://relay… --peer-id my-desktop
+ *   cc remote-control status [--json]
+ *   cc remote-control stop [--port N]
+ *
+ * `start` boots the WS server IN-PROCESS, then opens a loopback client that
+ * acts as the remote session HOST (the registry closes a remote session when
+ * its host disconnects, so this client stays open for the server's lifetime).
+ * With a relay configured you get the E2EE `chainlesschain://remote-session/…`
+ * URI; without one you get a direct-LAN pairing URI embedding ws://<lan-ip>.
+ * Devices join with observe/prompt/approve/interrupt scopes — the same wire
+ * contract the web-panel and Android client already speak.
+ */
+
+import chalk from "chalk";
+import { logger } from "../lib/logger.js";
+import { loadConfig } from "../lib/config-manager.js";
+import { createAgentRuntimeFactory } from "../runtime/runtime-factory.js";
+import { WsRpcClient } from "../lib/ws-rpc-client.js";
+import {
+  buildDirectPairingUri,
+  pickLanAddress,
+  readRemoteControlStates,
+  removeRemoteControlState,
+  renderQrCode,
+  resolveRemoteControlOptions,
+  writeRemoteControlState,
+} from "../lib/remote-control.js";
+
+export function registerRemoteControlCommand(program) {
+  const cmd = program
+    .command("remote-control")
+    .alias("rc")
+    .description(
+      "Unified remote-control entry — pair mobile/web devices to drive this machine's agent sessions",
+    );
+
+  cmd
+    .command("start", { isDefault: true })
+    .description(
+      "Start the remote-control host (WS server + remote session) and print the pairing URI/QR",
+    )
+    .option("-p, --port <port>", "WS server port (default 18800)")
+    .option("--host <host>", "Bind host (default 0.0.0.0)")
+    .option("--token <token>", "Server auth token (default: auto-generated)")
+    .option(
+      "--relay-url <url>",
+      "Signaling relay URL for E2EE pairing (falls back to direct LAN pairing when unset)",
+    )
+    .option("--peer-id <id>", "Stable relay peer ID for this host")
+    .option(
+      "--scopes <csv>",
+      "Granted device scopes (observe,prompt,approve,interrupt)",
+    )
+    .option("--name <name>", "Remote session display name")
+    .option(
+      "--session <agentSessionId>",
+      "Attach to an existing agent session instead of creating a new one",
+    )
+    .option("--no-qr", "Skip terminal QR rendering")
+    .option("--json", "Emit machine-readable pairing JSON and keep serving")
+    .action(async (options) => {
+      const result = await runRemoteControlStart(options);
+      if (result.code !== 0) process.exit(result.code);
+    });
+
+  cmd
+    .command("status")
+    .description("Show discovered remote-control hosts on this machine")
+    .option("--json", "Machine-readable JSON output")
+    .option("--prune", "Remove stale state files (dead pid)")
+    .action((options) => {
+      process.exitCode = runRemoteControlStatus(options);
+    });
+
+  cmd
+    .command("stop")
+    .description("Stop a running remote-control host")
+    .option("-p, --port <port>", "Port of the host to stop")
+    .option("--json", "Machine-readable JSON output")
+    .action((options) => {
+      process.exitCode = runRemoteControlStop(options);
+    });
+}
+
+/**
+ * Boot the host: server runtime + loopback host client + remote session +
+ * pairing printout + discovery state. Resolves `{code}` (0 = serving; the
+ * server + host client keep the process alive) plus live handles so tests and
+ * embedders can tear the host down (`{client, server, state}`).
+ */
+export async function runRemoteControlStart(options = {}, _deps = {}) {
+  const log = _deps.log || ((m) => console.log(m));
+  const errLog = _deps.err || ((m) => logger.error(m));
+  const env = _deps.env || process.env;
+  const stateDir = _deps.stateDir; // undefined → default dir
+  let config = {};
+  try {
+    config = _deps.loadConfig ? _deps.loadConfig() : loadConfig();
+  } catch {
+    // config is optional for remote-control
+  }
+
+  let resolved;
+  try {
+    resolved = resolveRemoteControlOptions({
+      flags: {
+        port: options.port,
+        host: options.host,
+        token: options.token,
+        relayUrl: options.relayUrl,
+        peerId: options.peerId,
+        scopes: options.scopes,
+        name: options.name,
+      },
+      env,
+      config,
+    });
+  } catch (err) {
+    errLog(err.message);
+    return { code: 4 };
+  }
+
+  // Refuse to double-start on a port that already has a LIVE host.
+  const existing = readRemoteControlStates({ dir: stateDir }).find(
+    (state) => state.port === resolved.port && state.alive,
+  );
+  if (existing) {
+    errLog(
+      `remote-control host already running on port ${resolved.port} (pid ${existing.pid}). ` +
+        `Use \`cc remote-control status\` or \`cc remote-control stop --port ${resolved.port}\`.`,
+    );
+    return { code: 2 };
+  }
+
+  let server;
+  try {
+    const startServer =
+      _deps.startServer ||
+      (async () =>
+        createAgentRuntimeFactory()
+          .createServerRuntime({
+            port: resolved.port,
+            host: resolved.host,
+            token: resolved.token,
+            allowRemote: resolved.host !== "127.0.0.1",
+            remoteSessionRelayUrl: resolved.relayUrl,
+            remoteSessionPeerId: resolved.peerId,
+          })
+          .startServer());
+    server = await startServer(resolved);
+  } catch (err) {
+    errLog(`Failed to start remote-control host: ${err.message}`);
+    return { code: 1 };
+  }
+
+  // Loopback HOST connection — must stay open, its disconnect closes the
+  // remote session (registry semantics).
+  const client =
+    _deps.createClient?.(resolved) ||
+    new WsRpcClient({ url: `ws://127.0.0.1:${resolved.port}` });
+  let remoteSession;
+  let pairing;
+  let agentSessionId = options.session || null;
+  try {
+    await client.connect();
+    await client.auth(resolved.token);
+    if (!agentSessionId) {
+      const created = await client.request("session-create", {
+        sessionType: "agent",
+        projectRoot: _deps.cwd || process.cwd(),
+      });
+      agentSessionId =
+        created.sessionId ||
+        created.payload?.sessionId ||
+        created.session?.sessionId ||
+        created.session?.id;
+      if (!agentSessionId) {
+        throw new Error("session-create returned no sessionId");
+      }
+    }
+    const createdRemote = await client.request("remote-session-create", {
+      sessionId: agentSessionId,
+      name: resolved.name,
+      scopes: resolved.scopes,
+    });
+    remoteSession = createdRemote.session;
+    pairing = createdRemote.pairing;
+  } catch (err) {
+    errLog(`Failed to create remote session: ${err.message}`);
+    client.close();
+    try {
+      await server.stop?.();
+    } catch {
+      // best-effort teardown
+    }
+    return { code: 1 };
+  }
+
+  const relayMode = Boolean(pairing?.uri);
+  const lanAddress = _deps.lanAddress || pickLanAddress() || "127.0.0.1";
+  const wsUrl = `ws://${lanAddress}:${resolved.port}`;
+  const pairingUri = relayMode
+    ? pairing.uri
+    : buildDirectPairingUri({
+        wsUrl,
+        serverToken: resolved.token,
+        remoteSessionId: remoteSession.sessionId,
+        agentSessionId,
+        pairingToken: pairing.token,
+        scopes: pairing.scopes,
+        expiresAt: pairing.expiresAt,
+      });
+
+  const state = {
+    pid: process.pid,
+    port: resolved.port,
+    host: resolved.host,
+    wsUrl,
+    token: resolved.token,
+    mode: relayMode ? "relay" : "direct",
+    relayUrl: resolved.relayUrl || null,
+    peerId: resolved.peerId || null,
+    agentSessionId,
+    remoteSessionId: remoteSession.sessionId,
+    scopes: pairing.scopes,
+    startedAt: new Date().toISOString(),
+  };
+  const stateFile = writeRemoteControlState(state, { dir: stateDir });
+  const cleanup = () => {
+    removeRemoteControlState(resolved.port, { dir: stateDir });
+  };
+  process.once("exit", cleanup);
+  process.once("SIGINT", cleanup);
+  process.once("SIGTERM", cleanup);
+
+  if (options.json) {
+    log(
+      JSON.stringify(
+        {
+          mode: state.mode,
+          wsUrl,
+          port: resolved.port,
+          agentSessionId,
+          remoteSessionId: remoteSession.sessionId,
+          pairingUri,
+          pairing: {
+            token: pairing.token,
+            scopes: pairing.scopes,
+            expiresAt: pairing.expiresAt,
+          },
+          stateFile,
+        },
+        null,
+        2,
+      ),
+    );
+  } else {
+    log("");
+    log(chalk.bold("  Remote Control ready"));
+    log("");
+    log(
+      `  Mode:        ${state.mode === "relay" ? chalk.cyan("relay (E2EE)") : chalk.cyan("direct LAN")}`,
+    );
+    log(`  WS server:   ${chalk.cyan(wsUrl)}`);
+    log(`  Agent sess:  ${agentSessionId}`);
+    log(`  Remote sess: ${remoteSession.sessionId}`);
+    log(`  Scopes:      ${pairing.scopes.join(", ")}`);
+    log(
+      `  Token exp:   ${pairing.expiresAt ? new Date(pairing.expiresAt).toISOString() : "n/a"} ${chalk.dim("(one-time; re-run start for another device)")}`,
+    );
+    log("");
+    log("  Pairing URI (open in ChainlessChain mobile / paste in web panel):");
+    log("");
+    log("    " + chalk.green(pairingUri));
+    if (options.qr !== false) {
+      const qr = await renderQrCode(pairingUri, _deps);
+      if (qr) {
+        log("");
+        log(
+          qr
+            .split("\n")
+            .map((line) => "  " + line)
+            .join("\n"),
+        );
+      } else {
+        log("");
+        log(
+          chalk.dim(
+            "  (install the optional `qrcode` package for a terminal QR)",
+          ),
+        );
+      }
+    }
+    log("");
+    log(chalk.dim("  Press Ctrl+C to stop"));
+    log("");
+  }
+
+  return { code: 0, client, server, state, pairingUri };
+}
+
+export function runRemoteControlStatus(options = {}, _deps = {}) {
+  const log = _deps.log || ((m) => console.log(m));
+  const states = readRemoteControlStates({ dir: _deps.stateDir });
+  if (options.prune) {
+    for (const state of states) {
+      if (!state.alive && state.port) {
+        removeRemoteControlState(state.port, { dir: _deps.stateDir });
+      }
+    }
+  }
+  if (options.json) {
+    log(
+      JSON.stringify(
+        // The token stays in the 0600 state file — status output may be pasted
+        // into issues/chat, so redact it here.
+        states.map(({ token: _token, ...rest }) => rest),
+        null,
+        2,
+      ),
+    );
+    return 0;
+  }
+  if (states.length === 0) {
+    log(chalk.gray("\n  No remote-control hosts found.\n"));
+    return 0;
+  }
+  log("");
+  log(chalk.bold("  Remote-control hosts:\n"));
+  for (const state of states) {
+    if (state.invalid) {
+      log(`  ${chalk.red("invalid")}  ${state.stateFile}`);
+      continue;
+    }
+    const badge = state.alive ? chalk.green("running") : chalk.yellow("stale");
+    log(
+      `  ${badge}  port ${String(state.port).padEnd(6)} pid ${String(state.pid).padEnd(8)} ` +
+        `${(state.mode || "?").padEnd(7)} session ${state.agentSessionId || "?"}`,
+    );
+  }
+  log("");
+  return 0;
+}
+
+export function runRemoteControlStop(options = {}, _deps = {}) {
+  const log = _deps.log || ((m) => console.log(m));
+  const errLog = _deps.err || ((m) => logger.error(m));
+  const kill = _deps.kill || ((pid) => process.kill(pid));
+  const states = readRemoteControlStates({ dir: _deps.stateDir }).filter(
+    (state) => !state.invalid,
+  );
+  const port = options.port ? Number(options.port) : null;
+  const candidates = port
+    ? states.filter((state) => state.port === port)
+    : states;
+  if (candidates.length === 0) {
+    errLog(
+      port
+        ? `No remote-control host recorded on port ${port}.`
+        : "No remote-control hosts recorded.",
+    );
+    return 2;
+  }
+  if (!port && candidates.filter((state) => state.alive).length > 1) {
+    errLog(
+      "Multiple hosts running — specify which with --port. Use `cc remote-control status` to list.",
+    );
+    return 4;
+  }
+  let failures = 0;
+  const results = [];
+  for (const state of candidates) {
+    let stopped = false;
+    if (state.alive) {
+      try {
+        kill(state.pid);
+        stopped = true;
+      } catch (err) {
+        failures += 1;
+        errLog(`Failed to stop pid ${state.pid}: ${err.message}`);
+      }
+    }
+    removeRemoteControlState(state.port, { dir: _deps.stateDir });
+    results.push({ port: state.port, pid: state.pid, stopped });
+    if (!options.json) {
+      log(
+        stopped
+          ? chalk.green(
+              `  ✓ stopped host on port ${state.port} (pid ${state.pid})`,
+            )
+          : chalk.gray(
+              `  · cleaned stale record for port ${state.port} (pid ${state.pid} not running)`,
+            ),
+      );
+    }
+  }
+  if (options.json) log(JSON.stringify({ results }, null, 2));
+  return failures > 0 ? 1 : 0;
+}

package/src/data/changelog.json

@@ -3,7 +3,7 @@
   "releases": [
     {
       "productVersion": "Unreleased",
-      "cliVersion": "0.162.154",
+      "cliVersion": "0.162.156",
       "cliVersions": [
         "0.4.46",
         "0.37.4",
@@ -11,11 +11,21 @@
         "0.162.151",
         "0.162.152",
         "0.162.153",
-        "0.162.154"
+        "0.162.154",
+        "0.162.155",
+        "0.162.156"
       ],
       "date": null,
       "title": "",
       "sections": [
+        {
+          "heading": "Added — cc CLI 0.162.156：agenda/batch 双命令（第四阶段收口）+ @chainlesschain/agent-sdk 0.1.0 npm 首发（CLI-only npm 发版）",
+          "body": "> `chainlesschain` 0.162.155 → **0.162.156** 发 npm `latest`（经 `npm-publish.yml`，`--provenance --access public`）；**`@chainlesschain/agent-sdk` 0.1.0 同 run 首发 npm**（平台化第三阶段产物，npm-publish.yml / release.yml 均已加发布 step，防 trap #127 漏发）。纯 `packages/cli/src`（+web-panel dist 随包）+ 新独立包，未触 `pdh/lib` → 无 Android cc bundle rollover / 无 USR_VERSION 改动。命令数 **170 → 172**（新增顶层 `agenda`/`batch`，清单已重生，13 文档面已扫）。\n\n- **`cc agenda` + notify/schedule 双 agent 工具（第四阶段批19）**：Monitor/Cron/Push 暴露为 agent 可调工具（AGENT_TOOLS 21→23）——`notify` 推送到用户已配置的多通道通知器（Telegram/企业微信/钉钉/飞书）；`schedule` 一工具五动作（wakeup/cron/monitor/list/cancel），单轮进程持不住定时器 → 意图持久化到 `~/.chainlesschain/agent-schedule/*.jsonl`（0600），由 `cc agenda list|run|cancel` 消费触发（wakeup/cron 到期 spawn `cc agent -p`，monitor 跑命令匹配 stop_when 即通知）。两工具 LOW 风险、plan 模式禁用；29 单测 + 真进程 smoke。\n- **`cc batch` 动态 worktree 批处理（第四阶段批20，第四阶段全收口）**：把大改动拆成独立单元并行跑——`--units <file>` 或 `--decompose <goal> --parts N`（agent 经 `--json-schema` 产单元 JSON，`--plan-only` 只打印）；每单元独立 git worktree（复用 `cc team --worktree` 的 worktree-isolator），`--test` 门控、`--merge` 顺序集成（后合分支与已合冲突时报告不强合、测试失败单元永不合并）；15 单测 + 2 真 git/worktree 集成测试。\n- **`@chainlesschain/agent-sdk` 0.1.0 首发**：`cc agent` stream-json 双工协议的 TypeScript 正式契约（Agent Protocol v1）——流式事件全词汇 + 审批回调（fail-closed）+ 检查点 + 会话恢复；`AgentSession` spawn 客户端（Windows `cmd.exe /c` shim + `NoDefaultCurrentDirectoryInExePath` 反劫持 + `taskkill /T` 进程树回收内置）、`attachBackgroundSession` 后台管道接管、`/browser` 浏览器安全入口（web-panel bg-\\* 帧）、`/protocol` 纯类型入口；双构建 ESM+CJS，零运行时依赖，36 测试（单元+真管道集成+真 CLI e2e）。VS Code 扩展（vendored）与 web-panel（vite alias）已消费；JetBrains 对齐语言中立 `docs/PROTOCOL.md`。用户文档 `docs-site/docs/chainlesschain/agent-sdk.md`。\n- 修复（随本版仓内，不在 cli 包面）：SDK 真 CLI e2e 抓出的两 IDE 首会话不落盘洞（IDE 重载后 resume 静默空会话）已在两插件修复，随各自下次插件发版出货。"
+        },
+        {
+          "heading": "Added — cc CLI 0.162.155：权限模式/auto 分类器 + 后台会话可交互接管全家桶（第一阶段收口，CLI-only npm 发版）",
+          "body": "> `chainlesschain` 0.162.154 → **0.162.155** 已发 npm `latest`（经 `npm-publish.yml`，`--provenance --access public`）。纯 `packages/cli/src`（+web-panel dist 随包）增量，未触 `pdh/lib` → 无 Android cc bundle rollover / 无 USR_VERSION 改动。gap-analysis「第一阶段：安全与可运营性」4 项全部落地（批 1-15，9 commit `e3ab46c73f..1618a3ca83`）。命令数 **165 → 170**（新增顶层 `attach`/`auto-mode`/`daemon`/`logs`/`remote-control`，清单已重生）。发版前本机三层全绿（unit 21808 / integration 除 1 已知 real-spawn flake 隔离 3 连绿 / e2e 628）。\n\n- **权限模式补齐 `manual`/`auto`/`dontAsk`**（headless + 交互 REPL 双面）：`manual`=default 别名；`auto`=可配置分类器——settings `autoMode.decisions` 按 riskLevel（对象/数组形）与 tool/commandPattern 细粒度规则（`*` glob，声明序优先）映射 allow/ask/deny，未配置时字节不变映射 trusted；`dontAsk`=需确认动作直接 deny 不弹审批（REPL 两处 confirmer 全覆盖）。REPL `/permissions auto|dontask` 中途切换，Shift+Tab 循环兼容；`cc agent --permission-mode` 对交互式会话生效（顺带修 `resolveAgentPolicy` 白名单静默丢弃 `--vim/--think/--fallback-model/--pdh` 等交互 flag 的预存 bug）。\n- **`cc auto-mode defaults|config [--json]`**：内置分类默认值文档 + user/project/local/managed 分层合并后的有效配置（含细粒度规则展示）；修 `mergeSandboxSettings` 数组分支把数组形 decisions 毁成 `\"[object Object]\"` 的潜伏 bug（新 `mergeAutoModeSettings`，decisions=有序规则集 closer 层整体替换）。\n- **`cc permissions recent|denials [--json|--clear]` + 决策逐层解释链**：跨会话持久 denial ring buffer（headless + REPL 双源）；被拒 run_shell 附带 `permissionChain`（settings-rules→shell-policy→approval-gate 各层判定+理由），`/permissions denials` 与 `cc permissions recent` 渲染紧凑链——一眼看清「allow 规则为何没生效」。\n- **后台会话可运营全家桶**：顶层 `cc logs <id>` / `cc attach <id>` / `cc daemon status|view|stop|rename|resume`。worker heartbeat + workerPid/agentPid 分离 + stale-heartbeat/PID-reuse 防误杀（可靠标 `lost`）；`cc daemon resume <id> <prompt>` 把崩溃/终态会话按 sessionId 续接为新后台运行（原 argv 有意不持久化防 secrets 落盘）。\n- **`cc attach` 可交互接管（session transport）**：worker 每会话托管本地 NDJSON 控制通道（Win named pipe / POSIX socket，随机 token 存 0600 state 文件）；attach 后键入即发 follow-up prompt（同 `--session` 自动续接对话史，多轮 turn 循环），`/stop` 截断当前轮，turn 运行中断开任务照跑、idle 断开会话收尾；transport 不可用自动回退日志流，`--no-input` 强制纯日志。\n- **web-panel「后台 Agent」面板**：新 `bg-*` WS 协议（list/view/attach/prompt/stop-turn/detach/stop/rename/resume，attach 期间推送 worker 事件与日志增量）；takeover token 永不过 WS 边界。面板含列表/接管卡片/日志流/重命名/续跑。\n- 修复：后台 rename 与 worker read-modify-write 竞态（写后校验+有界重试）；`settingsVerdict` 未传入 executeToolInner 的解释链断点；launcher/worker 状态竞写（先写 state 后 spawn + heartbeat 重申 transport）。\n- **`cc remote-control`（第四阶段批17，随本版一同发布）**：统一远控入口（别名 `rc`）——start/status/stop 组合既有 remote-session 栈（WS server + E2EE relay + registry + ledger + push + audit），配对 URI 双模式（relay E2EE / 直连 LAN），跨进程 0600 state 发现；顺带修 `cc serve --remote-session-relay-url` 白名单丢参从未生效的预存 bug。\n- **MCP tool search（第二阶段批16，随本版一同发布）**：大规模 MCP 面下工具定义超上下文阈值（默认窗口 10%，`mcp.toolSearch` settings / `CC_TOOL_SEARCH` env 可配）时自动换成 `[deferred]` stub + 内部 `tool_search` 检索工具；完整 schema 经 tool result 返回（append-only，保 prompt cache 稳定）；REPL `/context` 新增 MCP tool schemas 占用与优化建议一节。未超阈值/关闭时行为字节不变。"
+        },
         {
           "heading": "Added — cc CLI 0.162.154：`cc complete` 内联补全后端（IDE ghost-text）+ 本地化残留清扫（CLI-only npm 发版）",
           "body": "> `chainlesschain` 0.162.153 → **0.162.154** 已发 npm `latest`（经 `npm-publish.yml`，`--provenance --access public`）。纯 `packages/cli/src` 增量，未触 `pdh/lib` → 无 Android cc bundle rollover / 无 USR_VERSION 改动。发版动因：VS Code 0.37.7 + JetBrains 0.4.49 的内联 ghost-text 补全依赖 `cc complete`，此命令不在已发的 0.162.153 里 → 不发 npm 则两端补全功能对终端用户不可用。命令数 **164 → 165**（新增 `cc complete`，清单已重生）。发版前本机三层全绿（unit+integration+e2e）。\n\n- **`cc complete` — IDE 内联补全（fill-in-the-middle）后端**：读 stdin JSON `{prefix,suffix,language}` → 打印光标处应插入的代码（`--json` 输出 `{completion,model,provider}`）。复用 `cc ask` 的 provider 路由（`queryLLM`）——honor 用户已配置的 LLM/provider/key，零新鉴权（本地 FIM 模型如 `qwen2.5-coder` 更快，慢速 chat 模型也能用因为是手动触发）。纯可测 helper：`buildFimPrompt`（cursor-sentinel 提示让无原生 FIM 的 chat 模型也有双向上下文）+ `cleanCompletion`（剥 markdown fence / `<CURSOR>` / 硬上限 2000 字符；**故意不做 suffix-overlap 裁剪**——朴素「补全结尾等于 suffix 首行就切」会吃掉合法的结尾 token 如 `if` 块自己的 `}`，重复交给 prompt 的「勿重复周围代码」指令处理）。fail-quiet：后端故障返回空补全而非在编辑器里抛错。IDE 侧（VS Code `InlineCompletionItemProvider` / JetBrains `InlineCompletionProvider`）共享同一后端，两端行为一致。"