kc-beta 0.3.2 → 0.5.4

package/src/agent/tools/release.js

@@ -0,0 +1,323 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { BaseTool, ToolResult } from "./base.js";
+import { SnapshotTool } from "./snapshot.js";
+import { normalizeRuleCatalog } from "../rule-catalog-normalize.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = path.resolve(__dirname, "../../../template/release-runtime");
+
+/**
+ * Bundle the current workspace into a portable, self-contained release for
+ * end users. The bundle has no kc-beta dependency — anyone with Python +
+ * a worker LLM API key can run `python run.py <doc>`.
+ *
+ * Sequence:
+ *   1. Snapshot the workspace (git tag + snapshots/<slug>/snapshot.json)
+ *   2. Read rules/catalog.json, filter by `include` if given
+ *   3. For each rule, find the latest workflow under workflows/<rule_id>/
+ *   4. Build output/releases/<slug>/ from template/release-runtime/ + workspace
+ *      artifacts (workflows, glossary, catalog, corner_cases, calibration, models)
+ *   5. Write manifest.json + auto-generated README.md
+ *   6. Optionally include KC-selected fixtures from samples/
+ */
+export class ReleaseTool extends BaseTool {
+  /**
+   * @param {import('../workspace.js').Workspace} workspace
+   * @param {object} [opts]
+   * @param {string} [opts.kcVersion]
+   */
+  constructor(workspace, { kcVersion = "0.5.1" } = {}) {
+    super();
+    this._workspace = workspace;
+    this._snapshot = new SnapshotTool(workspace);
+    this._kcVersion = kcVersion;
+  }
+
+  get name() { return "release"; }
+
+  get description() {
+    return (
+      "Bundle the current workspace into a portable release at " +
+      "output/releases/<slug>/. The bundle is self-contained — anyone with " +
+      "Python 3 and a worker LLM API key can run it via `python run.py <doc>`. " +
+      "Snapshots the workspace as a git tag (snap/release-<slug>) for reproducibility. " +
+      "Use when workflows have met accuracy thresholds and the system is ready " +
+      "to be handed off to end users or deployed for production runs."
+    );
+  }
+
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        label: {
+          type: "string",
+          description: "Human-readable release name, e.g. 'v1' or 'q2-2026'. Slugified for the directory name.",
+        },
+        notes: {
+          type: "string",
+          description: "Optional release notes embedded in the manifest and README.",
+        },
+        include: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional rule-id allowlist. Default: all rules in catalog.json.",
+        },
+        fixtures: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional list of sample file paths (relative to samples/ or project) to bundle as fixtures/. KC should pick 1-3 representative samples.",
+        },
+      },
+      required: ["label"],
+    };
+  }
+
+  async execute(input) {
+    const label = (input.label || "").trim();
+    if (!label) return new ToolResult("label required", true);
+    const slug = label.replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+    if (!slug) return new ToolResult("label produced empty slug", true);
+
+    if (!fs.existsSync(TEMPLATE_DIR)) {
+      return new ToolResult(`release template missing at ${TEMPLATE_DIR}`, true);
+    }
+
+    // 1. Snapshot first — locks in commit + tag, regardless of whether bundle build succeeds
+    const snapResult = await this._snapshot.execute({
+      label: `release-${slug}`,
+      notes: `Release ${label} bundle source`,
+    });
+    if (snapResult.isError) return new ToolResult(`snapshot failed: ${snapResult.content}`, true);
+    const { tag: snapshotTag, commit: snapshotCommit } = this._readSnapshotMeta(`release-${slug}`);
+
+    // 2. Read catalog and filter
+    const catalogPath = path.join(this._workspace.cwd, "rules", "catalog.json");
+    if (!fs.existsSync(catalogPath)) {
+      return new ToolResult("rules/catalog.json not found — extract rules before releasing", true);
+    }
+    let catalog;
+    try { catalog = JSON.parse(fs.readFileSync(catalogPath, "utf-8")); }
+    catch (e) { return new ToolResult(`catalog.json invalid: ${e.message}`, true); }
+    catalog = normalizeRuleCatalog(catalog);
+
+    const includeSet = Array.isArray(input.include) && input.include.length > 0
+      ? new Set(input.include) : null;
+    const selectedRules = catalog.filter((r) => !includeSet || includeSet.has(r.id));
+    if (selectedRules.length === 0) {
+      return new ToolResult("no rules selected for release (empty catalog or include filter matched nothing)", true);
+    }
+
+    // 3. Build bundle dir
+    const bundleRel = path.join("output", "releases", slug);
+    const bundleAbs = this._workspace.resolvePath(bundleRel);
+    fs.mkdirSync(bundleAbs, { recursive: true });
+
+    // Copy Python runtime (run.py, render_dashboard.py, serve.sh, kc_runtime/)
+    this._copyDir(TEMPLATE_DIR, bundleAbs, { exclude: ["README.md.tmpl"] });
+    // Make .py executable, .sh executable
+    this._chmodPlusX(path.join(bundleAbs, "run.py"));
+    this._chmodPlusX(path.join(bundleAbs, "render_dashboard.py"));
+    this._chmodPlusX(path.join(bundleAbs, "serve.sh"));
+
+    // 4. Per-rule workflows
+    const ruleEntries = [];
+    const missingWorkflows = [];
+    for (const rule of selectedRules) {
+      const ruleId = rule.id;
+      const found = this._findLatestWorkflow(ruleId);
+      if (!found) {
+        missingWorkflows.push(ruleId);
+        continue;
+      }
+      const destRuleDir = path.join(bundleAbs, "workflows", ruleId);
+      fs.mkdirSync(destRuleDir, { recursive: true });
+      // Copy the workflow file
+      const wfFile = path.basename(found);
+      fs.copyFileSync(found, path.join(destRuleDir, wfFile));
+      this._chmodPlusX(path.join(destRuleDir, wfFile));
+      // Copy prompts/ if present
+      const promptsDir = path.join(this._workspace.cwd, "workflows", ruleId, "prompts");
+      if (fs.existsSync(promptsDir) && fs.statSync(promptsDir).isDirectory()) {
+        this._copyDir(promptsDir, path.join(destRuleDir, "prompts"));
+      }
+      ruleEntries.push({
+        id: ruleId,
+        title: rule.title || rule.description || "",
+        workflow: `workflows/${ruleId}/${wfFile}`,
+      });
+    }
+
+    if (ruleEntries.length === 0) {
+      return new ToolResult(
+        `no workflows found for any selected rule. Missing: ${missingWorkflows.join(", ")}`,
+        true,
+      );
+    }
+
+    // 5. Frozen workspace artifacts
+    this._copyIfExists(catalogPath, path.join(bundleAbs, "catalog.json"));
+    this._copyIfExists(path.join(this._workspace.cwd, "rules", "glossary.json"),
+                       path.join(bundleAbs, "glossary.json"), { fallback: '{"version":1,"entries":[]}\n' });
+    this._copyIfExists(path.join(this._workspace.cwd, "corner_cases.json"),
+                       path.join(bundleAbs, "corner_cases.json"), { fallback: '[]\n' });
+    this._copyIfExists(path.join(this._workspace.cwd, "confidence_calibration.json"),
+                       path.join(bundleAbs, "confidence_calibration.json"),
+                       { fallback: '{"historical_accuracy":{}}\n' });
+
+    // 6. models.json — pull tier mappings from workspace .env (worker tiers)
+    const models = this._readWorkerTiers();
+    fs.writeFileSync(path.join(bundleAbs, "models.json"),
+      JSON.stringify(models, null, 2) + "\n", "utf-8");
+
+    // 7. Optional fixtures
+    const fixtures = Array.isArray(input.fixtures) ? input.fixtures : [];
+    const bundledFixtures = [];
+    if (fixtures.length > 0) {
+      const fixDir = path.join(bundleAbs, "fixtures");
+      fs.mkdirSync(fixDir, { recursive: true });
+      for (const f of fixtures) {
+        const src = this._resolveFixture(f);
+        if (!src) continue;
+        const dst = path.join(fixDir, path.basename(src));
+        fs.copyFileSync(src, dst);
+        bundledFixtures.push(path.basename(src));
+      }
+    }
+
+    // 8. Manifest
+    const manifest = {
+      label,
+      slug,
+      snapshot_tag: snapshotTag,
+      snapshot_commit: snapshotCommit,
+      created_at: new Date().toISOString(),
+      notes: input.notes || "",
+      rules: ruleEntries,
+      models,
+      fixtures: bundledFixtures,
+      kc_beta_version: this._kcVersion,
+    };
+    fs.writeFileSync(path.join(bundleAbs, "manifest.json"),
+      JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+
+    // 9. README from template
+    const readmeTmpl = fs.readFileSync(path.join(TEMPLATE_DIR, "README.md.tmpl"), "utf-8");
+    const rulesList = ruleEntries.map((r) => `- \`${r.id}\` — ${r.title || "(no title)"}`).join("\n");
+    const notesBlock = input.notes ? `> ${input.notes}\n` : "";
+    const readme = readmeTmpl
+      .replace(/\{LABEL\}/g, label)
+      .replace(/\{SLUG\}/g, slug)
+      .replace(/\{CREATED_AT\}/g, manifest.created_at)
+      .replace(/\{SNAPSHOT_TAG\}/g, snapshotTag || "(no tag — git unavailable)")
+      .replace(/\{SNAPSHOT_COMMIT\}/g, snapshotCommit || "(unknown)")
+      .replace(/\{KC_VERSION\}/g, this._kcVersion)
+      .replace(/\{NOTES_BLOCK\}/g, notesBlock)
+      .replace(/\{RULES_LIST\}/g, rulesList);
+    fs.writeFileSync(path.join(bundleAbs, "README.md"), readme, "utf-8");
+
+    // Bundle dir is in output/ (gitignored). Snapshot manifest in snapshots/ IS tracked.
+    const lines = [
+      `Release '${label}' bundled at ${bundleRel}`,
+      `  rules included: ${ruleEntries.length}` +
+        (missingWorkflows.length ? ` (skipped, no workflow: ${missingWorkflows.join(", ")})` : ""),
+      `  snapshot tag:   ${snapshotTag || "(none)"}`,
+      `  fixtures:       ${bundledFixtures.length > 0 ? bundledFixtures.join(", ") : "(none)"}`,
+      ``,
+      `Run from anywhere:`,
+      `  LLM_API_KEY=... TIER1=... python ${bundleRel}/run.py <doc>`,
+      `Open dashboards:`,
+      `  ${bundleRel}/serve.sh && open http://localhost:8080/`,
+      ``,
+      `Not in this release: HTTP serve framework, batch processor, sandboxing.`,
+      `Bundle is regenerable from the snapshot tag (output/releases/ is gitignored).`,
+    ];
+    return new ToolResult(lines.join("\n"));
+  }
+
+  // --- helpers ---
+
+  _readSnapshotMeta(slug) {
+    const p = path.join(this._workspace.cwd, "snapshots", slug, "snapshot.json");
+    if (!fs.existsSync(p)) return { tag: null, commit: null };
+    try {
+      const d = JSON.parse(fs.readFileSync(p, "utf-8"));
+      return { tag: d.tag || null, commit: d.commit || null };
+    } catch {
+      return { tag: null, commit: null };
+    }
+  }
+
+  _findLatestWorkflow(ruleId) {
+    const wfDir = path.join(this._workspace.cwd, "workflows", ruleId);
+    if (!fs.existsSync(wfDir) || !fs.statSync(wfDir).isDirectory()) return null;
+    const entries = fs.readdirSync(wfDir).sort();
+    const versioned = entries.filter((f) => /^workflow_v\d+\.py$/.test(f));
+    if (versioned.length > 0) return path.join(wfDir, versioned[versioned.length - 1]);
+    const any = entries.find((f) => f.endsWith(".py") && f.toLowerCase().includes("workflow"));
+    if (any) return path.join(wfDir, any);
+    const py = entries.find((f) => f.endsWith(".py"));
+    return py ? path.join(wfDir, py) : null;
+  }
+
+  _resolveFixture(rel) {
+    // Try samples/ first (workspace, then project), then plain workspace path
+    const candidates = [];
+    candidates.push(path.join(this._workspace.cwd, "samples", rel));
+    if (this._workspace.projectDir) {
+      candidates.push(path.join(this._workspace.projectDir, "samples", rel));
+      candidates.push(path.join(this._workspace.projectDir, rel));
+    }
+    candidates.push(path.join(this._workspace.cwd, rel));
+    for (const c of candidates) {
+      if (fs.existsSync(c) && fs.statSync(c).isFile()) return c;
+    }
+    return null;
+  }
+
+  _readWorkerTiers() {
+    const envPath = path.join(this._workspace.cwd, ".env");
+    const out = { tier1: "", tier2: "", tier3: "", tier4: "" };
+    if (!fs.existsSync(envPath)) return out;
+    const lines = fs.readFileSync(envPath, "utf-8").split("\n");
+    for (const line of lines) {
+      for (const t of ["TIER1", "TIER2", "TIER3", "TIER4"]) {
+        if (line.startsWith(`${t}=`)) {
+          out[t.toLowerCase()] = line.split("=").slice(1).join("=").trim();
+        }
+      }
+    }
+    return out;
+  }
+
+  _copyDir(src, dst, { exclude = [] } = {}) {
+    fs.mkdirSync(dst, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+      if (exclude.includes(entry.name)) continue;
+      const srcPath = path.join(src, entry.name);
+      const dstPath = path.join(dst, entry.name);
+      if (entry.isDirectory()) {
+        this._copyDir(srcPath, dstPath, { exclude });
+      } else if (entry.isFile()) {
+        fs.copyFileSync(srcPath, dstPath);
+      }
+    }
+  }
+
+  _copyIfExists(src, dst, { fallback = null } = {}) {
+    if (fs.existsSync(src) && fs.statSync(src).isFile()) {
+      fs.copyFileSync(src, dst);
+    } else if (fallback !== null) {
+      fs.writeFileSync(dst, fallback, "utf-8");
+    }
+  }
+
+  _chmodPlusX(p) {
+    try {
+      const stat = fs.statSync(p);
+      fs.chmodSync(p, stat.mode | 0o111);
+    } catch { /* file may not exist; ignore */ }
+  }
+}

package/src/agent/tools/rule-catalog.js

@@ -1,10 +1,52 @@
 import fs from "node:fs";
 import path from "node:path";
 import { BaseTool, ToolResult } from "./base.js";
+import { normalizeRuleCatalog } from "../rule-catalog-normalize.js";
 
 const REQUIRED_FIELDS = new Set(["id", "source_ref", "description"]);
 const RECOMMENDED_FIELDS = new Set(["falsifiability_statement", "test_case_stub", "applicable_sections"]);
 
+// Field-name aliases — LLMs frequently produce `source` or 来源 instead of
+// `source_ref`, `desc` instead of `description`. Rather than making 38+ failed
+// calls before the model figures out the canonical names (as observed in the
+// v0.5.3 E2E test), accept the common aliases and canonicalize on ingest.
+const FIELD_ALIASES = {
+  source: "source_ref",
+  reference: "source_ref",
+  ref: "source_ref",
+  "来源": "source_ref",
+  desc: "description",
+  "描述": "description",
+  rule_id: "id",
+  ruleId: "id",
+};
+
+function normalizeRuleData(data) {
+  if (!data || typeof data !== "object") return data;
+  const out = { ...data };
+  for (const [alias, canonical] of Object.entries(FIELD_ALIASES)) {
+    if (out[alias] !== undefined && out[canonical] === undefined) {
+      out[canonical] = out[alias];
+    }
+  }
+  return out;
+}
+
+function missingFieldError(missing, data) {
+  // Concrete, actionable error. The generic "Missing required fields: id,
+  // source_ref, description" confused agents (they couldn't tell which field
+  // they'd actually failed to provide). Point at the first missing field, name
+  // what was supplied, and mention the aliases so the model can self-correct.
+  const provided = Object.keys(data || {}).slice(0, 8).join(", ") || "(none)";
+  const first = missing[0];
+  const rest = missing.length > 1 ? ` (also missing: ${missing.slice(1).join(", ")})` : "";
+  return (
+    `Missing field '${first}' in data.${rest} ` +
+    `Provided keys: {${provided}}. ` +
+    `Accepted aliases: source/来源/reference → source_ref, desc/描述 → description, rule_id → id.`
+  );
+}
+
 /**
  * CRUD on the rule registry with schema enforcement.
  * Enforces required fields (id, source_ref, description) on create/update.
@@ -48,14 +90,22 @@ export class RuleCatalogTool extends BaseTool {
     if (op === "create") return this._create(data);
     if (op === "update") return this._update(ruleId || data.id || "", data);
     if (op === "delete") return this._delete(ruleId || data.id || "");
-    return new ToolResult(`Unknown operation: ${op}`, true);
+    // More helpful than "Unknown operation: " — tells the agent exactly what's
+    // allowed and what shape to call with next time (observed in v0.5.3 E2E
+    // where GLM-5.1 sent input: {} 38+ times without learning).
+    return new ToolResult(
+      `rule_catalog requires {operation}. Got: ${op ? `'${op}'` : "(empty)"}. ` +
+      `Valid operations: list, read, create, update, delete. ` +
+      `Examples: {"operation":"list"} · {"operation":"create","data":{"id":"R-01","source_ref":"民法典 710","description":"..."}}`,
+      true,
+    );
   }
 
   _load() {
     if (!fs.existsSync(this._catalogPath)) return [];
     try {
       const data = JSON.parse(fs.readFileSync(this._catalogPath, "utf-8"));
-      return Array.isArray(data) ? data : [];
+      return normalizeRuleCatalog(data);
     } catch { return []; }
   }
 
@@ -79,8 +129,9 @@ export class RuleCatalogTool extends BaseTool {
   }
 
   _create(data) {
-    const missing = [...REQUIRED_FIELDS].filter((f) => !(f in data));
-    if (missing.length > 0) return new ToolResult(`Missing required fields: ${missing.join(", ")}`, true);
+    data = normalizeRuleData(data);
+    const missing = [...REQUIRED_FIELDS].filter((f) => !data[f]);
+    if (missing.length > 0) return new ToolResult(missingFieldError(missing, data), true);
     const rules = this._load();
     if (rules.some((r) => r.id === data.id)) return new ToolResult(`Rule already exists: ${data.id}. Use update.`, true);
     const warnings = [...RECOMMENDED_FIELDS].filter((f) => !(f in data));
@@ -93,6 +144,7 @@ export class RuleCatalogTool extends BaseTool {
 
   _update(ruleId, data) {
     if (!ruleId) return new ToolResult("rule_id required for update", true);
+    data = normalizeRuleData(data);
     const rules = this._load();
     const idx = rules.findIndex((r) => r.id === ruleId);
     if (idx < 0) return new ToolResult(`Rule not found: ${ruleId}`, true);

package/src/agent/tools/schedule-fetch.js

@@ -0,0 +1,118 @@
+import { BaseTool, ToolResult } from "./base.js";
+import { Scheduler } from "../scheduler.js";
+
+/**
+ * Manage scheduled document-ingestion jobs. Each job is a shell command that
+ * lands files in `input/`. KC writes a per-job wrapper script under
+ * `scripts/ingest/<id>.sh`; the user installs the script into their crontab
+ * (or other OS scheduler) themselves via `crontab -e`.
+ *
+ * KC does NOT run jobs itself — it generates the artifacts the OS scheduler
+ * needs. This means scheduled ingestion works while kc-beta is closed.
+ */
+export class ScheduleFetchTool extends BaseTool {
+  constructor(workspace) {
+    super();
+    this._workspace = workspace;
+    this._sched = new Scheduler(workspace);
+  }
+
+  get name() { return "schedule_fetch"; }
+
+  get description() {
+    return (
+      "Manage scheduled ingestion jobs that pull documents into input/. " +
+      "Each job is a shell command (e.g. rsync, curl, wget, custom script). " +
+      "KC writes a per-job wrapper script under scripts/ingest/<id>.sh; the user " +
+      "installs the script into their system cron (or launchd / Task Scheduler) " +
+      "via 'crontab -e'. Jobs run while kc-beta is closed. " +
+      "Files landing in input/ are auto-prefixed with <job-id>_<UTC-timestamp>_ " +
+      "so origin and ingest time are visible in the filename."
+    );
+  }
+
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        operation: {
+          type: "string",
+          enum: ["add", "list", "remove", "enable", "disable", "print_crontab"],
+          description: "Operation: add (register), list, remove, enable, disable, print_crontab.",
+        },
+        id: {
+          type: "string",
+          description: "Job identifier (alphanumeric + _-). Required for add/remove/enable/disable.",
+        },
+        command: {
+          type: "string",
+          description: "Shell command for add. Available env vars: $WORKSPACE, $INPUT_DIR, $PROJECT_DIR. Example: 'rsync -av /shared/regs/ \"$INPUT_DIR\"/'.",
+        },
+        description: {
+          type: "string",
+          description: "Optional human-readable description of the job.",
+        },
+        cron_hint: {
+          type: "string",
+          description: "Optional cron expression (5 fields) to embed in the printed crontab line. KC does NOT evaluate it; the OS does. Example: '0 9 * * *' for daily at 09:00.",
+        },
+      },
+      required: ["operation"],
+    };
+  }
+
+  async execute(input) {
+    const op = input.operation;
+    switch (op) {
+      case "add": {
+        const r = this._sched.add({
+          id: input.id,
+          command: input.command,
+          description: input.description,
+          cron_hint: input.cron_hint,
+        });
+        if (!r.ok) return new ToolResult(`add failed: ${r.reason}`, true);
+        const scriptRel = `scripts/ingest/${r.job.id}.sh`;
+        return new ToolResult(
+          `Job '${r.job.id}' registered. Wrapper script: ${scriptRel}\n` +
+          `Install via 'crontab -e' — use 'schedule_fetch print_crontab' to get the line.`
+        );
+      }
+      case "list": {
+        const jobs = this._sched.list();
+        if (jobs.length === 0) return new ToolResult("(no jobs registered)");
+        const lines = jobs.map((j) => {
+          const status = j.enabled ? "enabled" : "disabled";
+          const hint = j.cron_hint ? ` cron_hint='${j.cron_hint}'` : "";
+          return `  ${j.id} [${status}]${hint}\n    cmd: ${j.command}\n    ${j.description ? `desc: ${j.description}` : ""}`;
+        });
+        const tail = this._sched.tailLog(5);
+        return new ToolResult(
+          lines.join("\n") +
+          (tail ? `\n\nlogs/ingest.log (last 5 lines):\n${tail}` : "")
+        );
+      }
+      case "remove": {
+        if (!input.id) return new ToolResult("id required for remove", true);
+        const r = this._sched.remove(input.id);
+        return new ToolResult(r.ok ? `Removed '${input.id}'.` : `remove failed: ${r.reason}`, !r.ok);
+      }
+      case "enable":
+      case "disable": {
+        if (!input.id) return new ToolResult(`id required for ${op}`, true);
+        const r = this._sched.setEnabled(input.id, op === "enable");
+        return new ToolResult(
+          r.ok
+            ? `Job '${input.id}' ${op}d.${op === "disable" ? " Wrapper script removed; remember to remove the line from your crontab too." : ""}`
+            : `${op} failed: ${r.reason}`,
+          !r.ok,
+        );
+      }
+      case "print_crontab": {
+        return new ToolResult(this._sched.formatCrontab());
+      }
+      default:
+        return new ToolResult(`Unknown operation: ${op}`, true);
+    }
+  }
+}

package/src/agent/tools/snapshot.js

@@ -0,0 +1,101 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { BaseTool, ToolResult } from "./base.js";
+
+/**
+ * Create a named snapshot of the current workspace state.
+ * A snapshot is a git tag (`snap/<slug>`) plus a manifest at
+ * snapshots/<slug>/snapshot.json. Used for release bundles (Block 8) or
+ * before risky operations.
+ *
+ * Auto-commits any pending changes before tagging so the snapshot is always
+ * a valid commit. If git isn't available, the manifest is still written but
+ * no tag is created.
+ */
+export class SnapshotTool extends BaseTool {
+  constructor(workspace) {
+    super();
+    this._workspace = workspace;
+  }
+
+  get name() { return "snapshot"; }
+
+  get description() {
+    return (
+      "Create a named snapshot of the current workspace state (git tag + manifest). " +
+      "Use to freeze a moment for a release bundle or before a risky operation. " +
+      "Auto-commits any pending changes before tagging."
+    );
+  }
+
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        label: {
+          type: "string",
+          description: "Human-readable label, e.g. 'release-v1' or 'before-skill-rewrite'.",
+        },
+        notes: {
+          type: "string",
+          description: "Optional description recorded in the snapshot manifest.",
+        },
+      },
+      required: ["label"],
+    };
+  }
+
+  async execute(input) {
+    const label = (input.label || "").trim();
+    if (!label) return new ToolResult("label required", true);
+    const notes = input.notes || "";
+
+    const slug = label.replace(/[^A-Za-z0-9_-]+/g, "_").replace(/^_+|_+$/g, "");
+    if (!slug) return new ToolResult("label produced empty slug", true);
+
+    let commitSha = null;
+    let tagName = null;
+
+    if (this._workspace.gitAvailable) {
+      // Auto-commit any pending changes (so the snapshot is reproducible)
+      spawnSync("git", ["add", "-A"], { cwd: this._workspace.cwd, stdio: "ignore" });
+      spawnSync("git", ["commit", "-m", `snapshot: ${label}`, "--allow-empty"], {
+        cwd: this._workspace.cwd, stdio: "ignore",
+      });
+
+      tagName = `snap/${slug}`;
+      // Force the tag in case the same label is re-used
+      spawnSync("git", ["tag", "-f", tagName], { cwd: this._workspace.cwd, stdio: "ignore" });
+
+      const r = spawnSync("git", ["rev-parse", "HEAD"], {
+        cwd: this._workspace.cwd, encoding: "utf-8",
+      });
+      if (r.status === 0) commitSha = r.stdout.trim();
+    }
+
+    const snapDirRel = path.join("snapshots", slug);
+    const snapDirAbs = this._workspace.resolvePath(snapDirRel);
+    fs.mkdirSync(snapDirAbs, { recursive: true });
+    const manifestRel = path.join(snapDirRel, "snapshot.json");
+    const manifestAbs = this._workspace.resolvePath(manifestRel);
+    const manifest = {
+      label,
+      slug,
+      tag: tagName,
+      commit: commitSha,
+      created_at: new Date().toISOString(),
+      notes: notes || null,
+    };
+    fs.writeFileSync(manifestAbs, JSON.stringify(manifest, null, 2), "utf-8");
+    this._workspace.autoCommit(manifestRel, "snapshot");
+
+    const lines = [
+      `Snapshot '${label}' created.`,
+      tagName ? `  tag: ${tagName}` : "  tag: (skipped — git unavailable)",
+      commitSha ? `  commit: ${commitSha}` : "",
+      `  manifest: ${manifestRel}`,
+    ].filter(Boolean);
+    return new ToolResult(lines.join("\n"));
+  }
+}

package/src/agent/tools/workspace-file.js

@@ -7,17 +7,20 @@ const MAX_READ = 50_000;
 /**
  * Read, write, or list files in the workspace or project directory.
  * All paths are resolved relative to the chosen scope with
- * traversal protection. VersionManager hooks into workspace writes for automatic versioning.
+ * traversal protection. Workspace writes are auto-committed by Workspace.autoCommit
+ * (skips gitignored paths and silently no-ops if git is unavailable).
+ *
+ * The second `versionManager` arg is retained for back-compat with the engine
+ * constructor but is no longer required for any logic.
  */
 export class WorkspaceFileTool extends BaseTool {
   /**
    * @param {import('../workspace.js').Workspace} workspace
-   * @param {import('../version-manager.js').VersionManager} [versionManager]
+   * @param {import('../version-manager.js').VersionManager} [_versionManager] - unused, kept for back-compat
    */
-  constructor(workspace, versionManager) {
+  constructor(workspace, _versionManager) {
     super();
     this._workspace = workspace;
-    this._versionManager = versionManager || null;
   }
 
   get name() { return "workspace_file"; }
@@ -112,10 +115,10 @@ export class WorkspaceFileTool extends BaseTool {
     fs.mkdirSync(path.dirname(resolved), { recursive: true });
     fs.writeFileSync(resolved, content, "utf-8");
 
-    // Version tracking only for workspace writes
+    // Auto-commit to git for workspace writes (silently no-ops if gitignored or git unavailable)
     let traceId = null;
-    if (scope === "workspace" && this._versionManager) {
-      traceId = this._versionManager.onWrite(filePath, content);
+    if (scope === "workspace") {
+      traceId = this._workspace.autoCommit(filePath, "update");
     }
 
     const label = scope === "project" ? `[project] ${filePath}` : filePath;