@voybio/ace-swarm 0.1.0

package/dist/tracker-adapters.js

@@ -0,0 +1,776 @@
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { DEFAULTS_ROOT, resolveWorkspaceArtifactPath as resolveWorkspaceArtifactPathHelper, resolveWorkspaceRoot, } from "./helpers.js";
+import { validateTrackerSnapshotPayload } from "./schemas.js";
+import { appendStatusEvent } from "./status-events.js";
+import { readRuntimeProfile } from "./runtime-profile.js";
+export const TRACKER_SNAPSHOT_REL_PATH = "agent-state/tracker-snapshot.json";
+export const TRACKER_SNAPSHOT_SCHEMA_REL_PATH = "agent-state/MODULES/schemas/TRACKER_SNAPSHOT.schema.json";
+export const TRACKER_SNAPSHOT_SCHEMA_NAME = "tracker-snapshot@1.0.0";
+const DEFAULT_TRACKER_SNAPSHOT_PATH = resolve(DEFAULTS_ROOT, TRACKER_SNAPSHOT_REL_PATH);
+function defaultTrackerSnapshot(kind = "none") {
+    return {
+        version: 1,
+        adapter_kind: kind,
+        updated_at: "1970-01-01T00:00:00.000Z",
+        items: [],
+        comments: [],
+    };
+}
+function normalizeSource(path) {
+    return path === DEFAULT_TRACKER_SNAPSHOT_PATH || path.startsWith(DEFAULTS_ROOT)
+        ? "package-defaults"
+        : "workspace";
+}
+function resolveTrackerSnapshotTarget(explicitPath) {
+    if (explicitPath) {
+        const resolved = explicitPath.startsWith("/")
+            ? resolve(explicitPath)
+            : resolveWorkspaceArtifactPathHelper(explicitPath, "read");
+        return { path: resolved, source: normalizeSource(resolved) };
+    }
+    const workspacePath = resolveWorkspaceArtifactPathHelper(TRACKER_SNAPSHOT_REL_PATH, "read");
+    if (existsSync(workspacePath)) {
+        return { path: workspacePath, source: "workspace" };
+    }
+    return { path: DEFAULT_TRACKER_SNAPSHOT_PATH, source: "package-defaults" };
+}
+function resolveWorkspaceArtifactPath(filePath) {
+    return resolveWorkspaceArtifactPathHelper(filePath, "write");
+}
+function safeWriteWorkspaceFile(filePath, content) {
+    const abs = resolveWorkspaceArtifactPath(filePath);
+    mkdirSync(dirname(abs), { recursive: true });
+    const tmpPath = `${abs}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmpPath, content, "utf-8");
+    renameSync(tmpPath, abs);
+    return abs;
+}
+function normalizeTrackerItem(item) {
+    return {
+        ...item,
+        labels: [...new Set(item.labels)].sort((a, b) => a.localeCompare(b)),
+        metadata: { ...(item.metadata ?? {}) },
+    };
+}
+function normalizeTrackerComment(comment) {
+    return {
+        ...comment,
+        metadata: { ...(comment.metadata ?? {}) },
+    };
+}
+function normalizeTrackerSnapshot(snapshot) {
+    return {
+        ...snapshot,
+        items: [...snapshot.items]
+            .map(normalizeTrackerItem)
+            .sort((a, b) => a.item_id.localeCompare(b.item_id)),
+        comments: [...snapshot.comments]
+            .map(normalizeTrackerComment)
+            .sort((a, b) => a.comment_id.localeCompare(b.comment_id)),
+    };
+}
+function parseTrackerSnapshotContent(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Tracker snapshot contains invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const validation = validateTrackerSnapshotPayload(parsed);
+    if (!validation.ok) {
+        throw new Error(`Tracker snapshot failed validation (${validation.schema}): ${validation.errors.join("; ")}`);
+    }
+    return normalizeTrackerSnapshot(parsed);
+}
+function readTrackerConfig() {
+    const config = readRuntimeProfile().tracker.config;
+    if (!config || typeof config !== "object" || Array.isArray(config)) {
+        return {};
+    }
+    return { ...config };
+}
+function readStringList(input, key) {
+    const value = input[key];
+    let strings = [];
+    if (Array.isArray(value)) {
+        strings = value
+            .filter((entry) => typeof entry === "string")
+            .map((entry) => entry.trim())
+            .filter(Boolean);
+    }
+    else if (typeof value === "string") {
+        strings = value
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter(Boolean);
+    }
+    return strings.length > 0 ? strings : undefined;
+}
+function filterTrackerItems(items, filter) {
+    const config = readTrackerConfig();
+    const ids = Array.isArray(filter?.ids)
+        ? filter.ids.filter((entry) => typeof entry === "string")
+        : undefined;
+    const states = Array.isArray(filter?.states)
+        ? filter.states.filter((entry) => typeof entry === "string")
+        : readStringList(config, "active_states");
+    const labels = Array.isArray(filter?.labels)
+        ? filter.labels.filter((entry) => typeof entry === "string")
+        : undefined;
+    const assignee = typeof filter?.assignee === "string" ? filter.assignee.trim() : undefined;
+    const query = typeof filter?.query === "string" ? filter.query.trim().toLowerCase() : "";
+    return items.filter((item) => {
+        if (ids && ids.length > 0) {
+            const match = ids.includes(item.item_id) || ids.includes(item.external_id ?? "");
+            if (!match)
+                return false;
+        }
+        if (states && states.length > 0 && !states.includes(item.state)) {
+            return false;
+        }
+        if (labels &&
+            labels.length > 0 &&
+            !labels.every((label) => item.labels.includes(label))) {
+            return false;
+        }
+        if (assignee && item.assignee !== assignee) {
+            return false;
+        }
+        if (query) {
+            const haystack = `${item.title}\n${item.body ?? ""}`.toLowerCase();
+            if (!haystack.includes(query))
+                return false;
+        }
+        return true;
+    });
+}
+function emitTrackerEvent(eventType, summary, payload) {
+    try {
+        appendStatusEvent({
+            source_module: "capability-framework",
+            event_type: eventType,
+            status: eventType === "TRACKER_SNAPSHOT_REFRESH_FAILED" ? "fail" : "done",
+            summary,
+            payload,
+        });
+    }
+    catch {
+        // Tracker operations must not fail because event logging failed.
+    }
+}
+function resolveTrackerAdapterKind(kind) {
+    const candidate = (kind?.trim() || readRuntimeProfile().tracker.kind || "none");
+    if (candidate === "none" || candidate === "memory" || candidate === "external") {
+        return candidate;
+    }
+    throw new Error(`Unknown tracker adapter kind: ${candidate}`);
+}
+function findItemIndex(snapshot, itemId) {
+    return snapshot.items.findIndex((item) => item.item_id === itemId || item.external_id === itemId);
+}
+function getMemoryTrackerAuthor() {
+    const config = readTrackerConfig();
+    if (typeof config.author === "string" && config.author.trim().length > 0) {
+        return config.author.trim();
+    }
+    return "ace-memory";
+}
+function getExternalTrackerAuthor() {
+    const config = readTrackerConfig();
+    if (typeof config.author === "string" && config.author.trim().length > 0) {
+        return config.author.trim();
+    }
+    return "ace-external";
+}
+function readConfigString(config, key) {
+    const value = config[key];
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function readConfigPositiveInt(config, key) {
+    const value = config[key];
+    return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+function resolveExternalTrackerProvider() {
+    const config = readTrackerConfig();
+    const provider = (readConfigString(config, "provider") ?? "github").toLowerCase();
+    if (provider === "github")
+        return "github";
+    throw new Error(`Unsupported external tracker provider: ${provider}`);
+}
+function resolveExternalTrackerCommand() {
+    const config = readTrackerConfig();
+    return readConfigString(config, "command") ?? "gh";
+}
+function resolveExternalTrackerRepo() {
+    const config = readTrackerConfig();
+    const repo = readConfigString(config, "repo");
+    if (!repo)
+        throw new Error("External tracker config requires tracker.config.repo.");
+    return repo;
+}
+function resolveExternalTrackerCwd() {
+    const config = readTrackerConfig();
+    const cwd = readConfigString(config, "cwd");
+    return cwd
+        ? cwd.startsWith("/")
+            ? resolve(cwd)
+            : resolve(resolveWorkspaceRoot(), cwd)
+        : resolveWorkspaceRoot();
+}
+function resolveExternalTrackerLimit() {
+    const config = readTrackerConfig();
+    return readConfigPositiveInt(config, "limit") ?? 100;
+}
+async function runExternalTrackerCommand(args) {
+    const command = resolveExternalTrackerCommand();
+    const cwd = resolveExternalTrackerCwd();
+    return new Promise((resolvePromise) => {
+        const child = spawn(command, args, {
+            cwd,
+            env: process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("error", (error) => {
+            resolvePromise({
+                ok: false,
+                stdout,
+                stderr: `${stderr}${error.message}`,
+                exit_code: null,
+            });
+        });
+        child.on("close", (code) => {
+            resolvePromise({
+                ok: code === 0,
+                stdout,
+                stderr,
+                exit_code: code,
+            });
+        });
+    });
+}
+function parseGithubIssueNumber(itemId) {
+    const trimmed = itemId.trim();
+    const match = trimmed.match(/#?(\d+)$/);
+    if (!match) {
+        throw new Error(`GitHub tracker item id is invalid: ${itemId}`);
+    }
+    return match[1];
+}
+function readGithubJson(stdout, label) {
+    try {
+        return JSON.parse(stdout);
+    }
+    catch (error) {
+        throw new Error(`${label} returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function normalizeGithubTrackerItem(issue, repo) {
+    const numberValue = issue.number;
+    const issueNumber = typeof numberValue === "number" || typeof numberValue === "string"
+        ? String(numberValue)
+        : "";
+    if (!issueNumber) {
+        throw new Error("GitHub issue payload is missing number.");
+    }
+    const labels = Array.isArray(issue.labels)
+        ? issue.labels
+            .map((label) => {
+            if (typeof label === "string")
+                return label;
+            if (label && typeof label === "object" && typeof label.name === "string") {
+                return label.name;
+            }
+            return "";
+        })
+            .map((entry) => entry.trim())
+            .filter(Boolean)
+        : [];
+    const assignee = Array.isArray(issue.assignees)
+        ? issue.assignees
+            .map((entry) => {
+            if (typeof entry === "string")
+                return entry;
+            if (entry && typeof entry === "object") {
+                const record = entry;
+                if (typeof record.login === "string")
+                    return record.login;
+                if (typeof record.name === "string")
+                    return record.name;
+            }
+            return "";
+        })
+            .map((entry) => entry.trim())
+            .find(Boolean)
+        : undefined;
+    const state = typeof issue.state === "string" && issue.state.trim().length > 0
+        ? issue.state.trim().toLowerCase()
+        : "open";
+    return normalizeTrackerItem({
+        item_id: `github:${repo}#${issueNumber}`,
+        external_id: issueNumber,
+        title: typeof issue.title === "string" ? issue.title.trim() : `GitHub issue ${issueNumber}`,
+        body: typeof issue.body === "string" ? issue.body : undefined,
+        state,
+        labels,
+        assignee,
+        url: typeof issue.url === "string" ? issue.url : undefined,
+        updated_at: typeof issue.updatedAt === "string" && issue.updatedAt.trim().length > 0
+            ? issue.updatedAt
+            : new Date().toISOString(),
+        metadata: {
+            provider: "github",
+            repo,
+            issue_number: issueNumber,
+            issue_id: typeof issue.id === "string" ? issue.id : undefined,
+            state_reason: typeof issue.stateReason === "string" ? issue.stateReason : undefined,
+        },
+    });
+}
+async function githubListIssues(filter) {
+    const repo = resolveExternalTrackerRepo();
+    const limit = Math.max(1, resolveExternalTrackerLimit());
+    const result = await runExternalTrackerCommand([
+        "issue",
+        "list",
+        "--repo",
+        repo,
+        "--state",
+        "all",
+        "--limit",
+        String(limit),
+        "--json",
+        "id,number,title,body,state,stateReason,labels,assignees,updatedAt,url",
+    ]);
+    if (!result.ok) {
+        throw new Error(result.stderr.trim() || `GitHub issue list failed (exit ${result.exit_code ?? "?"}).`);
+    }
+    const issues = readGithubJson(result.stdout, "GitHub issue list");
+    return filterTrackerItems(issues.map((issue) => normalizeGithubTrackerItem(issue, repo)), filter);
+}
+async function githubGetIssuesById(ids) {
+    const repo = resolveExternalTrackerRepo();
+    const items = [];
+    for (const id of ids) {
+        const issueNumber = parseGithubIssueNumber(id);
+        const result = await runExternalTrackerCommand([
+            "issue",
+            "view",
+            issueNumber,
+            "--repo",
+            repo,
+            "--json",
+            "id,number,title,body,state,stateReason,labels,assignees,updatedAt,url",
+        ]);
+        if (!result.ok) {
+            throw new Error(result.stderr.trim() || `GitHub issue view failed for ${id}.`);
+        }
+        items.push(normalizeGithubTrackerItem(readGithubJson(result.stdout, "GitHub issue view"), repo));
+    }
+    return items;
+}
+function readOrBuildExternalSnapshot() {
+    const loaded = loadTrackerSnapshot();
+    if (loaded.ok && loaded.snapshot)
+        return loaded.snapshot;
+    return buildDefaultTrackerSnapshot("external");
+}
+function upsertTrackerItem(snapshot, item) {
+    const items = [...snapshot.items];
+    const index = findItemIndex(snapshot, item.item_id);
+    if (index === -1) {
+        items.push(item);
+    }
+    else {
+        items[index] = item;
+    }
+    return {
+        ...snapshot,
+        adapter_kind: "external",
+        updated_at: item.updated_at,
+        items,
+    };
+}
+async function githubCreateComment(itemId, body) {
+    const issueNumber = parseGithubIssueNumber(itemId);
+    const repo = resolveExternalTrackerRepo();
+    const trimmedBody = body.trim();
+    if (!trimmedBody) {
+        return { ok: false, error: "Comment body must not be empty." };
+    }
+    const result = await runExternalTrackerCommand([
+        "issue",
+        "comment",
+        issueNumber,
+        "--repo",
+        repo,
+        "--body",
+        trimmedBody,
+    ]);
+    if (!result.ok) {
+        return {
+            ok: false,
+            error: result.stderr.trim() || `GitHub issue comment failed for ${itemId}.`,
+        };
+    }
+    try {
+        const snapshot = readOrBuildExternalSnapshot();
+        const issue = (await githubGetIssuesById([itemId]))[0] ??
+            normalizeTrackerItem({
+                item_id: `github:${repo}#${issueNumber}`,
+                external_id: issueNumber,
+                title: `GitHub issue ${issueNumber}`,
+                state: "open",
+                labels: [],
+                updated_at: new Date().toISOString(),
+                metadata: { provider: "github", repo, issue_number: issueNumber },
+            });
+        const now = new Date().toISOString();
+        const commentId = randomUUID();
+        const nextSnapshot = upsertTrackerItem(snapshot, issue);
+        nextSnapshot.comments = [
+            ...nextSnapshot.comments,
+            normalizeTrackerComment({
+                comment_id: commentId,
+                item_id: issue.item_id,
+                body: trimmedBody,
+                author: getExternalTrackerAuthor(),
+                created_at: now,
+                metadata: {
+                    provider: "github",
+                    repo,
+                    issue_number: issueNumber,
+                },
+            }),
+        ];
+        nextSnapshot.updated_at = now;
+        writeTrackerSnapshot(nextSnapshot);
+        emitTrackerEvent("TRACKER_COMMENT_CREATED", `Tracker comment created for ${issue.item_id}.`, {
+            adapter_kind: "external",
+            provider: "github",
+            item_id: issue.item_id,
+            comment_id: commentId,
+        });
+        return { ok: true, comment_id: commentId };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+async function githubUpdateItemState(itemId, state) {
+    const issueNumber = parseGithubIssueNumber(itemId);
+    const repo = resolveExternalTrackerRepo();
+    const nextState = state.trim().toLowerCase();
+    if (!nextState) {
+        return { ok: false, error: "Tracker state must not be empty." };
+    }
+    const action = ["closed", "done", "completed", "resolved"].includes(nextState)
+        ? "close"
+        : ["open", "opened", "reopened", "todo", "backlog", "in_progress"].includes(nextState)
+            ? "reopen"
+            : undefined;
+    if (!action) {
+        return {
+            ok: false,
+            error: `GitHub tracker only supports open/closed transitions, received "${state}".`,
+        };
+    }
+    const result = await runExternalTrackerCommand([
+        "issue",
+        action,
+        issueNumber,
+        "--repo",
+        repo,
+    ]);
+    if (!result.ok) {
+        return {
+            ok: false,
+            error: result.stderr.trim() || `GitHub issue ${action} failed for ${itemId}.`,
+        };
+    }
+    try {
+        const issue = (await githubGetIssuesById([itemId]))[0];
+        const snapshot = upsertTrackerItem(readOrBuildExternalSnapshot(), issue);
+        writeTrackerSnapshot(snapshot);
+        emitTrackerEvent("TRACKER_ITEM_STATE_UPDATED", `Tracker item ${issue.item_id} moved to ${issue.state}.`, {
+            adapter_kind: "external",
+            provider: "github",
+            item_id: issue.item_id,
+            state: issue.state,
+        });
+        return { ok: true };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+export function validateTrackerSnapshotContent(raw) {
+    try {
+        parseTrackerSnapshotContent(raw);
+        return { ok: true, schema: TRACKER_SNAPSHOT_SCHEMA_NAME };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            schema: TRACKER_SNAPSHOT_SCHEMA_NAME,
+            errors: [error instanceof Error ? error.message : String(error)],
+        };
+    }
+}
+export function loadTrackerSnapshot(explicitPath) {
+    const target = resolveTrackerSnapshotTarget(explicitPath);
+    if (!existsSync(target.path)) {
+        return {
+            ok: false,
+            schema: TRACKER_SNAPSHOT_SCHEMA_NAME,
+            path: target.path,
+            source: target.source,
+            errors: [`Tracker snapshot file not found: ${target.path}`],
+        };
+    }
+    try {
+        const raw = readFileSync(target.path, "utf-8");
+        const snapshot = parseTrackerSnapshotContent(raw);
+        return {
+            ok: true,
+            schema: TRACKER_SNAPSHOT_SCHEMA_NAME,
+            path: target.path,
+            source: target.source,
+            snapshot,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            schema: TRACKER_SNAPSHOT_SCHEMA_NAME,
+            path: target.path,
+            source: target.source,
+            errors: [error instanceof Error ? error.message : String(error)],
+        };
+    }
+}
+export function readTrackerSnapshot() {
+    const result = loadTrackerSnapshot();
+    if (result.ok && result.snapshot)
+        return result.snapshot;
+    throw new Error((result.errors ?? ["Tracker snapshot unavailable"]).join("; "));
+}
+export function getTrackerSnapshotPath() {
+    return resolveTrackerSnapshotTarget().path;
+}
+export function writeTrackerSnapshot(snapshot) {
+    const normalized = normalizeTrackerSnapshot(snapshot);
+    const validation = validateTrackerSnapshotPayload(normalized);
+    if (!validation.ok) {
+        throw new Error(`Tracker snapshot failed validation (${validation.schema}): ${validation.errors.join("; ")}`);
+    }
+    return safeWriteWorkspaceFile(TRACKER_SNAPSHOT_REL_PATH, JSON.stringify(normalized, null, 2));
+}
+const noneTrackerAdapter = {
+    kind: "none",
+    async healthCheck() {
+        return { ok: true, detail: "Tracker disabled via runtime profile." };
+    },
+    async listActiveItems() {
+        return [];
+    },
+    async getItemsById() {
+        return [];
+    },
+    async createComment() {
+        return {
+            ok: false,
+            error: "Tracker adapter 'none' does not support comment creation.",
+        };
+    },
+    async updateItemState() {
+        return {
+            ok: false,
+            error: "Tracker adapter 'none' does not support state updates.",
+        };
+    },
+};
+const externalTrackerAdapter = {
+    kind: "external",
+    async healthCheck() {
+        try {
+            const provider = resolveExternalTrackerProvider();
+            if (provider !== "github") {
+                return { ok: false, detail: `Unsupported external tracker provider: ${provider}` };
+            }
+            const repo = resolveExternalTrackerRepo();
+            const result = await runExternalTrackerCommand([
+                "issue",
+                "list",
+                "--repo",
+                repo,
+                "--state",
+                "all",
+                "--limit",
+                "1",
+                "--json",
+                "number",
+            ]);
+            return result.ok
+                ? { ok: true, detail: `GitHub tracker healthy for ${repo}.` }
+                : {
+                    ok: false,
+                    detail: result.stderr.trim() ||
+                        `GitHub tracker health check failed for ${repo} (exit ${result.exit_code ?? "?"}).`,
+                };
+        }
+        catch (error) {
+            return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+        }
+    },
+    async listActiveItems(filter) {
+        return githubListIssues(filter);
+    },
+    async getItemsById(ids) {
+        return githubGetIssuesById(ids);
+    },
+    async createComment(itemId, body) {
+        return githubCreateComment(itemId, body);
+    },
+    async updateItemState(itemId, state) {
+        return githubUpdateItemState(itemId, state);
+    },
+};
+const memoryTrackerAdapter = {
+    kind: "memory",
+    async healthCheck() {
+        try {
+            const snapshot = readTrackerSnapshot();
+            return {
+                ok: true,
+                detail: `Memory tracker snapshot loaded with ${snapshot.items.length} items.`,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                detail: error instanceof Error ? error.message : String(error),
+            };
+        }
+    },
+    async listActiveItems(filter) {
+        const snapshot = readTrackerSnapshot();
+        return filterTrackerItems(snapshot.items, filter);
+    },
+    async getItemsById(ids) {
+        const snapshot = readTrackerSnapshot();
+        return filterTrackerItems(snapshot.items, { ids });
+    },
+    async createComment(itemId, body) {
+        try {
+            const trimmedBody = body.trim();
+            if (!trimmedBody) {
+                return { ok: false, error: "Comment body must not be empty." };
+            }
+            const snapshot = readTrackerSnapshot();
+            const itemIndex = findItemIndex(snapshot, itemId);
+            if (itemIndex === -1) {
+                return { ok: false, error: `Tracker item not found: ${itemId}` };
+            }
+            const now = new Date().toISOString();
+            const comment = {
+                comment_id: randomUUID(),
+                item_id: snapshot.items[itemIndex].item_id,
+                body: trimmedBody,
+                author: getMemoryTrackerAuthor(),
+                created_at: now,
+                metadata: {
+                    adapter_kind: "memory",
+                },
+            };
+            const nextSnapshot = {
+                ...snapshot,
+                adapter_kind: "memory",
+                updated_at: now,
+                comments: [...snapshot.comments, comment],
+            };
+            writeTrackerSnapshot(nextSnapshot);
+            emitTrackerEvent("TRACKER_COMMENT_CREATED", `Tracker comment created for ${comment.item_id}.`, {
+                adapter_kind: "memory",
+                item_id: comment.item_id,
+                comment_id: comment.comment_id,
+            });
+            return { ok: true, comment_id: comment.comment_id };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    },
+    async updateItemState(itemId, state) {
+        try {
+            const nextState = state.trim();
+            if (!nextState) {
+                return { ok: false, error: "Tracker state must not be empty." };
+            }
+            const snapshot = readTrackerSnapshot();
+            const itemIndex = findItemIndex(snapshot, itemId);
+            if (itemIndex === -1) {
+                return { ok: false, error: `Tracker item not found: ${itemId}` };
+            }
+            const now = new Date().toISOString();
+            const items = [...snapshot.items];
+            items[itemIndex] = {
+                ...items[itemIndex],
+                state: nextState,
+                updated_at: now,
+                metadata: {
+                    ...items[itemIndex].metadata,
+                    adapter_kind: "memory",
+                },
+            };
+            const nextSnapshot = {
+                ...snapshot,
+                adapter_kind: "memory",
+                updated_at: now,
+                items,
+            };
+            writeTrackerSnapshot(nextSnapshot);
+            emitTrackerEvent("TRACKER_ITEM_STATE_UPDATED", `Tracker item ${items[itemIndex].item_id} moved to ${nextState}.`, {
+                adapter_kind: "memory",
+                item_id: items[itemIndex].item_id,
+                state: nextState,
+            });
+            return { ok: true };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    },
+};
+const TRACKER_ADAPTERS = {
+    none: noneTrackerAdapter,
+    memory: memoryTrackerAdapter,
+    external: externalTrackerAdapter,
+};
+export function listTrackerAdapterKinds() {
+    return Object.keys(TRACKER_ADAPTERS).sort((a, b) => a.localeCompare(b));
+}
+export function getTrackerAdapter(kind) {
+    return TRACKER_ADAPTERS[resolveTrackerAdapterKind(kind)];
+}
+export function buildDefaultTrackerSnapshot(kind = "none") {
+    return defaultTrackerSnapshot(kind);
+}
+//# sourceMappingURL=tracker-adapters.js.map