@netnodeag/kraftwerk 0.76.0 → 0.78.0

package/dist/client/routes.d.ts

@@ -45,6 +45,11 @@ 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"];
+    readonly "cloud.unlink": readonly ["POST", "/api/cloud/unlink"];
     readonly "devices.code": readonly ["POST", "/api/devices/code"];
     readonly "devices.dropPush": readonly ["DELETE", "/api/devices/push"];
     readonly "devices.list": readonly ["GET", "/api/devices"];

package/dist/client/routes.js

@@ -46,6 +46,11 @@ 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"],
+    "cloud.unlink": ["POST", "/api/cloud/unlink"],
     "devices.code": ["POST", "/api/devices/code"],
     "devices.dropPush": ["DELETE", "/api/devices/push"],
     "devices.list": ["GET", "/api/devices"],

package/dist/config.d.ts

@@ -34,11 +34,10 @@
   *     root: apps               # one folder per app, part of the workspace. Default: kraftwerk-data/vibeables
  *   projects:                  # goal-scoped folders (brief, systems of record, links) that chats work in (absent = off, bare key = on)
  *     root: kraftwerk-data/projects   # one folder per project, part of the workspace. Default: kraftwerk-data/projects
- *   cloud:                     # kraftwerk cloud manager — ON BY DEFAULT, `enabled: false` opts out
- *     url: https://srv.kraftwerk-cloud.netnode.cloud   # where the cloud answers (default). KRAFTWERK_CLOUD_URL env wins; "off" disables
- *     interval: 60             # seconds between heartbeats. Default: 60
- *   # No key here: the cloud hands the instance its identity and a claim code (Settings → Cloud in the UI);
- *   # a server that should register under an account unattended puts KRAFTWERK_CLOUD_TOKEN into .env.
+ *   cloud:                     # the machine's kraftwerk cloud record lists this workspace — `enabled: false` leaves it out
+ *     enabled: false           # a per-workspace veto; the machine's switch is `kraftwerk cloud on|off` (~/.kraftwerk/cloud.json)
+ *   # No key here: the daemon registers the MACHINE (its relay id) and `kraftwerk login` claims it.
+ *   # `url` and `interval` are deprecated: the cloud's origin is the machine's (cloud.json / KRAFTWERK_CLOUD_URL).
  */
 /** Stable, versionless URL of the workflow JSON schema (editor validation). */
 export declare const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json";
@@ -123,35 +122,23 @@ export declare const PROJECTS_DEFAULT_ROOT = "kraftwerk-data/projects";
 /** Absolute projects root when the feature is on, undefined otherwise. */
 export declare function projectsRootFor(project: ResolvedWorkspace): string | undefined;
 /**
- * Cloud manager: the kraftwerk cloud is ~/.kraftwerk made reachable over
- * the internet — a registry of instances across machines. Every inspector
- * registers on start and heartbeats while it runs, so the cloud's global
- * view shows this workspace, where it runs, and whether it is live; the
- * user claims it into their account with the code the UI shows. On by
- * default: an absent block is the same as a bare one, `enabled: false`
- * opts out, and so does KRAFTWERK_CLOUD_URL=off in the environment (what
- * the tests and CI set). No credential lives in kraftwerk.yml — the
- * identity comes from the cloud, and an account token for unattended
- * servers is KRAFTWERK_CLOUD_TOKEN in .env.
+ * kraftwerk.yml `cloud:` — since the cloud knows machines (core/cloud.ts,
+ * server/cloud.ts), this block only vetoes: `enabled: false` leaves the
+ * workspace out of the machine's reports. The machine's switch and the
+ * cloud's origin are ~/.kraftwerk/cloud.json (`kraftwerk cloud on|off`) and
+ * KRAFTWERK_CLOUD_URL. `url` is still honored for one release (with a
+ * warning) when the machine names none; `interval` is ignored — the cloud
+ * sets the cadence.
  */
 export interface CloudConfig {
-    /** false turns the feature off. Default: true. */
+    /** false leaves this workspace out of the machine's cloud record. Default: true. */
     enabled?: boolean;
-    /** Origin of the cloud manager. Default: https://srv.kraftwerk-cloud.netnode.cloud */
+    /** @deprecated The machine's (cloud.json / KRAFTWERK_CLOUD_URL); used only when the machine names none. */
     url?: string;
-    /** Seconds between heartbeats. Default: 60 (the cloud may raise it). */
+    /** @deprecated Ignored: the cloud sets the heartbeat interval. */
     interval?: number;
 }
 export declare const CLOUD_DEFAULT_URL = "https://srv.kraftwerk-cloud.netnode.cloud";
-export declare const CLOUD_DEFAULT_INTERVAL = 60;
-export interface CloudSettings {
-    url: string;
-    interval: number;
-    /** KRAFTWERK_CLOUD_TOKEN from the environment (.env), when set. */
-    token?: string;
-}
-/** The effective cloud settings when the feature is on; undefined when kraftwerk.yml or the environment turned it off. */
-export declare function cloudFor(project: ResolvedWorkspace): CloudSettings | undefined;
 /** A directory as a .gitignore entry: relative, forward slashes, no trailing slash; undefined outside the root. */
 export declare function ignoreEntryFor(projectRoot: string, dir: string): string | undefined;
 /** True when .gitignore text already covers the entry (with or without a leading or trailing slash). */
@@ -206,7 +193,7 @@ export interface WorkspaceConfig {
     vibeables?: VibeablesConfig;
     /** Projects: goal-scoped folders the chats work in. Absent = off. */
     projects?: ProjectsConfig;
-    /** kraftwerk cloud manager this instance registers with. Absent = on with defaults; `enabled: false` opts out. */
+    /** The machine's cloud record lists this workspace. Absent = listed; `enabled: false` leaves it out. */
     cloud?: CloudConfig;
 }
 export interface ResolvedWorkspace {

package/dist/config.js

@@ -39,11 +39,10 @@ import { parse } from "yaml";
   *     root: apps               # one folder per app, part of the workspace. Default: kraftwerk-data/vibeables
  *   projects:                  # goal-scoped folders (brief, systems of record, links) that chats work in (absent = off, bare key = on)
  *     root: kraftwerk-data/projects   # one folder per project, part of the workspace. Default: kraftwerk-data/projects
- *   cloud:                     # kraftwerk cloud manager — ON BY DEFAULT, `enabled: false` opts out
- *     url: https://srv.kraftwerk-cloud.netnode.cloud   # where the cloud answers (default). KRAFTWERK_CLOUD_URL env wins; "off" disables
- *     interval: 60             # seconds between heartbeats. Default: 60
- *   # No key here: the cloud hands the instance its identity and a claim code (Settings → Cloud in the UI);
- *   # a server that should register under an account unattended puts KRAFTWERK_CLOUD_TOKEN into .env.
+ *   cloud:                     # the machine's kraftwerk cloud record lists this workspace — `enabled: false` leaves it out
+ *     enabled: false           # a per-workspace veto; the machine's switch is `kraftwerk cloud on|off` (~/.kraftwerk/cloud.json)
+ *   # No key here: the daemon registers the MACHINE (its relay id) and `kraftwerk login` claims it.
+ *   # `url` and `interval` are deprecated: the cloud's origin is the machine's (cloud.json / KRAFTWERK_CLOUD_URL).
  */
 /** Stable, versionless URL of the workflow JSON schema (editor validation). */
 export const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json";
@@ -98,19 +97,6 @@ export function projectsRootFor(project) {
     return path.resolve(project.root, p.root ?? PROJECTS_DEFAULT_ROOT);
 }
 export const CLOUD_DEFAULT_URL = "https://srv.kraftwerk-cloud.netnode.cloud";
-export const CLOUD_DEFAULT_INTERVAL = 60;
-/** The effective cloud settings when the feature is on; undefined when kraftwerk.yml or the environment turned it off. */
-export function cloudFor(project) {
-    const c = project.config.cloud ?? {};
-    const envUrl = process.env.KRAFTWERK_CLOUD_URL?.trim();
-    if (c.enabled === false || envUrl?.toLowerCase() === "off")
-        return undefined;
-    return {
-        url: (envUrl || c.url || CLOUD_DEFAULT_URL).replace(/\/+$/, ""),
-        interval: c.interval ?? CLOUD_DEFAULT_INTERVAL,
-        token: process.env.KRAFTWERK_CLOUD_TOKEN?.trim() || undefined,
-    };
-}
 /** A directory as a .gitignore entry: relative, forward slashes, no trailing slash; undefined outside the root. */
 export function ignoreEntryFor(projectRoot, dir) {
     const rel = path.relative(projectRoot, path.resolve(projectRoot, dir)).split(path.sep).join("/");
@@ -337,7 +323,7 @@ function validateCloud(configPath, value) {
     const c = value;
     for (const key of Object.keys(c)) {
         if (key === "token") {
-            throw new Error(`${file}: cloud.token does not belong in kraftwerk.yml — put KRAFTWERK_CLOUD_TOKEN into .env (and only for unattended servers; a workspace with a UI is claimed with its code)`);
+            throw new Error(`${file}: cloud.token does not belong in kraftwerk.yml — the cloud knows the machine, and \`kraftwerk login\` claims it`);
         }
         if (!["enabled", "url", "interval"].includes(key)) {
             throw new Error(`${file}: cloud.${key} is unknown (allowed: enabled, url, interval)`);

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

@@ -0,0 +1,152 @@
+/**
+ * The kraftwerk cloud, machine side: the settings and the wire contract the
+ * daemon's machine client (server/cloud.ts) and the CLI (`kraftwerk cloud`,
+ * `login`, `logout`) share.
+ *
+ * The daemon registers this MACHINE once; the workspaces it serves ride
+ * along as children of that record. The machine's id is its relay id (the
+ * hash of the X25519 key in ~/.kraftwerk/relay.json) and the proof is the
+ * relay secret — the key cannot sign. Nothing here opens the relay link.
+ *
+ * ~/.kraftwerk/cloud.json — the machine's switch and the cloud's origin:
+ *
+ *   { "enabled": false, "url": "https://cloud.example.com" }
+ *
+ * `enabled` absent = on. The origin: KRAFTWERK_CLOUD_URL (env) wins, then
+ * cloud.json `url`, then a kraftwerk.yml `cloud.url` of an open workspace
+ * (deprecated, one release), then the default. KRAFTWERK_CLOUD_URL=off
+ * turns the cloud off for the process (what tests and CI set). kraftwerk.yml
+ * `cloud.enabled: false` is a per-workspace veto: that workspace is left out
+ * of the machine's reports.
+ *
+ * The contract (all POST, JSON):
+ *
+ *   /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?, 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;
+    url?: string;
+}
+/** Where the effective origin came from. */
+export type CloudUrlSource = "env" | "cloud.json" | "kraftwerk.yml" | "default";
+export interface MachineCloud {
+    enabled: boolean;
+    url: string;
+    source: CloudUrlSource;
+    /** Why it is off, when it is. */
+    reason?: string;
+}
+export interface MachineWorkspace {
+    id?: string;
+    name: string;
+    slug: string;
+    root?: string;
+}
+export interface Credentials {
+    id: string;
+    key: string;
+    secret: string;
+}
+export interface RegisterResponse {
+    ok: boolean;
+    interval: number;
+    claimCode: string | null;
+    account: string | null;
+}
+export interface HeartbeatResponse {
+    ok: boolean;
+    interval: number;
+    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;
+}
+export declare const cloudFilePath: () => string;
+/** The retired per-workspace identities (before machines): deleted at the daemon's start. */
+export declare const retiredCloudDir: () => string;
+export declare function readCloudFile(): Promise<CloudFile>;
+/** Merge a change into cloud.json (a `url: undefined` leaves the URL as it is). */
+export declare function writeCloudFile(change: CloudFile): Promise<CloudFile>;
+/** Whether the environment turned the cloud off for this process. */
+export declare const envCloudOff: () => boolean;
+/**
+ * The machine's effective cloud. `ymlUrls`: `cloud.url` of open workspaces
+ * (deprecated) — used only when neither the environment nor cloud.json names
+ * an origin.
+ */
+export declare function machineCloud(ymlUrls?: string[]): Promise<MachineCloud>;
+export declare const claimUrlFor: (url: string, code: string | null | undefined) => string | null;
+export declare const GOODBYE_TIMEOUT_MS = 800;
+/** A refused or failed call; `status` is the HTTP status (0: no answer). */
+export declare class CloudError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/** The cloud no longer knows this machine (its data was reset): registering again fixes it. */
+export declare const unknownMachine: (err: unknown) => boolean;
+export declare function cloudPost<T>(base: string, route: string, body: unknown, opts?: {
+    version?: string;
+    timeout?: number;
+}): Promise<T>;
+/** What register says about the machine besides its credentials. */
+export interface MachineHello {
+    name: string;
+    handle: string;
+    hostname: string;
+    platform: string;
+    version: string;
+}
+export declare const machineRegister: (base: string, creds: Credentials, hello: MachineHello, workspaces: MachineWorkspace[]) => Promise<RegisterResponse>;
+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

@@ -0,0 +1,98 @@
+import { randomBytes } from "node:crypto";
+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");
+/** The retired per-workspace identities (before machines): deleted at the daemon's start. */
+export const retiredCloudDir = () => path.join(kwHome(), "cloud");
+export async function readCloudFile() {
+    try {
+        const raw = JSON.parse(await fs.readFile(cloudFilePath(), "utf8"));
+        return {
+            ...(typeof raw.enabled === "boolean" ? { enabled: raw.enabled } : {}),
+            ...(typeof raw.url === "string" && raw.url ? { url: raw.url.replace(/\/+$/, "") } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/** Merge a change into cloud.json (a `url: undefined` leaves the URL as it is). */
+export async function writeCloudFile(change) {
+    const cur = await readCloudFile();
+    const next = { ...cur, ...(change.enabled !== undefined ? { enabled: change.enabled } : {}), ...(change.url ? { url: change.url.replace(/\/+$/, "") } : {}) };
+    const file = cloudFilePath();
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(next, null, 2) + "\n");
+    await fs.rename(tmp, file);
+    return next;
+}
+/** Whether the environment turned the cloud off for this process. */
+export const envCloudOff = () => process.env.KRAFTWERK_CLOUD_URL?.trim().toLowerCase() === "off";
+/**
+ * The machine's effective cloud. `ymlUrls`: `cloud.url` of open workspaces
+ * (deprecated) — used only when neither the environment nor cloud.json names
+ * an origin.
+ */
+export async function machineCloud(ymlUrls = []) {
+    const file = await readCloudFile();
+    const env = process.env.KRAFTWERK_CLOUD_URL?.trim();
+    const [url, source] = env && !envCloudOff() ? [env, "env"] : file.url ? [file.url, "cloud.json"] : ymlUrls[0] ? [ymlUrls[0], "kraftwerk.yml"] : [CLOUD_DEFAULT_URL, "default"];
+    const base = { url: url.replace(/\/+$/, ""), source };
+    if (envCloudOff())
+        return { ...base, enabled: false, reason: "KRAFTWERK_CLOUD_URL=off" };
+    if (file.enabled === false)
+        return { ...base, enabled: false, reason: "turned off for this machine (`kraftwerk cloud on` turns it on)" };
+    return { ...base, enabled: true };
+}
+export const claimUrlFor = (url, code) => (code ? `${url}/claim/${encodeURIComponent(code)}` : null);
+const REQUEST_TIMEOUT_MS = 8_000;
+export const GOODBYE_TIMEOUT_MS = 800;
+/** A refused or failed call; `status` is the HTTP status (0: no answer). */
+export class CloudError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+/** The cloud no longer knows this machine (its data was reset): registering again fixes it. */
+export const unknownMachine = (err) => err instanceof CloudError && (err.status === 404 || /unknown machine|not registered/i.test(err.message));
+export async function cloudPost(base, route, body, opts = {}) {
+    const url = `${base}${route}`;
+    let r;
+    try {
+        r = await fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json", "user-agent": `kraftwerk/${opts.version ?? "dev"}` },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(opts.timeout ?? REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        throw new CloudError(err.message, 0);
+    }
+    const text = await r.text();
+    let data;
+    try {
+        data = text ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new CloudError(`${r.status} from ${url}: not JSON`, r.status);
+    }
+    if (!r.ok)
+        throw new CloudError(data.error ?? `${r.status} from ${url}`, r.status);
+    return data;
+}
+export const machineRegister = (base, creds, hello, workspaces) => cloudPost(base, "/api/machines/register", { ...creds, ...hello, workspaces }, { version: hello.version });
+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 });