@voybio/ace-swarm 0.2.5 → 2.4.1

package/assets/scripts/ace-hook-dispatch.mjs

@@ -28,6 +28,9 @@ const ACE_CORE_FILES = [
   "agent-state/SCOPE.md",
   "agent-state/EVIDENCE_LOG.md",
 ];
+const STORE_MAGIC = "ACEPACK1";
+const STORE_HEADER_SIZE = 32;
+const HOOK_CONTEXT_STORE_KEY = "state/runtime/hook_context";
 
 const PROTECTED_PATH_FRAGMENTS = [
   ".github/hooks/",
@@ -114,9 +117,61 @@ function resolveAcePath(workspaceRoot, relativePath) {
   return canonical;
 }
 
+function getWorkspaceStorePath(workspaceRoot) {
+  const canonical = resolve(workspaceRoot, "agent-state", "ace-state.ace");
+  if (existsSync(canonical)) return canonical;
+  return resolve(workspaceRoot, ACE_ROOT, "ace-state.ace");
+}
+
+function readStoreUint64(buffer, offset) {
+  return buffer.readUInt32BE(offset) * 2 ** 32 + buffer.readUInt32BE(offset + 4);
+}
+
+function readStoreBlob(workspaceRoot, key) {
+  const storePath = getWorkspaceStorePath(workspaceRoot);
+  if (!existsSync(storePath)) return undefined;
+  try {
+    const file = readFileSync(storePath);
+    if (file.length < STORE_HEADER_SIZE) return undefined;
+    if (file.subarray(0, 8).toString("utf8") !== STORE_MAGIC) return undefined;
+    const indexOffset = readStoreUint64(file, 16);
+    const indexLength = readStoreUint64(file, 24);
+    const index = JSON.parse(file.subarray(indexOffset, indexOffset + indexLength).toString("utf8"));
+    const entry = index?.[key];
+    if (!entry || typeof entry.offset !== "number" || typeof entry.length !== "number") {
+      return undefined;
+    }
+    const start = entry.offset + 4;
+    const end = start + entry.length;
+    return file.subarray(start, end).toString("utf8");
+  } catch {
+    return undefined;
+  }
+}
+
 function readIfPresent(workspaceRoot, relativePath) {
   const absolute = resolveAcePath(workspaceRoot, relativePath);
-  if (!existsSync(absolute)) return undefined;
+  if (!existsSync(absolute)) {
+    const normalized = String(relativePath).replace(/\\/g, "/").replace(/^\.?\//, "");
+    const logicalPath = normalized.startsWith(`${ACE_ROOT}/`)
+      ? normalized.slice(`${ACE_ROOT}/`.length)
+      : normalized;
+    const rel = logicalPath.startsWith("agent-state/") ? logicalPath.slice("agent-state/".length) : "";
+    const keys = [];
+    if (rel) {
+      keys.push(`state/artifacts/agent-state/${rel}`);
+      keys.push(`knowledge/agent-state/${rel}`);
+      if (rel === "ACE_WORKFLOW.md") {
+        keys.unshift("knowledge/runtime/ACE_WORKFLOW.md");
+        keys.push("knowledge/kernel/ACE_WORKFLOW.md");
+      }
+    }
+    for (const key of keys) {
+      const blob = readStoreBlob(workspaceRoot, key);
+      if (typeof blob === "string") return blob;
+    }
+    return undefined;
+  }
   try {
     return readFileSync(absolute, "utf8");
   } catch {
@@ -203,12 +258,19 @@ function buildRoleToolHint(role) {
 }
 
 /**
- * Try to read the store-materialized hook context snapshot.
+ * Try to read the store-backed hook context snapshot.
  * Returns the parsed snapshot or undefined if not present / unreadable.
- * When present this is the single authoritative source; the dispatcher
- * never needs to open the .ace store directly.
  */
 function tryReadHookContextSnapshot(workspaceRoot) {
+  const storeRaw = readStoreBlob(workspaceRoot, HOOK_CONTEXT_STORE_KEY);
+  if (typeof storeRaw === "string") {
+    try {
+      const parsed = JSON.parse(storeRaw);
+      if (parsed?.schema_version === 1) return parsed;
+    } catch {
+      // Fall through to legacy file compatibility.
+    }
+  }
   const snapshotPath = resolve(workspaceRoot, ACE_ROOT, "ace-hook-context.json");
   if (!existsSync(snapshotPath)) return undefined;
   try {
@@ -222,7 +284,7 @@ function tryReadHookContextSnapshot(workspaceRoot) {
 }
 
 function aceContext(workspaceRoot) {
-  // ── Fast path: store-materialized snapshot ──────────────────────────────
+  // ── Fast path: store-backed snapshot ────────────────────────────────────
   const snapshot = tryReadHookContextSnapshot(workspaceRoot);
   if (snapshot) {
     const taskObjective = snapshot.task?.content
@@ -233,7 +295,9 @@ function aceContext(workspaceRoot) {
     const scopeReminder = scopeLines.length
       ? `ACE scope reminder: ${truncate(scopeLines.slice(0, 4).join(" "), 220)}`
       : undefined;
-    const hasAgentState = existsSync(resolve(workspaceRoot, ACE_ROOT, "agent-state"));
+    const hasAgentState =
+      existsSync(resolve(workspaceRoot, ACE_ROOT, "agent-state")) ||
+      existsSync(resolve(workspaceRoot, "agent-state", "ace-state.ace"));
     const hasSkills = existsSync(resolve(workspaceRoot, ACE_ROOT, "skills")) ||
       existsSync(resolve(workspaceRoot, ".agents", "skills"));
     return {

package/assets/scripts/render-mcp-configs.sh

@@ -12,6 +12,9 @@ CURSOR_DIR="${ACE_ROOT}/.cursor"
 VSCODE_DIR="${ACE_ROOT}/.vscode"
 HOOK_COMMAND="node ./.agents/ACE/scripts/ace/ace-hook-dispatch.mjs"
 HOOK_COMMAND_WINDOWS="node .\\\\.agents\\\\ACE\\\\scripts\\\\ace\\\\ace-hook-dispatch.mjs"
+NODE_BIN_DIR="$(dirname -- "$(command -v node)")"
+CLI_ENTRY="${WORKSPACE_ROOT}/dist/cli.js"
+MCP_LAUNCH="export PATH=\"${NODE_BIN_DIR}:\$PATH\" && if ! command -v node >/dev/null 2>&1; then [ -s \"\$HOME/.zprofile\" ] && . \"\$HOME/.zprofile\"; [ -s \"\$HOME/.zshrc\" ] && . \"\$HOME/.zshrc\"; fi && cd \"${WORKSPACE_ROOT}\" && ACE_WORKSPACE_ROOT=\"${WORKSPACE_ROOT}\" node \"${CLI_ENTRY}\" mcp"
 
 mkdir -p "${MCP_CONFIG_DIR}"
 mkdir -p "${GITHUB_DIR}/hooks"
@@ -25,7 +28,18 @@ cat > "${MCP_CONFIG_DIR}/vscode.mcp.json" <<JSON
     "ace-swarm": {
       "type": "stdio",
       "command": "/bin/zsh",
-      "args": ["-lc", "cd \"${WORKSPACE_ROOT}\" && ACE_WORKSPACE_ROOT=\"${WORKSPACE_ROOT}\" npx -y ace-swarm mcp"]
+      "args": ["-lc", "${MCP_LAUNCH}"]
+    }
+  }
+}
+JSON
+
+cat > "${WORKSPACE_ROOT}/.mcp.json" <<JSON
+{
+  "mcpServers": {
+    "ace-swarm": {
+      "command": "/bin/zsh",
+      "args": ["-lc", "${MCP_LAUNCH}"]
     }
   }
 }
@@ -36,7 +50,7 @@ cat > "${MCP_CONFIG_DIR}/cursor.mcp.json" <<JSON
   "mcpServers": {
     "ace-swarm": {
       "command": "/bin/zsh",
-      "args": ["-lc", "cd \"${WORKSPACE_ROOT}\" && ACE_WORKSPACE_ROOT=\"${WORKSPACE_ROOT}\" npx -y ace-swarm mcp"]
+      "args": ["-lc", "${MCP_LAUNCH}"]
     }
   }
 }
@@ -47,7 +61,7 @@ cat > "${MCP_CONFIG_DIR}/claude_desktop_config.json" <<JSON
   "mcpServers": {
     "ace-swarm": {
       "command": "/bin/zsh",
-      "args": ["-lc", "cd \"${WORKSPACE_ROOT}\" && ACE_WORKSPACE_ROOT=\"${WORKSPACE_ROOT}\" npx -y ace-swarm mcp"]
+      "args": ["-lc", "${MCP_LAUNCH}"]
     }
   }
 }
@@ -58,7 +72,7 @@ cat > "${MCP_CONFIG_DIR}/antigravity.mcp.json" <<JSON
   "mcpServers": {
     "ace-swarm": {
       "command": "/bin/zsh",
-      "args": ["-lc", "cd \"${WORKSPACE_ROOT}\" && ACE_WORKSPACE_ROOT=\"${WORKSPACE_ROOT}\" npx -y ace-swarm mcp"]
+      "args": ["-lc", "${MCP_LAUNCH}"]
     }
   }
 }
@@ -68,7 +82,7 @@ cat > "${MCP_CONFIG_DIR}/codex.config.toml" <<TOML
 # ACE instructions are scaffolded into .agents/ACE/AGENTS.md during bootstrap.
 [mcp_servers.ace-swarm]
 command = "/bin/zsh"
-args = ["-lc", "cd \"${WORKSPACE_ROOT}\" && ACE_WORKSPACE_ROOT=\"${WORKSPACE_ROOT}\" npx -y ace-swarm mcp"]
+args = ["-lc", "${MCP_LAUNCH}"]
 TOML
 
 cat > "${ACE_ROOT}/CLAUDE.md" <<MD

package/dist/ace-context.js

@@ -1,6 +1,6 @@
 import { buildAceContinuityPacket, buildAceRecallContext, formatAceContinuityPacketMarkdown, formatAceRecallMarkdown, normalizeAutonomyPolicy, normalizeContinuityPolicy, } from "./ace-autonomy.js";
 import { listAceInternalToolCatalog, } from "./ace-internal-tools.js";
-import { ALL_AGENTS, readAgentInstructions } from "./helpers.js";
+import { ALL_AGENTS, listAvailableSkills, readAgentInstructions } from "./helpers.js";
 import { readRuntimeProfileState, renderRuntimePrompt } from "./runtime-profile.js";
 const ROLE_TOOL_DEFAULTS = {
     orchestrator: [
@@ -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");
@@ -156,9 +176,27 @@ function buildPlanningCatalog(role, task, tier) {
         .slice(0, limit)
         .map((entry) => entry.tool);
 }
+function inferRelevantSkills(task) {
+    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/ },
+        { name: "schema-forge", pattern: /\b(schema|contract|interface)\b/ },
+        { name: "release-sentry", pattern: /\b(ship|release|promotion|rollback)\b/ },
+        { name: "risk-quant", pattern: /\b(risk|blocker|severity)\b/ },
+        { name: "eval-harness", pattern: /\b(eval|regression|verify|validation)\b/ },
+        { name: "incident-commander", pattern: /\b(incident|outage|blocker storm)\b/ },
+        { name: "problem-triage", pattern: /\b(triage|classify|scope)\b/ },
+    ];
+    const available = new Set(listAvailableSkills().map((skill) => skill.name));
+    return skillSignals
+        .filter((signal) => signal.pattern.test(lowered) && available.has(signal.name))
+        .map((signal) => signal.name);
+}
 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);
@@ -185,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();
@@ -211,6 +285,7 @@ export function renderAceContext(options) {
     const roleInstructions = resolveRoleInstructions(options.role);
     const toolCatalog = renderToolCatalogMarkdown(tools, tier);
     const stateDigest = recall.task_contract.summary;
+    const relevantSkills = inferRelevantSkills(options.task);
     const systemPrompt = [
         runtimePrompt,
         "",
@@ -223,17 +298,22 @@ export function renderAceContext(options) {
         "## Tool Scope",
         toolCatalog || "- No ACE tools available.",
         "",
+        "## Relevant Skills",
+        relevantSkills.length > 0 ? `- ${relevantSkills.join(", ")}` : "- No task-specific skill hint matched.",
+        "",
         "## Compact Guardrails",
         "- 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/ace-server-instructions.js

@@ -229,10 +229,10 @@ export function buildHostInstructionText(host, workspaceRoot) {
         "3. Prefer ACE prompts/resources (`ace-orchestrator`, `get_task_pack`, `get_skill_instructions`) over relying on this file.",
         "",
         "Ground truth:",
-        "- `agent-state/*` is the logical state surface; the resolver reads it from top-level, nested, or store-backed layouts.",
-        "- `.agents/ACE/ace-state.ace` remains the canonical store-backed projection when that layout is used.",
+        "- `agent-state/*` is the visible runtime state surface for this workspace.",
+        "- `agent-state/ace-state.ace` is the canonical store path; legacy nested store layouts are compatibility fallback only.",
         "- `.agents/ACE/tasks/todo.md` is the human-facing todo surface.",
-        "- `.agents/ACE/ace-hook-context.json` is the compact hook snapshot.",
+        "- Hook context is store-backed in `agent-state/ace-state.ace` and consumed without extra workspace projections.",
         "",
         `Workspace digest hint: ${buildAceDigest(workspaceRoot)}.`,
     ].join("\n");

package/dist/ace-state-resolver.js

@@ -95,9 +95,11 @@ export function resolveAceStateLayout(workspaceRoot) {
         scopePath: resolveAceLogicalPath(workspaceRoot, "agent-state/SCOPE.md"),
         evidencePath: resolveAceLogicalPath(workspaceRoot, "agent-state/EVIDENCE_LOG.md"),
         storePath: storePresent ? storePath : undefined,
-        hookSnapshotPath: existsSync(nestedAcePath(workspaceRoot, "ace-hook-context.json"))
-            ? nestedAcePath(workspaceRoot, "ace-hook-context.json")
-            : undefined,
+        hookSnapshotPath: readStoreBlobSync(workspaceRoot, "state/runtime/hook_context") != null
+            ? toVirtualStorePath(storePath, "state/runtime/hook_context")
+            : existsSync(nestedAcePath(workspaceRoot, "ace-hook-context.json"))
+                ? nestedAcePath(workspaceRoot, "ace-hook-context.json")
+                : undefined,
         isAcePresent: physicalMode !== "missing" ||
             CRITICAL_LOGICAL_PATHS.some((relativePath) => typeof readAceLogicalFile(workspaceRoot, relativePath) === "string"),
         missingCriticalArtifacts,

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,57 @@
+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;
+    column: number;
+    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;
@@ -20,5 +74,7 @@ export interface RefreshAstgrepIndexResult {
         todo_signals: number;
     };
 }
-export declare function refreshAstgrepIndex(input?: RefreshAstgrepIndexInput): RefreshAstgrepIndexResult;
+export declare function detectAstgrepCommand(): string | null;
+export declare function refreshAstgrepIndex(input?: RefreshAstgrepIndexInput): Promise<RefreshAstgrepIndexResult>;
+export {};
 //# sourceMappingURL=astgrep-index.d.ts.map