@voybio/ace-swarm 2.4.6 → 2.4.8

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="assets/logo/ace-logo.png" alt="ACE — Autonomous Coding Entity" width="640">
+</p>
+
 # ACE Swarm MCP Server and CLI
 
 Autonomous Coding Entity (ACE) is a local MCP server and CLI for agent-assisted coding.

package/dist/ace-server-instructions.js

@@ -31,6 +31,13 @@ const REFRESH_TOOLS = new Set([
 // New mutation tools with non-standard prefixes must be added here explicitly.
 const NAMED_MUTATION_TOOLS = new Set([
     "rewrite_targets",
+    "apply_patch",
+    "astgrep_rewrite",
+    "reap_stale_jobs",
+    "heartbeat_job",
+    "generate_kanban_ui",
+    "codemunch_snapshot",
+    "codemunch_index",
 ]);
 const MUTATION_PREFIXES = [
     "ack_",
@@ -207,15 +214,19 @@ export function buildServerInstructions(workspaceRoot) {
     const lines = [
         "You are operating in an ACE-governed workspace.",
         coreFiles.length > 0
-            ? `Ground truth lives in ${coreFiles.join(", ")}.`
-            : `Ground truth lives in ${ACE_ROOT_REL}/agent-state/* artifacts, not chat history.`,
+            ? `Ground truth for task/status/scope/evidence is store-backed under ${coreFiles.join(", ")} (canonical store: ${ACE_ROOT_REL}/agent-state/ace-state.ace).`
+            : `Ground truth is store-backed under ${ACE_ROOT_REL}/agent-state/* artifacts (canonical store: ${ACE_ROOT_REL}/agent-state/ace-state.ace), not chat history.`,
+        "`ace compact` and the automatic lifecycle sweep intentionally remove loose agent-state/* files from disk after folding them into the store — this is expected, not data loss, and applies to every swept artifact (kanban, run-ledger, handoffs, playbook, tracker snapshots, etc.), not only TASK/STATUS/SCOPE/EVIDENCE_LOG. If a path is not on disk, call list_workspace on its directory to see the full store-backed listing (or `ace ls` from the CLI), then read it back with read_workspace_file (or `ace read <path>`); never recreate swept files.",
         stateDirs.length > 0
-            ? `Durable artifacts belong under ${stateDirs.map((entry) => `${entry}/`).join(", ")}.`
+            ? `Durable artifacts belong under ${stateDirs.map((entry) => `${entry}/`).join(", ")} and are persisted into the store; the loose copies are sweep inputs, not the source of truth.`
             : undefined,
         "Before significant work, call recall_context to load current task, scope, and status.",
         "Use route_task and get_agent_instructions for role guidance; do not self-assign by guesswork.",
         "After meaningful edits or state changes, call execute_gates and persist evidence/handoffs in ACE artifacts.",
         "For delegated or long-running work, use create_handoff / ack_handoff and append_vericify_process_post instead of ad-hoc status notes.",
+        "For self-paced, evidence-gated multi-step objectives beyond this session, use start_goal / get_goal_status / resume_goal / stop_goal (or `ace goal` from the CLI).",
+        "Prefer the matching MCP tool over ad-hoc shell/chat tracking: git_status / git_diff / git_log / git_commit for git; enqueue_job / dispatch_jobs / heartbeat_job / get_lock_table for background jobs; snapshot_state / semantic_diff / drift_report / rewrite_targets for change intelligence.",
+        "skill_catalog_summary / skill_audit / problem_triage surface packaged skills; get_todo / update_todo / get_run_ledger is the human-facing todo surface; scan_workspace_delta / web_research_packet / codemunch_snapshot / codemunch_index cover workspace-wide search and indexing.",
         `Current ACE digest: ${digest}.`,
         autonomyHint ? `Runtime autonomy signals: ${autonomyHint}.` : undefined,
     ];
@@ -239,10 +250,13 @@ export function buildHostInstructionText(host, workspaceRoot) {
         "2. Call `route_task` and `get_agent_instructions` before choosing a role.",
         "3. Prefer ACE prompts/resources (`ace-orchestrator`, `get_task_pack`, `get_skill_instructions`) over relying on this file.",
         "4. Read/write task state through MCP tools (`recall_context`, `read_workspace_file`, `write_workspace_file`, lifecycle append tools); do not create files under `agent-state/` directly.",
+        "5. For self-paced, evidence-gated multi-step objectives beyond this session, use `start_goal` / `get_goal_status` / `resume_goal` / `stop_goal` (or `ace goal` from the CLI).",
+        "6. Also prefer the matching MCP domain over ad-hoc equivalents for git, background jobs/scheduler, change intelligence, discovery/indexing, skills, and todo — see docs/mcp-tool-reference.md for the full per-domain tool catalog.",
         "",
         "Ground truth:",
         "- ACE MCP tools are the authoritative interface for task state and lifecycle updates.",
         "- `agent-state/ace-state.ace` is the canonical store path; visible `agent-state/*` files are compatibility projections or sweep inputs.",
+        "- `ace compact` and the automatic lifecycle sweep intentionally remove loose `agent-state/*` files from disk after folding them into the store — this is expected, not data loss, for any swept artifact. Do NOT recreate them; if a path isn't on disk, call `list_workspace` on its directory (or `ace ls`) to see the full store-backed listing, then retrieve it via `ace read <path>` or the `read_workspace_file` / `recall_context` MCP tools.",
         "- `.agents/ACE/tasks/todo.md` is the human-facing todo surface.",
         "- Hook context is store-backed in `agent-state/ace-state.ace` and consumed without extra workspace projections.",
         "",

package/dist/cli.js

@@ -98,8 +98,13 @@ Options for turnkey:
 Options for mcp:
   --profile <host-min|full>    Select the visible tool schema (default: full)
 
-Options for playbook add:
-  --reason-code <code>         Scope the lesson to a matching failure reason code
+Options for playbook:
+  list [--section <s>] [--status <s>]   List playbook bullets (default subcommand)
+  show <id>                             Show one bullet as JSON
+  add --content <text> [--section <s>]  Add a bullet
+      [--reason-code <code>]              Scope the lesson to a matching failure reason code
+  tag <id> helpful|harmful              Curate a bullet's helpful/harmful tag
+  gc                                    Prune and quarantine curated bullets
 
 Options for eval:
   --model, --models <csv>      Model name or comma-separated model names (required)
@@ -1696,7 +1701,10 @@ async function main() {
         const savedKb = Math.round((result.before - result.after) / 1024);
         console.log(`Store compacted: ${result.before} → ${result.after} bytes (saved ${savedKb}KB)`);
         if (result.sweep) {
-            console.log(`Sweep: cached ${result.sweep.cached_files}, removed ${result.sweep.removed_files}, semantic GC removed ${result.sweep.removed_semantic_cache_files}`);
+            console.log(`Sweep: folded ${result.sweep.cached_files} artifact(s) into the store, freed ${result.sweep.removed_files} loose file(s) from disk, semantic GC removed ${result.sweep.removed_semantic_cache_files}`);
+            if (result.sweep.removed_files > 0) {
+                console.log("  Swept files are stored, not lost — read them back with `ace read <path>` (e.g. `ace read agent-state/TASK.md`). Do not recreate them.");
+            }
         }
         return;
     }
@@ -1739,7 +1747,7 @@ async function main() {
         console.log(`Cached files: ${result.cached_files}`);
         console.log(`Kept projected files: ${result.kept_projected_files}`);
         console.log(`Skipped files: ${result.skipped_files}`);
-        console.log(`Removed files: ${result.removed_files}`);
+        console.log(`Removed files: ${result.removed_files} (folded into the store, not lost — read back with \`ace read <path>\`; do not recreate)`);
         console.log(`Semantic cache GC removed files: ${result.removed_semantic_cache_files}`);
         console.log(`Staging GC removed entries: ${stagingGc.removed_entries}`);
         if (result.warnings.length > 0) {

package/dist/server.d.ts

@@ -11,9 +11,20 @@ export declare function createAceServer(options?: CreateAceServerOptions): McpSe
 export type AceHostProfile = "host-min" | "full";
 /**
  * Curated premium-host surface (report WS-G). ~15–25 high-value tools instead of the
- * full tool surface, cutting the per-session schema tax. Everything omitted here remains reachable
- * via `run_orchestrator` delegation or by starting with `--profile full`. Goal-engine
- * tools (start_goal/…) are intentionally absent until WS-F ships.
+ * full tool surface, cutting the per-session schema tax. `run_orchestrator` only reaches an
+ * omitted tool if the model-bridge child it spawns happens to have that tool in its own MCP
+ * session — it is a role/plan dispatcher, not a generic proxy for any omitted tool by name.
+ * The reliable way to reach anything below is to start with `--profile full`.
+ *
+ * Whole domains are intentionally absent, not just individual tools: goal-engine
+ * (start_goal/get_goal_status/resume_goal/stop_goal — until WS-F ships), git
+ * (git_status/git_diff/git_log/git_commit), scheduler (enqueue_job/dispatch_jobs/
+ * heartbeat_job/reap_stale_jobs/get_lock_table/…), drift/change-intelligence
+ * (snapshot_state/semantic_diff/drift_report/rewrite_targets/list_snapshots), discovery
+ * (scan_workspace_delta/web_research_packet/codemunch_snapshot/codemunch_index/
+ * mcp_ingestion_probe/refresh_astgrep_index), skills (skill_catalog_summary/skill_audit/
+ * problem_triage), and todo (get_todo/update_todo/get_run_ledger) all have zero
+ * representation below.
  */
 export declare const HOST_MIN_TOOL_PROFILE: readonly string[];
 export declare function resolveHostProfileAllowlist(profile: AceHostProfile): readonly string[] | undefined;

package/dist/server.js

@@ -94,9 +94,20 @@ async function verifyMcpStoreStartup(workspaceRoot, logStartup) {
 }
 /**
  * Curated premium-host surface (report WS-G). ~15–25 high-value tools instead of the
- * full tool surface, cutting the per-session schema tax. Everything omitted here remains reachable
- * via `run_orchestrator` delegation or by starting with `--profile full`. Goal-engine
- * tools (start_goal/…) are intentionally absent until WS-F ships.
+ * full tool surface, cutting the per-session schema tax. `run_orchestrator` only reaches an
+ * omitted tool if the model-bridge child it spawns happens to have that tool in its own MCP
+ * session — it is a role/plan dispatcher, not a generic proxy for any omitted tool by name.
+ * The reliable way to reach anything below is to start with `--profile full`.
+ *
+ * Whole domains are intentionally absent, not just individual tools: goal-engine
+ * (start_goal/get_goal_status/resume_goal/stop_goal — until WS-F ships), git
+ * (git_status/git_diff/git_log/git_commit), scheduler (enqueue_job/dispatch_jobs/
+ * heartbeat_job/reap_stale_jobs/get_lock_table/…), drift/change-intelligence
+ * (snapshot_state/semantic_diff/drift_report/rewrite_targets/list_snapshots), discovery
+ * (scan_workspace_delta/web_research_packet/codemunch_snapshot/codemunch_index/
+ * mcp_ingestion_probe/refresh_astgrep_index), skills (skill_catalog_summary/skill_audit/
+ * problem_triage), and todo (get_todo/update_todo/get_run_ledger) all have zero
+ * representation below.
  */
 export const HOST_MIN_TOOL_PROFILE = [
     "recall_context",

package/dist/tools-files.js

@@ -17,7 +17,8 @@ import { safeEditFile, diffContents, applyPatch } from "./safe-edit.js";
 import { detectAstgrepCommand, flattenMetaVariables, locateAstgrepMatches, runAstgrepQuery, } from "./astgrep-index.js";
 import { readRuntimeProfile, resolveEffectiveSurgicalReadBudget, validateRuntimeProfileContent, } from "./runtime-profile.js";
 import { withLocalModelRuntimeRepository } from "./store/repositories/local-model-runtime-repository.js";
-import { listStoreKeysSync } from "./store/store-snapshot.js";
+import { getWorkspaceStorePath, listStoreKeysSync } from "./store/store-snapshot.js";
+import { listStoreEntries } from "./store/store-cli.js";
 function reasonCodeFromError(error) {
     return typeof error === "object" && error !== null && "reason_code" in error
         ? String(error.reason_code)
@@ -1092,7 +1093,7 @@ export function registerFileTools(server) {
             ],
         };
     });
-    server.tool("list_workspace", "List files/directories in a workspace path", {
+    server.tool("list_workspace", "List files/directories in a workspace path, plus any ACEPACK store-only artifacts under it (content the lifecycle sweep folded into the store and removed from disk). Store-only entries are flat logical paths, not directory entries; read them back with read_workspace_file.", {
         path: z
             .string()
             .optional()
@@ -1110,24 +1111,47 @@ export function registerFileTools(server) {
                 ],
             };
         }
+        const diskNames = new Set();
+        let diskSection;
+        let diskError;
         try {
-            const entries = readdirSync(dir, { withFileTypes: true })
+            const diskEntries = readdirSync(dir, { withFileTypes: true });
+            for (const entry of diskEntries)
+                diskNames.add(entry.name);
+            diskSection = diskEntries
                 .map((entry) => `${entry.isDirectory() ? "[DIR]" : "[FILE]"} ${entry.name}`)
                 .join("\n");
-            return {
-                content: [{ type: "text", text: `# ${dir}\n\n${entries}` }],
-            };
         }
         catch (err) {
+            diskError = String(err);
+        }
+        const storePrefix = normalizeRelPath(rel);
+        let storeSection;
+        if (existsSync(getWorkspaceStorePath(WORKSPACE_ROOT))) {
+            const storeOnly = listStoreEntries(WORKSPACE_ROOT, storePrefix).filter((entry) => !diskNames.has(entry.path.slice(storePrefix.length).replace(/^\//, "").split("/")[0]));
+            if (storeOnly.length > 0) {
+                storeSection = storeOnly
+                    .map((entry) => `[STORE] ${entry.path}  (${entry.bytes}B)`)
+                    .join("\n");
+            }
+        }
+        if (diskError && !storeSection) {
             return {
                 content: [
                     {
                         type: "text",
-                        text: `❌ Could not list ${dir}\n${String(err)}`,
+                        text: `❌ Could not list ${dir}\n${diskError}`,
                     },
                 ],
             };
         }
+        const sections = [
+            diskError ? `(no such disk directory: ${diskError})` : diskSection || "(empty)",
+            storeSection ? `\nStore-only (not on disk):\n${storeSection}` : undefined,
+        ].filter(Boolean);
+        return {
+            content: [{ type: "text", text: `# ${dir}\n\n${sections.join("\n")}` }],
+        };
     });
     // ── Safe-edit (new P0 tool) ───────────────────────────────────────
     server.tool("safe_edit_file", "Edit a file using copy→validate→swap pattern. Automatically rolls back if validation or tests fail. Prefer apply_patch for small targeted edits. Cost: heavy for large files.", {

package/docs/cli-reference.md

@@ -73,6 +73,8 @@ ACE_HERMES_ROOT=/path/to/hermes-agent HERMES_PYTHON=/path/to/python \
   ace tui --provider llama.cpp --base-url http://localhost:8080 --model gemma-3-4b-it --hermes
 
 # Compact the store and sweep loose generated artifacts
+# (the sweep removes loose agent-state/*.md from disk on purpose after storing
+#  them — not data loss; read them back with `ace read <path>`, don't recreate)
 ace compact
 ace compact --no-sweep
 

package/docs/state-model.md

@@ -88,7 +88,7 @@ ace compact --no-sweep  # store rewrite only
 ace compact             # store rewrite plus loose generated-artifact sweep
 ```
 
-The default command runs a sweep after compaction: eligible loose generated ACE artifacts are ingested into the store and removed from disk. Use `--no-sweep` when only the container rewrite is intended. Back up the store and active goal directory before maintenance on a critical workspace.
+The default command runs a sweep after compaction: eligible loose generated ACE artifacts are ingested into the store and removed from disk. This removal is by design and is not data loss — the content lives in the store and is read back with `ace read <path>` (e.g. `ace read agent-state/TASK.md`) or the `read_workspace_file` / `recall_context` MCP tools. Agents should not recreate swept files. The same sweep also runs automatically on a lifecycle cadence (silently, with a short min-age guard), so loose `agent-state/*` files disappearing between sessions is expected. Use `--no-sweep` when only the container rewrite is intended. Back up the store and active goal directory before maintenance on a critical workspace.
 
 ### Repair
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voybio/ace-swarm",
-  "version": "2.4.6",
+  "version": "2.4.8",
   "description": "ACE Framework MCP server and CLI — single-file ACEPACK state, local-model serving, agent orchestration, and host compliance enforcement.",
   "type": "module",
   "main": "dist/index.js",