@voybio/ace-swarm 0.1.0

package/dist/tools-agent.js

@@ -0,0 +1,1542 @@
+/**
+ * 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 { 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 { 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 { executeAceInternalTool } from "./ace-internal-tools.js";
+import { ModelBridge } from "./model-bridge.js";
+import { getVericifyContextPacket, getVericifyDelta } from "./vericify-context.js";
+import { createTaskPlan, superviseTaskPlan, } from "./orchestrator-supervisor.js";
+function parseOptionalJsonObject(raw) {
+    if (!raw)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // fall through
+    }
+    return { raw_json: raw };
+}
+function parseUnknownJson(raw) {
+    if (typeof raw !== "string" || raw.trim().length === 0)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return { raw };
+    }
+}
+function extractToolTextContent(result) {
+    if (!result || typeof result !== "object")
+        return "";
+    const content = Array.isArray(result.content) ? result.content : [];
+    return content
+        .filter((entry) => Boolean(entry) &&
+        typeof entry === "object" &&
+        entry.type === "text")
+        .map((entry) => String(entry.text ?? "").trim())
+        .filter(Boolean)
+        .join("\n");
+}
+function normalizeRoleCandidate(input) {
+    if (!input)
+        return undefined;
+    const normalized = input.trim().toLowerCase().replace(/^ace-/, "").replace(/[^a-z0-9]+/g, "");
+    const candidate = normalized === "coder" ? "coders" : normalized;
+    return ROLE_ENUM.options.includes(candidate)
+        ? candidate
+        : undefined;
+}
+function parseRoleFromRoutingSummary(summary) {
+    const match = summary.match(/\*\*Primary Swarm Agent\(s\):\*\*\s*([^\n]+)/i);
+    if (!match?.[1])
+        return undefined;
+    const firstAgent = match[1]
+        .split(",")
+        .map((entry) => entry.trim())
+        .find(Boolean);
+    return normalizeRoleCandidate(firstAgent);
+}
+function mapRoleToTaskType(role) {
+    switch (role) {
+        case "vos":
+            return "venture";
+        case "ui":
+            return "ux";
+        case "orchestrator":
+            return "mixed";
+        default:
+            return "engineering";
+    }
+}
+function extractHandoffId(text) {
+    const jsonMatch = text.match(/"handoff_id"\s*:\s*"([^"]+)"/);
+    if (jsonMatch?.[1])
+        return jsonMatch[1];
+    const lineMatch = text.match(/handoff_id:\s*([A-Z0-9-]+)/i);
+    return lineMatch?.[1];
+}
+async function buildOrchestratorSteps(task, sessionId) {
+    const routing = await executeAceInternalTool("route_task", { description: task, domain: "unknown" }, sessionId);
+    const routedRole = parseRoleFromRoutingSummary(extractToolTextContent(routing)) ?? "orchestrator";
+    return [{ role: routedRole, task }];
+}
+function appendUniqueNote(target, note) {
+    if (!target.includes(note)) {
+        target.push(note);
+    }
+}
+function buildDefaultOrchestratorAmendment(input) {
+    if (input.result.status !== "completed" || input.step.role !== "coders") {
+        return undefined;
+    }
+    const currentIndex = input.plan.steps.findIndex((step) => step.step_id === input.step.step_id);
+    if (currentIndex < 0) {
+        return undefined;
+    }
+    const downstreamSteps = input.plan.steps.slice(currentIndex + 1);
+    const hasValidationStep = downstreamSteps.some((step) => step.role === "qa" || step.role === "docs");
+    if (hasValidationStep) {
+        return undefined;
+    }
+    return {
+        steps_to_add: [
+            {
+                role: "qa",
+                task: `Validate completed work for ${input.step.step_id}: ${input.step.task}`,
+                depends_on: [input.step.step_id],
+                tool_scope: ["run_tests", "execute_gates", "git_diff"],
+            },
+        ],
+        add_after_step_id: input.step.step_id,
+    };
+}
+async function tryVericifyPacket(factory, onWarning) {
+    try {
+        return await factory();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        onWarning?.(message);
+        return undefined;
+    }
+}
+export function registerAgentTools(server) {
+    // ── Agent Instructions & Manifests ────────────────────────────────
+    server.tool("get_agent_instructions", "Load the full instruction file for a specific ACE agent role", {
+        role: ROLE_ENUM.describe("Which agent role to load"),
+    }, async ({ role }) => {
+        const content = readAgentInstructions(role);
+        const sourcePath = getAgentInstructionPath(role);
+        const source = classifyPathSource(sourcePath);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `# ACE-${role.toUpperCase()} Instructions`,
+                        "",
+                        `Source: ${source}${sourcePath ? ` (${sourcePath})` : ""}`,
+                        "",
+                        content,
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("get_agent_manifest", "Load AGENTS manifest-style instructions for a specific ACE role", {
+        role: ROLE_ENUM.describe("Which agent role to load"),
+    }, async ({ role }) => {
+        const content = readAgentManifest(role);
+        const sourcePath = getAgentManifestPath(role);
+        const source = classifyPathSource(sourcePath);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `# ACE-${role.toUpperCase()} Manifest`,
+                        "",
+                        `Source: ${source}${sourcePath ? ` (${sourcePath})` : ""}`,
+                        "",
+                        content,
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("get_all_agents_summary", "Get an overview of the unified swarm + composable ACE agent system and source files", {}, async () => {
+        const swarmLabel = [...SWARM_AGENTS].map((role) => `ACE-${getRoleTitle(role)}`);
+        const composableLabel = [...COMPOSABLE_AGENTS].map((role) => `ACE-${getRoleTitle(role)}`);
+        const blocks = ALL_AGENTS.map((role) => {
+            const instructionPath = getAgentInstructionPath(role);
+            const manifestPath = getAgentManifestPath(role);
+            const group = isSwarmRole(role) ? "swarm" : "composable";
+            const linkage = isSwarmRole(role)
+                ? `- Composable subagents: ${SWARM_SUBAGENT_MAP[role].join(", ")}`
+                : `- Available to swarm agents: ${[...SWARM_AGENTS].join(", ")}`;
+            return [
+                `## ACE-${getRoleTitle(role)}`,
+                `- Group: ${group}`,
+                `- Instruction source: ${classifyPathSource(instructionPath)}${instructionPath ? ` (${instructionPath})` : ""}`,
+                `- Manifest source: ${classifyPathSource(manifestPath)}${manifestPath ? ` (${manifestPath})` : ""}`,
+                linkage,
+            ].join("\n");
+        });
+        const kernelKeys = ["directive_kernel", "agent_registry"];
+        const kernelLines = kernelKeys.map((key) => {
+            const path = getKernelArtifactPath(key);
+            return `- ${key}: ${classifyPathSource(path)}${path ? ` (${path})` : ""}`;
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "# ACE Unified Agent Summary",
+                        "",
+                        "## Agent Groups",
+                        `- Swarm agents: ${swarmLabel.join(", ")}`,
+                        `- Composable agents: ${composableLabel.join(", ")}`,
+                        "",
+                        ...blocks,
+                        "",
+                        "## Shared Kernel Artifacts",
+                        ...kernelLines,
+                        "",
+                        "## Pipelines",
+                        "- standard: Swarm entrypoint -> ASTGrep -> Research -> Spec -> Builder -> QA -> Docs (Skeptic sidecar)",
+                        "- high_certainty: Swarm entrypoint -> ASTGrep -> Spec -> Builder -> QA -> Security -> Eval -> Release",
+                        "- high_ambiguity: Swarm entrypoint -> ASTGrep -> Research (continuous) -> Spec -> Builder with Ops + Memory sidecars",
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("get_kernel_artifact", "Load shared ACE kernel artifacts that harmonize swarm and composable agents", {
+        key: KERNEL_KEY_ENUM.describe("Kernel artifact key: directive_kernel or agent_registry"),
+    }, async ({ key }) => {
+        const path = getKernelArtifactPath(key);
+        const source = classifyPathSource(path);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `# ACE Kernel Artifact: ${key}`,
+                        "",
+                        `Source: ${source}${path ? ` (${path})` : ""}`,
+                        "",
+                        readKernelArtifact(key),
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("get_runtime_profile", "Load the active ACE runtime profile and prompt template state", {
+        path: z
+            .string()
+            .optional()
+            .describe("Optional workspace-relative path to inspect instead of the canonical runtime profile"),
+    }, async ({ path }) => {
+        const current = loadRuntimeProfile(path);
+        const active = readRuntimeProfileState();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "# ACE Runtime Profile",
+                        "",
+                        `Current load: ${current.ok ? "valid" : "INVALID"}`,
+                        `Current source: ${current.source}`,
+                        `Current path: ${current.path}`,
+                        current.ok
+                            ? `Current cache: ${current.cache_hit ? "hit" : "miss"}`
+                            : "",
+                        !current.ok && current.errors.length > 0
+                            ? ["## Current Errors", ...current.errors.map((error) => `- ${error}`)].join("\n")
+                            : "",
+                        "",
+                        `Active source: ${active.source}`,
+                        `Active path: ${active.path}`,
+                        "",
+                        "## Active Profile",
+                        "```json",
+                        JSON.stringify(active.profile, null, 2),
+                        "```",
+                        "",
+                        "## Active Prompt Template",
+                        "```md",
+                        readRuntimePromptTemplate(),
+                        "```",
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("validate_runtime_profile", "Validate ACE runtime profile markdown content or the current ACE_WORKFLOW.md file", {
+        content: z
+            .string()
+            .optional()
+            .describe("Raw ACE_WORKFLOW.md content. If omitted, validate the selected file path."),
+        path: z
+            .string()
+            .optional()
+            .describe("Optional workspace-relative path to validate when content is omitted."),
+    }, async ({ content, path }) => {
+        const validation = typeof content === "string"
+            ? validateRuntimeProfileContent(content)
+            : loadRuntimeProfile(path);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: validation.ok
+                        ? `✅ Runtime profile is valid (${validation.schema})`
+                        : [
+                            "❌ Runtime profile failed validation.",
+                            `Schema: ${validation.schema}`,
+                            ...validation.errors.map((error) => `- ${error}`),
+                        ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("get_runtime_tool_specs", "Load the active runtime-configured external tool spec registry", {
+        path: z
+            .string()
+            .optional()
+            .describe("Optional workspace-relative path to inspect instead of the configured runtime tool registry"),
+    }, async ({ path }) => {
+        const result = loadRuntimeToolRegistry(path);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.ok
+                        ? JSON.stringify({
+                            schema: result.schema,
+                            path: result.path,
+                            source: result.source,
+                            registry: result.registry,
+                        }, null, 2)
+                        : [
+                            "❌ Runtime tool registry failed validation.",
+                            `Schema: ${result.schema}`,
+                            `Path: ${result.path}`,
+                            ...((result.errors ?? []).map((error) => `- ${error}`)),
+                        ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("validate_runtime_tool_specs", "Validate runtime-tool-specs.json content or the active runtime tool registry file", {
+        content: z
+            .string()
+            .optional()
+            .describe("Raw runtime-tool-specs.json content. If omitted, validate the selected file path."),
+        path: z
+            .string()
+            .optional()
+            .describe("Optional workspace-relative path to validate when content is omitted."),
+    }, async ({ content, path }) => {
+        const validation = typeof content === "string"
+            ? validateRuntimeToolRegistryContent(content)
+            : loadRuntimeToolRegistry(path);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: validation.ok
+                        ? `✅ Runtime tool registry is valid (${validation.schema})`
+                        : [
+                            "❌ Runtime tool registry failed validation.",
+                            `Schema: ${validation.schema}`,
+                            ...((validation.errors ?? []).map((error) => `- ${error}`)),
+                        ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("list_runtime_tool_specs", "List runtime-configured external tool specs", {}, async () => ({
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(listRuntimeToolSpecs().map((tool) => ({
+                    name: tool.name,
+                    description: tool.description,
+                    executor: {
+                        command: tool.executor.command,
+                        cwd: tool.executor.cwd ?? null,
+                        timeout_ms: tool.executor.timeout_ms ?? null,
+                    },
+                })), null, 2),
+            },
+        ],
+    }));
+    server.tool("execute_runtime_tool", "Execute a runtime-configured external tool spec by name", {
+        name: z.string().describe("Runtime tool spec name"),
+        input_json: z
+            .string()
+            .optional()
+            .describe("JSON payload validated against the tool input schema"),
+        workspace_path: z
+            .string()
+            .optional()
+            .describe("Optional workspace/session path used as the execution root"),
+        session_id: z
+            .string()
+            .optional()
+            .describe("Optional unattended session id for provenance"),
+        turn_number: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Optional unattended session turn number for provenance"),
+    }, async ({ name, input_json, workspace_path, session_id, turn_number }) => {
+        const result = await executeRuntimeTool(name, parseUnknownJson(input_json), {
+            workspace_path,
+            session_id,
+            turn_number,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("list_unattended_sessions", "List unattended ACE runtime executor sessions", {}, async () => ({
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(listUnattendedSessions(), null, 2),
+            },
+        ],
+    }));
+    server.tool("get_unattended_session", "Get a single unattended ACE runtime executor session by id", {
+        session_id: z.string().describe("Unattended session id"),
+    }, async ({ session_id }) => ({
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(getUnattendedSession(session_id) ?? {
+                    error: `Unknown unattended session: ${session_id}`,
+                }, null, 2),
+            },
+        ],
+    }));
+    server.tool("validate_unattended_session_registry", "Validate runtime-executor-sessions.json content or the active unattended session registry file", {
+        content: z
+            .string()
+            .optional()
+            .describe("Raw runtime-executor-sessions.json content. If omitted, validate the active registry file."),
+    }, async ({ content }) => {
+        const validation = typeof content === "string"
+            ? validateRuntimeExecutorSessionRegistryContent(content)
+            : validateRuntimeExecutorSessionRegistryContent(JSON.stringify(listUnattendedSessions(), null, 2));
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: validation.ok
+                        ? `✅ Unattended session registry is valid (${validation.schema})`
+                        : [
+                            "❌ Unattended session registry failed validation.",
+                            `Schema: ${validation.schema}`,
+                            ...((validation.errors ?? []).map((error) => `- ${error}`)),
+                        ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("start_unattended_session", "Start a managed unattended execution session using ACE_WORKFLOW.md", {
+        task: z.string().describe("Primary objective or task for the unattended session"),
+        context_json: z
+            .string()
+            .optional()
+            .describe("Optional JSON object merged into the turn request context"),
+        workspace_name: z
+            .string()
+            .optional()
+            .describe("Optional logical workspace name for the managed session"),
+        workspace_path: z
+            .string()
+            .optional()
+            .describe("Optional explicit managed workspace path"),
+        objective_id: z.string().optional().describe("Optional linked objective id"),
+        tracker_item_id: z.string().optional().describe("Optional linked tracker item id"),
+        max_turns: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Optional max-turn override"),
+        turn_timeout_ms: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Optional per-turn timeout override in milliseconds"),
+        auto_cleanup: z
+            .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, }) => {
+        const result = await startUnattendedSession({
+            task,
+            context: parseOptionalJsonObject(context_json),
+            workspace_name,
+            workspace_path,
+            objective_id,
+            tracker_item_id,
+            max_turns,
+            turn_timeout_ms,
+            auto_cleanup,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.ok
+                        ? [
+                            "✅ Unattended session started",
+                            `Registry: ${result.registry_path}`,
+                            "```json",
+                            JSON.stringify(result.session, null, 2),
+                            "```",
+                        ].join("\n")
+                        : [
+                            "❌ Unattended session failed to start",
+                            result.error ?? "Unknown error",
+                        ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("wait_for_unattended_session", "Wait for an unattended runtime session to reach a terminal state", {
+        session_id: z.string().describe("Unattended session id"),
+        timeout_ms: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("How long to wait before timing out"),
+    }, async ({ session_id, timeout_ms }) => {
+        const result = await waitForUnattendedSession(session_id, timeout_ms);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("stop_unattended_session", "Stop an active unattended runtime session", {
+        session_id: z.string().describe("Unattended session id"),
+    }, async ({ session_id }) => {
+        const result = await stopUnattendedSession(session_id);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("run_local_model", "Offload a governed ACE subtask to a local model bridge and return the result", {
+        task: z.string().describe("Task to execute with the local ACE model bridge"),
+        role: ROLE_ENUM.optional().describe("Optional ACE role; defaults to route_task"),
+        max_turns: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Optional max-turn override; defaults by role"),
+        tier: z
+            .enum(["auto", "full", "compressed", "brief"])
+            .optional()
+            .describe("Prompt packing tier; default auto-detects from role and model"),
+        provider: z
+            .string()
+            .optional()
+            .describe("Optional provider override; otherwise discovered from local runtime context"),
+        model: z
+            .string()
+            .optional()
+            .describe("Optional model override; otherwise discovered from local runtime context"),
+        base_url: z
+            .string()
+            .optional()
+            .describe("Optional local runtime base URL override"),
+        ollama_url: z
+            .string()
+            .optional()
+            .describe("Optional Ollama base URL override (legacy alias for base_url)"),
+        tool_scope: z
+            .array(z.string())
+            .optional()
+            .describe("Optional explicit ACE tool allowlist for the delegated run"),
+        workspace_root: z
+            .string()
+            .optional()
+            .describe("Optional workspace root override; defaults to the active workspace"),
+    }, async ({ task, role, max_turns, tier, provider, model, base_url, ollama_url, tool_scope, workspace_root, }) => {
+        const delegated = await runLocalModelTask({
+            task,
+            role,
+            workspaceRoot: workspace_root,
+            provider,
+            model,
+            baseUrl: base_url,
+            ollamaUrl: ollama_url,
+            maxTurns: max_turns,
+            tier,
+            toolScope: tool_scope,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "## Local Model Run",
+                        `- role: ${delegated.role}`,
+                        `- provider: ${delegated.runtime.provider}`,
+                        `- model: ${delegated.runtime.model}`,
+                        `- workspace: ${delegated.runtime.workspaceRoot}`,
+                        `- status: ${delegated.result.status}`,
+                        `- turns: ${delegated.result.turns}`,
+                        delegated.routingSummary
+                            ? ["", "### Routing", delegated.routingSummary].join("\n")
+                            : "",
+                        delegated.runtime.notes.length > 0
+                            ? [
+                                "",
+                                "### Discovery Notes",
+                                ...delegated.runtime.notes.map((note) => `- ${note}`),
+                            ].join("\n")
+                            : "",
+                        "",
+                        "### Result",
+                        delegated.result.summary,
+                        delegated.result.tool_calls.length > 0
+                            ? [
+                                "",
+                                "### Tool Calls",
+                                ...delegated.result.tool_calls.map((tool) => `- ${tool.tool}: ${tool.ok ? "ok" : "error"} — ${tool.summary}`),
+                            ].join("\n")
+                            : "",
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("run_orchestrator", "Execute a supervised plan via model bridge child runs; when steps are omitted, auto-planning falls back to a single route_task-derived step", {
+        task: z.string().describe("The task to decompose and execute"),
+        steps: z
+            .array(z.object({
+            role: ROLE_ENUM.describe("ACE role assigned to the step"),
+            task: z.string().describe("Task directive for the step"),
+            depends_on: z
+                .array(z.string())
+                .optional()
+                .describe("Optional step ids that must complete first"),
+            parallel_group: z
+                .string()
+                .optional()
+                .describe("Optional parallel execution group"),
+            tool_scope: z
+                .array(z.string())
+                .optional()
+                .describe("Optional ACE tool allowlist for the step"),
+        }))
+            .optional()
+            .describe("Pre-defined steps; if omitted, the orchestrator derives a single routed step"),
+        execution_mode: z
+            .enum(["sequential", "scheduled"])
+            .optional()
+            .describe("Execution mode for the task plan"),
+        max_turns_per_step: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Optional max-turn limit applied to each child bridge step"),
+        provider: z
+            .string()
+            .optional()
+            .describe("Optional provider override; otherwise discovered from local runtime context"),
+        model: z
+            .string()
+            .optional()
+            .describe("Optional model override; otherwise discovered from local runtime context"),
+        base_url: z
+            .string()
+            .optional()
+            .describe("Optional local runtime base URL override"),
+        ollama_url: z
+            .string()
+            .optional()
+            .describe("Optional Ollama base URL override (legacy alias for base_url)"),
+        workspace_root: z
+            .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) => {
+        const runtime = resolveLocalModelRuntime({
+            workspaceRoot: workspace_root,
+            provider,
+            model,
+            baseUrl: base_url,
+            ollamaUrl: ollama_url,
+        });
+        const sessionId = typeof extra?.sessionId === "string" ? extra.sessionId : undefined;
+        const planSource = Array.isArray(steps) && steps.length > 0 ? "explicit_steps" : "route_task_single_step";
+        const planSteps = Array.isArray(steps) && steps.length > 0
+            ? steps
+            : await buildOrchestratorSteps(task, sessionId);
+        const plan = createTaskPlan({
+            task,
+            steps: planSteps,
+            execution_mode: execution_mode ?? "sequential",
+        });
+        const bridge = new ModelBridge(createDefaultModelBridgeClients(runtime));
+        const fallbackHandoffPrefix = `LOCAL-${plan.plan_id}-`;
+        const vericifyWarnings = [];
+        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,
+                });
+            },
+            async createHandoff({ step, plan: activePlan }) {
+                const created = await executeAceInternalTool("create_handoff", {
+                    from: "orchestrator",
+                    to: step.role,
+                    title: `${activePlan.plan_id}:${step.step_id} ${step.task}`.slice(0, 120),
+                    task_type: mapRoleToTaskType(step.role),
+                    priority: "P1",
+                    directive: step.task,
+                    acceptance_criteria: [`Complete ${step.step_id}: ${step.task}`],
+                    context_pointers: {
+                        engineering_constraint: `plan=${activePlan.plan_id}; step=${step.step_id}`,
+                    },
+                }, sessionId);
+                const handoffId = extractHandoffId(extractToolTextContent(created));
+                return {
+                    handoff_id: handoffId ?? `${fallbackHandoffPrefix}${step.step_id}`,
+                };
+            },
+            async ackHandoff(handoffId, status, note) {
+                if (handoffId.startsWith(fallbackHandoffPrefix)) {
+                    return;
+                }
+                await executeAceInternalTool("ack_handoff", {
+                    handoff_id: handoffId,
+                    status,
+                    note,
+                }, sessionId);
+            },
+            amendPlan({ plan: activePlan, step, result }) {
+                return buildDefaultOrchestratorAmendment({
+                    plan: activePlan,
+                    step,
+                    result,
+                });
+            },
+            async getVericifyContext() {
+                return tryVericifyPacket(() => getVericifyContextPacket({
+                    workspaceRoot: runtime.workspaceRoot,
+                }), (message) => appendUniqueNote(vericifyWarnings, `Vericify context unavailable for ${plan.plan_id}: ${message}`));
+            },
+            async getVericifyDelta(since) {
+                return tryVericifyPacket(() => getVericifyDelta({
+                    since,
+                    workspaceRoot: runtime.workspaceRoot,
+                }), (message) => appendUniqueNote(vericifyWarnings, `Vericify delta unavailable for ${plan.plan_id}: ${message}`));
+            },
+            async openCircuitBreaker(reason) {
+                await executeAceInternalTool("open_circuit_breaker", {
+                    reason,
+                    owner: "capability-ops",
+                }, sessionId);
+            },
+            async closeCircuitBreaker(reason) {
+                await executeAceInternalTool("close_circuit_breaker", {
+                    reason,
+                }, sessionId);
+            },
+            async executeGates() {
+                const result = await executeAceInternalTool("execute_gates", {}, sessionId);
+                return {
+                    ok: !Boolean(result?.isError),
+                    summary: extractToolTextContent(result),
+                };
+            },
+            async contextSnapshot(activePlan) {
+                await executeAceInternalTool("context_snapshot", {
+                    name: `${activePlan.plan_id}-final`,
+                    summary: `Orchestrator plan ${activePlan.plan_id} finished with status ${activePlan.status}`,
+                    artifacts: activePlan.steps.map((step) => `${step.step_id}:${step.role}`),
+                    decisions: activePlan.steps
+                        .filter((step) => typeof step.result_summary === "string" && step.result_summary.trim())
+                        .map((step) => `${step.step_id}: ${step.result_summary}`),
+                }, sessionId);
+            },
+            async emitStatusEvent(event) {
+                await executeAceInternalTool("emit_status_event", {
+                    source_module: "capability-ops",
+                    event_type: "ORCHESTRATOR_STEP",
+                    status: event.status === "done" ? "done" : event.status === "blocked" ? "blocked" : "in_progress",
+                    summary: event.summary,
+                    payload_json: JSON.stringify(event.step_id ? { step_id: event.step_id, plan_id: plan.plan_id } : { plan_id: plan.plan_id }),
+                }, sessionId);
+            },
+        });
+        const step_summaries = supervised.plan.steps.map((step) => ({
+            step_id: step.step_id,
+            role: step.role,
+            task: step.task,
+            status: step.status,
+            result_summary: step.result_summary ?? "",
+            handoff_id: step.handoff_id ?? null,
+            job_id: step.job_id ?? null,
+            blocked_reason: step.blocked_reason ?? null,
+        }));
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        runtime,
+                        plan_source: planSource,
+                        planning_note: planSource === "route_task_single_step"
+                            ? "Auto-planning currently falls back to a single route_task-derived step. Pass explicit steps for multi-step orchestration."
+                            : null,
+                        plan: supervised.plan,
+                        step_summaries,
+                        handoff_ids: supervised.handoff_ids,
+                        job_ids: supervised.job_ids,
+                        circuit_opened: supervised.circuit_opened,
+                        final_gate: supervised.final_gate ?? null,
+                        vericify_warnings: vericifyWarnings,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("get_vericify_context", "Build a compact Vericify context packet for workspace:current or a specified run", {
+        run_id: z
+            .string()
+            .optional()
+            .describe("Optional Vericify run id; defaults to workspace:current"),
+        workspace_root: z
+            .string()
+            .optional()
+            .describe("Optional workspace root override used to locate the Vericify workspace"),
+    }, async ({ run_id, workspace_root }) => {
+        try {
+            const packet = await getVericifyContextPacket({
+                runId: run_id,
+                workspaceRoot: workspace_root,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(packet, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `❌ Vericify context failed: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.tool("get_vericify_delta", "Build a compact Vericify delta from a prior vcx cursor or checkpoint reference", {
+        since: z
+            .string()
+            .describe("Required prior vcx cursor or compatible checkpoint reference"),
+        run_id: z
+            .string()
+            .optional()
+            .describe("Optional Vericify run id; defaults to workspace:current"),
+        workspace_root: z
+            .string()
+            .optional()
+            .describe("Optional workspace root override used to locate the Vericify workspace"),
+    }, async ({ since, run_id, workspace_root }) => {
+        try {
+            const delta = await getVericifyDelta({
+                since,
+                runId: run_id,
+                workspaceRoot: workspace_root,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(delta, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `❌ Vericify delta failed: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.tool("get_vericify_bridge", "Load the optional Vericify sidecar bridge snapshot derived from ACE runtime artifacts", {}, async () => {
+        const result = loadVericifyBridgeSnapshot();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.ok
+                        ? JSON.stringify({
+                            schema: result.schema,
+                            path: result.path,
+                            snapshot: result.snapshot,
+                        }, null, 2)
+                        : [
+                            "❌ Vericify bridge snapshot failed validation.",
+                            `Schema: ${result.schema}`,
+                            `Path: ${result.path}`,
+                            ...((result.errors ?? []).map((error) => `- ${error}`)),
+                        ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("refresh_vericify_bridge", "Refresh the optional Vericify sidecar bridge snapshot from current ACE runtime artifacts", {}, async () => {
+        const result = refreshVericifyBridgeSnapshot();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.ok
+                        ? [
+                            "✅ Vericify bridge refreshed",
+                            `Path: ${result.path}`,
+                            "```json",
+                            JSON.stringify(result.snapshot, null, 2),
+                            "```",
+                        ].join("\n")
+                        : [
+                            "❌ Vericify bridge refresh failed",
+                            `Path: ${result.path}`,
+                            result.error ?? "Unknown error",
+                        ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("validate_vericify_bridge", "Validate the Vericify bridge snapshot content or active file", {
+        content: z
+            .string()
+            .optional()
+            .describe("Raw Vericify bridge snapshot JSON. If omitted, validate the active bridge file."),
+    }, async ({ content }) => {
+        const validation = typeof content === "string"
+            ? validateVericifyBridgeSnapshotContent(content)
+            : loadVericifyBridgeSnapshot();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: validation.ok
+                        ? `✅ Vericify bridge snapshot is valid (${validation.schema})`
+                        : [
+                            "❌ Vericify bridge snapshot failed validation.",
+                            `Schema: ${validation.schema}`,
+                            ...((validation.errors ?? []).map((error) => `- ${error}`)),
+                        ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("get_vericify_process_posts", "Load the optional Vericify sidecar process-post log maintained by ACE", {}, async () => {
+        const result = loadVericifyProcessPostLog();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.ok
+                        ? JSON.stringify({
+                            schema: result.schema,
+                            path: result.path,
+                            log: result.log,
+                        }, null, 2)
+                        : [
+                            "❌ Vericify process post log failed validation.",
+                            `Schema: ${result.schema}`,
+                            `Path: ${result.path}`,
+                            ...((result.errors ?? []).map((error) => `- ${error}`)),
+                        ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("append_vericify_process_post", "Append a structured process post to the optional Vericify sidecar log without requiring Vericify to be installed", {
+        run_id: z.string().describe("Vericify run id"),
+        branch_id: z.string().optional().describe("Optional Vericify branch id"),
+        lane_id: z.string().optional().describe("Optional Vericify lane id"),
+        agent_id: z.string().describe("Posting agent/module id"),
+        kind: z
+            .enum(["intent", "progress", "blocker", "handoff_note", "stale_ack", "completion"])
+            .describe("Structured process post kind"),
+        summary: z.string().describe("Short operator-facing summary"),
+        tool_refs: z
+            .array(z.string())
+            .optional()
+            .describe("Optional tool references attached to the process post"),
+        evidence_refs: z
+            .array(z.string())
+            .optional()
+            .describe("Optional evidence references attached to the process post"),
+        checkpoint_ref: z.string().optional().describe("Optional checkpoint id"),
+    }, async ({ run_id, branch_id, lane_id, agent_id, kind, summary, tool_refs, evidence_refs, checkpoint_ref }) => {
+        const result = await appendVericifyProcessPost({
+            run_id,
+            branch_id,
+            lane_id,
+            agent_id,
+            kind,
+            summary,
+            tool_refs,
+            evidence_refs,
+            checkpoint_ref,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "✅ Vericify process post appended",
+                        `Path: ${result.path}`,
+                        "```json",
+                        JSON.stringify(result.post, null, 2),
+                        "```",
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("validate_vericify_process_post_log", "Validate the Vericify process-post log content or active file", {
+        content: z
+            .string()
+            .optional()
+            .describe("Raw Vericify process-post log JSON. If omitted, validate the active log file."),
+    }, async ({ content }) => {
+        const validation = typeof content === "string"
+            ? validateVericifyProcessPostLogContent(content)
+            : loadVericifyProcessPostLog();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: validation.ok
+                        ? `✅ Vericify process post log is valid (${validation.schema})`
+                        : [
+                            "❌ Vericify process post log failed validation.",
+                            `Schema: ${validation.schema}`,
+                            ...((validation.errors ?? []).map((error) => `- ${error}`)),
+                        ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("list_workspace_sessions", "List managed ACE workspace sessions from the runtime registry", {}, async () => ({
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(listWorkspaceSessions(), null, 2),
+            },
+        ],
+    }));
+    server.tool("validate_managed_workspace_path", "Validate a target path against the configured managed workspace root and path-safety invariants", {
+        target: z.string().describe("Target workspace path or relative child path"),
+        root: z
+            .string()
+            .optional()
+            .describe("Optional root override. Defaults to the runtime profile workspace root."),
+    }, async ({ target, root }) => {
+        const resolvedRoot = resolveRuntimeWorkspaceRoot(root);
+        const validation = validateManagedWorkspacePath(resolvedRoot, target);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(validation, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("create_workspace_session", "Create a managed ACE workspace session under the configured runtime root", {
+        workspace_name: z
+            .string()
+            .optional()
+            .describe("Logical workspace name used to derive the managed directory name"),
+        workspace_path: z
+            .string()
+            .optional()
+            .describe("Optional explicit target path. Relative paths are resolved under the managed root."),
+        source: z
+            .enum(["manual", "executor", "test"])
+            .describe("How this workspace session was created"),
+        objective_id: z.string().optional().describe("Optional linked objective id"),
+        tracker_item_id: z.string().optional().describe("Optional linked tracker item id"),
+        root: z
+            .string()
+            .optional()
+            .describe("Optional root override. Defaults to the runtime profile workspace root."),
+        hooks_timeout_ms: z
+            .number()
+            .int()
+            .positive()
+            .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({
+            workspace_name,
+            workspace_path,
+            source,
+            objective_id,
+            tracker_item_id,
+            root,
+            hooks_timeout_ms,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.ok
+                        ? [
+                            "✅ Workspace session created",
+                            `Registry: ${result.registry_path}`,
+                            "```json",
+                            JSON.stringify(result.session, null, 2),
+                            "```",
+                        ].join("\n")
+                        : [
+                            "❌ Workspace session create failed",
+                            result.error ?? "Unknown error",
+                            result.validation ? "```json" : "",
+                            result.validation ? JSON.stringify(result.validation, null, 2) : "",
+                            result.validation ? "```" : "",
+                        ]
+                            .filter(Boolean)
+                            .join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("remove_workspace_session", "Remove or archive a managed ACE workspace session using the runtime retention policy", {
+        session_id: z.string().optional().describe("Managed workspace session id"),
+        workspace_path: z
+            .string()
+            .optional()
+            .describe("Managed workspace path when removing by path instead of session id"),
+        root: z
+            .string()
+            .optional()
+            .describe("Optional root override. Defaults to the runtime profile workspace root."),
+        hooks_timeout_ms: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Optional hook timeout override in milliseconds"),
+    }, async ({ session_id, workspace_path, root, hooks_timeout_ms }) => {
+        const result = removeWorkspaceSession({
+            session_id,
+            workspace_path,
+            root,
+            hooks_timeout_ms,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.ok
+                        ? [
+                            "✅ Workspace session updated",
+                            `Registry: ${result.registry_path}`,
+                            "```json",
+                            JSON.stringify(result.session, null, 2),
+                            "```",
+                        ].join("\n")
+                        : [
+                            "❌ Workspace session removal failed",
+                            result.error ?? "Unknown error",
+                            result.validation ? "```json" : "",
+                            result.validation ? JSON.stringify(result.validation, null, 2) : "",
+                            result.validation ? "```" : "",
+                        ]
+                            .filter(Boolean)
+                            .join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("get_tracker_snapshot", "Load the active normalized ACE tracker snapshot", {
+        path: z
+            .string()
+            .optional()
+            .describe("Optional workspace-relative path override for a tracker snapshot file."),
+    }, async ({ path }) => {
+        const result = loadTrackerSnapshot(path);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.ok
+                        ? JSON.stringify({
+                            schema: result.schema,
+                            path: result.path,
+                            source: result.source,
+                            snapshot: result.snapshot,
+                        }, null, 2)
+                        : [
+                            "❌ Tracker snapshot failed validation.",
+                            `Schema: ${result.schema}`,
+                            `Path: ${result.path}`,
+                            ...((result.errors ?? []).map((error) => `- ${error}`)),
+                        ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("validate_tracker_snapshot", "Validate tracker-snapshot.json content or the active snapshot file", {
+        content: z
+            .string()
+            .optional()
+            .describe("Raw tracker snapshot JSON content. If omitted, validate the selected file path."),
+        path: z
+            .string()
+            .optional()
+            .describe("Optional workspace-relative path to validate when content is omitted."),
+    }, async ({ content, path }) => {
+        const validation = typeof content === "string"
+            ? validateTrackerSnapshotContent(content)
+            : loadTrackerSnapshot(path);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: validation.ok
+                        ? `✅ Tracker snapshot is valid (${validation.schema})`
+                        : [
+                            "❌ Tracker snapshot failed validation.",
+                            `Schema: ${validation.schema}`,
+                            ...((validation.errors ?? []).map((error) => `- ${error}`)),
+                        ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("list_tracker_adapter_kinds", "List available ACE tracker adapter kinds", {}, async () => ({
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(listTrackerAdapterKinds(), null, 2),
+            },
+        ],
+    }));
+    server.tool("get_tracker_adapter_health", "Run the active or selected tracker adapter health check", {
+        kind: z
+            .string()
+            .optional()
+            .describe("Optional tracker adapter kind override (none, memory, external)"),
+    }, async ({ kind }) => {
+        try {
+            const adapter = getTrackerAdapter(kind);
+            const health = adapter.healthCheck
+                ? await adapter.healthCheck()
+                : { ok: true, detail: "No health check implemented." };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            kind: adapter.kind,
+                            ...health,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `❌ ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    });
+    server.tool("list_tracker_items", "List normalized tracker items through the active or selected tracker adapter", {
+        kind: z
+            .string()
+            .optional()
+            .describe("Optional tracker adapter kind override (none, memory, external)"),
+        ids: z.array(z.string()).optional().describe("Optional item ids or external ids to include"),
+        states: z.array(z.string()).optional().describe("Optional allowed item states"),
+        labels: z.array(z.string()).optional().describe("Optional required labels"),
+        assignee: z.string().optional().describe("Optional assignee filter"),
+        query: z
+            .string()
+            .optional()
+            .describe("Optional case-insensitive title/body substring filter"),
+    }, async ({ kind, ids, states, labels, assignee, query }) => {
+        const adapter = getTrackerAdapter(kind);
+        const items = adapter.listActiveItems
+            ? await adapter.listActiveItems({
+                ids,
+                states,
+                labels,
+                assignee,
+                query,
+            })
+            : [];
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(items, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("create_tracker_comment", "Create a tracker comment through the active or selected adapter", {
+        item_id: z.string().describe("Normalized tracker item id"),
+        body: z.string().describe("Comment body"),
+        kind: z
+            .string()
+            .optional()
+            .describe("Optional tracker adapter kind override (none, memory, external)"),
+    }, async ({ item_id, body, kind }) => {
+        const adapter = getTrackerAdapter(kind);
+        const result = adapter.createComment
+            ? await adapter.createComment(item_id, body)
+            : { ok: false, error: `Tracker adapter '${adapter.kind}' does not support comments.` };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.ok
+                        ? [
+                            "✅ Tracker comment created",
+                            `Adapter: ${adapter.kind}`,
+                            result.comment_id ? `Comment ID: ${result.comment_id}` : "",
+                        ]
+                            .filter(Boolean)
+                            .join("\n")
+                        : [
+                            "❌ Tracker comment failed",
+                            `Adapter: ${adapter.kind}`,
+                            result.error ?? "Unknown error",
+                        ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("update_tracker_item_state", "Update a tracker item state through the active or selected adapter", {
+        item_id: z.string().describe("Normalized tracker item id"),
+        state: z.string().describe("New tracker state"),
+        kind: z
+            .string()
+            .optional()
+            .describe("Optional tracker adapter kind override (none, memory, external)"),
+    }, async ({ item_id, state, kind }) => {
+        const adapter = getTrackerAdapter(kind);
+        const result = adapter.updateItemState
+            ? await adapter.updateItemState(item_id, state)
+            : { ok: false, error: `Tracker adapter '${adapter.kind}' does not support state updates.` };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.ok
+                        ? [
+                            "✅ Tracker state updated",
+                            `Adapter: ${adapter.kind}`,
+                            `Item: ${item_id}`,
+                            `State: ${state}`,
+                        ].join("\n")
+                        : [
+                            "❌ Tracker state update failed",
+                            `Adapter: ${adapter.kind}`,
+                            result.error ?? "Unknown error",
+                        ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("refresh_tracker_snapshot", "Refresh tracker-snapshot.json through the active or selected tracker adapter", {
+        kind: z
+            .string()
+            .optional()
+            .describe("Optional tracker adapter kind override (none, memory, external)"),
+    }, async ({ kind }) => {
+        const result = await refreshTrackerSnapshot(kind);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.ok
+                        ? [
+                            "✅ Tracker snapshot refreshed",
+                            `Adapter: ${result.adapter_kind}`,
+                            `Path: ${result.snapshot_path}`,
+                            "```json",
+                            JSON.stringify(result.snapshot, null, 2),
+                            "```",
+                        ].join("\n")
+                        : [
+                            "❌ Tracker snapshot refresh failed",
+                            `Adapter: ${result.adapter_kind}`,
+                            `Path: ${result.snapshot_path}`,
+                            result.error ?? "Unknown error",
+                        ].join("\n"),
+                },
+            ],
+        };
+    });
+    // ── Skills ────────────────────────────────────────────────────────
+    server.tool("list_skills", "List all discoverable ACE skills with source paths", {}, async () => {
+        const skills = listAvailableSkills();
+        const lines = [
+            "# ACE Skills",
+            "",
+            ...skills.map((skill) => `- ${skill.name} (${skill.source}) -> ${skill.path}`),
+        ];
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+        };
+    });
+    server.tool("get_skill_instructions", "Load SKILL.md for a specific ACE skill", {
+        name: z.string().describe("Skill name (e.g., codemunch, codesnipe)"),
+    }, async ({ name }) => {
+        const skills = listAvailableSkills();
+        const match = skills.find((skill) => skill.name.toLowerCase() === name.trim().toLowerCase());
+        const prefix = match
+            ? `# Skill: ${match.name}\n\nSource: ${match.source} (${match.path})\n\n`
+            : `# Skill: ${name}\n\n`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `${prefix}${readSkillInstructions(name)}`,
+                },
+            ],
+        };
+    });
+    // ── Task Pack ─────────────────────────────────────────────────────
+    server.tool("get_task_pack", "Get responsibilities and evidence requirements for a specific ACE role", {
+        role: ROLE_ENUM.describe("Agent role"),
+    }, async ({ role }) => {
+        const full = readTaskArtifact("role_tasks");
+        const headerSuffix = ROLE_TITLES[role] ?? role;
+        const roleHeader = `## ACE-${headerSuffix} Task Pack`;
+        const start = full.indexOf(roleHeader);
+        if (start === -1) {
+            const lowerFull = full.toLowerCase();
+            const lowerHeader = roleHeader.toLowerCase();
+            const ciStart = lowerFull.indexOf(lowerHeader);
+            if (ciStart === -1) {
+                return {
+                    content: [{ type: "text", text: `Task pack section not found for role: ${role}` }],
+                };
+            }
+            const ciNext = lowerFull.indexOf("\n## ", ciStart + lowerHeader.length);
+            const section = ciNext === -1 ? full.slice(ciStart) : full.slice(ciStart, ciNext);
+            return { content: [{ type: "text", text: section.trim() }] };
+        }
+        const next = full.indexOf("\n## ", start + roleHeader.length);
+        const section = next === -1 ? full.slice(start) : full.slice(start, next);
+        return {
+            content: [{ type: "text", text: section.trim() }],
+        };
+    });
+    // ── Lessons ───────────────────────────────────────────────────────
+    server.tool("get_lessons", "Read all accumulated lessons and guardrails", {}, async () => ({
+        content: [{ type: "text", text: readTaskArtifact("lessons") }],
+    }));
+    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 = safeWrite(resolveWritableTaskPath("lessons"), `${existing}${entry}`);
+        return {
+            content: [{ type: "text", text: `✅ Lesson recorded in ${path}` }],
+        };
+    });
+    // ── CLI Work Split ────────────────────────────────────────────────
+    server.tool("get_cli_split", "Get the CLI work split contract (Codex vs Gemini routing)", {}, async () => ({
+        content: [{ type: "text", text: readTaskArtifact("cli_work_split") }],
+    }));
+}
+//# sourceMappingURL=tools-agent.js.map