@netnodeag/kraftwerk 0.61.0 → 0.63.0

package/dist/inspector/api/workspace.js

@@ -0,0 +1,117 @@
+import path from "node:path";
+import { publicUrlFor, resolveProject } from "../../config.js";
+import { disposeAllBackends } from "../chat/sessions.js";
+import { cloudStatus } from "../cloud.js";
+import { getProjectRoot } from "../context.js";
+import { discoverWorkspaces, forgetWorkspace, listWorkspacesDetailed, startWorkspace, stopWorkspace, tildify } from "../instances.js";
+import { searchAgents } from "../search.js";
+import { getSettings, saveSettings } from "../settings.js";
+import { canSelfUpdate, startUpdate, updateStatus } from "../update.js";
+import { getDiskVersion, getPkgName, getPkgVersion, RESTART_EXIT_CODE, supervised } from "../version.js";
+import { disposeAllDevs } from "../vibeables.js";
+import { fail, reply, route } from "./router.js";
+/** The workspace itself: identity and features, settings, the other workspaces, updates. */
+export const workspaceRoutes = [
+    // ?probe=1 marks a discovery probe from another instance: answer identity
+    // only, skip our own discovery (two instances must not probe each other
+    // recursively).
+    route({ name: "meta.get", method: "GET", path: "/api/meta", summary: "version, workspace identity, enabled features, the switcher" }, async (c) => {
+        const project = await resolveProject(getProjectRoot()).catch(() => null);
+        const projectName = project?.config.name ?? (project ? path.basename(project.root) : "");
+        const manual = project?.config.switcher ?? [];
+        const discovered = c.query.get("probe") === "1" ? [] : await discoverWorkspaces();
+        // Manual switcher entries keep their configured name/icon; discovered
+        // workspaces that duplicate one (same url, running) only contribute
+        // the live flag. Stopped workspaces never collide — they carry a root,
+        // and a manual entry pointing at the same port is just a link.
+        const norm = (u) => u.replace(/\/+$/, "").replace("127.0.0.1", "localhost").toLowerCase();
+        const manualUrls = new Set(manual.map((e) => norm(e.url)));
+        const liveUrls = new Set(discovered.filter((d) => d.live).map((d) => norm(d.url)));
+        const switcher = [
+            ...manual.map((e) => (liveUrls.has(norm(e.url)) ? { ...e, live: true } : e)),
+            ...discovered.filter((d) => !(d.live && manualUrls.has(norm(d.url)))),
+        ];
+        return {
+            version: await getPkgVersion(),
+            // A differing disk version means an upgrade landed while this process
+            // runs — the UI offers a relaunch when a supervisor can respawn us.
+            diskVersion: await getDiskVersion(),
+            restartable: supervised(),
+            projectName,
+            projectIcon: project?.config.icon ?? "",
+            projectColor: project?.config.color ?? "",
+            projectNamed: !!project?.config.name,
+            projectRoot: project?.root ?? getProjectRoot(),
+            projectRootLabel: tildify(project?.root ?? getProjectRoot()),
+            git: (project?.config.git && project.config.git.enabled !== false) === true,
+            repos: (project?.config.repos && project.config.repos.enabled !== false) === true,
+            vibeables: (project?.config.vibeables && project.config.vibeables.enabled !== false) === true,
+            projects: (project?.config.projects && project.config.projects.enabled !== false) === true,
+            publicUrl: (project && publicUrlFor(project)) ?? "",
+            cloud: cloudStatus(),
+            switcher,
+        };
+    }),
+    route({ name: "settings.get", method: "GET", path: "/api/settings", summary: "kraftwerk.yml, parsed, with resolved paths" }, async () => getSettings()),
+    route({ name: "settings.save", method: "PUT", path: "/api/settings", summary: "write the UI-editable subset of kraftwerk.yml", errors: 400 }, async (c) => saveSettings(await c.body())),
+    route({ name: "workspaces.list", method: "GET", path: "/api/workspaces", summary: "every known workspace incl. this one, with state and counts" }, async () => listWorkspacesDetailed()),
+    // Launches `kraftwerk ui` for a known workspace as a detached process (the switcher's Start button).
+    route({ name: "workspaces.start", method: "POST", path: "/api/workspaces/start", summary: "start a known workspace {root}", errors: 400 }, async (c) => {
+        const { root } = await c.body();
+        if (!root)
+            fail(400, "root required");
+        const result = await startWorkspace(root);
+        return reply(result.ok ? 200 : 409, result);
+    }),
+    route({ name: "workspaces.stop", method: "POST", path: "/api/workspaces/stop", summary: "stop a running workspace's server {root | url}", errors: 400 }, async (c) => {
+        const target = await c.body();
+        if (!target.root && !target.url)
+            fail(400, "root or url required");
+        const result = await stopWorkspace(target);
+        return reply(result.ok ? 200 : 409, result);
+    }),
+    route({ name: "workspaces.forget", method: "POST", path: "/api/workspaces/forget", summary: "drop a workspace from the registry {root}", errors: 400 }, async (c) => {
+        const { root } = await c.body();
+        if (!root)
+            fail(400, "root required");
+        return { ok: await forgetWorkspace(root) };
+    }),
+    route({ name: "search.agents", method: "GET", path: "/api/search/agents", summary: "active agents and channels of every reachable workspace (⌘K)" }, async () => searchAgents()),
+    route({ name: "update.check", method: "GET", path: "/api/update-check", summary: "the latest version on the npm registry" }, async () => {
+        const name = await getPkgName();
+        const current = await getDiskVersion();
+        try {
+            const r = await fetch(`https://registry.npmjs.org/${name}/latest`, { signal: AbortSignal.timeout(5_000) });
+            if (!r.ok)
+                throw new Error(String(r.status));
+            const latest = (await r.json()).version ?? "";
+            return { name, current, latest };
+        }
+        catch {
+            return reply(502, { name, current, latest: "", error: "npm registry unreachable" });
+        }
+    }),
+    route({ name: "update.status", method: "GET", path: "/api/update", summary: "state and log of the self-update, and whether one can run here" }, async () => {
+        const name = await getPkgName();
+        const can = canSelfUpdate(name);
+        return { ...updateStatus(), name, available: can.ok, reason: can.ok ? undefined : can.reason, restartable: supervised() };
+    }),
+    // Runs `npm i -g <name>@<version>`; 409 when refused or already running.
+    route({ name: "update.start", method: "POST", path: "/api/update", summary: "self-update to {version?} (default latest)", errors: 409 }, async (c) => {
+        const name = await getPkgName();
+        const body = await c.body();
+        const version = typeof body.version === "string" && body.version ? body.version : "latest";
+        return reply(202, { ...startUpdate(name, version), name });
+    }),
+    // Exits with the respawn code; the `kraftwerk ui` supervisor relaunches.
+    route({ name: "server.restart", method: "POST", path: "/api/restart", summary: "relaunch the server (needs the `kraftwerk ui` supervisor)" }, async () => {
+        if (!supervised())
+            fail(400, "not supervised — restart `kraftwerk ui` manually");
+        setTimeout(() => {
+            disposeAllBackends();
+            disposeAllDevs();
+            process.exit(RESTART_EXIT_CODE);
+        }, 150);
+        return { ok: true };
+    }),
+];

package/dist/inspector/chat/sessions.js

@@ -1,6 +1,8 @@
 import { randomUUID } from "node:crypto";
 import { promises as fs } from "node:fs";
 import { getOutputDir, getProjectRoot } from "../context.js";
+import { perWorkspace } from "../workspace.js";
+import { touch } from "../live.js";
 import { knowledgeIndex } from "../knowledge.js";
 import { getRun, listRuns, safeRunDir } from "../runs.js";
 import { listSkills, readSkill } from "../skills.js";
@@ -19,7 +21,8 @@ import { JOURNAL_FILE, journalExcerpt, readJournal } from "../journal.js";
 import { filesSummary } from "../files.js";
 import { appendEvent, attachmentPath, copyChatFiles, listChatMetas, newChatId, readEvents, readMeta, readMetaAt, safeChatDir, writeMeta, } from "./store.js";
 const MAIN = "main";
-const states = new Map();
+/** Chats with a loaded state, by id — one table per workspace. */
+const chatStates = perWorkspace(() => new Map());
 const newSeat = (key, harness) => ({
     key,
     harness,
@@ -130,21 +133,25 @@ function dropBackend(state) {
 const IDLE_BACKEND_MS = 15 * 60_000;
 const reaper = setInterval(() => {
     const cutoff = Date.now() - IDLE_BACKEND_MS;
-    for (const state of states.values()) {
-        const live = [...state.seats.values()].some((s) => s.backend);
-        if (live && !isBusy(state) && Date.parse(state.meta.updatedAt) < cutoff) {
-            dropBackend(state);
-        }
+    for (const [ws, states] of chatStates.entries()) {
+        ws.run(() => {
+            for (const state of chatStates().values()) {
+                const live = [...state.seats.values()].some((s) => s.backend);
+                if (live && !isBusy(state) && Date.parse(state.meta.updatedAt) < cutoff) {
+                    dropBackend(state);
+                }
+            }
+        });
     }
 }, 60_000);
 reaper.unref?.();
 /** Server shutdown: no agent subprocess may outlive the inspector. */
 export function disposeAllBackends() {
-    for (const state of states.values())
-        dropBackend(state);
+    for (const [ws, states] of chatStates.entries())
+        ws.run(() => states.forEach((state) => dropBackend(state)));
 }
 async function loadState(id) {
-    const existing = states.get(id);
+    const existing = chatStates().get(id);
     if (existing)
         return existing;
     const meta = await readMeta(id);
@@ -162,7 +169,7 @@ async function loadState(id) {
         writeChain: Promise.resolve(),
     };
     // Two racing loads: keep whichever registered first.
-    const registered = states.get(id) ?? (states.set(id, state), state);
+    const registered = chatStates().get(id) ?? (chatStates().set(id, state), state);
     if (registered === state)
         closeInterruptedWork(state);
     return registered;
@@ -241,8 +248,13 @@ function emit(state, ev, from) {
         .catch(() => { });
     for (const fn of state.subscribers)
         fn(stored);
+    // What a list shows about a chat (busy, waiting for you) changed: live watches re-evaluate.
+    if (STATUS_EVENTS.has(ev.type))
+        touch();
     return stored;
 }
+/** Events that change a chat's state as lists show it — not the streamed text in between. */
+const STATUS_EVENTS = new Set(["user_message", "turn_start", "turn_end", "error", "failure", "permission_request", "permission_resolved", "elicitation_request", "elicitation_resolved", "files_changed"]);
 /* ---------- skills ---------- */
 /**
  * Skills visible to a chat: every discovered skill (workspace skills root
@@ -858,7 +870,7 @@ export async function createChat(opts) {
         updatedAt: now,
     };
     await writeMeta(meta);
-    states.set(meta.id, {
+    chatStates().set(meta.id, {
         meta,
         events: [],
         subscribers: new Set(),
@@ -873,12 +885,12 @@ export async function createChat(opts) {
 }
 /** A permission request is waiting for a human in this chat (live state only — a restart drops it with the backend). */
 export function chatAwaitingApproval(id) {
-    return (states.get(id)?.pendingInfo.size ?? 0) > 0;
+    return (chatStates().get(id)?.pendingInfo.size ?? 0) > 0;
 }
 /** Every request waiting for a human, across the chats in memory. */
 export function waitingRequests() {
     const out = [];
-    for (const state of states.values()) {
+    for (const state of chatStates().values()) {
         for (const [requestId, info] of state.pendingInfo) {
             out.push({ requestId, ...info, meta: state.meta, seat: state.pendingSeat.get(requestId) ?? MAIN });
         }
@@ -894,7 +906,7 @@ export function waitingRequests() {
 export function agentActivity() {
     const out = new Map();
     const of = (slug) => out.get(slug) ?? out.set(slug, { working: [], waiting: [] }).get(slug);
-    for (const state of states.values()) {
+    for (const state of chatStates().values()) {
         const { meta } = state;
         for (const seat of state.seats.values()) {
             const slug = meta.scope.kind === "agent" ? meta.scope.slug : meta.scope.kind === "channel" ? seat.key : undefined;
@@ -912,8 +924,8 @@ export function agentActivity() {
 export async function listChats() {
     const metas = await listChatMetas();
     return metas.map((m) => ({
-        ...(states.get(m.id)?.meta ?? m),
-        busy: states.has(m.id) ? isBusy(states.get(m.id)) : false,
+        ...(chatStates().get(m.id)?.meta ?? m),
+        busy: chatStates().has(m.id) ? isBusy(chatStates().get(m.id)) : false,
         awaitingApproval: chatAwaitingApproval(m.id),
     }));
 }
@@ -1130,7 +1142,7 @@ export async function ensureChannelChat(channel) {
     const metas = await listChatMetas();
     const existing = metas.find((m) => m.scope.kind === "channel" && m.scope.slug === channel.slug);
     if (existing)
-        return states.get(existing.id)?.meta ?? existing;
+        return chatStates().get(existing.id)?.meta ?? existing;
     const meta = await createChat({ agent: "claude", scope: { kind: "channel", slug: channel.slug }, title: channel.name });
     if (channel.project) {
         meta.project = channel.project;
@@ -1191,7 +1203,7 @@ export async function convertChatToChannel(chatId, channel) {
 }
 /** Members left the channel: their processes go, the transcript stays. */
 export async function dropChannelSeats(chatId, keep) {
-    const state = states.get(chatId);
+    const state = chatStates().get(chatId);
     if (!state)
         return;
     for (const [key, seat] of state.seats) {
@@ -1423,7 +1435,7 @@ export async function deleteChat(id) {
     for (const resolve of state.pendingElicitations.values())
         resolve({ action: "cancel" });
     dropBackend(state);
-    states.delete(id);
+    chatStates().delete(id);
     await moveToTrash("chats", id, safeChatDir(id));
     return {};
 }

package/dist/inspector/context.d.ts

@@ -1,10 +1,8 @@
-export declare function setOutputDir(dir: string): void;
-export declare function setProjectRoot(dir: string): void;
-/** Absolute output directory (runs/ + chats/ live inside). */
-export declare function getOutputDir(): string;
 /**
- * The consumer project root. Set explicitly at startup; falls back to the
- * parent of the output dir (wrong for nested output dirs like
- * kraftwerk-data/output — always pass projectRoot when known).
+ * Shorthands for the current workspace's paths (see workspace.ts for how
+ * the current workspace is chosen).
  */
+/** Absolute output directory (runs/ + chats/ live inside). */
+export declare function getOutputDir(): string;
+/** The workspace root: where kraftwerk.yml lives. */
 export declare function getProjectRoot(): string;

package/dist/inspector/context.js

@@ -1,27 +1,13 @@
-import path from "node:path";
+import { currentWorkspace } from "./workspace.js";
 /**
- * Server-side context for the inspector: which consumer project it looks at.
- * Set once by startInspector() before any request is served.
+ * Shorthands for the current workspace's paths (see workspace.ts for how
+ * the current workspace is chosen).
  */
-let outputDir = "";
-let projectRoot = "";
-export function setOutputDir(dir) {
-    outputDir = path.resolve(dir);
-}
-export function setProjectRoot(dir) {
-    projectRoot = path.resolve(dir);
-}
 /** Absolute output directory (runs/ + chats/ live inside). */
 export function getOutputDir() {
-    if (!outputDir)
-        throw new Error("inspector context not initialized");
-    return outputDir;
+    return currentWorkspace().outputDir;
 }
-/**
- * The consumer project root. Set explicitly at startup; falls back to the
- * parent of the output dir (wrong for nested output dirs like
- * kraftwerk-data/output — always pass projectRoot when known).
- */
+/** The workspace root: where kraftwerk.yml lives. */
 export function getProjectRoot() {
-    return projectRoot || path.dirname(getOutputDir());
+    return currentWorkspace().root;
 }

package/dist/inspector/git.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { projectsRootFor, reposRootFor, resolveProject, vibeablesRootFor, isSafeGitName } from "../config.js";
 import { ENV_FILE } from "../runner/docker.js";
 import { getOutputDir, getProjectRoot } from "./context.js";
+import { perWorkspace } from "./workspace.js";
 /**
  * Workspace git sync. Several people run kraftwerk against one git repo, so
  * knowledge, agents, skills, channels and workflows travel between them like
@@ -325,13 +326,26 @@ export function parseStatus(out) {
     }
     return files;
 }
-let statusCache = null;
-/** Bumped by touched(); a status computed under an older value is stale. */
-let generation = 0;
+/**
+ * The workspace's sync state: the status cache, the queue of repo-mutating
+ * commands, the last fetch/pull/error, and the background timer.
+ */
+const gitState = perWorkspace(() => ({
+    statusCache: null,
+    /** Bumped by touched(); a status computed under an older value is stale. */
+    generation: 0,
+    chain: Promise.resolve(),
+    lastFetch: undefined,
+    lastPull: undefined,
+    lastError: undefined,
+    timer: null,
+    ticking: false,
+    lastRun: 0,
+}));
 /** Invalidate the status cache after anything that changes the repo. */
 const touched = () => {
-    statusCache = null;
-    generation++;
+    gitState().statusCache = null;
+    gitState().generation++;
 };
 /**
  * One repo-mutating git command at a time. The background sync and the
@@ -341,24 +355,21 @@ const touched = () => {
  * fetch, pull and push queue behind each other. Status stays outside the
  * queue (GIT_OPTIONAL_LOCKS=0 keeps it lock-free).
  */
-let chain = Promise.resolve();
 function serial(fn) {
-    const run = chain.then(fn, fn);
-    chain = run.catch(() => { });
+    const run = gitState().chain.then(fn, fn);
+    gitState().chain = run.catch(() => { });
     return run;
 }
-let lastFetch;
-let lastPull;
-let lastError;
 /**
  * Everything the git screen renders. Each call shells out to git a handful
  * of times, and the nav badge polls it from every open tab, so results are
  * cached for a beat.
  */
 export async function gitStatus(fresh = false) {
-    if (!fresh && statusCache && Date.now() - statusCache.at < CACHE_MS)
-        return statusCache.value;
-    const gen = generation;
+    const cached = gitState().statusCache;
+    if (!fresh && cached && Date.now() - cached.at < CACHE_MS)
+        return cached.value;
+    const gen = gitState().generation;
     const opened = await openRepo();
     if (opened.off)
         return { enabled: false };
@@ -393,17 +404,17 @@ export async function gitStatus(fresh = false) {
         diverged: !!ahead && !!behind,
         autosync: repo.cfg.autosync,
         interval: repo.cfg.interval,
-        lastFetch,
-        lastPull,
-        lastError,
+        lastFetch: gitState().lastFetch,
+        lastPull: gitState().lastPull,
+        lastError: gitState().lastError,
     };
     // A failed status (a stale index.lock, a timeout on a huge untracked tree)
     // must not read as "workspace clean": with no file list the commit endpoint
     // refuses everything, and the message should say why.
     if (!status.ok) {
         const value = { ...base, error: `git status failed: ${status.stderr || "unknown error"}` };
-        if (gen === generation)
-            statusCache = { at: Date.now(), value };
+        if (gen === gitState().generation)
+            gitState().statusCache = { at: Date.now(), value };
         return value;
     }
     const scope = scopeFor(repo);
@@ -428,8 +439,8 @@ export async function gitStatus(fresh = false) {
     // A commit that finished while this status was running already emptied
     // the cache; caching the pre-commit list on top of that would show the
     // committed file as dirty for another CACHE_MS.
-    if (gen === generation)
-        statusCache = { at: Date.now(), value };
+    if (gen === gitState().generation)
+        gitState().statusCache = { at: Date.now(), value };
     return value;
 }
 /**
@@ -556,11 +567,11 @@ async function fetchNow() {
     // put "fetched 5s ago" next to ahead/behind counts that stopped moving
     // hours ago, which is the one thing this line exists to rule out.
     if (!r.ok) {
-        lastError = r.stderr || "fetch failed";
-        return { ok: false, error: lastError };
+        gitState().lastError = r.stderr || "fetch failed";
+        return { ok: false, error: gitState().lastError };
     }
-    lastFetch = new Date().toISOString();
-    lastError = undefined;
+    gitState().lastFetch = new Date().toISOString();
+    gitState().lastError = undefined;
     return { ok: true };
 }
 /** Fast-forward only. A diverged branch is the user's problem, not ours. */
@@ -584,13 +595,13 @@ async function pullNow() {
         // git's own non-fast-forward output is a wall of hints. Say the one
         // thing that matters and leave the resolution to a terminal.
         const notFf = /non-fast-forward|diverg|cannot be fast-forwarded/i.test(r.stderr);
-        lastError = notFf
+        gitState().lastError = notFf
             ? "The branch has diverged from its upstream. Merge or rebase it in a terminal."
             : r.stderr || "pull failed";
-        return { ok: false, error: lastError };
+        return { ok: false, error: gitState().lastError };
     }
-    lastPull = new Date().toISOString();
-    lastError = undefined;
+    gitState().lastPull = new Date().toISOString();
+    gitState().lastError = undefined;
     return { ok: true };
 }
 export function gitPush() {
@@ -610,10 +621,10 @@ async function pushNow() {
         : await gitNet(netArgs(["push", "--set-upstream"], cfg.remote, `HEAD:${head.branch}`), repoRoot);
     touched();
     if (!r.ok) {
-        lastError = r.stderr || "push failed";
-        return { ok: false, error: lastError };
+        gitState().lastError = r.stderr || "push failed";
+        return { ok: false, error: gitState().lastError };
     }
-    lastError = undefined;
+    gitState().lastError = undefined;
     return { ok: true };
 }
 /* ---------- background sync ---------- */
@@ -624,9 +635,6 @@ async function pushNow() {
  * next restart.
  */
 const RECHECK_MS = 60_000;
-let timer = null;
-let ticking = false;
-let lastRun = 0;
 /**
  * Fetch on an interval, and fast-forward when `autosync: pull` is set. Never
  * commits. A pull is skipped while the tree is dirty, so nobody's unsaved
@@ -635,34 +643,35 @@ let lastRun = 0;
  * out) before the next one starts, or a short interval piles up processes.
  */
 export function startGitSync() {
-    if (timer || ticking)
+    if (gitState().timer || gitState().ticking)
         return;
     schedule(0);
 }
 function schedule(ms) {
-    timer = setTimeout(() => void tick(), ms);
+    const timer = setTimeout(() => void tick(), ms);
     timer.unref?.();
+    gitState().timer = timer;
 }
 async function tick() {
-    timer = null;
-    ticking = true;
+    gitState().timer = null;
+    gitState().ticking = true;
     let next = RECHECK_MS;
     try {
         const { repo } = await openRepo();
         if (repo && repo.cfg.interval > 0) {
             const every = repo.cfg.interval * 1000;
-            if (Date.now() - lastRun >= every - 500) {
-                lastRun = Date.now();
+            if (Date.now() - gitState().lastRun >= every - 500) {
+                gitState().lastRun = Date.now();
                 await sync(repo);
             }
-            next = Math.min(RECHECK_MS, Math.max(1_000, lastRun + every - Date.now()));
+            next = Math.min(RECHECK_MS, Math.max(1_000, gitState().lastRun + every - Date.now()));
         }
     }
     catch {
         // A failed tick is retried at the next one; the status carries lastError.
     }
     finally {
-        ticking = false;
+        gitState().ticking = false;
         schedule(next);
     }
 }

package/dist/inspector/live.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Live data for watching clients: a watch is a route result some client
+ * keeps on screen (the rail's agents, the bell's notifications). The server
+ * evaluates each distinct watch once — however many clients share it — and
+ * pushes it only when it changed:
+ *
+ * - right after any change made through the API (`touch()` from the router),
+ * - when a chat's state changes (turn start/end, a question, an answer),
+ * - and on the watch's interval, for changes nobody announces (an agent
+ *   writing files, a run progressing on disk).
+ *
+ * Evaluation runs in the watch's workspace. This module knows nothing about
+ * routes: the socket hands it an `evaluate` closure.
+ */
+interface Watcher {
+    interval: number;
+    push(data: unknown): void;
+}
+interface Watch {
+    evaluate(): Promise<{
+        ok: boolean;
+        data: unknown;
+    }>;
+    watchers: Set<Watcher>;
+    /** The last pushed JSON, to push changes only. */
+    last?: string;
+    timer?: ReturnType<typeof setTimeout>;
+    /** The evaluation in flight, and the one waiting behind it. */
+    running?: Promise<void>;
+    queued?: {
+        promise: Promise<void>;
+        forced: Set<Watcher>;
+    };
+}
+/**
+ * Keep `push` fed with the result of `evaluate` (shared by `key`): now, on
+ * every change, and at least every `interval` ms. Returns the unwatch.
+ */
+export declare function watch(key: string, evaluate: Watch["evaluate"], interval: number, push: (data: unknown) => void): () => void;
+/** Something changed: re-evaluate every watch of this workspace soon (debounced). */
+export declare function touch(): void;
+export {};

package/dist/inspector/live.js

@@ -0,0 +1,91 @@
+import { perWorkspace } from "./workspace.js";
+const MIN_INTERVAL = 1000;
+const TOUCH_DEBOUNCE_MS = 60;
+const state = perWorkspace(() => ({ watches: new Map(), touchTimer: undefined }));
+/**
+ * Evaluate after whatever evaluation is in flight (it may predate the
+ * change that asked for this one). Requests that arrive while one waits
+ * share it. Changed data goes to every watcher; `force` watchers (just
+ * joined) get it even unchanged.
+ */
+function run(w, force) {
+    if (w.queued) {
+        if (force)
+            w.queued.forced.add(force);
+        return w.queued.promise;
+    }
+    const forced = new Set(force ? [force] : []);
+    const promise = (w.running ?? Promise.resolve()).then(async () => {
+        w.queued = undefined;
+        try {
+            const r = await w.evaluate();
+            // A failed evaluation keeps the last good value on every client.
+            if (!r.ok)
+                return;
+            const json = JSON.stringify(r.data) ?? "null";
+            const changed = json !== w.last;
+            w.last = json;
+            for (const x of w.watchers)
+                if (changed || forced.has(x))
+                    x.push(r.data);
+        }
+        catch { }
+    });
+    w.queued = { promise, forced };
+    w.running = promise;
+    return promise;
+}
+function schedule(w) {
+    clearTimeout(w.timer);
+    if (!w.watchers.size)
+        return;
+    const every = Math.max(MIN_INTERVAL, Math.min(...[...w.watchers].map((x) => x.interval)));
+    w.timer = setTimeout(() => void run(w, undefined).finally(() => schedule(w)), every);
+    w.timer.unref?.();
+}
+/**
+ * Keep `push` fed with the result of `evaluate` (shared by `key`): now, on
+ * every change, and at least every `interval` ms. Returns the unwatch.
+ */
+export function watch(key, evaluate, interval, push) {
+    const { watches } = state();
+    let w = watches.get(key);
+    if (!w) {
+        w = { evaluate, watchers: new Set() };
+        watches.set(key, w);
+    }
+    const watcher = { interval, push };
+    w.watchers.add(watcher);
+    // A new watcher gets the current value at once, changed or not.
+    void run(w, watcher).finally(() => schedule(w));
+    const current = w;
+    return () => {
+        current.watchers.delete(watcher);
+        if (!current.watchers.size) {
+            clearTimeout(current.timer);
+            if (watches.get(key) === current)
+                watches.delete(key);
+        }
+        else
+            schedule(current);
+    };
+}
+/** Something changed: re-evaluate every watch of this workspace soon (debounced). */
+export function touch() {
+    // Outside any workspace (a unit test, a CLI command) nobody can be watching.
+    let s;
+    try {
+        s = state();
+    }
+    catch {
+        return;
+    }
+    if (!s.watches.size || s.touchTimer)
+        return;
+    s.touchTimer = setTimeout(() => {
+        s.touchTimer = undefined;
+        for (const w of s.watches.values())
+            void run(w, undefined).finally(() => schedule(w));
+    }, TOUCH_DEBOUNCE_MS);
+    s.touchTimer.unref?.();
+}