@netnodeag/kraftwerk 0.77.0 → 0.78.0

package/dist/server/api/chats.js

@@ -2,8 +2,9 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import * as z from "zod";
 import { getAgent } from "../../core/agents.js";
-import { answerElicitation, cancelChat, createChat, deleteChat, forkChat, getChat, listAgentSessionsFor, listChats, postMessage, renameChat, resetSession, resolvePermission, setChatConfig, setChatProject, setChatVibeable, steerChat, stopChatTask, subscribeChat, } from "../../core/chat/sessions.js";
-import { attachmentPath, saveAttachment } from "../../core/chat/store.js";
+import { answerElicitation, cancelChat, createChat, deleteChat, forkChat, getChat, listAgentSessionsFor, listChats, localPerson, postMessage, renameChat, resetSession, resolvePermission, setChatConfig, setChatProject, setChatVibeable, steerChat, stopChatTask, subscribeChat, } from "../../core/chat/sessions.js";
+import { attachmentPath, readMeta, saveAttachment } from "../../core/chat/store.js";
+import { remoteCaller } from "../trust.js";
 import { getProject } from "../../core/projects.js";
 import { MIME } from "./mime.js";
 import { projectErrors } from "./projects.js";
@@ -75,9 +76,39 @@ async function projectSlug(slug) {
         fail(404, "project not found");
     return found.slug;
 }
+/** Who a chat or message is signed with: a member session's member, else this machine's person. */
+const personOf = async (trust) => trust.kind === "member" ? { handle: trust.member.handle, email: trust.member.email } : localPerson();
+/**
+ * A private routine's run (meta.private) is not there for a remote caller
+ * (trust.ts remoteCaller): a 404, as if it did not exist. This machine and
+ * the LAN see it.
+ */
+async function hiddenFrom(trust, id) {
+    if (!remoteCaller(trust))
+        return;
+    const meta = await readMeta(id).catch(() => null);
+    if (meta?.private)
+        fail(404, "not found");
+}
+/** Every route on one chat (`:id`) checks hiddenFrom first. */
+function guarded(r) {
+    if (!r.path.includes("/:id"))
+        return r;
+    const handle = r.handle;
+    return {
+        ...r,
+        handle: async (c) => {
+            await hiddenFrom(c.trust, c.params.id);
+            return handle(c);
+        },
+    };
+}
 /** Chats: ACP sessions with a coding agent, their event stream, and what a person does in them. */
 export const chatRoutes = [
-    route({ name: "chats.list", method: "GET", path: "/api/chats", summary: "every chat with its live state" }, async () => ({ chats: await listChats() })),
+    route({ name: "chats.list", method: "GET", path: "/api/chats", summary: "every chat with its live state; a remote caller's list leaves private routines' runs out" }, async (c) => {
+        const chats = await listChats();
+        return { chats: remoteCaller(c.trust) ? chats.filter((x) => !x.private) : chats };
+    }),
     route({ name: "chats.create", method: "POST", path: "/api/chats", summary: "start a chat {agent, scope, resume?, project?}", body: NewChat }, async (c) => {
         // `resume` continues one of the agent's own sessions (see agents.sessions).
         const body = await c.body();
@@ -88,7 +119,13 @@ export const chatRoutes = [
             fail(400, "only an agent's chat takes a project");
         const project = body.project ? await projectSlug(body.project) : undefined;
         try {
-            return await createChat({ agent: agent, scope, ...(project ? { project } : {}), ...(body.resume ? { resume: body.resume } : {}) });
+            return await createChat({
+                agent: agent,
+                scope,
+                author: await personOf(c.trust),
+                ...(project ? { project } : {}),
+                ...(body.resume ? { resume: body.resume } : {}),
+            });
         }
         catch (err) {
             throw new ApiError(400, err.message);
@@ -146,7 +183,7 @@ export const chatRoutes = [
         const { slug } = await c.body();
         return metaOf(await setChatVibeable(c.params.id, slug || null));
     }),
-    route({ name: "chats.fork", method: "POST", path: "/api/chats/:id/fork", summary: "a new chat continuing a copy of this one's session", errors: 400 }, async (c) => metaOf(await forkChat(c.params.id))),
+    route({ name: "chats.fork", method: "POST", path: "/api/chats/:id/fork", summary: "a new chat continuing a copy of this one's session", errors: 400 }, async (c) => metaOf(await forkChat(c.params.id, await personOf(c.trust)))),
     route({ name: "chats.resetSession", method: "POST", path: "/api/chats/:id/reset-session", summary: "forget the agent's session; the next message starts fresh", errors: 400 }, async (c) => metaOf(await resetSession(c.params.id))),
     // The body is the file itself; x-file-name names it, content-type types it.
     route({ name: "chats.attach", method: "POST", path: "/api/chats/:id/attachments", summary: "upload an attachment for the next message", errors: 400, upload: true }, async (c) => {
@@ -178,8 +215,8 @@ export const chatRoutes = [
         res.end(data);
     }),
     // Channels: `from` is the poster's display name, which signs the message.
-    act("chats.message", "/api/chats/:id/message", "send a message {text, attachments?, from?}", Said.extend({ from: z.string().optional() }), (c, body) => postMessage(c.params.id, textOf(body), { from: body.from, attachments: body.attachments })),
-    act("chats.steer", "/api/chats/:id/steer", "add to the running turn {text, attachments?}", Said, (c, body) => steerChat(c.params.id, textOf(body), body.attachments)),
+    act("chats.message", "/api/chats/:id/message", "send a message {text, attachments?, from?}", Said.extend({ from: z.string().optional() }), async (c, body) => postMessage(c.params.id, textOf(body), { from: body.from, attachments: body.attachments, by: await personOf(c.trust) })),
+    act("chats.steer", "/api/chats/:id/steer", "add to the running turn {text, attachments?}", Said, async (c, body) => steerChat(c.params.id, textOf(body), body.attachments, await personOf(c.trust))),
     act("chats.permission", "/api/chats/:id/permission", "answer a permission request {requestId, optionId | null}", z.object({ requestId: z.string().default(""), optionId: z.string().nullable().default(null) }), (c, body) => resolvePermission(c.params.id, body.requestId, body.optionId)),
     // Channels: `agent` stops one member; without it every agent in the chat.
     act("chats.cancel", "/api/chats/:id/cancel", "stop the running turn {agent?}", z.object({ agent: z.string().optional() }), (c, body) => cancelChat(c.params.id, body.agent || undefined)),
@@ -190,4 +227,4 @@ export const chatRoutes = [
     }), (c, { requestId, action, content }) => answerElicitation(c.params.id, requestId, action === "accept" ? { action, content } : { action })),
     act("chats.stopTask", "/api/chats/:id/task-stop", "stop one background task {taskId}", z.object({ taskId: z.string().default("") }), (c, body) => stopChatTask(c.params.id, body.taskId)),
     act("chats.config", "/api/chats/:id/config", "set a session option {configId, value}", z.object({ configId: z.string().default(""), value: z.union([z.string(), z.boolean()]).default("") }), (c, body) => setChatConfig(c.params.id, body.configId, body.value)),
-];
+].map(guarded);

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

@@ -4,9 +4,23 @@ import * as z from "zod";
  * it on or off, a round now, releasing the claim. What `kraftwerk cloud`,
  * `login` and `logout` ask the running daemon; a standalone server answers
  * "off" (only the daemon registers). This machine only: the claim code
- * claims the machine.
+ * claims the machine. And an invite to one served workspace (`kraftwerk
+ * invite`): someone joins it as a remote member, without a clone.
  */
-export declare const cloudRoutes: (import("./router.js").Route<"cloud.set", {
+export declare const cloudRoutes: (import("./router.js").Route<"cloud.invite", import("../../core/cloud.js").InviteResponse & {
+    workspace: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+}, "/api/cloud/invite", z.ZodObject<{
+    slug: z.ZodOptional<z.ZodString>;
+    root: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodEnum<{
+        member: "member";
+        owner: "owner";
+    }>>;
+}, z.core.$strip>> | import("./router.js").Route<"cloud.set", {
     daemon: boolean;
     url: string;
     state: import("../cloud.js").CloudState;

package/dist/server/api/cloud.js

@@ -1,6 +1,6 @@
 import * as z from "zod";
 import { writeCloudFile } from "../../core/cloud.js";
-import { applyMachineCloud, cloudStatus, syncMachineCloud, unlinkMachineCloud } from "../cloud.js";
+import { applyMachineCloud, cloudStatus, createWorkspaceInvite, syncMachineCloud, unlinkMachineCloud } from "../cloud.js";
 import { currentHub } from "../hub-context.js";
 import { route } from "./router.js";
 /**
@@ -8,7 +8,8 @@ import { route } from "./router.js";
  * it on or off, a round now, releasing the claim. What `kraftwerk cloud`,
  * `login` and `logout` ask the running daemon; a standalone server answers
  * "off" (only the daemon registers). This machine only: the claim code
- * claims the machine.
+ * claims the machine. And an invite to one served workspace (`kraftwerk
+ * invite`): someone joins it as a remote member, without a clone.
  */
 export const cloudRoutes = [
     route({ name: "cloud.status", method: "GET", path: "/api/cloud", summary: "the machine's cloud record: state, claim code, account, last heartbeat", access: "local" }, async () => ({
@@ -31,6 +32,18 @@ export const cloudRoutes = [
         daemon: currentHub().daemon === true,
         ...(await syncMachineCloud()),
     })),
+    route({
+        name: "cloud.invite",
+        method: "POST",
+        path: "/api/cloud/invite",
+        summary: "an invite to a served workspace {slug | root, role?}: the cloud's join code and link (a claimed machine only)",
+        access: "local",
+        errors: 409,
+        body: z.object({ slug: z.string().optional(), root: z.string().optional(), role: z.enum(["owner", "member"]).optional() }).refine((b) => b.slug || b.root, "name the workspace: slug or root"),
+    }, async (c) => {
+        const { slug, root, role } = await c.body();
+        return createWorkspaceInvite({ slug, root }, role);
+    }),
     route({ name: "cloud.unlink", method: "POST", path: "/api/cloud/unlink", summary: "release the machine from its account; the cloud hands out a fresh claim code", access: "local", errors: 400 }, async () => ({
         daemon: currentHub().daemon === true,
         ...(await unlinkMachineCloud()),

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

@@ -29,8 +29,14 @@ export declare const deviceRoutes: (import("./router.js").Route<"devices.code",
 }, "/api/devices/relay", undefined> | import("./router.js").Route<"devices.revoke", {
     ok: boolean;
 }, "/api/devices/:id", undefined> | import("./router.js").Route<"devices.self", {
-    trust: "device" | "local" | "none";
+    trust: "device" | "local" | "member" | "none";
     device?: import("../../core/devices.js").Device | undefined;
+    relay?: boolean | undefined;
+    member?: import("../../core/cloud.js").MemberVerdict | undefined;
+    workspace?: {
+        id: string;
+        slug: string;
+    } | undefined;
 }, "/api/devices/self", undefined> | import("./router.js").Route<"devices.setPush", {
     ok: boolean;
 }, "/api/devices/push", z.ZodObject<{

package/dist/server/api/devices.js

@@ -44,9 +44,10 @@ export const deviceRoutes = [
             throw new ApiError(400, err.message);
         }
     }),
-    route({ name: "devices.self", method: "GET", path: "/api/devices/self", summary: "how this caller is trusted: this machine or a paired device" }, async (c) => ({
+    route({ name: "devices.self", method: "GET", path: "/api/devices/self", summary: "how this caller is trusted: this machine, a paired device, or a workspace's member" }, async (c) => ({
         trust: c.trust.kind,
-        ...(c.trust.kind === "device" ? { device: c.trust.device } : {}),
+        ...(c.trust.kind === "device" ? { device: c.trust.device, ...(c.trust.relay ? { relay: true } : {}) } : {}),
+        ...(c.trust.kind === "member" ? { member: c.trust.member, workspace: { id: c.trust.workspaceId, slug: c.trust.slug } } : {}),
     })),
     // A paired device's app says where its push notifications go (and the key it seals them with); see server/push.ts.
     route({

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

@@ -291,6 +291,19 @@ export declare const routes: (Route<"agents.addJournal", {
     ok: true;
 }, "/api/chats/:id/task-stop", z.ZodObject<{
     taskId: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>> | Route<"cloud.invite", import("../../core/cloud.js").InviteResponse & {
+    workspace: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+}, "/api/cloud/invite", z.ZodObject<{
+    slug: z.ZodOptional<z.ZodString>;
+    root: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodEnum<{
+        member: "member";
+        owner: "owner";
+    }>>;
 }, z.core.$strip>> | Route<"cloud.set", {
     daemon: boolean;
     url: string;
@@ -383,8 +396,14 @@ export declare const routes: (Route<"agents.addJournal", {
 }, "/api/devices/relay", undefined> | Route<"devices.revoke", {
     ok: boolean;
 }, "/api/devices/:id", undefined> | Route<"devices.self", {
-    trust: "device" | "local" | "none";
+    trust: "device" | "local" | "member" | "none";
     device?: import("../../core/devices.js").Device | undefined;
+    relay?: boolean | undefined;
+    member?: import("../../core/cloud.js").MemberVerdict | undefined;
+    workspace?: {
+        id: string;
+        slug: string;
+    } | undefined;
 }, "/api/devices/self", undefined> | Route<"devices.setPush", {
     ok: boolean;
 }, "/api/devices/push", z.ZodObject<{

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

@@ -59,8 +59,9 @@ export interface RouteDef<N extends string, P extends string = string, S extends
     body?: S;
     /**
      * Who may call it. Default: anyone trusted (this machine, a paired
-     * device). `public`: also unpaired callers (pairing, the protocol).
-     * `local`: this machine only (managing devices).
+     * device, a workspace's member — except the machine-level routes
+     * MEMBER_DENIED names). `public`: also unpaired callers (pairing, the
+     * protocol). `local`: this machine only (managing devices).
      */
     access?: "public" | "local";
 }

package/dist/server/api/router.js

@@ -39,12 +39,24 @@ function validate(route, raw) {
 }
 /** Maps an error message to a status by the usual wording: "no <thing>" is 404, "… are off" 409, else 400. */
 export const statusByMessage = (missing) => (message) => missing.test(message) ? 404 : /are off/.test(message) ? 409 : 400;
+/**
+ * What a member session (one workspace, over the relay; see members.ts) may
+ * not call: the machine's own business — its workspaces, devices, cloud
+ * record, settings, updates, restarts, identity, trash. server.ts already
+ * keeps the session inside its workspace; this keeps it out of the machine.
+ */
+const MEMBER_DENIED = /^(hub|devices|cloud|settings|server|update|workspaces|identity|trash)\./;
+/** …except asking who it is. */
+const MEMBER_ALLOWED = new Set(["devices.self"]);
 /** Why a caller may not use a route, or undefined when it may. */
 function refusal(route, trust) {
     if (route.access === "public")
         return undefined;
     if (trust.kind === "none")
         return new ApiError(401, "pair this device first", { error: "pair this device first", pair: true });
+    if (trust.kind === "member" && (route.access === "local" || (MEMBER_DENIED.test(route.name) && !MEMBER_ALLOWED.has(route.name)))) {
+        return new ApiError(403, `${route.name} is not open to a workspace member — only to the machine kraftwerk runs on`);
+    }
     if (route.access === "local" && trust.kind !== "local")
         return new ApiError(403, "only on the machine kraftwerk runs on");
     return undefined;

package/dist/server/cloud.d.ts

@@ -1,4 +1,4 @@
-import { type CloudUrlSource } from "../core/cloud.js";
+import { type Credentials, type CloudUrlSource, type InviteResponse } from "../core/cloud.js";
 /**
  * The machine client: the daemon registers THIS MACHINE with the kraftwerk
  * cloud once and heartbeats while it runs; the workspaces it serves ride
@@ -16,7 +16,12 @@ import { type CloudUrlSource } from "../core/cloud.js";
  *              along whenever it changed (opened, closed, vetoed, claimed).
  *              A claim made in the cloud arrives in the answer
  *   privacy    while unclaimed, entries carry name/slug/ws-id only — no
- *              roots; once claimed, roots too
+ *              roots; once claimed, roots too, and the routines that ran
+ *              here (`routines`, sent when it changed; private ones never)
+ *   members    the machine's credentials and the served workspaces are
+ *              what member sessions over the relay are verified with
+ *              (server/members.ts), and what `kraftwerk invite` asks the
+ *              cloud with (createWorkspaceInvite)
  *   recovery   a cloud that no longer knows the machine (data reset) gets a
  *              fresh registration; a cloud that is down is retried at the
  *              same cadence and never affects the UI
@@ -50,11 +55,14 @@ export interface CloudStatus {
     /** Workspaces reported (vetoed ones left out). */
     workspaces?: number;
 }
-/** What the daemon serves right now. */
+/** What the daemon serves right now; `ws` runs code inside that workspace (the routine report reads its state). */
 export type WorkspaceSource = () => Array<{
     root: string;
     slug: string;
     name: string;
+    ws?: {
+        run<T>(fn: () => T): T;
+    };
 }>;
 export declare const cloudStatus: () => CloudStatus;
 /**
@@ -83,3 +91,34 @@ export declare function unlinkMachineCloud(): Promise<CloudStatus>;
  * started (a hub stopping in a test leaves another's alone).
  */
 export declare function stopMachineCloud(owner?: unknown): Promise<void>;
+/**
+ * What member verification needs (server/members.ts): the cloud's origin,
+ * this machine's credentials. Null when no machine client runs (a
+ * standalone server, the cloud turned off).
+ */
+export declare function machineLink(): {
+    url: string;
+    creds: Credentials;
+    version: string;
+} | null;
+/** The served workspace whose kraftwerk.yml `id` is `id` (vetoed ones not), or null. */
+export declare function servedWorkspace(id: string): Promise<{
+    slug: string;
+    name: string;
+    root: string;
+} | null>;
+/**
+ * An invite to a served workspace (`kraftwerk invite`): the cloud's machine
+ * path, so only a claimed machine that reports the workspace gets one.
+ * `which` is the workspace's slug or root.
+ */
+export declare function createWorkspaceInvite(which: {
+    slug?: string;
+    root?: string;
+}, role?: "owner" | "member"): Promise<InviteResponse & {
+    workspace: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+}>;

package/dist/server/cloud.js

@@ -1,8 +1,9 @@
 import { promises as fs } from "node:fs";
 import os from "node:os";
 import { resolveWorkspace } from "../config.js";
-import { claimUrlFor, machineCloud, machineGoodbye, machineHeartbeat, machineRegister, machineUnlink, retiredCloudDir, unknownMachine, } from "../core/cloud.js";
+import { claimUrlFor, machineCloud, machineGoodbye, machineHeartbeat, machineRegister, machineUnlink, MAX_REPORTED_ROUTINES, retiredCloudDir, unknownMachine, workspaceInvite, } from "../core/cloud.js";
 import { identityString, readIdentity } from "../core/identity.js";
+import { routineReport } from "../core/routines.js";
 import { machineCredentials } from "./relay.js";
 const DEFAULT_INTERVAL = 60;
 const STANDALONE = { url: "", state: "off", reason: "only the daemon registers this machine with the cloud (`kraftwerk daemon start`)" };
@@ -17,6 +18,8 @@ const m = {
     version: "",
     /** The workspace list the cloud last acknowledged, as JSON: sent again only when it differs. */
     reported: "",
+    /** The routine report the cloud last took, as JSON (claimed only; "" sends it again). */
+    routines: "",
     /** One round at a time: a timer tick, a sync from the CLI and a workspace change never overlap. */
     lock: Promise.resolve(),
     warned: new Set(),
@@ -43,6 +46,26 @@ async function entries(withRoots) {
     return { list, ymlUrls };
 }
 const claimed = () => typeof m.status.account === "string" && m.status.account.length > 0;
+/** The routines that ran here, per served workspace with a ws_ id (vetoed ones left out), capped. */
+async function routineEntries() {
+    const out = [];
+    for (const o of m.source()) {
+        const ws = await resolveWorkspace(o.root).catch(() => null);
+        const id = ws?.config.id;
+        if (!id || ws.config.cloud?.enabled === false || !o.ws)
+            continue;
+        // A workspace closing meanwhile throws "workspace closed": it simply reports nothing.
+        const run = o.ws.run.bind(o.ws);
+        const ran = await Promise.resolve()
+            .then(() => run(() => routineReport()))
+            .catch(() => []);
+        for (const r of ran)
+            out.push({ workspaceId: id, ...r });
+        if (out.length >= MAX_REPORTED_ROUTINES)
+            break;
+    }
+    return out.slice(0, MAX_REPORTED_ROUTINES);
+}
 function warnYml(cloud, ymlUrls) {
     if (!ymlUrls.length)
         return;
@@ -85,6 +108,7 @@ async function register() {
             version: m.version,
         }, list);
         m.registered = true;
+        m.routines = "";
         // An unclaimed register carries no roots: the list counts as reported only when that is all the cloud should know.
         m.reported = r.account ? "" : JSON.stringify(list);
         m.status = {
@@ -108,9 +132,17 @@ async function heartbeat() {
     const wasClaimed = claimed();
     const { list } = await entries(wasClaimed);
     const now = JSON.stringify(list);
+    // Routines only while claimed; unclaimed, the next claim sends them afresh.
+    const routines = wasClaimed ? await routineEntries() : null;
+    const ran = routines ? JSON.stringify(routines) : "";
     try {
-        const r = await machineHeartbeat(m.status.url, m.creds, { version: m.version, ...(now !== m.reported ? { workspaces: list } : {}) });
+        const r = await machineHeartbeat(m.status.url, m.creds, {
+            version: m.version,
+            ...(now !== m.reported ? { workspaces: list } : {}),
+            ...(routines && ran !== m.routines ? { routines } : {}),
+        });
         m.reported = now;
+        m.routines = ran;
         m.status = {
             ...m.status, state: "connected", error: undefined, interval: r.interval || m.status.interval || DEFAULT_INTERVAL, lastSeen: new Date().toISOString(),
             ...(r.account !== undefined ? { account: r.account } : {}),
@@ -225,6 +257,7 @@ export async function unlinkMachineCloud() {
         const r = await machineUnlink(m.status.url, m.creds, m.version);
         // The next heartbeat sends the list again — without roots now.
         m.reported = "";
+        m.routines = "";
         m.status = { ...m.status, account: null, claimCode: r.claimCode ?? null, claimUrl: claimUrlFor(m.status.url, r.claimCode) };
         return m.status;
     });
@@ -249,3 +282,45 @@ export async function stopMachineCloud(owner) {
     if (registered && creds && url)
         await machineGoodbye(url, creds, m.version).catch(() => { });
 }
+/**
+ * What member verification needs (server/members.ts): the cloud's origin,
+ * this machine's credentials. Null when no machine client runs (a
+ * standalone server, the cloud turned off).
+ */
+export function machineLink() {
+    if (!m.started || m.status.state === "off" || !m.creds || !m.status.url)
+        return null;
+    return { url: m.status.url, creds: m.creds, version: m.version };
+}
+/** The served workspace whose kraftwerk.yml `id` is `id` (vetoed ones not), or null. */
+export async function servedWorkspace(id) {
+    for (const o of m.source()) {
+        const ws = await resolveWorkspace(o.root).catch(() => null);
+        if (ws?.config.id === id && ws.config.cloud?.enabled !== false)
+            return { slug: o.slug, name: o.name, root: o.root };
+    }
+    return null;
+}
+/**
+ * An invite to a served workspace (`kraftwerk invite`): the cloud's machine
+ * path, so only a claimed machine that reports the workspace gets one.
+ * `which` is the workspace's slug or root.
+ */
+export async function createWorkspaceInvite(which, role) {
+    const o = m.source().find((x) => (which.root && x.root === which.root) || (which.slug && x.slug === which.slug));
+    if (!o)
+        throw new Error(`the daemon does not serve ${which.slug ? `"${which.slug}"` : which.root} — open it first (\`kraftwerk ui\` in its folder)`);
+    const ws = await resolveWorkspace(o.root);
+    if (ws.config.cloud?.enabled === false)
+        throw new Error(`${o.slug} is left out of the cloud (cloud.enabled: false in kraftwerk.yml)`);
+    const id = ws.config.id;
+    if (!id)
+        throw new Error(`${o.slug} has no workspace id (ws_…) in kraftwerk.yml — run \`kraftwerk doctor --fix\``);
+    const link = machineLink();
+    if (!link)
+        throw new Error(m.status.reason ? `the cloud is off: ${m.status.reason}` : "this machine is not connected to the kraftwerk cloud — `kraftwerk daemon start`");
+    if (!claimed())
+        throw new Error("this machine is not claimed — run `kraftwerk login` first");
+    const invite = await workspaceInvite(link.url, link.creds, id, role, link.version);
+    return { ...invite, workspace: { id, slug: o.slug, name: o.name } };
+}

package/dist/server/members.d.ts

@@ -0,0 +1,87 @@
+import { type MemberVerdict } from "../core/cloud.js";
+/**
+ * Remote members: people who joined a workspace by invite in the cloud and
+ * have no clone of it. They hold a workspace-scoped member token (`kwm_…`)
+ * and reach the workspace through the relay: their app opens the encrypted
+ * channel (server/relay.ts) and, as its first sealed message, presents
+ *
+ *   → {t:"auth", memberToken: "kwm_…", workspaceId: "ws_…"}
+ *   ← {t:"auth", ok: true, member: {email, handle, role}, workspace: {id, slug, name}}
+ *   ← {t:"auth", ok: false, error}                      and the channel closes
+ *
+ * instead of a paired device's token. This daemon asks the cloud
+ * (/api/members/verify, with the machine's credentials) and caches the
+ * answer per (token, workspace) for five minutes — short, because revoking
+ * a member kills their tokens in the cloud at once, and the cache is all
+ * that keeps them in until it expires:
+ *
+ *   fresh        within the TTL the cache answers, the cloud is not asked
+ *   expired      a live session re-verifies lazily with its next request
+ *   unreachable  the cloud down, a 5xx, no machine client: a cached entry is
+ *                KEPT and used (stale); without one the session is refused
+ *   revoked      404 (unknown or revoked token) or 403 (this machine does not
+ *                host the workspace) drops the entry, and the session with it
+ *
+ * A session is scoped to that one workspace: the relay tags each of its
+ * requests with the session's random id (MEMBER_HEADER), which only this
+ * process knows, and trust.ts turns the tag into `member` trust; server.ts
+ * and router.ts refuse everything outside the workspace. Paired devices are
+ * untouched — machine-wide, as before.
+ */
+export type Member = MemberVerdict;
+/** The header the relay puts on a member session's requests (a client's own is dropped). */
+export declare const MEMBER_HEADER = "x-kraftwerk-member";
+/** How long a verified answer counts as fresh — tests shorten it; no argument restores the default. */
+export declare function setMemberCacheTtl(ms?: number): void;
+/** Forget every cached answer (tests). */
+export declare function forgetMemberCache(): void;
+export type Verdict = {
+    ok: true;
+    member: Member;
+    stale?: true;
+}
+/** `drop`: the cloud said no (the session ends); otherwise it could not be asked. */
+ | {
+    ok: false;
+    error: string;
+    drop: boolean;
+};
+/** Whether `token` is a member of `workspaceId`: the cache within its TTL, else the cloud. */
+export declare function verifyMember(token: string, workspaceId: string): Promise<Verdict>;
+/**
+ * A member's hello: verify the token for the workspace, find the workspace
+ * this daemon serves under that id, and open a session. Its id is what the
+ * relay tags the session's requests with.
+ */
+export declare function openMemberSession(token: unknown, workspaceId: unknown): Promise<{
+    ok: true;
+    id: string;
+    member: Member;
+    workspace: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+} | {
+    ok: false;
+    error: string;
+}>;
+/** The session behind a request's tag, or undefined. */
+export declare function memberSession(id: string): {
+    member: Member;
+    workspaceId: string;
+    slug: string;
+} | undefined;
+/**
+ * Before each of a session's requests: still a member? Within the TTL this
+ * is the cache; past it, the cloud (a cloud that cannot be reached keeps the
+ * cached answer). A refusal ends the session.
+ */
+export declare function checkMemberSession(id: string): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+    ended: boolean;
+}>;
+export declare function closeMemberSession(id: string): void;