chainlesschain 0.162.155 → 0.162.157

package/src/lib/agent-schedule-store.js

@@ -0,0 +1,330 @@
+/**
+ * AgentScheduleStore — persistent backing for the agent-callable Monitor /
+ * Cron / Wakeup tools (gap-analysis 第四阶段 #3).
+ *
+ * A one-shot `cc agent` turn cannot itself keep a timer alive, so these tools
+ * PERSIST their intent to a JSONL store under
+ * `~/.chainlesschain/agent-schedule/<kind>.jsonl`; a supervising loop / cron
+ * (`cc agenda run`) reads due entries and acts. This mirrors how Claude Code's
+ * Monitor/CronCreate/ScheduleWakeup outlive a single turn.
+ *
+ * Three entry kinds share one store:
+ *   - wakeup   one-shot: run `prompt` (a `cc agent -p`) once at/after `dueAt`.
+ *   - cron     recurring: run `prompt` on a cron schedule; `nextAt` advances.
+ *   - monitor  recurring watch: run `command` (shell) every `intervalMs`;
+ *              fire the `notify` payload when `stopWhen` regex matches output.
+ *
+ * Pure over an injected clock + directory so it is fully unit-testable. Cron
+ * parsing is a compact 5-field evaluator (min hour dom mon dow) supporting
+ * `* , - /` — enough for the scheduling the agent actually asks for.
+ */
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { randomUUID } from "crypto";
+
+export const SCHEDULE_KINDS = Object.freeze(["wakeup", "cron", "monitor"]);
+
+export function agentScheduleDir(homedir = os.homedir()) {
+  return path.join(homedir, ".chainlesschain", "agent-schedule");
+}
+
+// ─── cron (5-field) ────────────────────────────────────────────────────────
+
+const CRON_RANGES = [
+  [0, 59], // minute
+  [0, 23], // hour
+  [1, 31], // day of month
+  [1, 12], // month
+  [0, 6], // day of week (0/7 = Sunday)
+];
+
+function parseCronField(field, [min, max]) {
+  const values = new Set();
+  for (const part of String(field).split(",")) {
+    const [rangePart, stepPart] = part.split("/");
+    const step = stepPart ? parseInt(stepPart, 10) : 1;
+    if (!Number.isFinite(step) || step < 1) {
+      throw new Error(`invalid cron step in "${field}"`);
+    }
+    let lo = min;
+    let hi = max;
+    if (rangePart !== "*" && rangePart !== "") {
+      const bounds = rangePart.split("-");
+      lo = parseInt(bounds[0], 10);
+      hi = bounds.length > 1 ? parseInt(bounds[1], 10) : lo;
+      if (!Number.isFinite(lo) || !Number.isFinite(hi)) {
+        throw new Error(`invalid cron range in "${field}"`);
+      }
+    }
+    for (let v = lo; v <= hi; v += step) {
+      if (v < min || v > max) throw new Error(`cron value out of range: ${v}`);
+      values.add(v);
+    }
+  }
+  return values;
+}
+
+/** Parse a 5-field cron expression into per-field value sets. Throws on junk. */
+export function parseCron(expr) {
+  const fields = String(expr).trim().split(/\s+/);
+  if (fields.length !== 5) {
+    throw new Error(
+      `cron expression must have 5 fields (min hour dom mon dow), got ${fields.length}`,
+    );
+  }
+  return fields.map((field, i) => parseCronField(field, CRON_RANGES[i]));
+}
+
+function cronMatches(sets, date) {
+  const dow = date.getDay(); // 0-6, Sun=0
+  return (
+    sets[0].has(date.getMinutes()) &&
+    sets[1].has(date.getHours()) &&
+    sets[2].has(date.getDate()) &&
+    sets[3].has(date.getMonth() + 1) &&
+    (sets[4].has(dow) || (sets[4].has(7) && dow === 0))
+  );
+}
+
+/**
+ * Next epoch-ms at which `expr` fires strictly after `fromMs` (local time,
+ * minute granularity). Scans up to ~366 days then gives up (returns null) so a
+ * never-matching expression can't loop forever.
+ */
+export function nextCronTime(expr, fromMs) {
+  const sets = parseCron(expr);
+  const cursor = new Date(fromMs);
+  cursor.setSeconds(0, 0);
+  cursor.setMinutes(cursor.getMinutes() + 1);
+  const limit = 366 * 24 * 60;
+  for (let i = 0; i < limit; i += 1) {
+    if (cronMatches(sets, cursor)) return cursor.getTime();
+    cursor.setMinutes(cursor.getMinutes() + 1);
+  }
+  return null;
+}
+
+// ─── store ───────────────────────────────────────────────────────────────
+
+export class AgentScheduleStore {
+  constructor({ dir = null, now = () => Date.now() } = {}) {
+    this.dir = dir || agentScheduleDir();
+    this._now = typeof now === "function" ? now : () => now;
+  }
+
+  _file(kind) {
+    return path.join(this.dir, `${kind}.jsonl`);
+  }
+
+  _ensureDir() {
+    fs.mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+  }
+
+  _readAll(kind) {
+    let raw;
+    try {
+      raw = fs.readFileSync(this._file(kind), "utf-8");
+    } catch {
+      return [];
+    }
+    const entries = [];
+    for (const line of raw.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        entries.push(JSON.parse(trimmed));
+      } catch {
+        // Skip a corrupt line rather than throwing — one bad append must not
+        // poison the whole store (per-row resilience, like the JSON.parse sweep).
+      }
+    }
+    return entries;
+  }
+
+  _writeAll(kind, entries) {
+    this._ensureDir();
+    const body = entries.map((entry) => JSON.stringify(entry)).join("\n");
+    fs.writeFileSync(this._file(kind), body ? body + "\n" : "", {
+      encoding: "utf-8",
+      mode: 0o600,
+    });
+  }
+
+  // ── create ──────────────────────────────────────────────────────────────
+
+  scheduleWakeup({ prompt, delayMs = 0, dueAt = null, label = null } = {}) {
+    if (!prompt || typeof prompt !== "string") {
+      throw new Error("wakeup requires a prompt");
+    }
+    const now = this._now();
+    const entry = {
+      id: randomUUID(),
+      kind: "wakeup",
+      prompt,
+      label: label || null,
+      dueAt:
+        dueAt != null ? Number(dueAt) : now + Math.max(0, Number(delayMs) || 0),
+      createdAt: now,
+      status: "pending",
+    };
+    const entries = this._readAll("wakeup");
+    entries.push(entry);
+    this._writeAll("wakeup", entries);
+    return entry;
+  }
+
+  createCron({ prompt, cron, label = null } = {}) {
+    if (!prompt || typeof prompt !== "string") {
+      throw new Error("cron requires a prompt");
+    }
+    const now = this._now();
+    const nextAt = nextCronTime(cron, now); // validates the expression too
+    if (nextAt == null) {
+      throw new Error(`cron "${cron}" has no upcoming match`);
+    }
+    const entry = {
+      id: randomUUID(),
+      kind: "cron",
+      prompt,
+      cron,
+      label: label || null,
+      nextAt,
+      createdAt: now,
+      lastRunAt: null,
+      runs: 0,
+      status: "active",
+    };
+    const entries = this._readAll("cron");
+    entries.push(entry);
+    this._writeAll("cron", entries);
+    return entry;
+  }
+
+  createMonitor({
+    command,
+    intervalMs,
+    stopWhen = null,
+    notify = null,
+    maxChecks = null,
+    label = null,
+  } = {}) {
+    if (!command || typeof command !== "string") {
+      throw new Error("monitor requires a command");
+    }
+    const interval = Math.max(1000, Number(intervalMs) || 60000);
+    if (stopWhen != null) {
+      // Validate the regex up-front so a bad pattern errors at creation, not
+      // silently at the first check.
+      // eslint-disable-next-line no-new
+      new RegExp(stopWhen);
+    }
+    const now = this._now();
+    const entry = {
+      id: randomUUID(),
+      kind: "monitor",
+      command,
+      intervalMs: interval,
+      stopWhen: stopWhen || null,
+      notify: notify || null,
+      maxChecks: maxChecks != null ? Number(maxChecks) : null,
+      label: label || null,
+      nextAt: now + interval,
+      createdAt: now,
+      checks: 0,
+      status: "active",
+    };
+    const entries = this._readAll("monitor");
+    entries.push(entry);
+    this._writeAll("monitor", entries);
+    return entry;
+  }
+
+  // ── query ─────────────────────────────────────────────────────────────────
+
+  list(kind = null) {
+    const kinds = kind ? [kind] : SCHEDULE_KINDS;
+    const out = [];
+    for (const k of kinds) out.push(...this._readAll(k));
+    return out;
+  }
+
+  /** Entries whose time has come (pending wakeup / active cron|monitor). */
+  due(kind = null, atMs = null) {
+    const now = atMs != null ? atMs : this._now();
+    return this.list(kind).filter((entry) => {
+      if (entry.kind === "wakeup") {
+        return entry.status === "pending" && entry.dueAt <= now;
+      }
+      return entry.status === "active" && entry.nextAt <= now;
+    });
+  }
+
+  cancel(id) {
+    for (const kind of SCHEDULE_KINDS) {
+      const entries = this._readAll(kind);
+      const idx = entries.findIndex((entry) => entry.id === id);
+      if (idx >= 0) {
+        const [removed] = entries.splice(idx, 1);
+        this._writeAll(kind, entries);
+        return removed;
+      }
+    }
+    return null;
+  }
+
+  // ── lifecycle mutations (used by `cc agenda run`) ──────────────────────────
+
+  /** Mark a one-shot wakeup fired (keeps history; due() skips it). */
+  markWakeupFired(id, atMs = null) {
+    return this._mutate("wakeup", id, (entry) => {
+      entry.status = "fired";
+      entry.firedAt = atMs != null ? atMs : this._now();
+    });
+  }
+
+  /** Advance a cron entry to its next fire time after running once. */
+  advanceCron(id, atMs = null) {
+    const now = atMs != null ? atMs : this._now();
+    return this._mutate("cron", id, (entry) => {
+      entry.lastRunAt = now;
+      entry.runs = (entry.runs || 0) + 1;
+      const next = nextCronTime(entry.cron, now);
+      if (next == null) {
+        entry.status = "exhausted";
+      } else {
+        entry.nextAt = next;
+      }
+    });
+  }
+
+  /**
+   * Record a monitor check. `matched` ends the monitor (done); otherwise it is
+   * re-armed for the next interval, or exhausted once maxChecks is hit.
+   */
+  recordMonitorCheck(id, { matched = false, atMs = null } = {}) {
+    const now = atMs != null ? atMs : this._now();
+    return this._mutate("monitor", id, (entry) => {
+      entry.checks = (entry.checks || 0) + 1;
+      entry.lastCheckAt = now;
+      if (matched) {
+        entry.status = "matched";
+        entry.matchedAt = now;
+      } else if (entry.maxChecks != null && entry.checks >= entry.maxChecks) {
+        entry.status = "exhausted";
+      } else {
+        entry.nextAt = now + entry.intervalMs;
+      }
+    });
+  }
+
+  _mutate(kind, id, fn) {
+    const entries = this._readAll(kind);
+    const entry = entries.find((e) => e.id === id);
+    if (!entry) return null;
+    fn(entry);
+    this._writeAll(kind, entries);
+    return entry;
+  }
+}

package/src/lib/artifact-store.js

@@ -0,0 +1,236 @@
+/**
+ * ArtifactStore — durable home for agent DELIVERABLES (gap-analysis P1 #10).
+ *
+ * An agent run produces important files — a Markdown report, a patch, a
+ * screenshot, test logs, review findings JSON — that otherwise live as loose
+ * paths the user has to remember. `publish_artifact` copies such a file into
+ * `~/.chainlesschain/artifacts/` with metadata (title, kind, mime, sha256,
+ * session), so:
+ *   - the session transcript only records the small METADATA object (the tool
+ *     result), never the file body;
+ *   - `cc artifacts` lists/inspects/cleans them across sessions;
+ *   - web-panel / remote surfaces can later serve previews from one place.
+ *
+ * Layout:
+ *   ~/.chainlesschain/artifacts/index.jsonl   one metadata row per artifact
+ *   ~/.chainlesschain/artifacts/files/<id><ext>  the stored copy
+ *
+ * Per-row tolerant JSONL (a corrupt line never poisons the store); injected
+ * clock + dir for unit tests; TTL-based expiry with an explicit cleanup call
+ * (`cc artifacts clean` / opportunistic on publish).
+ */
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+import crypto from "crypto";
+
+export const ARTIFACT_KINDS = Object.freeze([
+  "report",
+  "patch",
+  "screenshot",
+  "log",
+  "data",
+  "other",
+]);
+
+/** Copy-size guard: an "artifact" is a deliverable, not a build tree. */
+export const MAX_ARTIFACT_BYTES = 100 * 1024 * 1024; // 100 MB
+
+/** Default retention before `clean` removes an artifact. */
+export const DEFAULT_TTL_DAYS = 30;
+
+const MIME_BY_EXT = Object.freeze({
+  ".md": "text/markdown",
+  ".markdown": "text/markdown",
+  ".txt": "text/plain",
+  ".log": "text/plain",
+  ".json": "application/json",
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".csv": "text/csv",
+  ".xml": "application/xml",
+  ".yaml": "application/yaml",
+  ".yml": "application/yaml",
+  ".patch": "text/x-patch",
+  ".diff": "text/x-patch",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".svg": "image/svg+xml",
+  ".pdf": "application/pdf",
+  ".zip": "application/zip",
+});
+
+export function artifactsDir(homedir = os.homedir()) {
+  // Test/deployment override (same convention as CC_BACKGROUND_AGENTS_DIR).
+  if (process.env.CC_ARTIFACTS_DIR) return process.env.CC_ARTIFACTS_DIR;
+  return path.join(homedir, ".chainlesschain", "artifacts");
+}
+
+function mimeForExt(ext) {
+  return (
+    MIME_BY_EXT[String(ext || "").toLowerCase()] || "application/octet-stream"
+  );
+}
+
+function normalizeKind(kind) {
+  const k = typeof kind === "string" ? kind.trim().toLowerCase() : "";
+  return ARTIFACT_KINDS.includes(k) ? k : "other";
+}
+
+export class ArtifactStore {
+  constructor({ dir = null, now = () => Date.now() } = {}) {
+    this.dir = dir || artifactsDir();
+    this._now = typeof now === "function" ? now : () => now;
+  }
+
+  _indexFile() {
+    return path.join(this.dir, "index.jsonl");
+  }
+
+  _filesDir() {
+    return path.join(this.dir, "files");
+  }
+
+  _ensureDirs() {
+    fs.mkdirSync(this._filesDir(), { recursive: true });
+  }
+
+  /**
+   * Publish a file as an artifact (copy + metadata row).
+   * @param {{ filePath: string, title?: string, kind?: string,
+   *           sessionId?: string|null, ttlDays?: number }} opts
+   * @returns {object} the metadata entry (what the tool returns — no body)
+   */
+  publish({ filePath, title, kind, sessionId = null, ttlDays } = {}) {
+    if (!filePath) throw new Error("publish requires a filePath");
+    const abs = path.resolve(filePath);
+    let stat;
+    try {
+      stat = fs.statSync(abs);
+    } catch {
+      throw new Error(`artifact source not found: ${abs}`);
+    }
+    if (!stat.isFile()) {
+      throw new Error(`artifact source is not a regular file: ${abs}`);
+    }
+    if (stat.size > MAX_ARTIFACT_BYTES) {
+      throw new Error(
+        `artifact too large (${stat.size} bytes > ${MAX_ARTIFACT_BYTES}); artifacts are deliverables, not build output`,
+      );
+    }
+    const body = fs.readFileSync(abs);
+    const sha256 = crypto.createHash("sha256").update(body).digest("hex");
+    const ext = path.extname(abs);
+    const id = `art_${this._now().toString(36)}_${crypto
+      .randomBytes(4)
+      .toString("hex")}`;
+    const days = Number.isFinite(Number(ttlDays))
+      ? Math.max(1, Number(ttlDays))
+      : DEFAULT_TTL_DAYS;
+    const createdAt = this._now();
+    const entry = {
+      id,
+      title: String(title || path.basename(abs)),
+      kind: normalizeKind(kind),
+      mime: mimeForExt(ext),
+      size: stat.size,
+      sha256,
+      sourcePath: abs,
+      file: `${id}${ext}`,
+      sessionId: sessionId ? String(sessionId) : null,
+      createdAt: new Date(createdAt).toISOString(),
+      expiresAt: new Date(createdAt + days * 24 * 60 * 60 * 1000).toISOString(),
+    };
+    this._ensureDirs();
+    fs.writeFileSync(path.join(this._filesDir(), entry.file), body);
+    fs.appendFileSync(this._indexFile(), JSON.stringify(entry) + "\n", "utf-8");
+    return entry;
+  }
+
+  /** All (non-corrupt) metadata rows, oldest first. */
+  list({ sessionId } = {}) {
+    let raw;
+    try {
+      raw = fs.readFileSync(this._indexFile(), "utf-8");
+    } catch {
+      return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+      const t = line.trim();
+      if (!t) continue;
+      try {
+        const e = JSON.parse(t);
+        if (e && typeof e === "object" && e.id) out.push(e);
+      } catch {
+        /* per-row tolerance — a corrupt line never poisons the store */
+      }
+    }
+    return sessionId ? out.filter((e) => e.sessionId === sessionId) : out;
+  }
+
+  /** One entry by id (or null). */
+  get(id) {
+    return this.list().find((e) => e.id === id) || null;
+  }
+
+  /** Absolute path of an artifact's stored copy (or null). */
+  storedPath(idOrEntry) {
+    const entry =
+      typeof idOrEntry === "object" && idOrEntry
+        ? idOrEntry
+        : this.get(idOrEntry);
+    if (!entry) return null;
+    return path.join(this._filesDir(), entry.file);
+  }
+
+  /** Remove one artifact (file + index row). @returns {boolean} found */
+  remove(id) {
+    const entries = this.list();
+    const target = entries.find((e) => e.id === id);
+    if (!target) return false;
+    try {
+      fs.rmSync(this.storedPath(target), { force: true });
+    } catch {
+      /* best-effort — the index row is the source of truth */
+    }
+    this._rewrite(entries.filter((e) => e.id !== id));
+    return true;
+  }
+
+  /**
+   * Remove expired artifacts (expiresAt in the past).
+   * @returns {{ removed: number }}
+   */
+  cleanupExpired() {
+    const entries = this.list();
+    const now = this._now();
+    const keep = [];
+    let removed = 0;
+    for (const e of entries) {
+      const exp = Date.parse(e.expiresAt || "");
+      if (Number.isFinite(exp) && exp <= now) {
+        try {
+          fs.rmSync(this.storedPath(e), { force: true });
+        } catch {
+          /* best-effort */
+        }
+        removed += 1;
+      } else {
+        keep.push(e);
+      }
+    }
+    if (removed > 0) this._rewrite(keep);
+    return { removed };
+  }
+
+  _rewrite(entries) {
+    this._ensureDirs();
+    const text = entries.map((e) => JSON.stringify(e)).join("\n");
+    fs.writeFileSync(this._indexFile(), text ? text + "\n" : "", "utf-8");
+  }
+}