jev-devtools 0.3.0 → 0.4.1

package/lib/flow/runtime.js

@@ -0,0 +1,81 @@
+/** Detached JSON snapshot, without capture truncation or lossy JSON.stringify. */
+export function jsonSnapshot(value, seen = new Set(), depth = 0) {
+    if (depth > 40)
+        throw new TypeError("Task data nesting exceeds 40");
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (!value ||
+        typeof value !== "object" ||
+        (!Array.isArray(value) &&
+            Object.getPrototypeOf(value) !== Object.prototype &&
+            Object.getPrototypeOf(value) !== null))
+        throw new TypeError("Task inputs and outputs must be JSON-compatible");
+    if (seen.has(value))
+        throw new TypeError("Task data cannot contain cycles");
+    if (Object.getOwnPropertySymbols(value).length)
+        throw new TypeError("Task data cannot contain symbol keys");
+    seen.add(value);
+    try {
+        if (Array.isArray(value))
+            return Array.from(value, (v) => jsonSnapshot(v, seen, depth + 1));
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [
+            k,
+            jsonSnapshot(v, seen, depth + 1),
+        ]));
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+/** Cancellation ends awaiting, even when user code ignores the cooperative signal. */
+export function runCallback(callback, parent, timeoutMs) {
+    const controller = new AbortController();
+    const started = performance.now();
+    return new Promise((resolve, reject) => {
+        let timer;
+        let settled = false;
+        const cleanup = () => {
+            clearTimeout(timer);
+            parent.removeEventListener("abort", cancel);
+        };
+        const finish = (error, value, failed = false) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (failed)
+                reject(error);
+            else
+                resolve(value);
+        };
+        const stop = (error) => {
+            controller.abort(error);
+            finish(error, undefined, true);
+        };
+        const cancel = () => stop(new DOMException("Flow cancelled", "AbortError"));
+        if (parent.aborted) {
+            cancel();
+            return;
+        }
+        parent.addEventListener("abort", cancel, { once: true });
+        if (timeoutMs !== undefined)
+            timer = setTimeout(() => stop(new DOMException("Task timed out", "TimeoutError")), timeoutMs);
+        Promise.resolve()
+            .then(() => {
+            if (controller.signal.aborted)
+                throw controller.signal.reason;
+            return callback(controller.signal);
+        })
+            .then((value) => {
+            // CPU-bound callbacks cannot be interrupted, but their late result must
+            // still not advance the flow after the configured deadline.
+            if (timeoutMs !== undefined &&
+                performance.now() - started >= timeoutMs)
+                stop(new DOMException("Task timed out", "TimeoutError"));
+            else
+                finish(undefined, value);
+        }, (error) => finish(error, undefined, true));
+    });
+}

package/lib/server/flows.d.ts

@@ -10,10 +10,13 @@ export declare class FlowRecorder {
     private revisions;
     private revision;
     private listeners;
+    private itemCaptures;
+    private taskCaptures;
     constructor(options: CaptureOptions);
     subscribe(fn: (sessions: Set<string>) => void): () => void;
     private notify;
     start(definition: FlowDefinition, run: FlowRun, session: string): void;
+    private captureRun;
     update(run: FlowRun): void;
     private remove;
     private prune;

package/lib/server/flows.js

@@ -9,6 +9,8 @@ export class FlowRecorder {
     revisions = new Map();
     revision = 0;
     listeners = new Set();
+    itemCaptures = new WeakMap();
+    taskCaptures = new WeakMap();
     constructor(options) {
         this.options = options;
     }
@@ -29,18 +31,23 @@ export class FlowRecorder {
     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);
+            const redactRules = (definition, prefix = []) => {
+                for (const node of definition.nodes) {
+                    if (node.itemDefinition)
+                        redactRules(node.itemDefinition, [...prefix, node.id, "items"]);
+                    if (node.conditionRule === undefined)
+                        continue;
+                    try {
+                        node.conditionRule = capture(node.conditionRule, new Set(), this.options.redact
+                            ? (path, value) => this.options.redact(["conditions", ...prefix, node.id, ...path], value)
+                            : undefined);
+                    }
+                    catch {
+                        node.conditionRule = "[rule capture unavailable]";
+                    }
                 }
-                catch {
-                    node.conditionRule = "[rule capture unavailable]";
-                }
-            }
+            };
+            redactRules(stored);
             this.definitions.set(definition.id, stored);
             this.definitionRevisions.set(definition.id, ++this.revision);
         }
@@ -57,19 +64,84 @@ export class FlowRecorder {
         this.prune();
         this.notify(sessions);
     }
-    update(run) {
-        if (!this.runs.has(run.id))
-            return; // Clear/eviction cannot resurrect pending runs.
-        const stored = { ...run };
+    captureRun(run, prefix = []) {
+        // Child updates are immutable snapshots; unchanged items need no recapture.
+        const previous = prefix.length ? this.itemCaptures.get(run) : undefined;
+        if (previous)
+            return previous;
+        const stored = {
+            ...run,
+            steps: Object.fromEntries(Object.entries(run.steps).map(([id, raw]) => {
+                const step = { ...raw };
+                if (raw.collection)
+                    step.collection = {
+                        ...raw.collection,
+                        items: raw.collection.items.map((item) => ({
+                            ...item,
+                            ...(item.run
+                                ? {
+                                    run: this.captureRun(item.run, [
+                                        ...prefix,
+                                        "steps",
+                                        id,
+                                        "items",
+                                        String(item.index),
+                                    ]),
+                                }
+                                : {}),
+                        })),
+                    };
+                if (step.data === undefined)
+                    return [id, { ...step }];
+                const key = step.data;
+                let captured = key && typeof key === "object"
+                    ? this.taskCaptures.get(key)
+                    : undefined;
+                if (!captured) {
+                    const warnings = new Set();
+                    let data;
+                    try {
+                        data =
+                            capture(step.data, warnings, this.options.redact
+                                ? (path, value) => this.options.redact([...prefix, "steps", id, "data", ...path], value)
+                                : undefined) ?? null;
+                    }
+                    catch {
+                        data = "[capture unavailable]";
+                        warnings.add("Task capture unavailable.");
+                    }
+                    captured = { data, warnings: [...warnings] };
+                    if (key && typeof key === "object")
+                        this.taskCaptures.set(key, captured);
+                }
+                return [
+                    id,
+                    {
+                        ...step,
+                        data: captured.data,
+                        captureWarnings: captured.warnings,
+                    },
+                ];
+            })),
+        };
         if ("value" in stored) {
             try {
-                stored.value = capture(stored.value, new Set(), this.options.redact);
+                stored.value = capture(stored.value, new Set(), this.options.redact
+                    ? (path, value) => this.options.redact([...prefix, ...path], value)
+                    : undefined);
             }
             catch {
                 stored.value = "[capture unavailable]";
             }
         }
-        this.runs.set(run.id, stored);
+        if (prefix.length)
+            this.itemCaptures.set(run, stored);
+        return stored;
+    }
+    update(run) {
+        if (!this.runs.has(run.id))
+            return; // Clear/eviction cannot resurrect pending runs.
+        this.runs.set(run.id, this.captureRun(run));
         this.revisions.set(run.id, ++this.revision);
         this.notify(new Set([this.sessions.get(run.id)]));
     }

package/lib/server/index.d.ts

@@ -8,7 +8,10 @@ export type JevDevtoolsServerOptions = CaptureOptions & {
     enabled?: boolean;
     origin: string;
     endpoint?: string;
-    /** Required for non-loopback origins. Apply your application's authentication. */
+    /**
+     * Required for non-loopback origins. Without it, Node middleware only accepts
+     * loopback connections. Apply your application's authentication.
+     */
     authorize?: (request: Request) => boolean | Promise<boolean>;
     /** Server-derived scope. Defaults to a shared local-development history. */
     getSession?: (request: Request) => string | Promise<string>;
@@ -32,6 +35,8 @@ export declare function createJevDevtools(options: JevDevtoolsServerOptions): {
      * For Node framework routes whose Request URL uses an internal hostname.
      * Require the actual Host header to match the configured public authority;
      * never trust forwarded host/protocol headers. Origin checks still apply.
+     * A Request does not expose the socket peer and any non-browser client can
+     * set Host, so bind the server to loopback or set authorize.
      */
     handleNodeRoute(request: Request): Promise<Response>;
     middleware: (req: IncomingMessage, res: ServerResponse, next: () => void) => Promise<void>;

package/lib/server/index.js

@@ -5,6 +5,8 @@ import { pipeline } from "node:stream/promises";
 import { TypeSafeClient } from "@typesafe-ai/sdk";
 import { JevRecorder } from "./recorder.js";
 export { JevRecorder } from "./recorder.js";
+// Host and Origin are client-controlled, so locality is decided by the socket peer.
+const isLoopback = (address = "") => address === "::1" || /^(::ffff:)?127\./.test(address);
 const json = (data, status = 200) => Response.json(data, { status, headers: { "cache-control": "no-store" } });
 /** Node runtime adapter: framework-neutral Request/Response plus Node middleware. */
 export function createJevDevtools(options) {
@@ -256,6 +258,17 @@ export function createJevDevtools(options) {
             next();
             return;
         }
+        if (enabled() &&
+            !options.authorize &&
+            !isLoopback(req.socket.remoteAddress)) {
+            res
+                .writeHead(403, {
+                "content-type": "application/json",
+                "cache-control": "no-store",
+            })
+                .end('{"error":"Loopback connections required without authorize"}');
+            return;
+        }
         const abort = new AbortController();
         res.once("close", () => abort.abort());
         try {
@@ -299,6 +312,8 @@ export function createJevDevtools(options) {
          * For Node framework routes whose Request URL uses an internal hostname.
          * Require the actual Host header to match the configured public authority;
          * never trust forwarded host/protocol headers. Origin checks still apply.
+         * A Request does not expose the socket peer and any non-browser client can
+         * set Host, so bind the server to loopback or set authorize.
          */
         handleNodeRoute(request) {
             if (!enabled())

package/lib/server/recorder.js

@@ -67,10 +67,15 @@ export function capture(value, warnings, redact) {
                 .map((v, i) => visit(v, [...path, String(i)], depth + 1));
         }
         const entries = Object.entries(input);
-        if (entries.length > 150)
+        // Choice maps need room for the full roster; retain the overall byte/depth
+        // budget and the smaller general-purpose object/array limit.
+        const entryLimit = ["criteria", "probabilities"].includes(path.at(-1) ?? "")
+            ? 256
+            : 150;
+        if (entries.length > entryLimit)
             warnings.add("Long collection truncated in capture.");
         return Object.fromEntries(entries
-            .slice(0, 150)
+            .slice(0, entryLimit)
             .map(([key, v]) => [key, visit(v, [...path, key], depth + 1)]));
     };
     return visit(value, [], 0);

package/lib/src/FlowDetailsPanel.d.ts

@@ -0,0 +1,8 @@
+import { type ReactNode } from "react";
+/** Keep metadata out of the canvas until requested; size it within the flow workspace. */
+export declare function FlowDetailsPanel({ children, selection, onLayoutChange, inline, }: {
+    children: ReactNode;
+    selection?: string;
+    onLayoutChange: () => void;
+    inline?: boolean;
+}): import("react").JSX.Element;

package/lib/src/FlowDetailsPanel.js

@@ -0,0 +1,79 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState } from "react";
+/** Keep metadata out of the canvas until requested; size it within the flow workspace. */
+export function FlowDetailsPanel({ children, selection, onLayoutChange, inline = false, }) {
+    const id = useId();
+    const panel = useRef(null);
+    const drag = useRef(null);
+    const [open, setOpen] = useState(false);
+    const [height, setHeight] = useState(240);
+    const [max, setMax] = useState(0);
+    const min = Math.min(96, max);
+    const visibleHeight = Math.max(min, Math.min(max, height));
+    useEffect(() => {
+        const workspace = panel.current?.parentElement;
+        if (!workspace)
+            return;
+        const measure = () => {
+            // Inline panels grow the canvas instead of taking space from a fixed viewport.
+            // Exclude the panel itself so resizing cannot grow its own upper bound.
+            const available = workspace.clientHeight -
+                (inline ? panel.current?.offsetHeight ?? 0 : 0);
+            // Leave room for the bar/divider and a usable canvas, including short drawers.
+            setMax(Math.max(0, available - Math.min(140, available * 0.45) - 44));
+        };
+        measure();
+        const observer = new ResizeObserver(measure);
+        observer.observe(workspace);
+        return () => observer.disconnect();
+    }, [inline]);
+    const resize = (next) => {
+        onLayoutChange();
+        setHeight(Math.max(min, Math.min(max, next)));
+    };
+    return (_jsxs("div", { className: "flow-details-panel", ref: panel, "data-diagram-scroll": true, children: [open && (_jsx("div", { className: "flow-details-resize", role: "separator", tabIndex: 0, "aria-label": "Resize flow details", "aria-orientation": "horizontal", "aria-controls": id, "aria-valuemin": Math.round(min), "aria-valuemax": Math.round(max), "aria-valuenow": Math.round(visibleHeight), "aria-valuetext": `${Math.round(visibleHeight)} pixels high`, onPointerDown: (event) => {
+                    if (event.button !== 0)
+                        return;
+                    event.preventDefault();
+                    event.currentTarget.focus({ preventScroll: true });
+                    event.currentTarget.setPointerCapture(event.pointerId);
+                    drag.current = {
+                        y: event.clientY,
+                        height: visibleHeight,
+                        // Inline item details share the outer canvas zoom.
+                        scale: event.currentTarget.getBoundingClientRect().height /
+                            event.currentTarget.offsetHeight || 1,
+                    };
+                }, onPointerMove: (event) => {
+                    if (drag.current)
+                        resize(drag.current.height +
+                            (drag.current.y - event.clientY) / drag.current.scale);
+                }, onPointerUp: (event) => {
+                    drag.current = null;
+                    if (event.currentTarget.hasPointerCapture(event.pointerId))
+                        event.currentTarget.releasePointerCapture(event.pointerId);
+                }, onPointerCancel: () => {
+                    drag.current = null;
+                }, onLostPointerCapture: () => {
+                    drag.current = null;
+                }, onKeyDown: (event) => {
+                    const increment = event.shiftKey ? 80 : 20;
+                    const next = event.key === "ArrowUp"
+                        ? visibleHeight + increment
+                        : event.key === "ArrowDown"
+                            ? visibleHeight - increment
+                            : event.key === "Home"
+                                ? min
+                                : event.key === "End"
+                                    ? max
+                                    : undefined;
+                    if (next !== undefined) {
+                        event.preventDefault();
+                        event.stopPropagation();
+                        resize(next);
+                    }
+                }, children: _jsx("span", {}) })), _jsxs("div", { className: "flow-details-bar", children: [_jsx("button", { "aria-expanded": open, "aria-controls": id, onClick: () => {
+                            onLayoutChange();
+                            setOpen(!open);
+                        }, children: open ? "Hide details" : "Show details" }), selection && _jsx("span", { title: selection, children: selection })] }), _jsx("div", { id: id, hidden: !open, className: "flow-details-body", role: "region", "aria-label": "Flow details", tabIndex: 0, style: { height: visibleHeight }, children: open && children })] }));
+}

package/lib/src/FlowOverview.d.ts

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