ace-swarm 2.0.5 → 2.0.7

package/dist/tools-agent.js

@@ -3,7 +3,38 @@
  */
 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";
+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 };
+    }
+}
 export function registerAgentTools(server) {
     // ── Agent Instructions & Manifests ────────────────────────────────
     server.tool("get_agent_instructions", "Load the full instruction file for a specific ACE agent role", {
@@ -116,6 +147,844 @@ export function registerAgentTools(server) {
             ],
         };
     });
+    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("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", "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();