@voybio/ace-swarm 0.1.0

package/dist/public-surface.js

@@ -0,0 +1,316 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, extname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PACKAGE_ROOT, resolveWorkspaceRoot } from "./helpers.js";
+import { EVENT_TYPE } from "./shared.js";
+export const PUBLIC_SURFACE_REPORT_REL_PATH = "agent-state/PUBLIC_SURFACE_REPORT.md";
+const SCHEMA_REQUIREMENTS = {
+    "resource:ace://runtime/profile": [
+        "agent-state/MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json",
+    ],
+    "resource:ace://runtime/continuity-packet": [
+        "agent-state/MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json",
+    ],
+    "prompt:ace-runtime-executor": [
+        "agent-state/MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json",
+    ],
+    "tool:build_continuity_packet": [
+        "agent-state/MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json",
+    ],
+    "tool:get_runtime_profile": ["agent-state/MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json"],
+    "tool:validate_runtime_profile": [
+        "agent-state/MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json",
+    ],
+    "resource:ace://runtime/workspaces": [
+        "agent-state/MODULES/schemas/WORKSPACE_SESSION_REGISTRY.schema.json",
+    ],
+    "tool:list_workspace_sessions": [
+        "agent-state/MODULES/schemas/WORKSPACE_SESSION_REGISTRY.schema.json",
+    ],
+    "tool:create_workspace_session": [
+        "agent-state/MODULES/schemas/WORKSPACE_SESSION_REGISTRY.schema.json",
+    ],
+    "tool:remove_workspace_session": [
+        "agent-state/MODULES/schemas/WORKSPACE_SESSION_REGISTRY.schema.json",
+    ],
+    "resource:ace://runtime/tool-specs": [
+        "agent-state/MODULES/schemas/RUNTIME_TOOL_SPEC_REGISTRY.schema.json",
+    ],
+    "tool:get_runtime_tool_specs": [
+        "agent-state/MODULES/schemas/RUNTIME_TOOL_SPEC_REGISTRY.schema.json",
+    ],
+    "tool:validate_runtime_tool_specs": [
+        "agent-state/MODULES/schemas/RUNTIME_TOOL_SPEC_REGISTRY.schema.json",
+    ],
+    "tool:list_runtime_tool_specs": [
+        "agent-state/MODULES/schemas/RUNTIME_TOOL_SPEC_REGISTRY.schema.json",
+    ],
+    "tool:execute_runtime_tool": [
+        "agent-state/MODULES/schemas/RUNTIME_TOOL_SPEC_REGISTRY.schema.json",
+    ],
+    "resource:ace://runtime/executor-sessions": [
+        "agent-state/MODULES/schemas/RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json",
+    ],
+    "tool:list_unattended_sessions": [
+        "agent-state/MODULES/schemas/RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json",
+    ],
+    "tool:get_unattended_session": [
+        "agent-state/MODULES/schemas/RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json",
+    ],
+    "tool:start_unattended_session": [
+        "agent-state/MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json",
+        "agent-state/MODULES/schemas/RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json",
+    ],
+    "tool:wait_for_unattended_session": [
+        "agent-state/MODULES/schemas/RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json",
+    ],
+    "tool:stop_unattended_session": [
+        "agent-state/MODULES/schemas/RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json",
+    ],
+    "tool:validate_unattended_session_registry": [
+        "agent-state/MODULES/schemas/RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json",
+    ],
+    "resource:ace://runtime/tracker-snapshot": [
+        "agent-state/MODULES/schemas/TRACKER_SNAPSHOT.schema.json",
+    ],
+    "tool:get_tracker_snapshot": ["agent-state/MODULES/schemas/TRACKER_SNAPSHOT.schema.json"],
+    "tool:validate_tracker_snapshot": [
+        "agent-state/MODULES/schemas/TRACKER_SNAPSHOT.schema.json",
+    ],
+    "tool:list_tracker_items": ["agent-state/MODULES/schemas/TRACKER_SNAPSHOT.schema.json"],
+    "tool:create_tracker_comment": ["agent-state/MODULES/schemas/TRACKER_SNAPSHOT.schema.json"],
+    "tool:update_tracker_item_state": [
+        "agent-state/MODULES/schemas/TRACKER_SNAPSHOT.schema.json",
+    ],
+    "tool:refresh_tracker_snapshot": [
+        "agent-state/MODULES/schemas/TRACKER_SNAPSHOT.schema.json",
+    ],
+    "resource:ace://runtime/vericify-bridge": [
+        "agent-state/MODULES/schemas/VERICIFY_BRIDGE_SNAPSHOT.schema.json",
+    ],
+    "resource:ace://runtime/vericify-process-posts": [
+        "agent-state/MODULES/schemas/VERICIFY_PROCESS_POST_LOG.schema.json",
+    ],
+    "tool:get_vericify_bridge": [
+        "agent-state/MODULES/schemas/VERICIFY_BRIDGE_SNAPSHOT.schema.json",
+    ],
+    "tool:refresh_vericify_bridge": [
+        "agent-state/MODULES/schemas/VERICIFY_BRIDGE_SNAPSHOT.schema.json",
+    ],
+    "tool:validate_vericify_bridge": [
+        "agent-state/MODULES/schemas/VERICIFY_BRIDGE_SNAPSHOT.schema.json",
+    ],
+    "tool:get_vericify_process_posts": [
+        "agent-state/MODULES/schemas/VERICIFY_PROCESS_POST_LOG.schema.json",
+    ],
+    "tool:append_vericify_process_post": [
+        "agent-state/MODULES/schemas/VERICIFY_PROCESS_POST_LOG.schema.json",
+    ],
+    "tool:validate_vericify_process_post_log": [
+        "agent-state/MODULES/schemas/VERICIFY_PROCESS_POST_LOG.schema.json",
+    ],
+};
+function workspaceRoot() {
+    return resolveWorkspaceRoot();
+}
+function reportPath(relPath = PUBLIC_SURFACE_REPORT_REL_PATH) {
+    return resolve(workspaceRoot(), relPath);
+}
+function safeWriteReport(filePath, content) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmpPath, content, "utf-8");
+    renameSync(tmpPath, filePath);
+    return filePath;
+}
+async function collectSurfaceEntries() {
+    const entries = [];
+    const [{ registerTools }, { registerResources }, { registerPrompts }] = await Promise.all([
+        import("./tools.js"),
+        import("./resources.js"),
+        import("./prompts.js"),
+    ]);
+    const stub = {
+        tool(name, description) {
+            entries.push({
+                kind: "tool",
+                id: `tool:${name}`,
+                name,
+                description: description ?? "",
+            });
+        },
+        resource(name, uri, meta) {
+            const resolvedUri = typeof uri === "string" ? uri : `template:${String(name ?? "resource-template")}`;
+            entries.push({
+                kind: "resource",
+                id: `resource:${resolvedUri}`,
+                name: resolvedUri,
+                description: meta?.description ?? "",
+            });
+        },
+        prompt(name, description) {
+            entries.push({
+                kind: "prompt",
+                id: `prompt:${name}`,
+                name,
+                description: description ?? "",
+            });
+        },
+    };
+    registerTools(stub);
+    registerResources(stub);
+    registerPrompts(stub);
+    return entries.sort((left, right) => left.id.localeCompare(right.id));
+}
+function walkTypescriptFiles(root) {
+    const files = [];
+    const visit = (dirPath) => {
+        const entries = readdirSync(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name.startsWith("."))
+                continue;
+            const absolutePath = join(dirPath, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === "dist" || entry.name === "node_modules")
+                    continue;
+                visit(absolutePath);
+                continue;
+            }
+            if (extname(entry.name) === ".ts")
+                files.push(absolutePath);
+        }
+    };
+    visit(root);
+    return files.sort((left, right) => left.localeCompare(right));
+}
+function collectEmittedEventTypes() {
+    const srcRoot = dirname(fileURLToPath(import.meta.url));
+    const files = walkTypescriptFiles(srcRoot);
+    const discovered = new Set();
+    const patterns = [
+        /event_type:\s*"([A-Z][A-Z0-9_]+)"/g,
+        /emit[A-Za-z]+Event\(\s*"([A-Z][A-Z0-9_]+)"/g,
+    ];
+    for (const filePath of files) {
+        const raw = readFileSync(filePath, "utf-8");
+        for (const pattern of patterns) {
+            for (const match of raw.matchAll(pattern)) {
+                discovered.add(match[1]);
+            }
+        }
+    }
+    return [...discovered].sort((left, right) => left.localeCompare(right));
+}
+function renderReport(result) {
+    const grouped = {
+        tool: result.surfaces.filter((entry) => entry.kind === "tool"),
+        resource: result.surfaces.filter((entry) => entry.kind === "resource"),
+        prompt: result.surfaces.filter((entry) => entry.kind === "prompt"),
+    };
+    const schemaBacked = Object.entries(SCHEMA_REQUIREMENTS)
+        .sort((left, right) => left[0].localeCompare(right[0]))
+        .map(([surfaceId, schemaRefs]) => `- ${surfaceId} -> ${schemaRefs.join(", ")}`);
+    return [
+        "# PUBLIC_SURFACE_REPORT",
+        "",
+        `Generated: ${new Date().toISOString()}`,
+        `Gate status: ${result.ok ? "PASS" : "FAIL"}`,
+        "",
+        "## Summary",
+        `- tools: ${result.summary.tools}`,
+        `- resources: ${result.summary.resources}`,
+        `- prompts: ${result.summary.prompts}`,
+        `- emitted events: ${result.summary.emitted_events}`,
+        `- schema-backed surfaces: ${result.summary.schema_bound_surfaces}`,
+        "",
+        "## Failures",
+        ...(result.failures.length > 0 ? result.failures.map((entry) => `- ${entry}`) : ["- none"]),
+        "",
+        "## Warnings",
+        ...(result.warnings.length > 0 ? result.warnings.map((entry) => `- ${entry}`) : ["- none"]),
+        "",
+        "## Schema-backed Surfaces",
+        ...schemaBacked,
+        "",
+        "## Tools",
+        ...grouped.tool.map((entry) => `- ${entry.name} — ${entry.description}`),
+        "",
+        "## Resources",
+        ...grouped.resource.map((entry) => `- ${entry.name} — ${entry.description}`),
+        "",
+        "## Prompts",
+        ...grouped.prompt.map((entry) => `- ${entry.name} — ${entry.description}`),
+        "",
+        "## Events",
+        ...result.emitted_events.map((entry) => `- ${entry}`),
+        "",
+    ].join("\n");
+}
+export function auditPublicSurface(options) {
+    return collectSurfaceEntries().then((surfaces) => {
+        const emittedEvents = collectEmittedEventTypes();
+        const failures = [];
+        const warnings = [];
+        const seen = new Set();
+        for (const surface of surfaces) {
+            if (seen.has(surface.id)) {
+                failures.push(`duplicate public surface registration: ${surface.id}`);
+                continue;
+            }
+            seen.add(surface.id);
+            if (!surface.description.trim()) {
+                failures.push(`missing description for ${surface.id}`);
+            }
+        }
+        for (const [surfaceId, schemaRefs] of Object.entries(SCHEMA_REQUIREMENTS)) {
+            if (!seen.has(surfaceId)) {
+                failures.push(`schema-backed surface missing from registration: ${surfaceId}`);
+                continue;
+            }
+            for (const relPath of schemaRefs) {
+                const abs = resolve(workspaceRoot(), relPath);
+                const packageAbs = resolve(PACKAGE_ROOT, "assets", relPath);
+                if (!existsSync(abs) && !existsSync(packageAbs)) {
+                    failures.push(`schema file missing for ${surfaceId}: ${relPath}`);
+                }
+            }
+        }
+        const eventRegistry = new Set(Object.values(EVENT_TYPE));
+        for (const eventType of emittedEvents) {
+            if (!eventRegistry.has(eventType)) {
+                failures.push(`event type emitted without shared registry entry: ${eventType}`);
+            }
+        }
+        const publicSurfaceTestPath = resolve(PACKAGE_ROOT, "test", "public-surface.test.mjs");
+        if (!existsSync(publicSurfaceTestPath)) {
+            warnings.push(`expected audit self-test missing: ${publicSurfaceTestPath}`);
+        }
+        const summary = {
+            tools: surfaces.filter((entry) => entry.kind === "tool").length,
+            resources: surfaces.filter((entry) => entry.kind === "resource").length,
+            prompts: surfaces.filter((entry) => entry.kind === "prompt").length,
+            emitted_events: emittedEvents.length,
+            schema_bound_surfaces: Object.keys(SCHEMA_REQUIREMENTS).length,
+        };
+        const report_path = reportPath(options?.artifact_path || PUBLIC_SURFACE_REPORT_REL_PATH);
+        const result = {
+            ok: failures.length === 0,
+            summary,
+            failures,
+            warnings,
+            surfaces,
+            emitted_events: emittedEvents,
+        };
+        if (options?.write_artifact !== false) {
+            safeWriteReport(report_path, renderReport(result));
+        }
+        else if (!existsSync(report_path)) {
+            warnings.push(`public surface report missing: ${report_path}`);
+        }
+        return {
+            ...result,
+            report_path,
+        };
+    });
+}
+//# sourceMappingURL=public-surface.js.map

package/dist/resources.d.ts

@@ -0,0 +1,7 @@
+/**
+ * MCP Resources – expose ACE instruction files, task artifacts, skills,
+ * and handoff examples as readable resources.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerResources(server: McpServer): void;
+//# sourceMappingURL=resources.d.ts.map