@miadi/stateloom-mcp 0.2.0 → 0.2.2

package/dist/projectSwitch.d.ts

@@ -8,4 +8,17 @@ export interface SwitchResult {
     /** True when the new path equals the previous one. */
     unchanged: boolean;
 }
+export declare function chronicleRoot(env?: Record<string, string | undefined>): string;
+/**
+ * Resolve `miadi-chronicle://<episode>/[diagrams/]<name>[.smdf.json]` to the
+ * absolute path `<root>/<episode-dir>/diagrams/<name>.smdf.json`.
+ *
+ * Episode matching: exact folder name first; else a bare number matches
+ * `-episode-NNN-` folders. Episode numbers are NOT unique in the chronicle
+ * (011, 016, 043, 078, 083, 098, 120 are doubled) — ambiguity is a HARD
+ * ERROR naming every candidate, never a silent first match: a resolver that
+ * guesses writes the wrong episode into the record. A missing diagram file
+ * stays legitimate — naming it is how an episode's FIRST diagram is created.
+ */
+export declare function resolveChronicleUri(uri: string, env?: Record<string, string | undefined>): string;
 export declare function resolveProjectSwitch(next: string, previous: string): SwitchResult;

package/dist/projectSwitch.js

@@ -1,11 +1,74 @@
 /**
  * Pure logic behind the `set_project_file` MCP tool (path power — the agent
  * chooses which `.smdf.json` document the loom weaves).
+ *
+ * Two modalities, by William's orientation (2026-08-07): STANDALONE — a plain
+ * path, no episode, just designing — and RELATIONAL — the document lives
+ * inside a chronicle episode and is addressed as
+ * `miadi-chronicle://<episode>/<diagram>`, resolving over
+ * $MIADI_CHRONICLE_ROOT to `<episode-dir>/diagrams/<diagram>.smdf.json`.
+ * The relationship is carried by WHERE the file lives (the scalar truth of
+ * jgwill/Miadi#593); wheel edges stay derived/ceremonial, never minted here.
  */
-import { existsSync } from "fs";
-import { resolve } from "path";
+import { existsSync, readdirSync, statSync } from "fs";
+import { join, resolve } from "path";
+const CHRONICLE_SCHEME = /^miadi-chronicle:\/\//i;
+export function chronicleRoot(env = process.env) {
+    return env.MIADI_CHRONICLE_ROOT ?? "/srv/miadi/episodes/miadi-chronicle";
+}
+/**
+ * Resolve `miadi-chronicle://<episode>/[diagrams/]<name>[.smdf.json]` to the
+ * absolute path `<root>/<episode-dir>/diagrams/<name>.smdf.json`.
+ *
+ * Episode matching: exact folder name first; else a bare number matches
+ * `-episode-NNN-` folders. Episode numbers are NOT unique in the chronicle
+ * (011, 016, 043, 078, 083, 098, 120 are doubled) — ambiguity is a HARD
+ * ERROR naming every candidate, never a silent first match: a resolver that
+ * guesses writes the wrong episode into the record. A missing diagram file
+ * stays legitimate — naming it is how an episode's FIRST diagram is created.
+ */
+export function resolveChronicleUri(uri, env = process.env) {
+    const rest = uri.replace(CHRONICLE_SCHEME, "").replace(/[?#].*$/, "");
+    const segments = rest.split("/").filter(Boolean);
+    if (segments.length < 2) {
+        throw new Error(`chronicle address needs <episode>/<diagram> (got '${uri}') — e.g. miadi-chronicle://103/film-preprod`);
+    }
+    const episodeRef = segments[0];
+    const name = segments[segments.length - 1];
+    const root = chronicleRoot(env);
+    let dirs;
+    try {
+        dirs = readdirSync(root).filter((d) => {
+            try {
+                return statSync(join(root, d)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        throw new Error(`chronicle root not readable: ${root} (MIADI_CHRONICLE_ROOT)`);
+    }
+    let matches = dirs.filter((d) => d === episodeRef);
+    if (matches.length === 0 && /^\d+$/.test(episodeRef)) {
+        const num = String(parseInt(episodeRef, 10));
+        matches = dirs.filter((d) => {
+            const m = d.match(/-episode-0*(\d+)-/);
+            return m !== null && m[1] === num;
+        });
+    }
+    if (matches.length === 0) {
+        throw new Error(`no episode matches '${episodeRef}' under ${root}`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`episode '${episodeRef}' is ambiguous — candidates:\n  ${matches.sort().join("\n  ")}\nName the full folder.`);
+    }
+    const file = name.endsWith(".json") ? name : `${name}.smdf.json`;
+    return join(root, matches[0], "diagrams", file);
+}
 export function resolveProjectSwitch(next, previous) {
-    const path = resolve(next);
+    const path = CHRONICLE_SCHEME.test(next) ? resolveChronicleUri(next) : resolve(next);
     if (!path.endsWith(".json")) {
         throw new Error(`project file must be a .json document (got '${path}') — the loom weaves .smdf.json files`);
     }

package/dist/server.js

@@ -47,6 +47,11 @@ import { resolveProjectSwitch } from "./projectSwitch.js";
 const BRIDGE_URL = envAlias("BRIDGE_URL");
 const AGENT_NAME = envAlias("AGENT_NAME");
 const BRIDGE_TOKEN = envAlias("BRIDGE_TOKEN");
+// The canvas address for a document (chart_1785683055671): when the agent
+// re-points the loom, the human gets a link to LOOK at the same document —
+// the `?doc=` parameter is resolved and allowlist-guarded by the web side.
+const CANVAS_URL = envAlias("CANVAS_URL") ?? `http://127.0.0.1:${envAlias("WEB_PORT") ?? "4598"}`;
+const canvasLink = (path) => `${CANVAS_URL}/?doc=${encodeURIComponent(path)}`;
 // ─── File-backed shared store ────────────────────────────────────────
 // Both web/ and mcp/ resolve the same path from STATELOOM_PROJECT_FILE
 // (legacy twin SMCRAFT_PROJECT_FILE still honored).
@@ -782,7 +787,7 @@ function buildServer() {
             return { content: [{ type: "text", text: "No events defined yet." }] };
         return { content: [{ type: "text", text: events.join("\n") }] };
     });
-    server.tool("set_project_file", "Choose which .smdf.json path is the active document the loom weaves. Disk persistence AND the live bridge room (the hub keys rooms by this path) both re-point to it. A missing file is legitimate — create_state_machine or load_definition writes it next. Path must end in .json; convention is *.smdf.json.", { path: z.string() }, async ({ path }) => {
+    server.tool("set_project_file", "Choose the active document the loom weaves — two modalities. STANDALONE: any .smdf.json path. RELATIONAL: a chronicle address `miadi-chronicle://<episode>/<diagram>` resolving over $MIADI_CHRONICLE_ROOT to <episode-dir>/diagrams/<diagram>.smdf.json — an ambiguous episode number is a hard error naming the candidates. Disk persistence AND the live bridge room both re-point. A missing file is legitimate — naming it is how an episode's first diagram is created.", { path: z.string() }, async ({ path }) => {
         try {
             const r = resolveProjectSwitch(path, PROJECT_FILE);
             const denial = denyProjectSwitch(r.path);
@@ -808,7 +813,7 @@ function buildServer() {
                 content: [
                     {
                         type: "text",
-                        text: `Active document: ${r.path}\nPrevious: ${r.previous}\n${summary}\n${bridgeNote}`,
+                        text: `Active document: ${r.path}\nPrevious: ${r.previous}\n${summary}\n${bridgeNote}\nCanvas: ${canvasLink(r.path)}`,
                     },
                 ],
             };
@@ -832,7 +837,7 @@ function buildServer() {
             : "bridge not configured (STATELOOM_BRIDGE_URL unset)";
         return {
             content: [
-                { type: "text", text: `Active document: ${PROJECT_FILE}\n${summary}\n${bridgeNote}` },
+                { type: "text", text: `Active document: ${PROJECT_FILE}\n${summary}\n${bridgeNote}\nCanvas: ${canvasLink(PROJECT_FILE)}` },
             ],
         };
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miadi/stateloom-mcp",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "MCP server for miadi-stateloom (formerly smcraft-mcp) — lets LLM agents design state machines through conversation",
   "repository": {
     "type": "git",