substrattice 0.1.4 → 0.1.5

package/README.md

@@ -62,6 +62,7 @@ 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. Accepts `role` (planner/coder/reviewer…) and a stable wake `key` so a reconnect reclaims your slot + queued work. |
+| `omni_onboard` | **Gated** comprehension check (multiple-choice on the token model, rules/docs, and room skills). Call with no args for questions; resubmit `answers` to pass — you can't take work until you do. |
 | `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). |

package/dist/bridge.js

@@ -19,6 +19,10 @@ export class OmniBridge {
     /** 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;
+    /** Expected answer letters for the in-flight onboarding quiz (set when the
+     *  questions are issued, checked when the agent submits — a real comprehension
+     *  gate, not a rubber stamp). Empty when no quiz is pending. */
+    onboardExpected = [];
     /** Governed connector actions this room exposes (from the registration frame). */
     availableActions = [];
     /** Outcomes of actions this agent proposed, once the host approves + they run. */

package/dist/index.js

@@ -17,6 +17,62 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import { OmniBridge } from "./bridge.js";
 const bridge = new OmniBridge();
 const env = process.env;
+/**
+ * Build the onboarding comprehension quiz — a real, context-forcing gate. Each
+ * question's options are shuffled, so the correct letter varies per call (a bot
+ * can't memorize answers); the expected letters are returned for grading. Mixes
+ * checks on the **token**, the **operating rules/docs**, and the room's **skills**.
+ */
+function buildOnboardQuiz(url, skills) {
+    const base = [
+        {
+            prompt: "How does a headless agent obtain an agent token for this server?",
+            correct: "Sign in, then GET /api/auth/agent-token (or use the room's \"Connect Claude Code\").",
+            distractors: ["Hardcode any random string — tokens aren't checked.", "Reuse your OPENAI_API_KEY.", "Tokens are optional when the server requires auth."],
+        },
+        {
+            prompt: "How do you make work you produced VISIBLE to the room?",
+            correct: "Call omni_share_artifact (and omni_stream to show progress).",
+            distractors: ["Paste the entire output as a chat reply.", "Commit it to git and hope they look.", "You can't — the room is read-only to agents."],
+        },
+        {
+            prompt: "When do you actually receive work?",
+            correct: "When you're @-tagged (delivered via omni_wait_for_message); untagged messages are just chat.",
+            distractors: ["On every message anyone posts in the room.", "Only while you are the room host.", "Never — you must poll the repo yourself."],
+        },
+        {
+            prompt: "A change to a REAL workspace (commit, open a PR) must:",
+            correct: "go through omni_request_action — it enters the host's approval queue.",
+            distractors: ["be pushed straight to main, fast.", "be done silently so nobody is bothered.", "be pasted into chat as a diff."],
+        },
+    ];
+    if (skills.length) {
+        base.push({
+            prompt: `This room has skills (${skills.slice(0, 3).join(", ")}${skills.length > 3 ? "…" : ""}). Before answering a task they cover, you:`,
+            correct: `read the relevant SKILL.md (${url}/api/skills/<name>/skill.md) and follow it.`,
+            distractors: ["ignore them and answer from memory.", "ask the host to read it and summarize.", "guess, then apologize if wrong."],
+        });
+    }
+    const L = ["A", "B", "C", "D"];
+    const expected = [];
+    const lines = [];
+    base.forEach((q, qi) => {
+        const opts = [q.correct, ...q.distractors];
+        for (let i = opts.length - 1; i > 0; i--) {
+            const j = Math.floor(Math.random() * (i + 1));
+            [opts[i], opts[j]] = [opts[j], opts[i]];
+        }
+        expected.push(L[opts.indexOf(q.correct)]);
+        lines.push(`Q${qi + 1}. ${q.prompt}`);
+        opts.forEach((o, oi) => lines.push(`   ${L[oi]}) ${o}`));
+    });
+    return {
+        text: `🧭 ONBOARDING CHECK — answer to unlock work (this forces real context, not a rubber stamp).\n` +
+            `Read ${url}/llms.txt and any room skills first, then answer ALL questions.\n\n` +
+            lines.join("\n"),
+        expected,
+    };
+}
 /** 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 = [];
@@ -33,7 +89,8 @@ const HELP = [
     "                    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.",
+    "  0) omni_onboard()                REQUIRED — a multiple-choice check on rules/skills/token;",
+    "                                   read /llms.txt + skills, then omni_onboard({ answers:[...] }) to pass.",
     "  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.",
@@ -107,12 +164,11 @@ const tools = [
     },
     {
         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.",
+        description: "REQUIRED before you can take work — a real comprehension GATE, not a rubber stamp. Call with NO args to get a short multiple-choice check on the room's token model, operating rules/docs, and attached skills; read /llms.txt and the SKILL.md files, then call again with `answers` (letters, in order). You're unlocked only when you pass; wrong answers re-issue a fresh set.",
         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)." },
+                answers: { type: "array", items: { type: "string" }, description: "Your chosen option letters in question order, e.g. [\"A\",\"C\",\"B\",\"D\"]. Omit on the first call to receive the questions." },
             },
         },
     },
@@ -315,24 +371,40 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
             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.`);
+            const rawAnswers = args.answers;
+            const answers = Array.isArray(rawAnswers)
+                ? rawAnswers.map((a) => String(a).trim().toUpperCase().charAt(0))
+                : null;
+            // Phase 2 — grade a submission.
+            if (answers && bridge.onboardExpected.length) {
+                const expected = bridge.onboardExpected;
+                const wrong = [];
+                for (let i = 0; i < expected.length; i++)
+                    if ((answers[i] ?? "") !== expected[i])
+                        wrong.push(i + 1);
+                if (wrong.length) {
+                    return text(`❌ Not yet — question(s) ${wrong.join(", ")} are wrong (${expected.length - wrong.length}/${expected.length} correct).\n` +
+                        `Re-read ${bridge.url}/llms.txt${roomSkills.length ? " and the room's SKILL.md files" : ""}, then call omni_onboard() again for a FRESH set of questions.`);
+                }
+                bridge.onboarded = true;
+                bridge.onboardExpected = [];
+                const skillBlock = roomSkills.length
+                    ? `\n⚡ Use these when they apply: ${roomSkills.map((s) => `${s} (${bridge.url}/api/skills/${s}/skill.md)`).join(", ")}.`
+                    : "";
+                return text(`✅ ONBOARDED — you passed the comprehension check.\n` +
+                    `Operating rules you just confirmed:\n` +
+                    `  • You only act when @-tagged; share work with omni_share_artifact; stream progress.\n` +
+                    `  • Real-workspace changes go through omni_request_action (host approves).\n` +
+                    `  • Async work waits in omni_inbox(); answer + omni_resolve_handoff.` +
+                    skillBlock +
+                    `\n\n👉 NEXT: omni_wait_for_message() to receive work (or omni_inbox() to catch up on async tasks).`);
+            }
+            // Phase 1 — issue a fresh quiz.
+            const quiz = buildOnboardQuiz(bridge.url, roomSkills);
+            bridge.onboardExpected = quiz.expected;
+            return text(quiz.text +
+                `\n\n👉 Submit IN ORDER: omni_onboard({ answers: ["A","C","B","D"${roomSkills.length ? ',"A"' : ""}] }). ` +
+                `You must pass to receive work.`);
         }
         if (name === "omni_wait_for_message") {
             if (!bridge.connected)

package/package.json

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