jev-devtools 0.2.0 → 0.3.0

package/lib/server/flows.js

@@ -0,0 +1,115 @@
+import { capture } from "./recorder.js";
+/** Independent bounded run store. Definitions are retained only while referenced. */
+export class FlowRecorder {
+    options;
+    runs = new Map();
+    definitions = new Map();
+    sessions = new Map();
+    definitionRevisions = new Map();
+    revisions = new Map();
+    revision = 0;
+    listeners = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    subscribe(fn) {
+        this.listeners.add(fn);
+        return () => {
+            this.listeners.delete(fn);
+        };
+    }
+    notify(sessions) {
+        for (const fn of this.listeners) {
+            try {
+                fn(sessions);
+            }
+            catch { }
+        }
+    }
+    start(definition, run, session) {
+        if (!this.definitions.has(definition.id)) {
+            const stored = structuredClone(definition);
+            for (const node of stored.nodes) {
+                if (node.conditionRule === undefined)
+                    continue;
+                try {
+                    node.conditionRule = capture(node.conditionRule, new Set(), this.options.redact
+                        ? (path, value) => this.options.redact(["conditions", node.id, ...path], value)
+                        : undefined);
+                }
+                catch {
+                    node.conditionRule = "[rule capture unavailable]";
+                }
+            }
+            this.definitions.set(definition.id, stored);
+            this.definitionRevisions.set(definition.id, ++this.revision);
+        }
+        this.runs.set(run.id, run);
+        this.sessions.set(run.id, session);
+        this.revisions.set(run.id, ++this.revision);
+        const sessions = new Set([session]);
+        const limit = Math.max(1, Math.min(200, this.options.limit ?? 50));
+        while (this.runs.size > limit) {
+            const id = this.runs.keys().next().value;
+            sessions.add(this.sessions.get(id));
+            this.remove(id);
+        }
+        this.prune();
+        this.notify(sessions);
+    }
+    update(run) {
+        if (!this.runs.has(run.id))
+            return; // Clear/eviction cannot resurrect pending runs.
+        const stored = { ...run };
+        if ("value" in stored) {
+            try {
+                stored.value = capture(stored.value, new Set(), this.options.redact);
+            }
+            catch {
+                stored.value = "[capture unavailable]";
+            }
+        }
+        this.runs.set(run.id, stored);
+        this.revisions.set(run.id, ++this.revision);
+        this.notify(new Set([this.sessions.get(run.id)]));
+    }
+    remove(id) {
+        this.runs.delete(id);
+        this.sessions.delete(id);
+        this.revisions.delete(id);
+    }
+    prune() {
+        const used = new Set([...this.runs.values()].map((r) => r.definitionId));
+        for (const id of this.definitions.keys())
+            if (!used.has(id)) {
+                this.definitions.delete(id);
+                this.definitionRevisions.delete(id);
+            }
+    }
+    clear(session) {
+        for (const id of this.runs.keys())
+            if (this.sessions.get(id) === session)
+                this.remove(id);
+        this.prune();
+        this.revision++;
+        this.notify(new Set([session]));
+    }
+    changes(session, cursor) {
+        const current = [...this.runs.values()]
+            .filter((r) => this.sessions.get(r.id) === session)
+            .reverse();
+        const used = new Set(current.map((r) => r.definitionId));
+        return {
+            revision: this.revision,
+            data: structuredClone({
+                version: 1,
+                definitions: [...used]
+                    .filter((id) => cursor === undefined ||
+                    this.definitionRevisions.get(id) > cursor)
+                    .map((id) => this.definitions.get(id)),
+                upserts: current.filter((r) => cursor === undefined || this.revisions.get(r.id) > cursor),
+                order: current.map((r) => r.id),
+            }),
+        };
+    }
+}

package/lib/server/index.d.ts

@@ -19,6 +19,14 @@ export type ClientMetadata = {
 };
 /** Node runtime adapter: framework-neutral Request/Response plus Node middleware. */
 export declare function createJevDevtools(options: JevDevtoolsServerOptions): {
+    startFlow: (definition: import("../src/flow-protocol.js").FlowDefinition, run: import("../src/flow-protocol.js").FlowRun) => {
+        update(run: import("../src/flow-protocol.js").FlowRun): void;
+        request<T>(link: {
+            runId: string;
+            stepId: string;
+            executionId: string;
+        }, onTrace: (id: string) => void, callback: () => T): T;
+    } | undefined;
     handle: (request: Request) => Promise<Response>;
     /**
      * For Node framework routes whose Request URL uses an internal hostname.

package/lib/server/index.js

@@ -1,3 +1,4 @@
+import { FlowRecorder } from "./flows.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
@@ -17,6 +18,7 @@ export function createJevDevtools(options) {
     if (options.enabled && !local && !options.authorize)
         throw new Error("Non-loopback inspector endpoints require authorize");
     const recorder = new JevRecorder(options), scope = new AsyncLocalStorage();
+    const flows = new FlowRecorder(options);
     const streams = new Set();
     const pending = new Set();
     const encoder = new TextEncoder();
@@ -91,15 +93,84 @@ export function createJevDevtools(options) {
             return json({ error: "Unauthorized" }, 403);
         const session = await sessionFor(request);
         if (url.pathname === endpoint && request.method === "GET")
-            return json({ version: 1, enabled: true });
+            return json({ version: 1, enabled: true, flows: true });
         if (url.pathname === endpoint + "/clear") {
             if (request.method !== "DELETE")
                 return json({ error: "Method not allowed" }, 405);
             if (request.headers.get("origin") !== origin)
                 return json({ error: "Same-origin requests required" }, 403);
             recorder.clear(session);
+            flows.clear(session);
             return json({ ok: true });
         }
+        let flowPull = () => { };
+        if (url.pathname === endpoint + "/flows/events") {
+            if (request.method !== "GET")
+                return json({ error: "Method not allowed" }, 405);
+            let stop = () => { };
+            const body = new ReadableStream({
+                start(controller) {
+                    let closed = false, dirty = true, cursor, timer;
+                    const flush = () => {
+                        timer = undefined;
+                        if (closed || !dirty || (controller.desiredSize ?? 0) <= 0)
+                            return;
+                        dirty = false;
+                        const update = flows.changes(session, cursor);
+                        cursor = update.revision;
+                        controller.enqueue(encoder.encode(`event: flows\ndata: ${JSON.stringify(update.data)}\n\n`));
+                    };
+                    const wake = () => {
+                        if (!closed && dirty && !timer)
+                            timer = setImmediate(flush);
+                    };
+                    const unsubscribe = flows.subscribe((sessions) => {
+                        if (sessions.has(session)) {
+                            dirty = true;
+                            wake();
+                        }
+                    });
+                    const heartbeat = setInterval(() => {
+                        if (!closed && (controller.desiredSize ?? 0) > 0)
+                            controller.enqueue(encoder.encode(": keepalive\n\n"));
+                    }, 15000);
+                    stop = () => {
+                        if (closed)
+                            return;
+                        closed = true;
+                        unsubscribe();
+                        clearImmediate(timer);
+                        clearInterval(heartbeat);
+                        request.signal.removeEventListener("abort", stop);
+                        streams.delete(stop);
+                        try {
+                            controller.close();
+                        }
+                        catch { }
+                    };
+                    streams.add(stop);
+                    request.signal.addEventListener("abort", stop, { once: true });
+                    flowPull = wake;
+                    if (request.signal.aborted)
+                        stop();
+                    else
+                        flush();
+                },
+                pull() {
+                    flowPull();
+                },
+                cancel() {
+                    stop();
+                },
+            });
+            return new Response(body, {
+                headers: {
+                    "content-type": "text/event-stream",
+                    "cache-control": "no-store",
+                    "x-accel-buffering": "no",
+                },
+            });
+        }
         if (url.pathname !== endpoint + "/events")
             return json({ error: "Not found" }, 404);
         if (request.method !== "GET")
@@ -209,7 +280,20 @@ export function createJevDevtools(options) {
                 res.destroy();
         }
     }
+    const startFlow = (definition, run) => {
+        if (!enabled())
+            return;
+        flows.start(definition, run, scope.getStore() ?? "local");
+        return {
+            update: (next) => {
+                if (enabled())
+                    flows.update(next);
+            },
+            request: (link, onTrace, callback) => recorder.withFlow(link, onTrace, callback),
+        };
+    };
     return {
+        startFlow,
         handle,
         /**
          * For Node framework routes whose Request URL uses an internal hostname.

package/lib/server/recorder.d.ts

@@ -1,10 +1,11 @@
 import { TypeSafeClient } from "@typesafe-ai/sdk";
 import type { Fetch } from "@typesafe-ai/sdk";
-import type { Trace } from "../src/protocol.js";
+import type { Json, Trace } from "../src/protocol.js";
 export type CaptureOptions = {
     limit?: number;
     redact?: (path: string[], value: unknown) => unknown;
 };
+export declare function capture(value: unknown, warnings: Set<string>, redact?: CaptureOptions["redact"]): Json;
 export declare class JevRecorder {
     private options;
     private traces;
@@ -12,6 +13,8 @@ export declare class JevRecorder {
     private revision;
     private revisions;
     private context;
+    private flowContext;
+    withFlow<T>(link: NonNullable<Trace["flow"]>, onTrace: (id: string) => void, callback: () => T): T;
     private limit;
     constructor(options?: CaptureOptions);
     snapshot(session: string): Trace[];

package/lib/server/recorder.js

@@ -5,7 +5,7 @@ const secretKey = /^(authorization|cookie|set-cookie|api[-_]?key|password|secret
 const safeMessage = (value) => value.replace(/Bearer\s+\S+/gi, "Bearer [redacted]").slice(0, 500);
 // Snapshot before the caller can mutate its request. Bounded and cycle-safe;
 // image handles become explicit previews/references instead of opaque SDK objects.
-function capture(value, warnings, redact) {
+export function capture(value, warnings, redact) {
     const seen = new WeakSet();
     let budget = 96_000;
     const visit = (input, path, depth) => {
@@ -82,6 +82,10 @@ export class JevRecorder {
     revision = 0;
     revisions = new WeakMap();
     context = new AsyncLocalStorage();
+    flowContext = new AsyncLocalStorage();
+    withFlow(link, onTrace, callback) {
+        return this.flowContext.run({ link, onTrace }, callback);
+    }
     limit;
     constructor(options = {}) {
         this.options = options;
@@ -196,6 +200,7 @@ export class JevRecorder {
                         version: 1,
                         id,
                         ...(typeof meta === "function" ? meta() : meta),
+                        flow: this.flowContext.getStore()?.link,
                         startedAt: Date.now(),
                         status: "pending",
                         request: captured,
@@ -203,6 +208,12 @@ export class JevRecorder {
                         captureWarnings: [...warnings],
                     });
                     const trace = this.traces.get(id);
+                    try {
+                        this.flowContext.getStore()?.onTrace(id);
+                    }
+                    catch {
+                        /* Observer only. */
+                    }
                     this.revisions.set(trace, ++this.revision);
                     const sessions = new Set([trace.session]);
                     while (this.traces.size > this.limit) {

package/lib/src/ChoiceProbabilities.js

@@ -10,7 +10,7 @@ export function ChoiceProbabilities({ answer }) {
     }, [rows, search]);
     const pages = Math.max(1, Math.ceil(filtered.length / 20));
     const current = Math.min(page, pages - 1);
-    return (_jsxs("div", { className: "lab-choice-browser", role: "region", "aria-label": "All Choice probabilities", children: [_jsxs("div", { className: "lab-choice-controls", children: [_jsxs("label", { children: ["Search categories", _jsx("input", { autoFocus: true, type: "search", value: search, onChange: (event) => {
+    return (_jsxs("div", { className: "lab-choice-browser", role: "region", "aria-label": "All Choice probabilities", "data-diagram-scroll": "", children: [_jsxs("div", { className: "lab-choice-controls", children: [_jsxs("label", { children: ["Search categories", _jsx("input", { autoFocus: true, type: "search", value: search, onChange: (event) => {
                                     setSearch(event.target.value);
                                     setPage(0);
                                 } })] }), _jsxs("span", { role: "status", children: [filtered.length, " of ", rows.length, " categories \u00B7 highest probability first"] })] }), _jsxs("div", { className: "lab-choice-table-scroll", tabIndex: 0, "aria-label": "Probability table", children: [_jsxs("table", { children: [_jsxs("caption", { children: ["Captured probabilities. Values are not renormalized. Returned choice: ", answer.choice ?? "unavailable", "."] }), _jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: "Category" }), _jsx("th", { scope: "col", children: "Probability" }), _jsx("th", { scope: "col", children: "Exact value (0\u20131)" })] }) }), _jsx("tbody", { children: filtered

package/lib/src/ConnectedInspector.js

@@ -3,6 +3,7 @@ import { memo, useCallback, useEffect, useRef, useState } from "react";
 import { JevPanel } from "./JevDevtools.js";
 import { JevDrawer } from "./JevDrawer.js";
 import { connectTraceStream } from "./trace-stream.js";
+import { connectFlowStream, emptyFlows, } from "./flow-stream.js";
 const RetainedPanel = memo(JevPanel);
 function endpointUrl(endpoint) {
     const url = new URL(endpoint, window.location.origin);
@@ -18,7 +19,11 @@ export default function ConnectedInspector({ endpoint = "/api/jev-devtools", def
     const [open, setOpen] = useState(defaultOpen);
     const [visited, setVisited] = useState(defaultOpen);
     const visible = useRef(defaultOpen);
-    const latest = useRef({ traces: [], connection: "connecting" });
+    const latest = useRef({
+        traces: [],
+        connection: "connecting",
+        flows: emptyFlows,
+    });
     const [snapshot, setSnapshot] = useState(latest.current);
     const toggle = (value) => {
         visible.current = value;
@@ -29,20 +34,21 @@ export default function ConnectedInspector({ endpoint = "/api/jev-devtools", def
         }
     };
     useEffect(() => {
-        let alive = true, disconnect = () => { };
+        let alive = true, disconnect = () => { }, disconnectFlows = () => { };
         const abort = new AbortController();
         // Keep capture current while closed without scheduling React work. Reopening
         // publishes only the latest snapshot; the retained panel keeps its UI state.
         const update = (patch) => {
             const next = { ...latest.current, ...patch };
             if (next.traces === latest.current.traces &&
-                next.connection === latest.current.connection)
+                next.connection === latest.current.connection &&
+                next.flows === latest.current.flows)
                 return;
             latest.current = next;
             if (visible.current)
                 setSnapshot(latest.current);
         };
-        update({ traces: [], connection: "connecting" });
+        update({ traces: [], connection: "connecting", flows: emptyFlows });
         void (async () => {
             try {
                 const url = endpointUrl(endpoint);
@@ -59,6 +65,8 @@ export default function ConnectedInspector({ endpoint = "/api/jev-devtools", def
                     throw new Error("Unsupported inspector endpoint");
                 if (!alive)
                     return;
+                if (config.flows)
+                    disconnectFlows = connectFlowStream(url, (flows) => update({ flows }));
                 disconnect = connectTraceStream(url, (traces) => update({ traces }), (connection) => update({ connection }));
             }
             catch (error) {
@@ -72,6 +80,7 @@ export default function ConnectedInspector({ endpoint = "/api/jev-devtools", def
             alive = false;
             abort.abort();
             disconnect();
+            disconnectFlows();
         };
     }, [endpoint]);
     const clear = useCallback(async () => {

package/lib/src/DiagramContent.d.ts

@@ -0,0 +1,6 @@
+import type { Json } from "./protocol.js";
+/** Bounded, lazy property rendering inside a fixed-size diagram card. */
+export declare const DiagramContent: import("react").MemoExoticComponent<({ value, label, }: {
+    value: Json | undefined;
+    label: string;
+}) => import("react").JSX.Element>;

package/lib/src/DiagramContent.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { memo, useMemo, useState } from "react";
+const PAGE_SIZE = 12;
+function TextValue({ value }) {
+    const [expanded, setExpanded] = useState(false);
+    const long = value.length > 140 || value.split("\n").length > 3;
+    return (_jsxs("span", { className: "diagram-text-value", children: [_jsx("span", { className: long && !expanded ? "diagram-text-preview" : undefined, children: value === "" ? (_jsx("span", { className: "diagram-value-empty", children: "empty string" })) : long && !expanded ? (`${value.slice(0, 140)}${value.length > 140 ? "…" : ""}`) : (value) }), long && (_jsx("button", { type: "button", className: "diagram-content-toggle", "aria-expanded": expanded, onClick: () => setExpanded(!expanded), children: expanded ? "Less text" : "Full text" }))] }));
+}
+function Properties({ value }) {
+    const [visible, setVisible] = useState(PAGE_SIZE);
+    const entries = useMemo(() => Object.entries(value), [value]);
+    if (!entries.length)
+        return (_jsx("span", { className: "diagram-value-empty", children: Array.isArray(value) ? "[] Empty array" : "{} Empty object" }));
+    return (_jsxs("div", { className: "diagram-properties", children: [entries.slice(0, visible).map(([name, child]) => (_jsx(Property, { name: name, value: child }, name))), visible < entries.length && (_jsxs("button", { type: "button", className: "diagram-content-toggle", onClick: () => setVisible((count) => count + PAGE_SIZE), children: ["Show ", Math.min(PAGE_SIZE, entries.length - visible), " more (", entries.length - visible, " remaining)"] })), visible > PAGE_SIZE && (_jsx("button", { type: "button", className: "diagram-content-toggle", onClick: () => setVisible(PAGE_SIZE), children: "Fewer properties" }))] }));
+}
+function Scalar({ value }) {
+    if (typeof value === "string")
+        return _jsx(TextValue, { value: value });
+    return (_jsx("span", { className: `diagram-value-${value === null || value === undefined ? "empty" : typeof value}`, children: value === undefined ? "Not captured" : String(value) }));
+}
+function Property({ name, value }) {
+    const [expanded, setExpanded] = useState(false);
+    const object = value !== null && typeof value === "object";
+    if (!object)
+        return (_jsxs("div", { className: `diagram-property ${typeof value === "string" ? "diagram-property-text" : ""}`, children: [_jsx("span", { className: "diagram-property-key", children: name || '""' }), _jsx(Scalar, { value: value })] }));
+    const count = Object.keys(value).length;
+    return (_jsxs("div", { className: "diagram-property-group", children: [_jsxs("button", { type: "button", className: "diagram-property-disclosure", "aria-label": `${expanded ? "Collapse" : "Expand"} ${name || '""'}`, "aria-expanded": expanded, onClick: () => setExpanded(!expanded), children: [_jsx("span", { "aria-hidden": "true", className: "diagram-property-caret", children: expanded ? "▾" : "▸" }), _jsx("span", { className: "diagram-property-key", children: name || '""' }), _jsx("span", { className: "diagram-property-type", children: Array.isArray(value) ? `[${count}]` : `{${count}}` })] }), expanded && (_jsx("div", { className: "diagram-property-children", children: _jsx(Properties, { value: value }) }))] }));
+}
+/** Bounded, lazy property rendering inside a fixed-size diagram card. */
+export const DiagramContent = memo(function DiagramContent({ value, label, }) {
+    return (_jsx("div", { className: "diagram-content", "data-diagram-scroll": true, role: "region", "aria-label": label, tabIndex: 0, children: value !== null && typeof value === "object" ? (_jsx(Properties, { value: value })) : (_jsx(Scalar, { value: value })) }));
+});

package/lib/src/FlowOverview.d.ts

@@ -0,0 +1,7 @@
+import type { FlowDefinition, FlowRun } from "./flow-protocol.js";
+import type { Trace } from "./protocol.js";
+export declare const FlowOverview: import("react").MemoExoticComponent<({ definition, run, traces, }: {
+    definition: FlowDefinition;
+    run: FlowRun;
+    traces: Trace[];
+}) => import("react").JSX.Element>;