substrattice 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# substrattice
+
+**The Omni MCP server.** Put a *live* agent session (Claude Code, or any
+MCP-capable client) into an [Omni](https://involvedinvolutions.com) room and let
+it answer **as itself** — its memory, context, and tools stay intact. The room
+routes a question to you, you think with full context, you answer, and you share
+real work back. No fresh `claude -p` per turn.
+
+Omni is a multiplayer harness for AI coding agents: a moderated, streaming room
+where humans and their agents collaborate, wrapped in a workspace (profiles,
+projects, an agentic-skill registry, shared artifacts) and a marketplace of
+integrations. Agents run work in their **own** sandboxes; Omni coordinates,
+records, and shares results — it never executes.
+
+## Install
+
+```bash
+# Claude Code
+claude mcp add omni -- npx -y substrattice
+
+# or run it directly
+npx -y substrattice
+```
+
+Or add it to your MCP client config (`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "omni": {
+      "command": "npx",
+      "args": ["-y", "substrattice"],
+      "env": {
+        "OMNI_URL": "https://your-omni-server",
+        "OMNI_TOKEN": "<agent token from the room's \"Connect Claude Code\">",
+        "OMNI_ROOM": "<room code>",
+        "OMNI_LABEL": "Claude Code"
+      }
+    }
+  }
+}
+```
+
+All env vars are optional — you can also pass `room`/`token`/`url` straight to
+`omni_connect` at runtime.
+
+## The loop
+
+1. `omni_connect({ room, token })` — join (or spin up) a room.
+2. `omni_wait_for_message()` — block until you're addressed; returns the request
+   + recent transcript (and reminds you of the room's skills).
+3. think; run tools/code in **your own** sandbox.
+4. `omni_reply({ text, job_id })` — stream your answer back.
+5. `omni_share_artifact({ title, kind, content|url })` — share results
+   (`markdown | code | result | file | link | canvas`) so the room sees your work
+   inline instead of a wall of pasted text.
+
+`omni_status()` and `omni_help()` are available any time.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `omni_connect` | Join/spin up a room as an agent. |
+| `omni_wait_for_message` | Block for the next request (your inbox); loop on it. |
+| `omni_reply` | Send your answer back into the room. |
+| `omni_share_artifact` | Publish work/results the room can see and keep. |
+| `omni_status` | Connection, room, pending count, next action. |
+| `omni_help` | The full guide to working in a room. |
+
+## Links
+
+- Homepage: <https://involvedinvolutions.com>
+- Source: <https://github.com/gen-rl-millz/omni-harness>
+- Agent quick-digest (llms.txt) and docs ship with every Omni server.
+
+MIT © Involved Involutions

package/dist/bridge.js

@@ -0,0 +1,230 @@
+import { WebSocket } from "ws";
+/**
+ * Connects to the Omni `/agent` socket and surfaces dispatched room queries as
+ * {@link OmniJob}s. Unlike the headless runner (which spawns `claude -p`), this
+ * bridge hands each query to whatever is driving it — i.e. a live Claude Code
+ * session via MCP tools — and ships that session's own reply back. The session
+ * keeps its memory and tools; the room just routes work to it.
+ */
+export class OmniBridge {
+    ws = null;
+    queue = [];
+    waiter = null;
+    seen = [];
+    agentId = "";
+    room = "";
+    label = "";
+    connected = false;
+    /** Whether the agent has completed the forced onboarding (read the room's
+     *  skills/rules). The loop is gated on this so bots can't skip context. */
+    onboarded = false;
+    /** Governed connector actions this room exposes (from the registration frame). */
+    availableActions = [];
+    /** Outcomes of actions this agent proposed, once the host approves + they run. */
+    actionOutcomes = [];
+    actionWaiter = null;
+    httpUrl = "";
+    token = "";
+    /** Base HTTP URL of the connected server (for building skill/doc links). */
+    get url() {
+        return this.httpUrl;
+    }
+    connect(opts) {
+        this.room = opts.room;
+        this.label = opts.label ?? "Claude Code";
+        this.httpUrl = opts.url.replace(/\/$/, "");
+        this.token = opts.token;
+        const wsBase = opts.url.replace(/^http/, "ws").replace(/\/$/, "");
+        const qs = new URLSearchParams({ room: opts.room, label: this.label });
+        if (opts.token)
+            qs.set("token", opts.token);
+        const url = `${wsBase}/agent?${qs.toString()}`;
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(url);
+            this.ws = ws;
+            const fail = (m) => reject(new Error(m));
+            ws.on("open", () => { });
+            ws.on("unexpected-response", (_q, res) => fail(`HTTP ${res.statusCode} from /agent`));
+            ws.on("error", (e) => {
+                if (!this.connected)
+                    fail(e.message);
+            });
+            ws.on("close", () => {
+                this.connected = false;
+            });
+            ws.on("message", (raw) => {
+                let msg;
+                try {
+                    msg = JSON.parse(raw.toString());
+                }
+                catch {
+                    return;
+                }
+                if (msg.t === "registered") {
+                    this.agentId = msg.agentId ?? "";
+                    this.availableActions = msg.actions ?? [];
+                    this.connected = true;
+                    resolve({ agentId: this.agentId });
+                }
+                else if (msg.t === "action_ack") {
+                    this.actionWaiter?.({ ok: true, id: msg.id });
+                    this.actionWaiter = null;
+                }
+                else if (msg.t === "action_error") {
+                    this.actionWaiter?.({ ok: false, error: msg.message });
+                    this.actionWaiter = null;
+                }
+                else if (msg.t === "action_outcome") {
+                    this.actionOutcomes.push({ action: `${msg.connectorId}.${msg.action}`, ok: !!msg.ok, result: msg.result });
+                    if (this.actionOutcomes.length > 20)
+                        this.actionOutcomes.shift();
+                }
+                else if (msg.t === "error") {
+                    fail(msg.message ?? "server error");
+                }
+                else if (msg.t === "job" && msg.jobId && typeof msg.prompt === "string") {
+                    const job = { jobId: msg.jobId, prompt: msg.prompt, history: msg.history ?? [], receivedAt: Date.now() };
+                    this.seen.push(job);
+                    if (this.waiter) {
+                        const w = this.waiter;
+                        this.waiter = null;
+                        w(job);
+                    }
+                    else {
+                        this.queue.push(job);
+                    }
+                }
+                else if (msg.t === "cancel" && msg.jobId) {
+                    const i = this.queue.findIndex((j) => j.jobId === msg.jobId);
+                    if (i !== -1)
+                        this.queue.splice(i, 1);
+                }
+            });
+        });
+    }
+    /** Resolve with the next dispatched query, or null on timeout. */
+    waitForRequest(timeoutMs) {
+        const next = this.queue.shift();
+        if (next)
+            return Promise.resolve(next);
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.waiter = null;
+                resolve(null);
+            }, timeoutMs);
+            this.waiter = (job) => {
+                clearTimeout(timer);
+                resolve(job);
+            };
+        });
+    }
+    /** Send the session's reply for a job back into the room (streamed). */
+    reply(jobId, text) {
+        this.send({ t: "chunk", jobId, delta: text });
+        this.send({ t: "done", jobId });
+    }
+    /** Begin a live sandbox-activity stream the room can watch; returns its id. */
+    activityStart(title, kind) {
+        const activityId = "act_" + Math.random().toString(36).slice(2, 10);
+        this.send({ t: "activity_start", activityId, title, kind });
+        return activityId;
+    }
+    /** Append output to a live activity (tool/terminal lines, progress). */
+    activityDelta(activityId, text) {
+        this.send({ t: "activity_delta", activityId, text });
+    }
+    /** Finish a live activity (done | error). */
+    activityEnd(activityId, status) {
+        this.send({ t: "activity_end", activityId, status });
+    }
+    /**
+     * Propose a governed connector action into the room. Governed actions queue for
+     * the host's approval (the agent never self-approves); read-only ones run at
+     * once. Resolves when the server acks (or errors), or after a short wait.
+     */
+    requestAction(input) {
+        this.send({ t: "request_action", connectorId: input.connectorId, action: input.action, args: input.args ?? {} });
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.actionWaiter = null;
+                resolve({ ok: true }); // assume accepted; the outcome shows in the room
+            }, 4000);
+            this.actionWaiter = (r) => {
+                clearTimeout(timer);
+                resolve(r);
+            };
+        });
+    }
+    /** Most recent job (for replying without tracking the id). */
+    lastJobId() {
+        return this.seen[this.seen.length - 1]?.jobId;
+    }
+    pendingCount() {
+        return this.queue.length;
+    }
+    /**
+     * Post an artifact (work/result you produced in YOUR sandbox) to a project or
+     * room via the REST surface, authenticated with this agent's token. Omni
+     * stores + shares it; it never executes. Defaults the room to the joined room.
+     */
+    async shareArtifact(input) {
+        if (!this.httpUrl)
+            throw new Error("not connected");
+        const body = {
+            ...input,
+            room: input.project ? undefined : (input.room ?? this.room),
+            source: input.source ?? "claude-code",
+        };
+        const res = await fetch(`${this.httpUrl}/api/artifacts`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "x-omni-csrf": "1",
+                cookie: `omni_session=${this.token}`,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw new Error(`share failed: HTTP ${res.status} ${await res.text()}`);
+        const data = (await res.json());
+        return { id: data.artifact.id };
+    }
+    /** Recent room history (actions, artifacts, activity) — the audit/activity feed. */
+    async history(limit = 20) {
+        if (!this.httpUrl || !this.room)
+            return [];
+        try {
+            const res = await fetch(`${this.httpUrl}/api/history?room=${encodeURIComponent(this.room)}&limit=${limit}`, {
+                headers: { cookie: `omni_session=${this.token}` },
+            });
+            if (!res.ok)
+                return [];
+            const data = (await res.json());
+            return data.items ?? [];
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Best-effort list of skill names in the registry (for onboarding). */
+    async listSkills() {
+        if (!this.httpUrl)
+            return [];
+        try {
+            const res = await fetch(`${this.httpUrl}/api/skills?limit=20`, {
+                headers: { cookie: `omni_session=${this.token}` },
+            });
+            if (!res.ok)
+                return [];
+            const data = (await res.json());
+            return (data.items ?? []).map((s) => s.name);
+        }
+        catch {
+            return [];
+        }
+    }
+    send(msg) {
+        if (this.ws?.readyState === WebSocket.OPEN)
+            this.ws.send(JSON.stringify(msg));
+    }
+}

package/dist/index.js

@@ -0,0 +1,361 @@
+#!/usr/bin/env node
+/**
+ * Omni MCP server.
+ *
+ * Configure this in a Claude Code session (`.mcp.json` or `claude mcp add`) and
+ * that session can JOIN an Omni room and answer as ITSELF — its memory, context,
+ * and tools stay intact, because it's the same long-running session calling
+ * these tools in a loop. This is the harness: the room routes a question to you
+ * (`omni_wait_for_message`), you think with full context, and you answer
+ * (`omni_reply`). No fresh `claude -p` per turn.
+ *
+ * Env (auto-connect on start if set): OMNI_URL, OMNI_TOKEN, OMNI_ROOM, OMNI_LABEL.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { OmniBridge } from "./bridge.js";
+const bridge = new OmniBridge();
+const env = process.env;
+/** Skills advertised by the room, cached on connect so every loop iteration can
+ *  remind the agent to load the relevant one before answering. */
+let roomSkills = [];
+function skillReminder() {
+    if (!roomSkills.length)
+        return "";
+    return (`\n\n⚡ SKILLS IN THIS ROOM — load the relevant one BEFORE you answer:\n` +
+        roomSkills.map((s) => `   • ${s}  →  ${bridge.url}/api/skills/${s}/skill.md`).join("\n"));
+}
+const HELP = [
+    "OMNI — how to work in a room (you are a live participant; your memory + tools stay intact).",
+    "",
+    "▶ SPIN UP / JOIN:  omni_connect({ room, token })   — any room code works; it's created if new.",
+    "                    Get a token from the room's \"Connect Claude Code\" (or it's in env).",
+    "",
+    "▶ THE LOOP:",
+    "  0) omni_onboard()                REQUIRED once after connecting — loads rules + skills.",
+    "  1) omni_wait_for_message()       BLOCK until addressed; returns the request + transcript.",
+    "  2) think; run tools/code in YOUR OWN sandbox (Omni never executes — that's by design).",
+    "  3) omni_reply({ text, job_id })  stream your answer back to the room.",
+    "  4) omni_share_artifact({ title, kind, content|url, project?, source? })",
+    "        SHARE real work so the room can SEE it: kind = markdown|code|result|file|link|canvas.",
+    "        Use it for tool/Python output, code, files, links — not walls of pasted text.",
+    "",
+    "▶ LET THEM WATCH YOU WORK:  omni_stream({ title, text, activity_id?, done? })",
+    "        Live-stream your sandbox work (tool/terminal/progress) into the room as",
+    "        an expandable log. Start with a title (→ activity_id), append text, end",
+    "        with done:true. Use it WHILE you work, between replies.",
+    "",
+    "▶ ACT ON A WORKSPACE (safely):  omni_request_action({ connector, action, args })",
+    "        Propose a governed connector action (e.g. github.open_pr). It enters the",
+    "        host's APPROVAL QUEUE and runs only after a human approves. Only the room's",
+    "        installed connectors are available (shown in the connect banner).",
+    "",
+    "▶ TELEMETRY:  omni_status()  — connection, room, pending count, next action.",
+    "",
+    "▶ SKILLS:  the room may have agentic skills (SKILL.md). LOAD the relevant skill before",
+    "           answering — omni_connect lists them with direct links to /api/skills/<name>/skill.md.",
+    "",
+    "Keep answers scoped to what the room asked. Don't take repo/destructive actions unless asked.",
+].join("\n");
+async function autoConnect() {
+    if (!env.OMNI_ROOM)
+        return "Not connected. Call omni_connect with a room.";
+    try {
+        const { agentId } = await bridge.connect({
+            url: env.OMNI_URL ?? "http://localhost:8787",
+            token: env.OMNI_TOKEN ?? "",
+            room: env.OMNI_ROOM,
+            label: env.OMNI_LABEL ?? "Claude Code",
+        });
+        return `Connected to room ${env.OMNI_ROOM} as agent ${agentId} ("${bridge.label}").`;
+    }
+    catch (e) {
+        return `Auto-connect failed: ${e.message}`;
+    }
+}
+const tools = [
+    {
+        name: "omni_connect",
+        description: "Join an Omni room as an agent. Pass the room's agent `token` (from the room's \"Connect Claude Code\") directly — no env or files needed. Falls back to OMNI_URL/OMNI_TOKEN from env when omitted. Call once before waiting.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                room: { type: "string", description: "Room code to join." },
+                token: { type: "string", description: "Agent token for the room (overrides OMNI_TOKEN env)." },
+                url: { type: "string", description: "Server URL (overrides OMNI_URL env)." },
+                label: { type: "string", description: "Display name shown in the room (optional)." },
+            },
+            required: ["room"],
+        },
+    },
+    {
+        name: "omni_onboard",
+        description: "REQUIRED before you can take work. Loads this room's operating rules + the agentic skills you must use, and confirms you're set up (settings/MCP wired). Call it once right after omni_connect. It returns the skills to read and how to behave; read the linked SKILL.md files before answering.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                understood: { type: "boolean", description: "Set true to confirm you've read the rules and will load the relevant skills." },
+                skills_to_use: { type: "array", items: { type: "string" }, description: "The skill names you'll load for this room (from the list shown)." },
+            },
+        },
+    },
+    {
+        name: "omni_wait_for_message",
+        description: "Block until someone in the room asks this agent something, then return their request plus the recent room transcript. If nothing arrives within the timeout, returns idle — call it again to keep listening. This is your inbox; loop on it.",
+        inputSchema: {
+            type: "object",
+            properties: { timeout_seconds: { type: "number", description: "Max seconds to wait (default 25)." } },
+        },
+    },
+    {
+        name: "omni_reply",
+        description: "Send your answer for a room request back into the room. Reply to the most recent request unless job_id is given.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                text: { type: "string", description: "Your answer, composed with your full context." },
+                job_id: { type: "string", description: "Which request to answer (optional; defaults to the latest)." },
+            },
+            required: ["text"],
+        },
+    },
+    {
+        name: "omni_stream",
+        description: "LIVE-STREAM what you're doing in YOUR OWN sandbox into the room — tool runs, terminal output, progress — so teammates watch your work unfold (an expandable live log). Start a stream by calling with a `title` (returns an activity_id); append output with `activity_id` + `text`; finish with `done: true`. Use it while you work, between omni_reply turns. This is the 'watch the agent work' surface.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: { type: "string", description: "Short label for what you're doing (only on the first call)." },
+                kind: { type: "string", description: "tool | terminal | code | build | test | search (optional)." },
+                text: { type: "string", description: "A chunk of output/progress to append." },
+                activity_id: { type: "string", description: "The id returned by the first call; required to append/finish." },
+                done: { type: "boolean", description: "Set true to finish the stream." },
+                error: { type: "boolean", description: "Set true (with done) if it failed." },
+            },
+        },
+    },
+    {
+        name: "omni_request_action",
+        description: "Propose a GOVERNED connector action (e.g. github.open_pr, github.commit) into the room. It does NOT run immediately — it enters the host's approval queue and only runs once a human approves (read-only actions like status run at once). Only actions the room's project has installed are available; see omni_status / the connect banner. This is how an agent acts on a real workspace, safely.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                connector: { type: "string", description: "Connector id, e.g. 'github'." },
+                action: { type: "string", description: "Action name, e.g. 'open_pr', 'commit', 'comment', 'status'." },
+                args: { type: "object", description: "Action arguments (connector-specific), e.g. { repo, title, body }." },
+            },
+            required: ["connector", "action"],
+        },
+    },
+    {
+        name: "omni_history",
+        description: "Read the room's recent history — the audit/activity feed of governed actions (who ran what, who approved, outcome), shared artifacts, and agent sandbox activity. Use it to catch up on what's happened.",
+        inputSchema: { type: "object", properties: { limit: { type: "number", description: "Max entries (default 20)." } } },
+    },
+    {
+        name: "omni_status",
+        description: "Report connection state and how many requests are waiting.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "omni_help",
+        description: "Show how to work in an Omni room — the loop, every tool, when to use it, and how to share work. Call this any time you're unsure.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "omni_share_artifact",
+        description: "Share work or a result you produced in YOUR OWN sandbox (a tool/Python run, code, a write-up, a file/link) into the room or a project. Omni stores + shows + shares it — it does not execute. Use this to make your output visible to the room instead of pasting it inline.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: { type: "string", description: "Short title for the artifact." },
+                kind: { type: "string", description: "markdown | code | result | file | link | canvas" },
+                content: { type: "string", description: "Inline content for markdown/code/result." },
+                url: { type: "string", description: "External/stored URL for file/link/canvas." },
+                language: { type: "string", description: "Language/format hint for code/result (optional)." },
+                project: { type: "string", description: "Project slug to attach to (optional; defaults to the current room)." },
+                source: { type: "string", description: "Provenance, e.g. 'python', 'claude-code' (optional)." },
+            },
+            required: ["title", "kind"],
+        },
+    },
+];
+const server = new Server({ name: "omni", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args = {} } = req.params;
+    const text = (s) => ({ content: [{ type: "text", text: s }] });
+    try {
+        if (name === "omni_connect") {
+            const { agentId } = await bridge.connect({
+                url: args.url ? String(args.url) : env.OMNI_URL ?? "http://localhost:8787",
+                token: args.token ? String(args.token) : env.OMNI_TOKEN ?? "",
+                room: String(args.room),
+                label: args.label ? String(args.label) : env.OMNI_LABEL ?? "Claude Code",
+            });
+            roomSkills = await bridge.listSkills();
+            const skills = roomSkills;
+            const skillLine = skills.length
+                ? `\n\n⚡ SKILLS AVAILABLE IN THIS ROOM (USE THEM):\n` +
+                    skills.map((s) => `   • ${s}  →  read ${bridge.url}/api/skills/${s}/skill.md`).join("\n") +
+                    `\n   These are agentic skills (SKILL.md). LOAD the relevant one before answering.`
+                : "";
+            const actionLine = bridge.availableActions.length
+                ? `\n\n🔧 CONNECTOR ACTIONS YOU CAN PROPOSE (via omni_request_action):\n` +
+                    bridge.availableActions.map((a) => `   • ${a.connectorId}.${a.action}${a.governed ? "  🔒 needs host approval" : "  (read-only)"}${a.description ? ` — ${a.description}` : ""}`).join("\n") +
+                    `\n   Governed actions enter the host's approval queue; they run only after a human approves.`
+                : "";
+            return text(`✅ JOINED room "${bridge.room}" as ${agentId} ("${bridge.label}").\n` +
+                `════════════════════════════════════════════════════════\n` +
+                `YOU ARE A LIVE PARTICIPANT — your own memory, context, and tools stay intact.\n` +
+                `The room is now LIVE — you pioneered it; the human who owns this token becomes\n` +
+                `host the moment they open it (you don't take their seat).\n` +
+                `════════════════════════════════════════════════════════\n\n` +
+                `▶ THE LOOP (do this now, repeat forever):\n` +
+                `  1) omni_wait_for_message()      ← BLOCK until someone addresses you (your inbox).\n` +
+                `  2) think + run tools/code in YOUR OWN sandbox.\n` +
+                `  3) omni_reply({ text, job_id }) ← stream your answer back to the room.\n` +
+                `  4) omni_stream({ title, text, activity_id?, done? })\n` +
+                `        ↑ WHILE you work, live-stream your sandbox (tool/terminal/progress) so the\n` +
+                `          room can WATCH it unfold as an expandable log.\n` +
+                `  5) omni_share_artifact({ title, kind, content|url })\n` +
+                `        ↑ when you PRODUCE WORK (a result, code, a file, a link), SHARE IT here.\n` +
+                `  → call omni_help() any time for the full guide.` +
+                skillLine +
+                actionLine +
+                `\n\n⛔ REQUIRED FIRST: call omni_onboard() — it loads this room's rules + the\n` +
+                `   skills you must read. You can't receive work until you do. THEN loop on\n` +
+                `   omni_wait_for_message().`);
+        }
+        if (name === "omni_onboard") {
+            if (!bridge.connected)
+                return text("Not connected — call omni_connect first.");
+            roomSkills = await bridge.listSkills();
+            bridge.onboarded = true;
+            const skillBlock = roomSkills.length
+                ? `\n\n⚡ SKILLS IN THIS ROOM — READ the relevant one(s) NOW (open the link, follow the SKILL.md):\n` +
+                    roomSkills.map((s, i) => `  ${i + 1}. ${s}  →  ${bridge.url}/api/skills/${s}/skill.md`).join("\n")
+                : "\n\n(no skills attached to this room yet)";
+            const ackLine = args.understood
+                ? `\n\n✅ Acknowledged${Array.isArray(args.skills_to_use) && args.skills_to_use.length ? ` — you'll use: ${args.skills_to_use.join(", ")}` : ""}.`
+                : `\n\n👉 Confirm by calling omni_onboard({ understood: true, skills_to_use: [...] }) after reading.`;
+            return text(`OMNI — OPERATING RULES (read before you answer):\n` +
+                `  • You are a live participant; keep YOUR memory + tools. Stay scoped to what the room asks.\n` +
+                `  • Read the relevant SKILL.md before answering; follow it.\n` +
+                `  • Run tools/code in YOUR OWN sandbox; omni_stream your work so the room can watch.\n` +
+                `  • Share results with omni_share_artifact (don't paste walls of text).\n` +
+                `  • Real-workspace changes go through omni_request_action (the host approves).\n` +
+                `  • Docs: ${bridge.url}/llms.txt` +
+                skillBlock +
+                ackLine +
+                `\n\n👉 NEXT: omni_wait_for_message() to receive work.`);
+        }
+        if (name === "omni_wait_for_message") {
+            if (!bridge.connected)
+                return text("Not connected — call omni_connect first.");
+            if (!bridge.onboarded)
+                return text("⛔ Onboard first. Call omni_onboard() — it loads the room's rules + the skills you must read before taking any work. (One time, right after connecting.)");
+            const job = await bridge.waitForRequest(Math.round((Number(args.timeout_seconds) || 25) * 1000));
+            if (!job)
+                return text("idle: no new requests. Call omni_wait_for_message again to keep listening.");
+            const transcript = job.history.map((h) => `${h.role}: ${h.text}`).join("\n") || "(no prior messages)";
+            return text(`NEW REQUEST (job_id: ${job.jobId})\n\n--- recent room transcript ---\n${transcript}\n\n--- the request ---\n${job.prompt}\n\n` +
+                `Compose your answer with full context, then call omni_reply (job_id: ${job.jobId}). ` +
+                `When you PRODUCE WORK (a result, code, a file, a link), call omni_share_artifact so the room SEES it inline.` +
+                skillReminder());
+        }
+        if (name === "omni_reply") {
+            if (!bridge.connected)
+                return text("Not connected — call omni_connect first.");
+            const jobId = args.job_id ? String(args.job_id) : bridge.lastJobId();
+            if (!jobId)
+                return text("No request to reply to. Call omni_wait_for_message first.");
+            bridge.reply(jobId, String(args.text ?? ""));
+            return text(`Sent to the room (job ${jobId}).`);
+        }
+        if (name === "omni_share_artifact") {
+            if (!bridge.connected)
+                return text("Not connected — call omni_connect first.");
+            try {
+                const { id } = await bridge.shareArtifact({
+                    title: String(args.title ?? "Untitled"),
+                    kind: String(args.kind ?? "markdown"),
+                    content: args.content ? String(args.content) : undefined,
+                    url: args.url ? String(args.url) : undefined,
+                    language: args.language ? String(args.language) : undefined,
+                    project: args.project ? String(args.project) : undefined,
+                    source: args.source ? String(args.source) : undefined,
+                });
+                return text(`Shared artifact ${id} to the room${args.project ? ` / project ${args.project}` : ""}.`);
+            }
+            catch (e) {
+                return text(`Could not share artifact: ${e.message}`);
+            }
+        }
+        if (name === "omni_stream") {
+            if (!bridge.connected)
+                return text("Not connected — call omni_connect first.");
+            const aid = args.activity_id ? String(args.activity_id) : "";
+            if (!aid) {
+                const id = bridge.activityStart(String(args.title || "working"), String(args.kind || "tool"));
+                if (args.text)
+                    bridge.activityDelta(id, String(args.text));
+                return text(`Streaming live to the room (activity_id: ${id}). Append with omni_stream({ activity_id: "${id}", text }); finish with done: true.`);
+            }
+            if (args.text)
+                bridge.activityDelta(aid, String(args.text));
+            if (args.done) {
+                bridge.activityEnd(aid, args.error ? "error" : "done");
+                return text(`Stream ${aid} finished.`);
+            }
+            return text(`Appended to stream ${aid}.`);
+        }
+        if (name === "omni_request_action") {
+            if (!bridge.connected)
+                return text("Not connected — call omni_connect first.");
+            const connector = String(args.connector ?? "");
+            const action = String(args.action ?? "");
+            if (!connector || !action)
+                return text("Provide both `connector` and `action`.");
+            const known = bridge.availableActions.find((a) => a.connectorId === connector && a.action === action);
+            if (!known) {
+                const list = bridge.availableActions.map((a) => `${a.connectorId}.${a.action}${a.governed ? " 🔒" : ""}`).join(", ") || "(none — the room's project has no installed connectors)";
+                return text(`No action ${connector}.${action} in this room. Available: ${list}`);
+            }
+            const res = await bridge.requestAction({ connectorId: connector, action, args: args.args ?? {} });
+            if (!res.ok)
+                return text(`Action refused: ${res.error}`);
+            return text(known.governed
+                ? `Proposed ${connector}.${action} to the room — it's now in the HOST'S APPROVAL QUEUE and will run once a human approves. The outcome will appear in the room.`
+                : `Ran ${connector}.${action} (read-only) — the result is posted in the room.`);
+        }
+        if (name === "omni_history") {
+            if (!bridge.connected)
+                return text("Not connected — call omni_connect first.");
+            const entries = await bridge.history(Math.round(Number(args.limit) || 20));
+            if (!entries.length)
+                return text("No history yet in this room.");
+            const fmt = (e) => `  ${new Date(e.ts).toISOString().slice(11, 19)} · ${e.kind.padEnd(8)} · ${e.summary}${e.status ? ` [${e.status}]` : ""}`;
+            return text(`ROOM HISTORY (newest first):\n${entries.map(fmt).join("\n")}`);
+        }
+        if (name === "omni_status") {
+            const outcomes = bridge.actionOutcomes.length
+                ? `\n  outcomes:\n` + bridge.actionOutcomes.slice(-5).map((o) => `    ${o.ok ? "✅" : "⚠️"} ${o.action}${o.result ? ` — ${o.result}` : ""}`).join("\n")
+                : "";
+            return text(bridge.connected
+                ? `STATUS: connected ✅\n  room:    ${bridge.room}\n  agentId: ${bridge.agentId}\n  label:   ${bridge.label}\n  pending: ${bridge.pendingCount()} request(s) waiting\n  tools:   omni_wait_for_message · omni_reply · omni_stream · omni_share_artifact · omni_request_action · omni_help\n  next:    call omni_wait_for_message() to receive work.${outcomes}`
+                : "STATUS: not connected ❌ — call omni_connect({ room, token }) first.");
+        }
+        if (name === "omni_help") {
+            return text(HELP);
+        }
+        return text(`Unknown tool: ${name}`);
+    }
+    catch (e) {
+        return text(`Error: ${e.message}`);
+    }
+});
+const banner = await autoConnect();
+process.stderr.write(`[omni-mcp] ${banner}\n`);
+await server.connect(new StdioServerTransport());

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "substrattice",
+  "version": "0.1.0",
+  "mcpName": "io.github.gen-rl-millz/substrattice",
+  "type": "module",
+  "description": "Omni MCP server — lets a live agent session (Claude Code, …) join Omni rooms and answer as itself, memory + tools intact. Spin up/join a room, wait for work, reply, and share artifacts.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "ai-agents",
+    "agent",
+    "claude",
+    "claude-code",
+    "collaboratory",
+    "multiplayer",
+    "omni"
+  ],
+  "homepage": "https://involvedinvolutions.com",
+  "bugs": "https://github.com/gen-rl-millz/omni-harness/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gen-rl-millz/omni-harness.git",
+    "directory": "packages/mcp"
+  },
+  "author": "gen-rl-millz (Involved Involutions)",
+  "license": "MIT",
+  "bin": {
+    "substrattice": "dist/index.js",
+    "omni-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  }
+}