chainlesschain 0.162.158 → 0.162.160

package/src/command-manifest.json

@@ -1,6 +1,6 @@
 {
   "_generated": "scripts/gen-command-manifest.mjs — do not edit by hand",
-  "commandCount": 173,
+  "commandCount": 175,
   "commands": [
     {
       "name": "a2a",
@@ -177,6 +177,13 @@
       "register": "registerCliAnythingCommand",
       "summary": "CLI-Anything — discover and register Agent-native CLI tools as skills"
     },
+    {
+      "name": "cloud",
+      "aliases": [],
+      "module": "./commands/cloud.js",
+      "register": "registerCloudCommand",
+      "summary": "Self-hosted cloud handoff — offload a task to a private runner (bundle → run → reflow)"
+    },
     {
       "name": "code-intel",
       "aliases": ["ci"],
@@ -340,10 +347,10 @@
     },
     {
       "name": "doctor",
-      "aliases": [],
+      "aliases": ["checkup"],
       "module": "./commands/doctor.js",
       "register": "registerDoctorCommand",
-      "summary": "Diagnose your ChainlessChain environment"
+      "summary": "Diagnose your ChainlessChain environment (alias: checkup)"
     },
     {
       "name": "economy",
@@ -884,6 +891,13 @@
       "register": "registerOrchestrateCommand",
       "summary": "Agent router V2 governance"
     },
+    {
+      "name": "routine",
+      "aliases": [],
+      "module": "./commands/routine.js",
+      "register": "registerRoutineCommand",
+      "summary": "Named scheduled/triggered agent tasks with run history (cron/once/webhook/github)"
+    },
     {
       "name": "runtime",
       "aliases": [],

package/src/commands/agent.js

@@ -16,7 +16,10 @@ import {
 } from "../runtime/fallback-model.js";
 import { resolveImages, resolveVisionLlm } from "../lib/image-input.js";
 import { loadConfig } from "../lib/config-manager.js";
-import { normalizeAgentSandbox } from "../lib/agent-sandbox.js";
+import {
+  normalizeAgentSandbox,
+  assertSandboxAvailable,
+} from "../lib/agent-sandbox.js";
 
 /**
  * Resolve + validate `--add-dir` values into absolute, existing, de-duped
@@ -172,6 +175,14 @@ export function registerAgentCommand(program) {
       "--bare",
       "Everything --safe-mode disables PLUS skills, plugins and MCP/IDE auto-connect — minimal fast surface for scripted calls (explicit --mcp-config still loads; permission rules STAY active)",
     )
+    .option(
+      "--ephemeral",
+      "No session persistence: nothing is written to the session store (headless; a --resume id still replays history read-only)",
+    )
+    .option(
+      "--capabilities",
+      "Print a machine-readable capability manifest (JSON: protocol version, tools, permission modes, exit codes) and exit",
+    )
     .option(
       "--disable-slash-commands",
       "Interactive REPL: don't dispatch '/' input as slash commands — it reaches the model verbatim (/exit and /quit stay live)",
@@ -331,6 +342,10 @@ export function registerAgentCommand(program) {
       "--remote-control",
       "Route confirm-tier approvals to paired mobile/web devices — prints a pairing URI/QR. Headless waits for the remote allow/deny (fail-closed on timeout); interactive races the terminal prompt (first answer wins; also /remote-control)",
     )
+    .option(
+      "--channels <list>",
+      "Inbound channels for the interactive session (webhook[:port],telegram) — external events enter as user turns; webhook needs its bearer token, telegram needs channels.telegram.allowFrom",
+    )
     .option(
       "--settings <file>",
       "Merge an extra .claude/settings.json-shaped file for this run: permission rules (allow/ask/deny) + native config overrides (model, env)",
@@ -363,12 +378,31 @@ export function registerAgentCommand(program) {
       false,
     )
     .action(async (task, options, command) => {
+      // --capabilities: print the machine-readable manifest and exit — no
+      // config, no bootstrap, no network (gap-analysis 2026-07-11 快速收益 #6).
+      if (options.capabilities) {
+        const { buildAgentCapabilities } =
+          await import("../lib/headless-manifest.js");
+        console.log(JSON.stringify(buildAgentCapabilities(), null, 2));
+        return;
+      }
       // CC_API_KEY env fallback for --api-key: lets callers (IDE plugins,
       // scripts) pass the key via the environment instead of argv, where it
       // is visible to every local process (/proc/<pid>/cmdline, Win32_Process).
       // An explicit --api-key still wins.
       if (!options.apiKey && process.env.CC_API_KEY) {
         options.apiKey = process.env.CC_API_KEY;
+      } else if (
+        options.apiKey &&
+        process.argv.includes("--api-key") &&
+        !process.env.VITEST &&
+        !process.env.VITEST_WORKER_ID
+      ) {
+        // gap-analysis 2026-07-11: argv keys leak into shell history, process
+        // lists and logs — steer callers to the env/helper paths.
+        process.stderr.write(
+          "⚠️  --api-key on the command line is visible to every local process (shell history, ps). Prefer CC_API_KEY env or config llm.apiKeyHelper.\n",
+        );
       }
       const bypassPermissions = !!(
         options.allowDangerousBypass ||
@@ -826,6 +860,7 @@ export function registerAgentCommand(program) {
             outputStyle: options.outputStyle || null,
             strictMcpConfig: options.strictMcpConfig === true,
             replayUserMessages: options.replayUserMessages === true,
+            ephemeral: options.ephemeral === true,
             maxCostUsd,
             priceTable,
             chatFn: fallbackChatFn,
@@ -933,6 +968,15 @@ export function registerAgentCommand(program) {
           network: options.sandboxNetwork === true,
           settings: settingsSandbox,
         });
+        // Strict sandbox mode: failIfUnavailable refuses to START when the
+        // configured engine can't run — no silent per-command degradation.
+        try {
+          assertSandboxAvailable(agentSandbox);
+        } catch (err) {
+          process.stderr.write(`Error: ${err.message}\n`);
+          await _finishWorktree();
+          process.exit(6); // config error (see lib/exit-codes.cjs)
+        }
         // Resume requested onto a session with no headless (JSONL) transcript?
         // Warn instead of silently starting empty 鈥?headless resume rebuilds
         // from the JSONL store only (DB-only sessions are not replayable here).
@@ -1021,6 +1065,8 @@ export function registerAgentCommand(program) {
           // --settings: extra .claude/settings.json permission rules
           settingsFile: options.settings || null,
           outputStyle: options.outputStyle || null,
+          // --ephemeral: no session persistence (resume replay stays read-only)
+          ephemeral: options.ephemeral === true,
           // --max-budget-usd: hard spend cap (+ price table from config llm.pricing)
           maxCostUsd,
           priceTable,
@@ -1070,6 +1116,13 @@ export function registerAgentCommand(program) {
         return;
       }
 
+      // --ephemeral is a headless contract (the interactive REPL owns its own
+      // session lifecycle) — warn instead of silently dropping the flag.
+      if (options.ephemeral) {
+        process.stderr.write(
+          "--ephemeral is only used in headless mode (-p / a task / piped stdin); ignoring for the interactive session.\n",
+        );
+      }
       // Reached only for an interactive session, where --image has no turn to
       // attach to 鈥?warn instead of silently dropping the attachment.
       if (images.length) {
@@ -1078,6 +1131,20 @@ export function registerAgentCommand(program) {
         );
       }
 
+      // Strict sandbox mode also guards the interactive session: refuse to
+      // start when failIfUnavailable is set and the engine can't run.
+      const interactiveSandbox = normalizeAgentSandbox(options.sandbox, {
+        cwd: process.cwd(),
+        network: options.sandboxNetwork === true,
+        settings: settingsSandbox,
+      });
+      try {
+        assertSandboxAvailable(interactiveSandbox);
+      } catch (err) {
+        process.stderr.write(`Error: ${err.message}\n`);
+        process.exit(6); // config error (see lib/exit-codes.cjs)
+      }
+
       const runtime = createAgentRuntimeFactory().createAgentRuntime({
         model: options.model,
         thinking,
@@ -1099,11 +1166,7 @@ export function registerAgentCommand(program) {
         parkOnExit: options.parkOnExit, // false when --no-park-on-exit
         bundlePath: options.bundle || null,
         additionalDirectories,
-        sandbox: normalizeAgentSandbox(options.sandbox, {
-          cwd: process.cwd(),
-          network: options.sandboxNetwork === true,
-          settings: settingsSandbox,
-        }),
+        sandbox: interactiveSandbox,
         autoCheckpoint,
         // --vim: start the REPL in vim-mode editing (also CC_VIM=1 or /vim).
         vimMode: options.vim === true,
@@ -1133,6 +1196,9 @@ export function registerAgentCommand(program) {
         // --remote-control: start the paired-device approval bridge for the
         // interactive session too (terminal prompt races the device).
         remoteControl: options.remoteControl === true,
+        // --channels: inbound channel listeners (webhook/telegram) whose
+        // events become user turns in this session.
+        channels: options.channels || null,
       });
       await runtime.startAgentSession();
       // Interactive session ended (REPL closed) — settle the worktree.

package/src/commands/background-session.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import chalk from "chalk";
 import { logger } from "../lib/logger.js";
+import { readPrLinkLedger } from "../lib/pr-link-ledger.js";
 
 function formatAge(ms) {
   const n = Math.max(0, Math.round(Number(ms || 0) / 1000));
@@ -67,6 +68,11 @@ export function formatBackgroundAgentDetails(
     `  log: ${session.logFile || "-"}`,
   ];
   if (session.phase) lines.push(`  phase: ${session.phase}`);
+  if (session.pr?.number) {
+    lines.push(
+      `  pr: #${session.pr.number}${session.pr.state ? ` ${session.pr.state}` : ""}${session.pr.url ? `  ${session.pr.url}` : ""}`,
+    );
+  }
   if (Number.isFinite(Number(session.turnCount))) {
     lines.push(`  turns: ${session.turnCount}`);
   }
@@ -146,7 +152,7 @@ async function followBackgroundAgent(id, options = {}) {
  * when the transport is unavailable so the caller can fall back to the
  * log-only follow.
  */
-async function interactiveAttach(id, state, options = {}) {
+export async function interactiveAttach(id, state, options = {}) {
   const { connectBackgroundSession } =
     await import("../lib/background-session-transport.js");
   const { readBackgroundAgentLog, logPath } = await loadSupervisor();
@@ -279,6 +285,134 @@ async function interactiveAttach(id, state, options = {}) {
   return true;
 }
 
+/**
+ * `cc daemon view` (no id) — the interactive agent dashboard. Wires the real
+ * supervisor/transport into the injectable controller (repl/bg-dashboard.js).
+ * Non-TTY (or --json) degrades to the status listing.
+ */
+async function runDashboardView(options = {}) {
+  const supervisor = await loadSupervisor();
+  const {
+    listBackgroundAgents,
+    readBackgroundAgentLog,
+    stopBackgroundAgent,
+    renameBackgroundAgent,
+    setBackgroundAgentPinned,
+    resumeBackgroundAgent,
+    readBackgroundAgentState,
+    effectiveBackgroundAgentState,
+  } = supervisor;
+
+  const listAll = () => {
+    const sessions = listBackgroundAgents({ all: true });
+    // PR/session linking: decorate rows whose conversation touched a PR
+    // (`#123 open`). One ledger read per refresh; best-effort.
+    try {
+      const ledger = readPrLinkLedger();
+      for (const s of sessions) {
+        const links = s.sessionId ? ledger[s.sessionId] : null;
+        if (Array.isArray(links) && links.length > 0 && !s.pr) {
+          s.pr = [...links].sort(
+            (a, b) => (b.updatedAt || 0) - (a.updatedAt || 0),
+          )[0];
+        }
+      }
+    } catch {
+      /* PR decoration is cosmetic */
+    }
+    return sessions;
+  };
+
+  if (options.json || !process.stdout.isTTY || !process.stdin.isTTY) {
+    const sessions = listAll();
+    if (options.json) {
+      console.log(JSON.stringify({ sessions }, null, 2));
+    } else {
+      printBackgroundAgents(sessions);
+      logger.log(
+        chalk.gray("(interactive dashboard needs a TTY — showing a snapshot)"),
+      );
+    }
+    return;
+  }
+
+  const { runBgDashboard } = await import("../repl/bg-dashboard.js");
+  const { fileURLToPath } = await import("node:url");
+  const { spawn } = await import("node:child_process");
+  const BIN_PATH = fileURLToPath(
+    new URL("../../bin/chainlesschain.js", import.meta.url),
+  );
+
+  await runBgDashboard({
+    listAgents: listAll,
+    readLog: (id, lines) => {
+      try {
+        return readBackgroundAgentLog(id, { lines });
+      } catch {
+        return "";
+      }
+    },
+    stopAgent: (id) => stopBackgroundAgent(id),
+    renameAgent: (id, title) => renameBackgroundAgent(id, title),
+    pinAgent: (id, pinned) => setBackgroundAgentPinned(id, pinned),
+    replyAgent: async (session, text) => {
+      // Running with a live transport → queue a follow-up turn; otherwise
+      // continue the finished conversation as a new background session.
+      if (
+        session.status === "running" &&
+        session.transport?.pipe &&
+        session.transport?.token
+      ) {
+        const { connectBackgroundSession } =
+          await import("../lib/background-session-transport.js");
+        const conn = await connectBackgroundSession({
+          pipePath: session.transport.pipe,
+          token: session.transport.token,
+          onEvent: () => {},
+          onClose: () => {},
+        });
+        try {
+          conn.send({ type: "prompt", text });
+          // give the frame a beat to flush before closing
+          await new Promise((r) => setTimeout(r, 150));
+        } finally {
+          try {
+            conn.close();
+          } catch {
+            /* worker already closed it */
+          }
+        }
+        return;
+      }
+      resumeBackgroundAgent(session.id, text);
+    },
+    attachAgent: async (session) => {
+      const fresh = effectiveBackgroundAgentState(
+        readBackgroundAgentState(session.id),
+      );
+      if (!fresh) return;
+      if (
+        fresh.status === "running" &&
+        fresh.transport?.pipe &&
+        fresh.transport?.token
+      ) {
+        const attached = await interactiveAttach(session.id, fresh, {});
+        if (attached) return;
+      }
+      await followBackgroundAgent(session.id, { lines: 40 });
+    },
+    dispatchAgent: async (text) => {
+      const child = spawn(
+        process.execPath,
+        [BIN_PATH, "agent", "--bg", "-p", text],
+        { detached: true, stdio: "ignore", windowsHide: true },
+      );
+      child.unref();
+      return null; // id is minted by the launcher; the next refresh shows it
+    },
+  });
+}
+
 export function registerBackgroundSessionCommands(program) {
   program
     .command("logs <id>")
@@ -378,12 +512,18 @@ export function registerBackgroundSessionCommands(program) {
     });
 
   daemon
-    .command("view <id>")
-    .description("Show a detailed background agent view")
+    .command("view [id]")
+    .description(
+      "Detailed view of one background agent, or the interactive agent dashboard when no id is given",
+    )
     .option("-n, --lines <n>", "Recent log lines to include", "40")
     .option("--json", "Output as JSON")
     .action(async (id, options) => {
       try {
+        if (!id) {
+          await runDashboardView(options);
+          return;
+        }
         const {
           readBackgroundAgentState,
           effectiveBackgroundAgentState,
@@ -457,6 +597,36 @@ export function registerBackgroundSessionCommands(program) {
       }
     });
 
+  // daemon rm — record cleanup (gap-analysis 2026-07-11 P0 后台 Supervisor).
+  daemon
+    .command("rm <id>")
+    .description(
+      "Remove a finished background agent's record + log (running agents need --force; the conversation session itself is untouched)",
+    )
+    .option("--force", "Stop a still-running agent first, then remove")
+    .option("--keep-log", "Keep the log file, remove only the state record")
+    .option("--json", "Output as JSON")
+    .action(async (id, options) => {
+      try {
+        const { removeBackgroundAgent } = await loadSupervisor();
+        const result = removeBackgroundAgent(id, {
+          force: options.force === true,
+          keepLog: options.keepLog === true,
+        });
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+        logger.log(
+          chalk.green(`Removed background agent ${result.id}`) +
+            chalk.gray(` (was ${result.status})`),
+        );
+      } catch (error) {
+        logger.error(chalk.red(error.message));
+        process.exitCode = 1;
+      }
+    });
+
   daemon
     .command("stop [id]")
     .description("Stop one background agent, or all running agents with --any")

package/src/commands/browse.js

@@ -391,6 +391,92 @@ export function registerBrowseChromeCommand(browse) {
         logger.success(`Screenshot: ${state.screenshotPath}`);
       }
     });
+
+  chrome
+    .command("act")
+    .description(
+      "Perform EXPLICIT actions (click/type/press/navigate/waitForSelector/screenshot/assertText) in the connected Chrome — unlike 'state', this DRIVES your logged-in browser",
+    )
+    .option("-p, --port <port>", "CDP port", "9222")
+    .option("-t, --tab <n>", "Tab index", "0")
+    .requiredOption(
+      "--actions <json|@file>",
+      'JSON array of steps, e.g. \'[{"type":"click","selector":"#go"}]\', or @steps.json',
+    )
+    .option(
+      "--continue-on-error",
+      "Keep executing the remaining steps after a failed one (default: fail fast)",
+    )
+    .option("--json", "Output as JSON")
+    .action(async (options) => {
+      const { discoverCdp, performActions } =
+        await import("../lib/chrome-connector.js");
+      const port = numericOption(options.port, {
+        name: "--port",
+        integer: true,
+        min: 1,
+        fallback: 9222,
+      });
+      let actions;
+      try {
+        const raw = options.actions.startsWith("@")
+          ? (await import("fs")).readFileSync(options.actions.slice(1), "utf-8")
+          : options.actions;
+        actions = JSON.parse(raw);
+      } catch (err) {
+        logger.error(
+          `--actions must be a JSON array (or @file.json): ${err.message}`,
+        );
+        process.exit(1);
+      }
+      // Refuse outright when nothing is listening — an action command must
+      // never silently no-op or launch a browser on its own.
+      const probe = await discoverCdp({ port });
+      if (!probe.ok) {
+        const msg = `No debuggable Chrome on port ${port} — refusing to act. Start one first: cc browse chrome launch`;
+        if (options.json) {
+          console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+        } else {
+          logger.error(msg);
+        }
+        process.exitCode = 1;
+        return;
+      }
+      const res = await performActions(actions, {
+        port,
+        tab: numericOption(options.tab, {
+          name: "--tab",
+          integer: true,
+          min: 0,
+          fallback: 0,
+        }),
+        continueOnError: options.continueOnError === true,
+      });
+      if (options.json) {
+        console.log(JSON.stringify(res, null, 2));
+        if (!res.ok) process.exitCode = 1;
+        return;
+      }
+      if (res.error) {
+        logger.error(res.error);
+        process.exitCode = 1;
+        return;
+      }
+      if (res.profileWarning) logger.warn(res.profileWarning);
+      for (const step of res.steps) {
+        const mark = step.ok ? chalk.green("ok") : chalk.red("FAIL");
+        logger.log(
+          `  [${mark}] ${step.action} ${chalk.gray(`(${step.durationMs}ms)`)} ${step.detail}`,
+        );
+      }
+      logger.log(
+        `  ${res.executed}/${actions.length} step(s) executed → ${chalk.cyan(res.url)}${res.title ? ` (${res.title})` : ""}`,
+      );
+      if (res.auditError) {
+        logger.warn(`audit log write failed: ${res.auditError}`);
+      }
+      if (!res.ok) process.exitCode = 1;
+    });
 }
 
 import {