@voybio/ace-swarm 0.1.0

package/dist/prompts.js

@@ -0,0 +1,628 @@
+/**
+ * MCP Prompts – pre-built prompt templates for each ACE role,
+ * multi-agent workflows, and skill activation.
+ */
+import { z } from "zod";
+import { readKernelArtifact, listAvailableSkills, readAgentInstructions, readSkillInstructions, readTaskArtifact, } from "./helpers.js";
+import { readRuntimeProfileState, renderRuntimePrompt } from "./runtime-profile.js";
+import { buildAceContinuityPacket, buildAceRecallContext, formatAceContinuityPacketMarkdown, formatAceRecallMarkdown, normalizeAutonomyPolicy, normalizeContinuityPolicy, } from "./ace-autonomy.js";
+function formatRecallSlices(task) {
+    const recall = buildAceRecallContext();
+    const slices = recall.state_slices
+        .filter((entry) => entry.present)
+        .slice(0, 5)
+        .flatMap((entry) => [
+        `### ${entry.path}`,
+        "```text",
+        entry.excerpt,
+        "```",
+    ]);
+    return [
+        "## ACE Preflight",
+        "ACE-Orchestrator owns preflight before any substantial dispatch.",
+        formatAceRecallMarkdown(recall),
+        task ? `- Requested task: ${task}` : "",
+        "",
+        "## ACE Recall",
+        ...(slices.length > 0 ? slices : ["(no current ACE state slices found)"]),
+        ...(recall.snapshot
+            ? [
+                "",
+                "## Latest Context Snapshot",
+                `Name: ${recall.snapshot.name}`,
+                `Timestamp: ${recall.snapshot.timestamp}`,
+                `Summary: ${recall.snapshot.summary}`,
+                "```json",
+                recall.snapshot.content,
+                "```",
+            ]
+            : []),
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+function resolveSnapshotName(context) {
+    const candidates = [context.context_snapshot_name, context.snapshot_name];
+    for (const candidate of candidates) {
+        if (typeof candidate === "string" && candidate.trim().length > 0) {
+            return candidate.trim();
+        }
+    }
+    return undefined;
+}
+function renderRuntimeRecallSections(input) {
+    const recall = buildAceRecallContext({
+        state_sources: input.stateSources,
+        snapshot_name: input.snapshotName,
+    });
+    const slices = input.includeSlices
+        ? recall.state_slices
+            .filter((entry) => entry.present)
+            .slice(0, 5)
+            .flatMap((entry) => [
+            `### ${entry.path}`,
+            "```text",
+            entry.excerpt,
+            "```",
+        ])
+        : [];
+    return {
+        recallMd: [
+            formatAceRecallMarkdown(recall),
+            input.task ? `- Requested task: ${input.task}` : "",
+            ...(slices.length > 0 ? ["", ...slices] : []),
+        ]
+            .filter(Boolean)
+            .join("\n"),
+        snapshotMd: recall.snapshot
+            ? [
+                `Name: ${recall.snapshot.name}`,
+                `Timestamp: ${recall.snapshot.timestamp}`,
+                `Summary: ${recall.snapshot.summary}`,
+                "```json",
+                recall.snapshot.content,
+                "```",
+            ].join("\n")
+            : "",
+    };
+}
+export function registerPrompts(server) {
+    // ── Token-budget mode ─────────────────────────────────────────────
+    const BRIEF_SCHEMA = z
+        .boolean()
+        .optional()
+        .describe("Token-budget mode: true = role instructions only (no kernel/task-packs). Default: false (full context).");
+    // ── 1. Per-agent activation prompts ─────────────────────────────────
+    server.prompt("ace-runtime-executor", "Render the active ACE runtime prompt template for unattended execution flows", {
+        task: z.string().optional().describe("Task or objective to inject into the runtime prompt"),
+        context_json: z
+            .string()
+            .optional()
+            .describe("Optional JSON object merged into the runtime prompt context"),
+    }, ({ task, context_json }) => {
+        let extraContext = {};
+        if (context_json) {
+            try {
+                const parsed = JSON.parse(context_json);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                    extraContext = parsed;
+                }
+                else {
+                    extraContext = { context_json };
+                }
+            }
+            catch {
+                extraContext = { context_json };
+            }
+        }
+        const active = readRuntimeProfileState();
+        const autonomy = normalizeAutonomyPolicy(active.profile.autonomy);
+        const continuity = normalizeContinuityPolicy(active.profile.continuity);
+        const snapshotName = resolveSnapshotName(extraContext);
+        const recallSections = renderRuntimeRecallSections({
+            task,
+            snapshotName,
+            stateSources: autonomy.state_sources,
+            includeSlices: !continuity.enabled,
+        });
+        const continuityPacket = buildAceContinuityPacket({
+            snapshot_name: snapshotName,
+            policy: continuity,
+        });
+        const rendered = renderRuntimePrompt({
+            task: task ?? "No task provided.",
+            autonomy,
+            continuity,
+            ace_state_recall_md: recallSections.recallMd,
+            ace_context_snapshot_md: recallSections.snapshotMd,
+            ace_continuity_packet_md: formatAceContinuityPacketMarkdown(continuityPacket),
+            ...extraContext,
+        });
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: [
+                            "# ACE Runtime Executor Prompt",
+                            "",
+                            `Source: ${active.source} (${active.path})`,
+                            "",
+                            rendered,
+                        ].join("\n"),
+                    },
+                },
+            ],
+        };
+    });
+    server.prompt("ace-orchestrator", "Activate ACE Orchestrator – Swarm Hypervisor and TPM", {
+        task: z.string().optional().describe("What should the orchestrator do?"),
+        brief: BRIEF_SCHEMA,
+    }, ({ task, brief }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "# ACE Orchestrator Activation",
+                        "",
+                        "You are now operating as ACE-Orchestrator.",
+                        "",
+                        "## Orchestrator Instructions",
+                        readAgentInstructions("orchestrator"),
+                        "",
+                        ...(brief ? ["## ACE Preflight", formatAceRecallMarkdown(buildAceRecallContext())] : [formatRecallSlices(task)]),
+                        ...(brief
+                            ? []
+                            : [
+                                "",
+                                "## Shared Kernel (Swarm + Composable)",
+                                readKernelArtifact("directive_kernel"),
+                                "",
+                                "## Composable Registry",
+                                readKernelArtifact("agent_registry"),
+                                "",
+                                "## Role Task Packs",
+                                readTaskArtifact("role_tasks"),
+                                "",
+                                "## Handoff Template",
+                                readTaskArtifact("handoff_template"),
+                            ]),
+                        "",
+                        task
+                            ? `## Current Task\n${task}`
+                            : "## Awaiting Task\nScan state artifacts and propose next routed action.",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    server.prompt("ace-vos", "Activate ACE VOS – Venture Architect", {
+        task: z.string().optional().describe("What venture question should VOS solve?"),
+        brief: BRIEF_SCHEMA,
+    }, ({ task, brief }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "# ACE VOS Activation",
+                        "",
+                        "You are now operating as ACE-VOS.",
+                        "",
+                        "## VOS Instructions",
+                        readAgentInstructions("vos"),
+                        ...(brief
+                            ? []
+                            : [
+                                "",
+                                "## Shared Kernel (Swarm + Composable)",
+                                readKernelArtifact("directive_kernel"),
+                                "",
+                                "## CLI Work Split",
+                                readTaskArtifact("cli_work_split"),
+                            ]),
+                        "",
+                        task
+                            ? `## Current Task\n${task}`
+                            : "## Awaiting Input\nBegin Socratic venture interrogation.",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    server.prompt("ace-ui", "Activate ACE UI – Mercer Protocol UX/CX Strategist", {
+        task: z.string().optional().describe("What surface should UI audit or rewrite?"),
+        brief: BRIEF_SCHEMA,
+    }, ({ task, brief }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "# ACE UI Activation",
+                        "",
+                        "You are now operating as ACE-UI.",
+                        "",
+                        "## UI Instructions",
+                        readAgentInstructions("ui"),
+                        ...(brief
+                            ? []
+                            : [
+                                "",
+                                "## Shared Kernel (Swarm + Composable)",
+                                readKernelArtifact("directive_kernel"),
+                                "",
+                                "## CLI Work Split",
+                                readTaskArtifact("cli_work_split"),
+                            ]),
+                        "",
+                        task
+                            ? `## Current Task\n${task}`
+                            : "## Awaiting Input\nRun a Mercer audit on the current surface.",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    server.prompt("ace-coders", "Activate ACE Coders – Engineering TDD Swarm", {
+        task: z.string().optional().describe("What should engineering build or fix?"),
+        brief: BRIEF_SCHEMA,
+    }, ({ task, brief }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "# ACE Coders Activation",
+                        "",
+                        "You are now operating as ACE-Coders.",
+                        "",
+                        "## Coders Instructions",
+                        readAgentInstructions("coders"),
+                        ...(brief
+                            ? []
+                            : [
+                                "",
+                                "## Shared Kernel (Swarm + Composable)",
+                                readKernelArtifact("directive_kernel"),
+                                "",
+                                "## CLI Work Split",
+                                readTaskArtifact("cli_work_split"),
+                            ]),
+                        "",
+                        task
+                            ? `## Current Task\n${task}`
+                            : "## Awaiting Spec\nLoad SPEC_CONTRACT.json or request a structured handoff.",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    server.prompt("ace-astgrep", "Activate ACE ASTGrep – Structural Discovery Indexing", { task: z.string().optional().describe("What discovery map or structural index should ASTGrep build?") }, ({ task }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "# ACE ASTGrep Activation",
+                        "",
+                        "You are now operating as ACE-ASTGrep.",
+                        "",
+                        "## ASTGrep Agent Instructions",
+                        readAgentInstructions("astgrep"),
+                        "",
+                        "## AST-grep Command Pack",
+                        readSkillInstructions("astgrep-index"),
+                        "",
+                        task
+                            ? `## Current Task\n${task}`
+                            : "## Awaiting Task\nProduce a compact structural discovery index for orchestrator/research routing.",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    server.prompt("ace-memory", "Activate ACE Memory – Context Integrity Sidecar", { task: z.string().optional().describe("What memory reconciliation task should run?") }, ({ task }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "# ACE Memory Activation",
+                        "",
+                        "You are now operating as ACE-Memory.",
+                        "",
+                        "## Memory Agent Instructions",
+                        readAgentInstructions("memory"),
+                        "",
+                        "## Shared Kernel",
+                        readKernelArtifact("directive_kernel"),
+                        "",
+                        task
+                            ? `## Current Task\n${task}`
+                            : "## Awaiting Task\nReconcile durable memory from evidence/decisions/risks.",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    server.prompt("ace-security", "Activate ACE Security – Security and Policy Gatekeeper", { task: z.string().optional().describe("What security validation should run?") }, ({ task }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "# ACE Security Activation",
+                        "",
+                        "You are now operating as ACE-Security.",
+                        "",
+                        "## Security Agent Instructions",
+                        readAgentInstructions("security"),
+                        "",
+                        "## Shared Kernel",
+                        readKernelArtifact("directive_kernel"),
+                        "",
+                        task
+                            ? `## Current Task\n${task}`
+                            : "## Awaiting Task\nValidate security and policy posture against active artifacts.",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    server.prompt("ace-observability", "Activate ACE Observability – Telemetry and Incident Readiness", { task: z.string().optional().describe("What observability check should run?") }, ({ task }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "# ACE Observability Activation",
+                        "",
+                        "You are now operating as ACE-Observability.",
+                        "",
+                        "## Observability Agent Instructions",
+                        readAgentInstructions("observability"),
+                        "",
+                        "## Shared Kernel",
+                        readKernelArtifact("directive_kernel"),
+                        "",
+                        task
+                            ? `## Current Task\n${task}`
+                            : "## Awaiting Task\nAssess telemetry, runbooks, and incident routing readiness.",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    server.prompt("ace-eval", "Activate ACE Eval – Autonomy Benchmark and Regression Gate", { task: z.string().optional().describe("What evaluation suite should run?") }, ({ task }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "# ACE Eval Activation",
+                        "",
+                        "You are now operating as ACE-Eval.",
+                        "",
+                        "## Eval Agent Instructions",
+                        readAgentInstructions("eval"),
+                        "",
+                        "## Shared Kernel",
+                        readKernelArtifact("directive_kernel"),
+                        "",
+                        task
+                            ? `## Current Task\n${task}`
+                            : "## Awaiting Task\nRun deterministic evaluation suites and report regressions.",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    server.prompt("ace-release", "Activate ACE Release – Promotion and Rollback Gatekeeper", { task: z.string().optional().describe("What release decision should be evaluated?") }, ({ task }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "# ACE Release Activation",
+                        "",
+                        "You are now operating as ACE-Release.",
+                        "",
+                        "## Release Agent Instructions",
+                        readAgentInstructions("release"),
+                        "",
+                        "## Shared Kernel",
+                        readKernelArtifact("directive_kernel"),
+                        "",
+                        task
+                            ? `## Current Task\n${task}`
+                            : "## Awaiting Task\nIssue an explicit release hold/promote decision with rollback viability.",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    // ── 2. Bootstrap and workflow prompts ───────────────────────────────
+    server.prompt("ace-initiate", "Initialize ACE state and route first task", {
+        goal: z.string().optional().describe("Primary objective for this ACE session"),
+    }, ({ goal }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "# Initiate ACE",
+                        "",
+                        "1. Run `bootstrap_state` to materialize ACE artifacts.",
+                        "2. Run `refresh_astgrep_index` to populate structural discovery artifacts and status events.",
+                        "3. Run `scan_workspace_delta` for lightweight summary metadata + full fingerprint delta tracking.",
+                        "4. Load `ace://tasks/role_tasks`, `ace://kernel/directive_kernel`, and `ace://kernel/agent_registry`.",
+                        "5. Route to the correct primary agent using `route_task`.",
+                        "6. Activate `ace-orchestrator` and emit a structured handoff before execution.",
+                        "",
+                        goal ? `## Goal\n${goal}` : "## Goal\nDerive the next highest-value action from current state.",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    server.prompt("ace-genesis", "Run full Genesis pipeline: VOS → UI → Coders", { idea: z.string().describe("Describe the product idea or feature") }, ({ idea }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "# ACE Genesis Pipeline",
+                        "",
+                        `> ${idea}`,
+                        "",
+                        "## Pipeline",
+                        "1. VOS: harden thesis and distribution wedge.",
+                        "2. UI: design UX flow and copy deck.",
+                        "3. Coders: implement via TDD with verification evidence.",
+                        "",
+                        "## Handoff Contract",
+                        readTaskArtifact("handoff_template"),
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    server.prompt("ace-handoff", "Create a structured handoff between ACE agents", {
+        from: z.string().describe("Source agent (orchestrator, vos, ui, coders)"),
+        to: z.string().describe("Target agent (orchestrator, vos, ui, coders)"),
+        task: z.string().describe("What task is being handed off?"),
+    }, ({ from, to, task }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "# ACE Handoff Request",
+                        "",
+                        `Route: ACE-${from.toUpperCase()} -> ACE-${to.toUpperCase()}`,
+                        `Task: ${task}`,
+                        "",
+                        "## Handoff Template",
+                        readTaskArtifact("handoff_template"),
+                        "",
+                        "## Example",
+                        readTaskArtifact("handoff_example"),
+                        "",
+                        "## Rules",
+                        "- Populate every required field",
+                        "- Include artifact pointers, not narrative-only summaries",
+                        "- Use measurable acceptance criteria",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    server.prompt("ace-lessons", "Review and apply lessons/guardrails", () => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "# ACE Lessons and Guardrails",
+                        "",
+                        readTaskArtifact("lessons"),
+                        "",
+                        "Apply these guardrails to all subsequent actions.",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    // ── 3. Skill prompts ─────────────────────────────────────────────────
+    server.prompt("ace-skill", "Load an ACE skill into active prompt context", {
+        skill: z.string().describe("Skill name (e.g. codemunch, codesnipe, ace-orchestrator)"),
+        task: z.string().optional().describe("Optional task to apply against the skill"),
+    }, ({ skill, task }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        `# ACE Skill Activation: ${skill}`,
+                        "",
+                        readSkillInstructions(skill),
+                        "",
+                        task ? `## Task\n${task}` : "## Task\nApply this skill to the current workspace objective.",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    server.prompt("ace-codemunch", "Activate the codemunch skill for AST-first codebase mapping", { task: z.string().optional().describe("Optional analysis objective") }, ({ task }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "# CodeMunch Activation",
+                        "",
+                        readSkillInstructions("codemunch"),
+                        "",
+                        task
+                            ? `## Objective\n${task}`
+                            : "## Objective\nProduce CODEBASE_MAP.md and dependency insights using AST-first extraction.",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    server.prompt("ace-codesnipe", "Activate the codesnipe skill for dual-codebase comparison", { task: z.string().optional().describe("Optional comparison objective") }, ({ task }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "# CodeSnipe Activation",
+                        "",
+                        readSkillInstructions("codesnipe"),
+                        "",
+                        task
+                            ? `## Objective\n${task}`
+                            : "## Objective\nBuild HOME registry, score TARGET relevance, then extract only high-value symbols.",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    server.prompt("ace-skills-index", "List all discoverable ACE skills", () => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        "# ACE Skills Index",
+                        "",
+                        ...listAvailableSkills().map((skill) => `- ${skill.name} (${skill.source})`),
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+}
+//# sourceMappingURL=prompts.js.map

package/dist/public-surface.d.ts

@@ -0,0 +1,30 @@
+export declare const PUBLIC_SURFACE_REPORT_REL_PATH = "agent-state/PUBLIC_SURFACE_REPORT.md";
+type SurfaceKind = "tool" | "resource" | "prompt";
+export interface PublicSurfaceEntry {
+    kind: SurfaceKind;
+    id: string;
+    name: string;
+    description: string;
+}
+export interface PublicSurfaceAuditSummary {
+    tools: number;
+    resources: number;
+    prompts: number;
+    emitted_events: number;
+    schema_bound_surfaces: number;
+}
+export interface PublicSurfaceAuditResult {
+    ok: boolean;
+    summary: PublicSurfaceAuditSummary;
+    failures: string[];
+    warnings: string[];
+    surfaces: PublicSurfaceEntry[];
+    emitted_events: string[];
+    report_path: string;
+}
+export declare function auditPublicSurface(options?: {
+    write_artifact?: boolean;
+    artifact_path?: string;
+}): Promise<PublicSurfaceAuditResult>;
+export {};
+//# sourceMappingURL=public-surface.d.ts.map