@voybio/ace-swarm 0.1.0

package/dist/skill-catalog.js

@@ -0,0 +1,305 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { basename, dirname, extname, relative, resolve } from "node:path";
+import { ALL_MCP_CLIENTS, listAvailableSkills, readSkillInstructions, } from "./helpers.js";
+import { listStoreKeysByPathSync, parseVirtualStorePath, readStoreBlobByPathSync, readVirtualStorePathSync, toVirtualStorePath, } from "./store/store-snapshot.js";
+function stripQuotes(value) {
+    return value.replace(/^["']+|["']+$/g, "").trim();
+}
+function parseSimpleYamlBlock(raw) {
+    const result = {};
+    const lines = raw.replace(/\r\n/g, "\n").split("\n");
+    let currentKey;
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        const keyMatch = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (keyMatch) {
+            currentKey = keyMatch[1];
+            result[currentKey] = stripQuotes(keyMatch[2] ?? "");
+            continue;
+        }
+        if (currentKey && /^[ \t]+/.test(line)) {
+            const nextValue = stripQuotes(line.trim());
+            result[currentKey] = result[currentKey]
+                ? `${result[currentKey]} ${nextValue}`.trim()
+                : nextValue;
+        }
+    }
+    return result;
+}
+export function parseSkillFrontmatter(raw) {
+    const normalized = raw.replace(/\r\n/g, "\n");
+    if (!normalized.startsWith("---\n")) {
+        return { attributes: {}, body: normalized, has_frontmatter: false };
+    }
+    const endIndex = normalized.indexOf("\n---\n", 4);
+    if (endIndex === -1) {
+        return { attributes: {}, body: normalized, has_frontmatter: false };
+    }
+    const frontmatter = normalized.slice(4, endIndex);
+    const body = normalized.slice(endIndex + 5);
+    return {
+        attributes: parseSimpleYamlBlock(frontmatter),
+        body,
+        has_frontmatter: true,
+    };
+}
+function extractHeadings(markdown) {
+    return [...markdown.matchAll(/^##\s+(.+)$/gm)].map((match) => match[1].trim());
+}
+function normalizeHeading(heading) {
+    return heading
+        .toLowerCase()
+        .replace(/[`*_]/g, "")
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim();
+}
+function hasHeading(headings, terms) {
+    return headings.some((heading) => terms.some((term) => heading.includes(term)));
+}
+function bodyMentionsAny(markdown, terms) {
+    const text = markdown.toLowerCase();
+    return terms.some((term) => text.includes(term));
+}
+function descriptionLooksTriggerAware(description) {
+    const text = description.toLowerCase();
+    return [
+        "when the user",
+        "use when",
+        "use this",
+        "trigger when",
+        "asks for",
+        "when a task",
+    ].some((term) => text.includes(term));
+}
+function hasValidationSurface(markdown, headings) {
+    return (hasHeading(headings, ["validation", "verify", "verification", "test", "tests", "canary"]) ||
+        bodyMentionsAny(markdown, [
+            "validation command",
+            "expected evidence",
+            "trigger canary",
+            "functional canary",
+            "baseline comparison",
+            "verify by",
+            "run this check",
+        ]));
+}
+function hasPortabilityNotes(markdown, headings) {
+    return (hasHeading(headings, [
+        "compatibility",
+        "portability",
+        "portable",
+        "cross platform",
+        "cross-platform",
+        "client adapters",
+        "adapter policy",
+    ]) ||
+        bodyMentionsAny(markdown, [
+            "portable source of truth",
+            "portable contract",
+            "portable skill",
+            "vendor-neutral",
+            "cross-platform",
+            "cross platform",
+            "client-specific",
+            "optional overlay",
+            "optional adapter",
+            "works without",
+        ]));
+}
+function resolveOpenAiYamlPath(skillPath) {
+    const parsed = parseVirtualStorePath(skillPath);
+    if (parsed) {
+        const parts = parsed.key.split("/");
+        const skillName = parts[2] ?? "";
+        const key = `knowledge/skills/${skillName}/agents/openai.yaml`;
+        return readStoreBlobByPathSync(parsed.storePath, key)
+            ? toVirtualStorePath(parsed.storePath, key)
+            : undefined;
+    }
+    const agentsPath = resolve(dirname(skillPath), "agents", "openai.yaml");
+    return existsSync(agentsPath) ? agentsPath : undefined;
+}
+const KNOWN_ADAPTER_CLIENTS = [...ALL_MCP_CLIENTS, "openai", "vscode"];
+const ADAPTER_EXTENSIONS = new Set([".yaml", ".yml", ".json", ".jsonc", ".toml", ".md"]);
+function detectAdapterClient(relativePath) {
+    const lower = relativePath.toLowerCase();
+    for (const client of KNOWN_ADAPTER_CLIENTS) {
+        if (lower.includes(client))
+            return client;
+    }
+    const stem = basename(lower, extname(lower)).replace(/[^a-z0-9]+/g, "-");
+    return stem || "generic";
+}
+function listSkillAdapterOverlays(skillPath) {
+    const parsed = parseVirtualStorePath(skillPath);
+    if (parsed) {
+        const skillName = parsed.key.split("/")[2] ?? "";
+        const prefix = `knowledge/skills/${skillName}/agents/`;
+        return listStoreKeysByPathSync(parsed.storePath, prefix)
+            .filter((key) => key.toLowerCase() !== `${prefix}readme.md`)
+            .filter((key) => ADAPTER_EXTENSIONS.has(extname(key).toLowerCase()))
+            .map((key) => {
+            const relativePath = key.slice(prefix.length);
+            return {
+                client: detectAdapterClient(relativePath),
+                format: extname(relativePath).slice(1) || "unknown",
+                path: toVirtualStorePath(parsed.storePath, key),
+                relative_path: relativePath,
+            };
+        })
+            .sort((a, b) => a.relative_path.localeCompare(b.relative_path));
+    }
+    const agentsRoot = resolve(dirname(skillPath), "agents");
+    if (!existsSync(agentsRoot))
+        return [];
+    const overlays = [];
+    const walk = (dirPath) => {
+        const entries = readdirSync(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name.startsWith("."))
+                continue;
+            const absolutePath = resolve(dirPath, entry.name);
+            if (entry.isDirectory()) {
+                walk(absolutePath);
+                continue;
+            }
+            const extension = extname(entry.name).toLowerCase();
+            const relativePath = relative(agentsRoot, absolutePath).replace(/\\/g, "/");
+            if (!ADAPTER_EXTENSIONS.has(extension))
+                continue;
+            if (relativePath.toLowerCase() === "readme.md")
+                continue;
+            overlays.push({
+                client: detectAdapterClient(relativePath),
+                format: extension.slice(1) || "unknown",
+                path: absolutePath,
+                relative_path: relativePath,
+            });
+        }
+    };
+    walk(agentsRoot);
+    return overlays.sort((a, b) => a.relative_path.localeCompare(b.relative_path));
+}
+export function readSkillCatalogEntry(skill) {
+    const raw = skill.source === "store" || !existsSync(skill.path)
+        ? readVirtualStorePathSync(skill.path) ?? readSkillInstructions(skill.name)
+        : readFileSync(skill.path, "utf-8");
+    const parsed = parseSkillFrontmatter(raw);
+    const headings = extractHeadings(parsed.body);
+    const normalizedHeadings = headings.map(normalizeHeading);
+    const fileBacked = existsSync(skill.path);
+    const openaiYamlPath = resolveOpenAiYamlPath(skill.path);
+    const openaiMetadata = openaiYamlPath
+        ? parseSimpleYamlBlock(fileBacked && existsSync(openaiYamlPath)
+            ? readFileSync(openaiYamlPath, "utf-8")
+            : readVirtualStorePathSync(openaiYamlPath) ?? "")
+        : {};
+    const adapterOverlays = listSkillAdapterOverlays(skill.path);
+    const adapterOverlayClients = [...new Set(adapterOverlays.map((overlay) => overlay.client))];
+    const hasReferencesDir = fileBacked
+        ? existsSync(resolve(dirname(skill.path), "references"))
+        : (() => {
+            const parsed = parseVirtualStorePath(skill.path);
+            if (!parsed)
+                return false;
+            const skillName = parsed.key.split("/")[2] ?? "";
+            return listStoreKeysByPathSync(parsed.storePath, `knowledge/skills/${skillName}/references/`).length > 0;
+        })();
+    return {
+        ...skill,
+        description: parsed.attributes.description?.trim() ?? "",
+        headings,
+        normalized_headings: normalizedHeadings,
+        line_count: raw.replace(/\r\n/g, "\n").split("\n").length,
+        has_frontmatter: parsed.has_frontmatter,
+        has_openai_yaml: Boolean(openaiYamlPath),
+        openai_yaml_path: openaiYamlPath,
+        openai_metadata: openaiMetadata,
+        has_inputs_section: hasHeading(normalizedHeadings, ["inputs", "input"]),
+        has_workflow_section: hasHeading(normalizedHeadings, [
+            "workflow",
+            "steps",
+            "process",
+            "procedure",
+        ]),
+        has_outputs_section: hasHeading(normalizedHeadings, [
+            "outputs",
+            "output",
+            "artifacts",
+            "resulting artifacts",
+        ]),
+        has_failure_policy: hasHeading(normalizedHeadings, [
+            "failure",
+            "troubleshooting",
+            "fallback",
+        ]),
+        has_use_cases_section: hasHeading(normalizedHeadings, [
+            "use cases",
+            "canonical use cases",
+            "examples",
+        ]),
+        has_references_dir: hasReferencesDir,
+        has_validation_surface: hasValidationSurface(parsed.body, normalizedHeadings),
+        has_portability_notes: hasPortabilityNotes(parsed.body, normalizedHeadings),
+        has_optional_adapters: adapterOverlays.length > 0,
+        adapter_overlay_clients: adapterOverlayClients,
+        adapter_overlays: adapterOverlays,
+    };
+}
+export function listSkillCatalogEntries() {
+    return listAvailableSkills().map((skill) => readSkillCatalogEntry(skill));
+}
+export function summarizeSkillCatalog(entries = listSkillCatalogEntries()) {
+    const longSkills = entries
+        .filter((entry) => entry.line_count > 500)
+        .map((entry) => ({ name: entry.name, line_count: entry.line_count }));
+    const missingCoreSections = entries
+        .filter((entry) => !entry.has_inputs_section ||
+        !entry.has_workflow_section ||
+        !entry.has_outputs_section ||
+        !entry.has_failure_policy)
+        .map((entry) => entry.name);
+    const missingUseCases = entries
+        .filter((entry) => !entry.has_use_cases_section)
+        .map((entry) => entry.name);
+    const missingValidationSurface = entries
+        .filter((entry) => !entry.has_validation_surface)
+        .map((entry) => entry.name);
+    const missingPortabilityNotes = entries
+        .filter((entry) => !entry.has_portability_notes)
+        .map((entry) => entry.name);
+    const progressiveDisclosureGaps = entries
+        .filter((entry) => entry.line_count > 500 && !entry.has_references_dir)
+        .map((entry) => entry.name);
+    const adapterClients = [...new Set(entries.flatMap((entry) => entry.adapter_overlay_clients))].sort((a, b) => a.localeCompare(b));
+    const portableContractReadySkills = entries.filter((entry) => entry.has_frontmatter &&
+        descriptionLooksTriggerAware(entry.description) &&
+        entry.has_use_cases_section &&
+        entry.has_inputs_section &&
+        entry.has_workflow_section &&
+        entry.has_outputs_section &&
+        entry.has_failure_policy).length;
+    return {
+        total_skills: entries.length,
+        with_openai_yaml: entries.filter((entry) => entry.has_openai_yaml).length,
+        with_adapter_overlays: entries.filter((entry) => entry.has_optional_adapters).length,
+        adapter_clients: adapterClients,
+        with_frontmatter: entries.filter((entry) => entry.has_frontmatter).length,
+        trigger_aware_descriptions: entries.filter((entry) => descriptionLooksTriggerAware(entry.description)).length,
+        with_validation_surface: entries.filter((entry) => entry.has_validation_surface).length,
+        with_portability_notes: entries.filter((entry) => entry.has_portability_notes).length,
+        portable_contract_ready_skills: portableContractReadySkills,
+        long_skills: longSkills,
+        skills_missing_core_sections: missingCoreSections,
+        skills_missing_use_cases: missingUseCases,
+        skills_missing_validation_surface: missingValidationSurface,
+        skills_missing_portability_notes: missingPortabilityNotes,
+        progressive_disclosure_gaps: progressiveDisclosureGaps,
+    };
+}
+export function findSkillCatalogEntry(name, entries = listSkillCatalogEntries()) {
+    const target = name.trim().toLowerCase();
+    return entries.find((entry) => entry.name.toLowerCase() === target);
+}
+//# sourceMappingURL=skill-catalog.js.map

package/dist/status-events.d.ts

@@ -0,0 +1,40 @@
+export declare const STATUS_EVENTS_REL_PATH = "agent-state/STATUS_EVENTS.ndjson";
+export type StatusEventStatus = "started" | "in_progress" | "pass" | "fail" | "blocked" | "done";
+export interface AppendStatusEventInput {
+    source_module: string;
+    event_type: string;
+    status: StatusEventStatus;
+    summary: string;
+    payload?: Record<string, unknown>;
+    trace_id?: string;
+    objective_id?: string;
+    decision_id?: string;
+}
+export interface StatusEventRecord {
+    schema_version: "1.0.0";
+    event_id: string;
+    trace_id: string;
+    timestamp: string;
+    source_module: string;
+    event_type: string;
+    status: StatusEventStatus;
+    objective_id?: string;
+    decision_id?: string;
+    payload: Record<string, unknown>;
+}
+export declare function waitForPendingStatusEventMirrors(): Promise<void>;
+export declare function appendStatusEvent(input: AppendStatusEventInput): {
+    path: string;
+    event: StatusEventRecord;
+};
+/**
+ * Concurrency-safe variant of appendStatusEvent.
+ * Use this from async tool handlers where parallel subagents may fire.
+ */
+export declare function appendStatusEventSafe(input: AppendStatusEventInput): Promise<{
+    path: string;
+    event: StatusEventRecord;
+}>;
+export declare function readStatusEvents(limit?: number): StatusEventRecord[];
+export declare function getStatusEventsPath(): string;
+//# sourceMappingURL=status-events.d.ts.map

package/dist/status-events.js

@@ -0,0 +1,269 @@
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { resolveWorkspaceRoot, resolveWorkspaceArtifactPath as resolveWorkspaceArtifactPathHelper, safeRead, safeWrite, } from "./helpers.js";
+import { isReadError } from "./shared.js";
+import { validateStatusEventPayload, PROVENANCE_CRITICAL_EVENT_TYPES } from "./schemas.js";
+import { openStore } from "./store/ace-packed-store.js";
+import { VericifyProjector } from "./store/materializers/vericify-projector.js";
+import { TrackerRepository } from "./store/repositories/tracker-repository.js";
+import { getWorkspaceStorePath, listStoreKeysSync, readStoreJsonSync, storeExistsSync, } from "./store/store-snapshot.js";
+import { operationalArtifactVirtualPath } from "./store/store-artifacts.js";
+import { withStoreWriteQueue } from "./store/write-queue.js";
+export const STATUS_EVENTS_REL_PATH = "agent-state/STATUS_EVENTS.ndjson";
+const STATUS_EVENTS_ARCHIVE_REL = "agent-state/STATUS_EVENTS-archive.ndjson";
+const MAX_EVENT_LINES = 2000;
+const _fileLocks = new Map();
+let trackerMirrorChain = Promise.resolve();
+function workspaceRoot() {
+    return resolveWorkspaceRoot();
+}
+function buildStatusEvent(input) {
+    return {
+        schema_version: "1.0.0",
+        event_id: randomUUID(),
+        trace_id: input.trace_id ?? randomUUID(),
+        timestamp: new Date().toISOString(),
+        source_module: input.source_module,
+        event_type: input.event_type,
+        status: input.status,
+        objective_id: input.objective_id,
+        decision_id: input.decision_id,
+        payload: {
+            summary: input.summary,
+            ...(input.payload ?? {}),
+        },
+    };
+}
+function validateStatusEvent(event) {
+    const isProvenanceCritical = PROVENANCE_CRITICAL_EVENT_TYPES.has(event.event_type);
+    const validation = validateStatusEventPayload(event, {
+        provenanceCritical: isProvenanceCritical,
+    });
+    if (!validation.ok) {
+        throw new Error(`Status event failed validation (${validation.schema}): ${validation.errors.join("; ")}`);
+    }
+}
+function resolveWorkspaceArtifactPath(filePath) {
+    return resolveWorkspaceArtifactPathHelper(filePath, "write");
+}
+function safeReadWorkspaceFile(filePath) {
+    return safeRead(filePath);
+}
+function safeWriteWorkspaceFile(filePath, content) {
+    return safeWrite(filePath, content);
+}
+async function withDynamicFileLock(path, fn) {
+    const key = resolveWorkspaceArtifactPath(path);
+    const prev = _fileLocks.get(key) ?? Promise.resolve();
+    let releaseLock;
+    const next = new Promise((resolveLock) => {
+        releaseLock = resolveLock;
+    });
+    _fileLocks.set(key, next);
+    await prev;
+    try {
+        return await fn();
+    }
+    finally {
+        releaseLock();
+        if (_fileLocks.get(key) === next)
+            _fileLocks.delete(key);
+    }
+}
+function readExistingNdjson() {
+    const existing = safeReadWorkspaceFile(STATUS_EVENTS_REL_PATH);
+    if (isReadError(existing)) {
+        return "";
+    }
+    return existing.trimEnd();
+}
+function rotateIfNeeded(content) {
+    const lines = content.split("\n").filter((l) => l.trim().length > 0);
+    if (lines.length <= MAX_EVENT_LINES)
+        return content;
+    const excess = lines.splice(0, lines.length - MAX_EVENT_LINES);
+    const archiveContent = excess.join("\n") + "\n";
+    const existingArchive = safeReadWorkspaceFile(STATUS_EVENTS_ARCHIVE_REL);
+    const archiveFull = isReadError(existingArchive)
+        ? archiveContent
+        : existingArchive.trimEnd() + "\n" + archiveContent;
+    safeWriteWorkspaceFile(STATUS_EVENTS_ARCHIVE_REL, archiveFull);
+    return lines.join("\n") + "\n";
+}
+async function mirrorStatusEventToStore(event) {
+    const root = workspaceRoot();
+    const storePath = getWorkspaceStorePath(root);
+    if (!existsSync(storePath))
+        return;
+    await withStoreWriteQueue(storePath, async () => {
+        const store = await openStore(storePath);
+        try {
+            const tracker = new TrackerRepository(store);
+            await tracker.emit({
+                kind: event.event_type,
+                agent: event.source_module,
+                summary: typeof event.payload.summary === "string"
+                    ? event.payload.summary
+                    : event.event_type,
+                metadata: {
+                    ...event.payload,
+                    status: event.status,
+                    trace_id: event.trace_id,
+                    objective_id: event.objective_id,
+                    decision_id: event.decision_id,
+                    event_id: event.event_id,
+                },
+            });
+            await store.commit();
+            const projector = new VericifyProjector(store, root);
+            await projector.projectStatusEvents();
+            await store.commit();
+        }
+        finally {
+            await store.close();
+        }
+    });
+}
+function scheduleStatusEventMirror(event) {
+    const snapshot = JSON.parse(JSON.stringify(event));
+    trackerMirrorChain = trackerMirrorChain
+        .catch(() => { })
+        .then(() => mirrorStatusEventToStore(snapshot))
+        .catch(() => { });
+}
+export async function waitForPendingStatusEventMirrors() {
+    await trackerMirrorChain.catch(() => { });
+}
+async function appendStatusEventStoreBacked(event) {
+    const root = workspaceRoot();
+    const storePath = getWorkspaceStorePath(root);
+    return withStoreWriteQueue(storePath, async () => {
+        const store = await openStore(storePath);
+        try {
+            const tracker = new TrackerRepository(store);
+            await tracker.emit({
+                kind: event.event_type,
+                agent: event.source_module,
+                summary: typeof event.payload.summary === "string"
+                    ? event.payload.summary
+                    : event.event_type,
+                metadata: {
+                    ...event.payload,
+                    status: event.status,
+                    trace_id: event.trace_id,
+                    objective_id: event.objective_id,
+                    decision_id: event.decision_id,
+                    event_id: event.event_id,
+                },
+            });
+            await store.commit();
+            const projector = new VericifyProjector(store, root);
+            await projector.projectStatusEvents();
+            await store.commit();
+            return {
+                path: operationalArtifactVirtualPath(root, STATUS_EVENTS_REL_PATH),
+                event,
+            };
+        }
+        finally {
+            await store.close();
+        }
+    });
+}
+export function appendStatusEvent(input) {
+    const event = buildStatusEvent(input);
+    validateStatusEvent(event);
+    // Atomic append under file lock to prevent lost writes under parallelism
+    const existing = readExistingNdjson();
+    const line = JSON.stringify(event);
+    const combined = existing.length > 0 ? `${existing}\n${line}\n` : `${line}\n`;
+    const next = rotateIfNeeded(combined);
+    const path = safeWriteWorkspaceFile(STATUS_EVENTS_REL_PATH, next);
+    scheduleStatusEventMirror(event);
+    return { path, event };
+}
+/**
+ * Concurrency-safe variant of appendStatusEvent.
+ * Use this from async tool handlers where parallel subagents may fire.
+ */
+export async function appendStatusEventSafe(input) {
+    return withDynamicFileLock(STATUS_EVENTS_REL_PATH, async () => {
+        const event = buildStatusEvent(input);
+        validateStatusEvent(event);
+        if (storeExistsSync(workspaceRoot())) {
+            return appendStatusEventStoreBacked(event);
+        }
+        return appendStatusEvent(input);
+    });
+}
+function mapStoreTrackerEvent(record) {
+    const metadata = record.metadata ?? {};
+    const status = typeof metadata.status === "string" &&
+        ["started", "in_progress", "pass", "fail", "blocked", "done"].includes(metadata.status)
+        ? metadata.status
+        : "in_progress";
+    const payload = { ...metadata };
+    delete payload.status;
+    delete payload.trace_id;
+    delete payload.objective_id;
+    delete payload.decision_id;
+    delete payload.event_id;
+    if (typeof payload.summary !== "string") {
+        payload.summary = record.summary;
+    }
+    return {
+        schema_version: "1.0.0",
+        event_id: typeof metadata.event_id === "string" ? metadata.event_id : record.id,
+        trace_id: typeof metadata.trace_id === "string" ? metadata.trace_id : record.id,
+        timestamp: new Date(record.ts).toISOString(),
+        source_module: record.agent ?? "system",
+        event_type: record.kind,
+        status,
+        objective_id: typeof metadata.objective_id === "string" ? metadata.objective_id : undefined,
+        decision_id: typeof metadata.decision_id === "string" ? metadata.decision_id : undefined,
+        payload,
+    };
+}
+function readStoreBackedStatusEvents(limit) {
+    const root = workspaceRoot();
+    if (!storeExistsSync(root))
+        return [];
+    const records = listStoreKeysSync(root, "state/tracker/")
+        .filter((key) => key !== "state/tracker/__seq")
+        .map((key) => readStoreJsonSync(root, key))
+        .filter((entry) => Boolean(entry))
+        .sort((a, b) => a.ts - b.ts);
+    return records.slice(Math.max(0, records.length - limit)).map(mapStoreTrackerEvent);
+}
+export function readStatusEvents(limit = 100) {
+    const storeEvents = readStoreBackedStatusEvents(limit);
+    if (storeEvents.length > 0) {
+        return storeEvents;
+    }
+    const raw = safeReadWorkspaceFile(STATUS_EVENTS_REL_PATH);
+    if (raw.startsWith("[FILE NOT FOUND]") || raw.startsWith("[ACCESS DENIED]")) {
+        return [];
+    }
+    const lines = raw
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    const parsed = [];
+    for (const line of lines.slice(Math.max(0, lines.length - limit))) {
+        try {
+            const row = JSON.parse(line);
+            parsed.push(row);
+        }
+        catch {
+            // Ignore malformed legacy rows; validation is enforced on future appends.
+        }
+    }
+    return parsed;
+}
+export function getStatusEventsPath() {
+    if (storeExistsSync(workspaceRoot())) {
+        return operationalArtifactVirtualPath(workspaceRoot(), STATUS_EVENTS_REL_PATH);
+    }
+    return resolveWorkspaceArtifactPath(STATUS_EVENTS_REL_PATH);
+}
+//# sourceMappingURL=status-events.js.map

package/dist/store/ace-packed-store.d.ts

@@ -0,0 +1,69 @@
+/**
+ * AcePackedStore
+ *
+ * Custom single-file store that implements Zarrita's AsyncReadable + AsyncWritable
+ * interfaces over a packed binary file at `.agents/ACE/ace-state.zarr`.
+ *
+ * File format:
+ *   [ Header  64 bytes ]   magic(8) version(4) flags(4) index_offset(8) index_length(8) reserved(32)
+ *   [ Chunk region     ]   chunk_0: [uint32 length][bytes] ... chunk_N: [uint32 length][bytes]
+ *   [ Index region     ]   UTF-8 JSON: { key → { offset, length } }
+ *
+ * Write protocol:
+ *   1. Append new chunk to end of chunk region.
+ *   2. Update in-memory index.
+ *   3. On commit(): rewrite index region → update header → fsync.
+ *
+ * Compaction:
+ *   Write live chunks to temp file → validate → atomic rename.
+ *
+ * Locking:
+ *   Advisory flock-style via a `.lock` sidecar file (PID + timestamp).
+ *   Stale detection: lock held >30s and PID not alive → break lock.
+ */
+import { IAcePackedStore, UnifiedEntry, EntryFilter, TopologyEntry, ContentSourceCode } from "./types.js";
+export declare class AcePackedStore implements IAcePackedStore {
+    private storePath;
+    private lockPath;
+    private readOnly;
+    private index;
+    private chunkEnd;
+    private fh;
+    private dirty;
+    private entryCounter;
+    open(path: string, opts?: {
+        readOnly?: boolean;
+    }): Promise<void>;
+    private _initNewStore;
+    private _loadExistingStore;
+    commit(): Promise<void>;
+    compact(): Promise<void>;
+    close(): Promise<void>;
+    get(key: string): Promise<Uint8Array | undefined>;
+    set(key: string, value: Uint8Array): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    list(): AsyncGenerator<string>;
+    getJSON<T>(key: string): Promise<T | undefined>;
+    setJSON(key: string, value: unknown): Promise<void>;
+    getBlob(key: string): Promise<string | undefined>;
+    setBlob(key: string, content: string): Promise<void>;
+    appendEntry(entry: Omit<UnifiedEntry, "id" | "ts">): Promise<UnifiedEntry>;
+    getEntries(filter?: EntryFilter): Promise<UnifiedEntry[]>;
+    getEntry(key: string): Promise<UnifiedEntry | undefined>;
+    getTopology(kind: string): Promise<TopologyEntry[]>;
+    setTopology(kind: string, entries: TopologyEntry[]): Promise<void>;
+    getAgentInstruction(agent: string, file: string): Promise<string | undefined>;
+    setAgentInstruction(agent: string, file: string, content: string, source?: ContentSourceCode): Promise<void>;
+    listAgents(): Promise<string[]>;
+    getSkillContent(skill: string, file: string): Promise<string | undefined>;
+    setSkillContent(skill: string, file: string, content: string, source?: ContentSourceCode): Promise<void>;
+    listSkills(): Promise<string[]>;
+    /** Dead space ratio — used to decide if compaction is needed */
+    get deadSpaceRatio(): number;
+    /** Number of entries in the unified log */
+    get entryCount(): number;
+}
+export declare function openStore(storePath: string, opts?: {
+    readOnly?: boolean;
+}): Promise<AcePackedStore>;
+//# sourceMappingURL=ace-packed-store.d.ts.map