@sapiom/harness 0.8.9 → 0.9.0

package/dist/server/studio-rail.js

@@ -0,0 +1,234 @@
+/**
+ * `.sapiom/studio-rail.json` — the Group axis's stored arrangement, one file
+ * per project root (SAP-2929; design.md § Persistence).
+ *
+ * This router is deliberately DUMB about the file's meaning. It reads, writes
+ * and removes an opaque UTF-8 blob; every rule about what the blob means —
+ * defensive parsing, pruning member paths no agent claims, and above all the
+ * difference between `groups: null` ("nothing stored, detection owns this") and
+ * `groups: []` ("the user materialized groups and then deleted them all") —
+ * lives in ONE place, `web/src/lib/agent-groups.ts`, where it is unit-tested.
+ *
+ * That split is the point. In the reference prototype the null/empty
+ * distinction was collapsed by a second, well-meaning serializer on the write
+ * path: the first page load wrote `groups: []` for a state that was `null`, and
+ * from the second load onward every agent fell into `Ungrouped`, in every
+ * project, permanently. A server that re-encodes the shape is a second place
+ * for that to happen. So the wire format here is `{ raw }` — the exact text —
+ * and "un-materialized" reaches disk as DELETE, never as a write.
+ *
+ * Containment: `root` must be a project root the studio actually knows about
+ * (`listKnownRoots`, injected — recentDirs, the configured project root, and
+ * live session cwds, which is exactly the set `web/src/lib/project-tree.ts`
+ * turns into project rows). Resolution happens before any disk access, so this
+ * route cannot be turned into an arbitrary-path file reader or writer. The
+ * written path is confined under `<root>/.sapiom/` by `resolveWithinRoot`, so a
+ * symlinked `.sapiom` cannot land the file outside the project.
+ *
+ * Mounted under the same `/api` boot-token middleware as the rest of the REST
+ * surface (server/index.ts).
+ */
+import * as path from "node:path";
+import * as fs from "node:fs/promises";
+import { Router } from "express";
+import { detectWorkflowLaunches } from "../core/canvas-interconnections.js";
+import { hasTraversalSegment, resolveWithinRoot } from "../core/path-safety.js";
+/** The directory the file lives in: already a live convention (canvas renders,
+ *  harness-context.json) and already skipped by every source scan. */
+const SAPIOM_DIR = ".sapiom";
+export const STUDIO_RAIL_FILE = "studio-rail.json";
+/**
+ * A stored arrangement is a handful of ids, labels and absolute paths. The cap
+ * is a backstop against a client (or a hand edit) turning a preferences file
+ * into a place to park a megabyte, not a real limit on how many groups a
+ * project may have.
+ */
+export const MAX_STUDIO_RAIL_BYTES = 256 * 1024;
+/** Trailing separators are spelling, not identity — `<root>/` and `<root>`
+ *  are one directory, and the client stores whichever the user typed. */
+const canonical = (p) => {
+    const resolved = path.resolve(p);
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+};
+/**
+ * The absolute, resolved root when `candidate` is a project root the studio
+ * knows about — null otherwise, which every route answers as a 400 rather than
+ * reaching for the disk.
+ */
+function resolveKnownRoot(candidate, knownRoots) {
+    if (typeof candidate !== "string" || candidate.trim() === "")
+        return null;
+    if (hasTraversalSegment(candidate))
+        return null;
+    if (!path.isAbsolute(candidate))
+        return null;
+    const wanted = canonical(candidate);
+    return knownRoots.some((root) => canonical(root) === wanted)
+        ? path.resolve(candidate)
+        : null;
+}
+/** `<root>/.sapiom/studio-rail.json`, or null if that escapes `root`. */
+export function studioRailPath(root) {
+    return resolveWithinRoot(root, path.join(SAPIOM_DIR, STUDIO_RAIL_FILE));
+}
+/**
+ * The stored blob, or null.
+ *
+ * An absent file, an unreadable directory and an oversized file all read as
+ * null — "nothing stored", which the model turns into the derived groups. A
+ * rail that throws on a bad preferences file is a rail you cannot open in order
+ * to fix it.
+ */
+export async function readStudioRailFile(root) {
+    const file = studioRailPath(root);
+    if (file == null)
+        return null;
+    try {
+        const stat = await fs.stat(file);
+        if (!stat.isFile() || stat.size > MAX_STUDIO_RAIL_BYTES)
+            return null;
+        return await fs.readFile(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Writes the blob verbatim, creating `.sapiom/` if it is not there yet. */
+export async function writeStudioRailFile(root, raw) {
+    const file = studioRailPath(root);
+    if (file == null)
+        throw new Error("studio-rail path escapes the project root");
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, raw, "utf8");
+}
+/**
+ * Removes the file. Missing is success: "there is no stored arrangement" is the
+ * requested end state, and DELETE is how an un-materialized state — including
+ * the one `Reset to detected` produces — reaches disk. Skipping the write
+ * instead would let the old arrangement outlive the reset.
+ */
+export async function removeStudioRailFile(root) {
+    const file = studioRailPath(root);
+    if (file == null)
+        return;
+    try {
+        await fs.rm(file);
+    }
+    catch {
+        // ENOENT and a read-only checkout alike: nothing stored is the goal state.
+    }
+}
+/**
+ * Launch edges across every registered agent, as parent-name to child-slug.
+ *
+ * Uses the shared syntax-only extractor (`core/canvas-interconnections.ts`) —
+ * the same detector the canvas and system graph use for agent relationships. A
+ * second edge detector would be a second answer to "what does this launch",
+ * and the Group axis and system graph are supposed to read one graph.
+ *
+ * `knownStepIds` is empty on purpose: that argument exists so a capability chip
+ * can be attributed to the step it sits in, and a group does not care which
+ * step launched the child, only that the launch exists.
+ *
+ * `child` is the `definition` slug as written at the call site. Matching it to
+ * an agent is the client's job (a slug can name an agent by `definitionSlug` or
+ * by folder name); the client ignores an unmatched slug.
+ */
+export async function detectLaunchEdges(workflows) {
+    const edges = [];
+    const seen = new Set();
+    for (const workflow of workflows) {
+        let launches;
+        try {
+            launches = await detectWorkflowLaunches(workflow.path, new Set());
+        }
+        catch {
+            continue;
+        }
+        for (const launch of launches) {
+            // A project that launches the same definition from three steps is ONE
+            // edge: the group is about the relationship, not its multiplicity.
+            const key = JSON.stringify([workflow.name, launch.slug]);
+            if (launch.slug === workflow.name || seen.has(key))
+                continue;
+            seen.add(key);
+            edges.push({ parent: workflow.name, child: launch.slug });
+        }
+    }
+    return edges;
+}
+/**
+ * GET    /api/studio-rail?root=abs   -> { root, raw: string | null }
+ * PUT    /api/studio-rail?root=abs   { raw } -> { ok: true }
+ * DELETE /api/studio-rail?root=abs   -> { ok: true }
+ * GET    /api/studio-rail/launch-edges -> { edges: [{ parent, child }] }
+ */
+export function createStudioRailRouter(deps) {
+    const router = Router();
+    // BEFORE the `?root=` routes: `/api/studio-rail/launch-edges` carries no
+    // root, and a root-less request must never be answered with a file read.
+    router.get("/api/studio-rail/launch-edges", async (_req, res, next) => {
+        try {
+            const edges = await detectLaunchEdges(deps.listWorkflows());
+            res.json({ edges });
+        }
+        catch (err) {
+            next(err);
+        }
+    });
+    router.get("/api/studio-rail", async (req, res, next) => {
+        const root = resolveKnownRoot(req.query.root, await deps.listKnownRoots());
+        if (root == null) {
+            res.status(400).json({ error: "root must be a known project root" });
+            return;
+        }
+        try {
+            res.json({
+                root,
+                raw: await readStudioRailFile(root),
+            });
+        }
+        catch (err) {
+            next(err);
+        }
+    });
+    router.put("/api/studio-rail", async (req, res, next) => {
+        const root = resolveKnownRoot(req.query.root, await deps.listKnownRoots());
+        if (root == null) {
+            res.status(400).json({ error: "root must be a known project root" });
+            return;
+        }
+        const raw = req.body?.raw;
+        if (typeof raw !== "string") {
+            res.status(400).json({ error: "raw must be a string" });
+            return;
+        }
+        if (Buffer.byteLength(raw, "utf8") > MAX_STUDIO_RAIL_BYTES) {
+            res.status(413).json({ error: "studio-rail.json is too large" });
+            return;
+        }
+        try {
+            await writeStudioRailFile(root, raw);
+            res.json({ ok: true });
+        }
+        catch (err) {
+            next(err);
+        }
+    });
+    router.delete("/api/studio-rail", async (req, res, next) => {
+        const root = resolveKnownRoot(req.query.root, await deps.listKnownRoots());
+        if (root == null) {
+            res.status(400).json({ error: "root must be a known project root" });
+            return;
+        }
+        try {
+            await removeStudioRailFile(root);
+            res.json({ ok: true });
+        }
+        catch (err) {
+            next(err);
+        }
+    });
+    return router;
+}
+//# sourceMappingURL=studio-rail.js.map

package/dist/server/studio-rail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"studio-rail.js","sourceRoot":"","sources":["../../src/server/studio-rail.ts"],"names":[],"mappings":"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"}

package/dist/server/system-graph.d.ts

@@ -0,0 +1,14 @@
+import { Router } from "express";
+import type { WorkspaceScope, WorkspaceScopeResolver } from "../core/system-graph.js";
+import type { SystemGraphStore } from "../core/system-graph-store.js";
+import { type SystemGraphSnapshot } from "../shared/system-graph.js";
+export interface SystemGraphRouterOptions {
+    scopeResolver: WorkspaceScopeResolver;
+    store: SystemGraphStore;
+    onScopeAccess?: (scope: WorkspaceScope) => void | Promise<void>;
+    /** Re-run registry prerequisites before an explicit user retry. */
+    onScopeRefresh?: (scope: WorkspaceScope) => SystemGraphSnapshot | Promise<SystemGraphSnapshot>;
+}
+/** Mounted beneath the boot-token-protected `/api` boundary. */
+export declare function createSystemGraphRouter(options: SystemGraphRouterOptions): Router;
+//# sourceMappingURL=system-graph.d.ts.map

package/dist/server/system-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-graph.d.ts","sourceRoot":"","sources":["../../src/server/system-graph.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EAIP,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EACV,cAAc,EACd,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AAEnC,MAAM,WAAW,wBAAwB;IACvC,aAAa,EAAE,sBAAsB,CAAC;IACtC,KAAK,EAAE,gBAAgB,CAAC;IACxB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,mEAAmE;IACnE,cAAc,CAAC,EAAE,CACf,KAAK,EAAE,cAAc,KAClB,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACzD;AAED,gEAAgE;AAChE,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,wBAAwB,GAChC,MAAM,CA4CR"}

package/dist/server/system-graph.js

@@ -0,0 +1,40 @@
+import { Router, } from "express";
+import { SYSTEM_GRAPH_CACHE_HEADER, } from "../shared/system-graph.js";
+/** Mounted beneath the boot-token-protected `/api` boundary. */
+export function createSystemGraphRouter(options) {
+    const router = Router();
+    const route = "/workspaces/:workspaceKey/system-graph";
+    const serve = async (req, res, next, refresh) => {
+        try {
+            const scope = await options.scopeResolver.resolve(req.params.workspaceKey);
+            if (!scope) {
+                res.status(404).json({ error: "Workspace not found" });
+                return;
+            }
+            try {
+                await options.onScopeAccess?.(scope);
+            }
+            catch {
+                // Watcher setup is best-effort. A graph read must remain available
+                // even when automatic freshness cannot be armed.
+            }
+            const snapshot = refresh
+                ? await (options.onScopeRefresh?.(scope) ??
+                    options.store.refresh(scope))
+                : await options.store.get(scope);
+            const cacheStatus = snapshot.state === "ready" ? "complete" : "degraded";
+            res.set(SYSTEM_GRAPH_CACHE_HEADER, cacheStatus).json(snapshot);
+        }
+        catch (err) {
+            next(err);
+        }
+    };
+    router.get(route, (req, res, next) => {
+        void serve(req, res, next, false);
+    });
+    router.post(`${route}/refresh`, (req, res, next) => {
+        void serve(req, res, next, true);
+    });
+    return router;
+}
+//# sourceMappingURL=system-graph.js.map

package/dist/server/system-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-graph.js","sourceRoot":"","sources":["../../src/server/system-graph.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,GAIP,MAAM,SAAS,CAAC;AAOjB,OAAO,EACL,yBAAyB,GAG1B,MAAM,2BAA2B,CAAC;AAYnC,gEAAgE;AAChE,MAAM,UAAU,uBAAuB,CACrC,OAAiC;IAEjC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,MAAM,KAAK,GAAG,wCAAwC,CAAC;IAEvD,MAAM,KAAK,GAAG,KAAK,EACjB,GAAY,EACZ,GAAa,EACb,IAAkB,EAClB,OAAgB,EACD,EAAE;QACjB,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,OAAO,CAC/C,GAAG,CAAC,MAAM,CAAC,YAAY,CACxB,CAAC;YACF,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC,CAAC;gBACvD,OAAO;YACT,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,OAAO,CAAC,aAAa,EAAE,CAAC,KAAK,CAAC,CAAC;YACvC,CAAC;YAAC,MAAM,CAAC;gBACP,mEAAmE;gBACnE,iDAAiD;YACnD,CAAC;YACD,MAAM,QAAQ,GAAG,OAAO;gBACtB,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,KAAK,CAAC;oBACpC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBACjC,CAAC,CAAC,MAAM,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,WAAW,GACf,QAAQ,CAAC,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC;YACvD,GAAG,CAAC,GAAG,CAAC,yBAAyB,EAAE,WAAW,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACjE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,GAAG,CAAC,CAAC;QACZ,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACnC,KAAK,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IACH,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACjD,KAAK,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/server/workflow-graph.d.ts

@@ -0,0 +1,43 @@
+import { type Router as ExpressRouter } from "express";
+import { type AgentProjectMarkerInspection } from "../core/agent-project-discovery.js";
+import { deriveWorkflowCanvas, type RenderableWorkflow } from "../core/canvas-render.js";
+import type { CanvasGraph } from "../core/canvas-graph.js";
+import type { CanvasEnrichment } from "../core/canvas-enrichment.js";
+/** Why a board is not a graph. `ok` is the only status carrying one. */
+export type WorkflowGraphStatus = "ok" | "empty" | "preparing" | "error";
+export interface WorkflowGraphResponse {
+    /** The resolved absolute agent directory the board was derived from. */
+    path: string;
+    /** The registry's display name — the board's panel title. */
+    name: string;
+    status: WorkflowGraphStatus;
+    /** The extracted graph; null for every status but "ok". */
+    graph: CanvasGraph | null;
+    /** Deterministic enrichment derived from `graph`; null when there is none. */
+    enrichment: CanvasEnrichment | null;
+    /** Human-readable explanation for "empty"/"error"; null otherwise. */
+    reason: string | null;
+    /** True when the graph came from the extraction cache — no child process ran. */
+    cached: boolean;
+    /**
+     * The finished canvas document, byte-identical to what `/canvas/:sessionId/`
+     * serves for a session bound to this workflow. Present for EVERY status —
+     * an empty board is still a renderable page, not a hole.
+     */
+    document: string;
+}
+export interface WorkflowGraphRouterDeps {
+    /**
+     * Resolves an absolute agent path against the live registry; null when the
+     * path is not registered. Called before anything touches disk.
+     */
+    resolveWorkflow(agentPath: string): RenderableWorkflow | null;
+    /** Seam for tests — defaults to the real `sapiom.json` inspection. */
+    inspectMarker?(dir: string): Promise<AgentProjectMarkerInspection>;
+    /** Seam for tests — defaults to the real derivation (which runs esbuild). */
+    deriveCanvas?: typeof deriveWorkflowCanvas;
+    /** Seam for tests — defaults to `fs.realpath`. */
+    realpath?(p: string): Promise<string>;
+}
+export declare function createWorkflowGraphRouter(deps: WorkflowGraphRouterDeps): ExpressRouter;
+//# sourceMappingURL=workflow-graph.d.ts.map

package/dist/server/workflow-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-graph.d.ts","sourceRoot":"","sources":["../../src/server/workflow-graph.ts"],"names":[],"mappings":"AA4DA,OAAO,EAAU,KAAK,MAAM,IAAI,aAAa,EAAE,MAAM,SAAS,CAAC;AAE/D,OAAO,EAEL,KAAK,4BAA4B,EAClC,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAE,oBAAoB,EAAE,KAAK,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACzF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAGrE,wEAAwE;AACxE,MAAM,MAAM,mBAAmB,GAAG,IAAI,GAAG,OAAO,GAAG,WAAW,GAAG,OAAO,CAAC;AAEzE,MAAM,WAAW,qBAAqB;IACpC,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,mBAAmB,CAAC;IAC5B,2DAA2D;IAC3D,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1B,8EAA8E;IAC9E,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACpC,sEAAsE;IACtE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,iFAAiF;IACjF,MAAM,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAAC;IAC9D,sEAAsE;IACtE,aAAa,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAAC;IACnE,6EAA6E;IAC7E,YAAY,CAAC,EAAE,OAAO,oBAAoB,CAAC;IAC3C,kDAAkD;IAClD,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvC;AAsDD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,uBAAuB,GAAG,aAAa,CA4FtF"}

package/dist/server/workflow-graph.js

@@ -0,0 +1,200 @@
+/**
+ * `GET /api/workflows/:path/graph` — the WORKFLOW-keyed canvas route (IA-01).
+ *
+ * The canvas has only ever been reachable through a session: boards live at
+ * `/canvas/:harnessSessionId/` and resolve by the session's current binding
+ * (server/canvas.ts), so an agent that has never hosted a session has no board
+ * at all. Reading agent F's board while working in agent B's session is
+ * therefore impossible, which is what the selection-driven rail needs.
+ *
+ * This route is the second, session-free entry point onto the SAME derivation.
+ * It renders nothing new: it calls `deriveWorkflowCanvas` (core/canvas-render.ts),
+ * the exact pipeline the write path uses, so `document` here is byte-identical
+ * to the render file a bound session's canvas serves for the same workflow.
+ * Nothing is written to disk.
+ *
+ * Keying: `:path` is the agent's absolute directory path, URI-encoded into one
+ * segment — `encodeURIComponent(agentPath)`, the same convention
+ * `/api/workflows/:id/input-contract` and `/api/workflows/:id/deploy` already
+ * use (web/src/lib/api.ts). Express matches on the raw path and decodes the
+ * param, so an encoded `/` never splits the route.
+ *
+ * Containment: the request string is a LOOKUP KEY AND NOTHING ELSE. It is
+ * matched against the live registry and then dropped; every filesystem call
+ * below runs on `workflow.path` — the path the registry itself authored when
+ * it scanned the disk. So the barrier is not "we checked the client's string
+ * carefully", it is "the client's string never reaches `fs`", which survives a
+ * future edit that reorders the checks and is a barrier static analysis can
+ * see rather than one it has to be told about.
+ *
+ * The lexical guards below (`..` segment, absolute-only) stay: they reject the
+ * escape shapes outright rather than let normalization quietly land them on
+ * some other registered path. Defence in depth, not the barrier. The marker's
+ * realpath is likewise confined to the agent directory, so a symlinked
+ * `sapiom.json` cannot turn this into a file reader.
+ *
+ * Failure modes are deliberately distinct, and every one of them is
+ * distinguishable from "no such route":
+ *
+ *   400  the path is missing, relative, or carries a `..` segment; or
+ *        `sapiom.json` resolves outside the agent directory
+ *   404  the path is not a registered workflow
+ *   200  `status: "empty"`    — registered, but no readable/parseable
+ *                               `sapiom.json` (absent ⇒ empty, not an error)
+ *   200  `status: "preparing"`— dependencies not installed yet
+ *   200  `status: "error"`    — extraction ran and failed; `reason` says why
+ *   200  `status: "ok"`       — graph + document
+ *
+ * EVERY failure below the registry lookup lands in that `error` shape. The
+ * derivation spawns a child process, parses a manifest this process did not
+ * write, and walks user directories that can EACCES — so it throws, and
+ * Express 4 does not catch a rejected async handler. Unhandled, Node's default
+ * `--unhandled-rejections=throw` takes the harness process down and the
+ * request is never answered: the canvas spins forever and then the studio
+ * dies. A board that cannot be derived is a board with a reason on it.
+ *
+ * Mounted under the same `/api` boot-token middleware as the rest of the REST
+ * surface (server/index.ts).
+ */
+import * as path from "node:path";
+import * as fsp from "node:fs/promises";
+import { Router } from "express";
+import { inspectAgentProjectMarker, } from "../core/agent-project-discovery.js";
+import { renderCanvasMessageDocument } from "../core/canvas-template.js";
+import { deriveWorkflowCanvas } from "../core/canvas-render.js";
+import { hasTraversalSegment, resolveWithinRoot } from "../core/path-safety.js";
+/** Why a registered agent has no graph, phrased for a person reading the pane. */
+const EMPTY_REASONS = {
+    gone: "This agent's directory is no longer on disk.",
+    absent: "This agent has no sapiom.json, so there is no graph to render yet.",
+    invalid: "This agent's sapiom.json is not valid JSON, so its graph can't be read.",
+    unreadable: "This agent's sapiom.json could not be read.",
+};
+/** The empty board — the same message document server/canvas.ts serves, with
+ *  the specific reason as its subtitle so the pane is never mutely blank. */
+function emptyResponse(agentPath, name, reason) {
+    return {
+        path: agentPath,
+        name,
+        status: "empty",
+        graph: null,
+        enrichment: null,
+        reason,
+        cached: false,
+        document: renderCanvasMessageDocument("Nothing rendered yet", reason),
+    };
+}
+/**
+ * The board a failed derivation gets: the declared `error` status, the reason
+ * that was thrown, and a renderable page rather than a hole.
+ *
+ * 200, not 500. `status` already distinguishes every outcome this route has,
+ * the pane renders `document` for all of them, and a 5xx would be read by the
+ * SPA's `ApiError` path as "this route is broken" rather than "this one
+ * agent's graph could not be extracted" — the same distinction
+ * `server/actions.ts` preserves when its input-contract extraction fails.
+ */
+function errorResponse(agentPath, name, reason) {
+    return {
+        path: agentPath,
+        name,
+        status: "error",
+        graph: null,
+        enrichment: null,
+        reason,
+        cached: false,
+        document: renderCanvasMessageDocument("Couldn't render this board", reason),
+    };
+}
+/** The thrown value as one line a person can read in the pane. */
+function failureReason(err) {
+    const detail = (err instanceof Error ? err.message : String(err)).trim();
+    return `Studio couldn't read this agent's graph: ${detail || "the derivation failed."}`;
+}
+export function createWorkflowGraphRouter(deps) {
+    const inspectMarker = deps.inspectMarker ?? inspectAgentProjectMarker;
+    const deriveCanvas = deps.deriveCanvas ?? deriveWorkflowCanvas;
+    const realpath = deps.realpath ?? ((p) => fsp.realpath(p));
+    const router = Router();
+    router.get("/api/workflows/:path/graph", async (req, res) => {
+        const raw = req.params.path;
+        if (typeof raw !== "string" || raw.trim() === "") {
+            res.status(400).json({ error: "agent path is required" });
+            return;
+        }
+        // Rejected on the RAW value, before resolution: a `..` climb must be an
+        // error, not something normalization silently lands on another registered
+        // path. (path-safety.ts's segment-aware test — "a..b" is a normal name.)
+        if (hasTraversalSegment(raw)) {
+            res.status(400).json({ error: "agent path must not contain a '..' segment" });
+            return;
+        }
+        if (!path.isAbsolute(raw)) {
+            res.status(400).json({ error: "agent path must be absolute" });
+            return;
+        }
+        // The lookup, and the LAST use of the request string. `workflow` is the
+        // registry's own row, so `workflow.path` is a path this server wrote when
+        // it scanned the disk — and that is the value every `fs` call below runs
+        // on. The request never reaches the filesystem, resolved or otherwise.
+        const workflow = deps.resolveWorkflow(path.resolve(raw));
+        if (!workflow) {
+            res.status(404).json({ error: "agent not found" });
+            return;
+        }
+        const agentPath = path.resolve(workflow.path);
+        const name = workflow.name || path.basename(agentPath);
+        let realDir;
+        try {
+            realDir = await realpath(agentPath);
+        }
+        catch {
+            // Registered but gone (the registry prunes lazily). That is an EMPTY
+            // board, not a 404 — 404 means "not registered", and conflating the two
+            // would make a consumer show "no such agent" for one it can see listed.
+            res.json(emptyResponse(agentPath, name, EMPTY_REASONS.gone));
+            return;
+        }
+        // Symlink guard on the one file this route reads by name. A symlinked
+        // agent DIRECTORY is legitimate (the user registered it, and realDir is
+        // its target), but a `sapiom.json` symlinked out of the project would make
+        // a path-keyed read endpoint into a file reader — refuse that outright.
+        const marker = await realpath(path.join(realDir, "sapiom.json")).catch(() => null);
+        if (marker !== null && resolveWithinRoot(realDir, marker) === null) {
+            res.status(400).json({ error: "sapiom.json resolves outside the agent directory" });
+            return;
+        }
+        // From here on the work is a child process, a manifest this process did
+        // not write, and a walk of user directories. All three throw, and an
+        // uncaught rejection in an Express 4 async handler kills the harness
+        // instead of answering the request.
+        try {
+            const inspection = await inspectMarker(realDir);
+            if (inspection.status !== "valid") {
+                res.json(emptyResponse(agentPath, name, EMPTY_REASONS[inspection.status]));
+                return;
+            }
+            const derived = await deriveCanvas({
+                path: workflow.path,
+                name,
+                definitionId: workflow.definitionId ?? null,
+                activeBuildRunStatus: workflow.activeBuildRunStatus ?? null,
+            });
+            res.json({
+                path: agentPath,
+                name,
+                status: derived.status,
+                graph: derived.graph,
+                enrichment: derived.enrichment,
+                reason: derived.reason,
+                cached: derived.cached,
+                document: derived.document,
+            });
+        }
+        catch (err) {
+            res.json(errorResponse(agentPath, name, failureReason(err)));
+        }
+    });
+    return router;
+}
+//# sourceMappingURL=workflow-graph.js.map

package/dist/server/workflow-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-graph.js","sourceRoot":"","sources":["../../src/server/workflow-graph.ts"],"names":[],"mappings":"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"}

package/dist/shared/system-graph.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Public contract for the local workspace dependency graph. Graph payloads
+ * never carry filesystem roots; WorkspaceScopeSummary only joins AppState's
+ * existing cwd-backed folder projection to an opaque key.
+ */
+export type WorkspaceKey = string;
+export type AgentKey = string;
+/**
+ * The one browser/server rule for a workspace-relative local AgentKey.
+ * Callers receive null when the source is not inside the supplied scope.
+ */
+export declare function workspaceRelativeLocalKey(scopeRoot: string, sourceRoot: string): AgentKey | null;
+/** Internal HTTP metadata; it is deliberately not part of SystemGraph JSON. */
+export declare const SYSTEM_GRAPH_CACHE_HEADER = "X-Sapiom-System-Graph-Cache";
+export type SystemGraphCacheStatus = "complete" | "degraded";
+export interface WorkspaceScopeSummary {
+    workspaceKey: WorkspaceKey;
+    /** Used only to join the existing workspace-folder projection in AppState. */
+    cwd: string;
+}
+export interface SystemGraphNode {
+    id: string;
+    agentKey: AgentKey;
+    label: string;
+}
+export type AgentInvocationMode = "blocking" | "async";
+export interface SystemGraphEdge {
+    from: string;
+    to: string;
+    kind: "invokes";
+    basis: "static";
+    mode: AgentInvocationMode;
+}
+export interface GraphWarning {
+    code: "unresolved-target" | "dynamic-target" | "duplicate-edge" | "projection-failed" | "duplicate-agent-key" | "inventory-extraction-failed";
+    message: string;
+    agentKey?: AgentKey;
+}
+export interface SystemGraph {
+    kind: "system";
+    scope: {
+        kind: "working-tree";
+        workspaceKey: WorkspaceKey;
+    };
+    nodes: SystemGraphNode[];
+    edges: SystemGraphEdge[];
+    warnings: GraphWarning[];
+}
+export type SystemGraphLifecycleState = "building" | "ready" | "stale" | "degraded";
+/** Path-free lifecycle envelope for one workspace projection. */
+export interface SystemGraphSnapshot {
+    workspaceKey: WorkspaceKey;
+    /** Monotonic within one server process and workspace. */
+    revision: number;
+    state: SystemGraphLifecycleState;
+    /** Null only before a usable projection exists. */
+    graph: SystemGraph | null;
+}
+//# sourceMappingURL=system-graph.d.ts.map

package/dist/shared/system-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-graph.d.ts","sourceRoot":"","sources":["../../src/shared/system-graph.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAClC,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAuD9B;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,QAAQ,GAAG,IAAI,CA0BjB;AAED,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB,gCAAgC,CAAC;AACvE,MAAM,MAAM,sBAAsB,GAAG,UAAU,GAAG,UAAU,CAAC;AAE7D,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,YAAY,CAAC;IAC3B,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,OAAO,CAAC;AAEvD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,QAAQ,CAAC;IAChB,IAAI,EAAE,mBAAmB,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EACA,mBAAmB,GACnB,gBAAgB,GAChB,gBAAgB,GAChB,mBAAmB,GACnB,qBAAqB,GACrB,6BAA6B,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE;QACL,IAAI,EAAE,cAAc,CAAC;QACrB,YAAY,EAAE,YAAY,CAAC;KAC5B,CAAC;IACF,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AACD,MAAM,MAAM,yBAAyB,GACjC,UAAU,GACV,OAAO,GACP,OAAO,GACP,UAAU,CAAC;AAEf,iEAAiE;AACjE,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,YAAY,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,yBAAyB,CAAC;IACjC,mDAAmD;IACnD,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;CAC3B"}