@netnodeag/kraftwerk 0.76.0 → 0.77.0

package/dist/core/cloud.d.ts

@@ -0,0 +1,115 @@
+/**
+ * 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?} → {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.
+ */
+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;
+}
+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[];
+}) => 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>;

package/dist/core/cloud.js

@@ -0,0 +1,94 @@
+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";
+// 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 });

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

@@ -0,0 +1,72 @@
+import * as z from "zod";
+/**
+ * The machine in the kraftwerk cloud (server/cloud.ts): its record, turning
+ * 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.
+ */
+export declare const cloudRoutes: (import("./router.js").Route<"cloud.set", {
+    daemon: boolean;
+    url: string;
+    state: import("../cloud.js").CloudState;
+    reason?: string;
+    source?: import("../../core/cloud.js").CloudUrlSource;
+    error?: string;
+    id?: string;
+    machine?: string;
+    account?: string | null;
+    interval?: number;
+    lastSeen?: string;
+    claimCode?: string | null;
+    claimUrl?: string | null;
+    workspaces?: number;
+}, "/api/cloud", z.ZodObject<{
+    enabled: z.ZodBoolean;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>> | import("./router.js").Route<"cloud.status", {
+    daemon: boolean;
+    url: string;
+    state: import("../cloud.js").CloudState;
+    reason?: string;
+    source?: import("../../core/cloud.js").CloudUrlSource;
+    error?: string;
+    id?: string;
+    machine?: string;
+    account?: string | null;
+    interval?: number;
+    lastSeen?: string;
+    claimCode?: string | null;
+    claimUrl?: string | null;
+    workspaces?: number;
+}, "/api/cloud", undefined> | import("./router.js").Route<"cloud.sync", {
+    daemon: boolean;
+    url: string;
+    state: import("../cloud.js").CloudState;
+    reason?: string;
+    source?: import("../../core/cloud.js").CloudUrlSource;
+    error?: string;
+    id?: string;
+    machine?: string;
+    account?: string | null;
+    interval?: number;
+    lastSeen?: string;
+    claimCode?: string | null;
+    claimUrl?: string | null;
+    workspaces?: number;
+}, "/api/cloud/sync", undefined> | import("./router.js").Route<"cloud.unlink", {
+    daemon: boolean;
+    url: string;
+    state: import("../cloud.js").CloudState;
+    reason?: string;
+    source?: import("../../core/cloud.js").CloudUrlSource;
+    error?: string;
+    id?: string;
+    machine?: string;
+    account?: string | null;
+    interval?: number;
+    lastSeen?: string;
+    claimCode?: string | null;
+    claimUrl?: string | null;
+    workspaces?: number;
+}, "/api/cloud/unlink", undefined>)[];

package/dist/server/api/cloud.js

@@ -0,0 +1,38 @@
+import * as z from "zod";
+import { writeCloudFile } from "../../core/cloud.js";
+import { applyMachineCloud, cloudStatus, syncMachineCloud, unlinkMachineCloud } from "../cloud.js";
+import { currentHub } from "../hub-context.js";
+import { route } from "./router.js";
+/**
+ * The machine in the kraftwerk cloud (server/cloud.ts): its record, turning
+ * 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.
+ */
+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 () => ({
+        daemon: currentHub().daemon === true,
+        ...cloudStatus(),
+    })),
+    route({
+        name: "cloud.set",
+        method: "POST",
+        path: "/api/cloud",
+        summary: "turn the machine's cloud on or off {enabled, url?} (~/.kraftwerk/cloud.json); off says goodbye",
+        access: "local",
+        body: z.object({ enabled: z.boolean(), url: z.string().url().optional() }),
+    }, async (c) => {
+        const { enabled, url } = await c.body();
+        await writeCloudFile({ enabled, url });
+        return { daemon: currentHub().daemon === true, ...(await applyMachineCloud()) };
+    }),
+    route({ name: "cloud.sync", method: "POST", path: "/api/cloud/sync", summary: "register or heartbeat now; answers the record (a claim made in the cloud shows here)", access: "local" }, async () => ({
+        daemon: currentHub().daemon === true,
+        ...(await syncMachineCloud()),
+    })),
+    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

@@ -16,16 +16,16 @@ export declare const deviceRoutes: (import("./router.js").Route<"devices.code",
     code: z.ZodString;
     name: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>> | import("./router.js").Route<"devices.relay", {
+    enabled: boolean;
+    url: string | null;
+    fingerprint: string | null;
+    daemon: boolean;
     state: import("../relay.js").RelayState;
     id?: string;
     key?: string;
     error?: string;
     clients: number;
     since?: string;
-    enabled: boolean;
-    url: string | null;
-    fingerprint: string | null;
-    daemon: boolean;
 }, "/api/devices/relay", undefined> | import("./router.js").Route<"devices.revoke", {
     ok: boolean;
 }, "/api/devices/:id", undefined> | import("./router.js").Route<"devices.self", {
@@ -41,16 +41,16 @@ export declare const deviceRoutes: (import("./router.js").Route<"devices.code",
     }>;
     key: z.ZodString;
 }, z.core.$strip>> | import("./router.js").Route<"devices.setRelay", {
+    enabled: boolean;
+    url: string;
+    fingerprint: string;
+    daemon: boolean;
     state: import("../relay.js").RelayState;
     id?: string;
     key?: string;
     error?: string;
     clients: number;
     since?: string;
-    enabled: boolean;
-    url: string;
-    fingerprint: string;
-    daemon: boolean;
 }, "/api/devices/relay", z.ZodObject<{
     enabled: z.ZodBoolean;
     url: z.ZodOptional<z.ZodString>;

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

@@ -291,7 +291,70 @@ 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<"devices.code", {
+}, z.core.$strip>> | Route<"cloud.set", {
+    daemon: boolean;
+    url: string;
+    state: import("../cloud.js").CloudState;
+    reason?: string;
+    source?: import("../../core/cloud.js").CloudUrlSource;
+    error?: string;
+    id?: string;
+    machine?: string;
+    account?: string | null;
+    interval?: number;
+    lastSeen?: string;
+    claimCode?: string | null;
+    claimUrl?: string | null;
+    workspaces?: number;
+}, "/api/cloud", z.ZodObject<{
+    enabled: z.ZodBoolean;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>> | Route<"cloud.status", {
+    daemon: boolean;
+    url: string;
+    state: import("../cloud.js").CloudState;
+    reason?: string;
+    source?: import("../../core/cloud.js").CloudUrlSource;
+    error?: string;
+    id?: string;
+    machine?: string;
+    account?: string | null;
+    interval?: number;
+    lastSeen?: string;
+    claimCode?: string | null;
+    claimUrl?: string | null;
+    workspaces?: number;
+}, "/api/cloud", undefined> | Route<"cloud.sync", {
+    daemon: boolean;
+    url: string;
+    state: import("../cloud.js").CloudState;
+    reason?: string;
+    source?: import("../../core/cloud.js").CloudUrlSource;
+    error?: string;
+    id?: string;
+    machine?: string;
+    account?: string | null;
+    interval?: number;
+    lastSeen?: string;
+    claimCode?: string | null;
+    claimUrl?: string | null;
+    workspaces?: number;
+}, "/api/cloud/sync", undefined> | Route<"cloud.unlink", {
+    daemon: boolean;
+    url: string;
+    state: import("../cloud.js").CloudState;
+    reason?: string;
+    source?: import("../../core/cloud.js").CloudUrlSource;
+    error?: string;
+    id?: string;
+    machine?: string;
+    account?: string | null;
+    interval?: number;
+    lastSeen?: string;
+    claimCode?: string | null;
+    claimUrl?: string | null;
+    workspaces?: number;
+}, "/api/cloud/unlink", undefined> | Route<"devices.code", {
     code: string;
     expiresAt: string;
     urls: string[];
@@ -307,16 +370,16 @@ export declare const routes: (Route<"agents.addJournal", {
     code: z.ZodString;
     name: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>> | Route<"devices.relay", {
+    enabled: boolean;
+    url: string | null;
+    fingerprint: string | null;
+    daemon: boolean;
     state: import("../relay.js").RelayState;
     id?: string;
     key?: string;
     error?: string;
     clients: number;
     since?: string;
-    enabled: boolean;
-    url: string | null;
-    fingerprint: string | null;
-    daemon: boolean;
 }, "/api/devices/relay", undefined> | Route<"devices.revoke", {
     ok: boolean;
 }, "/api/devices/:id", undefined> | Route<"devices.self", {
@@ -332,16 +395,16 @@ export declare const routes: (Route<"agents.addJournal", {
     }>;
     key: z.ZodString;
 }, z.core.$strip>> | Route<"devices.setRelay", {
+    enabled: boolean;
+    url: string;
+    fingerprint: string;
+    daemon: boolean;
     state: import("../relay.js").RelayState;
     id?: string;
     key?: string;
     error?: string;
     clients: number;
     since?: string;
-    enabled: boolean;
-    url: string;
-    fingerprint: string;
-    daemon: boolean;
 }, "/api/devices/relay", z.ZodObject<{
     enabled: z.ZodBoolean;
     url: z.ZodOptional<z.ZodString>;
@@ -439,7 +502,22 @@ export declare const routes: (Route<"agents.addJournal", {
     vibeables: boolean;
     projects: boolean;
     publicUrl: string;
-    cloud: import("../cloud.js").CloudStatus;
+    cloud: {
+        included: boolean;
+        url: string;
+        state: import("../cloud.js").CloudState;
+        reason?: string;
+        source?: import("../../core/cloud.js").CloudUrlSource;
+        error?: string;
+        id?: string;
+        machine?: string;
+        account?: string | null;
+        interval?: number;
+        lastSeen?: string;
+        claimCode?: string | null;
+        claimUrl?: string | null;
+        workspaces?: number;
+    };
     switcher: import("../../config.js").SwitcherEntry[];
 }, "/api/meta", undefined> | Route<"notifications.clear", {
     ok: boolean;

package/dist/server/api/index.js

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

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

@@ -35,7 +35,22 @@ export declare const workspaceRoutes: (import("./router.js").Route<"identity.get
     projects: boolean;
     /** @deprecated Always "": the Cloudflare Tunnel that set it was removed in 0.65. Removed with protocol 2. */
     publicUrl: string;
-    cloud: import("../cloud.js").CloudStatus;
+    cloud: {
+        included: boolean;
+        url: string;
+        state: import("../cloud.js").CloudState;
+        reason?: string;
+        source?: import("../../core/cloud.js").CloudUrlSource;
+        error?: string;
+        id?: string;
+        machine?: string;
+        account?: string | null;
+        interval?: number;
+        lastSeen?: string;
+        claimCode?: string | null;
+        claimUrl?: string | null;
+        workspaces?: number;
+    };
     switcher: import("../../config.js").SwitcherEntry[];
 }, "/api/meta", undefined> | import("./router.js").Route<"search.agents", {
     workspaces: (import("../../core/search.js").WorkspaceAgents & {

package/dist/server/api/workspace.js

@@ -105,7 +105,8 @@ export const workspaceRoutes = [
             projects: (ws?.config.projects && ws.config.projects.enabled !== false) === true,
             /** @deprecated Always "": the Cloudflare Tunnel that set it was removed in 0.65. Removed with protocol 2. */
             publicUrl: "",
-            cloud: cloudStatus(),
+            // The machine's cloud record (only the daemon registers one); `included`: this workspace rides along (no cloud.enabled: false veto).
+            cloud: { ...cloudStatus(), included: ws?.config.cloud?.enabled !== false },
             switcher,
         };
     }),