@clemrig/flow-ui 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clément CHESNEAU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# @clemrig/flow-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A local, read-only dashboard of the runs of [`@clemrig/flow`](https://www.npmjs.com/package/@clemrig/flow) workflows.
+
+## Use
+
+Requires macOS or Linux and Node.js 24 or later.
+
+```sh
+npm install -g @clemrig/flow-ui
+flow-ui [RUNS_DIR] [--port PORT]
+```
+
+`flow-ui` serves the runs kept in `RUNS_DIR` (default: `.flow/runs`, where `@clemrig/flow` keeps them; a `RUNS_DIR` given must be an existing directory) on `127.0.0.1`, on `PORT` or a port the system chooses, prints its URL and stops on Ctrl-C. The page lists the runs with their workflow, status, current stage, duration, estimated cost and last update, and for a run its runtimes, a timeline with one block per stage (agent tools and tokens, journal, decision), its correction counters and its result. It follows a running run as it goes. A result shows the run's validated data as JSON.
+
+To watch a run on another machine, forward the same port through SSH: `ssh -L 4321:127.0.0.1:4321 machine`, run `flow-ui --port 4321` there, and open `http://localhost:4321/`.
+
+While it runs, any local process that can reach `127.0.0.1` can read the runs it serves.
+
+## From code
+
+```ts
+import { startDashboard } from "@clemrig/flow-ui";
+
+const dashboard = await startDashboard({
+  runsDir: ".flow/runs",
+  title: "flow",
+  label: "my-project",
+  presentResult: (state) => [JSON.stringify(state.data)], // optional
+});
+console.log(dashboard.url);
+// later: await dashboard.close();
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+/** `flow-ui`: serves the dashboard of a runs directory until Ctrl-C. */
+export declare function main(argv: string[], cwd: string): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,73 @@
+import { stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { defaultRunsDir } from "@clemrig/flow";
+import { startDashboard } from "./server.js";
+const usage = `Usage: flow-ui [RUNS_DIR] [--port PORT]
+
+Serves a read-only dashboard of the runs kept in RUNS_DIR (default: .flow/runs)
+on 127.0.0.1, on PORT or one the system chooses, until Ctrl-C.
+`;
+/** `--port`: a fixed port, so that an SSH tunnel can forward the same one. */
+function parsePort(value) {
+    const port = Number(value);
+    if (value === undefined || !/^\d+$/.test(value) || port < 1 || port > 65535)
+        throw new Error(`Invalid --port ${value ?? ""}: expected a port from 1 to 65535`);
+    return port;
+}
+/** `flow-ui`: serves the dashboard of a runs directory until Ctrl-C. */
+export async function main(argv, cwd) {
+    try {
+        if (argv.includes("--help") || argv.includes("-h")) {
+            process.stdout.write(usage);
+            return 0;
+        }
+        const positional = [];
+        let port;
+        for (let i = 0; i < argv.length; i++) {
+            const arg = argv[i] ?? "";
+            if (arg === "--port") {
+                if (port !== undefined)
+                    throw new Error("Duplicate option --port");
+                port = parsePort(argv[++i]);
+            }
+            else if (arg.startsWith("-"))
+                throw new Error(`Unknown option ${arg}; see flow-ui --help`);
+            else
+                positional.push(arg);
+        }
+        if (positional.length > 1)
+            throw new Error("flow-ui takes one runs directory; see flow-ui --help");
+        const runsDir = positional[0]
+            ? resolve(cwd, positional[0])
+            : defaultRunsDir(cwd);
+        // The default may not exist before the first run; a directory given must.
+        const found = await stat(runsDir).catch((error) => {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        });
+        if (found ? !found.isDirectory() : positional[0] !== undefined)
+            throw new Error(`No runs directory at ${runsDir}`);
+        const inside = relative(cwd, runsDir);
+        const outside = inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside);
+        const label = outside ? runsDir : inside || ".";
+        const dashboard = await startDashboard({ runsDir, title: "flow", label }, port);
+        process.stdout.write(`flow-ui: ${dashboard.url} (runs in ${label}; read-only; Ctrl-C to stop)\n`);
+        await new Promise((resolve) => {
+            const stop = () => {
+                process.off("SIGINT", stop);
+                process.off("SIGTERM", stop);
+                resolve();
+            };
+            process.on("SIGINT", stop);
+            process.on("SIGTERM", stop);
+        });
+        await dashboard.close();
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`flow-ui: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+/** Public API of the dashboard: serve a read-only view of runs kept by `@clemrig/flow`. */
+export { type DashboardOptions, startDashboard } from "./server.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+/** Public API of the dashboard: serve a read-only view of runs kept by `@clemrig/flow`. */
+export { startDashboard } from "./server.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAE3F,OAAO,EAAyB,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "./cli.js";
+process.exitCode = await main(process.argv.slice(2), process.cwd());
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAEhC,OAAO,CAAC,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,18 @@
+import { type Server } from "node:http";
+import { type RunState } from "@clemrig/flow";
+export interface DashboardOptions {
+    /** Where the runs are kept. */
+    runsDir: string;
+    /** The page's title. */
+    title: string;
+    /** Shown beside the title: what the runs belong to. */
+    label: string;
+    /** A run's result lines; by default, its validated data as JSON. */
+    presentResult?(state: Readonly<RunState>): string[];
+}
+/** A read-only view of the runs on 127.0.0.1, on `port` or one chosen by the system. */
+export declare function startDashboard(options: DashboardOptions, listen?: number): Promise<{
+    url: string;
+    server: Server;
+    close(): Promise<void>;
+}>;

package/dist/server.js

@@ -0,0 +1,107 @@
+import { readFile } from "node:fs/promises";
+import { createServer, } from "node:http";
+import { listRuns, loadRun, loadRunEvents, presentResult, summarizeCorrections, summarizeRun, UnknownRunError, } from "@clemrig/flow";
+/** The runs, newest first; an unreadable run with its error. */
+async function runs(options) {
+    return {
+        title: options.title,
+        label: options.label,
+        runs: (await listRuns(options.runsDir))
+            .reverse()
+            .map((entry) => ("state" in entry ? summarizeRun(entry.state) : entry)),
+    };
+}
+/** A run with its events from the `after`-th: the page asks only for what it has not received. */
+async function detail(options, id, after) {
+    const state = await loadRun(options.runsDir, id);
+    const events = await loadRunEvents(options.runsDir, id);
+    return {
+        run: summarizeRun(state),
+        runtimes: state.runtimes ?? {},
+        error: state.error ?? null,
+        events: events.slice(after),
+        next: events.length,
+        // Each correction's maximum comes from all its events, not only those sent.
+        corrections: summarizeCorrections(state, events),
+        result: presentResult(options, state),
+    };
+}
+/** The page's files, served as they are: no script or style is ever inline. */
+const pageFiles = {
+    "/": ["index.html", "text/html; charset=utf-8"],
+    "/style.css": ["style.css", "text/css; charset=utf-8"],
+    "/dashboard.js": ["dashboard.js", "text/javascript; charset=utf-8"],
+    "/timeline.js": ["timeline.js", "text/javascript; charset=utf-8"],
+    "/follow.js": ["follow.js", "text/javascript; charset=utf-8"],
+};
+async function loadPage() {
+    const page = new Map();
+    for (const [path, [file, type]] of Object.entries(pageFiles))
+        page.set(path, {
+            body: await readFile(new URL(`./static/${file}`, import.meta.url), "utf8"),
+            type,
+        });
+    return page;
+}
+function send(response, status, body, type = "text/plain; charset=utf-8") {
+    response.writeHead(status, {
+        "content-type": type,
+        "cache-control": "no-store",
+        "x-content-type-options": "nosniff",
+        "content-security-policy": "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
+    });
+    response.end(body);
+}
+/** A read-only view of the runs on 127.0.0.1, on `port` or one chosen by the system. */
+export async function startDashboard(options, listen = 0) {
+    let port = 0;
+    const page = await loadPage();
+    const handle = async (request, response) => {
+        // Another Host means another site reached this port (DNS rebinding).
+        if (request.headers.host !== `127.0.0.1:${port}` &&
+            request.headers.host !== `localhost:${port}`)
+            return send(response, 403, "Forbidden");
+        if (request.method !== "GET")
+            return send(response, 405, "Method Not Allowed");
+        const url = new URL(request.url ?? "/", "http://127.0.0.1");
+        const file = page.get(url.pathname);
+        if (file)
+            return send(response, 200, file.body, file.type);
+        if (url.pathname === "/api/runs")
+            return send(response, 200, JSON.stringify(await runs(options)), "application/json");
+        const id = /^\/api\/runs\/([^/]+)$/.exec(url.pathname)?.[1];
+        if (id === undefined)
+            return send(response, 404, "Not Found");
+        const after = url.searchParams.get("after") ?? "0";
+        if (!/^\d+$/.test(after))
+            return send(response, 400, "Bad Request");
+        let body;
+        try {
+            body = await detail(options, decodeURIComponent(id), Number(after));
+        }
+        catch (error) {
+            // A run that cannot be read now may be read at the next request.
+            return error instanceof UnknownRunError
+                ? send(response, 404, "Not Found")
+                : send(response, 500, error instanceof Error ? error.message : String(error));
+        }
+        return send(response, 200, JSON.stringify(body), "application/json");
+    };
+    const server = createServer((request, response) => {
+        handle(request, response).catch((error) => send(response, 500, error instanceof Error ? error.message : String(error)));
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(listen, "127.0.0.1", () => resolve());
+    });
+    port = server.address().port;
+    return {
+        url: `http://127.0.0.1:${port}/`,
+        server,
+        close: () => new Promise((resolve, reject) => {
+            server.close((error) => (error ? reject(error) : resolve()));
+            server.closeAllConnections();
+        }),
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EACL,YAAY,GAIb,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,QAAQ,EACR,OAAO,EACP,aAAa,EACb,aAAa,EAEb,oBAAoB,EACpB,YAAY,EACZ,eAAe,GAChB,MAAM,eAAe,CAAC;AAavB,gEAAgE;AAChE,KAAK,UAAU,IAAI,CAAC,OAAyB;IAC3C,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,IAAI,EAAE,CAAC,MAAM,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;aACpC,OAAO,EAAE;aACT,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;KAC1E,CAAC;AACJ,CAAC;AAED,kGAAkG;AAClG,KAAK,UAAU,MAAM,CAAC,OAAyB,EAAE,EAAU,EAAE,KAAa;IACxE,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACxD,OAAO;QACL,GAAG,EAAE,YAAY,CAAC,KAAK,CAAC;QACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,EAAE;QAC9B,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,IAAI;QAC1B,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC;QAC3B,IAAI,EAAE,MAAM,CAAC,MAAM;QACnB,4EAA4E;QAC5E,WAAW,EAAE,oBAAoB,CAAC,KAAK,EAAE,MAAM,CAAC;QAChD,MAAM,EAAE,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC;KACtC,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,MAAM,SAAS,GAAG;IAChB,GAAG,EAAE,CAAC,YAAY,EAAE,0BAA0B,CAAC;IAC/C,YAAY,EAAE,CAAC,WAAW,EAAE,yBAAyB,CAAC;IACtD,eAAe,EAAE,CAAC,cAAc,EAAE,gCAAgC,CAAC;IACnE,cAAc,EAAE,CAAC,aAAa,EAAE,gCAAgC,CAAC;IACjE,YAAY,EAAE,CAAC,WAAW,EAAE,gCAAgC,CAAC;CACrD,CAAC;AAEX,KAAK,UAAU,QAAQ;IACrB,MAAM,IAAI,GAAG,IAAI,GAAG,EAA0C,CAAC;IAC/D,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC;QAC1D,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE;YACb,IAAI,EAAE,MAAM,QAAQ,CAClB,IAAI,GAAG,CAAC,YAAY,IAAI,EAAE,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,EAC5C,MAAM,CACP;YACD,IAAI;SACL,CAAC,CAAC;IACL,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,IAAI,CACX,QAAwB,EACxB,MAAc,EACd,IAAY,EACZ,IAAI,GAAG,2BAA2B;IAElC,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE;QACzB,cAAc,EAAE,IAAI;QACpB,eAAe,EAAE,UAAU;QAC3B,wBAAwB,EAAE,SAAS;QACnC,yBAAyB,EACvB,0IAA0I;KAC7I,CAAC,CAAC;IACH,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC;AAED,wFAAwF;AACxF,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAyB,EACzB,MAAM,GAAG,CAAC;IAEV,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,MAAM,IAAI,GAAG,MAAM,QAAQ,EAAE,CAAC;IAC9B,MAAM,MAAM,GAAG,KAAK,EAAE,OAAwB,EAAE,QAAwB,EAAE,EAAE;QAC1E,qEAAqE;QACrE,IACE,OAAO,CAAC,OAAO,CAAC,IAAI,KAAK,aAAa,IAAI,EAAE;YAC5C,OAAO,CAAC,OAAO,CAAC,IAAI,KAAK,aAAa,IAAI,EAAE;YAE5C,OAAO,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC;QAC1C,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK;YAC1B,OAAO,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,oBAAoB,CAAC,CAAC;QACnD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,EAAE,kBAAkB,CAAC,CAAC;QAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACpC,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3D,IAAI,GAAG,CAAC,QAAQ,KAAK,WAAW;YAC9B,OAAO,IAAI,CACT,QAAQ,EACR,GAAG,EACH,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC,EACnC,kBAAkB,CACnB,CAAC;QACJ,MAAM,EAAE,GAAG,wBAAwB,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC5D,IAAI,EAAE,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC;QAC9D,MAAM,KAAK,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC;QACnD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,aAAa,CAAC,CAAC;QACpE,IAAI,IAAa,CAAC;QAClB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,EAAE,kBAAkB,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACtE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,iEAAiE;YACjE,OAAO,KAAK,YAAY,eAAe;gBACrC,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,WAAW,CAAC;gBAClC,CAAC,CAAC,IAAI,CACF,QAAQ,EACR,GAAG,EACH,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACvD,CAAC;QACR,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,kBAAkB,CAAC,CAAC;IACvE,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE;QAChD,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE,CACjD,IAAI,CACF,QAAQ,EACR,GAAG,EACH,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACvD,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC1C,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7B,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;IACH,IAAI,GAAI,MAAM,CAAC,OAAO,EAAkB,CAAC,IAAI,CAAC;IAC9C,OAAO;QACL,GAAG,EAAE,oBAAoB,IAAI,GAAG;QAChC,MAAM;QACN,KAAK,EAAE,GAAG,EAAE,CACV,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACpC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YAC7D,MAAM,CAAC,mBAAmB,EAAE,CAAC;QAC/B,CAAC,CAAC;KACL,CAAC;AACJ,CAAC"}

package/dist/static/dashboard.js

@@ -0,0 +1,268 @@
+// @ts-check
+/**
+ * The dashboard: the run list every 2 seconds, and the selected run as
+ * `follow.js` follows it. Text only, never HTML.
+ */
+import { follower } from "./follow.js";
+import { cost, duration, timeline } from "./timeline.js";
+
+/** @typedef {import("@clemrig/flow").RunEvent} RunEvent */
+/** @typedef {import("./timeline.js").Block} Block */
+
+/**
+ * @typedef {object} Summary
+ * @property {string} id
+ * @property {string} [workflow]
+ * @property {string} [status]
+ * @property {string} [stage]
+ * @property {number | null} [durationMs]
+ * @property {number | null} [costUsd]
+ * @property {boolean} [partial]
+ * @property {string} [updatedAt]
+ * @property {string} [error] Why the run cannot be read.
+ */
+
+/**
+ * @typedef {object} Detail
+ * @property {Required<Omit<Summary, "error">>} run
+ * @property {Record<string, string>} runtimes
+ * @property {string | null} error
+ * @property {RunEvent[]} events
+ * @property {number} next
+ * @property {import("@clemrig/flow").Correction[]} corrections
+ * @property {string[]} result
+ */
+
+const LIST_EVERY_MS = 2000;
+const DETAIL_EVERY_MS = 1000;
+
+/**
+ * @param {string} id
+ * @returns {HTMLElement}
+ */
+function byId(id) {
+  const found = document.getElementById(id);
+  if (!found) throw new Error(`Missing element #${id}`);
+  return found;
+}
+
+/**
+ * @param {string} tag
+ * @param {string} [text]
+ * @param {string} [className]
+ * @returns {HTMLElement}
+ */
+function el(tag, text, className) {
+  const node = document.createElement(tag);
+  if (text !== undefined) node.textContent = text;
+  if (className) node.className = className;
+  return node;
+}
+
+/** @param {string} iso */
+function time(iso) {
+  const date = new Date(iso);
+  return Number.isNaN(date.getTime())
+    ? iso
+    : date.toLocaleString(undefined, {
+        dateStyle: "short",
+        timeStyle: "medium",
+      });
+}
+
+/** @param {import("@clemrig/flow").TokenCounts} tokens */
+function tokenLine(tokens) {
+  return `${tokens.input} input · ${tokens.output} output · ${tokens.cacheRead} cache read · ${tokens.cacheWrite} cache write tokens`;
+}
+
+/**
+ * @param {string} path
+ * @returns {Promise<any>}
+ */
+async function load(path) {
+  const response = await fetch(path, { cache: "no-store" });
+  if (!response.ok)
+    throw Object.assign(
+      new Error((await response.text()) || `HTTP ${response.status}`),
+      { status: response.status },
+    );
+  return response.json();
+}
+
+/** The run the address names, or none when it cannot be read. */
+function fromHash() {
+  try {
+    return decodeURIComponent(location.hash.slice(1));
+  } catch {
+    return "";
+  }
+}
+
+let selected = fromHash();
+
+/** @param {Summary[]} runs */
+function showRuns(runs) {
+  byId("none").hidden = runs.length > 0;
+  byId("runs").replaceChildren(
+    ...runs.map((run) => {
+      const row = el("tr");
+      row.title = run.id;
+      if (run.id === selected) row.className = "selected";
+      if (run.error !== undefined) {
+        const cause = el("td", run.error);
+        cause.setAttribute("colspan", "4");
+        row.append(el("td", run.id), el("td", "unreadable", "failed"), cause);
+      } else
+        row.append(
+          el("td", run.workflow),
+          el("td", run.status, run.status),
+          el("td", run.stage),
+          el("td", duration(run.durationMs ?? null)),
+          el("td", cost(run.costUsd ?? null, run.partial ?? false)),
+          el("td", time(run.updatedAt ?? "")),
+        );
+      row.addEventListener("click", () => select(run.id));
+      return row;
+    }),
+  );
+}
+
+/** @param {Block} block */
+function showBlock(block) {
+  const item = el("li", undefined, "block");
+  const head = el("p");
+  head.append(
+    `${block.kind} ${block.stage} · `,
+    el("span", block.status, block.status),
+    block.durationMs === null ? "" : ` · ${duration(block.durationMs)}`,
+  );
+  item.append(head);
+  const line = (/** @type {string} */ text, className = "line") =>
+    item.append(el("p", text, className));
+  const { call } = block;
+  if (call?.model)
+    line(`${call.runtime} ${call.model} · session ${call.session}`);
+  for (const tool of block.tools)
+    line(
+      tool.status === "running"
+        ? `${tool.name} …`
+        : `${tool.name}${tool.status === "failed" ? " failed" : ""} ${((tool.durationMs ?? 0) / 1000).toFixed(1)} s`,
+    );
+  if (call?.usage)
+    line(
+      `${call.scope === "session" ? "Session total" : "Call"}: ${tokenLine(call.usage)} · ${cost(call.usage.costUsd, false)}`,
+    );
+  else if (block.tokens)
+    line(
+      `So far: ${tokenLine(block.tokens)}${block.provisional ? " (provisional)" : ""}`,
+    );
+  for (const warning of block.warnings) line(warning, "line warning");
+  for (const entry of block.journal) line(`${time(entry.at)} ${entry.message}`);
+  if (block.decision) {
+    const { verdict, reason, destination } = block.decision;
+    const retry = block.retry
+      ? ` [${block.retry.key} ${block.retry.count}/${block.retry.max}]`
+      : "";
+    line(`${verdict} — ${reason} → ${destination ?? "end"}${retry}`);
+  }
+  if (block.detail) line(block.detail, "line failed");
+  return item;
+}
+
+/**
+ * @param {Detail} detail
+ * @param {RunEvent[]} events Every event received for the run.
+ */
+function showDetail(detail, events) {
+  const { run } = detail;
+  const summary = el("section");
+  const line = el("p", undefined, "empty");
+  line.append(
+    el("span", run.status, run.status),
+    ` · ${run.stage} · ${duration(run.durationMs)} · ${cost(run.costUsd, run.partial)}`,
+  );
+  summary.append(el("h3", `${run.workflow} · ${run.id}`), line);
+  for (const runtime of Object.values(detail.runtimes))
+    summary.append(el("p", runtime, "line"));
+  if (detail.error) summary.append(el("pre", detail.error, "failed"));
+  const stages = el("section");
+  const blocks = el("ol");
+  blocks.append(...timeline(events).map(showBlock));
+  stages.append(el("h2", "Timeline"), blocks);
+  const sections = [summary, stages];
+  if (detail.corrections.length) {
+    const corrections = el("section");
+    corrections.append(el("h2", "Corrections"));
+    for (const { key, count, max } of detail.corrections)
+      corrections.append(el("p", `${key} ${count}/${max ?? "?"}`, "line"));
+    sections.push(corrections);
+  }
+  const result = el("section");
+  result.append(el("h2", "Result"), el("pre", detail.result.join("\n")));
+  sections.push(result);
+  byId("detail").replaceChildren(...sections);
+}
+
+/** @param {string} message */
+function updated(message) {
+  byId("updated").textContent = message;
+}
+
+async function refreshRuns() {
+  try {
+    const { title, label, runs } = await load("/api/runs");
+    byId("title").textContent = title;
+    document.title = title;
+    byId("label").textContent = label;
+    showRuns(runs);
+    updated(`Updated ${new Date().toLocaleTimeString()}`);
+  } catch (error) {
+    unavailable(error);
+  }
+  setTimeout(refreshRuns, LIST_EVERY_MS);
+}
+
+/** @param {unknown} error */
+const unavailable = (error) =>
+  updated(
+    `Unavailable: ${error instanceof Error ? error.message : String(error)}`,
+  );
+
+/** @param {string} text */
+const placeholder = (text) =>
+  byId("detail").replaceChildren(el("p", text, "empty"));
+
+const follow = follower({
+  load,
+  schedule: (work) => setTimeout(work, DETAIL_EVERY_MS),
+  cancel: (timer) => clearTimeout(timer),
+  show: (detail, events) => showDetail(detail, events),
+  fail: (error) => {
+    const { status } = /** @type {{ status?: number }} */ (error);
+    // The follower stops on a run that does not exist and retries the rest.
+    if (status === 404) placeholder("This run does not exist.");
+    else if (status)
+      placeholder(
+        `This run cannot be read: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    else unavailable(error);
+  },
+});
+
+/** @param {string} id */
+function select(id) {
+  if (id === selected) return;
+  selected = id;
+  if (fromHash() !== id) location.hash = encodeURIComponent(id);
+  placeholder(id ? "Loading…" : "Select a run.");
+  for (const row of byId("runs").children)
+    row.className =
+      /** @type {HTMLElement} */ (row).title === id ? "selected" : "";
+  follow.select(id);
+}
+
+// A link or the history can change the selected run without reloading the page.
+window.addEventListener("hashchange", () => select(fromHash()));
+refreshRuns();
+if (selected) placeholder("Loading…");
+follow.select(selected);

package/dist/static/follow.js

@@ -0,0 +1,67 @@
+// @ts-check
+/**
+ * Follows the selected run: asks only for the events not received yet, one
+ * request after the answer to the previous one, drops an answer for a selection
+ * that has changed since, and stops once the run has ended or does not exist.
+ * Requests and timers are given, so that this logic is tested without a browser.
+ */
+
+/** @typedef {import("@clemrig/flow").RunEvent} RunEvent */
+
+/**
+ * @typedef {object} Answer
+ * @property {{ status: string }} run
+ * @property {RunEvent[]} events Events from the index the request asked for.
+ * @property {number} next The index to ask for next.
+ */
+
+/**
+ * @template Timer
+ * @param {object} options
+ * @param {(path: string) => Promise<any>} options.load Rejects with `status` set on an HTTP error.
+ * @param {(work: () => void) => Timer} options.schedule Runs `work` after the polling interval.
+ * @param {(timer: Timer | undefined) => void} options.cancel
+ * @param {(answer: any, events: RunEvent[]) => void} options.show The latest answer and every event received.
+ * @param {(error: unknown) => void} options.fail
+ */
+export function follower({ load, schedule, cancel, show, fail }) {
+  /** One selection: a new object each time, so that an old answer never matches. */
+  let current = { id: "", events: /** @type {RunEvent[]} */ ([]), next: 0 };
+  /** @type {Timer | undefined} */
+  let timer;
+
+  /** @param {typeof current} target */
+  async function refresh(target) {
+    if (!target.id) return;
+    /** @type {Answer} */
+    let answer;
+    try {
+      answer = await load(
+        `/api/runs/${encodeURIComponent(target.id)}?after=${target.next}`,
+      );
+    } catch (error) {
+      if (target !== current) return;
+      fail(error);
+      // A run that does not exist will not appear later.
+      const status = /** @type {{ status?: number }} */ (error).status;
+      if (status !== 404) timer = schedule(() => refresh(target));
+      return;
+    }
+    if (target !== current) return;
+    target.events.push(...answer.events);
+    target.next = answer.next;
+    show(answer, target.events);
+    if (answer.run.status === "running")
+      timer = schedule(() => refresh(target));
+  }
+
+  return {
+    /** @param {string} id */
+    select(id) {
+      if (id === current.id) return;
+      cancel(timer);
+      current = { id, events: [], next: 0 };
+      refresh(current);
+    },
+  };
+}

package/dist/static/index.html

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>runs</title>
+<link rel="stylesheet" href="/style.css">
+<script type="module" src="/dashboard.js"></script>
+</head>
+<body>
+<header><h1 id="title">runs</h1><span id="label"></span><span id="updated"></span></header>
+<main>
+<div>
+<div class="table"><table><thead><tr><th>Workflow</th><th>Status</th><th>Stage</th><th>Duration</th><th>Cost</th><th>Updated</th></tr></thead><tbody id="runs"></tbody></table></div>
+<p id="none" class="empty" hidden>No run yet.</p>
+</div>
+<div id="detail"><p class="empty">Select a run.</p></div>
+</main>
+</body>
+</html>

package/dist/static/style.css

@@ -0,0 +1,166 @@
+:root {
+  color-scheme: light dark;
+  --bg: #f7f7f5;
+  --panel: #fff;
+  --fg: #1d1d1b;
+  --muted: #6f6e69;
+  --line: #e4e3df;
+  --accent: #2557d6;
+  --ok: #19773a;
+  --bad: #b42318;
+  --run: #a15c07;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #111110;
+    --panel: #1b1b19;
+    --fg: #e8e7e3;
+    --muted: #9b9a94;
+    --line: #2c2c29;
+    --accent: #7aa2ff;
+    --ok: #5bd28a;
+    --bad: #ff7a6b;
+    --run: #f2b14c;
+  }
+}
+* {
+  box-sizing: border-box;
+}
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--fg);
+  font:
+    14px / 1.45 ui-sans-serif,
+    system-ui,
+    -apple-system,
+    sans-serif;
+}
+header {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px 12px;
+  align-items: baseline;
+  padding: 12px 16px;
+  border-bottom: 1px solid var(--line);
+}
+header h1 {
+  margin: 0;
+  font-size: 16px;
+}
+header span {
+  color: var(--muted);
+  font-size: 13px;
+}
+#updated {
+  margin-left: auto;
+}
+main {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1.4fr);
+  gap: 16px;
+  padding: 16px;
+}
+@media (max-width: 900px) {
+  main {
+    grid-template-columns: minmax(0, 1fr);
+  }
+}
+.table {
+  overflow-x: auto;
+  background: var(--panel);
+  border: 1px solid var(--line);
+  border-radius: 6px;
+}
+table {
+  width: 100%;
+  border-collapse: collapse;
+}
+th,
+td {
+  padding: 7px 10px;
+  border-bottom: 1px solid var(--line);
+  text-align: left;
+  white-space: nowrap;
+}
+th {
+  color: var(--muted);
+  font-size: 12px;
+  font-weight: 500;
+}
+tbody tr {
+  cursor: pointer;
+}
+tbody tr:hover,
+tbody tr.selected {
+  background: color-mix(in srgb, var(--accent) 12%, transparent);
+}
+.completed,
+.passed {
+  color: var(--ok);
+}
+.failed {
+  color: var(--bad);
+}
+.running {
+  color: var(--run);
+}
+section {
+  margin-bottom: 12px;
+  padding: 10px 12px;
+  background: var(--panel);
+  border: 1px solid var(--line);
+  border-radius: 6px;
+}
+h2 {
+  margin: 0 0 8px;
+  color: var(--muted);
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+h3 {
+  margin: 0 0 4px;
+  font-size: 14px;
+  overflow-wrap: anywhere;
+}
+ol {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.block {
+  padding: 6px 0;
+  border-bottom: 1px dotted var(--line);
+}
+.block:last-child {
+  border-bottom: 0;
+}
+.block > p {
+  margin: 0;
+}
+.line,
+pre {
+  font:
+    12px / 1.45 ui-monospace,
+    SFMono-Regular,
+    Menlo,
+    monospace;
+  overflow-wrap: anywhere;
+}
+.line {
+  margin: 2px 0 0 16px;
+  color: var(--muted);
+}
+.warning {
+  color: var(--run);
+}
+pre {
+  margin: 0;
+  white-space: pre-wrap;
+}
+.empty {
+  margin: 0;
+  color: var(--muted);
+}

package/dist/static/timeline.js

@@ -0,0 +1,180 @@
+// @ts-check
+/**
+ * The dashboard's pure logic: a run's events grouped into one block per stage
+ * execution, and the formats of durations and costs. Served as is to the browser.
+ */
+
+/** @typedef {import("@clemrig/flow").RunEvent} RunEvent */
+/** @typedef {import("@clemrig/flow").AgentActivity} AgentActivity */
+/** @typedef {import("@clemrig/flow").TokenCounts} TokenCounts */
+/** @typedef {import("@clemrig/flow").AgentUsage} AgentUsage */
+
+/**
+ * @typedef {object} Call
+ * @property {string} [runtime]
+ * @property {string} [model]
+ * @property {string} [session]
+ * @property {"running" | "completed" | "failed"} status
+ * @property {AgentUsage} [usage] As the runtime announced it at the end of the call.
+ * @property {"call" | "session"} [scope] Whether `usage` is the call's own or its session's total.
+ */
+
+/**
+ * @typedef {object} Tool
+ * @property {string} id
+ * @property {string} name
+ * @property {"running" | "completed" | "failed"} status
+ * @property {number} [durationMs]
+ */
+
+/**
+ * @typedef {object} Block
+ * @property {string} stage
+ * @property {string} kind
+ * @property {"running" | "passed" | "failed" | "completed"} status
+ * @property {string} startedAt
+ * @property {number | null} durationMs
+ * @property {{ verdict: string; reason: string; destination: string | null }} [decision]
+ * @property {{ key: string; count: number; max: number }} [retry]
+ * @property {string} [detail]
+ * @property {Call} [call]
+ * @property {Tool[]} tools
+ * @property {TokenCounts | null} tokens The call's responses so far.
+ * @property {boolean} provisional Whether `tokens` includes figures replaced at the end of the call.
+ * @property {string[]} warnings
+ * @property {{ at: string; message: string }[]} journal
+ */
+
+/**
+ * @param {string} stage
+ * @param {string} kind
+ * @param {string} at
+ * @returns {Block}
+ */
+const block = (stage, kind, at) => ({
+  stage,
+  kind,
+  status: "running",
+  startedAt: at,
+  durationMs: null,
+  tools: [],
+  tokens: null,
+  provisional: false,
+  warnings: [],
+  journal: [],
+});
+
+/**
+ * @param {Block} target
+ * @param {AgentActivity} activity
+ */
+function apply(target, activity) {
+  switch (activity.kind) {
+    case "call":
+      if (activity.status === "started") {
+        const { runtime, model, session } = activity;
+        target.call = { runtime, model, session, status: "running" };
+      } else
+        target.call = {
+          ...target.call,
+          runtime: activity.runtime,
+          status: activity.status,
+          usage: activity.usage,
+          scope: activity.scope,
+        };
+      break;
+    case "tool": {
+      const tool = target.tools.find(({ id }) => id === activity.id);
+      const update =
+        activity.status === "started"
+          ? { id: activity.id, name: activity.name, status: "running" }
+          : {
+              id: activity.id,
+              name: activity.name,
+              status: activity.status,
+              durationMs: activity.durationMs,
+            };
+      if (tool) Object.assign(tool, update);
+      else target.tools.push(/** @type {Tool} */ (update));
+      break;
+    }
+    case "response": {
+      const sum = target.tokens ?? {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+      };
+      for (const field of /** @type {const} */ ([
+        "input",
+        "output",
+        "cacheRead",
+        "cacheWrite",
+      ]))
+        sum[field] += activity.tokens[field];
+      target.tokens = sum;
+      target.provisional ||= activity.provisional;
+      break;
+    }
+    case "warning":
+      target.warnings.push(activity.message);
+  }
+}
+
+/**
+ * One block per stage execution, in order: a stage's journal, agent activity
+ * and decision go to its latest block.
+ * @param {RunEvent[]} events
+ * @returns {Block[]}
+ */
+export function timeline(events) {
+  /** @type {Block[]} */
+  const blocks = [];
+  const latest = (/** @type {string} */ stage) =>
+    blocks.findLast((candidate) => candidate.stage === stage);
+  for (const event of events) {
+    if (event.type === "stage" && event.status === "started") {
+      blocks.push(block(event.stage, event.kind, event.at));
+      continue;
+    }
+    let target = latest(event.stage);
+    if (!target || (event.type === "stage" && target.status !== "running")) {
+      // A stage reported without a start, such as one failed by an interruption.
+      target = block(event.stage, event.kind, event.at);
+      blocks.push(target);
+    }
+    if (event.type === "stage") {
+      target.status = event.status === "started" ? "running" : event.status;
+      target.durationMs = Date.parse(event.at) - Date.parse(target.startedAt);
+      if (event.decision) target.decision = event.decision;
+      if (event.retry) target.retry = event.retry;
+      if (event.detail) target.detail = event.detail;
+    } else if (event.type === "log")
+      target.journal.push({ at: event.at, message: event.message });
+    else apply(target, event.activity);
+  }
+  return blocks;
+}
+
+/**
+ * @param {number | null} ms
+ * @returns {string}
+ */
+export function duration(ms) {
+  if (ms === null) return "—";
+  const seconds = Math.floor(ms / 1000);
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+  return `${hours ? `${hours} h ` : ""}${minutes} min ${seconds % 60} s`;
+}
+
+/**
+ * An estimated cost as the runtimes announced it; unknown without any measure.
+ * @param {number | null} usd
+ * @param {boolean} partial Some agent call announced no usage.
+ * @returns {string}
+ */
+export function cost(usd, partial) {
+  const value = usd === null ? "—" : `${usd.toFixed(4)} USD`;
+  return partial ? `${value} (partial)` : value;
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@clemrig/flow-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "A local read-only dashboard of the runs of @clemrig/flow workflows",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clementchesneau/clemrig-factory-v2.git",
+    "directory": "packages/flow-ui"
+  },
+  "type": "module",
+  "bin": {
+    "flow-ui": "dist/main.js"
+  },
+  "exports": {
+    ".": {
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && node -e \"require('node:fs').cpSync('src/static','dist/static',{recursive:true})\"",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.ui.json",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@clemrig/flow": "0.2.0"
+  }
+}