@voybio/ace-swarm 2.4.3 → 2.4.6

package/dist/todo-state.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { ACE_TASKS_ROOT_REL, resolveWorkspaceRoot, safeRead, safeWrite, wsPath } from "./helpers.js";
+import { ACE_TASKS_ROOT_REL, resolveWorkspaceRoot, resolveWritableTaskPath, safeRead, safeWrite, safeWriteAsync, withFileLock, wsPath, } from "./helpers.js";
 import { openStore } from "./store/ace-packed-store.js";
 import { ProjectionManager } from "./store/materializers/projection-manager.js";
 import { TodoRepository } from "./store/repositories/todo-repository.js";
@@ -385,6 +385,49 @@ function setTodoCheckbox(todoRaw, line, checked) {
     lines[line - 1] = target.replace(/^- \[( |x|X)\]/, `- [${checked ? "x" : " "}]`);
     return lines.join("\n");
 }
+function insertTodoItem(todoRaw, section, title, id, dependsOn) {
+    const metaParts = [`id=${id}`];
+    if (dependsOn.length > 0)
+        metaParts.push(`depends_on=${dependsOn.join(",")}`);
+    const newLine = `- [ ] ${title} <!-- ace:${metaParts.join("; ")} -->`;
+    const lines = todoRaw.length > 0 ? todoRaw.split(/\r?\n/) : [];
+    let sectionStart = -1;
+    let sectionEnd = lines.length;
+    for (let i = 0; i < lines.length; i++) {
+        const header = lines[i]?.match(/^##\s+(.+)$/);
+        if (!header?.[1])
+            continue;
+        if (header[1].trim().toLowerCase() === section.toLowerCase()) {
+            sectionStart = i;
+            let j = i + 1;
+            while (j < lines.length && !/^##\s+/.test(lines[j] ?? ""))
+                j++;
+            sectionEnd = j;
+            break;
+        }
+    }
+    if (sectionStart === -1) {
+        const trimmed = todoRaw.replace(/\s+$/, "");
+        const prefix = trimmed.length > 0 ? `${trimmed}\n\n` : "";
+        return `${prefix}## ${section}\n${newLine}\n`;
+    }
+    let insertAt = sectionEnd;
+    while (insertAt > sectionStart + 1 && (lines[insertAt - 1] ?? "").trim() === "")
+        insertAt--;
+    lines.splice(insertAt, 0, newLine);
+    return lines.join("\n");
+}
+function uniqueTodoId(base, existingIds) {
+    if (!existingIds.has(base))
+        return base;
+    let n = 2;
+    let candidate = `${base}-${n}`;
+    while (existingIds.has(candidate)) {
+        n += 1;
+        candidate = `${base}-${n}`;
+    }
+    return candidate;
+}
 function getTodoPath() {
     return wsPath(TODO_MARKDOWN_REL);
 }
@@ -401,7 +444,10 @@ export function syncTodoState(todoContent) {
     const path = writeState(state);
     return { state, path };
 }
-export async function syncTodoStateSafe(todoContent) {
+// Lock-free core: callers that already hold the TODO_MARKDOWN_REL lock (e.g.
+// appendTodoItemSafe) must call this directly instead of syncTodoStateSafe,
+// since withFileLock is not reentrant and re-acquiring the same key deadlocks.
+async function syncTodoStateLocked(todoContent) {
     const root = workspaceRoot();
     if (storeExistsSync(root)) {
         const todoRaw = typeof todoContent === "string" ? todoContent : safeRead(TODO_MARKDOWN_REL);
@@ -418,6 +464,9 @@ export async function syncTodoStateSafe(todoContent) {
     await waitForTodoStoreMirror();
     return result;
 }
+export async function syncTodoStateSafe(todoContent) {
+    return withFileLock(TODO_MARKDOWN_REL, () => syncTodoStateLocked(todoContent));
+}
 export function readTodoState() {
     if (storeExistsSync(workspaceRoot())) {
         return readPersistedState();
@@ -495,73 +544,121 @@ export function transitionTodoNode(nodeId, targetStatus) {
     };
 }
 export async function transitionTodoNodeSafe(nodeId, targetStatus) {
-    const root = workspaceRoot();
-    if (storeExistsSync(root)) {
-        const todoRaw = safeRead(TODO_MARKDOWN_REL);
-        if (isReadError(todoRaw)) {
-            return {
-                ok: false,
-                path: getTodoStatePath(),
-                todo_path: getTodoPath(),
-                error: `${TODO_MARKDOWN_REL} not found; cannot apply transition.`,
-            };
-        }
-        const synced = syncStateWithTodo(todoRaw, readPersistedState());
-        const node = synced.nodes[nodeId];
-        if (!node) {
-            return {
-                ok: false,
-                path: getTodoStatePath(),
-                todo_path: getTodoPath(),
-                error: `Unknown node_id: ${nodeId}`,
-            };
-        }
-        const from = node.status;
-        if (from !== targetStatus) {
-            const allowed = TRANSITIONS[from];
-            if (!allowed.includes(targetStatus)) {
+    return withFileLock(TODO_MARKDOWN_REL, async () => {
+        const root = workspaceRoot();
+        if (storeExistsSync(root)) {
+            const todoRaw = safeRead(TODO_MARKDOWN_REL);
+            if (isReadError(todoRaw)) {
                 return {
                     ok: false,
                     path: getTodoStatePath(),
                     todo_path: getTodoPath(),
-                    node_id: nodeId,
-                    from,
-                    to: targetStatus,
-                    allowed,
-                    error: `Invalid transition ${from} -> ${targetStatus}`,
+                    error: `${TODO_MARKDOWN_REL} not found; cannot apply transition.`,
                 };
             }
-        }
-        if (targetStatus === "in_progress" ||
-            targetStatus === "gated" ||
-            targetStatus === "done") {
-            const unresolved = node.depends_on.filter((depId) => synced.nodes[depId]?.status !== "done");
-            if (unresolved.length > 0) {
+            const synced = syncStateWithTodo(todoRaw, readPersistedState());
+            const node = synced.nodes[nodeId];
+            if (!node) {
                 return {
                     ok: false,
                     path: getTodoStatePath(),
                     todo_path: getTodoPath(),
-                    node_id: nodeId,
-                    from,
-                    to: targetStatus,
-                    unresolved_dependencies: unresolved,
-                    error: `Dependencies not satisfied for ${nodeId}`,
+                    error: `Unknown node_id: ${nodeId}`,
                 };
             }
+            const from = node.status;
+            if (from !== targetStatus) {
+                const allowed = TRANSITIONS[from];
+                if (!allowed.includes(targetStatus)) {
+                    return {
+                        ok: false,
+                        path: getTodoStatePath(),
+                        todo_path: getTodoPath(),
+                        node_id: nodeId,
+                        from,
+                        to: targetStatus,
+                        allowed,
+                        error: `Invalid transition ${from} -> ${targetStatus}`,
+                    };
+                }
+            }
+            if (targetStatus === "in_progress" ||
+                targetStatus === "gated" ||
+                targetStatus === "done") {
+                const unresolved = node.depends_on.filter((depId) => synced.nodes[depId]?.status !== "done");
+                if (unresolved.length > 0) {
+                    return {
+                        ok: false,
+                        path: getTodoStatePath(),
+                        todo_path: getTodoPath(),
+                        node_id: nodeId,
+                        from,
+                        to: targetStatus,
+                        unresolved_dependencies: unresolved,
+                        error: `Dependencies not satisfied for ${nodeId}`,
+                    };
+                }
+            }
+            node.status = targetStatus;
+            const statePath = await writeStateStoreBacked(root, synced);
+            return {
+                ok: true,
+                path: statePath,
+                todo_path: getTodoPath(),
+                node_id: nodeId,
+                from,
+                to: targetStatus,
+            };
         }
-        node.status = targetStatus;
-        const statePath = await writeStateStoreBacked(root, synced);
+        const result = transitionTodoNode(nodeId, targetStatus);
+        await waitForTodoStoreMirror();
+        return result;
+    });
+}
+/**
+ * Atomically append a new TODO item under a section, without requiring the
+ * caller to read the whole board and resubmit it via update_todo(new_content).
+ * That read-modify-write dance is what let concurrent agents silently clobber
+ * each other's appended items: the read and write are separate MCP calls, so
+ * a lock around the write alone cannot close the race. Here the read, insert,
+ * and write all happen inside one TODO_MARKDOWN_REL lock acquisition.
+ */
+export async function appendTodoItemSafe(title, options) {
+    const trimmedTitle = title.trim();
+    if (!trimmedTitle) {
         return {
-            ok: true,
-            path: statePath,
+            ok: false,
+            path: getTodoStatePath(),
             todo_path: getTodoPath(),
-            node_id: nodeId,
-            from,
-            to: targetStatus,
+            error: "Todo item title must not be empty.",
         };
     }
-    const result = transitionTodoNode(nodeId, targetStatus);
-    await waitForTodoStoreMirror();
-    return result;
+    return withFileLock(TODO_MARKDOWN_REL, async () => {
+        const existingRaw = safeRead(TODO_MARKDOWN_REL);
+        const baseRaw = isReadError(existingRaw) ? "# Tasks\n" : existingRaw;
+        const section = options?.section?.trim() || "Active Work";
+        const dependsOn = (options?.depends_on ?? []).map((dep) => dep.trim()).filter(Boolean);
+        const existingIds = new Set(parseTodoMarkdown(baseRaw).map((entry) => entry.id));
+        const requestedId = options?.id?.trim();
+        if (requestedId && existingIds.has(requestedId)) {
+            return {
+                ok: false,
+                path: getTodoStatePath(),
+                todo_path: getTodoPath(),
+                error: `Todo id already exists: ${requestedId}`,
+            };
+        }
+        const id = requestedId || uniqueTodoId(`todo-${slugify(trimmedTitle)}`, existingIds);
+        const updatedRaw = insertTodoItem(baseRaw, section, trimmedTitle, id, dependsOn);
+        const synced = await syncTodoStateLocked(updatedRaw);
+        const mdPath = await safeWriteAsync(resolveWritableTaskPath("todo"), updatedRaw);
+        return {
+            ok: true,
+            path: synced.path,
+            todo_path: mdPath,
+            node_id: id,
+            section,
+        };
+    });
 }
 //# sourceMappingURL=todo-state.js.map

package/dist/tools-agent.js

@@ -2,9 +2,10 @@
  * 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, resolveWorkspaceRoot, resolveWritableTaskPath, safeWriteAsync, } 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, } from "./helpers.js";
 import { loadRuntimeProfile, readRuntimePromptTemplate, readRuntimeProfileState, validateRuntimeProfileContent, } from "./runtime-profile.js";
 import { getUnattendedSession, listUnattendedSessions, startUnattendedSession, stopUnattendedSession, validateRuntimeExecutorSessionRegistryContent, waitForUnattendedSession, } from "./runtime-executor.js";
+import { materializePlaybookMarkdown, PlaybookRepository, renderPlaybookMarkdown, } from "./store/repositories/playbook-repository.js";
 import { executeRuntimeTool, listRuntimeToolSpecs, loadRuntimeToolRegistry, validateRuntimeToolRegistryContent, } from "./runtime-tool-specs.js";
 import { createWorkspaceSessionAsync, listWorkspaceSessions, removeWorkspaceSession, resolveRuntimeWorkspaceRoot, validateManagedWorkspacePath, } from "./workspace-manager.js";
 import { getTrackerAdapter, listTrackerAdapterKinds, loadTrackerSnapshot, validateTrackerSnapshotContent, } from "./tracker-adapters.js";
@@ -350,8 +351,9 @@ 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}`,
+        status: "blocked",
+        reason_code: "no_model_runtime",
+        summary: `Step blocked — no model runtime available for ${step.step_id} (${step.role}): ${step.task}. ${reason} Run \`ace connect\` or \`ace doctor --scan\`, or pass provider/model to resolve.`,
         turns: 0,
         tool_calls: [],
         child_results: [],
@@ -1369,7 +1371,11 @@ export function registerAgentTools(server) {
             .string()
             .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) => {
+        mode: z
+            .enum(["execute", "plan_only"])
+            .optional()
+            .describe("'plan_only' compiles and validates the plan without executing any steps; 'execute' is the default"),
+    }, async ({ task, steps, execution_mode, max_turns_per_step, provider, model, base_url, ollama_url, workspace_root, mode }, extra) => {
         let runtime;
         const runtimeWarnings = [];
         try {
@@ -1406,6 +1412,32 @@ export function registerAgentTools(server) {
         const bridge = runtime
             ? new ModelBridge(createDefaultModelBridgeClients(runtime))
             : undefined;
+        // plan_only mode: return the compiled plan without executing anything
+        if (mode === "plan_only" || (!runtime && runtimeWarnings.length > 0)) {
+            const planOnly = mode === "plan_only";
+            const reasonCode = planOnly ? "plan_only_requested" : "no_model_runtime";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: planOnly,
+                            reason_code: reasonCode,
+                            execution_backend: "none",
+                            mode: planOnly ? "plan_only" : "execute",
+                            plan,
+                            runtime: runtime ?? null,
+                            runtime_warnings: runtimeWarnings,
+                            remediation: !runtime
+                                ? "Run `ace connect` or `ace doctor --scan`, or pass provider/model. Use mode:\"plan_only\" explicitly to compile a plan without a runtime."
+                                : undefined,
+                            acceptance_trace_map: traceArtifactPath,
+                            plan_source: planSource,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
         const fallbackHandoffPrefix = `LOCAL-${plan.plan_id}-`;
         const vericifyWarnings = [];
         const appendSessionPlanTransition = async (stepId, from, to, reason, reasonCode) => {
@@ -1426,6 +1458,22 @@ export function registerAgentTools(server) {
                     evidence_refs: step.tool_scope ?? [],
                 });
             }).catch(() => undefined);
+            // WS-C item 5: emit a PLAN_UPDATE payload on the existing status-event pipe so
+            // consumers can follow "exactly one item in_progress" without a new transport.
+            const inProgressStep = plan.steps.find((candidate) => candidate.status === "running");
+            await executeAceInternalTool("emit_status_event", {
+                source_module: "capability-ops",
+                event_type: "PLAN_UPDATE",
+                status: to === "done" ? "done" : to === "blocked" || to === "failed" ? "blocked" : "in_progress",
+                summary: `Plan ${plan.plan_id} step ${stepId}: ${from} -> ${to}`,
+                payload_json: JSON.stringify({
+                    plan_id: plan.plan_id,
+                    step_id: stepId,
+                    from,
+                    to,
+                    in_progress_step_id: inProgressStep?.step_id ?? null,
+                }),
+            }, sessionId).catch(() => undefined);
         };
         const supervised = await superviseTaskPlan(plan, {
             async spawnStep(step) {
@@ -1439,6 +1487,8 @@ export function registerAgentTools(server) {
                         provider: runtime.provider,
                         model: runtime.model,
                         toolScope: step.tool_scope,
+                        expectedArtifacts: step.expected_artifacts,
+                        requiredEvidenceRefs: step.required_evidence_refs,
                     });
                 }
                 const reason = runtimeWarnings[0] ??
@@ -2287,31 +2337,45 @@ export function registerAgentTools(server) {
         };
     });
     // ── Lessons ───────────────────────────────────────────────────────
-    server.tool("get_lessons", "Read all accumulated lessons and guardrails", {}, async () => ({
-        content: [{ type: "text", text: readTaskArtifact("lessons") }],
-    }));
+    server.tool("get_lessons", "Read all accumulated playbook lessons and guardrails", {}, async () => {
+        const root = resolveWorkspaceRoot();
+        const repo = new PlaybookRepository(root);
+        const path = materializePlaybookMarkdown(root);
+        return {
+            content: [{ type: "text", text: `${renderPlaybookMarkdown(repo)}\nProjection: ${path}` }],
+        };
+    });
     server.tool("add_lesson", "Record a new lesson/guardrail after a correction or failure", {
         context: z.string().describe("What happened"),
         failure_pattern: z.string().describe("What went wrong"),
         guardrail: z.string().describe("Rule to prevent recurrence"),
         verification_check: z.string().describe("How to verify compliance"),
     }, async ({ context, failure_pattern, guardrail, verification_check }) => {
-        const date = new Date().toISOString().slice(0, 10);
-        const entry = [
-            "",
-            `## Lesson — ${date}`,
-            "",
-            `- **Date:** ${date}`,
-            `- **Context:** ${context}`,
-            `- **Failure Pattern:** ${failure_pattern}`,
-            `- **Guardrail:** ${guardrail}`,
-            `- **Verification Check:** ${verification_check}`,
-            "",
-        ].join("\n");
-        const existing = readTaskArtifact("lessons");
-        const path = await safeWriteAsync(resolveWritableTaskPath("lessons"), `${existing}${entry}`);
+        const knownReasonCodes = [
+            "false_completion_no_evidence",
+            "forward_pacing_incomplete",
+            "bridge_tool_doom_loop",
+            "bridge_text_doom_loop",
+            "context_overflow",
+            "tool_timeout",
+            "role_contract_violation",
+        ];
+        const scope = {};
+        const lowered = failure_pattern.toLowerCase();
+        const reason = knownReasonCodes.find((code) => lowered.includes(code));
+        if (reason)
+            scope.reason_code = reason;
+        const root = resolveWorkspaceRoot();
+        const bullet = new PlaybookRepository(root).createBullet({
+            section: "failure_modes",
+            scope,
+            content: `${guardrail} Verify: ${verification_check}`,
+            evidence_refs: [],
+            provenance: { source: "operator" },
+        });
+        const path = materializePlaybookMarkdown(root);
         return {
-            content: [{ type: "text", text: `✅ Lesson recorded in ${path}` }],
+            content: [{ type: "text", text: `✅ Lesson recorded as ${bullet.bullet_id} (${bullet.status}) in ${path}. Context: ${context}` }],
         };
     });
     // ── CLI Work Split ────────────────────────────────────────────────

package/dist/tools-discovery.js

@@ -217,7 +217,7 @@ export function registerDiscoveryTools(server) {
             },
         ],
     }));
-    server.tool("mcp_ingestion_probe", "Validate an external MCP server configuration, persist request/response artifacts, and expose bounded declared tool metadata without leaking shell env", {
+    server.tool("mcp_ingestion_probe", "Connect to an external MCP server with a bounded initialize handshake, list tools/resources/templates/prompts, and persist the probe artifacts", {
         name: z.string().min(1).describe("Logical MCP server name"),
         transport: z.enum(["stdio", "http"]).describe("MCP transport class"),
         command: z.string().optional().describe("Command for stdio MCP servers"),
@@ -231,8 +231,9 @@ export function registerDiscoveryTools(server) {
             input_schema: z.unknown().optional(),
         }))
             .optional()
-            .describe("Optional declared tool metadata discovered or provided by the server class"),
-    }, async ({ name, transport, command, args, url, env, declared_tools }) => ({
+            .describe("Deprecated compatibility input; live server catalogs are authoritative"),
+        timeout_ms: z.number().int().min(250).max(60000).optional().describe("Bound for connect and each catalog request (default 10000ms)"),
+    }, async ({ name, transport, command, args, url, env, declared_tools, timeout_ms }) => ({
         content: [
             {
                 type: "text",
@@ -244,6 +245,7 @@ export function registerDiscoveryTools(server) {
                     url,
                     env,
                     declared_tools,
+                    timeout_ms,
                 }), null, 2),
             },
         ],