@netnodeag/kraftwerk 0.77.0 → 0.78.1

package/dist/cli/invite.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerInviteCommand(program: Command): void;

package/dist/cli/invite.js

@@ -0,0 +1,48 @@
+import chalk from "chalk";
+import { resolveWorkspace, workspaceSlug } from "../config.js";
+import { findDaemon } from "../core/daemon.js";
+const fail = (message, code = 1) => {
+    console.error(chalk.red(`✖ ${message}`));
+    process.exit(code);
+};
+export function registerInviteCommand(program) {
+    program
+        .command("invite")
+        .description("Invite someone into this workspace as a remote member (no clone): prints the join code and link — the machine must be claimed (`kraftwerk login`)")
+        .option("--role <role>", "member (default) or owner")
+        .option("--workspace <slug>", "A workspace the daemon serves, instead of the one in this folder")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => {
+        if (opts.role !== undefined && opts.role !== "owner" && opts.role !== "member")
+            fail("--role is member or owner", 2);
+        let which;
+        if (opts.workspace)
+            which = { slug: opts.workspace };
+        else {
+            const ws = await resolveWorkspace(process.cwd()).catch((err) => fail(err.message));
+            if (!ws.configPath)
+                fail("not in a workspace folder (no kraftwerk.yml here or above) — run it there, or pass --workspace <slug>", 2);
+            if (!ws.config.id)
+                fail("this workspace has no id (ws_…) in kraftwerk.yml — run `kraftwerk doctor --fix`");
+            which = { root: ws.root, slug: workspaceSlug(ws) };
+        }
+        const daemon = await findDaemon();
+        if (!daemon)
+            fail("the daemon is not running — `kraftwerk daemon start` (it holds this machine's place in the cloud)");
+        const r = await fetch(`http://127.0.0.1:${daemon.port}/api/cloud/invite`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ ...which, ...(opts.role ? { role: opts.role } : {}) }),
+            signal: AbortSignal.timeout(20_000),
+        }).catch((err) => fail(`the daemon did not answer: ${err.message}`));
+        const data = (await r.json().catch(() => ({})));
+        if (!r.ok)
+            fail(data.error ?? `${r.status} from the daemon`);
+        if (opts.json)
+            return void console.log(JSON.stringify(data, null, 2));
+        console.log(`${chalk.green("✔")} invite to ${chalk.bold(data.workspace.name)} ${chalk.dim(`(${data.workspace.slug}, ${data.workspace.id})`)} as ${data.role}`);
+        console.log(`  code        ${chalk.bold(data.code)}`);
+        console.log(`  join link   ${chalk.cyan(data.url)}`);
+        console.log(chalk.dim(`  valid until ${new Date(data.expiresAt).toLocaleString()} — they join in the cloud and reach the workspace through this machine`));
+    });
+}

package/dist/cli/kraftwerk.js

@@ -23,6 +23,7 @@ import { registerRemoteCommand } from "./remote.js";
 import { registerJournalCommands } from "./journal.js";
 import { registerWhoamiCommand } from "./whoami.js";
 import { registerCloudCommands } from "./cloud.js";
+import { registerInviteCommand } from "./invite.js";
 import { applyDotenv } from "../dotenv.js";
 import { resolveWorkspace } from "../config.js";
 import { registerRoutineCommands } from "./routines.js";
@@ -49,6 +50,7 @@ import { runUi } from "./ui.js";
  *   kraftwerk daemon                  the machine's kraftwerk: every open workspace at <slug>.localhost
  *   kraftwerk cloud [on|off|status]   this machine in the kraftwerk cloud (the daemon registers it)
  *   kraftwerk login / logout          claim this machine into your cloud account (in the browser) / release it
+ *   kraftwerk invite [--role owner]   invite a remote member into this workspace (join code + link, via the daemon)
  *   kraftwerk doctor [--fix]          preflight: harness CLIs, docker, workflows, env, routine runners
  *   kraftwerk validate [paths...]     validate without executing
  *
@@ -306,6 +308,7 @@ registerRemoteCommand(program);
 registerJournalCommands(program);
 registerWhoamiCommand(program);
 registerCloudCommands(program);
+registerInviteCommand(program);
 program
     .command("ui")
     .description("Start the inspector web UI for this project's runs and workflows")

package/dist/cli/remote.js

@@ -49,7 +49,7 @@ export function registerRemoteCommand(program) {
     remote
         .command("on")
         .description("Turn remote access on: the daemon connects to the relay")
-        .option("--url <url>", "The cloud whose relay to use (default: the kraftwerk cloud)")
+        .option("--url <url>", "The cloud whose relay to use (default: this machine's cloud — env, cloud.json, else the kraftwerk cloud)")
         .action(async (opts) => {
         if (opts.url && !/^https?:\/\//.test(opts.url)) {
             console.error(chalk.red("✖ --url is the cloud's address, e.g. https://srv.kraftwerk-cloud.netnode.cloud"));

package/dist/client/relay.d.ts

@@ -28,6 +28,12 @@
  * presents a paired device's token like any network caller, and the daemon
  * applies the same trust rules (src/server/trust.ts). Anyone holding the
  * pairing link still needs a pairing code or a token.
+ *
+ * Or, as a remote member of one workspace, it sends `{t:"auth",
+ * memberToken, workspaceId}` as its first sealed message and waits for the
+ * daemon's `{t:"auth", ok, …}` (src/server/members.ts): the whole channel
+ * is then that member's, scoped to that workspace. A client that sends no
+ * auth is a device's channel exactly as before.
  */
 export declare const RELAY_PROTOCOL = 1;
 export declare function toBase64(bytes: Uint8Array): string;
@@ -96,7 +102,27 @@ export type TunnelToDaemon = {
 } | {
     t: "abort";
     id: number;
+}
+/** A member session: first, once, before any request (see src/server/members.ts). */
+ | {
+    t: "auth";
+    memberToken: string;
+    workspaceId: string;
 };
+/** Who the cloud says the member is, and the workspace the session is scoped to. */
+export interface MemberAuth {
+    member: {
+        email: string;
+        handle: string;
+        role: "owner" | "member";
+    };
+    /** `slug` addresses it: /w/<slug>/api/… */
+    workspace: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+}
 export type TunnelToClient = {
     t: "res";
     id: number;
@@ -113,6 +139,13 @@ export type TunnelToClient = {
     t: "fail";
     id: number;
     error: string;
+} | ({
+    t: "auth";
+    ok: true;
+} & MemberAuth) | {
+    t: "auth";
+    ok: false;
+    error: string;
 };
 /** The socket the client talks over — the browser's WebSocket and Node's global one both fit. */
 export interface RelaySocket {
@@ -134,6 +167,8 @@ export interface Tunnel {
     close(): void;
     /** Resolves when the connection ends, with why. */
     readonly closed: Promise<string>;
+    /** A member session's answer (ConnectOptions.member); absent on a device's channel. */
+    readonly member?: MemberAuth;
 }
 export interface ConnectOptions {
     /** The relay's client endpoint, e.g. wss://srv.kraftwerk-cloud.netnode.cloud/api/relay/client */
@@ -144,6 +179,11 @@ export interface ConnectOptions {
     connect?: (url: string) => RelaySocket;
     /** Abort the handshake after this long (default 15 s). */
     timeoutMs?: number;
+    /** Open the channel as a remote member of one workspace instead of a device: the daemon verifies it with the cloud. */
+    member?: {
+        token: string;
+        workspaceId: string;
+    };
 }
 /** Connect to a machine through the relay: the handshake, then a `fetch` that goes through it. */
 export declare function connectTunnel(opts: ConnectOptions): Promise<Tunnel>;

package/dist/client/relay.js

@@ -28,6 +28,12 @@
  * presents a paired device's token like any network caller, and the daemon
  * applies the same trust rules (src/server/trust.ts). Anyone holding the
  * pairing link still needs a pairing code or a token.
+ *
+ * Or, as a remote member of one workspace, it sends `{t:"auth",
+ * memberToken, workspaceId}` as its first sealed message and waits for the
+ * daemon's `{t:"auth", ok, …}` (src/server/members.ts): the whole channel
+ * is then that member's, scoped to that workspace. A client that sends no
+ * auth is a device's channel exactly as before.
  */
 const subtle = () => globalThis.crypto.subtle;
 const enc = new TextEncoder();
@@ -167,6 +173,7 @@ export async function connectTunnel(opts) {
     const closed = new Promise((r) => (resolveClosed = r));
     const pending = new Map();
     let nextId = 1;
+    let onAuth = null;
     const finish = (why) => {
         if (closedWhy)
             return;
@@ -230,6 +237,11 @@ export async function connectTunnel(opts) {
         });
     });
     const receive = (msg) => {
+        if (msg.t === "auth") {
+            onAuth?.(msg);
+            onAuth = null;
+            return;
+        }
         const p = pending.get(msg.id);
         if (!p)
             return;
@@ -277,6 +289,28 @@ export async function connectTunnel(opts) {
         ws.send(await channel.seal(JSON.stringify(msg)));
     };
     await ready;
+    let member;
+    if (opts.member) {
+        const m = opts.member;
+        const answer = await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error("the machine did not answer the member's hello")), opts.timeoutMs ?? 15_000);
+            onAuth = (msg) => {
+                clearTimeout(timer);
+                resolve(msg);
+            };
+            void closed.then((why) => {
+                clearTimeout(timer);
+                reject(new Error(why));
+            });
+            send({ t: "auth", memberToken: m.token, workspaceId: m.workspaceId }).catch(reject);
+        });
+        if (!answer.ok) {
+            ws.close(1000, "bye");
+            finish(answer.error);
+            throw new Error(answer.error);
+        }
+        member = { member: answer.member, workspace: answer.workspace };
+    }
     const tunnelFetch = async (input, init) => {
         if (closedWhy)
             throw new Error(closedWhy);
@@ -314,5 +348,6 @@ export async function connectTunnel(opts) {
             finish("closed");
         },
         closed,
+        ...(member ? { member } : {}),
     };
 }

package/dist/client/routes.d.ts

@@ -45,6 +45,7 @@ export declare const ROUTES: {
     readonly "chats.setVibeable": readonly ["POST", "/api/chats/:id/vibeable"];
     readonly "chats.steer": readonly ["POST", "/api/chats/:id/steer"];
     readonly "chats.stopTask": readonly ["POST", "/api/chats/:id/task-stop"];
+    readonly "cloud.invite": readonly ["POST", "/api/cloud/invite"];
     readonly "cloud.set": readonly ["POST", "/api/cloud"];
     readonly "cloud.status": readonly ["GET", "/api/cloud"];
     readonly "cloud.sync": readonly ["POST", "/api/cloud/sync"];

package/dist/client/routes.js

@@ -46,6 +46,7 @@ export const ROUTES = {
     "chats.setVibeable": ["POST", "/api/chats/:id/vibeable"],
     "chats.steer": ["POST", "/api/chats/:id/steer"],
     "chats.stopTask": ["POST", "/api/chats/:id/task-stop"],
+    "cloud.invite": ["POST", "/api/cloud/invite"],
     "cloud.set": ["POST", "/api/cloud"],
     "cloud.status": ["GET", "/api/cloud"],
     "cloud.sync": ["POST", "/api/cloud/sync"],

package/dist/core/chat/channel-turns.d.ts

@@ -1,4 +1,4 @@
-import type { Attachment } from "./types.js";
+import type { Attachment, ChatPerson } from "./types.js";
 import { type ChatState } from "./state.js";
 /**
  * Channels: how a post wakes the agents it mentions, and how each agent
@@ -10,6 +10,6 @@ import { type ChatState } from "./state.js";
  * parallel, never blocking the humans, who can keep posting. An agent that
  * is still busy is woken again when its turn ends, so nothing is lost.
  */
-export declare function postChannelMessage(state: ChatState, slug: string, text: string, from?: string, attachments?: Attachment[]): Promise<{
+export declare function postChannelMessage(state: ChatState, slug: string, text: string, from?: string, attachments?: Attachment[], by?: ChatPerson): Promise<{
     error?: string;
 }>;

package/dist/core/chat/channel-turns.js

@@ -15,12 +15,12 @@ import { dropSeat, emit, forgetFailedResume, newSeat } from "./state.js";
  * parallel, never blocking the humans, who can keep posting. An agent that
  * is still busy is woken again when its turn ends, so nothing is lost.
  */
-export async function postChannelMessage(state, slug, text, from, attachments) {
+export async function postChannelMessage(state, slug, text, from, attachments, by) {
     const channel = await getChannel(slug).catch(() => null);
     if (!channel)
         return { error: `channel "${slug}" has no definition under channels/` };
     const name = (from ?? "").replace(/\s+/g, " ").trim().slice(0, 40) || "you";
-    emit(state, { type: "user_message", text, ...(attachments ? { attachments } : {}) }, { kind: "human", name });
+    emit(state, { type: "user_message", text, ...(attachments ? { attachments } : {}), ...(by ? { by } : {}) }, { kind: "human", name });
     void writeMeta(state.meta).catch(() => { });
     for (const target of mentionTargets(text, channel))
         void wakeSeat(state, channel, target, 0);

package/dist/core/chat/sessions.d.ts

@@ -1,7 +1,19 @@
-import type { Attachment, ChatAgentId, ChatMeta, ChatScope, ElicitationAnswer, StoredChatEvent } from "./types.js";
+import type { Attachment, ChatAgentId, ChatMeta, ChatPerson, ChatScope, ElicitationAnswer, StoredChatEvent } from "./types.js";
 import { type Channel } from "../channels.js";
 export { agentFilesContext, agentJournalContext, agentVibeablesContext, vibeableContext } from "./context.js";
 export { disposeAllBackends, disposeWorkspaceBackends } from "./state.js";
+/**
+ * Chats: what the API does with them — create, post, steer, answer, fork,
+ * rename, delete, subscribe. The pieces live beside it: the live state and
+ * its events (state.ts), the context an agent is given (context.ts), its
+ * process (seats.ts) and channel turns (channel-turns.ts).
+ */
+/**
+ * This machine's person: its identity handle (identity.ts). What a chat or
+ * message is signed with when nobody else is named — local use, a paired
+ * device, a routine's run. A member session names its member instead.
+ */
+export declare function localPerson(): Promise<ChatPerson>;
 /**
  * The folder the agent is actually spawned in. A vibeable that was removed
  * leaves meta.cwd pointing nowhere; spawning there fails, so fall back to
@@ -18,6 +30,10 @@ export declare function createChat(opts: {
     resume?: string;
     /** The project an agent's chat works in (meta.project); the caller checks that it exists. */
     project?: string;
+    /** Who starts it; default this machine's person. */
+    author?: ChatPerson;
+    /** A private routine's run: hidden from remote callers (meta.private). */
+    private?: boolean;
 }): Promise<ChatMeta>;
 /** A permission request is waiting for a human in this chat (live state only — a restart drops it with the backend). */
 export declare function chatAwaitingApproval(id: string): boolean;
@@ -61,6 +77,7 @@ export declare function getChat(id: string): Promise<{
 export declare function postMessage(id: string, text: string, opts?: {
     from?: string;
     attachments?: Attachment[];
+    by?: ChatPerson;
 }): Promise<{
     error?: string;
 }>;
@@ -101,7 +118,7 @@ export declare function setChatVibeable(id: string, slug: string | null): Promis
  * once. The source's process is (re)spawned if needed; the fork's own
  * process starts with its first message and resumes the forked id.
  */
-export declare function forkChat(id: string): Promise<{
+export declare function forkChat(id: string, by?: ChatPerson): Promise<{
     error?: string;
     status?: number;
     meta?: ChatMeta;
@@ -125,7 +142,7 @@ export declare function answerElicitation(id: string, requestId: string, answer:
  * for it to end. Shown in the thread like any message. When no turn is
  * running (or the agent cannot take steering) it goes the ordinary way.
  */
-export declare function steerChat(id: string, text: string, attachments?: Attachment[]): Promise<{
+export declare function steerChat(id: string, text: string, attachments?: Attachment[], by?: ChatPerson): Promise<{
     error?: string;
 }>;
 export declare function stopChatTask(id: string, taskId: string): Promise<{

package/dist/core/chat/sessions.js

@@ -5,6 +5,7 @@ import { getAgent } from "../agents.js";
 import { resolveVibeable } from "../vibeables.js";
 import { deleteAgentSession, listAgentSessions } from "./acp.js";
 import { chatHref, pushNotification } from "../notifications.js";
+import { readIdentity } from "../identity.js";
 import { moveToTrash } from "../trash.js";
 import { attachmentPath, copyChatFiles, listChatMetas, newChatId, readMetaAt, safeChatDir, writeMeta } from "./store.js";
 import { postChannelMessage } from "./channel-turns.js";
@@ -20,6 +21,14 @@ export { disposeAllBackends, disposeWorkspaceBackends } from "./state.js";
  * process (seats.ts) and channel turns (channel-turns.ts).
  */
 /* ---------- public API (used by server.ts) ---------- */
+/**
+ * This machine's person: its identity handle (identity.ts). What a chat or
+ * message is signed with when nobody else is named — local use, a paired
+ * device, a routine's run. A member session names its member instead.
+ */
+export async function localPerson() {
+    return { handle: (await readIdentity()).handle };
+}
 /** Where a chat's agent runs when no vibeable is open: the run folder for run chats, else the project root. */
 const defaultCwd = (scope) => (scope.kind === "run" ? safeRunDir(scope.runId) : workspaceRoot());
 /**
@@ -37,6 +46,7 @@ export async function effectiveCwd(meta) {
 export async function createChat(opts) {
     const cwd = defaultCwd(opts.scope);
     const now = new Date().toISOString();
+    const author = opts.author ?? (await localPerson());
     const meta = {
         id: newChatId(),
         agent: opts.agent,
@@ -45,6 +55,8 @@ export async function createChat(opts) {
         scope: opts.scope,
         ...(opts.project && opts.scope.kind === "agent" ? { project: opts.project } : {}),
         ...(opts.resume && opts.agent !== "pi" ? { sessions: { [MAIN]: opts.resume } } : {}),
+        author,
+        ...(opts.private ? { private: true } : {}),
         createdAt: now,
         updatedAt: now,
     };
@@ -121,8 +133,9 @@ export async function postMessage(id, text, opts = {}) {
     if (!state)
         return { error: "not found" };
     const attachments = opts.attachments?.length ? opts.attachments : undefined;
+    const by = opts.by ?? (await localPerson());
     if (state.meta.scope.kind === "channel")
-        return postChannelMessage(state, state.meta.scope.slug, text, opts.from, attachments);
+        return postChannelMessage(state, state.meta.scope.slug, text, opts.from, attachments, by);
     const seat = mainSeat(state);
     if (seat.busy)
         return { error: "agent is still working — wait for the turn to finish" };
@@ -133,7 +146,7 @@ export async function postMessage(id, text, opts = {}) {
         state.meta.title = text.replace(/\s+/g, " ").trim().slice(0, 80);
         void writeMeta(state.meta).catch(() => { });
     }
-    const turnStart = emit(state, { type: "user_message", text, ...(attachments ? { attachments } : {}) }).seq;
+    const turnStart = emit(state, { type: "user_message", text, ...(attachments ? { attachments } : {}), by }).seq;
     // The turn runs in the background; the HTTP request returns immediately
     // and the browser follows along on the SSE stream.
     void (async () => {
@@ -319,7 +332,7 @@ export async function setChatVibeable(id, slug) {
  * once. The source's process is (re)spawned if needed; the fork's own
  * process starts with its first message and resumes the forked id.
  */
-export async function forkChat(id) {
+export async function forkChat(id, by) {
     const state = await loadState(id);
     if (!state)
         return { error: "not found", status: 404 };
@@ -351,6 +364,7 @@ export async function forkChat(id) {
         id: newChatId(),
         title: meta.title ? `${meta.title} (fork)` : "",
         sessions: { [MAIN]: forked },
+        author: by ?? (await localPerson()),
         createdAt: now,
         updatedAt: now,
     };
@@ -394,7 +408,7 @@ export async function answerElicitation(id, requestId, answer) {
  * for it to end. Shown in the thread like any message. When no turn is
  * running (or the agent cannot take steering) it goes the ordinary way.
  */
-export async function steerChat(id, text, attachments) {
+export async function steerChat(id, text, attachments, by) {
     const state = await loadState(id);
     if (!state)
         return { error: "not found" };
@@ -402,17 +416,18 @@ export async function steerChat(id, text, attachments) {
         return { error: "channels take messages, not steering — @mention the agent" };
     const seat = mainSeat(state);
     const files = attachments?.length ? attachments : undefined;
+    const person = by ?? (await localPerson());
     if (!seat.busy || !seat.backend?.steer)
-        return postMessage(id, text, { attachments: files });
+        return postMessage(id, text, { attachments: files, by: person });
     try {
         const outcome = await seat.backend.steer(text, promptFiles(id, files));
         if (outcome === "promptRequired")
-            return postMessage(id, text, { attachments: files });
+            return postMessage(id, text, { attachments: files, by: person });
     }
     catch (err) {
         return { error: err.message };
     }
-    emit(state, { type: "user_message", text, steered: true, ...(files ? { attachments: files } : {}) });
+    emit(state, { type: "user_message", text, steered: true, ...(files ? { attachments: files } : {}), by: person });
     void writeMeta(state.meta).catch(() => { });
     return {};
 }

package/dist/core/chat/types.d.ts

@@ -31,6 +31,17 @@ export type ChatScope = {
     kind: "channel";
     slug: string;
 };
+/**
+ * The person behind a chat or a message: this machine's identity handle
+ * (local use, a paired device) or a remote member of the workspace (the
+ * cloud vouched for their handle and email; see server/members.ts).
+ * Absent on chats and messages from before authors were recorded.
+ */
+export interface ChatPerson {
+    handle: string;
+    /** A remote member's account email; absent for this machine's own person. */
+    email?: string;
+}
 /** Who produced an event. Absent on single-agent chats (the one human, the one agent). */
 export type Author = {
     kind: "human";
@@ -60,6 +71,14 @@ export interface ChatMeta {
      * over with the transcript as a summary.
      */
     sessions?: Record<string, string>;
+    /** Who started the chat (a routine's run: this machine's person). */
+    author?: ChatPerson;
+    /**
+     * A run of a `private: true` routine: left out of what remote callers see
+     * (member sessions, paired devices over the relay); this machine and the
+     * LAN still see it.
+     */
+    private?: boolean;
     createdAt: string;
     updatedAt: string;
 }
@@ -166,11 +185,13 @@ export type ElicitationAnswer = {
  */
 export type ChatEvent = 
 /** `steered`: handed into the running turn instead of starting the next one. */
+/** `by`: the person who sent it (see ChatPerson). */
 {
     type: "user_message";
     text: string;
     steered?: boolean;
     attachments?: Attachment[];
+    by?: ChatPerson;
 } | {
     type: "text";
     text: string;

package/dist/core/cloud.d.ts

@@ -23,13 +23,25 @@
  *
  *   /api/machines/register   {id, key, secret, name, handle, hostname?, platform?, version, interval?, workspaces}
  *                            → {ok, interval, claimCode|null, account|null}   (403: wrong secret)
- *   /api/machines/heartbeat  {id, secret, version?, workspaces?} → {ok, interval, account, claimCode}
+ *   /api/machines/heartbeat  {id, secret, version?, workspaces?, routines?} → {ok, interval, account, claimCode}
  *   /api/machines/goodbye    {id, secret}
  *   /api/machines/unlink     {id, secret} → {ok, claimCode}
  *
  * workspaces: [{id?: "ws_…", name, slug, root?}] — `root` only once the
  * machine is claimed (account set): an unclaimed machine tells the cloud no
  * paths.
+ *
+ * routines: [{workspaceId, routineId: "<agent>/<id>", name, lastRunAt|null, ok}]
+ * — the routines that ran here, private ones left out, at most 500; only
+ * while claimed, and only when it changed since the cloud last took it.
+ *
+ * Membership (remote members, no clone — they reach a workspace through the
+ * relay with a workspace-scoped member token, see server/members.ts):
+ *
+ *   /api/members/verify          {id, secret, token, workspaceId} → {email, handle, role: "owner"|"member"}
+ *                                (404: unknown or revoked token; 403: this machine does not host the workspace)
+ *   /api/workspaces/:id/invites  {id, secret, role?} → {code, url, role, expiresAt}
+ *                                (a claimed machine reporting the workspace; `kraftwerk invite`)
  */
 export interface CloudFile {
     enabled?: boolean;
@@ -67,6 +79,28 @@ export interface HeartbeatResponse {
     account: string | null;
     claimCode: string | null;
 }
+/** What the cloud vouches for about a member token in one workspace. */
+export interface MemberVerdict {
+    email: string;
+    handle: string;
+    role: "owner" | "member";
+}
+export interface InviteResponse {
+    code: string;
+    url: string;
+    role: "owner" | "member";
+    expiresAt: string;
+}
+/** One routine that ran here, in the heartbeat (claimed machines only). */
+export interface RoutineReportEntry {
+    workspaceId: string;
+    routineId: string;
+    name: string;
+    lastRunAt: string | null;
+    ok: boolean;
+}
+/** The most routines one heartbeat carries. */
+export declare const MAX_REPORTED_ROUTINES = 500;
 export interface UnlinkResponse {
     ok: boolean;
     claimCode: string | null;
@@ -110,6 +144,9 @@ export declare const machineRegister: (base: string, creds: Credentials, hello:
 export declare const machineHeartbeat: (base: string, creds: Credentials, extra: {
     version?: string;
     workspaces?: MachineWorkspace[];
+    routines?: RoutineReportEntry[];
 }) => Promise<HeartbeatResponse>;
 export declare const machineGoodbye: (base: string, creds: Credentials, version?: string) => Promise<unknown>;
 export declare const machineUnlink: (base: string, creds: Credentials, version?: string) => Promise<UnlinkResponse>;
+export declare const memberVerify: (base: string, creds: Credentials, token: string, workspaceId: string, version?: string) => Promise<MemberVerdict>;
+export declare const workspaceInvite: (base: string, creds: Credentials, workspaceId: string, role?: "owner" | "member", version?: string) => Promise<InviteResponse>;

package/dist/core/cloud.js

@@ -3,6 +3,8 @@ import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { CLOUD_DEFAULT_URL } from "../config.js";
+/** The most routines one heartbeat carries. */
+export const MAX_REPORTED_ROUTINES = 500;
 // Resolved on every use, not at import: a test swaps HOME after some module already imported this one.
 const kwHome = () => path.join(os.homedir(), ".kraftwerk");
 export const cloudFilePath = () => path.join(kwHome(), "cloud.json");
@@ -92,3 +94,5 @@ export const machineRegister = (base, creds, hello, workspaces) => cloudPost(bas
 export const machineHeartbeat = (base, creds, extra) => cloudPost(base, "/api/machines/heartbeat", { id: creds.id, secret: creds.secret, ...extra }, { version: extra.version });
 export const machineGoodbye = (base, creds, version) => cloudPost(base, "/api/machines/goodbye", { id: creds.id, secret: creds.secret }, { version, timeout: GOODBYE_TIMEOUT_MS });
 export const machineUnlink = (base, creds, version) => cloudPost(base, "/api/machines/unlink", { id: creds.id, secret: creds.secret }, { version });
+export const memberVerify = (base, creds, token, workspaceId, version) => cloudPost(base, "/api/members/verify", { id: creds.id, secret: creds.secret, token, workspaceId }, { version });
+export const workspaceInvite = (base, creds, workspaceId, role, version) => cloudPost(base, `/api/workspaces/${encodeURIComponent(workspaceId)}/invites`, { id: creds.id, secret: creds.secret, ...(role ? { role } : {}) }, { version });

package/dist/core/routines.d.ts

@@ -18,7 +18,12 @@
  * runs_on is exactly this machine's identity. No runs_on, no runner — an
  * unassigned routine fires nowhere until someone adopts it ("run these
  * here"), which writes runs_on and commits routines.yml so the other clones
- * learn who runs it. `private:` is stored and round-tripped; nothing reads it yet.
+ * learn who runs it.
+ *
+ * `private: true` keeps a routine's runs to this machine: each run's chat is
+ * marked private when it is created (ChatMeta.private), and remote callers —
+ * member sessions and paired devices over the relay — never get it listed;
+ * the machine's cloud report (routineReport) leaves the routine out too.
  */
 export interface Routine {
     id: string;
@@ -29,7 +34,7 @@ export interface Routine {
     enabled: boolean;
     /** The one identity (`handle@machine`) that fires it. Absent: unassigned, fires nowhere. */
     runsOn?: string;
-    /** Stored as given; no behaviour yet. */
+    /** Its runs' chats stay off remote callers' listings, and out of the cloud's report. */
     private?: boolean;
 }
 /**
@@ -101,6 +106,21 @@ export declare function routineStatuses(slug: string): Promise<RoutineStatus[]>;
 export declare function runRoutineNow(slug: string, id: string): Promise<{
     chatId: string;
 }>;
+/** One routine that ran on this machine, as the machine's cloud heartbeat reports it (server/cloud.ts). */
+export interface RoutineRan {
+    /** `<agent>/<routine id>`: the key in routines-state.json. */
+    routineId: string;
+    name: string;
+    /** Null when it never started (only failed to). */
+    lastRunAt: string | null;
+    /** False when its last attempt could not start (lastError). */
+    ok: boolean;
+}
+/**
+ * The current workspace's routines that ran (or tried to) on this machine,
+ * from routines-state.json and the listings; private routines left out.
+ */
+export declare function routineReport(): Promise<RoutineRan[]>;
 /**
  * The routines due at `now` that fire on this machine: enabled, runs_on
  * exactly this identity, cron matching. Everything else — unassigned,

package/dist/core/routines.js

@@ -252,6 +252,7 @@ async function fireRoutine(slug, routine) {
         agent: def.harness,
         scope: { kind: "agent", slug: slug, routine: routine.id },
         title: `⏰ ${routine.name}`,
+        ...(routine.private ? { private: true } : {}),
     });
     const { error } = await postMessage(meta.id, routine.prompt);
     if (error)
@@ -288,6 +289,31 @@ export async function runRoutineNow(slug, id) {
         throw err;
     }
 }
+/**
+ * The current workspace's routines that ran (or tried to) on this machine,
+ * from routines-state.json and the listings; private routines left out.
+ */
+export async function routineReport() {
+    const state = await readState();
+    const out = [];
+    const bySlug = new Map();
+    for (const [key, s] of Object.entries(state)) {
+        if (!s.lastRunAt && !s.lastError)
+            continue;
+        const cut = key.indexOf("/");
+        if (cut <= 0)
+            continue;
+        const slug = key.slice(0, cut);
+        const id = key.slice(cut + 1);
+        if (!bySlug.has(slug))
+            bySlug.set(slug, await listRoutines(slug).catch(() => []));
+        const r = bySlug.get(slug).find((x) => x.id === id);
+        if (r?.private)
+            continue;
+        out.push({ routineId: key, name: r?.name ?? id, lastRunAt: s.lastRunAt ?? null, ok: !s.lastError });
+    }
+    return out.sort((a, b) => a.routineId.localeCompare(b.routineId));
+}
 /* ---------- scheduler ---------- */
 /** The scheduler's timer, one per workspace. */
 const scheduler = perWorkspace(() => ({ timer: null }));