@voybio/ace-swarm 0.2.5 → 2.4.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [2.4.0] - 2026-05-02
+
+### Changed
+
+- Added `ace connect` so users can register an explicit local or hosted runtime profile without ACE inventing a local model preset.
+- Updated local runtime bootstrap and doctor guidance to avoid hardcoded `llama.cpp` model defaults when the user has not supplied one.
+- Added a Copilot CLI `.mcp.json` projection to `ace preconfig` while preserving the existing `.vscode/mcp.json` bridge.
+
 ## [2.3.0] - 2026-03-28
 
 ### Added
@@ -35,9 +43,19 @@
 - Expanded hook dispatch context to emit role-aware ACE tool hints from session, subagent, and tool lifecycle events.
 - Updated bootstrap and config rendering to generate multi-host hook artifacts under `.vscode`, `.cursor`, and `.mcp-config`.
 
+**Store-Unity Migration:**
+- Added `src/store/workspace-store-paths.ts` as the canonical resolver for the canonical/legacy ACE store transition. Every command that opens ACEPACK now uses this shared module; no command assembles `.agents/ACE/ace-state.ace` by hand.
+- `agent-state/ace-state.ace` is the canonical store for new and adopted workspaces. `.agents/ACE/ace-state.ace` is retained as a supported legacy input and fallback — not a second active write target.
+- Added `ensureCanonicalWorkspaceStore()`: legacy-only workspaces are atomically adopted into the canonical path on the first mutating operation (bootstrap, install, repair, compact, preconfig). The legacy file is preserved as a fallback after adoption.
+- Dual-store conflicts (both files exist with different content) surface an explicit warning and halt mutating commands rather than silently merging or overwriting.
+- Added `resolveWorkspaceStorePath()` for read-only resolution: returns the active path and mode without writing anything.
+- Bootstrap, skill install/list, repair, compact, and preconfig all updated to use the shared resolver.
+- CLI help text, doctor messages, and run-ledger artifacts updated to describe `agent-state/ace-state.ace` as canonical.
+- Added `test/store-unity-release.test.mjs` as a dedicated release gate covering legacy adoption, dual-store conflict, canonical-only skill install/repair/compact, and a source-scan guard that fails on new hard-coded legacy path references outside the resolver module.
+
 ### Validation
 
-- Verified `208/208` tests passing (up from 202) with full orchestrator supervisor, model bridge, and compliance enforcement coverage.
+- Verified `319/319` tests passing (up from 208) with full orchestrator supervisor, model bridge, compliance enforcement, and store-unity migration coverage.
 
 ## [2.2.0] - 2026-03-26
 

package/README.md

@@ -2,7 +2,7 @@
 
 Autonomous Coding Entity (ACE) is a local MCP server and CLI for agent-assisted coding.
 
-`ace-swarm` provides Claude Code, Codex, Cursor, VS Code, and provider-backed workflows with a shared runtime: durable workspace state, typed handoffs, scheduler support, change intelligence, and operator tooling. All state lives in a single binary file — `.agents/ACE/ace-state.ace` — so the workspace keeps one source of truth instead of a forest of generated state files.
+`ace-swarm` provides Claude Code, Codex, Cursor, GitHub Copilot CLI, VS Code, and provider-backed workflows with a shared runtime: durable workspace state, typed handoffs, scheduler support, change intelligence, and operator tooling. All state lives in a single binary file — `agent-state/ace-state.ace` — with `.agents/ACE/ace-state.ace` kept only as a legacy fallback for older workspaces.
 
 Modern coding agents can already read files, write code, run commands, and call tools. The missing layer is coordination that survives restarts, model switches, and multi-agent work. ACE keeps the workflow in the store and projects only the files external clients still need. For provider-backed runs, ACE provides task context, tool surfaces, status events, evidence trails, and resumable state.
 
@@ -13,14 +13,17 @@ Modern coding agents can already read files, write code, run commands, and call
 - Shared workflow state should live in the workspace, not only in chat history.
 - ACE-Orchestrator is the default entrypoint, and every provider can delegate through the full agent set.
 - Provider-backed runs should get the same structure and observability.
-- Bootstrap should be contained and reversible: ACE writes into `.agents/ACE/ace-state.ace`.
+- Bootstrap should be contained and reversible: ACE writes into `agent-state/ace-state.ace`, with legacy fallback reads from `.agents/ACE/ace-state.ace` where needed.
 
 ### Serving model providers
 
 ACE provides model providers with the context they cannot infer on their own: task state, tool surfaces, status events, evidence trails, and the next move in the loop.
 
 - `ace init --llm <provider>` records the selected runtime profile in the store.
+- `ace connect` records an explicit runtime profile from a user-chosen local runtime endpoint or hosted provider without inventing a local model preset.
 - `ace doctor` validates local or hosted runtime wiring, checks the selected model when the provider exposes listings, and keeps the runtime honest.
+- `ace doctor --scan` probes common Ollama and llama.cpp endpoints and writes the selected profile back into the store.
+- `ace tui` is provider-aware for `ollama`, `llama.cpp`, `codex`, `claude`, `gemini`, and `copilot` when credentials or base URLs are configured.
 - `ace mcp` and `ace tui` expose the same workspace truth to the host, the terminal, and the model.
 
 ## Why This Exists Now
@@ -38,7 +41,7 @@ ACE also provides scheduler primitives for queued work, dependency gates, leases
 
 ## ACEPACK State Model
 
-ACE uses a custom binary format called ACEPACK to present `.agents/ACE/ace-state.ace` as a structured single-file store. The file has three regions:
+ACE uses a custom binary format called ACEPACK to present `agent-state/ace-state.ace` as a structured single-file store. Existing workspaces that still carry `.agents/ACE/ace-state.ace` are read through the legacy fallback path. The file has three regions:
 
 ```
 ace-state.ace
@@ -80,7 +83,7 @@ Every `appendEntry()` call — handoffs, status events, ledger entries, session
 - Per-event overhead is ~19 bytes fixed vs ~150 bytes for equivalent JSON.
 - At 100,000 events, the fixed columns are ~1.9 MB; a full JSON log would be ~15 MB.
 
-Events accumulate for the workspace lifetime and survive `compact()`. Full historical replay is always available. See `HOT_COLD_EVENT_TIERING.md` for the future branch that adds compressed batch archiving for very long-lived workspaces.
+Events accumulate for the workspace lifetime and survive `compact()`. Full historical replay is always available.
 
 ### Why one state file
 
@@ -98,7 +101,7 @@ The store holds runtime state, agent instructions, skills, topology, schemas, an
 Bootstrap a workspace:
 
 ```bash
-npx -y ace-swarm turnkey --project "My Project"
+npx -y @voybio/ace-swarm turnkey --project "My Project"
 ace mcp
 ```
 
@@ -111,7 +114,7 @@ initiate ACE
 Local-model path with Ollama:
 
 ```bash
-npx -y ace-swarm turnkey --project "My Project" --llm ollama --model llama3.1:8b --base-url http://localhost:11434
+npx -y @voybio/ace-swarm turnkey --project "My Project" --llm ollama --model llama3.1:8b --base-url http://localhost:11434
 ollama serve
 ollama pull llama3.1:8b
 ace doctor --llm ollama --model llama3.1:8b --base-url http://localhost:11434
@@ -121,7 +124,7 @@ ace mcp
 Local-model path with llama.cpp:
 
 ```bash
-npx -y ace-swarm turnkey --project "My Project" --llm llama.cpp --model local-model --base-url http://localhost:8080
+npx -y @voybio/ace-swarm turnkey --project "My Project" --llm llama.cpp --model local-model --base-url http://localhost:8080
 llama-server -m /path/to/model.gguf --port 8080
 ace doctor --llm llama.cpp --model local-model --base-url http://localhost:8080
 ace mcp
@@ -132,7 +135,7 @@ If you already have a local runtime running, `ace doctor --scan` will probe comm
 Hosted provider path with Codex:
 
 ```bash
-npx -y ace-swarm turnkey --project "My Project" --llm codex --model gpt-5
+npx -y @voybio/ace-swarm turnkey --project "My Project" --llm codex --model gpt-5
 export OPENAI_API_KEY=...
 ace doctor --llm codex --model gpt-5
 ace mcp
@@ -140,9 +143,10 @@ ace mcp
 
 ## What Bootstrap Writes
 
-ACE bootstrap is intentionally contained. The store is authoritative at `.agents/ACE/ace-state.ace`; only a few host-facing files land in the workspace when requested.
+ACE bootstrap is intentionally contained. The store is authoritative at `agent-state/ace-state.ace`; only a few host-facing files land in the workspace when requested.
 
-- `.agents/ACE/ace-state.ace` — runtime state, agent instructions, skills, topology, schemas, and the event log
+- `agent-state/ace-state.ace` — runtime state, agent instructions, skills, topology, schemas, and the event log
+- `.agents/ACE/ace-state.ace` — legacy fallback for existing workspaces
 - `.agents/ACE/ace-hook-context.json` — compact hook snapshot for external clients
 - `.agents/ACE/tasks/todo.md` — human-facing todo surface
 - Optional workspace-root stubs — `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`, and `.vscode/mcp.json`
@@ -159,6 +163,11 @@ Developer or MCP host
   |       |
   |       `-- calls ace-swarm over MCP
   |
+  +-- agent-state/
+  |       |
+  |       +-- ace-state.ace
+  |       +-- STATUS.md / TASK.md / HANDOFF.json projections
+  |
   +-- ace mcp
   |       |
   |       +-- tools, prompts, resources
@@ -168,7 +177,6 @@ Developer or MCP host
   |
   +-- .agents/ACE/
   |       |
-  |       +-- ace-state.ace
   |       +-- ace-hook-context.json
   |       +-- tasks/todo.md
   |       `-- host config bundles
@@ -190,7 +198,7 @@ Developer or MCP host
 | Runtime roles        | swarm and composable runtime roles                           |
 | Skills               | packaged skills                                              |
 | MCP server           | stdio surface for tools, prompts, resources, and workflows   |
-| Durable state        | single .ace authority for handoffs, status events, todos, run ledger, job queue, and discovery |
+| Durable state        | single `agent-state/ace-state.ace` authority for handoffs, status events, todos, run ledger, job queue, and discovery |
 | Projections          | hook context, todo surface, and host config bundles          |
 | Coordination         | scheduler queues, dependency gates, leases, and resource locks |
 | Change intelligence  | delta scan, semantic snapshots, drift reports, rewrite hints |
@@ -215,7 +223,7 @@ In that setup, the host remains the interface. ACE becomes the state contract un
 
 Local models are good at generating text. They usually need help seeing the workspace, hearing the handoff trail, and remembering what changed two turns ago. ACE closes that gap.
 
-- `ace init --llm <provider>` seeds the profile inside `.agents/ACE/ace-state.ace`.
+- `ace init --llm <provider>` seeds the profile inside `agent-state/ace-state.ace`.
 - `ace doctor` verifies that the selected runtime is configured and, when possible, reachable.
 - `ace tui` can talk to either local runtime and surface the same workspace state the MCP server sees.
 - The ACE model bridge gives local runs tool selection, execution flow, and persisted state instead of a fragile one-shot chat loop.

package/assets/.agents/ACE/agent-qa/instructions.md

@@ -1,6 +1,17 @@
 ---
 applyTo: 'agent-qa'
 ---
+<!-- ACE Bridge Contract — high salience: this block takes precedence over all directives below -->
+## ACE Bridge Contract (Non-Negotiable)
+
+**Short structured verdict:** Your completion summary must be a concise structured verdict — pass/fail counts, gate status, and failure classification. Do NOT reproduce file content, rewrite artifacts, or include large code blocks.
+
+**Read-only enforcement:** Do not modify, rewrite, or improve the artifacts you inspect. If an artifact has a bug, classify it and route it — do not fix it inline.
+
+**No artifact drift:** If you find yourself generating large code blocks or reproducing the full content of an inspected file, stop immediately and restate as a short verdict summary instead.
+
+---
+
 # agent-qa Execution Instructions
 
 ## Operating Objective

package/assets/agent-state/EVIDENCE_LOG.md

@@ -4,4 +4,4 @@ Append-only chain-of-custody for checks, decisions, and execution proofs.
 
 ## Entries
 
-- {{BOOTSTRAP_TIMESTAMP}} | bootstrap initialized | evidence_ref: `EVIDENCE_LOG.md#ts:{{BOOTSTRAP_TIMESTAMP}}`
+- 2026-03-03T00:00:00Z | bootstrap initialized | evidence_ref: `EVIDENCE_LOG.md#ts:2026-03-03T00:00:00Z`

package/assets/agent-state/MODULES/roles/capability-framework.json

@@ -0,0 +1,41 @@
+{
+  "id": "capability-framework",
+  "version": "1.0.0",
+  "objective": "Validate ACE framework contracts, execute gate bundles, and enforce state integrity checks",
+  "permissions": [
+    "allow_file_io",
+    "allow_shell_exec"
+  ],
+  "inputs": [
+    {
+      "file": "TEAL_CONFIG.md",
+      "critical": true
+    },
+    {
+      "file": "QUALITY_GATES.md",
+      "critical": true
+    },
+    {
+      "file": "HANDOFF.json",
+      "critical": true
+    },
+    {
+      "file": "MODULES/registry.json",
+      "critical": true
+    }
+  ],
+  "outputs": [
+    {
+      "file": "EVIDENCE_LOG.md",
+      "validation_gate": "gate-completeness"
+    },
+    {
+      "file": "STATUS_EVENTS.ndjson",
+      "validation_gate": "gate-autonomy"
+    }
+  ],
+  "failure_routing": {
+    "missing_input": "BLOCK_AND_REQUEST_INFO",
+    "gate_failure": "ESCALATE_TO_CAPABILITY_OPS"
+  }
+}

package/assets/agent-state/MODULES/roles/capability-git.json

@@ -0,0 +1,33 @@
+{
+  "id": "capability-git",
+  "version": "1.0.0",
+  "objective": "Execute repository initialization and commit operations with traceable evidence",
+  "permissions": [
+    "allow_file_io",
+    "allow_shell_exec"
+  ],
+  "inputs": [
+    {
+      "file": "STATUS.md",
+      "critical": false
+    },
+    {
+      "file": "EVIDENCE_LOG.md",
+      "critical": true
+    }
+  ],
+  "outputs": [
+    {
+      "file": "EVIDENCE_LOG.md",
+      "validation_gate": "gate-completeness"
+    },
+    {
+      "file": "STATUS_EVENTS.ndjson",
+      "validation_gate": "gate-autonomy"
+    }
+  ],
+  "failure_routing": {
+    "missing_input": "BLOCK_AND_REQUEST_INFO",
+    "gate_failure": "ESCALATE_TO_CAPABILITY_OPS"
+  }
+}

package/assets/agent-state/MODULES/roles/capability-safety.json

@@ -0,0 +1,37 @@
+{
+  "id": "capability-safety",
+  "version": "1.0.0",
+  "objective": "Apply safety checks and fail-closed validation before mutating critical ACE artifacts",
+  "permissions": [
+    "allow_file_io",
+    "allow_shell_exec"
+  ],
+  "inputs": [
+    {
+      "file": "HANDOFF.json",
+      "critical": false
+    },
+    {
+      "file": "QUALITY_GATES.md",
+      "critical": true
+    },
+    {
+      "file": "EVIDENCE_LOG.md",
+      "critical": true
+    }
+  ],
+  "outputs": [
+    {
+      "file": "EVIDENCE_LOG.md",
+      "validation_gate": "gate-completeness"
+    },
+    {
+      "file": "STATUS_EVENTS.ndjson",
+      "validation_gate": "gate-autonomy"
+    }
+  ],
+  "failure_routing": {
+    "missing_input": "BLOCK_AND_REQUEST_INFO",
+    "gate_failure": "BLOCK_AND_ESCALATE"
+  }
+}

package/assets/agent-state/MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json

@@ -145,6 +145,27 @@
         "registry_path": {
           "type": "string",
           "minLength": 1
+        },
+        "surgical_read_budgets": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "small_local": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "mid": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "frontier": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 1
+            }
+          }
         }
       }
     },

package/assets/agent-state/MODULES/schemas/RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json

@@ -163,6 +163,46 @@
           "items": {
             "$ref": "#/$defs/tool_call"
           }
+        },
+        "turn_outcome": {
+          "type": "string",
+          "enum": [
+            "no_op_success",
+            "meaningful_completion",
+            "escalation_blocker"
+          ]
+        },
+        "outcome_reason": {
+          "type": "string"
+        }
+      }
+    },
+    "output_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "emit_to",
+        "silent_unless_blocked",
+        "require_approval_before_emit"
+      ],
+      "properties": {
+        "emit_to": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "tui",
+              "tracker",
+              "handoff",
+              "vericify"
+            ]
+          }
+        },
+        "silent_unless_blocked": {
+          "type": "boolean"
+        },
+        "require_approval_before_emit": {
+          "type": "boolean"
         }
       }
     },
@@ -278,6 +318,9 @@
             "failed"
           ]
         },
+        "output_policy": {
+          "$ref": "#/$defs/output_policy"
+        },
         "turns": {
           "type": "array",
           "items": {

package/assets/agent-state/MODULES/schemas/RUNTIME_TOOL_SPEC_REGISTRY.schema.json

@@ -108,6 +108,46 @@
         }
       }
     },
+    "mcp_server": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "transport"
+      ],
+      "properties": {
+        "transport": {
+          "type": "string",
+          "enum": [
+            "stdio",
+            "http"
+          ]
+        },
+        "command": {
+          "type": "string"
+        },
+        "args": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "url": {
+          "type": "string"
+        },
+        "env": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "tool_allowlist": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
     "tool_spec": {
       "type": "object",
       "additionalProperties": false,
@@ -137,6 +177,9 @@
         },
         "executor": {
           "$ref": "#/$defs/executor"
+        },
+        "mcp_server": {
+          "$ref": "#/$defs/mcp_server"
         }
       }
     }

package/assets/agent-state/MODULES/schemas/WORKSPACE_SESSION_REGISTRY.schema.json

@@ -72,6 +72,17 @@
           "last_error": {
             "type": "string"
           },
+          "hook_health": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "degraded",
+              "failed"
+            ]
+          },
+          "hook_summary": {
+            "type": "string"
+          },
           "created_at": {
             "type": "string",
             "format": "date-time"

package/assets/agent-state/STATUS.md

@@ -1,8 +1,8 @@
 # STATUS
 
-- Current role: `ace-orchestrator`
+- Current role: `capability-skeptic`
 - Current phase: `STATE_ANALYSIS`
 - Active pipeline: `standard`
 - Blockers: `none`
 - Current objective delta: `bootstrap complete, awaiting first scoped objective`
-- Last update: `{{BOOTSTRAP_TIMESTAMP}}`
+- Last update: `2026-03-03T00:00:00Z`

package/assets/agent-state/runtime-tool-specs.json

@@ -1,5 +1,73 @@
 {
   "version": 1,
-  "updated_at": "1970-01-01T00:00:00.000Z",
-  "tools": []
+  "updated_at": "2026-05-06T00:00:00.000Z",
+  "tools": [
+    {
+      "name": "duckduckgo_search_fetch_mcp_example",
+      "description": "Example configurable DuckDuckGo-style search/fetch MCP server class. Cost: moderate. This is a registry template; provider command/env must be supplied by workspace policy before use.",
+      "input_schema": {
+        "type": "object",
+        "required": [
+          "query"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Search query"
+          },
+          "fetch_urls": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Optional URLs to fetch after search"
+          }
+        }
+      },
+      "success_schema": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "citations": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          },
+          "fetches": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          }
+        }
+      },
+      "failure_schema": {
+        "type": "object",
+        "additionalProperties": true
+      },
+      "executor": {
+        "command": "node -e \"const fs=require('node:fs'); fs.writeFileSync(process.env.ACE_RUNTIME_TOOL_RESPONSE_FILE, JSON.stringify({ok:false, summary:'DuckDuckGo MCP example is not configured in this workspace.', error:{reason_code:'provider_unconfigured'}}));\"",
+        "timeout_ms": 30000,
+        "env": {
+          "ACE_RUNTIME_TOOL_PROVIDER": "duckduckgo-mcp-example"
+        }
+      },
+      "mcp_server": {
+        "transport": "stdio",
+        "command": "duckduckgo-mcp-server",
+        "args": [],
+        "env": {
+          "ACE_MCP_PROVIDER": "duckduckgo"
+        },
+        "tool_allowlist": [
+          "search",
+          "fetch"
+        ]
+      }
+    }
+  ]
 }

package/assets/instructions/ACE_Coder.instructions.md

@@ -1,6 +1,19 @@
 ---
 applyTo: 'ACE_coders'
 ---
+<!-- ACE Bridge Contract — high salience: this block takes precedence over all directives below -->
+## ACE Bridge Contract (Non-Negotiable)
+
+**Output envelope:** Every response MUST be a valid JSON object with a `"status"` key. Do NOT wrap your JSON in markdown code fences. Do NOT add prose before or after it.
+
+**One envelope per response:** Emit exactly one top-level JSON object per turn. No preamble, no narration, no code fence wrappers around the envelope itself.
+
+**Tool-first discipline:** If the task requires writing, modifying, or creating files, call the appropriate write tool inside `tool_calls`. Do not narrate the change — execute it via a tool call.
+
+**No echo drift:** Do not reproduce the task description, the expected spec shape, or test output as your completion summary. State what you accomplished concisely.
+
+---
+
 # ACE Coders v7.1
 
 ## The Engineering Swarm — High-Performance TDD Execution Unit

package/assets/instructions/ACE_UI.instructions.md

@@ -1,6 +1,17 @@
 ---
 applyTo: 'ACE-UI'
 ---
+<!-- ACE Bridge Contract — high salience: this block takes precedence over all directives below -->
+## ACE Bridge Contract (Non-Negotiable)
+
+**Output format:** Your primary deliverable is **prose**. You may include brief HTML or JSON snippets inline as illustrations. Never produce a full HTML document, a large standalone JSON structure, or a raw data file as your main response.
+
+**Stay on scope:** When given a specific outline or a section list, follow it exactly. Do not invent new sections or expand the scope beyond what was requested.
+
+**No semantic drift:** If the task requests a CRISPR-style outline, produce only that outline. Do not layer in brand strategy, personas, or strategic narrative unless the operator explicitly requested those.
+
+---
+
 # CX-OS Framework v1.2 (Mercer-Integrated)
 
 ## Content Experience Operating System — Strategic Brand, UX & Visual Orchestration