@voybio/ace-swarm 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+## [2.3.0] - 2026-03-28
+
+### Added
+
+**Orchestrator Supervisor:**
+- Added `run_orchestrator` MCP tool for full task-plan execution with explicit step routing, sequential/parallel dispatch, and handoff create/ack flows.
+- Added Vericify context carry-forward and delta recovery for state continuity across plan execution.
+- Added circuit breaker open/close hooks for upstream failure handling.
+- Added plan amendment support during mid-execution.
+
+**Model Bridge Context Management:**
+- Added context budget calculation with configurable reserve (default 25%) to prevent overflow.
+- Added tier fallback (full → compressed → brief) when context exceeds budget.
+- Added automatic conversation history compaction (summarize older messages, retain recent messages + system).
+- Added large tool-result write-through to disk with configurable truncation (default 3000 chars).
+- Added retry-once on transient provider errors (abort, timeout, rate-limit).
+
+**ACE Compliance Enforcement:**
+- Added 5-layer ACE compliance enforcement: MCP instructions, per-host instruction files, lifecycle hooks, tool-level guidance, and bootstrap-on-first-tool.
+- Added per-host instruction file generation for CLAUDE.md, .cursorrules, .github/copilot-instructions.md, and Codex AGENTS.md.
+- Added lifecycle hook dispatcher (`ace-hook-dispatch.mjs`) with role-aware tool hints for 7 hosts.
+- Added tool-level soft enforcement via guidance appended to all tool results.
+- Added bootstrap nudge lifecycle for lazy ACE context loading on first mutation tool.
+
+**Tool Governance:**
+- Added named sets for explicit tool classification: BOOTSTRAP_TOOLS, REFRESH_TOOLS, NAMED_MUTATION_TOOLS.
+- Added maintenance comments on mutable tool sets to prevent accidental out-of-sync registrations.
+- Added Vericify resolution scoping with `startsWith` validation to prevent parent-directory leakage.
+
+### Changed
+
+- Changed agent worker and runner behavior so blocked or idle TUI agents can accept new input and resume without relaunching.
+- 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`.
+
+### Validation
+
+- Verified `208/208` tests passing (up from 202) with full orchestrator supervisor, model bridge, and compliance enforcement coverage.
+
+## [2.2.0] - 2026-03-26
+
+### Added
+- Added `ace turnkey` command for rapid workspace bootstrap with one command.
+- Added `ace tui` command for a full terminal operator surface with status, tasks, chat, and telemetry.
+- Expanded the packaged skill system to 15 skills, including `landing-review-watcher`, `problem-triage`, `skill-auditor`, and `astgrep-index`.
+- Finalized the 17-agent role system (4 swarm, 13 composable).
+- Added automatic MCP client configuration for Codex, VS Code, Claude Desktop, Cursor, and Antigravity.
+- Expanded the MCP tool surface to 70+ tools across 12 domain-specific modules.
+
+### Packaging
+- Bumped package version from `2.1.0` to `2.2.0`.
+- Verified 170/170 tests passing on the final v2.2.0 release candidate.
+
+## [2.1.0] - 2026-03-13
+
+### Changed
+
+- Rewrote the package README into a tighter operator-facing format with ASCII system maps and compact internal tables.
+- Added a recent-release summary to the README so the last three versions remain visible without turning the README into a full changelog.
+
+### Added
+
+- Added `CHANGELOG.md` to track tagged package release notes directly in the package.
+
+### Packaging
+
+- Bumped package version from `2.0.7` to `2.1.0`.
+
+## [2.0.7] - 2026-03-13
+
+### Added
+
+- Added runtime profile, runtime command, runtime executor, and runtime tool spec surfaces.
+- Added tracker adapters and tracker snapshot synchronization.
+- Added workspace-manager and Vericify bridge surfaces.
+- Added problem triage, skill auditor, skill catalog, and public-surface audit modules.
+- Added VS Code Copilot hook scaffolding and new packaged runtime/state schema assets.
+
+### Validation
+
+- Added broad new test coverage for runtime execution, tracker adapters, workspace management, problem triage, skill auditing, public surface checks, Vericify bridge behavior, and Copilot hook dispatch.
+
+## [2.0.6] - 2026-03-10
+
+### Fixed
+
+- Hardened bootstrap workspace path handling in `src/helpers.ts`.
+- Updated `assets/scripts/bootstrap-workspace.sh` to align with the fixed workspace bootstrap path flow.
+
+### Validation
+
+- Added integration coverage for workspace bootstrap behavior.
+
+## [2.0.5] - 2026-03-10
+
+### Added
+
+- Added packaged `ARTIFACT_MANIFEST.json`.
+- Expanded artifact-manifest and provenance-related schema coverage.
+
+### Changed
+
+- Tightened framework/file tool handling around artifact manifests and provenance enforcement.
+
+### Validation
+
+- Added integration and schema tests for the artifact-manifest path.

package/LICENSE

@@ -0,0 +1,186 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 ACE Swarm contributors
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work (an example is provided in the Appendix
+below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+"submitted" means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and
+issue tracking systems that are managed by, or on behalf of, the Licensor for
+the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright
+owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License,
+each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable (except as stated in this section) patent
+license to make, have made, use, offer to sell, sell, import, and otherwise
+transfer the Work, where such license applies only to those patent claims
+licensable by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s) with the Work
+to which such Contribution(s) was submitted. If You institute patent litigation
+against any entity (including a cross-claim or counterclaim in a lawsuit)
+alleging that the Work or a Contribution incorporated within the Work
+constitutes direct or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate as of the date
+such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any
+part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents of
+the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a
+whole, provided Your use, reproduction, and distribution of the Work otherwise
+complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+either express or implied, including, without limitation, any warranties or
+conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any
+character arising as a result of this License or out of the use or inability to
+use the Work (including but not limited to damages for loss of goodwill, work
+stoppage, computer failure or malfunction, or any and all other commercial
+damages or losses), even if such Contributor has been advised of the possibility
+of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations and/or
+rights consistent with this License. However, in accepting such obligations, You
+may act only on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify, defend, and hold
+each Contributor harmless for any liability incurred by, or claims asserted
+against, such Contributor by reason of your accepting any such warranty or
+additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "[]" replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier identification within
+third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,229 @@
+# ACE Swarm MCP Server and CLI
+
+Autonomous Coding Entity (ACE) is a local MCP server and CLI for agent-assisted coding.
+
+`ace-swarm` gives Claude Code, Codex, Cursor, VS Code, and local-model workflows a shared runtime: durable workspace state, typed handoffs, scheduler primitives, change intelligence, and operator tooling. It is built around a Zarrita-backed `.agents/ACE/ace-state.zarr` store, so the workspace keeps one source of truth instead of a forest of generated state files.
+
+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 fills that gap by keeping the workflow in the store and projecting only the few files external clients still need. For local models, ACE provides the eyes and ears they usually lack: task context, tool surfaces, status events, evidence trails, and resumable state.
+
+## ACE Manifesto
+
+- Agent work should survive restarts, handoffs, and review.
+- Handoffs should be typed, evidence-linked, and validated.
+- Shared workflow state should live in the workspace, not only in chat history.
+- Local models should get the same structure and observability as hosted models.
+- Bootstrap should be contained and reversible: ACE writes into `.agents/ACE/ace-state.zarr`.
+
+### Serving local models
+
+ACE is the eyes and ears for local models. It gives them 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 ollama` or `ace init --llm llama.cpp` records a local runtime profile in the store.
+- `ace doctor` discovers the endpoint, checks the selected model, and keeps the runtime honest.
+- `ace mcp` and `ace tui` expose the same workspace truth to the host, the terminal, and the model.
+
+## Why This Exists Now
+
+Frontier models are getting more capable and more restricted at the same time. Providers are tightening scope, access windows, and usage limits, which makes the hosted path less dependable for long-running agent work. Local models are slower, but they are available, and with ACE they can still do real work because ACE gives them the missing eyes and ears: shared context, tool surfaces, status events, evidence trails, and resumable state.
+
+- Claude Code proved the terminal-native agent loop.
+- OpenAI connectors and MCP widened the tool surface.
+- Ollama and llama.cpp keep local models in play.
+- MCP remains the common protocol surface across clients and runtimes.
+
+ACE sits underneath that stack. It does not compete with the host you already use. It gives that host a durable local runtime.
+
+## Zarr State Model
+
+ACE uses `@zarrita/core` and `@zarrita/storage` to present `.agents/ACE/ace-state.zarr` as a hierarchical store.
+Zarrita.js supplies the Zarr v3 groups, arrays, and typed views; ACE supplies `AcePackedStore`, the single-file local backend that keeps the store portable and atomic.
+
+### Why one state file
+
+| One `.zarr` authority | What it avoids |
+|---|---|
+| One read/write source of truth | Hundreds of generated state files drifting apart |
+| Zarr groups and arrays | Hand-rolled file sprawl for runtime state, instructions, and indexes |
+| Typed hot fields | Repeated JSON parsing for counters and scheduler state |
+| Store-backed projections | External tools reading the same truth through different paths |
+
+The store holds runtime state, agent instructions, skills, topology, schemas, and indexes. Materialized files exist only when an external client still needs a path on disk.
+
+## Quick Start
+
+Bootstrap a workspace:
+
+```bash
+npx -y ace-swarm turnkey --project "My Project"
+ace mcp
+```
+
+Then, in your MCP host:
+
+```text
+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
+ollama serve
+ollama pull llama3.1:8b
+ace doctor --llm ollama --model llama3.1:8b --base-url http://localhost:11434
+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
+llama-server -m /path/to/model.gguf --port 8080
+ace doctor --llm llama.cpp --model local-model --base-url http://localhost:8080
+ace mcp
+```
+
+If you already have a local runtime running, `ace doctor --scan` will probe common Ollama and llama.cpp endpoints and write the selected profile back into the store.
+
+## What Bootstrap Writes
+
+ACE bootstrap is intentionally contained. The store is authoritative at `.agents/ACE/ace-state.zarr`; only a few host-facing files land in the workspace when requested.
+
+- `.agents/ACE/ace-state.zarr` — runtime state, agent instructions, skills, topology, schemas, and indexes
+- `.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`
+- Store-backed host snippets — `.mcp-config/*`, exported by `ace mcp-config` for optional global install
+
+That containment matters. ACE is meant to structure the workflow, not contaminate the application tree. One store keeps the truth coherent, and the projections keep outside tools happy without turning the workspace into a generated-file forest.
+
+## Where ACE Fits
+
+```text
+Developer or MCP host
+  |
+  +-- Claude Code / Codex / Cursor / VS Code / Antigravity
+  |       |
+  |       `-- calls ace-swarm over MCP
+  |
+  +-- ace mcp
+  |       |
+  |       +-- tools, prompts, resources
+  |       +-- typed handoff validation
+  |       +-- scheduler and resource locks
+  |       `-- state-aware workflow tools
+  |
+  +-- .agents/ACE/
+  |       |
+  |       +-- ace-state.zarr
+  |       +-- ace-hook-context.json
+  |       +-- tasks/todo.md
+  |       `-- host config bundles
+  |
+  `-- ace tui
+          |
+          +-- chat
+          +-- agent tabs
+          +-- telemetry
+          `-- provider-aware runtime
+```
+
+## What Ships Today
+
+```text
++----------------------+--------------------------------------------------------------+
+| Surface              | Current scope                                                |
++----------------------+--------------------------------------------------------------+
+| Runtime roles        | 17 runtime roles: 4 swarm roles + 13 composable roles        |
+| Skills               | 15 packaged skills                                           |
+| MCP server           | stdio server for tools, prompts, resources, and workflows    |
+| Durable state        | single `.zarr` authority for handoffs, status events, todo state, run ledger, job queue, and discovery |
+| Projections          | hook context, todo surface, and host configs when needed      |
+| Coordination         | priority dispatch, dependency gates, leases, resource locks  |
+| Change intelligence  | delta scan, semantic snapshots, drift reports, rewrite hints |
+| Terminal UI          | provider-aware TUI with chat, tabs, telemetry, agent tabs    |
+| Local models         | Ollama and llama.cpp bootstrap, doctor checks, model bridge, tool loops |
+| Verification         | 208 tests passing in the current suite                       |
++----------------------+--------------------------------------------------------------+
+```
+
+## Agent-Assisted Coding, Structured
+
+ACE is for teams and solo operators who already like their coding host and want the workflow around it to stop leaking.
+
+- Use Claude Code, Codex, Cursor, or VS Code as the front end.
+- Use MCP as the tool protocol.
+- Use ACE as the shared local runtime.
+- Use Ollama or another OpenAI-compatible backend when you want the model local or provider-swappable.
+
+In that setup, the host remains the interface. ACE becomes the state contract underneath it.
+
+## Local Models
+
+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 ollama` or `ace init --llm llama.cpp` seeds the profile inside `.agents/ACE/ace-state.zarr`.
+- `ace doctor` verifies that the selected runtime is reachable and configured.
+- `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.
+
+If you want local agents with memory, evidence, and handoff discipline, this is the point of the package.
+
+## Compatible Surfaces
+
+```text
++-------------------+------------------------------------------------------------------+
+| Layer             | Current integration                                               |
++-------------------+------------------------------------------------------------------+
+| MCP clients       | Codex, VS Code, Claude Desktop, Cursor, Antigravity              |
+| Hook bundles      | Codex, VS Code, Claude, Cursor, Antigravity, Gemini-compatible   |
+| Model backends    | Ollama, llama.cpp, and OpenAI-compatible providers               |
+| Operator surface  | `ace tui`                                                        |
+| Bootstrap entry   | `ace init` (store-first), `ace turnkey` (store + host stubs)     |
++-------------------+------------------------------------------------------------------+
+```
+
+## CLI
+
+```text
++---------------------------------------------+---------------------------------------------------+
+| Command                                     | Purpose                                           |
++---------------------------------------------+---------------------------------------------------+
+| `ace init [options]`                        | seed the ACE store and optional host stubs        |
+| `ace turnkey [options]`                     | project the store-backed host surface              |
+| `ace mcp` / `ace serve`                     | start the MCP server over stdio                   |
+| `ace tui [options]`                         | open the terminal operator surface                |
+| `ace doctor [options]`                      | validate local-model readiness                    |
+| `ace mcp-config [--client <name>|--all]`    | print baked client snippets for optional install  |
+| `ace paths`                                 | show resolved package and workspace paths         |
++---------------------------------------------+---------------------------------------------------+
+```
+
+
+## Development
+
+```bash
+cd ace-mcp-server
+npm install
+npm run build
+npm test
+npm run start
+```
+
+See [CHANGELOG.md](./CHANGELOG.md) for release history.
+
+## References
+
+- [Claude Code overview](https://docs.anthropic.com/en/docs/claude-code/overview)
+- [OpenAI connectors and MCP servers](https://platform.openai.com/docs/guides/tools-remote-mcp?lang=python)
+- [Introducing GPT-5.2-Codex](https://openai.com/index/introducing-gpt-5-2-codex/)
+- [Ollama tool calling and agent loops](https://docs.ollama.com/capabilities/tool-calling)
+- [llama.cpp](https://github.com/ggerganov/llama.cpp)
+- [Zarrita.js](https://zarrita.dev/)
+- [Model Context Protocol SDKs](https://modelcontextprotocol.io/docs/sdk)
+
+## License
+
+Apache-2.0
+
+Collaborations, ideas, or concerns: `voybio.fundr@gmail.com`