@voybio/ace-swarm 2.4.0 → 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

package/README.md

@@ -20,6 +20,7 @@ Modern coding agents can already read files, write code, run commands, and call
 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.

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/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/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

package/dist/ace-context.js

@@ -22,9 +22,15 @@ const ROLE_TOOL_DEFAULTS = {
         "emit_status_event",
     ],
     coders: [
-        "read_workspace_file",
-        "write_workspace_file",
+        "outline_file",
+        "astgrep_query",
+        "astgrep_locate",
+        "read_file_lines",
+        "compile_structural_edit",
+        "preview_structural_edit",
+        "astgrep_rewrite",
         "safe_edit_file",
+        "write_workspace_file",
         "run_tests",
         "git_diff",
         "git_status",
@@ -91,8 +97,13 @@ export function renderAceContinuityPromptBlock(packet) {
     return packet ? formatAceContinuityPacketMarkdown(packet) : "";
 }
 function keywordScore(task, tool) {
-    const haystack = `${tool.name} ${tool.description} ${tool.input_keys.join(" ")}`.toLowerCase();
-    return task
+    const name = typeof tool?.name === "string" ? tool.name : String(tool?.name ?? "");
+    const desc = typeof tool?.description === "string" ? tool.description : String(tool?.description ?? "");
+    const inputs = Array.isArray(tool?.input_keys) ? tool.input_keys.join(" ") : "";
+    const haystack = `${name} ${desc} ${inputs}`.toLowerCase();
+    if (!task)
+        return 0;
+    return String(task)
         .toLowerCase()
         .split(/[^a-z0-9_]+/)
         .filter((token) => token.length > 2)
@@ -107,17 +118,26 @@ function selectToolCount(tier) {
 }
 function scopeTools(role, task, tier, explicitTools) {
     const catalog = listAceInternalToolCatalog();
-    if (explicitTools && explicitTools.length > 0) {
+    if (Array.isArray(explicitTools)) {
+        if (explicitTools.length === 0) {
+            return [];
+        }
         const explicitSet = new Set(explicitTools);
         return catalog.filter((tool) => explicitSet.has(tool.name));
     }
-    const roleDefaults = new Set(ROLE_TOOL_DEFAULTS[role.trim().toLowerCase()] ?? []);
+    const defaultTools = ROLE_TOOL_DEFAULTS[role.trim().toLowerCase()] ?? [];
+    const roleDefaults = new Set(defaultTools);
+    const rolePriority = new Map(defaultTools.map((name, index) => [name, index]));
     const ranked = catalog
         .map((tool) => ({
         tool,
         score: (roleDefaults.has(tool.name) ? 5 : 0) + keywordScore(task, tool),
     }))
-        .sort((left, right) => right.score - left.score || left.tool.name.localeCompare(right.tool.name))
+        .sort((left, right) => (roleDefaults.has(left.tool.name) && roleDefaults.has(right.tool.name)
+        ? (rolePriority.get(left.tool.name) ?? 999) - (rolePriority.get(right.tool.name) ?? 999)
+        : right.score - left.score) ||
+        right.score - left.score ||
+        left.tool.name.localeCompare(right.tool.name))
         .slice(0, selectToolCount(tier))
         .map((entry) => entry.tool);
     if (ranked.length > 0 && ranked.some((tool) => roleDefaults.has(tool.name))) {
@@ -130,7 +150,7 @@ function renderToolCatalogMarkdown(tools, tier) {
     return tools
         .map((tool) => {
         const parts = [`- \`${tool.name}\` — ${tool.description || "ACE MCP tool"}`];
-        if (includeInputs && tool.input_keys.length > 0) {
+        if (includeInputs && Array.isArray(tool.input_keys) && tool.input_keys.length > 0) {
             parts.push(`  - input keys: ${tool.input_keys.join(", ")}`);
         }
         return parts.join("\n");
@@ -157,7 +177,7 @@ function buildPlanningCatalog(role, task, tier) {
         .map((entry) => entry.tool);
 }
 function inferRelevantSkills(task) {
-    const lowered = task.toLowerCase();
+    const lowered = String(task ?? "").toLowerCase();
     const skillSignals = [
         { name: "state-auditor", pattern: /\b(state|drift|authority|audit)\b/ },
         { name: "handoff-lint", pattern: /\b(handoff|transition|payload)\b/ },
@@ -175,7 +195,8 @@ function inferRelevantSkills(task) {
 }
 export function buildToolPlan(options) {
     const tier = options.tier ?? "compressed";
-    const catalog = Array.isArray(options.tools) && options.tools.length > 0
+    const explicitToolsProvided = Array.isArray(options.tools);
+    const catalog = explicitToolsProvided
         ? listAceInternalToolCatalog().filter((tool) => options.tools?.includes(tool.name))
         : buildPlanningCatalog(options.role, options.task, tier);
     const recommended = scopeTools(options.role, options.task, tier, options.tools).map((tool) => tool.name);
@@ -202,6 +223,42 @@ export function buildToolPlan(options) {
         selection_limit: selectionLimit,
     };
 }
+/**
+ * Per-role negative output-shape guardrails injected into the system prompt.
+ * These complement the shared "## Output Contract" block with role-specific drift constraints.
+ *
+ * - coders/builder: bridge response must be a JSON envelope; they CAN write HTML/code via tools.
+ * - vos/ui: primary output is prose; snippets are fine inline but full HTML docs are not their job.
+ */
+const ROLE_OUTPUT_SHAPE_GUARDRAILS = {
+    coders: [
+        "- Your bridge response MUST be a JSON envelope (status: tool, complete, etc.) — do not send raw prose as your top-level reply.",
+        "- For code mutation, default to astgrep_locate -> compile_structural_edit -> preview_structural_edit -> astgrep_rewrite(plan_id).",
+        "- Use write_workspace_file for new files, generated non-code artifacts, or explicit structural_edit_waiver cases only.",
+        "- If you bypass the structural lane for code, state the waiver reason and provide evidence_refs.",
+        "- Do NOT echo the task description or expected artifact shape as your response without executing via tool calls.",
+        "- If you are writing files, call the write tool first, then close with status:complete and evidence_refs.",
+    ],
+    builder: [
+        "- Your bridge response MUST be a JSON envelope — raw prose as the top-level reply is a contract violation.",
+        "- For code mutation, default to astgrep_locate -> compile_structural_edit -> preview_structural_edit -> astgrep_rewrite(plan_id).",
+        "- Use write_workspace_file for new files, generated non-code artifacts, or explicit structural_edit_waiver cases only.",
+        "- If you bypass the structural lane for code, state the waiver reason and provide evidence_refs.",
+        "- Do NOT echo the artifact shape without executing the build step via tool calls.",
+        "- File content (code, HTML, configs) belongs inside tool calls, not in raw text output.",
+        "- If you are writing files, close with status:complete and evidence_refs after the write tool succeeds.",
+    ],
+    vos: [
+        "- Your primary output is prose. Inline code snippets or JSON examples are acceptable when illustrating a point.",
+        "- Do NOT produce a full HTML document or a raw JSON structure as your main deliverable.",
+        "- You are a planning and narrative role; do not attempt to write files or persist artifacts directly.",
+    ],
+    ui: [
+        "- Your primary output is prose. You may reference or sketch HTML snippets inline as examples.",
+        "- Do NOT produce a full HTML document as your response — HTML authoring is the coders role's job.",
+        "- Do not emit large raw JSON blobs as your main output; summarize or reference them instead.",
+    ],
+};
 export function renderAceContext(options) {
     const tier = options.tier ?? "compressed";
     const active = readRuntimeProfileState();
@@ -248,13 +305,15 @@ export function renderAceContext(options) {
         "- Stop if you are about to claim tested, verified, or passed without evidence.",
         "- If ACE state is thin or contradictory, call recall_context or validate_framework before improvising.",
         "- For obviously multi-step work, prefer run_orchestrator over a single free-form answer.",
+        "- When you mutate workspace, use the smallest safe mutation lane: structural edit for existing code, write_workspace_file for new/generated artifacts; never assert file creation in prose alone.",
         "- Do not declare completion while approval, retry, or blocker state remains active.",
+        ...(ROLE_OUTPUT_SHAPE_GUARDRAILS[options.role.trim().toLowerCase()] ?? []),
         "",
         "## Output Contract",
         'Respond in JSON only with one of these shapes:',
         '- `{"status":"tool","thinking":"...","tool_calls":[{"tool":"name","input":{}}]}`',
         '- `{"status":"message","thinking":"...","message":"..."}`',
-        '- `{"status":"complete","thinking":"...","summary":"..."}`',
+        '- `{"status":"complete","thinking":"...","summary":"...","evidence_refs":["agent-state/..."]}`',
         '- `{"status":"need_input","thinking":"...","message":"..."}`',
     ].join("\n");
     return {

package/dist/ace-internal-tools.d.ts

@@ -4,5 +4,7 @@ export interface AceInternalToolCatalogEntry {
     input_keys: string[];
 }
 export declare function listAceInternalToolCatalog(): AceInternalToolCatalogEntry[];
-export declare function executeAceInternalTool(name: string, input: Record<string, unknown> | undefined, sessionId?: string): Promise<any>;
+export declare function executeAceInternalTool(name: string, input: Record<string, unknown> | undefined, sessionId?: string, options?: {
+    workspace_path?: string;
+}): Promise<any>;
 //# sourceMappingURL=ace-internal-tools.d.ts.map

package/dist/ace-internal-tools.js

@@ -42,7 +42,7 @@ export function listAceInternalToolCatalog() {
     }))
         .sort((left, right) => left.name.localeCompare(right.name));
 }
-export async function executeAceInternalTool(name, input, sessionId) {
+export async function executeAceInternalTool(name, input, sessionId, options = {}) {
     const tool = getRegistry()[name];
     if (!tool || !tool.enabled) {
         return {
@@ -50,8 +50,16 @@ export async function executeAceInternalTool(name, input, sessionId) {
             isError: true,
         };
     }
+    const inputWithContext = options.workspace_path && name === "write_workspace_file"
+        ? {
+            ...(input ?? {}),
+            workspace_path: typeof input?.workspace_path === "string" && input.workspace_path.trim()
+                ? input.workspace_path
+                : options.workspace_path,
+        }
+        : input;
     const parsedInput = tool.inputSchema
-        ? tool.inputSchema.safeParse(input ?? {})
+        ? tool.inputSchema.safeParse(inputWithContext ?? {})
         : { success: true, data: undefined };
     if (!parsedInput.success) {
         const errorText = parsedInput.error.issues

package/dist/agent-runtime/role-adapters.d.ts

@@ -21,9 +21,26 @@ export interface AdapterDecision {
     domain: AdapterDomain;
     confidence: number;
     confidenceLevel: "low" | "medium" | "high";
+    preflight?: AcePreflightPacket;
+}
+export interface AcePreflightPacket {
+    required: boolean;
+    status: "passed" | "attention_required" | "blocked";
+    summary: string;
+    evidence_refs: string[];
+    model_visible_tools: ToolIntent[];
 }
 export declare function inferDomain(input: string): AdapterDomain;
 export declare function parseManualHandoffCommand(input: string): HandoffIntent | undefined;
 export declare function parseManualToolCommand(input: string): ToolIntent | undefined;
-export declare function planRoleExecution(roleValue: string, input: string): AdapterDecision;
+export declare function buildAcePreflightPacket(input: {
+    role: string;
+    model_class?: "frontier" | "mid" | "small_local";
+    text: string;
+    domain: AdapterDomain;
+    preflight_required: boolean;
+}): AcePreflightPacket;
+export declare function planRoleExecution(roleValue: string, input: string, options?: {
+    model_class?: "frontier" | "mid" | "small_local";
+}): AdapterDecision;
 //# sourceMappingURL=role-adapters.d.ts.map

package/dist/agent-runtime/role-adapters.js

@@ -273,7 +273,31 @@ function buildCreateHandoffIntent(fromRole, toRole, input) {
         },
     };
 }
-export function planRoleExecution(roleValue, input) {
+export function buildAcePreflightPacket(input) {
+    const routeIntent = { tool: "route_task", args: { description: input.text, domain: input.domain } };
+    const smallLocalOrchestrator = input.role === "orchestrator" && input.model_class === "small_local";
+    return {
+        required: input.preflight_required,
+        status: input.preflight_required ? "attention_required" : "passed",
+        summary: smallLocalOrchestrator
+            ? "ACE-owned preflight covers recall_context, validate_framework, and get_framework_status before model dispatch."
+            : "Adapter preflight remains model-visible for this caller.",
+        evidence_refs: [
+            "agent-state/TASK.md",
+            "agent-state/STATUS.md",
+            "agent-state/QUALITY_GATES.md",
+        ],
+        model_visible_tools: smallLocalOrchestrator
+            ? [routeIntent]
+            : [
+                { tool: "recall_context", args: {} },
+                { tool: "validate_framework", args: {} },
+                { tool: "get_framework_status", args: {} },
+                routeIntent,
+            ],
+    };
+}
+export function planRoleExecution(roleValue, input, options = {}) {
     const normalizedRole = canonicalizeRole(roleValue);
     const text = input.toLowerCase();
     const domainScore = scoreDomain(input);
@@ -316,10 +340,17 @@ export function planRoleExecution(roleValue, input) {
                 domainScore.confidenceLevel === "low" ||
                 contradictoryStateRequested ||
                 aceStateRequested;
-            toolCalls.push({ tool: "recall_context", args: {} });
-            toolCalls.push({ tool: "validate_framework", args: {} });
-            toolCalls.push({ tool: "get_framework_status", args: {} });
-            toolCalls.push({ tool: "route_task", args: { description: input, domain } });
+            const preflight = buildAcePreflightPacket({
+                role: normalizedRole,
+                model_class: options.model_class,
+                text: input,
+                domain,
+                preflight_required: preflightRequired,
+            });
+            toolCalls.push(...preflight.model_visible_tools);
+            if (options.model_class === "small_local") {
+                notes.push(preflight.summary);
+            }
             if (preflightRequired) {
                 toolCalls.push({ tool: "execute_gates", args: {} });
                 notes.push("Orchestrator preflight required before dispatch.");
@@ -568,6 +599,19 @@ export function planRoleExecution(roleValue, input) {
         domain,
         confidence: domainScore.confidence,
         confidenceLevel: domainScore.confidenceLevel,
+        preflight: normalizedRole === "orchestrator"
+            ? buildAcePreflightPacket({
+                role: normalizedRole,
+                model_class: options.model_class,
+                text: input,
+                domain,
+                preflight_required: dispatchRequested ||
+                    domainScore.ambiguous ||
+                    domainScore.confidenceLevel === "low" ||
+                    contradictoryStateRequested ||
+                    aceStateRequested,
+            })
+            : undefined,
     };
 }
 //# sourceMappingURL=role-adapters.js.map

package/dist/astgrep-index.d.ts

@@ -1,3 +1,20 @@
+interface AstGrepMatch {
+    file?: string;
+    text?: string;
+    range?: {
+        start?: {
+            line?: number;
+            column?: number;
+        };
+        end?: {
+            line?: number;
+            column?: number;
+        };
+    };
+    metaVariables?: Record<string, unknown>;
+    kind?: string;
+    nodeKind?: string;
+}
 export interface AstgrepMatch {
     file: string;
     line: number;
@@ -5,7 +22,36 @@ export interface AstgrepMatch {
     text: string;
     context_lines?: string[];
 }
+export interface AstgrepLocateInput {
+    pattern: string;
+    lang: string;
+    scope?: string;
+    symbol_hint?: string;
+    max_results?: number;
+}
+export interface AstgrepLocatedMatch {
+    match_id: string;
+    file: string;
+    range: NonNullable<AstGrepMatch["range"]>;
+    text_preview: string;
+    matched_text: string;
+    captures?: Record<string, string>;
+    node_kind?: string;
+    file_hash: string;
+}
+export interface AstgrepLocateResult {
+    ok: boolean;
+    pattern: string;
+    lang: string;
+    scope: string;
+    symbol_hint?: string;
+    astgrep_command: string | null;
+    total_matches: number;
+    matches: AstgrepLocatedMatch[];
+    error?: string;
+}
 export declare function runAstgrepQuery(pattern: string, lang: string, roots: string[], _contextLines?: number): AstgrepMatch[];
+export declare function locateAstgrepMatches(input: AstgrepLocateInput): AstgrepLocateResult;
 export interface RefreshAstgrepIndexInput {
     scope?: string;
     append_evidence?: boolean;
@@ -28,5 +74,7 @@ export interface RefreshAstgrepIndexResult {
         todo_signals: number;
     };
 }
+export declare function detectAstgrepCommand(): string | null;
 export declare function refreshAstgrepIndex(input?: RefreshAstgrepIndexInput): Promise<RefreshAstgrepIndexResult>;
+export {};
 //# sourceMappingURL=astgrep-index.d.ts.map