open-xmen 0.1.0

package/dist/index.js

@@ -0,0 +1,466 @@
+import { tool } from "@opencode-ai/plugin";
+import { appendFile, lstat, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+const DEFAULT_MODEL_SLOTS = {
+    frontier: "openai/gpt-5.4",
+    strong: "openai/gpt-5.4",
+    coding: "openai/gpt-5.3-codex",
+    spark: "openai/gpt-5.3-codex-spark",
+    fast: "openai/gpt-5.4-mini",
+    image: "openai/gpt-image-2",
+};
+const COMMANDS = new Set([
+    "/to-me-my-x-men",
+    "/cerebro-plan",
+    "/cerebro-start-work",
+    "/cerebro-index",
+    "/cerebro-doctor",
+    "/cerebro-reset",
+    "/cerebro-upgrade",
+]);
+const RISKS = ["LOW", "MEDIUM", "HIGH"];
+const TASK_STATUSES = ["pending", "active", "blocked", "done", "verified", "failed"];
+const CEREBRO_AGENTS = ["cerebro", "legion", "cypher", "professor-x", "cyclops", "wolverine", "storm", "forge", "nightcrawler", "sage", "beast", "emma-frost"];
+const SAFE_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+const SECRET_PATH_PATTERN = /(^|[/\\])\.env(\.|$|[/\\])|secret|credential|token|private[-_]?key/i;
+const MAX_PENDING_FILES = 500;
+const MAX_PENDING_FILE_BYTES = 64 * 1024;
+function now() {
+    return new Date().toISOString().replace("+00:00", "Z");
+}
+function slug(input) {
+    return input
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48) || "cerebro-run";
+}
+function runtimeRoot(ctx) {
+    return path.join(ctx.worktree || ctx.directory, ".cerebro");
+}
+function safeRuntimePath(ctx, relativePath) {
+    const root = runtimeRoot(ctx);
+    const full = path.resolve(root, relativePath);
+    const normalizedRoot = path.resolve(root) + path.sep;
+    if (full !== path.resolve(root) && !full.startsWith(normalizedRoot)) {
+        throw new Error(`Path escapes .cerebro runtime: ${relativePath}`);
+    }
+    return full;
+}
+async function readJson(file, fallback) {
+    if (!existsSync(file))
+        return fallback;
+    return JSON.parse(await readFile(file, "utf8"));
+}
+async function writeJson(file, data) {
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+}
+async function appendJsonl(file, data) {
+    await mkdir(path.dirname(file), { recursive: true });
+    await appendFile(file, `${JSON.stringify(data)}\n`, "utf8");
+}
+function modelSlots() {
+    return {
+        frontier: process.env.CEREBRO_MODEL_FRONTIER || DEFAULT_MODEL_SLOTS.frontier,
+        strong: process.env.CEREBRO_MODEL_STRONG || DEFAULT_MODEL_SLOTS.strong,
+        coding: process.env.CEREBRO_MODEL_CODING || DEFAULT_MODEL_SLOTS.coding,
+        spark: process.env.CEREBRO_MODEL_SPARK || DEFAULT_MODEL_SLOTS.spark,
+        fast: process.env.CEREBRO_MODEL_FAST || DEFAULT_MODEL_SLOTS.fast,
+        image: process.env.CEREBRO_MODEL_IMAGE || DEFAULT_MODEL_SLOTS.image,
+    };
+}
+function parseModelID(model) {
+    const [providerID, ...rest] = model.split("/");
+    const modelID = rest.join("/");
+    if (!providerID || !modelID)
+        throw new Error(`Invalid model id: ${model}`);
+    return { providerID, modelID };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function assertSafeName(value, label) {
+    if (!SAFE_NAME_PATTERN.test(value))
+        throw new Error(`${label} must be a safe slug-like name`);
+}
+function assertSafeAgent(agent) {
+    if (!CEREBRO_AGENTS.includes(agent))
+        throw new Error(`Unsupported Cerebro agent: ${agent}`);
+}
+function readToolArgs(args) {
+    return isRecord(args) ? args : {};
+}
+function isSecretPath(filePath) {
+    return SECRET_PATH_PATTERN.test(filePath);
+}
+function isInside(parent, child) {
+    const relative = path.relative(parent, child);
+    return relative === "" || (!!relative && !relative.startsWith("..") && !path.isAbsolute(relative));
+}
+async function scanPendingTodos(root, teamName) {
+    const normalizedRoot = path.resolve(root);
+    const base = teamName ? path.resolve(normalizedRoot, teamName) : normalizedRoot;
+    if (!isInside(normalizedRoot, base))
+        throw new Error("pending todo path escapes .cerebro/pending-todos");
+    const items = [];
+    let filesSeen = 0;
+    async function walk(current) {
+        if (!isInside(normalizedRoot, current))
+            throw new Error("pending todo scan escaped .cerebro/pending-todos");
+        if (isSecretPath(current))
+            throw new Error("Cerebro safety policy blocks pending todo scans of secret-like paths");
+        if (!existsSync(current))
+            return;
+        const stats = await lstat(current);
+        if (stats.isSymbolicLink())
+            return;
+        if (stats.isDirectory()) {
+            for (const name of await readdir(current))
+                await walk(path.join(current, name));
+            return;
+        }
+        if (!stats.isFile())
+            return;
+        filesSeen += 1;
+        if (filesSeen > MAX_PENDING_FILES)
+            throw new Error(`pending todo scan exceeded ${MAX_PENDING_FILES} files`);
+        if (stats.size > MAX_PENDING_FILE_BYTES)
+            throw new Error(`pending todo file is too large: ${current}`);
+        for (const line of (await readFile(current, "utf8")).split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed)
+                items.push({ file: current, line: trimmed });
+        }
+    }
+    await walk(base);
+    return items;
+}
+function hasChildSessionClient(client) {
+    if (!isRecord(client))
+        return false;
+    const session = client.session;
+    if (!isRecord(session))
+        return false;
+    return typeof session.create === "function" && typeof session.promptAsync === "function";
+}
+function childSessionID(result) {
+    if (!isRecord(result))
+        return undefined;
+    const data = result.data;
+    if (isRecord(data) && typeof data.id === "string")
+        return data.id;
+    return typeof result.id === "string" ? result.id : undefined;
+}
+function taskFile(ctx, runId) {
+    return safeRuntimePath(ctx, `team-runs/${runId}.tasks.json`);
+}
+function manifestFile(ctx, runId) {
+    return safeRuntimePath(ctx, `team-runs/${runId}.json`);
+}
+async function loadTasks(ctx, runId) {
+    return readJson(taskFile(ctx, runId), []);
+}
+async function saveTasks(ctx, runId, tasks) {
+    await writeJson(taskFile(ctx, runId), tasks);
+}
+export const CerebroPlugin = async ({ worktree, directory, client }) => {
+    const ctx = { worktree, directory };
+    return {
+        async event({ event }) {
+            if (!event || typeof event !== "object")
+                return;
+            const eventType = "type" in event ? String(event.type) : "unknown";
+            if (!eventType.startsWith("session.") && !eventType.startsWith("command.") && !eventType.startsWith("todo."))
+                return;
+            await appendJsonl(safeRuntimePath(ctx, "team-runs/events.jsonl"), {
+                logged_at: now(),
+                event: eventType,
+                payload: event,
+            });
+        },
+        async "command.execute.before"(input, output) {
+            const command = input.command.startsWith("/") ? input.command : `/${input.command}`;
+            if (!COMMANDS.has(command))
+                return;
+            output.parts.unshift({
+                id: `cerebro-command-${input.sessionID}`,
+                sessionID: input.sessionID,
+                messageID: `cerebro-command-${input.command}`,
+                type: "text",
+                text: [
+                    "Cerebro OpenCode runtime is active.",
+                    "Before acting, use the Cerebro coordination tools for run state, mailbox, checkpoints, pending-todo checks, and model-slot lookup.",
+                    "Runtime root: `.cerebro/`. Preserve command names and role names.",
+                ].join("\n"),
+                synthetic: true,
+            });
+        },
+        async "tool.execute.before"(_input, output) {
+            const args = readToolArgs(output.args);
+            const candidate = String(args.filePath || args.path || args.command || "");
+            if (isSecretPath(candidate)) {
+                throw new Error("Cerebro safety policy blocks reading or touching env/secret/credential paths without explicit user authorization.");
+            }
+        },
+        async "experimental.session.compacting"(_input, output) {
+            output.context.push("Preserve Cerebro state before compacting: summarize active command, run_id, boulder status, pending approvals, pending todos, verification evidence, and next checkpoint under `.cerebro/`.");
+        },
+        tool: {
+            cerebro_model_slots: tool({
+                description: "Return the configured Cerebro OpenAI model slots for role routing.",
+                args: {},
+                async execute() {
+                    return JSON.stringify(modelSlots(), null, 2);
+                },
+            }),
+            cerebro_run_start: tool({
+                description: "Create or initialize a Cerebro run manifest and boulder checkpoint under .cerebro.",
+                args: {
+                    command: tool.schema.enum(Array.from(COMMANDS)).describe("Cerebro command name"),
+                    objective: tool.schema.string().min(1).describe("User objective for this run"),
+                    risk_level: tool.schema.enum(RISKS).describe("Risk level"),
+                    team_name: tool.schema.string().optional().describe("Optional stable team/session name"),
+                },
+                async execute(args) {
+                    const timestamp = now();
+                    const runId = `${timestamp.slice(0, 10).replace(/-/g, "")}-${timestamp.slice(11, 19).replace(/:/g, "")}-${slug(args.objective)}`;
+                    const teamName = args.team_name || slug(`${args.command}-${args.objective}`);
+                    const manifest = {
+                        version: 1,
+                        run_id: runId,
+                        command: args.command,
+                        status: args.command === "/cerebro-plan" ? "planning" : "running",
+                        lead: "cerebro",
+                        team_name: teamName,
+                        objective: args.objective,
+                        risk_level: args.risk_level,
+                        started_at: timestamp,
+                        updated_at: timestamp,
+                        teammates: [],
+                        ownership: [],
+                        mailbox_decisions: [],
+                        approvals: [],
+                        verification: [],
+                        cleanup: {
+                            team_stopped: false,
+                            pending_todos_clear: false,
+                            notes: "OpenCode-managed Cerebro run",
+                        },
+                    };
+                    await writeJson(manifestFile(ctx, runId), manifest);
+                    await saveTasks(ctx, runId, []);
+                    if (["/to-me-my-x-men", "/cerebro-start-work"].includes(args.command)) {
+                        await writeJson(safeRuntimePath(ctx, "boulder.json"), {
+                            version: 2,
+                            active_plan: "",
+                            plan_name: slug(args.objective),
+                            status: "in_progress",
+                            risk_level: args.risk_level,
+                            team_name: teamName,
+                            started_at: timestamp,
+                            updated_at: timestamp,
+                            approval_gates: [],
+                            verification_history: [],
+                            decisions: [],
+                        });
+                    }
+                    return JSON.stringify({ run_id: runId, manifest: `.cerebro/team-runs/${runId}.json`, tasks: `.cerebro/team-runs/${runId}.tasks.json` }, null, 2);
+                },
+            }),
+            cerebro_task_create: tool({
+                description: "Create a task record for an OpenCode-managed Cerebro run.",
+                args: {
+                    run_id: tool.schema.string().min(1),
+                    subject: tool.schema.string().min(1),
+                    description: tool.schema.string().min(1),
+                    owner: tool.schema.string().min(1).describe("Cerebro role or spawned agent name"),
+                    depends_on: tool.schema.array(tool.schema.string()).optional(),
+                },
+                async execute(args) {
+                    const tasks = await loadTasks(ctx, args.run_id);
+                    const id = `task-${String(tasks.length + 1).padStart(3, "0")}`;
+                    const record = {
+                        id,
+                        subject: args.subject,
+                        description: args.description,
+                        owner: args.owner,
+                        status: "pending",
+                        depends_on: args.depends_on || [],
+                        created_at: now(),
+                        updated_at: now(),
+                        notes: [],
+                        verification: [],
+                    };
+                    tasks.push(record);
+                    await saveTasks(ctx, args.run_id, tasks);
+                    return JSON.stringify(record, null, 2);
+                },
+            }),
+            cerebro_task_list: tool({
+                description: "List task records for an OpenCode-managed Cerebro run.",
+                args: { run_id: tool.schema.string().min(1) },
+                async execute(args) {
+                    return JSON.stringify(await loadTasks(ctx, args.run_id), null, 2);
+                },
+            }),
+            cerebro_task_update: tool({
+                description: "Update task status, notes, or verification for a Cerebro run.",
+                args: {
+                    run_id: tool.schema.string().min(1),
+                    task_id: tool.schema.string().min(1),
+                    status: tool.schema.enum(TASK_STATUSES).optional(),
+                    note: tool.schema.string().optional(),
+                    verification_result: tool.schema.enum(["PASS", "FAIL", "BLOCKED", "NOT RUN"]).optional(),
+                    verification_command: tool.schema.string().optional(),
+                },
+                async execute(args) {
+                    const tasks = await loadTasks(ctx, args.run_id);
+                    const taskRecord = tasks.find((task) => task.id === args.task_id);
+                    if (!taskRecord)
+                        throw new Error(`Unknown task ${args.task_id}`);
+                    if (args.status)
+                        taskRecord.status = args.status;
+                    if (args.note)
+                        taskRecord.notes.push(`${now()} ${args.note}`);
+                    if (args.verification_result) {
+                        taskRecord.verification.push({
+                            at: now(),
+                            result: args.verification_result,
+                            command: args.verification_command,
+                            notes: args.note,
+                        });
+                    }
+                    taskRecord.updated_at = now();
+                    await saveTasks(ctx, args.run_id, tasks);
+                    return JSON.stringify(taskRecord, null, 2);
+                },
+            }),
+            cerebro_mailbox_send: tool({
+                description: "Append a mailbox message for a Cerebro run and optionally record decisions in the manifest.",
+                args: {
+                    run_id: tool.schema.string().min(1),
+                    from: tool.schema.string().min(1),
+                    to: tool.schema.string().min(1),
+                    type: tool.schema.string().min(1),
+                    body: tool.schema.string().min(1),
+                    decision: tool.schema.string().optional(),
+                },
+                async execute(args) {
+                    const record = { at: now(), ...args };
+                    await appendJsonl(safeRuntimePath(ctx, `team-runs/${args.run_id}.mailbox.jsonl`), record);
+                    if (args.decision) {
+                        const file = manifestFile(ctx, args.run_id);
+                        const manifest = await readJson(file, {});
+                        manifest.mailbox_decisions ||= [];
+                        manifest.mailbox_decisions.push({ at: record.at, from: args.from, to: args.to, decision: args.decision, notes: args.body });
+                        manifest.updated_at = now();
+                        await writeJson(file, manifest);
+                    }
+                    return JSON.stringify(record, null, 2);
+                },
+            }),
+            cerebro_mailbox_read: tool({
+                description: "Read mailbox messages for a Cerebro run, optionally filtered by recipient.",
+                args: {
+                    run_id: tool.schema.string().min(1),
+                    to: tool.schema.string().optional(),
+                    limit: tool.schema.number().int().min(1).max(200).optional(),
+                },
+                async execute(args) {
+                    const file = safeRuntimePath(ctx, `team-runs/${args.run_id}.mailbox.jsonl`);
+                    if (!existsSync(file))
+                        return "[]";
+                    const lines = (await readFile(file, "utf8")).split("\n");
+                    const records = lines
+                        .filter(Boolean)
+                        .map((line) => JSON.parse(line))
+                        .filter((record) => !args.to || record.to === args.to)
+                        .slice(-(args.limit || 50));
+                    return JSON.stringify(records, null, 2);
+                },
+            }),
+            cerebro_dispatch_agent: tool({
+                description: "Dispatch an OpenCode child session/subagent for Cerebro work and record the dispatch intent. Returns child session metadata when the SDK supports it.",
+                args: {
+                    run_id: tool.schema.string().min(1),
+                    agent: tool.schema.enum(CEREBRO_AGENTS).describe("OpenCode/Cerebro agent name, e.g. nightcrawler, wolverine, professor-x"),
+                    description: tool.schema.string().min(1),
+                    prompt: tool.schema.string().min(1),
+                    model_slot: tool.schema.enum(["frontier", "strong", "coding", "spark", "fast", "image"]).optional().describe("Optional Cerebro model slot override for this dispatch"),
+                    no_reply: tool.schema.boolean().optional(),
+                },
+                async execute(args, toolContext) {
+                    assertSafeAgent(args.agent);
+                    const dispatchRecord = { at: now(), type: "dispatch", from: "cerebro", to: args.agent, description: args.description };
+                    await appendJsonl(safeRuntimePath(ctx, `team-runs/${args.run_id}.mailbox.jsonl`), dispatchRecord);
+                    try {
+                        if (!hasChildSessionClient(client))
+                            throw new Error("OpenCode SDK client does not expose child session create/promptAsync methods");
+                        const created = await client.session.create({
+                            body: { parentID: toolContext.sessionID, title: `${args.agent}: ${args.description}` },
+                            query: { directory: toolContext.directory },
+                        });
+                        const childID = childSessionID(created);
+                        if (!childID)
+                            throw new Error("OpenCode SDK did not return a child session id");
+                        const slots = modelSlots();
+                        const selectedModel = args.model_slot ? slots[args.model_slot] : undefined;
+                        await client.session.promptAsync({
+                            path: { id: childID },
+                            query: { directory: toolContext.directory },
+                            body: {
+                                agent: args.agent,
+                                ...(selectedModel ? { model: parseModelID(selectedModel) } : {}),
+                                noReply: args.no_reply ?? true,
+                                parts: [{ type: "text", text: args.prompt }],
+                            },
+                        });
+                        return JSON.stringify({ dispatched: true, child_session_id: childID, agent: args.agent, model: selectedModel || "agent-default" }, null, 2);
+                    }
+                    catch (error) {
+                        return JSON.stringify({
+                            dispatched: false,
+                            agent: args.agent,
+                            fallback: `Use @${args.agent} with the prompt supplied to cerebro_dispatch_agent.`,
+                            error: error instanceof Error ? error.message : String(error),
+                        }, null, 2);
+                    }
+                },
+            }),
+            cerebro_checkpoint: tool({
+                description: "Write a durable Cerebro checkpoint for compaction/resume.",
+                args: {
+                    run_id: tool.schema.string().min(1),
+                    summary: tool.schema.string().min(1),
+                    next: tool.schema.string().optional(),
+                    verification: tool.schema.string().optional(),
+                },
+                async execute(args) {
+                    const record = { at: now(), ...args };
+                    await appendJsonl(safeRuntimePath(ctx, `team-runs/${args.run_id}.checkpoints.jsonl`), record);
+                    return JSON.stringify(record, null, 2);
+                },
+            }),
+            cerebro_verify_pending: tool({
+                description: "Scan .cerebro pending todo files and report whether final response is allowed.",
+                args: { team_name: tool.schema.string().optional() },
+                async execute(args) {
+                    const pendingRoot = safeRuntimePath(ctx, "pending-todos");
+                    const legacyPendingRoot = safeRuntimePath(ctx, ".pending-todos");
+                    const teamName = args.team_name?.trim();
+                    if (teamName)
+                        assertSafeName(teamName, "team_name");
+                    const items = [
+                        ...(await scanPendingTodos(pendingRoot, teamName)),
+                        ...(await scanPendingTodos(legacyPendingRoot, teamName)),
+                    ];
+                    return [items.length ? "BLOCKED" : "CLEAR", ...items.map((item) => `- ${item.line} (${item.file})`)].join("\n");
+                },
+            }),
+        },
+    };
+};
+export const server = CerebroPlugin;
+export default CerebroPlugin;

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "open-xmen",
+  "version": "0.1.0",
+  "description": "Cerebro/X-Men orchestration workflow for OpenCode.",
+  "type": "module",
+  "bin": {
+    "open-xmen": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "dist/index.d.ts",
+      "import": "dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    ".opencode/.gitignore",
+    ".opencode/agents",
+    ".opencode/commands",
+    ".cerebro/.gitignore",
+    ".cerebro/cerebro-identity.md",
+    ".cerebro/docs",
+    ".cerebro/integrations",
+    ".cerebro/opencode",
+    ".cerebro/schemas",
+    ".cerebro/scripts",
+    ".cerebro/templates",
+    ".cerebro/upgrade-manifest.json",
+    "AGENTS.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "doctor": "node dist/cli.js doctor",
+    "validate": "npm run build && node dist/cli.js doctor && npm run verify:release",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run validate",
+    "pack:check": "npm pack --dry-run",
+    "verify:release": "bun scripts/verify-release-artifact.ts"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.4.7",
+    "zod": "^4.1.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.9",
+    "typescript": "^5.8.2"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts"
+}