@sapiom/harness 0.0.0 → 0.1.0

package/dist/core/adapters/codex.js

@@ -0,0 +1,319 @@
+/**
+ * codex adapter — launches/resumes the `codex` CLI and scans its rollout
+ * store for resumable history. Codex has no hook system (see
+ * core/collector/codex-tailer.ts for how its analytics eventSource works
+ * instead); this file only covers process launch/resume/doctor/history.
+ *
+ * Verified against a locally installed `codex-cli 0.134.0`: `codex resume
+ * [SESSION_ID] [PROMPT]` (positional UUID or thread name) via `codex resume
+ * --help`; the generic `-c key=value` config-override mechanism via `codex
+ * --help`; and, via real spawns with `--strict-config`, that both
+ * `developer_instructions` and `model_instructions_file` are real,
+ * recognized keys (an earlier version of this file used the latter and
+ * flagged both as unconfirmed — see buildConfigArgs below for why the
+ * adapter now uses `developer_instructions` instead: `model_instructions_file`
+ * makes codex's own startup depend on re-reading a file we already have the
+ * content of, and an unreadable path there kills the process instantly with
+ * no trust prompt, no TUI — precisely the "session has no live pty" a user
+ * sees with zero indication why).
+ */
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { open, readdir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/** Bytes read from the head of a rollout file to find its session_meta line
+ * and an early title candidate. Unlike Claude's transcripts (where a summary
+ * lands near the end), Codex has no end-of-session summary line, so the
+ * earliest user message is the best available title — and it's always near
+ * the start of the file. */
+const ROLLOUT_HEAD_BYTES = 65536;
+const MAX_SCAN_DEPTH = 4; // ~/.codex/sessions/YYYY/MM/DD/*.jsonl
+/**
+ * Matches Codex's directory-trust confirmation prompt ("Do you trust the
+ * contents of this directory? ... 1. Yes, continue  2. No, quit"), after
+ * `stripAnsi` — confirmed against a real capture: Codex's TUI positions
+ * each *word* with its own cursor-addressing escape sequence instead of
+ * emitting literal spaces between them (`trust\x1b[3;16Hthe\x1b[3;20H...`),
+ * so even a stripped buffer runs the words together with no separator at
+ * all; `\s*` between them tolerates that (and ordinary whitespace, in case
+ * a future TUI revision renders differently). See `detectBlockingPrompt`
+ * for why this exists at all (Codex's own structured readiness signal can't
+ * be relied on standalone, unlike Claude Code's).
+ */
+const TRUST_PROMPT_PATTERN = /trust\s*the\s*contents\s*of\s*this\s*directory/i;
+/** Strips ANSI/CSI/OSC control sequences a pty stream is otherwise full of,
+ *  so text pattern-matching (e.g. `TRUST_PROMPT_PATTERN`) sees the words a
+ *  human would actually read rather than raw terminal-control bytes. Not
+ *  exhaustive of every escape sequence a TUI could emit, but covers what
+ *  Codex's TUI is confirmed (via real captures) to use: CSI (cursor moves,
+ *  SGR color/style) and OSC (window title) sequences. */
+export function stripAnsi(text) {
+    /* eslint-disable no-control-regex -- matching literal ESC (\x1b) / BEL
+     * (\x07) bytes is the entire point of an ANSI-sequence stripper; there's
+     * no non-control-character way to express "a real escape sequence". */
+    return text
+        // Lazy (`*?`), not greedy: a greedy `[^\x07]*` doesn't exclude `\x1b\\`
+        // (ST) from what it can consume, so it backtracks from the END of the
+        // whole string looking for the last reachable terminator instead of the
+        // next one — silently swallowing everything (including real prompt
+        // text) between an OSC sequence and some unrelated, much-later BEL/ST.
+        // Confirmed against a real capture: this exact bug made the trust-
+        // prompt regex below never match a full multi-KB scrollback buffer.
+        .replace(/\x1b\][\s\S]*?(?:\x07|\x1b\\)/g, "") // OSC ... BEL or ST
+        .replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, "") // CSI sequences
+        .replace(/\x1b[()>=][A-Za-z0-9]?/g, ""); // charset/keypad-mode selection
+    /* eslint-enable no-control-regex */
+}
+/** Read only the head of a (possibly huge) rollout file and extract its
+ * `session_meta` entry. Codex always writes `session_meta` as the first
+ * line, but this tolerates a few leading blank/malformed lines defensively. */
+async function readSessionMeta(filePath, maxBytes = ROLLOUT_HEAD_BYTES) {
+    let content;
+    try {
+        const handle = await open(filePath, "r");
+        try {
+            const { size } = await handle.stat();
+            const length = Math.min(size, maxBytes);
+            const buffer = Buffer.allocUnsafe(length);
+            await handle.read(buffer, 0, length, 0);
+            content = buffer.toString("utf8");
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return null;
+    }
+    for (const line of content.split("\n").slice(0, 20)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (parsed.type !== "session_meta")
+            continue;
+        const payload = parsed.payload;
+        const id = typeof payload?.id === "string" ? payload.id : undefined;
+        const cwd = typeof payload?.cwd === "string" ? payload.cwd : undefined;
+        if (!id || !cwd)
+            return null;
+        const timestamp = typeof payload?.timestamp === "string" ? Date.parse(payload.timestamp) : NaN;
+        return { id, cwd, timestampMs: Number.isNaN(timestamp) ? null : timestamp };
+    }
+    return null;
+}
+/** First `event_msg`/`user_message` found in the head of the file, truncated
+ * for use as a session title. Falls back to `fallback` when none is found
+ * within the head window (long system-prompt-only sessions, mid-tail-cut). */
+function extractTitleFromHead(content, fallback) {
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (parsed.type !== "event_msg" || parsed.payload?.type !== "user_message")
+            continue;
+        const message = parsed.payload.message;
+        if (typeof message === "string" && message.trim()) {
+            const text = message.trim();
+            return text.length > 120 ? `${text.slice(0, 120)}...` : text;
+        }
+    }
+    return fallback;
+}
+/** Recursively collect `.jsonl` files under Codex's date-sharded sessions
+ * root (`YYYY/MM/DD/rollout-*.jsonl`). Bounded depth as a safety guard
+ * against unexpectedly deep/cyclical directory structures. */
+async function collectRolloutFiles(dir, depth = 0) {
+    if (depth > MAX_SCAN_DEPTH)
+        return [];
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...(await collectRolloutFiles(fullPath, depth + 1)));
+        }
+        else if (entry.name.endsWith(".jsonl")) {
+            results.push(fullPath);
+        }
+    }
+    return results;
+}
+export class CodexAdapter {
+    constructor(options = {}) {
+        this.id = "codex";
+        this.eventSource = "transcript-tail";
+        this.binary = options.binary ?? "codex";
+        this.homeDir = options.homeDir ?? homedir();
+    }
+    async doctor() {
+        try {
+            const { stdout } = await execFileAsync(this.binary, ["--version"], { timeout: 5000 });
+            return [{ name: "codex", ok: true, detail: stdout.trim() || "installed" }];
+        }
+        catch {
+            return [
+                {
+                    name: "codex",
+                    ok: false,
+                    detail: `\`${this.binary}\` not found on PATH. Install: https://github.com/openai/codex`,
+                },
+            ];
+        }
+    }
+    launch(opts) {
+        return {
+            command: this.binary,
+            args: buildConfigArgs(opts),
+            // Codex has no analog to Claude's CLAUDECODE nested-agent guard; no env
+            // overrides are needed for a fresh launch.
+            env: {},
+            cwd: opts.cwd,
+        };
+    }
+    resume(agentSessionId, opts) {
+        return {
+            command: this.binary,
+            args: ["resume", agentSessionId, ...buildConfigArgs(opts)],
+            env: {},
+            cwd: opts.cwd,
+        };
+    }
+    /**
+     * See `HarnessAdapter.detectBlockingPrompt`. Codex needs this (Claude Code
+     * doesn't) because its rollout file — and therefore the SessionStart-
+     * equivalent event `SessionManager` otherwise waits on — isn't written
+     * until the *first* turn is actually submitted, confirmed empirically
+     * against a real `codex-cli 0.134.0`: an idle, fully-interactive session
+     * (trust prompt already accepted, composer visibly ready) produces zero
+     * files under `~/.codex/sessions` for as long as nothing is submitted.
+     * That real signal therefore can't arrive before the very first
+     * injection that needs it — a scrollback check is the only thing that
+     * can stand in for it up to that point.
+     */
+    detectBlockingPrompt(scrollback) {
+        return TRUST_PROMPT_PATTERN.test(stripAnsi(scrollback));
+    }
+    async listPastSessions(cwd) {
+        const root = join(this.homeDir, ".codex", "sessions");
+        const files = await collectRolloutFiles(root);
+        const summaries = [];
+        for (const filePath of files) {
+            const meta = await readSessionMeta(filePath);
+            if (!meta || meta.cwd !== cwd)
+                continue;
+            const fileStat = await stat(filePath).catch(() => undefined);
+            const lastActiveAt = fileStat ? fileStat.mtime.toISOString() : new Date(0).toISOString();
+            let title = basename(filePath, ".jsonl");
+            try {
+                const handle = await open(filePath, "r");
+                try {
+                    const { size } = await handle.stat();
+                    const length = Math.min(size, ROLLOUT_HEAD_BYTES);
+                    const buffer = Buffer.allocUnsafe(length);
+                    await handle.read(buffer, 0, length, 0);
+                    title = extractTitleFromHead(buffer.toString("utf8"), meta.id);
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            catch {
+                // Fall back to the rollout id as the title.
+            }
+            summaries.push({
+                agentSessionId: meta.id,
+                harness: "codex",
+                cwd,
+                title,
+                lastActiveAt,
+                source: "transcript",
+            });
+        }
+        return summaries.sort((a, b) => (a.lastActiveAt < b.lastActiveAt ? 1 : -1));
+    }
+}
+/**
+ * Codex has no single-flag equivalent to Claude's `--append-system-prompt` /
+ * `--mcp-config` — MCP servers are registered globally via `codex mcp add`
+ * (a persistent config.toml mutation, which the harness's "zero config
+ * mutation" design deliberately avoids), so `opts.mcpConfigFile` /
+ * `opts.settingsFile` are intentionally unused here. System-prompt injection
+ * uses the generic `-c key=value` override mechanism instead.
+ *
+ * Confirmed against a locally installed codex-cli 0.134.0: `-c
+ * model_instructions_file=<path>` is a real, recognized key — but if that
+ * path is missing/unreadable at codex's own startup (a moment we don't
+ * control, in a separate process), codex exits immediately with a config
+ * error, no trust prompt, no TUI — which reads to a user as the session
+ * dying instantly. Since we already have the prompt's content in hand
+ * (we're the ones who generated the file), embedding it inline via
+ * `developer_instructions=<value>` instead removes that dependency
+ * entirely: nothing for codex to fail to (re)read. `-c` values parse as
+ * TOML, and TOML basic strings share JSON's escaping rules for control
+ * characters/quotes/backslashes, so `JSON.stringify` produces a valid TOML
+ * string literal here — confirmed with a real multiline prompt.
+ *
+ * If even this read fails (the file we just generated is somehow gone by
+ * the time we get here — a narrow race, but still no reason to crash the
+ * whole session over an optional prompt), fall back to launching without
+ * one rather than passing a broken reference that's guaranteed to kill the
+ * process on startup.
+ */
+function buildConfigArgs(opts) {
+    const args = [
+        "-c",
+        "check_for_update_on_startup=false",
+        // Codex's default approval policy interrupts the session with "Would you
+        // like to run the following command?" prompts (even for read-only
+        // commands like `ps`). Harness sessions are expected to run without
+        // approval interruptions — the analog of Claude Code sessions, which the
+        // harness runs in auto mode — so pin codex's non-interactive pairing:
+        // never ask for approval, and confine writes to the workspace via the OS
+        // sandbox instead of via per-command human review. Both keys and their
+        // values confirmed against a locally installed codex-cli 0.134.0 (its
+        // config deserializer enumerates `never` / `workspace-write` among the
+        // accepted variants when probed with a bogus value). `-c` values parse
+        // as TOML, so the string values need the embedded quotes.
+        "-c",
+        'approval_policy="never"',
+        "-c",
+        'sandbox_mode="workspace-write"',
+    ];
+    if (opts.systemPromptFile) {
+        try {
+            const prompt = readFileSync(opts.systemPromptFile, "utf8");
+            args.push("-c", `developer_instructions=${JSON.stringify(prompt)}`);
+        }
+        catch (err) {
+            console.error(`[codex adapter] could not read systemPromptFile "${opts.systemPromptFile}" — launching without an injected system prompt: ${err.message}`);
+        }
+    }
+    return args;
+}
+export function createCodexAdapter(options) {
+    return new CodexAdapter(options);
+}
+//# sourceMappingURL=codex.js.map

package/dist/core/adapters/codex.js.map

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

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

@@ -0,0 +1,45 @@
+/**
+ * Assembles the `<div id="canvas-root">` body — the bound workflow's
+ * `<section class="canvas-panel">` (header + stats + SVG diagram) and a
+ * legend footer — entirely from the classes `core/canvas-template.ts`'s shell
+ * already defines. This is the HTML half of the deterministic render;
+ * `core/canvas-render.ts` wraps the result through `renderCanvasDocument()`
+ * and writes it to the workflow's render file.
+ */
+import type { CanvasEdgeKind, CanvasGraph, CanvasNodeKind } from "./canvas-graph.js";
+import type { CanvasEnrichment } from "./canvas-enrichment.js";
+export interface WorkflowPanelMeta {
+    title: string;
+    badges?: string[];
+}
+/** How enrichment content reaches the panel/footer builders: the validated
+ *  content itself plus whether its source fingerprint no longer matches the
+ *  workflow's current sources (kept displayed, marked stale). */
+export interface PanelEnrichment {
+    enrichment: CanvasEnrichment;
+    stale: boolean;
+}
+/** One workflow's full panel: title/badges header, step/entry stats, SVG
+ *  diagram — with any enrichment merged in (summary line, node/edge
+ *  annotations, a "stale" chip when its fingerprint no longer matches). */
+export declare function buildWorkflowPanelHtml(graph: CanvasGraph, meta: WorkflowPanelMeta, panelEnrichment?: PanelEnrichment | null): string;
+/** A degraded panel for a workflow whose graph couldn't be extracted — never
+ *  a crash, never a silent fallback to the LLM path, just an honest reason
+ *  styled through the same shell. */
+export declare function buildErrorPanelHtml(title: string, reason: string): string;
+/** Legend footer covering every node/edge kind actually used across every
+ *  rendered panel (aggregate, not per-panel — matches the template's shape). */
+export declare function buildLegendHtml(nodeKinds: Set<CanvasNodeKind>, edgeKinds: Set<CanvasEdgeKind>): string;
+/** Joins panels + a footer (enrichment notes/cross-workflow tie, legend,
+ *  note) into the final `#canvas-root` body — the string
+ *  `renderCanvasDocument()` wraps. */
+export declare function assembleCanvasBody(input: {
+    panels: string[];
+    legend: string;
+    note: string;
+    /** Enrichment footer facts (already schema-bounded), rendered as a list. */
+    notes?: string[];
+    /** Enrichment's "how this ties into the other workflows" line. */
+    crossWorkflow?: string;
+}): string;
+//# sourceMappingURL=canvas-body.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-body.d.ts","sourceRoot":"","sources":["../../src/core/canvas-body.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAO/D,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;iEAEiE;AACjE,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,gBAAgB,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;2EAE2E;AAC3E,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,iBAAiB,EACvB,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,GACvC,MAAM,CA4BR;AAED;;qCAEqC;AACrC,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAYzE;AAmBD;gFACgF;AAChF,wBAAgB,eAAe,CAAC,SAAS,EAAE,GAAG,CAAC,cAAc,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,cAAc,CAAC,GAAG,MAAM,CAWtG;AAED;;sCAEsC;AACtC,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,MAAM,CAcT"}

package/dist/core/canvas-body.js

@@ -0,0 +1,94 @@
+import { renderGraphSvg } from "./canvas-svg.js";
+function esc(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+/** One workflow's full panel: title/badges header, step/entry stats, SVG
+ *  diagram — with any enrichment merged in (summary line, node/edge
+ *  annotations, a "stale" chip when its fingerprint no longer matches). */
+export function buildWorkflowPanelHtml(graph, meta, panelEnrichment) {
+    const badges = (meta.badges ?? [])
+        .map((b) => `<span class="canvas-badge">${esc(b)}</span>`)
+        .join("");
+    const warningBadge = graph.warnings.length > 0
+        ? `<span class="canvas-badge">${graph.warnings.length} warning${graph.warnings.length === 1 ? "" : "s"}</span>`
+        : "";
+    const enrichment = panelEnrichment?.enrichment ?? null;
+    const staleBadge = panelEnrichment?.stale
+        ? `<span class="canvas-badge canvas-badge--stale">stale — Refresh</span>`
+        : "";
+    const summary = enrichment?.summary ? `\n    <p class="canvas-subtitle">${esc(enrichment.summary)}</p>` : "";
+    return `<section class="canvas-panel">
+  <header class="canvas-header">
+    <div class="canvas-title-row">
+      <h1 class="canvas-title">${esc(meta.title)}</h1>
+      ${badges}${warningBadge}${staleBadge}
+    </div>${summary}
+    <div class="canvas-stats">
+      <div class="canvas-stat"><span class="canvas-stat-value">${graph.nodes.length}</span><span class="canvas-stat-label">steps</span></div>
+      <div class="canvas-stat"><span class="canvas-stat-value">${esc(graph.entry)}</span><span class="canvas-stat-label">entry</span></div>
+    </div>
+  </header>
+  <div class="canvas-diagram-panel">
+${renderGraphSvg(graph, enrichment)}
+  </div>
+</section>`;
+}
+/** A degraded panel for a workflow whose graph couldn't be extracted — never
+ *  a crash, never a silent fallback to the LLM path, just an honest reason
+ *  styled through the same shell. */
+export function buildErrorPanelHtml(title, reason) {
+    return `<section class="canvas-panel">
+  <header class="canvas-header">
+    <div class="canvas-title-row">
+      <h1 class="canvas-title">${esc(title)}</h1>
+      <span class="canvas-badge">render failed</span>
+    </div>
+  </header>
+  <div class="canvas-diagram-panel">
+    <p class="canvas-empty-note">Could not extract this workflow's step graph: ${esc(reason)}. Ask your agent to fix the issue (see the terminal for details) — this pane updates automatically once it builds cleanly.</p>
+  </div>
+</section>`;
+}
+const NODE_KIND_LABEL = {
+    entry: "entry / active step",
+    step: "step",
+    pause: "pause / waits for input",
+    "terminal-success": "terminal · success",
+    "terminal-warn": "terminal · escalation",
+    "launched-workflow": "launches another workflow",
+};
+const NODE_KIND_ORDER = [
+    "entry",
+    "step",
+    "pause",
+    "terminal-success",
+    "terminal-warn",
+    "launched-workflow",
+];
+/** Legend footer covering every node/edge kind actually used across every
+ *  rendered panel (aggregate, not per-panel — matches the template's shape). */
+export function buildLegendHtml(nodeKinds, edgeKinds) {
+    const items = NODE_KIND_ORDER.filter((k) => nodeKinds.has(k)).map((k) => `<span class="canvas-legend-item"><span class="canvas-legend-marker canvas-legend-marker--${k}"></span>${NODE_KIND_LABEL[k]}</span>`);
+    if (edgeKinds.has("cross")) {
+        items.push(`<span class="canvas-legend-item"><span class="canvas-legend-marker canvas-legend-marker--cross"></span>cross-workflow signal/handoff</span>`);
+    }
+    return `<div class="canvas-legend">${items.join("")}</div>`;
+}
+/** Joins panels + a footer (enrichment notes/cross-workflow tie, legend,
+ *  note) into the final `#canvas-root` body — the string
+ *  `renderCanvasDocument()` wraps. */
+export function assembleCanvasBody(input) {
+    const parts = [...input.panels];
+    const notesHtml = input.notes && input.notes.length > 0
+        ? `\n  <ul class="canvas-notes">${input.notes.map((n) => `<li>${esc(n)}</li>`).join("")}</ul>`
+        : "";
+    const crossHtml = input.crossWorkflow
+        ? `\n  <p class="canvas-cross-workflow">${esc(input.crossWorkflow)}</p>`
+        : "";
+    parts.push(`<footer class="canvas-footer">${notesHtml}${crossHtml}
+${input.legend}
+  <p class="canvas-note">${esc(input.note)}</p>
+</footer>`);
+    return parts.join("\n\n");
+}
+//# sourceMappingURL=canvas-body.js.map

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

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

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

@@ -0,0 +1,23 @@
+import { type ExtractionResult } from "./canvas-graph.js";
+/** `<file count>:<newest mtimeMs>` over the workflow's own sources. */
+export declare function fingerprintWorkflowSources(root: string): Promise<string>;
+export interface CachedExtraction {
+    result: ExtractionResult;
+    /** True when the result came from cache — no child process ran. */
+    cached: boolean;
+    /** The source fingerprint the result corresponds to — the same value the
+     *  enrichment cache stores as `sourceFingerprint`, so freshness checks
+     *  compare like with like. */
+    fingerprint: string;
+}
+/**
+ * `extractWorkflowGraph` behind the fingerprint cache. The `extract`
+ * parameter exists for tests only (inject a spy to prove hit/miss behavior).
+ */
+export declare function extractWorkflowGraphCached(sourceDir: string, extract?: (dir: string) => Promise<ExtractionResult>): Promise<CachedExtraction>;
+/** Drops one workflow's cached extraction — the visualize macro's force
+ *  refresh, which must re-run the child process even for unchanged sources. */
+export declare function invalidateExtractionCache(sourceDir: string): void;
+/** Test hook — the cache is module-level state shared across a process. */
+export declare function clearExtractionCache(): void;
+//# sourceMappingURL=canvas-cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-cache.d.ts","sourceRoot":"","sources":["../../src/core/canvas-cache.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAwB,KAAK,gBAAgB,EAA0B,MAAM,mBAAmB,CAAC;AAGxG,uEAAuE;AACvE,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAa9E;AASD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,gBAAgB,CAAC;IACzB,mEAAmE;IACnE,MAAM,EAAE,OAAO,CAAC;IAChB;;kCAE8B;IAC9B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,CAC9C,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,CAAwB,GACzE,OAAO,CAAC,gBAAgB,CAAC,CAU3B;AAED;+EAC+E;AAC/E,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEjE;AAED,2EAA2E;AAC3E,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}

package/dist/core/canvas-cache.js

@@ -0,0 +1,64 @@
+/**
+ * In-memory extraction cache: binding an unchanged workflow must never pay
+ * for a child `check()` process twice. Keyed by workflow directory, guarded
+ * by a cheap source fingerprint (file count + newest mtime over the
+ * project's own `.ts`/`.tsx` sources — the same file walk the launch grep
+ * uses, see core/canvas-interconnections.ts's `listSourceFiles`). Any source
+ * edit bumps an mtime, any add/remove changes the count; either invalidates.
+ *
+ * Only SUCCESSFUL extractions are cached: a failure like "run npm install
+ * first" gets fixed without touching any `.ts` file, so a cached failure
+ * would never self-invalidate — re-running the (already fast-failing)
+ * extraction is the honest choice there.
+ *
+ * Process-lifetime only; a server restart re-extracts once per workflow.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { extractWorkflowGraph } from "./canvas-graph.js";
+import { listSourceFiles } from "./canvas-interconnections.js";
+/** `<file count>:<newest mtimeMs>` over the workflow's own sources. */
+export async function fingerprintWorkflowSources(root) {
+    const files = await listSourceFiles(root);
+    let maxMtimeMs = 0;
+    for (const file of files) {
+        try {
+            const stat = await fs.stat(file);
+            if (stat.mtimeMs > maxMtimeMs)
+                maxMtimeMs = stat.mtimeMs;
+        }
+        catch {
+            // A file deleted mid-walk still counts toward the file count; the next
+            // fingerprint won't include it, which is invalidation working as intended.
+        }
+    }
+    return `${files.length}:${maxMtimeMs}`;
+}
+const cache = new Map();
+/**
+ * `extractWorkflowGraph` behind the fingerprint cache. The `extract`
+ * parameter exists for tests only (inject a spy to prove hit/miss behavior).
+ */
+export async function extractWorkflowGraphCached(sourceDir, extract = extractWorkflowGraph) {
+    const key = path.resolve(sourceDir);
+    const fingerprint = await fingerprintWorkflowSources(key);
+    const hit = cache.get(key);
+    if (hit && hit.fingerprint === fingerprint)
+        return { result: hit.result, cached: true, fingerprint };
+    const result = await extract(key);
+    if (result.ok)
+        cache.set(key, { fingerprint, result });
+    else
+        cache.delete(key);
+    return { result, cached: false, fingerprint };
+}
+/** Drops one workflow's cached extraction — the visualize macro's force
+ *  refresh, which must re-run the child process even for unchanged sources. */
+export function invalidateExtractionCache(sourceDir) {
+    cache.delete(path.resolve(sourceDir));
+}
+/** Test hook — the cache is module-level state shared across a process. */
+export function clearExtractionCache() {
+    cache.clear();
+}
+//# sourceMappingURL=canvas-cache.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-cache.js","sourceRoot":"","sources":["../../src/core/canvas-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,oBAAoB,EAAiD,MAAM,mBAAmB,CAAC;AACxG,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAE/D,uEAAuE;AACvE,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,IAAY;IAC3D,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjC,IAAI,IAAI,CAAC,OAAO,GAAG,UAAU;gBAAE,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC;QAC3D,CAAC;QAAC,MAAM,CAAC;YACP,uEAAuE;YACvE,2EAA2E;QAC7E,CAAC;IACH,CAAC;IACD,OAAO,GAAG,KAAK,CAAC,MAAM,IAAI,UAAU,EAAE,CAAC;AACzC,CAAC;AAOD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;AAY5C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,SAAiB,EACjB,UAAsD,oBAAoB;IAE1E,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACpC,MAAM,WAAW,GAAG,MAAM,0BAA0B,CAAC,GAAG,CAAC,CAAC;IAC1D,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,GAAG,IAAI,GAAG,CAAC,WAAW,KAAK,WAAW;QAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAErG,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC;;QAClD,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACvB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;AAChD,CAAC;AAED;+EAC+E;AAC/E,MAAM,UAAU,yBAAyB,CAAC,SAAiB;IACzD,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;AACxC,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,oBAAoB;IAClC,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC"}