@voybio/ace-swarm 0.1.0

package/dist/handoff-registry.js

@@ -0,0 +1,422 @@
+import { resolveWorkspaceRoot, safeRead, safeWrite, wsPath, withFileLock } from "./helpers.js";
+import { isReadError } from "./shared.js";
+import { openStore } from "./store/ace-packed-store.js";
+import { VericifyProjector } from "./store/materializers/vericify-projector.js";
+import { HandoffRepository } from "./store/repositories/handoff-repository.js";
+import { getWorkspaceStorePath, listStoreKeysSync, readStoreJsonSync, storeExistsSync, } from "./store/store-snapshot.js";
+import { withStoreWriteQueue } from "./store/write-queue.js";
+const HANDOFF_REGISTRY_REL = "agent-state/handoff-registry.json";
+function workspaceRoot() {
+    return resolveWorkspaceRoot();
+}
+const TRANSITIONS = {
+    open: ["accepted", "blocked"],
+    accepted: ["blocked", "completed"],
+    blocked: ["accepted", "completed"],
+    completed: ["blocked"],
+};
+function defaultRegistry() {
+    const now = new Date().toISOString();
+    return {
+        version: 1,
+        updated_at: now,
+        handoffs: {},
+    };
+}
+function parseRegistry(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return undefined;
+        }
+        const candidate = parsed;
+        if (candidate.version !== 1 || !candidate.handoffs || typeof candidate.handoffs !== "object") {
+            return undefined;
+        }
+        const handoffs = {};
+        for (const [key, value] of Object.entries(candidate.handoffs)) {
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                continue;
+            const row = value;
+            if (typeof row.handoff_id !== "string" ||
+                typeof row.created_at !== "string" ||
+                typeof row.updated_at !== "string" ||
+                typeof row.from !== "string" ||
+                typeof row.to !== "string" ||
+                typeof row.title !== "string" ||
+                typeof row.status !== "string" ||
+                !Array.isArray(row.history)) {
+                continue;
+            }
+            const history = row.history.filter((event) => {
+                if (!event || typeof event !== "object" || Array.isArray(event))
+                    return false;
+                const e = event;
+                return (typeof e.timestamp_utc === "string" &&
+                    typeof e.status === "string" &&
+                    typeof e.actor === "string");
+            });
+            handoffs[key] = {
+                handoff_id: row.handoff_id,
+                created_at: row.created_at,
+                updated_at: row.updated_at,
+                from: row.from,
+                to: row.to,
+                title: row.title,
+                task_type: typeof row.task_type === "string" ? row.task_type : undefined,
+                priority: typeof row.priority === "string" ? row.priority : undefined,
+                source_file: typeof row.source_file === "string" ? row.source_file : undefined,
+                status: row.status === "open" ||
+                    row.status === "accepted" ||
+                    row.status === "blocked" ||
+                    row.status === "completed"
+                    ? row.status
+                    : "open",
+                history,
+            };
+        }
+        return {
+            version: 1,
+            updated_at: typeof candidate.updated_at === "string"
+                ? candidate.updated_at
+                : new Date().toISOString(),
+            handoffs,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function mapLegacyStatusToStore(status) {
+    switch (status) {
+        case "accepted":
+            return "acked";
+        case "completed":
+            return "closed";
+        case "blocked":
+            return "blocked";
+        default:
+            return "pending";
+    }
+}
+function mapStoreStatusToLegacy(status, metadata) {
+    if (metadata.legacy_status === "open" ||
+        metadata.legacy_status === "accepted" ||
+        metadata.legacy_status === "blocked" ||
+        metadata.legacy_status === "completed") {
+        return metadata.legacy_status;
+    }
+    switch (status) {
+        case "acked":
+        case "active":
+            return "accepted";
+        case "closed":
+            return "completed";
+        case "blocked":
+            return "blocked";
+        default:
+            return "open";
+    }
+}
+function normalizeHistory(value, fallbackStatus, updatedAt) {
+    if (!Array.isArray(value)) {
+        return [
+            {
+                timestamp_utc: updatedAt,
+                status: fallbackStatus,
+                actor: "store",
+            },
+        ];
+    }
+    const history = value.filter((event) => {
+        if (!event || typeof event !== "object" || Array.isArray(event))
+            return false;
+        const candidate = event;
+        return (typeof candidate.timestamp_utc === "string" &&
+            (candidate.status === "open" ||
+                candidate.status === "accepted" ||
+                candidate.status === "blocked" ||
+                candidate.status === "completed") &&
+            typeof candidate.actor === "string");
+    });
+    return history.length > 0
+        ? history
+        : [
+            {
+                timestamp_utc: updatedAt,
+                status: fallbackStatus,
+                actor: "store",
+            },
+        ];
+}
+function toLegacyHandoffRecord(record) {
+    const metadata = record.metadata && typeof record.metadata === "object" && !Array.isArray(record.metadata)
+        ? record.metadata
+        : {};
+    const createdAt = new Date(record.created_at).toISOString();
+    const updatedAt = new Date(record.updated_at).toISOString();
+    const status = mapStoreStatusToLegacy(record.status, metadata);
+    return {
+        handoff_id: record.id,
+        created_at: createdAt,
+        updated_at: updatedAt,
+        from: record.from_agent,
+        to: record.to_agent,
+        title: typeof metadata.title === "string" ? metadata.title : record.summary,
+        task_type: typeof metadata.task_type === "string" ? metadata.task_type : record.task,
+        priority: typeof metadata.priority === "string" ? metadata.priority : undefined,
+        source_file: typeof metadata.source_file === "string" ? metadata.source_file : undefined,
+        status,
+        history: normalizeHistory(metadata.history, status, updatedAt),
+    };
+}
+function readStoreBackedRegistry() {
+    const root = workspaceRoot();
+    if (!storeExistsSync(root))
+        return undefined;
+    const records = listStoreKeysSync(root, "state/handoffs/")
+        .map((key) => readStoreJsonSync(root, key))
+        .filter((record) => record !== undefined && record !== null && typeof record.id === "string")
+        .sort((left, right) => left.created_at - right.created_at);
+    const handoffs = Object.fromEntries(records.map((record) => {
+        const legacy = toLegacyHandoffRecord(record);
+        return [legacy.handoff_id, legacy];
+    }));
+    return {
+        version: 1,
+        updated_at: records.length
+            ? new Date(records[records.length - 1].updated_at).toISOString()
+            : new Date().toISOString(),
+        handoffs,
+    };
+}
+function writeRegistry(registry) {
+    registry.updated_at = new Date().toISOString();
+    return safeWrite(HANDOFF_REGISTRY_REL, JSON.stringify(registry, null, 2));
+}
+export function readHandoffRegistry() {
+    const storeRegistry = readStoreBackedRegistry();
+    if (storeRegistry)
+        return storeRegistry;
+    const raw = safeRead(HANDOFF_REGISTRY_REL);
+    if (isReadError(raw)) {
+        return defaultRegistry();
+    }
+    return parseRegistry(raw) ?? defaultRegistry();
+}
+export function registerHandoff(input) {
+    const registry = readHandoffRegistry();
+    const now = new Date().toISOString();
+    const actor = input.actor ?? "create_handoff";
+    const note = input.note ?? "created";
+    const existing = registry.handoffs[input.handoff_id];
+    if (existing) {
+        return {
+            record: existing,
+            path: wsPath(HANDOFF_REGISTRY_REL),
+            duplicate: true,
+        };
+    }
+    const record = {
+        handoff_id: input.handoff_id,
+        created_at: now,
+        updated_at: now,
+        from: input.from,
+        to: input.to,
+        title: input.title,
+        task_type: input.task_type,
+        priority: input.priority,
+        source_file: input.source_file,
+        status: "open",
+        history: [
+            {
+                timestamp_utc: now,
+                status: "open",
+                actor,
+                note,
+            },
+        ],
+    };
+    registry.handoffs[input.handoff_id] = record;
+    const path = writeRegistry(registry);
+    return { record, path };
+}
+export function acknowledgeHandoff(input) {
+    const registry = readHandoffRegistry();
+    const path = wsPath(HANDOFF_REGISTRY_REL);
+    const record = registry.handoffs[input.handoff_id];
+    if (!record) {
+        return {
+            ok: false,
+            path,
+            error: `handoff_id not found: ${input.handoff_id}`,
+        };
+    }
+    const previous = record.status;
+    if (previous !== input.status) {
+        const allowed = TRANSITIONS[previous];
+        if (!allowed.includes(input.status)) {
+            return {
+                ok: false,
+                path,
+                error: `invalid transition: ${previous} -> ${input.status}`,
+                allowed,
+                previous_status: previous,
+            };
+        }
+    }
+    const now = new Date().toISOString();
+    record.status = input.status;
+    record.updated_at = now;
+    record.history.push({
+        timestamp_utc: now,
+        status: input.status,
+        actor: input.actor ?? "ack_handoff",
+        note: input.note,
+    });
+    const writtenPath = writeRegistry(registry);
+    return {
+        ok: true,
+        path: writtenPath,
+        previous_status: previous,
+        record,
+    };
+}
+export function getHandoffRegistryPath() {
+    return wsPath(HANDOFF_REGISTRY_REL);
+}
+/**
+ * Concurrency-safe variant of registerHandoff.
+ */
+export async function registerHandoffSafe(input) {
+    const root = workspaceRoot();
+    const storePath = getWorkspaceStorePath(root);
+    if (!storeExistsSync(root)) {
+        return withFileLock(HANDOFF_REGISTRY_REL, () => registerHandoff(input));
+    }
+    return withFileLock(HANDOFF_REGISTRY_REL, async () => {
+        return withStoreWriteQueue(storePath, async () => {
+            const store = await openStore(storePath);
+            try {
+                const repo = new HandoffRepository(store);
+                const existing = await repo.get(input.handoff_id);
+                if (existing) {
+                    return {
+                        record: toLegacyHandoffRecord(existing),
+                        path: wsPath(HANDOFF_REGISTRY_REL),
+                        duplicate: true,
+                    };
+                }
+                const now = new Date().toISOString();
+                const record = await repo.create({
+                    id: input.handoff_id,
+                    from_agent: input.from,
+                    to_agent: input.to,
+                    status: "pending",
+                    summary: input.title,
+                    task: input.task_type,
+                    metadata: {
+                        legacy_status: "open",
+                        title: input.title,
+                        task_type: input.task_type,
+                        priority: input.priority,
+                        source_file: input.source_file,
+                        history: [
+                            {
+                                timestamp_utc: now,
+                                status: "open",
+                                actor: input.actor ?? "create_handoff",
+                                note: input.note ?? "created",
+                            },
+                        ],
+                    },
+                });
+                await store.commit();
+                const projector = new VericifyProjector(store, root);
+                await projector.projectHandoffs();
+                await store.commit();
+                return {
+                    record: toLegacyHandoffRecord(record),
+                    path: wsPath(HANDOFF_REGISTRY_REL),
+                };
+            }
+            finally {
+                await store.close();
+            }
+        });
+    });
+}
+/**
+ * Concurrency-safe variant of acknowledgeHandoff.
+ */
+export async function acknowledgeHandoffSafe(input) {
+    const root = workspaceRoot();
+    const storePath = getWorkspaceStorePath(root);
+    if (!storeExistsSync(root)) {
+        return withFileLock(HANDOFF_REGISTRY_REL, () => acknowledgeHandoff(input));
+    }
+    return withFileLock(HANDOFF_REGISTRY_REL, async () => {
+        return withStoreWriteQueue(storePath, async () => {
+            const store = await openStore(storePath);
+            try {
+                const repo = new HandoffRepository(store);
+                const current = await repo.get(input.handoff_id);
+                const path = wsPath(HANDOFF_REGISTRY_REL);
+                if (!current) {
+                    return {
+                        ok: false,
+                        path,
+                        error: `handoff_id not found: ${input.handoff_id}`,
+                    };
+                }
+                const currentLegacy = toLegacyHandoffRecord(current);
+                const previous = currentLegacy.status;
+                if (previous !== input.status) {
+                    const allowed = TRANSITIONS[previous];
+                    if (!allowed.includes(input.status)) {
+                        return {
+                            ok: false,
+                            path,
+                            error: `invalid transition: ${previous} -> ${input.status}`,
+                            allowed,
+                            previous_status: previous,
+                        };
+                    }
+                }
+                const metadata = current.metadata && typeof current.metadata === "object" && !Array.isArray(current.metadata)
+                    ? { ...current.metadata }
+                    : {};
+                const now = new Date().toISOString();
+                const history = normalizeHistory(metadata.history, previous, currentLegacy.updated_at);
+                history.push({
+                    timestamp_utc: now,
+                    status: input.status,
+                    actor: input.actor ?? "ack_handoff",
+                    note: input.note,
+                });
+                const updated = await repo.update(input.handoff_id, {
+                    status: mapLegacyStatusToStore(input.status),
+                    metadata: {
+                        ...metadata,
+                        legacy_status: input.status,
+                        history,
+                    },
+                });
+                await store.commit();
+                const projector = new VericifyProjector(store, root);
+                await projector.projectHandoffs();
+                await store.commit();
+                return {
+                    ok: true,
+                    path,
+                    previous_status: previous,
+                    record: toLegacyHandoffRecord(updated),
+                };
+            }
+            finally {
+                await store.close();
+            }
+        });
+    });
+}
+//# sourceMappingURL=handoff-registry.js.map

package/dist/helpers.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Shared helpers – path resolution, file I/O, artifact discovery, bootstrap.
+ */
+export { isInside, isReadError, normalizeRelPath, looksLikeSwarmHandoffPath } from "./shared.js";
+export declare const SERVER_ROOT: string;
+export declare const PACKAGE_ROOT: string;
+export declare function resolveWorkspaceRoot(): string;
+export declare const WORKSPACE_ROOT: string;
+export declare const DEFAULTS_ROOT: string;
+export declare const ACE_ROOT_REL = ".agents/ACE";
+export declare const ACE_SKILLS_ROOT_REL = ".agents/ACE/skills";
+export declare const ACE_TASKS_ROOT_REL = ".agents/ACE/tasks";
+export declare const ACE_SCRIPTS_ROOT_REL = ".agents/ACE/scripts/ace";
+export declare const ACE_BUNDLE_ROOT_REL = ".mcp-config";
+export declare const ACE_LLM_ROOT_REL = ".agents/ACE/.ace";
+export declare const ACE_VSCODE_ROOT_REL = ".vscode";
+export declare const ACE_CURSOR_ROOT_REL = ".cursor";
+export declare const ACE_CLAUDE_ROOT_REL = ".claude";
+export declare const ACE_GITHUB_ROOT_REL = ".github";
+export declare const ACE_HOST_AGENTS_REL = "AGENTS.md";
+export declare const ACE_HOST_CLAUDE_REL = "CLAUDE.md";
+export declare const ACE_HOST_CURSOR_RULES_REL = ".cursorrules";
+export declare const ALL_MCP_CLIENTS: readonly ["codex", "vscode", "claude", "cursor", "antigravity"];
+export type McpClient = (typeof ALL_MCP_CLIENTS)[number];
+export declare const ALL_LLM_PROVIDERS: readonly ["ollama", "llama.cpp"];
+export type LlmProvider = (typeof ALL_LLM_PROVIDERS)[number];
+export declare const ALL_AGENTS: readonly ["orchestrator", "vos", "ui", "coders", "astgrep", "skeptic", "ops", "research", "spec", "builder", "qa", "docs", "memory", "security", "observability", "eval", "release"];
+export type AgentRole = (typeof ALL_AGENTS)[number];
+export declare const SWARM_AGENTS: readonly ["orchestrator", "vos", "ui", "coders"];
+export type SwarmAgentRole = (typeof SWARM_AGENTS)[number];
+export declare const COMPOSABLE_AGENTS: readonly ["astgrep", "skeptic", "ops", "research", "spec", "builder", "qa", "docs", "memory", "security", "observability", "eval", "release"];
+export type ComposableAgentRole = (typeof COMPOSABLE_AGENTS)[number];
+export declare const SWARM_SUBAGENT_MAP: Record<SwarmAgentRole, readonly ComposableAgentRole[]>;
+export type TaskKey = "todo" | "role_tasks" | "cli_work_split" | "lessons" | "readme" | "handoff_template" | "handoff_example" | "handoff_example_vos_ui" | "handoff_example_ui_coders";
+export type KernelKey = "directive_kernel" | "agent_registry";
+export declare const AGENT_FILES: Record<AgentRole, string[]>;
+export declare const AGENT_MANIFEST_FILES: Record<AgentRole, string[]>;
+export declare const TASK_FILES: Record<TaskKey, string[]>;
+export declare const KERNEL_FILES: Record<KernelKey, string[]>;
+export type ArtifactSource = "workspace" | "package-defaults" | "store" | "missing";
+export interface SkillReference {
+    name: string;
+    path: string;
+    source: "workspace" | "package-defaults" | "store";
+}
+export interface BootstrapOptions {
+    projectName?: string;
+    force?: boolean;
+    includeMcpConfig?: boolean;
+    includeClientConfigBundle?: boolean;
+    llmProvider?: LlmProvider;
+    llmModel?: string;
+    llmBaseUrl?: string;
+    ollamaModel?: string;
+    ollamaBaseUrl?: string;
+    /**
+     * When true, skip copying store-managed trees (tasks, agent-state, skills,
+     * and the .agents/ACE defaults tree). Pass this when bootstrapStoreWorkspace()
+     * has already run so the store is authoritative for those paths.
+     */
+    skipStoreManaged?: boolean;
+}
+export interface BootstrapResult {
+    created: string[];
+    updated: string[];
+    skipped: string[];
+}
+export declare function mapAceWorkspaceRelativePath(path: string): string;
+export declare function acePath(...segments: string[]): string;
+export declare function wsPath(...segments: string[]): string;
+/** Normalize a path for validation: workspace-relative, forward slashes. */
+export declare function normalizePathForValidation(path: string): string;
+/** Check if a role is a swarm agent (vs composable). */
+export declare function isSwarmRole(role: string): role is (typeof SWARM_AGENTS)[number];
+/** Atomically write a file via tmp + rename to prevent partial writes. */
+export declare function atomicWrite(filePath: string, content: string): string;
+/** Check if a file exists. Relative paths are workspace-relative. */
+export declare function fileExists(filePath: string): boolean;
+export declare function resolveWorkspaceWritePath(filePath: string): string;
+export declare function resolveWorkspaceReadPath(filePath: string): string;
+export declare function resolveWorkspaceArtifactPath(filePath: string, mode?: "read" | "write"): string;
+export declare function classifyPathSource(path?: string): ArtifactSource;
+/** Safely read a workspace file, returning either text or a not-found/access message. */
+export declare function safeRead(filePath: string): string;
+/** Safely write a workspace file atomically (tmp + rename), creating directories if needed. */
+export declare function safeWrite(filePath: string, content: string): string;
+/**
+ * Execute `fn` while holding a per-path serialization lock.
+ * Prevents concurrent read-modify-write cycles on the same file
+ * within a single process. Cross-process safety relies on atomic rename.
+ */
+export declare function withFileLock<T>(path: string, fn: () => T | Promise<T>): Promise<T>;
+export declare function getAgentInstructionPath(role: AgentRole): string | undefined;
+export declare function getAgentManifestPath(role: AgentRole): string | undefined;
+export declare function readAgentInstructions(role: AgentRole): string;
+export declare function readAgentManifest(role: AgentRole): string;
+export declare function getTaskArtifactPath(key: TaskKey): string | undefined;
+export declare function readTaskArtifact(key: TaskKey): string;
+export declare function getKernelArtifactPath(key: KernelKey): string | undefined;
+export declare function readKernelArtifact(key: KernelKey): string;
+export declare function resolveWritableTaskPath(key: TaskKey): string;
+export declare function listAvailableSkills(): SkillReference[];
+export declare function getSkillPath(name: string): string | undefined;
+export declare function readSkillInstructions(name: string): string;
+export declare function getMcpClientBundlePath(client: McpClient): string;
+export declare function getMcpClientInstallHint(client: McpClient): string;
+export declare function getMcpServerConfigSnippet(client?: McpClient): string;
+export declare function getAllMcpServerConfigSnippets(): Record<McpClient, string>;
+export declare function bootstrapAceWorkspace(options?: BootstrapOptions): BootstrapResult;
+export interface DriftEntry {
+    asset_path: string;
+    runtime_path: string;
+    status: "match" | "drift" | "missing-runtime" | "missing-asset";
+}
+export interface DriftReport {
+    checked: number;
+    drifted: number;
+    missing_runtime: number;
+    entries: DriftEntry[];
+}
+/**
+ * Compare packaged assets against runtime workspace copies.
+ * Detects silent divergence between authoritative defaults and live state.
+ */
+export declare function detectAssetDrift(): DriftReport;
+//# sourceMappingURL=helpers.d.ts.map