@sapiom/harness 0.0.0 → 0.1.0

package/dist/core/canvas-graph.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Deterministic workflow graph extraction (no LLM). Runs `@sapiom/agent-core`'s
+ * `check()` pipeline (in an isolated child process — see
+ * core/canvas-manifest-check.ts for why) against a workflow project on disk
+ * — the same bundle+manifest+graph-validation path `sapiom agents check`
+ * uses — and reshapes the resulting manifest into the small node/edge model
+ * `canvas-svg.ts` renders. Never throws: extraction failure (missing
+ * node_modules, a type error, an invalid graph) is returned as a typed
+ * `ExtractionFailure` so the caller can render an honest degraded panel
+ * instead of crashing or silently falling back to an LLM.
+ */
+import type { AgentManifest } from "@sapiom/agent";
+import { type DetectedLaunch } from "./canvas-interconnections.js";
+export type CanvasNodeKind = "entry" | "step" | "pause" | "terminal-success" | "terminal-warn" | "launched-workflow";
+export type CanvasEdgeKind = "sequential" | "branching" | "cross" | "launch";
+export interface CanvasNode {
+    id: string;
+    kind: CanvasNodeKind;
+    label: string;
+    sublabel?: string;
+}
+export interface CanvasEdge {
+    from: string;
+    to: string;
+    kind: CanvasEdgeKind;
+    label?: string;
+}
+/** One workflow's extracted, render-ready graph. */
+export interface CanvasGraph {
+    /** The manifest's own name — used both as a display title fallback and as
+     *  the match key for cross-workflow interconnection detection. */
+    manifestName: string;
+    entry: string;
+    nodes: CanvasNode[];
+    edges: CanvasEdge[];
+    /** Non-fatal graph smells from `assertValidGraph` (unreachable steps, no
+     *  path to a terminal) — surfaced as a badge, not an error. */
+    warnings: string[];
+}
+export interface ExtractionSuccess {
+    ok: true;
+    graph: CanvasGraph;
+}
+export interface ExtractionFailure {
+    ok: false;
+    /** Human-readable, terminal-safe reason — shown verbatim in the degraded panel. */
+    reason: string;
+}
+export type ExtractionResult = ExtractionSuccess | ExtractionFailure;
+/** Reshapes a validated `AgentManifest` into the render-ready graph model. */
+export declare function graphFromManifest(manifest: AgentManifest, warnings: string[]): CanvasGraph;
+/**
+ * Merges heuristically detected cross-workflow launches into the workflow's
+ * own graph: one dashed `launched-workflow` node per distinct slug, with a
+ * `launch`-kind edge from the step the call was attributed to (falling back
+ * to the entry step — the launch definitely happens somewhere downstream of
+ * it). Self-launches (a workflow re-launching itself) are skipped: the graph
+ * already shows those steps. Pure — returns a new graph.
+ */
+export declare function mergeLaunchesIntoGraph(graph: CanvasGraph, launches: readonly DetectedLaunch[]): CanvasGraph;
+/**
+ * Extracts a workflow's step graph from its project directory, with detected
+ * cross-workflow launches merged in as dashed nodes. Never throws: any
+ * failure (no node_modules, a bundle/type error, an invalid graph, a
+ * check-process crash or timeout) comes back as `{ ok: false, reason }` for
+ * the caller to render as a degraded panel — this is the only place
+ * extraction failure is allowed to happen silently instead of crashing the
+ * render.
+ */
+export declare function extractWorkflowGraph(sourceDir: string): Promise<ExtractionResult>;
+//# sourceMappingURL=canvas-graph.d.ts.map

package/dist/core/canvas-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-graph.d.ts","sourceRoot":"","sources":["../../src/core/canvas-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,aAAa,EAAqB,MAAM,eAAe,CAAC;AAEtE,OAAO,EAA0B,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAE3F,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,kBAAkB,GAAG,eAAe,GAAG,mBAAmB,CAAC;AACrH,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE7E,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,oDAAoD;AACpD,MAAM,WAAW,WAAW;IAC1B;sEACkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB;mEAC+D;IAC/D,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,KAAK,CAAC;IACV,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AA0DrE,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,WAAW,CAS1F;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,WAAW,CAqB3G;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAMvF"}

package/dist/core/canvas-graph.js

@@ -0,0 +1,111 @@
+import { runManifestCheck } from "./canvas-manifest-check.js";
+import { detectWorkflowLaunches } from "./canvas-interconnections.js";
+/**
+ * Classifies a step for node styling. Priority: the entry step always reads
+ * as "entry" (the diagram's obvious starting point) even if it also happens
+ * to declare a pause/terminal transition; next, a declared `pause` always
+ * shows the dashed border regardless of what else the step declares; a step
+ * that can `continue` somewhere is a mid-flow "step" even if it can also
+ * terminate/fail from a different runtime branch; only a step with NO
+ * `continue` targets left resolves to a terminal color, warn (fail) over
+ * success (terminate) is not possible to prioritize both apply — success
+ * wins as the more common single-outcome shape.
+ *
+ * Every branch also carries a deterministic `sublabel` — a one-line role
+ * derived purely from the step's declared transitions (entry / step / pause ·
+ * <signal> / terminal · success / terminal · needs attention) — so each node
+ * renders as a titled card even before any AI enrichment. `renderGraphSvg`
+ * prefers an enrichment-supplied sublabel over this default when present.
+ */
+function classifyNode(name, entry, step) {
+    const continueTargets = step.transitions.filter((t) => t.kind === "continue");
+    const pause = step.transitions.find((t) => t.kind === "pause");
+    const hasTerminate = step.transitions.some((t) => t.kind === "terminate");
+    const hasFail = step.transitions.some((t) => t.kind === "fail");
+    if (name === entry)
+        return { kind: "entry", sublabel: "entry" };
+    if (pause)
+        return { kind: "pause", sublabel: `pause · ${pause.signal}` };
+    if (continueTargets.length === 0 && hasFail && !hasTerminate)
+        return { kind: "terminal-warn", sublabel: "terminal · needs attention" };
+    if (continueTargets.length === 0 && hasTerminate)
+        return { kind: "terminal-success", sublabel: "terminal · success" };
+    if (continueTargets.length > 0 && (hasTerminate || hasFail)) {
+        return { kind: "step", sublabel: hasFail ? "step · can also fail" : "step · can also terminate" };
+    }
+    return { kind: "step", sublabel: "step" };
+}
+/** Builds every edge a step declares — one per `continue` target plus its
+ *  `pause` edge, if any. Node kind (above) only decides border styling; every
+ *  declared transition with a target still gets its own edge. */
+function edgesForStep(name, step) {
+    const continueTargets = step.transitions.filter((t) => t.kind === "continue");
+    const edges = continueTargets.map((t) => ({
+        from: name,
+        to: t.target,
+        kind: continueTargets.length > 1 ? "branching" : "sequential",
+    }));
+    const pause = step.transitions.find((t) => t.kind === "pause");
+    if (pause) {
+        edges.push({ from: name, to: pause.resumeStep, kind: "cross", label: pause.signal });
+    }
+    return edges;
+}
+/** Reshapes a validated `AgentManifest` into the render-ready graph model. */
+export function graphFromManifest(manifest, warnings) {
+    const nodes = Object.entries(manifest.steps).map(([name, step]) => {
+        const { kind, sublabel } = classifyNode(name, manifest.entry, step);
+        return { id: name, kind, label: name, sublabel };
+    });
+    const edges = Object.entries(manifest.steps).flatMap(([name, step]) => edgesForStep(name, step));
+    return { manifestName: manifest.name, entry: manifest.entry, nodes, edges, warnings };
+}
+/**
+ * Merges heuristically detected cross-workflow launches into the workflow's
+ * own graph: one dashed `launched-workflow` node per distinct slug, with a
+ * `launch`-kind edge from the step the call was attributed to (falling back
+ * to the entry step — the launch definitely happens somewhere downstream of
+ * it). Self-launches (a workflow re-launching itself) are skipped: the graph
+ * already shows those steps. Pure — returns a new graph.
+ */
+export function mergeLaunchesIntoGraph(graph, launches) {
+    const stepIds = new Set(graph.nodes.map((n) => n.id));
+    const nodes = [...graph.nodes];
+    const edges = [...graph.edges];
+    const seenEdges = new Set();
+    for (const launch of launches) {
+        if (launch.slug === graph.manifestName)
+            continue;
+        // Prefixed id so a launched workflow can never collide with a step that
+        // happens to share its name.
+        const nodeId = `launch:${launch.slug}`;
+        if (!nodes.some((n) => n.id === nodeId)) {
+            nodes.push({ id: nodeId, kind: "launched-workflow", label: launch.slug, sublabel: "launched workflow" });
+        }
+        const from = launch.fromStepId && stepIds.has(launch.fromStepId) ? launch.fromStepId : graph.entry;
+        const edgeKey = `${from}->${nodeId}`;
+        if (seenEdges.has(edgeKey))
+            continue;
+        seenEdges.add(edgeKey);
+        edges.push({ from, to: nodeId, kind: "launch", label: "launch()" });
+    }
+    return { ...graph, nodes, edges };
+}
+/**
+ * Extracts a workflow's step graph from its project directory, with detected
+ * cross-workflow launches merged in as dashed nodes. Never throws: any
+ * failure (no node_modules, a bundle/type error, an invalid graph, a
+ * check-process crash or timeout) comes back as `{ ok: false, reason }` for
+ * the caller to render as a degraded panel — this is the only place
+ * extraction failure is allowed to happen silently instead of crashing the
+ * render.
+ */
+export async function extractWorkflowGraph(sourceDir) {
+    const result = await runManifestCheck(sourceDir);
+    if (!result.ok)
+        return { ok: false, reason: result.reason };
+    const graph = graphFromManifest(result.manifest, result.warnings);
+    const launches = await detectWorkflowLaunches(sourceDir, new Set(graph.nodes.map((n) => n.id)));
+    return { ok: true, graph: mergeLaunchesIntoGraph(graph, launches) };
+}
+//# sourceMappingURL=canvas-graph.js.map

package/dist/core/canvas-graph.js.map

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

package/dist/core/canvas-index-classify.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Classifies a `.sapiom/canvas/index.html` on disk as machine-generated
+ * (a leftover the harness itself wrote) vs. an agent-authored custom canvas,
+ * so the server can:
+ *
+ *   (a) refuse to serve a stale machine-generated file as the UNBOUND canvas
+ *       fallback — showing the clean empty state instead of stale content; and
+ *   (b) delete a legacy deterministic-overview file on session create so an
+ *       old one can't keep resurfacing (see `ensureCanvasTemplate`).
+ *
+ * Two machine-generated shapes exist in the wild:
+ *
+ *   - The seeded pristine template (`canvas-template.ts`'s `TEMPLATE_HTML`) —
+ *     benign (an empty state itself) but not a custom canvas either, so it
+ *     shouldn't be served as one.
+ *   - A LEGACY deterministic overview / single render. Before the
+ *     per-workflow render split, the deterministic pipeline wrote its output
+ *     straight to `index.html`; on a project first opened by one of those old
+ *     servers, that file is a stacked all-workflows page with baked-in
+ *     "render failed" panels that have nothing to do with the current session
+ *     — the actual bug this guards against. The writer that produced it was
+ *     removed when renders moved to `renders/<slug>.html`, so its signature is
+ *     matched by literal markup here rather than an imported constant.
+ *
+ * Detection is by signature substrings that only this package's own writers
+ * emit and that an agent authoring its own canvas would not reproduce.
+ */
+/** True when `html` is a legacy deterministic overview/single render that was
+ *  written directly to `index.html` by a pre-split server. This is the file
+ *  worth deleting on session create — the harmful stale "render failed" wall. */
+export declare function isLegacyDeterministicCanvas(html: string): boolean;
+/** True when `html` is the seeded pristine template, still un-customized. */
+export declare function isSeededCanvasTemplate(html: string): boolean;
+/**
+ * True when `html` is machine-generated (the seeded template OR a legacy
+ * deterministic overview) rather than an agent-authored custom canvas. Such a
+ * file must not be served as the unbound canvas fallback — the clean empty
+ * state is served instead.
+ */
+export declare function isMachineGeneratedCanvas(html: string): boolean;
+//# sourceMappingURL=canvas-index-classify.d.ts.map

package/dist/core/canvas-index-classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-index-classify.d.ts","sourceRoot":"","sources":["../../src/core/canvas-index-classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAoBH;;iFAEiF;AACjF,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED,6EAA6E;AAC7E,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9D"}

package/dist/core/canvas-index-classify.js

@@ -0,0 +1,63 @@
+/**
+ * Classifies a `.sapiom/canvas/index.html` on disk as machine-generated
+ * (a leftover the harness itself wrote) vs. an agent-authored custom canvas,
+ * so the server can:
+ *
+ *   (a) refuse to serve a stale machine-generated file as the UNBOUND canvas
+ *       fallback — showing the clean empty state instead of stale content; and
+ *   (b) delete a legacy deterministic-overview file on session create so an
+ *       old one can't keep resurfacing (see `ensureCanvasTemplate`).
+ *
+ * Two machine-generated shapes exist in the wild:
+ *
+ *   - The seeded pristine template (`canvas-template.ts`'s `TEMPLATE_HTML`) —
+ *     benign (an empty state itself) but not a custom canvas either, so it
+ *     shouldn't be served as one.
+ *   - A LEGACY deterministic overview / single render. Before the
+ *     per-workflow render split, the deterministic pipeline wrote its output
+ *     straight to `index.html`; on a project first opened by one of those old
+ *     servers, that file is a stacked all-workflows page with baked-in
+ *     "render failed" panels that have nothing to do with the current session
+ *     — the actual bug this guards against. The writer that produced it was
+ *     removed when renders moved to `renders/<slug>.html`, so its signature is
+ *     matched by literal markup here rather than an imported constant.
+ *
+ * Detection is by signature substrings that only this package's own writers
+ * emit and that an agent authoring its own canvas would not reproduce.
+ */
+/**
+ * The footer note the deterministic render pipeline emits via
+ * `assembleCanvasBody` — `<p class="canvas-note">Static preview — …</p>`.
+ * Stable across both the legacy overview and single-render variants (the exact
+ * trailing text differed between versions; the "Static preview" prefix did
+ * not). An agent-authored canvas writes its own copy, never this.
+ */
+const DETERMINISTIC_NOTE_SIGNATURE = 'class="canvas-note">Static preview';
+/**
+ * The inert patterns block the seeded template ships with, together with its
+ * untouched empty-state note. Both present means the seed is still
+ * un-customized — an agent is instructed to delete both once it authors real
+ * content, so their joint presence never matches a finished custom canvas.
+ */
+const TEMPLATE_PATTERNS_SIGNATURE = 'id="canvas-patterns"';
+const TEMPLATE_EMPTY_NOTE_SIGNATURE = "Nothing visualized yet";
+/** True when `html` is a legacy deterministic overview/single render that was
+ *  written directly to `index.html` by a pre-split server. This is the file
+ *  worth deleting on session create — the harmful stale "render failed" wall. */
+export function isLegacyDeterministicCanvas(html) {
+    return html.includes(DETERMINISTIC_NOTE_SIGNATURE);
+}
+/** True when `html` is the seeded pristine template, still un-customized. */
+export function isSeededCanvasTemplate(html) {
+    return html.includes(TEMPLATE_PATTERNS_SIGNATURE) && html.includes(TEMPLATE_EMPTY_NOTE_SIGNATURE);
+}
+/**
+ * True when `html` is machine-generated (the seeded template OR a legacy
+ * deterministic overview) rather than an agent-authored custom canvas. Such a
+ * file must not be served as the unbound canvas fallback — the clean empty
+ * state is served instead.
+ */
+export function isMachineGeneratedCanvas(html) {
+    return isLegacyDeterministicCanvas(html) || isSeededCanvasTemplate(html);
+}
+//# sourceMappingURL=canvas-index-classify.js.map

package/dist/core/canvas-index-classify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-index-classify.js","sourceRoot":"","sources":["../../src/core/canvas-index-classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;GAMG;AACH,MAAM,4BAA4B,GAAG,oCAAoC,CAAC;AAE1E;;;;;GAKG;AACH,MAAM,2BAA2B,GAAG,sBAAsB,CAAC;AAC3D,MAAM,6BAA6B,GAAG,wBAAwB,CAAC;AAE/D;;iFAEiF;AACjF,MAAM,UAAU,2BAA2B,CAAC,IAAY;IACtD,OAAO,IAAI,CAAC,QAAQ,CAAC,4BAA4B,CAAC,CAAC;AACrD,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,OAAO,IAAI,CAAC,QAAQ,CAAC,2BAA2B,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,6BAA6B,CAAC,CAAC;AACpG,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAY;IACnD,OAAO,2BAA2B,CAAC,IAAI,CAAC,IAAI,sBAAsB,CAAC,IAAI,CAAC,CAAC;AAC3E,CAAC"}

package/dist/core/canvas-interconnections.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Lists the workflow's own `.ts`/`.tsx` sources (skipping node_modules and
+ * friends), bounded to MAX_FILES_PER_WORKFLOW. Shared with the extraction
+ * cache's source fingerprint (core/canvas-cache.ts) so "the files this grep
+ * reads" and "the files whose mtimes invalidate the cache" can't drift.
+ */
+export declare function listSourceFiles(root: string): Promise<string[]>;
+export interface DetectedLaunch {
+    /** The `definition` slug the launch call referenced. */
+    slug: string;
+    /** The step (by declared name) the call was attributed to — the nearest
+     *  preceding `name: "<known step>"` declaration in the same file — or null
+     *  when no known step precedes it (e.g. a launch in a shared helper). */
+    fromStepId: string | null;
+}
+/**
+ * Every `*.launch({ definition: "..." })` call in `root`'s sources, each
+ * best-effort attributed to the step whose `defineStep` block it sits in
+ * (`knownStepIds` = the workflow's real step names, so an unrelated `name:`
+ * property can never be mistaken for a step). Never throws: unreadable
+ * files/directories simply contribute no launches.
+ */
+export declare function detectWorkflowLaunches(root: string, knownStepIds: ReadonlySet<string>): Promise<DetectedLaunch[]>;
+//# sourceMappingURL=canvas-interconnections.d.ts.map

package/dist/core/canvas-interconnections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-interconnections.d.ts","sourceRoot":"","sources":["../../src/core/canvas-interconnections.ts"],"names":[],"mappings":"AAkCA;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAsBrE;AAED,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb;;6EAEyE;IACzE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,GAChC,OAAO,CAAC,cAAc,EAAE,CAAC,CAuB3B"}

package/dist/core/canvas-interconnections.js

@@ -0,0 +1,96 @@
+/**
+ * Heuristic cross-workflow launch detection: greps a workflow project's
+ * TypeScript sources for `orchestrations.launch({ definition: "<slug>" })`
+ * (the pre-rename SDK's capability) and `agents.launch({ definition: ... })`
+ * (the current SDK, e.g. `ctx.sapiom.agents.launch`) calls, and best-effort
+ * attributes each call to the step whose `defineStep({ name: ... })` block it
+ * sits in. The result is merged into the workflow's own rendered graph as
+ * dashed "launched workflow" nodes (see core/canvas-graph.ts).
+ *
+ * This is deliberately a grep, not a type-aware analysis — a step can compute
+ * its `definition` dynamically, in which case it's simply not detected; false
+ * negatives are fine here, the launch nodes are a bonus, not a source of
+ * truth.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+const SKIP_DIR_NAMES = new Set(["node_modules", ".git", "dist", "build", ".sapiom"]);
+const SOURCE_EXTENSIONS = new Set([".ts", ".tsx"]);
+const MAX_FILES_PER_WORKFLOW = 200;
+const MAX_FILE_BYTES = 512 * 1024;
+// Matches `orchestrations.launch({ ...definition: "slug"... })` (old SDK) and
+// `agents.launch({ ...definition: "slug"... })` (current SDK), tolerating
+// other fields before `definition` in the object literal (bounded lookahead
+// so an unrelated huge object literal can't make this pathological).
+const LAUNCH_CALL_PATTERN = /(?:orchestrations|agents)\s*\.\s*launch\s*\(\s*\{[\s\S]{0,400}?definition\s*:\s*(['"`])([^'"`]+)\1/g;
+// A `name: "..."` property declaration — the step-name key `defineStep`
+// blocks always open with. The lookbehind rejects longer identifiers ending
+// in "name" (fromName, vendorName) without consuming the preceding char.
+const STEP_NAME_PATTERN = /(?<![\w$.])name\s*:\s*(['"`])([^'"`]+)\1/g;
+/**
+ * Lists the workflow's own `.ts`/`.tsx` sources (skipping node_modules and
+ * friends), bounded to MAX_FILES_PER_WORKFLOW. Shared with the extraction
+ * cache's source fingerprint (core/canvas-cache.ts) so "the files this grep
+ * reads" and "the files whose mtimes invalidate the cache" can't drift.
+ */
+export async function listSourceFiles(root) {
+    const files = [];
+    async function walk(dir) {
+        if (files.length >= MAX_FILES_PER_WORKFLOW)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (files.length >= MAX_FILES_PER_WORKFLOW)
+                return;
+            if (entry.isDirectory()) {
+                if (SKIP_DIR_NAMES.has(entry.name))
+                    continue;
+                await walk(path.join(dir, entry.name));
+            }
+            else if (SOURCE_EXTENSIONS.has(path.extname(entry.name))) {
+                files.push(path.join(dir, entry.name));
+            }
+        }
+    }
+    await walk(root);
+    return files;
+}
+/**
+ * Every `*.launch({ definition: "..." })` call in `root`'s sources, each
+ * best-effort attributed to the step whose `defineStep` block it sits in
+ * (`knownStepIds` = the workflow's real step names, so an unrelated `name:`
+ * property can never be mistaken for a step). Never throws: unreadable
+ * files/directories simply contribute no launches.
+ */
+export async function detectWorkflowLaunches(root, knownStepIds) {
+    const launches = [];
+    for (const file of await listSourceFiles(root)) {
+        let content;
+        try {
+            const stat = await fs.stat(file);
+            if (stat.size > MAX_FILE_BYTES)
+                continue;
+            content = await fs.readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const stepDeclarations = [];
+        for (const match of content.matchAll(STEP_NAME_PATTERN)) {
+            if (knownStepIds.has(match[2]))
+                stepDeclarations.push({ index: match.index, stepId: match[2] });
+        }
+        for (const match of content.matchAll(LAUNCH_CALL_PATTERN)) {
+            const preceding = stepDeclarations.filter((d) => d.index < match.index).at(-1);
+            launches.push({ slug: match[2], fromStepId: preceding?.stepId ?? null });
+        }
+    }
+    return launches;
+}
+//# sourceMappingURL=canvas-interconnections.js.map

package/dist/core/canvas-interconnections.js.map

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

package/dist/core/canvas-manifest-check.d.ts

@@ -0,0 +1,15 @@
+export interface ManifestCheckSuccess {
+    ok: true;
+    manifest: unknown;
+    warnings: string[];
+}
+export interface ManifestCheckFailure {
+    ok: false;
+    reason: string;
+}
+export type ManifestCheckResult = ManifestCheckSuccess | ManifestCheckFailure;
+/** Runs `check({ sourceDir })` in a child `node` process; never throws or
+ *  rejects — a crash, timeout, or unparsable output all come back as a
+ *  `ManifestCheckFailure` with a human-readable reason. */
+export declare function runManifestCheck(sourceDir: string): Promise<ManifestCheckResult>;
+//# sourceMappingURL=canvas-manifest-check.d.ts.map

package/dist/core/canvas-manifest-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-manifest-check.d.ts","sourceRoot":"","sources":["../../src/core/canvas-manifest-check.ts"],"names":[],"mappings":"AA+DA,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,IAAI,CAAC;IACT,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,GAAG,oBAAoB,CAAC;AAE9E;;2DAE2D;AAC3D,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA8BhF"}

package/dist/core/canvas-manifest-check.js

@@ -0,0 +1,90 @@
+/**
+ * Runs `@sapiom/agent-core`'s `check()` in an isolated child process, rather
+ * than importing it in-process. Two independent reasons:
+ *
+ *  1. `check()` dynamically `import()`s an esbuild-bundled copy of whatever
+ *     TypeScript the target workflow's `index.ts` contains — a workflow
+ *     project the harness doesn't control. Running that inside the harness's
+ *     own long-lived server process would let a stray top-level side effect,
+ *     infinite loop, or crash in someone else's workflow code take the whole
+ *     harness down. A child process bounds the blast radius to one failed
+ *     render.
+ *  2. It sidesteps a real Vite/Vitest limitation: `check()`'s own dynamic
+ *     `import(\`file://${tmpPath}\`)` gets intercepted by Vite's SSR
+ *     dynamic-import-vars transform when anything imports `check` directly
+ *     into a Vitest-run module graph, and mishandles the tmpdir's `file://`
+ *     URL on darwin ("File URL host must be 'localhost' or empty"),
+ *     corrupting every extraction. A plain child `node` process never goes
+ *     through that transform.
+ *
+ * The child process is a short inline ESM script (no separate file to keep
+ * in sync across dev/build) run with `cwd` set to this package's own root,
+ * so `import { check } from "@sapiom/agent-core"` resolves against the
+ * harness's real dependency — exactly like the CLI's own `sapiom agents
+ * check` already runs it, just invoked programmatically instead of as a
+ * subcommand.
+ */
+import { execFile } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Hard ceiling, not the performance target — bundling a small workflow is
+ *  typically well under a second; this only guards against a pathological
+ *  project (a huge dependency tree, a hanging top-level side effect) from
+ *  blocking a render indefinitely. */
+const CHECK_TIMEOUT_MS = 15000;
+const MAX_BUFFER_BYTES = 10 * 1024 * 1024;
+// This module lives at either src/core/ (tsx dev, vitest) or dist/core/
+// (built) — both two directories below the package root.
+function packageRoot() {
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+}
+const RUNNER_SOURCE = `
+import { check, AgentOperationError } from "@sapiom/agent-core";
+
+function reasonFor(err) {
+  if (err instanceof AgentOperationError) return err.hint ? \`\${err.message} \${err.hint}\` : err.message;
+  return err instanceof Error ? err.message : String(err);
+}
+
+const sourceDir = process.env.SAPIOM_CANVAS_CHECK_SOURCE_DIR;
+try {
+  // typecheck: false — a diagram only needs the manifest/graph, and the
+  // project's own tsc --noEmit is the dominant multi-second per-render cost;
+  // esbuild still surfaces real breakage (bad imports, syntax errors).
+  const result = await check({ sourceDir, typecheck: false });
+  process.stdout.write(JSON.stringify({ ok: true, manifest: result.manifest, warnings: result.warnings }));
+} catch (err) {
+  process.stdout.write(JSON.stringify({ ok: false, reason: reasonFor(err) }));
+}
+`;
+/** Runs `check({ sourceDir })` in a child `node` process; never throws or
+ *  rejects — a crash, timeout, or unparsable output all come back as a
+ *  `ManifestCheckFailure` with a human-readable reason. */
+export function runManifestCheck(sourceDir) {
+    return new Promise((resolve) => {
+        execFile(process.execPath, ["--input-type=module", "-e", RUNNER_SOURCE], {
+            cwd: packageRoot(),
+            env: { ...process.env, SAPIOM_CANVAS_CHECK_SOURCE_DIR: sourceDir },
+            timeout: CHECK_TIMEOUT_MS,
+            maxBuffer: MAX_BUFFER_BYTES,
+        }, (err, stdout, stderr) => {
+            if (err) {
+                const timedOut = err.killed && err.signal === "SIGTERM";
+                resolve({
+                    ok: false,
+                    reason: timedOut
+                        ? `Extraction timed out after ${CHECK_TIMEOUT_MS / 1000}s.`
+                        : (stderr.trim() || err.message),
+                });
+                return;
+            }
+            try {
+                resolve(JSON.parse(stdout));
+            }
+            catch {
+                resolve({ ok: false, reason: `Unexpected output from the check process: ${stdout.slice(0, 500)}` });
+            }
+        });
+    });
+}
+//# sourceMappingURL=canvas-manifest-check.js.map

package/dist/core/canvas-manifest-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-manifest-check.js","sourceRoot":"","sources":["../../src/core/canvas-manifest-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;sCAGsC;AACtC,MAAM,gBAAgB,GAAG,KAAM,CAAC;AAChC,MAAM,gBAAgB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAE1C,wEAAwE;AACxE,yDAAyD;AACzD,SAAS,WAAW;IAClB,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;CAkBrB,CAAC;AAeF;;2DAE2D;AAC3D,MAAM,UAAU,gBAAgB,CAAC,SAAiB;IAChD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,QAAQ,CACN,OAAO,CAAC,QAAQ,EAChB,CAAC,qBAAqB,EAAE,IAAI,EAAE,aAAa,CAAC,EAC5C;YACE,GAAG,EAAE,WAAW,EAAE;YAClB,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,8BAA8B,EAAE,SAAS,EAAE;YAClE,OAAO,EAAE,gBAAgB;YACzB,SAAS,EAAE,gBAAgB;SAC5B,EACD,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YACtB,IAAI,GAAG,EAAE,CAAC;gBACR,MAAM,QAAQ,GAAI,GAAoD,CAAC,MAAM,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC;gBAC1G,OAAO,CAAC;oBACN,EAAE,EAAE,KAAK;oBACT,MAAM,EAAE,QAAQ;wBACd,CAAC,CAAC,8BAA8B,gBAAgB,GAAG,IAAI,IAAI;wBAC3D,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,OAAO,CAAC;iBACnC,CAAC,CAAC;gBACH,OAAO;YACT,CAAC;YACD,IAAI,CAAC;gBACH,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAwB,CAAC,CAAC;YACrD,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,6CAA6C,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;YACtG,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/core/canvas-render.d.ts

@@ -0,0 +1,73 @@
+export interface RenderableSession {
+    cwd: string;
+    boundWorkflowPath: string | null;
+}
+export interface RenderableWorkflow {
+    path: string;
+    name: string;
+    definitionId: number | null;
+}
+/**
+ * Stable, filesystem-safe render-file name for a workflow: its directory
+ * basename (readable in `ls`) plus a short path hash (two same-named
+ * workflows at different paths can never collide). Shared by the writer here
+ * and the server's request-time resolution — must stay deterministic.
+ */
+export declare function slugForWorkflowPath(workflowPath: string): string;
+/** Absolute path of `workflowPath`'s render file under `cwd`'s canvas dir. */
+export declare function renderFileFor(cwd: string, workflowPath: string): string;
+/** Absolute path of `workflowPath`'s enrichment cache file under `cwd`'s
+ *  canvas dir — same slug scheme as the render file. */
+export declare function enrichmentCacheFileFor(cwd: string, workflowPath: string): string;
+export interface CanvasRenderOutcome {
+    /** "single": a bound workflow was rendered to its render file. "empty":
+     *  the session is unbound (or bound to an unknown path) — nothing was
+     *  extracted or written; the server serves the empty state on its own. */
+    mode: "single" | "empty";
+    workflowPath?: string;
+    /** Absolute path of the render file written (mode "single" only). */
+    renderPath?: string;
+    /** Display names of workflows whose graph couldn't be extracted (still rendered as a degraded panel). */
+    extractionFailed: string[];
+    /** True when the graph came from the extraction cache — no child process ran. */
+    cachedExtraction?: boolean;
+    /** True when a cached enrichment was merged into the render (mode "single",
+     *  successful extraction only). */
+    enrichmentApplied?: boolean;
+    /** True when the merged enrichment's fingerprint no longer matches the
+     *  current sources — rendered with the "stale" chip. */
+    enrichmentStale?: boolean;
+    /** Set only when writing the file itself failed (e.g. an unwritable cwd) — extraction success/failure above is unaffected. */
+    writeError?: string;
+    /** True when `preserveExistingOnFailure` kept the existing render instead of writing an error panel over it. */
+    preservedExisting?: boolean;
+}
+export interface RenderCanvasOptions {
+    /**
+     * For unprompted (auto) renders only — session create, boot. When the
+     * extraction failed AND a render file for this workflow already exists,
+     * keep the existing file rather than replace a possibly-good diagram with
+     * an error panel. An explicit user-invoked render (the Visualize macro,
+     * POST /canvas/:id/render) should NOT set this: there the honest error
+     * page IS the answer the user asked for.
+     */
+    preserveExistingOnFailure?: boolean;
+}
+/**
+ * Renders `session`'s bound workflow to its per-workflow render file. Never
+ * throws — every failure mode (extraction, filesystem) is captured in the
+ * returned outcome instead. Unbound sessions are a cheap no-op: no
+ * extraction, no write (`mode: "empty"`).
+ */
+export declare function renderCanvasForSession(session: RenderableSession, workflows: readonly RenderableWorkflow[], options?: RenderCanvasOptions): Promise<CanvasRenderOutcome>;
+/**
+ * Renders ONE workflow to its render file under `cwd`, merging in any cached
+ * enrichment (fresh or stale — stale gets the chip; the base structure is
+ * always freshly extracted either way). This is the write path shared by
+ * bind/create/macro renders (via `renderCanvasForSession`) and by the
+ * enrichment task's own completion re-render (core/canvas-enrich.ts), which
+ * targets a workflow directly — the session may have switched bindings while
+ * the task ran, and the render file is per-workflow anyway.
+ */
+export declare function renderWorkflowRenderFile(cwd: string, bound: RenderableWorkflow, options?: RenderCanvasOptions): Promise<CanvasRenderOutcome>;
+//# sourceMappingURL=canvas-render.d.ts.map

package/dist/core/canvas-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-render.d.ts","sourceRoot":"","sources":["../../src/core/canvas-render.ts"],"names":[],"mappings":"AAwCA,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAShE;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED;wDACwD;AACxD,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEhF;AAED,MAAM,WAAW,mBAAmB;IAClC;;8EAE0E;IAC1E,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yGAAyG;IACzG,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;uCACmC;IACnC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;4DACwD;IACxD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,8HAA8H;IAC9H,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gHAAgH;IAChH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;;;OAOG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC;AA+BD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,iBAAiB,EAC1B,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,mBAAmB,CAAC,CAM9B;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,mBAAmB,CAAC,CA+C9B"}