chainlesschain 0.162.155 → 0.162.157

package/src/gateways/ws/artifact-protocol.js

@@ -0,0 +1,219 @@
+/**
+ * artifact WS protocol — exposes the agent-published deliverable store
+ * (lib/artifact-store.js, P1 #10) to web-panel / IDE clients so an
+ * "Artifacts" panel can list deliverables, preview them (text inline /
+ * images as base64), and manage retention.
+ *
+ * Routes (request → reply):
+ *   artifact-list    {session?, kind?}         → {type:"artifact-list", artifacts}
+ *   artifact-show    {artifactId}              → {type:"artifact-show", artifact}
+ *   artifact-content {artifactId, maxBytes?}   → {type:"artifact-content", artifactId,
+ *                                                 mime, encoding, content, size,
+ *                                                 truncated, previewable}
+ *   artifact-remove  {artifactId}              → {type:"artifact-remove", removed, found}
+ *   artifact-clean   {}                        → {type:"artifact-clean", removed}
+ *
+ * Preview policy: text mimes stream as utf8 (capped, `truncated` flagged);
+ * images as base64 (hard cap — an oversized image reports previewable:false
+ * instead of flooding the socket); everything else is metadata-only
+ * (previewable:false, the user has `cc artifacts open <id>` locally).
+ *
+ * The stored-copy filename comes from index.jsonl; serving is refused if it
+ * is not a plain basename, so a hand-tampered index row can never turn the
+ * content route into an arbitrary-file read.
+ */
+
+import path from "node:path";
+import { readFileSync, statSync } from "node:fs";
+
+/** Text preview cap (utf8 chars ≈ bytes for the common case). */
+export const TEXT_PREVIEW_CAP = 256 * 1024;
+/** Image preview cap — beyond this the panel gets metadata only. */
+export const IMAGE_PREVIEW_CAP = 8 * 1024 * 1024;
+
+const TEXT_APPLICATION_MIMES = new Set([
+  "application/json",
+  "application/yaml",
+  "application/xml",
+]);
+
+async function loadStore() {
+  const { ArtifactStore } = await import("../../lib/artifact-store.js");
+  return new ArtifactStore();
+}
+
+function sendError(server, id, ws, code, message) {
+  server._send(ws, { id, type: "error", code, message });
+}
+
+/** Classify how (whether) an artifact can be previewed inline. */
+export function previewKindForMime(mime) {
+  const m = String(mime || "").toLowerCase();
+  if (m.startsWith("text/") || TEXT_APPLICATION_MIMES.has(m)) return "text";
+  if (m.startsWith("image/")) return "image";
+  return "none";
+}
+
+export async function handleArtifactList(server, id, ws, message) {
+  try {
+    const store = await loadStore();
+    let artifacts = store.list({ sessionId: message.session || undefined });
+    if (message.kind) {
+      artifacts = artifacts.filter((e) => e.kind === String(message.kind));
+    }
+    server._send(ws, { id, type: "artifact-list", artifacts });
+  } catch (err) {
+    sendError(server, id, ws, "ARTIFACT_LIST_FAILED", err.message);
+  }
+}
+
+export async function handleArtifactShow(server, id, ws, message) {
+  try {
+    if (!message.artifactId) {
+      return sendError(server, id, ws, "NO_ARTIFACT_ID", "artifactId required");
+    }
+    const store = await loadStore();
+    const entry = store.get(message.artifactId);
+    if (!entry) {
+      return sendError(
+        server,
+        id,
+        ws,
+        "ARTIFACT_NOT_FOUND",
+        `Artifact not found: ${message.artifactId}`,
+      );
+    }
+    server._send(ws, {
+      id,
+      type: "artifact-show",
+      artifact: { ...entry, storedPath: store.storedPath(entry) },
+    });
+  } catch (err) {
+    sendError(server, id, ws, "ARTIFACT_SHOW_FAILED", err.message);
+  }
+}
+
+export async function handleArtifactContent(server, id, ws, message) {
+  try {
+    if (!message.artifactId) {
+      return sendError(server, id, ws, "NO_ARTIFACT_ID", "artifactId required");
+    }
+    const store = await loadStore();
+    const entry = store.get(message.artifactId);
+    if (!entry) {
+      return sendError(
+        server,
+        id,
+        ws,
+        "ARTIFACT_NOT_FOUND",
+        `Artifact not found: ${message.artifactId}`,
+      );
+    }
+    // Traversal guard: the stored filename must be a plain basename. A
+    // tampered index row ("file":"../../secret") must not read outside the
+    // files dir.
+    if (
+      !entry.file ||
+      entry.file !== path.basename(entry.file) ||
+      entry.file.includes("..")
+    ) {
+      return sendError(
+        server,
+        id,
+        ws,
+        "ARTIFACT_BAD_FILE",
+        "artifact index row has a non-basename stored filename — refusing to serve it",
+      );
+    }
+    const previewKind = previewKindForMime(entry.mime);
+    const base = {
+      id,
+      type: "artifact-content",
+      artifactId: entry.id,
+      mime: entry.mime,
+      size: entry.size,
+    };
+    if (previewKind === "none") {
+      return server._send(ws, {
+        ...base,
+        previewable: false,
+        reason: `no inline preview for ${entry.mime} — use \`cc artifacts open ${entry.id}\` locally`,
+      });
+    }
+    const storedPath = store.storedPath(entry);
+    let actualSize;
+    try {
+      actualSize = statSync(storedPath).size;
+    } catch {
+      return sendError(
+        server,
+        id,
+        ws,
+        "ARTIFACT_FILE_MISSING",
+        `stored copy is missing: ${entry.file}`,
+      );
+    }
+    if (previewKind === "image") {
+      if (actualSize > IMAGE_PREVIEW_CAP) {
+        return server._send(ws, {
+          ...base,
+          previewable: false,
+          reason: `image exceeds the ${IMAGE_PREVIEW_CAP} byte preview cap`,
+        });
+      }
+      const body = readFileSync(storedPath);
+      return server._send(ws, {
+        ...base,
+        previewable: true,
+        encoding: "base64",
+        truncated: false,
+        content: body.toString("base64"),
+      });
+    }
+    // text
+    const cap = Math.min(
+      Number(message.maxBytes) > 0 ? Number(message.maxBytes) : TEXT_PREVIEW_CAP,
+      TEXT_PREVIEW_CAP,
+    );
+    const text = readFileSync(storedPath, "utf-8");
+    const truncated = text.length > cap;
+    server._send(ws, {
+      ...base,
+      previewable: true,
+      encoding: "utf8",
+      truncated,
+      content: truncated ? text.slice(0, cap) : text,
+    });
+  } catch (err) {
+    sendError(server, id, ws, "ARTIFACT_CONTENT_FAILED", err.message);
+  }
+}
+
+export async function handleArtifactRemove(server, id, ws, message) {
+  try {
+    if (!message.artifactId) {
+      return sendError(server, id, ws, "NO_ARTIFACT_ID", "artifactId required");
+    }
+    const store = await loadStore();
+    const found = store.remove(message.artifactId);
+    server._send(ws, {
+      id,
+      type: "artifact-remove",
+      artifactId: message.artifactId,
+      removed: found ? message.artifactId : null,
+      found,
+    });
+  } catch (err) {
+    sendError(server, id, ws, "ARTIFACT_REMOVE_FAILED", err.message);
+  }
+}
+
+export async function handleArtifactClean(server, id, ws, message) {
+  try {
+    const store = await loadStore();
+    const { removed } = store.cleanupExpired();
+    server._send(ws, { id, type: "artifact-clean", removed });
+  } catch (err) {
+    sendError(server, id, ws, "ARTIFACT_CLEAN_FAILED", err.message);
+  }
+}

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

@@ -185,6 +185,12 @@ export function createWsMessageDispatcher(server) {
         "bg-stop": () => server._handleBgStop(clientId, id, ws, message),
         "bg-rename": () => server._handleBgRename(id, ws, message),
         "bg-resume": () => server._handleBgResume(id, ws, message),
+        "artifact-list": () => server._handleArtifactList(id, ws, message),
+        "artifact-show": () => server._handleArtifactShow(id, ws, message),
+        "artifact-content": () =>
+          server._handleArtifactContent(id, ws, message),
+        "artifact-remove": () => server._handleArtifactRemove(id, ws, message),
+        "artifact-clean": () => server._handleArtifactClean(id, ws, message),
         "chat.intent.understand": () =>
           server._handleChatIntentUnderstand(id, ws, message),
         "chat.intent.understand-stream": () =>

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

@@ -106,6 +106,13 @@ import {
   handleBgStopTurn,
   handleBgView,
 } from "./background-agent-protocol.js";
+import {
+  handleArtifactClean,
+  handleArtifactContent,
+  handleArtifactList,
+  handleArtifactRemove,
+  handleArtifactShow,
+} from "./artifact-protocol.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -717,6 +724,31 @@ export class ChainlessChainWSServer extends EventEmitter {
     return handleBgResume(this, id, ws, message);
   }
 
+  /** @private — list agent-published artifacts (metadata only) */
+  async _handleArtifactList(id, ws, message) {
+    return handleArtifactList(this, id, ws, message);
+  }
+
+  /** @private — one artifact's metadata + stored path */
+  async _handleArtifactShow(id, ws, message) {
+    return handleArtifactShow(this, id, ws, message);
+  }
+
+  /** @private — inline preview content (text utf8 / image base64, capped) */
+  async _handleArtifactContent(id, ws, message) {
+    return handleArtifactContent(this, id, ws, message);
+  }
+
+  /** @private — remove one artifact (stored copy + index row) */
+  async _handleArtifactRemove(id, ws, message) {
+    return handleArtifactRemove(this, id, ws, message);
+  }
+
+  /** @private — drop expired artifacts (TTL) */
+  async _handleArtifactClean(id, ws, message) {
+    return handleArtifactClean(this, id, ws, message);
+  }
+
   /** @private */
   async _handleCompressionStats(id, ws, message) {
     return handleCompressionStats(this, id, ws, message);

package/src/index.js

@@ -156,6 +156,15 @@ import { registerServeCommand } from "./commands/serve.js";
 // Remote Control unified entry (第四阶段 #1)
 import { registerRemoteControlCommand } from "./commands/remote-control.js";
 
+// Agenda: consumer for agent-scheduled wakeups/crons/monitors (第四阶段 #3)
+import { registerAgendaCommand } from "./commands/agenda.js";
+
+// Batch: dynamic worktree batch — split a change into parallel units (第四阶段 #4)
+import { registerBatchCommand } from "./commands/batch.js";
+
+// Artifacts: agent-published deliverable store (P1 #10)
+import { registerArtifactsCommand } from "./commands/artifacts.js";
+
 // Web UI
 import { registerUiCommand } from "./commands/ui.js";
 import { registerPackCommand } from "./commands/pack.js";
@@ -586,6 +595,15 @@ export function createProgram(opts = {}) {
   // Remote Control unified entry
   registerRemoteControlCommand(program);
 
+  // Agenda: fire agent-scheduled wakeups/crons/monitors
+  registerAgendaCommand(program);
+
+  // Batch: dynamic worktree batch
+  registerBatchCommand(program);
+
+  // Artifacts: agent-published deliverable store
+  registerArtifactsCommand(program);
+
   // Web UI
   registerUiCommand(program);
 

package/src/lib/accessibility.js

@@ -0,0 +1,55 @@
+/**
+ * `cc agent --ax-screen-reader` — screen-reader friendly output.
+ *
+ * Screen readers linearize the terminal: colors are invisible, and anything
+ * that repaints in place (the context status line) reads as noisy duplicate
+ * lines. This mode therefore:
+ *   - forces the `mono` theme (chalk level 0 — no ANSI color codes) in the
+ *     interactive REPL (consumed via CC_SCREEN_READER in agent-repl.js);
+ *   - disables the repainting status line (reuses the existing
+ *     CC_STATUSLINE=0 kill-switch).
+ * Headless (-p) text output is already plain sequential lines.
+ *
+ * Ambient activation: CC_SCREEN_READER=1 (so wrappers/launchers can turn it
+ * on without threading a flag through every entry point).
+ */
+
+/** env switches applied by --ax-screen-reader. */
+export const SCREEN_READER_SWITCHES = Object.freeze({
+  CC_SCREEN_READER: "1", // REPL: force mono theme / no ANSI decorations
+  CC_STATUSLINE: "0", // in-place repainting status line off
+});
+
+/**
+ * Apply screen-reader mode to an env (default process.env).
+ * @returns {string[]} the switch names applied (for the startup notice)
+ */
+export function applyScreenReaderMode(env = process.env) {
+  for (const [k, v] of Object.entries(SCREEN_READER_SWITCHES)) {
+    env[k] = v;
+  }
+  return Object.keys(SCREEN_READER_SWITCHES);
+}
+
+/**
+ * Whether screen-reader mode is requested — the explicit `--ax-screen-reader`
+ * flag or the ambient CC_SCREEN_READER env var (1 / true / yes / on).
+ * @param {{ axScreenReader?: boolean }} [opts]
+ * @param {object} [env=process.env]
+ * @returns {boolean}
+ */
+export function screenReaderRequested(opts = {}, env = process.env) {
+  if (opts && opts.axScreenReader === true) return true;
+  return screenReaderActive(env);
+}
+
+/**
+ * Whether screen-reader mode is ACTIVE in the environment (what downstream
+ * consumers — the REPL theme init — should check).
+ * @param {object} [env=process.env]
+ * @returns {boolean}
+ */
+export function screenReaderActive(env = process.env) {
+  const raw = env.CC_SCREEN_READER;
+  return raw != null && /^(1|true|yes|on)$/i.test(String(raw).trim());
+}

package/src/lib/agent-batch.js

@@ -0,0 +1,235 @@
+/**
+ * agent-batch — dynamic worktree batch core (gap-analysis 第四阶段 #4).
+ *
+ * Takes a large task already decomposed into independent UNITS and runs each in
+ * its OWN git worktree, in parallel (bounded concurrency), then aggregates the
+ * outcome: per-unit agent status, test result, diff stat, and — on integration
+ * — a merge-conflict preview against base. This is the `/batch` shape from
+ * Claude Code, built on the same worktree isolation `cc team --worktree` uses.
+ *
+ * Pure over injected deps (worktree lifecycle, agent/test spawns, git) so the
+ * whole fan-out + aggregation is unit-testable without a real repo or LLM.
+ *
+ * A `unit` is `{ key, prompt, test? }`. Concurrency is a simple worker pool.
+ * Integration is SEQUENTIAL (like TeamWorktreeCoordinator.integrate) so a later
+ * branch that conflicts with an already-merged one is reported, not clobbered.
+ */
+
+/** Run `items` through `worker` with at most `limit` in flight; preserves order. */
+async function mapPool(items, limit, worker) {
+  const results = new Array(items.length);
+  let next = 0;
+  const runners = new Array(Math.max(1, Math.min(limit, items.length)))
+    .fill(0)
+    .map(async () => {
+      while (true) {
+        const i = next++;
+        if (i >= items.length) return;
+        results[i] = await worker(items[i], i);
+      }
+    });
+  await Promise.all(runners);
+  return results;
+}
+
+function normalizeUnits(units) {
+  if (!Array.isArray(units) || units.length === 0) {
+    throw new Error("batch requires a non-empty `units` array");
+  }
+  const seen = new Set();
+  return units.map((u, i) => {
+    const key = String(u.key || `unit-${i + 1}`);
+    if (seen.has(key)) throw new Error(`duplicate unit key "${key}"`);
+    seen.add(key);
+    if (!u.prompt || typeof u.prompt !== "string") {
+      throw new Error(`unit "${key}" has no prompt`);
+    }
+    return { key, prompt: u.prompt, test: u.test || null };
+  });
+}
+
+/**
+ * @param {object} opts
+ * @param {Array<{key,prompt,test?}>} opts.units
+ * @param {number} [opts.concurrency=4]
+ * @param {string} [opts.test]         default test command for units without one
+ * @param {boolean} [opts.merge]       merge clean branches back to base
+ * @param {(msg:object)=>void} [opts.onEvent]  progress callback
+ * @param {object} deps  injected effectful ops (see command wiring)
+ * @returns {Promise<{units:Array, summary:object}>}
+ */
+export async function runBatch(opts, deps) {
+  const units = normalizeUnits(opts.units);
+  const concurrency = Math.max(1, Number(opts.concurrency) || 4);
+  const onEvent = opts.onEvent || (() => {});
+  const {
+    createWorktree,
+    removeWorktree,
+    runAgent,
+    runTest,
+    diffStat,
+    commit,
+    previewMerge,
+    mergeBranch,
+    branchFor = (key) => `batch/${key}`,
+  } = deps;
+
+  onEvent({ type: "batch:start", units: units.length, concurrency });
+
+  const results = await mapPool(units, concurrency, async (unit) => {
+    const branch = branchFor(unit.key);
+    const record = {
+      key: unit.key,
+      branch,
+      status: "pending",
+      filesChanged: 0,
+      insertions: 0,
+      deletions: 0,
+      testCommand: unit.test || opts.test || null,
+      testPassed: null,
+      committed: false,
+      error: null,
+    };
+    let worktreePath = null;
+    try {
+      worktreePath = createWorktree(unit.key, branch);
+      onEvent({ type: "unit:start", key: unit.key, branch });
+      await runAgent(unit.prompt, worktreePath);
+
+      const stat = diffStat(worktreePath);
+      record.filesChanged = stat.filesChanged;
+      record.insertions = stat.insertions;
+      record.deletions = stat.deletions;
+
+      const testCmd = unit.test || opts.test || null;
+      if (testCmd) {
+        try {
+          await runTest(testCmd, worktreePath);
+          record.testPassed = true;
+        } catch (err) {
+          record.testPassed = false;
+          record.testError = err.message;
+        }
+      }
+
+      if (stat.filesChanged > 0) {
+        record.committed = commit(worktreePath, `batch: ${unit.key}`);
+      }
+      // A unit whose tests FAILED is reported failed even though its worktree
+      // committed — integration below skips non-passing units so a red unit
+      // never merges into base.
+      record.status =
+        record.testPassed === false
+          ? "test-failed"
+          : record.filesChanged === 0
+            ? "no-changes"
+            : "done";
+    } catch (err) {
+      record.status = "error";
+      record.error = err.message;
+    }
+    onEvent({
+      type: "unit:done",
+      key: unit.key,
+      status: record.status,
+      testPassed: record.testPassed,
+      filesChanged: record.filesChanged,
+    });
+    return { record, worktreePath };
+  });
+
+  // Sequential integration: only units that DID change, committed, and did not
+  // fail tests are eligible. Preview each; merge clean ones when --merge.
+  for (const { record } of results) {
+    if (!record.committed || record.status === "test-failed") {
+      record.integration = { eligible: false, reason: record.status };
+      continue;
+    }
+    let preview;
+    try {
+      preview = previewMerge(record.branch);
+    } catch (err) {
+      record.integration = {
+        eligible: true,
+        clean: false,
+        merged: false,
+        conflicts: [],
+        error: err.message,
+      };
+      continue;
+    }
+    const clean = preview?.success === true;
+    const conflicts = preview?.conflicts || [];
+    let merged = false;
+    if (clean && opts.merge) {
+      let mergeResult;
+      try {
+        mergeResult = mergeBranch(record.branch, `Merge batch ${record.key}`);
+      } catch (err) {
+        mergeResult = { success: false, message: err.message };
+      }
+      merged = mergeResult?.success === true;
+      if (!merged && (!conflicts || conflicts.length === 0)) {
+        record.integration = {
+          eligible: true,
+          clean,
+          merged,
+          conflicts: mergeResult?.conflicts || [],
+          error: mergeResult?.message || null,
+        };
+        continue;
+      }
+    }
+    record.integration = { eligible: true, clean, merged, conflicts };
+    onEvent({
+      type: "unit:integrated",
+      key: record.key,
+      clean,
+      merged,
+      conflicts: conflicts.length,
+    });
+  }
+
+  // Best-effort teardown of every worktree we created (branches persist for the
+  // user to inspect/merge later unless already merged).
+  if (typeof removeWorktree === "function") {
+    for (const { record, worktreePath } of results) {
+      if (!worktreePath) continue;
+      try {
+        removeWorktree(worktreePath, {
+          deleteBranch: record.integration?.merged === true,
+        });
+      } catch {
+        // best-effort — a leftover worktree is recoverable via `git worktree`
+      }
+    }
+  }
+
+  const records = results.map((r) => r.record);
+  const summary = summarize(records);
+  onEvent({ type: "batch:done", ...summary });
+  return { units: records, summary };
+}
+
+function summarize(records) {
+  const summary = {
+    total: records.length,
+    done: 0,
+    testFailed: 0,
+    noChanges: 0,
+    errored: 0,
+    merged: 0,
+    conflicted: 0,
+  };
+  for (const r of records) {
+    if (r.status === "done") summary.done += 1;
+    else if (r.status === "test-failed") summary.testFailed += 1;
+    else if (r.status === "no-changes") summary.noChanges += 1;
+    else if (r.status === "error") summary.errored += 1;
+    if (r.integration?.merged) summary.merged += 1;
+    if (r.integration?.conflicts?.length) summary.conflicted += 1;
+  }
+  return summary;
+}
+
+export const _internal = { mapPool, normalizeUnits, summarize };

package/src/lib/agent-notify.js

@@ -0,0 +1,66 @@
+/**
+ * agent-notify — shared backing for the `notify` agent tool + `cc agenda`
+ * monitor firing (gap-analysis 第四阶段 #3).
+ *
+ * Fans a notification out over the user's configured multi-channel notifiers
+ * (Telegram / WeCom / DingTalk / Feishu, via NotificationManager.fromEnv) and,
+ * when a paired-device push descriptor exists, the mobile push bridge. Pure
+ * over injected deps so it is unit-testable without any network.
+ */
+
+import { NotificationManager } from "./notifiers/index.js";
+
+/**
+ * @param {{title:string, body?:string, level?:"info"|"success"|"failure"}} msg
+ * @param {{env?:object, manager?:object}} [deps]
+ * @returns {Promise<{delivered:string[], failed:string[], channels:number, results:Array}>}
+ */
+export async function sendAgentNotification(msg, deps = {}) {
+  const title = String(msg?.title || "").trim();
+  if (!title) throw new Error("notify requires a title");
+  const body = msg?.body ? String(msg.body) : "";
+  const level = ["info", "success", "failure"].includes(msg?.level)
+    ? msg.level
+    : "info";
+
+  const manager =
+    deps.manager ||
+    NotificationManager.fromEnv({ env: deps.env || process.env });
+  if (!manager.isConfigured) {
+    return {
+      delivered: [],
+      failed: [],
+      channels: 0,
+      results: [],
+      note: "No notification channels configured (set TELEGRAM_BOT_TOKEN / WECOM_WEBHOOK_URL / DINGTALK_WEBHOOK_URL / FEISHU_WEBHOOK_URL).",
+    };
+  }
+
+  const summary = {
+    taskId: msg?.taskId || null,
+    description: title,
+    detail: body,
+    message: body || title,
+    title,
+  };
+  const method =
+    level === "success"
+      ? "notifySuccess"
+      : level === "failure"
+        ? "notifyFailure"
+        : "notifyStart";
+  const results = await manager[method](summary);
+
+  const delivered = [];
+  const failed = [];
+  for (const r of results || []) {
+    if (r && r.ok !== false) delivered.push(r.channel);
+    else failed.push(r?.channel || "unknown");
+  }
+  return {
+    delivered,
+    failed,
+    channels: (manager.activeChannels || []).length,
+    results: results || [],
+  };
+}