@chorus-aidlc/chorus 0.9.4 → 0.11.0

package/cli/daemon-lifecycle.mjs

@@ -0,0 +1,191 @@
+// cli/daemon-lifecycle.mjs
+// Background (`-d`) run + lifecycle subcommands (stop/status/restart/logs) for
+// `chorus daemon`. Pure Node, cross-platform, NO native dependencies and NO
+// `shell:true` — mirrors the platform-gated spawn approach in claude-spawner.mjs
+// (POSIX detached process-group leader + unref + stdio→logfile; Windows
+// windowsHide, no new console). All IO is injectable so both platform branches
+// are unit-testable from a single host.
+//
+// State files live alongside the credentials in ~/.chorus:
+//   pidfile  ~/.chorus/daemon.pid   (the background daemon's pid)
+//   logfile  ~/.chorus/daemon.log   (its redirected stdout+stderr)
+
+import { spawn } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/** Default IO bundle — overridable per-call for tests (no real disk/process). */
+function defaultIO() {
+  return {
+    existsSync,
+    mkdirSync,
+    openSync,
+    readFileSync,
+    unlinkSync,
+    writeFileSync,
+    spawn,
+    // process.kill with signal 0 is the portable liveness probe (no signal sent).
+    kill: (pid, sig) => process.kill(pid, sig),
+    platform: process.platform,
+    home: homedir(),
+  };
+}
+
+/** ~/.chorus/daemon.pid */
+export function pidFilePath(io = defaultIO()) {
+  return join(io.home ?? homedir(), ".chorus", "daemon.pid");
+}
+
+/** ~/.chorus/daemon.log */
+export function logFilePath(io = defaultIO()) {
+  return join(io.home ?? homedir(), ".chorus", "daemon.log");
+}
+
+/**
+ * Read the recorded pid, or null when absent / unreadable / malformed.
+ * @param {object} [io]
+ * @returns {number|null}
+ */
+export function readPid(io = defaultIO()) {
+  const path = pidFilePath(io);
+  try {
+    if (!io.existsSync(path)) return null;
+    const raw = io.readFileSync(path, "utf8");
+    const pid = Number.parseInt(String(raw).trim(), 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Is `pid` a live process? Uses signal 0 (sends nothing; throws ESRCH when the
+ * pid is gone, EPERM when alive-but-not-ours → still "alive").
+ * @param {number} pid @param {object} [io]
+ */
+export function processAlive(pid, io = defaultIO()) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    io.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err && err.code === "EPERM";
+  }
+}
+
+/**
+ * Current daemon status from the pidfile.
+ * @param {object} [io]
+ * @returns {{ running: boolean, pid: number|null, stale: boolean }}
+ *   `stale` = a pidfile exists but its pid is dead (left behind by a crash).
+ */
+export function isRunning(io = defaultIO()) {
+  const pid = readPid(io);
+  if (pid == null) return { running: false, pid: null, stale: false };
+  const alive = processAlive(pid, io);
+  return { running: alive, pid, stale: !alive };
+}
+
+/** Ensure ~/.chorus exists for the pid/log files. */
+function ensureDir(path, io) {
+  io.mkdirSync(dirname(path), { recursive: true });
+}
+
+/**
+ * Spawn the daemon DETACHED in the background. The caller has already completed
+ * any interactive preflight (credential completion + yolo confirm) in the
+ * foreground, so the child starts non-interactively. stdout+stderr are
+ * redirected to the logfile; the child pid is written to the pidfile; the child
+ * is unref'd so the parent can exit.
+ *
+ * Refuses to start a second daemon when a live pid is already recorded (returns
+ * `{ started:false, alreadyRunning:true, pid }`). A stale pidfile (dead pid) is
+ * overwritten.
+ *
+ * @param {{ nodePath: string, args: string[], env?: Record<string,string|undefined>, cwd?: string }} spec
+ *   `nodePath` (e.g. process.execPath) runs `args` (e.g. ["/path/chorus.mjs","daemon",...]
+ *   WITHOUT `-d`). The env should carry the detached marker so the child skips preflight.
+ * @param {object} [io]
+ * @returns {{ started: boolean, pid?: number, alreadyRunning?: boolean, logFile: string, pidFile: string }}
+ */
+export function startBackground(spec, io = defaultIO()) {
+  const pidFile = pidFilePath(io);
+  const logFile = logFilePath(io);
+
+  const status = isRunning(io);
+  if (status.running) {
+    return { started: false, alreadyRunning: true, pid: status.pid, logFile, pidFile };
+  }
+
+  ensureDir(logFile, io);
+  // Append so restarts keep history; the child owns the fd after spawn.
+  const out = io.openSync(logFile, "a");
+
+  const child = io.spawn(spec.nodePath, spec.args, {
+    cwd: spec.cwd ?? process.cwd(),
+    env: { ...(spec.env ?? {}) },
+    // POSIX: detached:true makes the child a process-group leader so it survives
+    // the parent and the controlling terminal closing. Windows: detached spawns
+    // its own process group too; windowsHide prevents a new console window.
+    detached: true,
+    windowsHide: true,
+    // No stdin; stdout+stderr → the logfile fd. shell:false (default) — no shell
+    // word-splitting / injection surface (args is an array).
+    stdio: ["ignore", out, out],
+  });
+
+  // Let the parent exit without waiting on the child (POSIX + Windows).
+  child.unref?.();
+
+  ensureDir(pidFile, io);
+  io.writeFileSync(pidFile, `${child.pid}\n`, { mode: 0o600 });
+  return { started: true, pid: child.pid, logFile, pidFile };
+}
+
+/**
+ * Stop the recorded background daemon: signal it, then remove the pidfile.
+ * @param {object} [io]
+ * @returns {{ stopped: boolean, pid: number|null, reason: "stopped"|"not-running"|"stale-cleared"|"error", message: string }}
+ */
+export function stopDaemon(io = defaultIO()) {
+  const pidFile = pidFilePath(io);
+  const status = isRunning(io);
+  if (status.pid == null) {
+    return { stopped: false, pid: null, reason: "not-running", message: "no daemon is running (no pidfile)" };
+  }
+  if (!status.running) {
+    // Stale pidfile — clean it up, report clearly (no silent failure).
+    try { io.unlinkSync(pidFile); } catch { /* best-effort */ }
+    return { stopped: false, pid: status.pid, reason: "stale-cleared", message: `no live daemon (cleared stale pidfile for pid ${status.pid})` };
+  }
+  try {
+    io.kill(status.pid, "SIGTERM");
+  } catch (err) {
+    return { stopped: false, pid: status.pid, reason: "error", message: `failed to signal pid ${status.pid}: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  try { io.unlinkSync(pidFile); } catch { /* best-effort */ }
+  return { stopped: true, pid: status.pid, reason: "stopped", message: `stopped daemon (pid ${status.pid})` };
+}
+
+/**
+ * Read the daemon logfile contents (for `chorus daemon logs`).
+ * @param {object} [io]
+ * @returns {{ ok: boolean, content?: string, message?: string }}
+ */
+export function readLog(io = defaultIO()) {
+  const logFile = logFilePath(io);
+  try {
+    if (!io.existsSync(logFile)) return { ok: false, message: `no log file at ${logFile}` };
+    return { ok: true, content: io.readFileSync(logFile, "utf8") };
+  } catch (err) {
+    return { ok: false, message: `could not read ${logFile}: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}

package/cli/daemon-permission-mode.mjs

@@ -0,0 +1,68 @@
+// cli/daemon-permission-mode.mjs
+// Pure resolution of the daemon's permission posture for the woken agent.
+// The DEFAULT is now `yolo` (full autonomy) — reversing the prior `chorus`-only
+// default. No confirmation needed; the startup banner prominently warns users
+// and shows how to opt out with --chorus-only.
+//
+// This module is PURE: `resolvePermissionMode` does no IO and returns a
+// decision object. Zero dependencies — ships in the npm package alongside chorus.mjs.
+
+/**
+ * @typedef {"yolo"|"chorus"} PermissionMode
+ *   "yolo"   → woken agent gets full autonomy (--dangerously-skip-permissions).
+ *   "chorus" → restricted: only mcp__chorus__* tools (no Bash / file edits).
+ */
+
+/**
+ * @typedef {Object} PermissionDecision
+ * @property {PermissionMode} mode        The resolved posture.
+ * @property {boolean} needConfirm        True iff the caller must obtain an
+ *   interactive TTY y/N confirmation AND persist an ack before starting yolo.
+ * @property {boolean} warnUnattended     True iff yolo is starting on a non-TTY
+ *   (unattended) — the caller must emit exactly one prominent ⚠ warning line.
+ */
+
+/**
+ * Resolve the permission posture from the layered inputs. Precedence:
+ *   1. Explicit restricted request (`--chorus-only` / CHORUS_CHORUS_ONLY=1) wins
+ *      outright → `chorus`, never needs confirmation.
+ *   2. Otherwise the posture is `yolo` (the default; `--yolo` /
+ *      CHORUS_YOLO=1 select it too, but it is also the no-flag default).
+ *      Yolo starts immediately with NO confirmation prompt — the warning banner
+ *      tells users how to opt out.
+ *
+ * `CHORUS_YOLO=0`/`"false"` is treated as an explicit opt-OUT of yolo (→
+ * `chorus`), symmetric with the `=1`/`"true"` opt-in, so the existing env knob
+ * keeps working after the default flip.
+ *
+ * @param {{ yolo?: boolean, chorusOnly?: boolean }} flags
+ * @param {Record<string, string|undefined>} env
+ * @param {{ isTTY: boolean, hasAck: boolean }} ctx
+ * @returns {PermissionDecision}
+ */
+export function resolvePermissionMode(flags, env, ctx) {
+  const envChorusOnly = env.CHORUS_CHORUS_ONLY === "1" || env.CHORUS_CHORUS_ONLY === "true";
+  const envYoloOff = env.CHORUS_YOLO === "0" || env.CHORUS_YOLO === "false";
+
+  // 1. Explicit restricted request wins — flag, env, or an explicit CHORUS_YOLO opt-out.
+  if (flags.chorusOnly || envChorusOnly || envYoloOff) {
+    return { mode: "chorus", needConfirm: false, warnUnattended: false };
+  }
+
+  // 2. Default + explicit yolo both resolve to yolo with NO confirmation needed.
+  // Always warn (both TTY and non-TTY) so users know how to restrict.
+  return { mode: "yolo", needConfirm: false, warnUnattended: true };
+}
+
+/**
+ * The prominent warning shown whenever yolo is active. Names `--chorus-only` as
+ * the opt-out switch. Shown in the startup banner for both TTY and non-TTY.
+ * @returns {string}
+ */
+export function yoloWarningLine() {
+  return (
+    "⚠ PERMISSION MODE: YOLO — the woken agent has FULL autonomy (Bash, file writes, " +
+    "any command) under this daemon's API key. Run only in a trusted/sandboxed " +
+    "environment. To restrict permissions, use --chorus-only (or CHORUS_CHORUS_ONLY=1)."
+  );
+}

package/cli/daemon-rest-client.mjs

@@ -0,0 +1,272 @@
+// cli/daemon-rest-client.mjs
+// Shared, host-agnostic pure-REST client for the Chorus daemon → server reporting
+// surface (`/api/daemon/*`). It is the SINGLE SOURCE OF TRUTH for the payload shapes
+// the existing server endpoints accept, so the two daemon hosts — the chorus CLI daemon
+// (`cli/daemon.mjs`) and the OpenClaw plugin — cannot drift in the wire contract.
+//
+// The five operations and their EXACT server payload shapes (verified against
+// src/app/api/daemon/*/route.ts — the server is NOT changed by this work):
+//   turnAdvance      → POST /api/daemon/turn-advance
+//                      { connectionUuid, sessionId, status, entityType?, entityUuid? }
+//   transcript       → POST /api/daemon/transcript
+//                      { sessionId, messages: [{ role, text }] }
+//   executionState   → POST /api/daemon/execution-state
+//                      { connectionUuid, executions: [{ entityType, entityUuid,
+//                                                       rootIdeaUuid|null, status,
+//                                                       startedAt|null }] }
+//   reportInterrupt  → POST /api/daemon/report-interrupt
+//                      { connectionUuid, entityType, entityUuid, reason }
+//   readPendingTurns → GET  /api/daemon/pending-turns?connectionUuid=…
+//                      → { turns: [{ turnUuid, sessionId, directIdeaUuid, trigger,
+//                                    promptText }] }
+//
+// HARD CONSTRAINTS (this module is consumed verbatim by the OpenClaw plugin too):
+//   • ZERO daemon-host coupling — no child_process, no `claude` spawn, no stream-json
+//     parsing, no OpenClaw SDK import. Its only outbound effect is HTTP via the
+//     injected `fetchImpl` (global fetch on Node 18+). Adds NO new npm dependency
+//     (CLAUDE.md pitfall #9).
+//   • Bearer-only auth: every request carries `Authorization: Bearer <apiKey>`.
+//   • NO SILENT ERRORS (project policy): a network error, a non-2xx response, or an
+//     empty/bad body where a result is expected is LOGGED WITH ITS CAUSE and SURFACED to
+//     the caller via a structured result object — never swallowed into a silent success.
+//   • A failed report MUST NOT crash the run: every method RESOLVES (never rejects) with
+//     a `{ ok: false, ... }` result so a fire-and-forget caller can `await` it safely.
+//     The callers decide whether to react; the failure is already visible in the log.
+
+const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
+
+/**
+ * @typedef {Object} DaemonRestResult
+ * @property {boolean} ok           True only on a 2xx response (and, for reads, a
+ *                                  well-formed body). False on network error, non-2xx,
+ *                                  or a malformed/empty body.
+ * @property {number|null} status   HTTP status when a response was received; null on a
+ *                                  pre-flight skip or a network-level error.
+ * @property {string} [error]       Human-readable failure cause (also logged). Absent on
+ *                                  success.
+ * @property {boolean} [skipped]    True when the call was intentionally not issued (e.g.
+ *                                  an empty transcript batch); not an error.
+ * @property {*} [data]             Parsed response payload for read operations
+ *                                  (`readPendingTurns` → `{ turns: [...] }`).
+ */
+
+/**
+ * Build the shared daemon REST client. The inputs are entirely host-agnostic, which is
+ * exactly why the same module serves both daemon hosts.
+ *
+ * @param {{
+ *   url: string,                          Chorus base URL (a trailing slash is normalized
+ *                                         away so callers may pass either form).
+ *   apiKey: string,                       `cho_` agent API key for Bearer auth.
+ *   getConnectionUuid?: () => (string|null), The daemon's registered connection uuid,
+ *                                         learned from the SSE handshake. Read LAZILY on
+ *                                         every call so construction order does not matter.
+ *                                         The connection-scoped operations (turnAdvance,
+ *                                         executionState, reportInterrupt, readPendingTurns)
+ *                                         require it; a null value skips the call (logged).
+ *   fetchImpl?: typeof fetch,             Injectable for tests (defaults to global fetch).
+ *   logger?: { info(m:string):void, warn(m:string):void, error(m:string):void },
+ * }} opts
+ * @returns {{
+ *   turnAdvance: (p: { sessionId: string, status: string, entityType?: string|null, entityUuid?: string|null }) => Promise<DaemonRestResult>,
+ *   transcript: (p: { sessionId: string, messages: Array<{ role: string, text: string }> }) => Promise<DaemonRestResult>,
+ *   executionState: (p: { executions: Array<Record<string, unknown>> }) => Promise<DaemonRestResult>,
+ *   reportInterrupt: (p: { entityType: string, entityUuid: string, reason: string }) => Promise<DaemonRestResult>,
+ *   readPendingTurns: () => Promise<DaemonRestResult>,
+ * }}
+ */
+export function createDaemonRestClient(opts) {
+  const url = opts.url.replace(/\/$/, "");
+  const apiKey = opts.apiKey;
+  const getConnectionUuid = opts.getConnectionUuid ?? (() => null);
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const logger = opts.logger ?? NOOP_LOGGER;
+
+  const jsonHeaders = {
+    Authorization: `Bearer ${apiKey}`,
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  };
+
+  /**
+   * Issue one daemon report. Owns the transport + the no-silent-errors contract that is
+   * IDENTICAL across all four POST endpoints; only the `op` label (used in the log line)
+   * and the path differ. Never throws — returns a structured {@link DaemonRestResult}.
+   *
+   * @param {string} op      Operation label for the log line (matches each endpoint's
+   *                         established wording, e.g. "turn-advance",
+   *                         "execution-state upload", "transcript upload",
+   *                         "report-interrupt").
+   * @param {string} path    Endpoint path, e.g. "/api/daemon/turn-advance".
+   * @param {unknown} body   JSON-serializable request body.
+   * @param {string} [successLog]  Optional info line on success.
+   * @param {string} [context]     Optional " for <entity>"-style suffix appended AFTER the
+   *                         `<op> request failed` / `<op> returned <status>` core, so the
+   *                         failing entity stays visible in the log without disturbing the
+   *                         established op-prefixed message.
+   * @returns {Promise<DaemonRestResult>}
+   */
+  async function post(op, path, body, successLog, context = "") {
+    let response;
+    try {
+      response = await fetchImpl(`${url}${path}`, {
+        method: "POST",
+        headers: jsonHeaders,
+        body: JSON.stringify(body),
+      });
+    } catch (err) {
+      // Network-level failure (DNS, connection refused, abort, …). Surface WITH cause.
+      const error = `${op} request failed${context}: ${err}`;
+      logger.warn(`[Chorus] ${error}`);
+      return { ok: false, status: null, error };
+    }
+    if (!response.ok) {
+      // Non-2xx. Surface WITH the status so a 4xx/5xx is debuggable.
+      const error = `${op} returned ${response.status}${context}`;
+      logger.warn(`[Chorus] ${error}`);
+      return { ok: false, status: response.status, error };
+    }
+    if (successLog) logger.info(`[Chorus] ${successLog}`);
+    return { ok: true, status: response.status };
+  }
+
+  return {
+    /**
+     * POST /api/daemon/turn-advance — advance a wake's DaemonSessionTurn lifecycle. The
+     * server resolves the turn by the session BUSINESS KEY (`sessionId`); the optional
+     * `entityType`/`entityUuid` stamp the weak executionUuid link. Requires the
+     * connectionUuid (the server addresses the turn against a connection the agent owns).
+     */
+    async turnAdvance({ sessionId, status, entityType, entityUuid }) {
+      const connectionUuid = getConnectionUuid();
+      if (!connectionUuid) {
+        const error = `cannot advance turn for session ${sessionId} → ${status} — no connection uuid yet`;
+        logger.warn(`[Chorus] ${error}`);
+        return { ok: false, status: null, error, skipped: true };
+      }
+      const body = {
+        connectionUuid,
+        sessionId,
+        status,
+        // Only sent when BOTH are present, so the server never gets a partial linkage.
+        ...(entityType && entityUuid ? { entityType, entityUuid } : {}),
+      };
+      return post(
+        "turn-advance",
+        "/api/daemon/turn-advance",
+        body,
+        `advanced turn for session ${sessionId} → ${status}`,
+      );
+    },
+
+    /**
+     * POST /api/daemon/transcript — append finalized user/assistant text to the current
+     * turn, targeted by the session BUSINESS KEY (`sessionId`). The caller is responsible
+     * for the content filter (only `{ role, text }` for user/assistant) and any batching.
+     * No connectionUuid needed (the agent key + sessionId resolve the turn server-side).
+     */
+    async transcript({ sessionId, messages }) {
+      return post(
+        "transcript upload",
+        "/api/daemon/transcript",
+        { sessionId, messages },
+        `transcript uploaded (${messages.length} msg) for session ${sessionId}`,
+      );
+    },
+
+    /**
+     * POST /api/daemon/execution-state — publish the connection's running/queued
+     * execution snapshot. The caller supplies the already-built `executions` array (in
+     * the server's `{ entityType, entityUuid, rootIdeaUuid|null, status, startedAt|null }`
+     * shape). Requires the connectionUuid to attribute the snapshot.
+     */
+    async executionState({ executions }) {
+      const connectionUuid = getConnectionUuid();
+      if (!connectionUuid) {
+        // No connectionUuid yet (SSE handshake hasn't reported it): nothing to attribute
+        // the snapshot to. A normal early/edge state — surfaced as a skip, NOT an error.
+        return { ok: false, status: null, skipped: true };
+      }
+      return post(
+        "execution-state upload",
+        "/api/daemon/execution-state",
+        { connectionUuid, executions },
+        `execution-state uploaded (${executions.length} active)`,
+      );
+    },
+
+    /**
+     * POST /api/daemon/report-interrupt — record a wake's `interrupted` outcome
+     * (reason = "user" | "crash") on the server execution row keyed by connection +
+     * entity. Requires the connectionUuid to target the right execution row.
+     */
+    async reportInterrupt({ entityType, entityUuid, reason }) {
+      const connectionUuid = getConnectionUuid();
+      if (!connectionUuid) {
+        const error = `cannot report interrupt for ${entityType}:${entityUuid} — no connection uuid yet`;
+        logger.warn(`[Chorus] ${error}`);
+        return { ok: false, status: null, error, skipped: true };
+      }
+      return post(
+        "report-interrupt",
+        "/api/daemon/report-interrupt",
+        { connectionUuid, entityType, entityUuid, reason },
+        `reported ${entityType}:${entityUuid} interrupted (reason=${reason})`,
+        // Keep the failing entity visible in the failure log (restores the suffix the
+        // standalone interrupt reporter used to emit) without altering the asserted
+        // `report-interrupt request failed` / `report-interrupt returned <status>` prefix.
+        ` for ${entityType}:${entityUuid}`,
+      );
+    },
+
+    /**
+     * GET /api/daemon/pending-turns?connectionUuid=… — read this connection's unstarted
+     * (pending) turns from the turn table (the reconnect-backfill / deliver_turn source).
+     * Returns the parsed `{ turns: [...] }` data on success; a network error, a non-2xx,
+     * a bad JSON body, or a missing `turns` array is LOGGED with cause and surfaced as a
+     * failure result — never a silent empty success.
+     *
+     * @returns {Promise<DaemonRestResult & { data?: { turns: Array<{ turnUuid: string, sessionId: string, directIdeaUuid: string|null, trigger: string, promptText: string|null }> } }>}
+     */
+    async readPendingTurns() {
+      const connectionUuid = getConnectionUuid();
+      if (!connectionUuid) {
+        // No connectionUuid yet: nothing to read against. A normal early state — skip.
+        return { ok: false, status: null, skipped: true };
+      }
+      const endpoint = `${url}/api/daemon/pending-turns?connectionUuid=${encodeURIComponent(connectionUuid)}`;
+      let response;
+      try {
+        response = await fetchImpl(endpoint, {
+          headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
+        });
+      } catch (err) {
+        const error = `pending-turns backfill request failed: ${err}`;
+        logger.warn(`[Chorus] ${error}`);
+        return { ok: false, status: null, error };
+      }
+      if (!response.ok) {
+        const error = `pending-turns backfill returned ${response.status}`;
+        logger.warn(`[Chorus] ${error}`);
+        return { ok: false, status: response.status, error };
+      }
+      let parsed;
+      try {
+        parsed = await response.json();
+      } catch (err) {
+        const error = `pending-turns backfill: bad JSON: ${err}`;
+        logger.warn(`[Chorus] ${error}`);
+        return { ok: false, status: response.status, error };
+      }
+      // API envelope: { success: true, data: { turns: [...] } }.
+      const data = parsed && typeof parsed === "object" ? parsed.data : undefined;
+      const turns = data && typeof data === "object" ? data.turns : undefined;
+      if (!Array.isArray(turns)) {
+        const error = "pending-turns backfill: no turns array in response";
+        logger.warn(`[Chorus] ${error}`);
+        return { ok: false, status: response.status, error };
+      }
+      return { ok: true, status: response.status, data: { turns } };
+    },
+  };
+}