@voybio/ace-swarm 0.2.4 → 2.4.0

package/dist/tools-agent.js

@@ -2,16 +2,17 @@
  * Agent, skill, kernel, and task-pack tool registrations.
  */
 import { z } from "zod";
-import { ALL_AGENTS, COMPOSABLE_AGENTS, SWARM_AGENTS, SWARM_SUBAGENT_MAP, classifyPathSource, getAgentInstructionPath, getAgentManifestPath, getKernelArtifactPath, isSwarmRole, listAvailableSkills, readAgentInstructions, readAgentManifest, readKernelArtifact, readSkillInstructions, readTaskArtifact, resolveWritableTaskPath, safeWrite, } from "./helpers.js";
+import { ALL_AGENTS, COMPOSABLE_AGENTS, SWARM_AGENTS, SWARM_SUBAGENT_MAP, classifyPathSource, getAgentInstructionPath, getAgentManifestPath, getKernelArtifactPath, isSwarmRole, listAvailableSkills, readAgentInstructions, readAgentManifest, readKernelArtifact, readSkillInstructions, readTaskArtifact, resolveWorkspaceRoot, resolveWritableTaskPath, safeWriteAsync, } from "./helpers.js";
 import { loadRuntimeProfile, readRuntimePromptTemplate, readRuntimeProfileState, validateRuntimeProfileContent, } from "./runtime-profile.js";
 import { getUnattendedSession, listUnattendedSessions, startUnattendedSession, stopUnattendedSession, validateRuntimeExecutorSessionRegistryContent, waitForUnattendedSession, } from "./runtime-executor.js";
 import { executeRuntimeTool, listRuntimeToolSpecs, loadRuntimeToolRegistry, validateRuntimeToolRegistryContent, } from "./runtime-tool-specs.js";
-import { createWorkspaceSession, listWorkspaceSessions, removeWorkspaceSession, resolveRuntimeWorkspaceRoot, validateManagedWorkspacePath, } from "./workspace-manager.js";
+import { createWorkspaceSessionAsync, listWorkspaceSessions, removeWorkspaceSession, resolveRuntimeWorkspaceRoot, validateManagedWorkspacePath, } from "./workspace-manager.js";
 import { getTrackerAdapter, listTrackerAdapterKinds, loadTrackerSnapshot, validateTrackerSnapshotContent, } from "./tracker-adapters.js";
 import { refreshTrackerSnapshot } from "./tracker-sync.js";
 import { appendVericifyProcessPost, loadVericifyBridgeSnapshot, loadVericifyProcessPostLog, refreshVericifyBridgeSnapshot, validateVericifyBridgeSnapshotContent, validateVericifyProcessPostLogContent, } from "./vericify-bridge.js";
 import { getRoleTitle, ROLE_ENUM, KERNEL_KEY_ENUM, ROLE_TITLES } from "./shared.js";
 import { createDefaultModelBridgeClients, resolveLocalModelRuntime, runLocalModelTask, } from "./local-model-runtime.js";
+import { withLocalModelRuntimeRepository } from "./store/repositories/local-model-runtime-repository.js";
 import { executeAceInternalTool } from "./ace-internal-tools.js";
 import { ModelBridge } from "./model-bridge.js";
 import { getVericifyContextPacket, getVericifyDelta } from "./vericify-context.js";
@@ -52,6 +53,11 @@ function extractToolTextContent(result) {
         .filter(Boolean)
         .join("\n");
 }
+function didExecuteGatesPass(result) {
+    if (Boolean(result?.isError))
+        return false;
+    return !extractToolTextContent(result).trimStart().startsWith("❌");
+}
 function mapRoleToTaskType(role) {
     switch (role) {
         case "vos":
@@ -71,15 +77,180 @@ function extractHandoffId(text) {
     const lineMatch = text.match(/handoff_id:\s*([A-Z0-9-]+)/i);
     return lineMatch?.[1];
 }
+function stepLabel(index) {
+    return `step-${index + 1}`;
+}
+function isShipBoundaryTask(task) {
+    return /\b(ship|release|promot(?:e|ion)|land|merge)\b/i.test(task);
+}
+function isImplementationRole(role) {
+    return role === "coders" || role === "builder";
+}
 async function buildOrchestratorSteps(task, sessionId) {
     void sessionId;
     return [{ role: "orchestrator", task }];
 }
+function normalizeExplicitPlanSteps(steps, task) {
+    const originalIdByLabel = new Map();
+    const normalized = steps.map((step, index) => {
+        const id = `explicit-${index + 1}`;
+        originalIdByLabel.set(stepLabel(index), id);
+        return {
+            ...step,
+            id,
+            depends_on_ids: [...(step.depends_on ?? [])],
+        };
+    });
+    for (const step of normalized) {
+        step.depends_on_ids = step.depends_on_ids.map((dependency) => originalIdByLabel.get(dependency) ?? dependency);
+    }
+    let insertedResearch = false;
+    for (let index = 0; index < normalized.length; index += 1) {
+        const step = normalized[index];
+        if (step.role !== "spec")
+            continue;
+        const hasResearchBefore = normalized.slice(0, index).some((candidate) => candidate.role === "research");
+        if (hasResearchBefore)
+            continue;
+        const researchId = `auto-research-${index + 1}`;
+        normalized.splice(index, 0, {
+            id: researchId,
+            role: "research",
+            task: `Validate source-backed claims and gather evidence before spec work: ${step.task}`,
+            tool_scope: ["recall_context", "read_workspace_file", "build_continuity_packet"],
+            depends_on_ids: [],
+        });
+        step.depends_on_ids = Array.from(new Set([researchId, ...step.depends_on_ids]));
+        insertedResearch = true;
+        index += 1;
+    }
+    const shipFanoutEnabled = isShipBoundaryTask(task) || normalized.some((step) => isShipBoundaryTask(step.task));
+    if (shipFanoutEnabled) {
+        const hasReviewRole = normalized.some((step) => step.role === "skeptic");
+        const hasSecurityRole = normalized.some((step) => step.role === "security");
+        const hasQaRole = normalized.some((step) => step.role === "qa");
+        const hasReleaseRole = normalized.some((step) => step.role === "release");
+        const lastImplementation = [...normalized].reverse().find((step) => isImplementationRole(step.role)) ?? normalized.at(-1);
+        const implementationDependency = lastImplementation ? [lastImplementation.id] : [];
+        const fanoutStepIds = [];
+        if (!hasReviewRole) {
+            const reviewId = `auto-review-${normalized.length + 1}`;
+            normalized.push({
+                id: reviewId,
+                role: "skeptic",
+                task: `Review ship readiness for: ${task}`,
+                tool_scope: ["execute_gates", "validate_framework"],
+                depends_on_ids: implementationDependency,
+            });
+            fanoutStepIds.push(reviewId);
+        }
+        if (!hasSecurityRole) {
+            const securityId = `auto-security-${normalized.length + 1}`;
+            normalized.push({
+                id: securityId,
+                role: "security",
+                task: `Assess security readiness for: ${task}`,
+                tool_scope: ["execute_gates", "validate_framework"],
+                depends_on_ids: implementationDependency,
+            });
+            fanoutStepIds.push(securityId);
+        }
+        if (!hasQaRole) {
+            const qaId = `auto-qa-${normalized.length + 1}`;
+            normalized.push({
+                id: qaId,
+                role: "qa",
+                task: `Validate ship readiness for: ${task}`,
+                tool_scope: ["run_tests", "execute_gates", "git_diff"],
+                depends_on_ids: implementationDependency,
+            });
+            fanoutStepIds.push(qaId);
+        }
+        if (!hasReleaseRole && fanoutStepIds.length > 0) {
+            normalized.push({
+                id: `auto-release-${normalized.length + 1}`,
+                role: "release",
+                task: `Finalize ship decision for: ${task}`,
+                tool_scope: ["git_status", "execute_gates", "validate_framework"],
+                depends_on_ids: fanoutStepIds,
+            });
+        }
+    }
+    const finalIdByInternal = new Map();
+    normalized.forEach((step, index) => {
+        finalIdByInternal.set(step.id, stepLabel(index));
+    });
+    return {
+        steps: normalized.map((step) => ({
+            role: step.role,
+            task: step.task,
+            depends_on: step.depends_on_ids.length > 0
+                ? step.depends_on_ids.map((dependency) => finalIdByInternal.get(dependency) ?? dependency)
+                : undefined,
+            parallel_group: step.parallel_group,
+            tool_scope: step.tool_scope,
+        })),
+        insertedResearch,
+        shipFanoutEnabled,
+    };
+}
+async function normalizeOrchestratorPlanSteps(task, steps, sessionId) {
+    if (!Array.isArray(steps) || steps.length === 0) {
+        return {
+            planSource: "orchestrator_default_step",
+            normalization: {
+                steps: await buildOrchestratorSteps(task, sessionId),
+                insertedResearch: false,
+                shipFanoutEnabled: false,
+            },
+        };
+    }
+    return {
+        planSource: "explicit_steps",
+        normalization: normalizeExplicitPlanSteps(steps, task),
+    };
+}
+async function persistAcceptanceTraceMap(input) {
+    return safeWriteAsync("agent-state/ACCEPTANCE_TRACE_MAP.json", JSON.stringify({
+        version: 1,
+        generated_at: new Date().toISOString(),
+        plan_id: input.plan.plan_id,
+        task: input.task,
+        plan_source: input.planSource,
+        policies: {
+            inserted_research_before_spec: input.insertedResearch,
+            ship_fanout_enabled: input.shipFanoutEnabled,
+        },
+        steps: input.plan.steps.map((step) => ({
+            step_id: step.step_id,
+            role: step.role,
+            task: step.task,
+            depends_on: step.depends_on ?? [],
+            tool_scope: step.tool_scope ?? [],
+            verification_role: step.role === "coders" || step.role === "builder"
+                ? "qa"
+                : step.role === "spec"
+                    ? "research"
+                    : null,
+        })),
+    }, null, 2));
+}
 function appendUniqueNote(target, note) {
     if (!target.includes(note)) {
         target.push(note);
     }
 }
+function createToolOnlyBridgeResult(step, reason) {
+    return {
+        bridge_id: `tool-only-${step.step_id}-${Date.now()}`,
+        role: step.role,
+        status: "completed",
+        summary: `Tool-only orchestrator completion for ${step.step_id} (${step.role}): ${step.task}. ${reason}`,
+        turns: 0,
+        tool_calls: [],
+        child_results: [],
+    };
+}
 function buildDefaultOrchestratorAmendment(input) {
     if (input.result.status !== "completed" || input.step.role !== "coders") {
         return undefined;
@@ -271,6 +442,45 @@ export function registerAgentTools(server) {
             ],
         };
     });
+    server.tool("get_transition_log", "Read the transition log for a session. Answers 'why stopped?', 'what changed?', and 'what evidence caused it?' from the ACE transition record store.", {
+        session_id: z.string().describe("Session ID to read transitions for"),
+        limit: z.number().int().positive().optional().default(20).describe("Max transitions to return (default: 20)"),
+    }, async ({ session_id, limit }) => {
+        try {
+            const transitions = await withLocalModelRuntimeRepository(resolveWorkspaceRoot(), (repo) => repo.getTransitionLog(session_id, limit ?? 20));
+            return {
+                content: [{ type: "text", text: JSON.stringify(transitions, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error reading transition log: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("get_capability_snapshot", "Read the capability snapshot for a specific turn. Shows which tools were available, their cost class, and any unavailable tools with reasons.", {
+        session_id: z.string().describe("Session ID"),
+        turn_number: z.number().int().positive().describe("Turn number"),
+    }, async ({ session_id, turn_number }) => {
+        try {
+            const snapshot = await withLocalModelRuntimeRepository(resolveWorkspaceRoot(), (repo) => repo.getCapabilitySnapshot(session_id, turn_number));
+            if (!snapshot) {
+                return {
+                    content: [{ type: "text", text: `No capability snapshot found for session ${session_id} turn ${turn_number}` }],
+                };
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(snapshot, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error reading capability snapshot: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
     server.tool("validate_runtime_profile", "Validate ACE runtime profile markdown content or the current ACE_WORKFLOW.md file", {
         content: z
             .string()
@@ -482,7 +692,19 @@ export function registerAgentTools(server) {
             .boolean()
             .optional()
             .describe("If false, keep the managed workspace session after completion"),
-    }, async ({ task, context_json, workspace_name, workspace_path, objective_id, tracker_item_id, max_turns, turn_timeout_ms, auto_cleanup, }) => {
+        emit_to: z
+            .array(z.enum(["tui", "tracker", "handoff", "vericify"]))
+            .optional()
+            .describe("Output emission targets for this session. Defaults to ['tui', 'vericify']."),
+        silent_unless_blocked: z
+            .boolean()
+            .optional()
+            .describe("If true, turns that produce no tool calls are classified as no_op_success and do not emit."),
+        require_approval_before_emit: z
+            .boolean()
+            .optional()
+            .describe("If true, require operator approval before emitting meaningful_completion output."),
+    }, async ({ task, context_json, workspace_name, workspace_path, objective_id, tracker_item_id, max_turns, turn_timeout_ms, auto_cleanup, emit_to, silent_unless_blocked, require_approval_before_emit, }) => {
         const result = await startUnattendedSession({
             task,
             context: parseOptionalJsonObject(context_json),
@@ -493,6 +715,9 @@ export function registerAgentTools(server) {
             max_turns,
             turn_timeout_ms,
             auto_cleanup,
+            emit_to,
+            silent_unless_blocked,
+            require_approval_before_emit,
         });
         return {
             content: [
@@ -687,37 +912,77 @@ export function registerAgentTools(server) {
             .optional()
             .describe("Optional workspace root override; defaults to the active workspace"),
     }, async ({ task, steps, execution_mode, max_turns_per_step, provider, model, base_url, ollama_url, workspace_root }, extra) => {
-        const runtime = resolveLocalModelRuntime({
-            workspaceRoot: workspace_root,
-            provider,
-            model,
-            baseUrl: base_url,
-            ollamaUrl: ollama_url,
-        });
+        let runtime;
+        const runtimeWarnings = [];
+        try {
+            runtime = resolveLocalModelRuntime({
+                workspaceRoot: workspace_root,
+                provider,
+                model,
+                baseUrl: base_url,
+                ollamaUrl: ollama_url,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            appendUniqueNote(runtimeWarnings, `Model bridge runtime unavailable; continuing in tool-only mode. ${message}`);
+        }
+        const effectiveWorkspaceRoot = runtime?.workspaceRoot ??
+            (workspace_root ? resolveRuntimeWorkspaceRoot(workspace_root) : resolveWorkspaceRoot());
         const sessionId = typeof extra?.sessionId === "string" ? extra.sessionId : undefined;
-        const planSource = Array.isArray(steps) && steps.length > 0 ? "explicit_steps" : "orchestrator_default_step";
-        const planSteps = Array.isArray(steps) && steps.length > 0
-            ? steps
-            : await buildOrchestratorSteps(task, sessionId);
+        const { planSource, normalization } = await normalizeOrchestratorPlanSteps(task, steps, sessionId);
         const plan = createTaskPlan({
             task,
-            steps: planSteps,
+            steps: normalization.steps,
             execution_mode: execution_mode ?? "sequential",
         });
-        const bridge = new ModelBridge(createDefaultModelBridgeClients(runtime));
+        const traceArtifactPath = await persistAcceptanceTraceMap({
+            plan,
+            task,
+            planSource,
+            insertedResearch: normalization.insertedResearch,
+            shipFanoutEnabled: normalization.shipFanoutEnabled,
+        });
+        const bridge = runtime
+            ? new ModelBridge(createDefaultModelBridgeClients(runtime))
+            : undefined;
         const fallbackHandoffPrefix = `LOCAL-${plan.plan_id}-`;
         const vericifyWarnings = [];
+        const appendSessionPlanTransition = async (stepId, from, to, reason, reasonCode) => {
+            if (!sessionId)
+                return;
+            await withLocalModelRuntimeRepository(effectiveWorkspaceRoot, async (repo) => {
+                const step = plan.steps.find((candidate) => candidate.step_id === stepId);
+                if (!step)
+                    return;
+                await repo.appendTransitionRecord({
+                    session_id: sessionId,
+                    subject_kind: "plan_step",
+                    subject_id: `${plan.plan_id}/${step.step_id}`,
+                    from,
+                    to,
+                    reason,
+                    reason_code: reasonCode,
+                    evidence_refs: step.tool_scope ?? [],
+                });
+            }).catch(() => undefined);
+        };
         const supervised = await superviseTaskPlan(plan, {
             async spawnStep(step) {
-                return bridge.spawn({
-                    task: step.task,
-                    role: step.role,
-                    workspace: runtime.workspaceRoot,
-                    maxTurns: max_turns_per_step ?? 6,
-                    provider: runtime.provider,
-                    model: runtime.model,
-                    toolScope: step.tool_scope,
-                });
+                if (bridge && runtime) {
+                    return bridge.spawn({
+                        task: step.task,
+                        role: step.role,
+                        workspace: runtime.workspaceRoot,
+                        maxTurns: max_turns_per_step ?? 6,
+                        provider: runtime.provider,
+                        model: runtime.model,
+                        toolScope: step.tool_scope,
+                    });
+                }
+                const reason = runtimeWarnings[0] ??
+                    "No local model provider/runtime was resolved for model bridge execution.";
+                return createToolOnlyBridgeResult(step, reason);
             },
             async createHandoff({ step, plan: activePlan }) {
                 const created = await executeAceInternalTool("create_handoff", {
@@ -747,7 +1012,12 @@ export function registerAgentTools(server) {
                     note,
                 }, sessionId);
             },
-            amendPlan({ plan: activePlan, step, result }) {
+            async amendPlan({ plan: activePlan, step, result }) {
+                await appendSessionPlanTransition(step.step_id, "running", step.status, `Plan step ${step.step_id} ${step.status}: ${result.summary}`, step.status === "done"
+                    ? "step_completed"
+                    : step.status === "blocked"
+                        ? "step_blocked"
+                        : "step_failed");
                 return buildDefaultOrchestratorAmendment({
                     plan: activePlan,
                     step,
@@ -756,13 +1026,13 @@ export function registerAgentTools(server) {
             },
             async getVericifyContext() {
                 return tryVericifyPacket(() => getVericifyContextPacket({
-                    workspaceRoot: runtime.workspaceRoot,
+                    workspaceRoot: effectiveWorkspaceRoot,
                 }), (message) => appendUniqueNote(vericifyWarnings, `Vericify context unavailable for ${plan.plan_id}: ${message}`));
             },
             async getVericifyDelta(since) {
                 return tryVericifyPacket(() => getVericifyDelta({
                     since,
-                    workspaceRoot: runtime.workspaceRoot,
+                    workspaceRoot: effectiveWorkspaceRoot,
                 }), (message) => appendUniqueNote(vericifyWarnings, `Vericify delta unavailable for ${plan.plan_id}: ${message}`));
             },
             async openCircuitBreaker(reason) {
@@ -779,7 +1049,7 @@ export function registerAgentTools(server) {
             async executeGates() {
                 const result = await executeAceInternalTool("execute_gates", {}, sessionId);
                 return {
-                    ok: !Boolean(result?.isError),
+                    ok: didExecuteGatesPass(result),
                     summary: extractToolTextContent(result),
                 };
             },
@@ -794,6 +1064,9 @@ export function registerAgentTools(server) {
                 }, sessionId);
             },
             async emitStatusEvent(event) {
+                if (event.step_id) {
+                    await appendSessionPlanTransition(event.step_id, "planned", "running", `Plan step ${event.step_id} started: ${event.summary}`, "step_started");
+                }
                 await executeAceInternalTool("emit_status_event", {
                     source_module: "capability-ops",
                     event_type: "ORCHESTRATOR_STEP",
@@ -818,11 +1091,23 @@ export function registerAgentTools(server) {
                 {
                     type: "text",
                     text: JSON.stringify({
-                        runtime,
+                        runtime: runtime ?? null,
+                        execution_backend: runtime ? "model_bridge" : "tool_only",
+                        runtime_warnings: runtimeWarnings,
+                        workspace_root: effectiveWorkspaceRoot,
                         plan_source: planSource,
                         planning_note: planSource === "orchestrator_default_step"
                             ? "Auto-planning currently starts with ACE-Orchestrator. Pass explicit steps for multi-step orchestration."
-                            : null,
+                            : normalization.insertedResearch
+                                ? "Research was inserted ahead of spec work to require source-backed evidence before specification."
+                                : normalization.shipFanoutEnabled
+                                    ? "Ship fan-out enforcement added review, security, QA, and release coordination steps."
+                                    : null,
+                        trace_artifact_path: traceArtifactPath,
+                        engskills_imports: {
+                            inserted_research_before_spec: normalization.insertedResearch,
+                            ship_fanout_enabled: normalization.shipFanoutEnabled,
+                        },
                         plan: supervised.plan,
                         step_summaries,
                         handoff_ids: supervised.handoff_ids,
@@ -1122,7 +1407,7 @@ export function registerAgentTools(server) {
             .optional()
             .describe("Optional hook timeout override in milliseconds"),
     }, async ({ workspace_name, workspace_path, source, objective_id, tracker_item_id, root, hooks_timeout_ms, }) => {
-        const result = createWorkspaceSession({
+        const result = await createWorkspaceSessionAsync({
             workspace_name,
             workspace_path,
             source,
@@ -1173,7 +1458,7 @@ export function registerAgentTools(server) {
             .optional()
             .describe("Optional hook timeout override in milliseconds"),
     }, async ({ session_id, workspace_path, root, hooks_timeout_ms }) => {
-        const result = removeWorkspaceSession({
+        const result = await removeWorkspaceSession({
             session_id,
             workspace_path,
             root,
@@ -1509,7 +1794,7 @@ export function registerAgentTools(server) {
             "",
         ].join("\n");
         const existing = readTaskArtifact("lessons");
-        const path = safeWrite(resolveWritableTaskPath("lessons"), `${existing}${entry}`);
+        const path = await safeWriteAsync(resolveWritableTaskPath("lessons"), `${existing}${entry}`);
         return {
             content: [{ type: "text", text: `✅ Lesson recorded in ${path}` }],
         };

package/dist/tools-discovery.js

@@ -25,7 +25,7 @@ export function registerDiscoveryTools(server) {
             .optional()
             .describe("Include rep_astgrep.cxml corpus mining when available (default: true)"),
     }, async ({ scope, append_evidence, emit_event, include_rep_corpus }) => {
-        const result = refreshAstgrepIndex({
+        const result = await refreshAstgrepIndex({
             scope,
             append_evidence,
             emit_event,

package/dist/tools-files.d.ts

@@ -2,5 +2,12 @@
  * File operation tool registrations + new safe-edit and diff tools.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface AstgrepRewriteTargetPlan {
+    ok: boolean;
+    affected_files: string[];
+    target_file?: string;
+    error?: string;
+}
+export declare function planAstgrepRewriteTargets(files: string[]): AstgrepRewriteTargetPlan;
 export declare function registerFileTools(server: McpServer): void;
 //# sourceMappingURL=tools-files.d.ts.map