substrattice 0.1.1 → 0.1.3

package/README.md

@@ -61,12 +61,18 @@ All env vars are optional — you can also pass `room`/`token`/`url` straight to
 
 | 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_connect` | Join/spin up a room as an agent. Accepts `role` (planner/coder/reviewer…) and a stable wake `key` so a reconnect reclaims your slot + queued work. |
+| `omni_wait_for_message` | Block for the next live request; loop on it. |
 | `omni_reply` | Send your answer back into the room. |
+| `omni_inbox` | Your **async** inbox — open work left for you/your role to answer later (even when you were offline). |
+| `omni_leave_handoff` | Leave async work for a teammate or another AI role to pick up later (linked to a repo/url/artifact). |
+| `omni_resolve_handoff` | Progress/answer a handoff: in_progress / done (attach the result artifact) / cancelled. |
 | `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. |
+| `omni_edit_artifact` | Co-edit a shared artifact (collaborative coding); bumps its version, optimistic concurrency. |
+| `omni_request_action` | Propose a governed connector action (e.g. github.open_pr) into the host approval queue. |
+| `omni_stream` | Live-stream your sandbox activity (tool/terminal/progress) into the room. |
+| `omni_upload` | Upload a real file as a downloadable artifact. |
+| `omni_status` / `omni_history` / `omni_help` | Connection state · room audit feed · the full guide. |
 
 ## Links
 

package/dist/bridge.js

@@ -14,6 +14,7 @@ export class OmniBridge {
     agentId = "";
     room = "";
     label = "";
+    role = "";
     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. */
@@ -32,10 +33,17 @@ export class OmniBridge {
     connect(opts) {
         this.room = opts.room;
         this.label = opts.label ?? "Claude Code";
+        this.role = opts.role ?? "";
         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.role)
+            qs.set("role", opts.role);
+        // Stable wake key: lets this runner reclaim its roster slot + drain queued
+        // work after a reconnect (the server also derives one from owner+role).
+        if (opts.key)
+            qs.set("key", opts.key);
         if (opts.token)
             qs.set("token", opts.token);
         const url = `${wsBase}/agent?${qs.toString()}`;
@@ -198,6 +206,128 @@ export class OmniBridge {
         const data = (await res.json());
         return { id: data.artifact.id };
     }
+    /** Fetch one artifact (e.g. to read the current version before co-editing). */
+    async getArtifact(artifactId) {
+        if (!this.httpUrl)
+            throw new Error("not connected");
+        const res = await fetch(`${this.httpUrl}/api/artifacts/${encodeURIComponent(artifactId)}`, {
+            headers: { cookie: `omni_session=${this.token}` },
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return data.artifact;
+    }
+    /** Co-edit a shared artifact (collaborative coding). Bumps its version; pass
+     *  `expectedVersion` for optimistic concurrency (409 if another edit landed). */
+    async editArtifact(input) {
+        if (!this.httpUrl)
+            throw new Error("not connected");
+        const body = {};
+        if (input.content !== undefined)
+            body.content = input.content;
+        if (input.title !== undefined)
+            body.title = input.title;
+        if (input.language !== undefined)
+            body.language = input.language;
+        if (input.expectedVersion !== undefined)
+            body.expectedVersion = input.expectedVersion;
+        const res = await fetch(`${this.httpUrl}/api/artifacts/${encodeURIComponent(input.id)}`, {
+            method: "PATCH",
+            headers: {
+                "content-type": "application/json",
+                "x-omni-csrf": "1",
+                cookie: `omni_session=${this.token}`,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw new Error(`edit failed: HTTP ${res.status} ${await res.text()}`);
+        const data = (await res.json());
+        return { id: data.artifact.id, version: data.artifact.version };
+    }
+    /** Your async **inbox**: open work left in this room addressed to your role (or
+     *  to "any" AI), waiting to be answered. This is how you "respond later". */
+    async inbox() {
+        if (!this.httpUrl || !this.room)
+            return [];
+        const roleQ = this.role ? `&toRole=${encodeURIComponent(this.role)}` : "";
+        const res = await fetch(`${this.httpUrl}/api/handoffs?room=${encodeURIComponent(this.room)}&status=open${roleQ}`, {
+            headers: { cookie: `omni_session=${this.token}` },
+        });
+        if (!res.ok)
+            throw new Error(`inbox failed: HTTP ${res.status} ${await res.text()}`);
+        const data = (await res.json());
+        return data.items;
+    }
+    /** Leave async work for a teammate or another AI role to pick up later. */
+    async leaveHandoff(input) {
+        if (!this.httpUrl)
+            throw new Error("not connected");
+        const body = { roomId: this.room, title: input.title, body: input.body };
+        if (input.toUserId)
+            body.toUserId = input.toUserId;
+        if (input.toAgentRole)
+            body.toAgentRole = input.toAgentRole;
+        if (input.repo)
+            body.repo = input.repo;
+        if (input.url)
+            body.url = input.url;
+        if (input.artifactId)
+            body.artifactId = input.artifactId;
+        const res = await fetch(`${this.httpUrl}/api/handoffs`, {
+            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(`leave failed: HTTP ${res.status} ${await res.text()}`);
+        const data = (await res.json());
+        return { id: data.handoff.id };
+    }
+    /** Answer (or progress) a handoff: mark it in_progress/done/cancelled, with an
+     *  optional result summary and the artifact you produced as the answer. */
+    async resolveHandoff(input) {
+        if (!this.httpUrl)
+            throw new Error("not connected");
+        const body = {};
+        if (input.status)
+            body.status = input.status;
+        if (input.result !== undefined)
+            body.result = input.result;
+        if (input.resultArtifactId)
+            body.resultArtifactId = input.resultArtifactId;
+        const res = await fetch(`${this.httpUrl}/api/handoffs/${encodeURIComponent(input.id)}`, {
+            method: "PATCH",
+            headers: { "content-type": "application/json", "x-omni-csrf": "1", cookie: `omni_session=${this.token}` },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw new Error(`resolve failed: HTTP ${res.status} ${await res.text()}`);
+        const data = (await res.json());
+        return { id: data.handoff.id, status: data.handoff.status };
+    }
+    /** Upload a FILE into the room (a real downloadable file artifact). Text by
+     *  default; pass base64 for binary. Returns the created artifact id. */
+    async uploadFile(input) {
+        if (!this.httpUrl)
+            throw new Error("not connected");
+        const bytes = Buffer.from(input.content, input.base64 ? "base64" : "utf8");
+        const res = await fetch(`${this.httpUrl}/api/uploads?room=${encodeURIComponent(this.room)}`, {
+            method: "POST",
+            headers: {
+                "x-omni-csrf": "1",
+                "content-type": input.contentType ?? "text/plain; charset=utf-8",
+                "x-filename": encodeURIComponent(input.filename),
+                cookie: `omni_session=${this.token}`,
+            },
+            body: bytes,
+        });
+        if (!res.ok)
+            throw new Error(`upload 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)

package/dist/index.js

@@ -9,7 +9,7 @@
  * (`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.
+ * Env (auto-connect on start if set): OMNI_URL, OMNI_TOKEN, OMNI_ROOM, OMNI_LABEL, OMNI_ROLE, OMNI_AGENT_KEY.
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -67,6 +67,8 @@ async function autoConnect() {
             token: env.OMNI_TOKEN ?? "",
             room: env.OMNI_ROOM,
             label: env.OMNI_LABEL ?? "Claude Code",
+            role: env.OMNI_ROLE,
+            key: env.OMNI_AGENT_KEY,
         });
         return `Connected to room ${env.OMNI_ROOM} as agent ${agentId} ("${bridge.label}").`;
     }
@@ -85,6 +87,8 @@ const tools = [
                 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)." },
+                role: { type: "string", description: "Declared role for this agent (e.g. planner, coder, reviewer) — shown in the roster (optional)." },
+                key: { type: "string", description: "Stable wake key (optional) — reconnecting with the same key reclaims this agent's roster slot and drains work queued while it was offline." },
             },
             required: ["room"],
         },
@@ -148,6 +152,56 @@ const tools = [
             required: ["connector", "action"],
         },
     },
+    {
+        name: "omni_upload",
+        description: "Upload a FILE into the room — a real, downloadable file artifact (code, a doc, data), not pasted text. Provide a filename + content (text); set base64:true for binary. Use this to hand a teammate an actual file.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                filename: { type: "string", description: "File name, e.g. parser.ts or report.md." },
+                content: { type: "string", description: "File contents (utf-8 text, or base64 if base64:true)." },
+                content_type: { type: "string", description: "MIME type (optional), e.g. text/markdown." },
+                base64: { type: "boolean", description: "True if content is base64-encoded binary." },
+            },
+            required: ["filename", "content"],
+        },
+    },
+    {
+        name: "omni_inbox",
+        description: "Your ASYNC INBOX: open work other people left in this room for you (or your role) to answer LATER — even when they're not around. Call this on connect and whenever you catch up. Each item has a title, body, and optional linked repo/url/artifact. Do the work in your own environment, share results with omni_share_artifact, then close it with omni_resolve_handoff. This is how async, leave-it-and-walk-away collaboration works.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "omni_leave_handoff",
+        description: "Leave ASYNC WORK for a teammate or another AI role to pick up later (without them being live). Provide a title + body; optionally address a person (to_user_id), an AI role (to_agent_role, e.g. 'coder' or 'any'), and link a repo/url/artifact. The work waits durably in the room until it's answered.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: { type: "string", description: "Short headline for the work." },
+                body: { type: "string", description: "Describe the task / leave the message." },
+                to_user_id: { type: "string", description: "Address a specific teammate (account id), optional." },
+                to_agent_role: { type: "string", description: "Address an AI role (e.g. coder, reviewer) or 'any', optional." },
+                repo: { type: "string", description: "Linked repo (owner/name or URL), optional." },
+                url: { type: "string", description: "Any external link, optional." },
+                artifact_id: { type: "string", description: "A related artifact id (the spec/input), optional." },
+            },
+            required: ["title", "body"],
+        },
+    },
+    {
+        name: "omni_resolve_handoff",
+        description: "Progress or ANSWER a handoff from your inbox: set status to in_progress (you're on it), done (answered — attach the result artifact you produced), or cancelled. Include a short result summary so the room sees what you did.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Handoff id (from omni_inbox)." },
+                status: { type: "string", description: "in_progress | done | cancelled" },
+                result: { type: "string", description: "Short summary of the answer/outcome." },
+                result_artifact_id: { type: "string", description: "The artifact you produced as the answer (from omni_share_artifact)." },
+            },
+            required: ["id"],
+        },
+    },
     {
         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.",
@@ -180,6 +234,21 @@ const tools = [
             required: ["title", "kind"],
         },
     },
+    {
+        name: "omni_edit_artifact",
+        description: "Co-edit a SHARED artifact in the room (collaborative coding): replace its content/title/language. Bumps its version and updates it live for everyone — multiple agents and humans can iterate on the same code/doc. Best practice: read it first (you get its version), then pass expected_version so a concurrent edit can't silently clobber yours (a conflict returns 409 — re-read and retry).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Artifact id to edit (from omni_share_artifact or a shared card)." },
+                content: { type: "string", description: "New full content (replaces the prior text)." },
+                title: { type: "string", description: "New title (optional)." },
+                language: { type: "string", description: "New language/format hint (optional)." },
+                expected_version: { type: "number", description: "The version you edited (optimistic concurrency; 409 if it moved on)." },
+            },
+            required: ["id"],
+        },
+    },
 ];
 const server = new Server({ name: "omni", version: "0.1.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
@@ -193,6 +262,8 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
                 token: args.token ? String(args.token) : env.OMNI_TOKEN ?? "",
                 room: String(args.room),
                 label: args.label ? String(args.label) : env.OMNI_LABEL ?? "Claude Code",
+                role: args.role ? String(args.role) : env.OMNI_ROLE,
+                key: args.key ? String(args.key) : env.OMNI_AGENT_KEY,
             });
             roomSkills = await bridge.listSkills();
             const skills = roomSkills;
@@ -293,6 +364,79 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
                 return text(`Could not share artifact: ${e.message}`);
             }
         }
+        if (name === "omni_edit_artifact") {
+            if (!bridge.connected)
+                return text("Not connected — call omni_connect first.");
+            const aid = String(args.id ?? "");
+            if (!aid)
+                return text("Provide the artifact `id` to edit.");
+            try {
+                const { id, version } = await bridge.editArtifact({
+                    id: aid,
+                    content: args.content !== undefined ? String(args.content) : undefined,
+                    title: args.title !== undefined ? String(args.title) : undefined,
+                    language: args.language !== undefined ? String(args.language) : undefined,
+                    expectedVersion: args.expected_version !== undefined ? Number(args.expected_version) : undefined,
+                });
+                return text(`Edited artifact ${id} → version ${version}. Everyone in the room sees the update live.`);
+            }
+            catch (e) {
+                return text(`Could not edit artifact: ${e.message} (on a version conflict, re-fetch with omni_history/the shared card and retry).`);
+            }
+        }
+        if (name === "omni_inbox") {
+            if (!bridge.connected)
+                return text("Not connected — call omni_connect first.");
+            try {
+                const items = await bridge.inbox();
+                if (items.length === 0)
+                    return text("📭 Your async inbox is empty — no open work left for you in this room.");
+                const lines = items.map((h) => `• [${h.id}] ${h.title}${h.toAgentRole ? ` (for @${h.toAgentRole})` : ""}\n    ${h.body.slice(0, 240)}${h.body.length > 240 ? "…" : ""}` +
+                    `${h.repo ? `\n    repo: ${h.repo}` : ""}${h.url ? `\n    link: ${h.url}` : ""}${h.artifactId ? `\n    artifact: ${h.artifactId}` : ""}`);
+                return text(`📥 ${items.length} item(s) waiting for you:\n\n${lines.join("\n\n")}\n\nDo the work, share results with omni_share_artifact, then close with omni_resolve_handoff({ id, status: "done", result, result_artifact_id }).`);
+            }
+            catch (e) {
+                return text(`Could not read inbox: ${e.message}`);
+            }
+        }
+        if (name === "omni_leave_handoff") {
+            if (!bridge.connected)
+                return text("Not connected — call omni_connect first.");
+            try {
+                const { id } = await bridge.leaveHandoff({
+                    title: String(args.title ?? "Untitled"),
+                    body: String(args.body ?? ""),
+                    toUserId: args.to_user_id ? String(args.to_user_id) : undefined,
+                    toAgentRole: args.to_agent_role ? String(args.to_agent_role) : undefined,
+                    repo: args.repo ? String(args.repo) : undefined,
+                    url: args.url ? String(args.url) : undefined,
+                    artifactId: args.artifact_id ? String(args.artifact_id) : undefined,
+                });
+                return text(`Left async work ${id} in the room — it waits until it's picked up.`);
+            }
+            catch (e) {
+                return text(`Could not leave handoff: ${e.message}`);
+            }
+        }
+        if (name === "omni_resolve_handoff") {
+            if (!bridge.connected)
+                return text("Not connected — call omni_connect first.");
+            const hid = String(args.id ?? "");
+            if (!hid)
+                return text("Provide the handoff `id` to resolve.");
+            try {
+                const { id, status } = await bridge.resolveHandoff({
+                    id: hid,
+                    status: args.status ? String(args.status) : undefined,
+                    result: args.result !== undefined ? String(args.result) : undefined,
+                    resultArtifactId: args.result_artifact_id ? String(args.result_artifact_id) : undefined,
+                });
+                return text(`Handoff ${id} is now ${status}. The room sees the update.`);
+            }
+            catch (e) {
+                return text(`Could not resolve handoff: ${e.message}`);
+            }
+        }
         if (name === "omni_stream") {
             if (!bridge.connected)
                 return text("Not connected — call omni_connect first.");
@@ -330,6 +474,22 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
                 ? `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_upload") {
+            if (!bridge.connected)
+                return text("Not connected — call omni_connect first.");
+            try {
+                const { id } = await bridge.uploadFile({
+                    filename: String(args.filename || "file.txt"),
+                    content: String(args.content ?? ""),
+                    contentType: args.content_type ? String(args.content_type) : undefined,
+                    base64: !!args.base64,
+                });
+                return text(`Uploaded "${args.filename}" as a downloadable file artifact (${id}). The room can open/download it.`);
+            }
+            catch (e) {
+                return text(`Upload failed: ${e.message}`);
+            }
+        }
         if (name === "omni_history") {
             if (!bridge.connected)
                 return text("Not connected — call omni_connect first.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "substrattice",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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.",