@netnodeag/kraftwerk 0.65.0 → 0.66.0

package/dist/server/api/hub.js

@@ -0,0 +1,32 @@
+import * as z from "zod";
+import { tildify } from "../../core/instances.js";
+import { currentHub } from "../hub-context.js";
+import { fail, route } from "./router.js";
+const Root = z.object({ root: z.string().min(1, "root is required") });
+/** What a hub serves (server.ts Hub): the machine's open workspaces, and opening or closing one. Need no workspace. */
+export const hubRoutes = [
+    // The folder is this machine's business; a paired device sees names and addresses.
+    route({ name: "hub.list", method: "GET", path: "/api/hub", summary: "the workspaces this kraftwerk serves: slug, name, address" }, async (c) => {
+        const hub = currentHub();
+        return {
+            daemon: hub.daemon,
+            port: hub.port,
+            workspaces: hub.list().map((o) => ({
+                slug: o.slug,
+                name: o.name,
+                url: o.url,
+                ...(o.aliasPort ? { aliasPort: o.aliasPort } : {}),
+                ...(c.trust.kind === "local" ? { root: o.root, rootLabel: tildify(o.root) } : {}),
+            })),
+        };
+    }),
+    route({ name: "hub.open", method: "POST", path: "/api/hub/open", summary: "serve a workspace {root} next to the others", access: "local", body: Root, errors: 400 }, async (c) => {
+        const { root } = await c.body();
+        const o = await currentHub().open(root);
+        return { slug: o.slug, name: o.name, url: o.url, ...(o.aliasPort ? { aliasPort: o.aliasPort } : {}) };
+    }),
+    route({ name: "hub.close", method: "POST", path: "/api/hub/close", summary: "stop serving a workspace {root}; the others keep running", access: "local", body: Root }, async (c) => {
+        const { root } = await c.body();
+        return (await currentHub().close(root)) ? { ok: true } : fail(404, "not open here");
+    }),
+];

package/dist/server/api/index.d.ts

@@ -337,7 +337,29 @@ export declare const routes: (Route<"agents.addJournal", {
 }>, "/api/git/pull", undefined> | Route<"git.push", import("./router.js").Reply<{
     ok: boolean;
     error?: string;
-}>, "/api/git/push", undefined> | Route<"git.status", import("../../core/git.js").GitStatus, "/api/git", undefined> | Route<"knowledge.concept", import("../../okf.js").ConceptDetail, "/api/knowledge/:bundle/concept", undefined> | Route<"knowledge.create", import("../../okf.js").BundleInfo, "/api/knowledge", z.ZodObject<{
+}>, "/api/git/push", undefined> | Route<"git.status", import("../../core/git.js").GitStatus, "/api/git", undefined> | Route<"hub.close", {
+    ok: boolean;
+}, "/api/hub/close", z.ZodObject<{
+    root: z.ZodString;
+}, z.core.$strip>> | Route<"hub.list", {
+    daemon: boolean;
+    port: number;
+    workspaces: {
+        slug: string;
+        name: string;
+        url: string;
+        aliasPort?: number | undefined;
+        root?: string | undefined;
+        rootLabel?: string | undefined;
+    }[];
+}, "/api/hub", undefined> | Route<"hub.open", {
+    slug: string;
+    name: string;
+    url: string;
+    aliasPort?: number | undefined;
+}, "/api/hub/open", z.ZodObject<{
+    root: z.ZodString;
+}, z.core.$strip>> | Route<"knowledge.concept", import("../../okf.js").ConceptDetail, "/api/knowledge/:bundle/concept", undefined> | Route<"knowledge.create", import("../../okf.js").BundleInfo, "/api/knowledge", z.ZodObject<{
     name: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>> | Route<"knowledge.delete", {
     ok: boolean;
@@ -348,6 +370,7 @@ export declare const routes: (Route<"agents.addJournal", {
     id: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>> | Route<"meta.get", {
     workspaceName: string;
+    workspaceSlug: string;
     workspaceIcon: string;
     workspaceColor: string;
     workspaceNamed: boolean;

package/dist/server/api/index.js

@@ -4,6 +4,7 @@ import { attentionRoutes } from "./attention.js";
 import { channelRoutes } from "./channels.js";
 import { chatRoutes } from "./chats.js";
 import { deviceRoutes } from "./devices.js";
+import { hubRoutes } from "./hub.js";
 import { fileRoutes } from "./files.js";
 import { gitRoutes } from "./git.js";
 import { knowledgeRoutes } from "./knowledge.js";
@@ -34,6 +35,7 @@ const domainRoutes = [
     ...gitRoutes,
     ...vibeableRoutes,
     ...deviceRoutes,
+    ...hubRoutes,
 ];
 const protocolRoute = route({ name: "protocol.get", method: "GET", path: "/api/protocol", summary: "the protocol version and every route", access: "public" }, async () => ({
     version: PROTOCOL_VERSION,

package/dist/server/api/socket.d.ts

@@ -1,4 +1,5 @@
 import type { Workspace } from "../../core/workspace.js";
+import type { Hub } from "../server.js";
 import type { Trust } from "../trust.js";
 import type { Socket } from "../ws.js";
 /**
@@ -6,4 +7,11 @@ import type { Socket } from "../ws.js";
  * been revoked since it connected): a device whose answer is no longer
  * `device` is disconnected at once (close code 4401).
  */
-export declare function serveSocket(conn: Socket, workspace: Workspace, version: string, trust: Trust, recheck: () => Promise<Trust>): void;
+/**
+ * `workspaceOf` finds the workspace a message is for: its `ws` (a slug), or
+ * the connection's own (the one the socket was opened for) when it names
+ * none. A daemon's socket opened at its root has no workspace of its own:
+ * there, a message without `ws` reaches only the machine's routes (hub,
+ * devices, protocol).
+ */
+export declare function serveSocket(conn: Socket, workspaceOf: (slug?: string) => Workspace | undefined, version: string, trust: Trust, recheck: () => Promise<Trust>, hub: Hub): void;

package/dist/server/api/socket.js

@@ -1,6 +1,7 @@
 import { subscribeChat } from "../../core/chat/sessions.js";
 import { watch } from "../live.js";
 import { resolveVibeable, subscribeVibeable } from "../../core/vibeables.js";
+import { MACHINE_ROUTES, runInHub } from "../hub-context.js";
 import { apiRouter, PROTOCOL_VERSION, routes } from "./index.js";
 /**
  * The control plane over one WebSocket (`/api/ws`): every JSON route by
@@ -30,7 +31,14 @@ const RECHECK_MS = 5_000;
  * been revoked since it connected): a device whose answer is no longer
  * `device` is disconnected at once (close code 4401).
  */
-export function serveSocket(conn, workspace, version, trust, recheck) {
+/**
+ * `workspaceOf` finds the workspace a message is for: its `ws` (a slug), or
+ * the connection's own (the one the socket was opened for) when it names
+ * none. A daemon's socket opened at its root has no workspace of its own:
+ * there, a message without `ws` reaches only the machine's routes (hub,
+ * devices, protocol).
+ */
+export function serveSocket(conn, workspaceOf, version, trust, recheck, hub) {
     const trustKey = trust.kind === "device" ? `device:${trust.device.id}` : trust.kind;
     const stops = new Map();
     const send = (msg) => conn.send(JSON.stringify(msg));
@@ -72,6 +80,8 @@ export function serveSocket(conn, workspace, version, trust, recheck) {
             return unsubscribe();
         stops.set(key, unsubscribe);
     }
+    /** A refusal answered the way the message expects one (its id, watch or sub key). */
+    const refuse = (msg, status, error) => send({ id: msg.id, ...(typeof msg.watch === "string" ? { watch: msg.watch } : {}), ...(typeof msg.sub === "string" ? { sub: msg.sub } : {}), status, data: { error }, error });
     async function handle(msg) {
         if (typeof msg.call === "string") {
             const r = await apiRouter.invoke(msg.call, objectOf(msg.input), trust);
@@ -129,17 +139,27 @@ export function serveSocket(conn, workspace, version, trust, recheck) {
             return send({ error: "invalid JSON" });
         }
         // Every message runs in the connection's workspace, whatever started the read; a revoked device's message runs nowhere.
-        void workspace
-            .run(async () => {
+        const slug = typeof msg.ws === "string" ? msg.ws : undefined;
+        const ws = workspaceOf(slug);
+        if (msg.ws !== undefined && !ws)
+            return refuse(msg, 404, `no workspace "${String(msg.ws)}" here`);
+        if (!ws && !(typeof msg.call === "string" && MACHINE_ROUTES.test(msg.call)))
+            return refuse(msg, 404, "name a workspace: `ws` on the message");
+        const run = (fn) => runInHub(hub, () => (ws ? ws.run(fn) : fn()));
+        void run(async () => {
             if (await stillPaired())
                 await handle(msg);
-        })
-            .catch((err) => send({ id: msg.id, error: err.message }));
+        }).catch((err) => send({ id: msg.id, error: err.message }));
     });
     conn.onClose(() => {
         clearInterval(watchdog);
-        for (const fn of stops.values())
-            fn();
+        // A subscription of a workspace that closed meanwhile has nothing left to let go of.
+        for (const fn of stops.values()) {
+            try {
+                fn();
+            }
+            catch { }
+        }
         stops.clear();
     });
     send({ hello: { protocol: PROTOCOL_VERSION, version } });

package/dist/server/api/workspace.d.ts

@@ -2,6 +2,7 @@ import * as z from "zod";
 /** The workspace itself: identity and features, settings, the other workspaces, updates. */
 export declare const workspaceRoutes: (import("./router.js").Route<"meta.get", {
     workspaceName: string;
+    workspaceSlug: string;
     workspaceIcon: string;
     workspaceColor: string;
     workspaceNamed: boolean;

package/dist/server/api/workspace.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import * as z from "zod";
-import { resolveWorkspace } from "../../config.js";
+import { resolveWorkspace, slugFromFolder, workspaceSlug } from "../../config.js";
 import { disposeAllBackends } from "../../core/chat/sessions.js";
 import { cloudStatus } from "../cloud.js";
 import { workspaceRoot } from "../../core/context.js";
@@ -56,6 +56,7 @@ export const workspaceRoutes = [
         ];
         const identity = {
             workspaceName: name,
+            workspaceSlug: ws ? workspaceSlug(ws) : slugFromFolder(path.basename(root)),
             workspaceIcon: ws?.config.icon ?? "",
             workspaceColor: ws?.config.color ?? "",
             workspaceNamed: !!ws?.config.name,

package/dist/server/cloud.d.ts

@@ -38,7 +38,7 @@ export declare const cloudStatus: () => CloudStatus;
  * registration attempt (success or not); the heartbeat loop runs on its
  * own afterwards.
  */
-export declare function startCloudSync(port: number, version: string): Promise<void>;
+export declare function startCloudSync(url: string, version: string): Promise<void>;
 /** Stop the heartbeat loop (server close, tests). */
 export declare function stopCloudSync(): void;
 /**
@@ -47,3 +47,7 @@ export declare function stopCloudSync(): void;
  * this, and a slow cloud must not hold the process.
  */
 export declare function cloudGoodbye(): Promise<void>;
+/** Every served workspace: stop its heartbeat (the server closes). */
+export declare function stopAllCloudSync(): void;
+/** Every served workspace says goodbye, in parallel (still bounded per workspace). */
+export declare function cloudGoodbyeAll(): Promise<void>;

package/dist/server/cloud.js

@@ -4,21 +4,26 @@ import os from "node:os";
 import path from "node:path";
 import { cloudFor, resolveWorkspace } from "../config.js";
 import { workspaceRoot } from "../core/context.js";
+import { perWorkspace, workspaceOpen } from "../core/workspace.js";
 import { listAgents, toSummary } from "../core/agents.js";
 import { listChannels, toChannelSummary } from "../core/channels.js";
 import { tildify } from "../core/instances.js";
 const claimUrlFor = (url, code) => (code ? `${url}/claim/${encodeURIComponent(code)}` : null);
 const REQUEST_TIMEOUT_MS = 8_000;
 const GOODBYE_TIMEOUT_MS = 800;
-let status = { url: "", state: "off" };
-let identity = null;
-let timer = null;
-let stopped = false;
-let lastRoster = "";
-let selfPort = 0;
-let selfVersion = "";
-const startedAt = new Date().toISOString();
-export const cloudStatus = () => status;
+/** The client's state, one per workspace: each served workspace registers and heartbeats on its own. */
+const client = perWorkspace(() => ({
+    status: { url: "", state: "off" },
+    identity: null,
+    timer: null,
+    stopped: false,
+    lastRoster: "",
+    /** Where this workspace is reached on this machine, as the cloud lists it. */
+    selfUrl: "",
+    selfVersion: "",
+    startedAt: new Date().toISOString(),
+}));
+export const cloudStatus = () => client().status;
 const cloudDir = () => path.join(os.homedir(), ".kraftwerk", "cloud");
 const identityFile = (url, root) => path.join(cloudDir(), `${createHash("sha1").update(`${url}\n${root}`).digest("hex").slice(0, 16)}.json`);
 async function readIdentity(file) {
@@ -46,9 +51,10 @@ async function roster() {
     return { agents, channels };
 }
 async function post(url, body, timeout = REQUEST_TIMEOUT_MS) {
+    const c = client();
     const r = await fetch(url, {
         method: "POST",
-        headers: { "content-type": "application/json", "user-agent": `kraftwerk/${selfVersion}` },
+        headers: { "content-type": "application/json", "user-agent": `kraftwerk/${c.selfVersion}` },
         body: JSON.stringify(body),
         signal: AbortSignal.timeout(timeout),
     });
@@ -66,16 +72,17 @@ async function post(url, body, timeout = REQUEST_TIMEOUT_MS) {
 }
 /** Register (or re-register) this instance. Returns false when the cloud refused or is unreachable. */
 async function register() {
+    const c = client();
     const project = await resolveWorkspace(workspaceRoot()).catch(() => null);
     const cloud = project ? cloudFor(project) : undefined;
     if (!project || !cloud)
         return false;
     const file = identityFile(cloud.url, project.root);
-    identity ??= await readIdentity(file);
+    c.identity ??= await readIdentity(file);
     const { agents, channels } = await roster();
-    lastRoster = JSON.stringify({ agents, channels });
+    c.lastRoster = JSON.stringify({ agents, channels });
     const body = {
-        ...(identity ?? {}),
+        ...(c.identity ?? {}),
         name: project.config.name ?? path.basename(project.root),
         icon: project.config.icon ?? "",
         color: project.config.color ?? "",
@@ -83,106 +90,121 @@ async function register() {
         rootLabel: tildify(project.root),
         hostname: os.hostname(),
         platform: `${process.platform}-${process.arch}`,
-        version: selfVersion,
-        url: `http://localhost:${selfPort}`,
+        version: c.selfVersion,
+        url: c.selfUrl,
         // Part of the cloud's register contract; always "" since the Cloudflare Tunnel was removed (0.65).
         publicUrl: "",
         agents,
         channels,
         interval: cloud.interval,
-        startedAt,
+        startedAt: c.startedAt,
         ...(cloud.token ? { accountToken: cloud.token } : {}),
     };
     try {
         const r = await post(`${cloud.url}/api/instances/register`, body);
-        if (!identity || identity.id !== r.id || identity.secret !== r.secret) {
-            identity = { id: r.id, secret: r.secret };
-            await writeIdentity(file, cloud.url, project.root, identity);
+        if (!c.identity || c.identity.id !== r.id || c.identity.secret !== r.secret) {
+            c.identity = { id: r.id, secret: r.secret };
+            await writeIdentity(file, cloud.url, project.root, c.identity);
         }
-        status = {
+        c.status = {
             url: cloud.url, state: "connected", id: r.id, account: r.account, interval: r.interval, lastSeen: new Date().toISOString(),
             claimCode: r.claimCode ?? null, claimUrl: claimUrlFor(cloud.url, r.claimCode),
         };
         return true;
     }
     catch (err) {
-        status = { url: cloud.url, state: "error", error: err.message, ...(identity ? { id: identity.id } : {}) };
+        c.status = { url: cloud.url, state: "error", error: err.message, ...(c.identity ? { id: c.identity.id } : {}) };
         return false;
     }
 }
 async function heartbeat() {
-    if (!identity || status.state === "off")
+    const c = client();
+    if (!c.identity || c.status.state === "off")
         return;
     const { agents, channels } = await roster();
     const rosterNow = JSON.stringify({ agents, channels });
     const body = {
-        ...identity,
-        version: selfVersion,
-        ...(rosterNow !== lastRoster ? { agents, channels } : {}),
+        ...c.identity,
+        version: c.selfVersion,
+        ...(rosterNow !== c.lastRoster ? { agents, channels } : {}),
     };
     try {
-        const r = await post(`${status.url}/api/instances/heartbeat`, body);
-        lastRoster = rosterNow;
-        status = {
-            ...status, state: "connected", error: undefined, interval: r.interval, lastSeen: new Date().toISOString(),
+        const r = await post(`${c.status.url}/api/instances/heartbeat`, body);
+        c.lastRoster = rosterNow;
+        c.status = {
+            ...c.status, state: "connected", error: undefined, interval: r.interval, lastSeen: new Date().toISOString(),
             ...(r.account !== undefined ? { account: r.account } : {}),
-            ...(r.claimCode !== undefined ? { claimCode: r.claimCode, claimUrl: claimUrlFor(status.url, r.claimCode) } : {}),
+            ...(r.claimCode !== undefined ? { claimCode: r.claimCode, claimUrl: claimUrlFor(c.status.url, r.claimCode) } : {}),
         };
     }
     catch (err) {
         const message = err.message;
-        status = { ...status, state: "error", error: message };
+        c.status = { ...c.status, state: "error", error: message };
         // An unknown identity (the cloud lost it) is fixed by registering again, which hands out a new one.
         if (/unknown instance|wrong instance secret|id and secret required/.test(message)) {
-            identity = null;
-            await register();
+            c.identity = null;
+            // Not after a goodbye: a stopped client registers nothing again.
+            if (!c.stopped && workspaceOpen())
+                await register();
         }
     }
 }
 /** Schedule the next tick after the effective interval; a failed cloud is retried at the same cadence. */
 function schedule() {
-    if (stopped)
+    const c = client();
+    if (c.stopped)
         return;
-    const seconds = status.interval && status.interval > 0 ? status.interval : 60;
-    timer = setTimeout(async () => {
-        if (status.state === "connected" || status.state === "error") {
-            if (identity)
+    const seconds = c.status.interval && c.status.interval > 0 ? c.status.interval : 60;
+    c.timer = setTimeout(async () => {
+        // Stopped (or the workspace closed) while this timer waited, or while the call below ran: no next round.
+        if (c.stopped || !workspaceOpen())
+            return;
+        if (c.status.state === "connected" || c.status.state === "error") {
+            if (c.identity)
                 await heartbeat();
             else
                 await register();
         }
-        schedule();
+        if (!c.stopped && workspaceOpen())
+            schedule();
     }, seconds * 1000);
-    timer.unref();
+    c.timer.unref();
 }
 /**
  * Start the client once the inspector listens. Resolves after the first
  * registration attempt (success or not); the heartbeat loop runs on its
  * own afterwards.
  */
-export async function startCloudSync(port, version) {
-    selfPort = port;
-    selfVersion = version;
-    stopped = false;
+export async function startCloudSync(url, version) {
+    const c = client();
+    c.selfUrl = url;
+    c.selfVersion = version;
+    c.stopped = false;
     const project = await resolveWorkspace(workspaceRoot()).catch(() => null);
     const cloud = project ? cloudFor(project) : undefined;
     if (!cloud) {
-        status = { url: "", state: "off" };
+        c.status = { url: "", state: "off" };
         return;
     }
-    status = { url: cloud.url, state: "connecting", interval: cloud.interval };
+    // The workspace may close (or the client stop) while this waits: then it does not register or schedule at all.
+    if (c.stopped || !workspaceOpen())
+        return;
+    c.status = { url: cloud.url, state: "connecting", interval: cloud.interval };
     await register();
+    if (c.stopped || !workspaceOpen())
+        return;
     // Until the cloud answers, retry at the configured cadence; once it does, at what it asked for.
-    if (status.state !== "connected")
-        status.interval = cloud.interval;
+    if (c.status.state !== "connected")
+        c.status.interval = cloud.interval;
     schedule();
 }
 /** Stop the heartbeat loop (server close, tests). */
 export function stopCloudSync() {
-    stopped = true;
-    if (timer)
-        clearTimeout(timer);
-    timer = null;
+    const c = client();
+    c.stopped = true;
+    if (c.timer)
+        clearTimeout(c.timer);
+    c.timer = null;
 }
 /**
  * Tell the cloud we are going away, so the record flips to "stopped" now
@@ -190,11 +212,21 @@ export function stopCloudSync() {
  * this, and a slow cloud must not hold the process.
  */
 export async function cloudGoodbye() {
+    const c = client();
     stopCloudSync();
-    if (!identity || status.state === "off" || !status.url)
+    if (!c.identity || c.status.state === "off" || !c.status.url)
         return;
     try {
-        await post(`${status.url}/api/instances/goodbye`, identity, GOODBYE_TIMEOUT_MS);
+        await post(`${c.status.url}/api/instances/goodbye`, c.identity, GOODBYE_TIMEOUT_MS);
     }
     catch { }
 }
+/** Every served workspace: stop its heartbeat (the server closes). */
+export function stopAllCloudSync() {
+    for (const [ws] of client.entries())
+        ws.run(stopCloudSync);
+}
+/** Every served workspace says goodbye, in parallel (still bounded per workspace). */
+export async function cloudGoodbyeAll() {
+    await Promise.all(client.entries().map(([ws]) => ws.run(cloudGoodbye)));
+}

package/dist/server/hub-context.d.ts

@@ -0,0 +1,7 @@
+import type { Hub } from "./server.js";
+export declare const runInHub: <T>(hub: Hub, fn: () => T) => T;
+export declare function currentHub(): Hub;
+/** API paths that need no workspace: the machine's own (the hub, devices and pairing, the protocol, the socket). */
+export declare const MACHINE_PATHS: RegExp;
+/** Route names callable over the socket without a workspace. */
+export declare const MACHINE_ROUTES: RegExp;

package/dist/server/hub-context.js

@@ -0,0 +1,18 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * The hub a request runs in, like the workspace (core/workspace.ts): the
+ * machine-level routes (hub.*) find theirs here, so several hubs in one
+ * process (tests) never act on each other's workspaces.
+ */
+const storage = new AsyncLocalStorage();
+export const runInHub = (hub, fn) => storage.run(hub, fn);
+export function currentHub() {
+    const hub = storage.getStore();
+    if (!hub)
+        throw new Error("no hub here");
+    return hub;
+}
+/** API paths that need no workspace: the machine's own (the hub, devices and pairing, the protocol, the socket). */
+export const MACHINE_PATHS = /^\/api\/(hub(\/|$)|pair$|devices(\/|$)|protocol$|ws$)/;
+/** Route names callable over the socket without a workspace. */
+export const MACHINE_ROUTES = /^(hub|devices|protocol)\./;

package/dist/server/live.d.ts

@@ -37,6 +37,8 @@ interface Watch {
  * 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;
+/** The current workspace closes: its watches stop re-evaluating (their sockets close with it). */
+export declare function closeWatches(): void;
 /** Something changed: re-evaluate every watch of this workspace soon (debounced). */
 export declare function touch(): void;
 export {};

package/dist/server/live.js

@@ -71,6 +71,15 @@ export function watch(key, evaluate, interval, push) {
             schedule(current);
     };
 }
+/** The current workspace closes: its watches stop re-evaluating (their sockets close with it). */
+export function closeWatches() {
+    const s = state();
+    for (const w of s.watches.values())
+        clearTimeout(w.timer);
+    s.watches.clear();
+    clearTimeout(s.touchTimer);
+    s.touchTimer = undefined;
+}
 /** 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.

package/dist/server/preview.js

@@ -108,7 +108,8 @@ export async function serveVibeable(req, res, url) {
     let st = await fs.stat(abs).catch(() => null);
     if (st?.isDirectory()) {
         if (!url.pathname.endsWith("/")) {
-            res.writeHead(302, { location: `${url.pathname}/${url.search}`, "cache-control": "no-store" });
+            // Relative, so it holds under a /w/<slug> prefix too.
+            res.writeHead(302, { location: `${url.pathname.split("/").pop()}/${url.search}`, "cache-control": "no-store" });
             return void res.end();
         }
         abs = path.join(abs, "index.html");

package/dist/server/server.d.ts

@@ -1,4 +1,5 @@
 import http from "node:http";
+import { Workspace } from "../core/workspace.js";
 import { RESTART_EXIT_CODE } from "./version.js";
 export { RESTART_EXIT_CODE };
 export interface InspectorOptions {
@@ -14,5 +15,55 @@ export interface InspectorOptions {
      */
     trustLoopback?: boolean;
 }
-/** Start the server; resolves once it listens. Runs until the process ends. */
+/** A workspace a hub serves. */
+export interface OpenWorkspace {
+    slug: string;
+    root: string;
+    name: string;
+    /** Where it is reached: <slug>.localhost:<port> under a daemon, localhost:<port> standalone. */
+    url: string;
+    /** Its own port too (kraftwerk.yml `port`), when the hub listens there for it — old links keep working. */
+    aliasPort?: number;
+    ws: Workspace;
+}
+/**
+ * One HTTP server serving workspaces by slug (see target.ts): a daemon
+ * (`kraftwerk daemon`) serves every workspace that is open on the machine,
+ * a standalone `kraftwerk ui` exactly one — its default, also reached
+ * without a slug, as before. Each open workspace runs in its own Workspace
+ * (core/workspace.ts) with its own .env, background jobs (routines, git
+ * sync, cloud), registry entry and live state; closing one ends all of that
+ * and leaves the others running.
+ */
+export interface Hub {
+    readonly server: http.Server;
+    /** The port it listens on. */
+    readonly port: number;
+    /** Whether it is the machine's daemon (workspaces addressed by slug, none by default). */
+    readonly daemon: boolean;
+    /** Serve a workspace (idempotent: an open one is returned as it is). */
+    open(root: string, opts?: {
+        outputDir?: string;
+    }): Promise<OpenWorkspace>;
+    /** Stop serving one; false when it was not open. */
+    close(root: string): Promise<boolean>;
+    list(): OpenWorkspace[];
+    /** Close every workspace and the server. */
+    stop(): Promise<void>;
+}
+export interface HubOptions {
+    port: number;
+    staticDir: string;
+    trustLoopback?: boolean;
+    /** The machine's daemon: workspaces get `hub` instance files, their own ports as aliases, and no default. */
+    daemon?: boolean;
+    /** After a workspace opened or closed (the daemon notes what to reopen after a restart). */
+    onChange?: (hub: Hub) => void | Promise<void>;
+}
+export declare function startHub(opts: HubOptions): Promise<Hub>;
+/**
+ * A standalone server for one workspace (`kraftwerk ui`, tests): a hub
+ * serving it as its default, reached with or without its slug. Resolves
+ * once it listens.
+ */
 export declare function startInspector(opts: InspectorOptions): Promise<http.Server>;