@netnodeag/kraftwerk 0.75.1 → 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/core/identity.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Who and where this kraftwerk is: ~/.kraftwerk/identity.json, one per
+ * machine (every workspace here shares it).
+ *
+ *   { "handle": "lukas", "machine": "mbp", "previous": ["lukas@old-name"] }
+ *
+ * The identity string is `handle@machine`. A workspace is git-shared, its
+ * run state is not, so a routine names the one identity that fires it
+ * (`runs_on:` in routines.yml) — without that every clone would fire it.
+ *
+ * Defaults come from the OS (user name, host name without its domain) and
+ * are written the first time they are read: macOS changes the host name
+ * with the network, and an identity that drifts with it would silently stop
+ * every routine assigned to this machine. Renaming appends the retired pair
+ * to `previous`, so routines that still name it can be found and healed.
+ */
+export interface Identity {
+    handle: string;
+    machine: string;
+    /** Retired `handle@machine` pairs, oldest first. */
+    previous: string[];
+}
+/** One half of an identity: lowercase, no "@". */
+export declare const IDENTITY_PART_RE: RegExp;
+/** The OS user name. */
+export declare function defaultHandle(): string;
+/** The host name, lowercased, without `.local` or a domain; anything outside [a-z0-9-] becomes "-". */
+export declare function defaultMachine(hostname?: string): string;
+/** Why a handle or machine name is refused, or undefined when it is fine. */
+export declare function identityPartError(label: "handle" | "machine", value: string): string | undefined;
+/** `handle@machine` with both halves well-formed: what `runs_on:` must look like. */
+export declare function isIdentityString(value: string): boolean;
+export declare const identityString: (id: Pick<Identity, "handle" | "machine">) => string;
+/**
+ * This machine's identity. A missing file gets the OS defaults, written so
+ * they stay put; a damaged field falls back to its default without being
+ * written over (a person may be halfway through editing the file).
+ */
+export declare function readIdentity(): Promise<Identity>;
+/** This machine's `handle@machine`. */
+export declare function localIdentity(): Promise<string>;
+/** Change the handle and/or machine name; the pair it replaces goes to `previous`. */
+export declare function setIdentity(change: {
+    handle?: string;
+    machine?: string;
+}): Promise<Identity>;

package/dist/core/identity.js

@@ -0,0 +1,106 @@
+import { randomBytes } from "node:crypto";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** One half of an identity: lowercase, no "@". */
+export const IDENTITY_PART_RE = /^[a-z0-9._-]+$/;
+/** How many retired pairs are kept. */
+const MAX_PREVIOUS = 10;
+// Resolved on every use, not at import: a test swaps HOME after some module already imported this one.
+const identityFile = () => path.join(os.homedir(), ".kraftwerk", "identity.json");
+/** A free-form name as an identity half: lowercase, anything outside [a-z0-9._-] becomes "-". */
+function sanitize(raw, fallback) {
+    const s = raw
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/-{2,}/g, "-")
+        .replace(/^[-.]+|[-.]+$/g, "");
+    return s || fallback;
+}
+/** The OS user name. */
+export function defaultHandle() {
+    let name = "";
+    try {
+        name = os.userInfo().username;
+    }
+    catch {
+        name = process.env.USER ?? process.env.USERNAME ?? "";
+    }
+    return sanitize(name, "user");
+}
+/** The host name, lowercased, without `.local` or a domain; anything outside [a-z0-9-] becomes "-". */
+export function defaultMachine(hostname = os.hostname()) {
+    const host = hostname.toLowerCase().split(".")[0] ?? "";
+    const s = host.replace(/[^a-z0-9-]+/g, "-").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "");
+    return s || "machine";
+}
+/** Why a handle or machine name is refused, or undefined when it is fine. */
+export function identityPartError(label, value) {
+    if (!value)
+        return `${label} must not be empty`;
+    if (value.includes("@"))
+        return `${label} must not contain "@" (the identity is handle@machine)`;
+    if (!IDENTITY_PART_RE.test(value))
+        return `${label} must be lowercase letters, digits, ".", "_" or "-"`;
+    return undefined;
+}
+/** `handle@machine` with both halves well-formed: what `runs_on:` must look like. */
+export function isIdentityString(value) {
+    const parts = value.split("@");
+    return parts.length === 2 && IDENTITY_PART_RE.test(parts[0]) && IDENTITY_PART_RE.test(parts[1]);
+}
+export const identityString = (id) => `${id.handle}@${id.machine}`;
+async function write(id) {
+    const file = identityFile();
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    // A temp name per write: two writers in flight must not rename each other's file.
+    const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(id, null, 2) + "\n");
+    await fs.rename(tmp, file);
+}
+/**
+ * This machine's identity. A missing file gets the OS defaults, written so
+ * they stay put; a damaged field falls back to its default without being
+ * written over (a person may be halfway through editing the file).
+ */
+export async function readIdentity() {
+    let raw = null;
+    try {
+        raw = JSON.parse(await fs.readFile(identityFile(), "utf8"));
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            raw = {};
+    }
+    const handle = typeof raw?.handle === "string" && !identityPartError("handle", raw.handle) ? raw.handle : defaultHandle();
+    const machine = typeof raw?.machine === "string" && !identityPartError("machine", raw.machine) ? raw.machine : defaultMachine();
+    const previous = Array.isArray(raw?.previous) ? raw.previous.filter((p) => typeof p === "string" && isIdentityString(p)) : [];
+    const id = { handle, machine, previous };
+    if (raw === null)
+        await write(id).catch(() => { });
+    return id;
+}
+/** This machine's `handle@machine`. */
+export async function localIdentity() {
+    return identityString(await readIdentity());
+}
+/** Change the handle and/or machine name; the pair it replaces goes to `previous`. */
+export async function setIdentity(change) {
+    for (const label of ["handle", "machine"]) {
+        const v = change[label];
+        if (v === undefined)
+            continue;
+        const err = identityPartError(label, v);
+        if (err)
+            throw new Error(err);
+    }
+    const cur = await readIdentity();
+    const next = { handle: change.handle ?? cur.handle, machine: change.machine ?? cur.machine, previous: cur.previous };
+    const before = identityString(cur);
+    const after = identityString(next);
+    if (before !== after) {
+        next.previous = [...cur.previous.filter((p) => p !== before && p !== after), before].slice(-MAX_PREVIOUS);
+    }
+    await write(next);
+    return next;
+}

package/dist/core/routines.d.ts

@@ -10,6 +10,15 @@
  * session (chat) for the agent and posts the prompt — the run shows up in
  * the agent's sessions sidebar like any conversation. Schedules use
  * standard 5-field cron in the server's local time.
+ *
+ * The definitions travel with the workspace's git, the state does not, so a
+ * workspace cloned on three machines would fire every routine three times.
+ * Each routine therefore names its runner, `runs_on: <handle>@<machine>`
+ * (see identity.ts), and the scheduler is strict: a routine fires only where
+ * 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.
  */
 export interface Routine {
     id: string;
@@ -18,8 +27,21 @@ export interface Routine {
     schedule: string;
     prompt: string;
     enabled: boolean;
+    /** The one identity (`handle@machine`) that fires it. Absent: unassigned, fires nowhere. */
+    runsOn?: string;
+    /** Stored as given; no behaviour yet. */
+    private?: boolean;
 }
+/**
+ * Who fires a routine, seen from this machine: here, on another identity,
+ * or nobody (no runs_on).
+ */
+export type RoutineRunner = "here" | "elsewhere" | "unassigned";
 export interface RoutineStatus extends Routine {
+    runner: RoutineRunner;
+    /** runs_on names an identity this machine had before (identity.json `previous`): a rename left it behind. */
+    retired?: boolean;
+    /** Only for an enabled routine that fires here. */
     nextRunAt?: string;
     lastRunAt?: string;
     lastChatId?: string;
@@ -46,6 +68,9 @@ export interface SaveRoutineInput {
     schedule: string;
     prompt: string;
     enabled?: boolean;
+    /** Absent: kept as it is (a new routine gets this machine's identity). null or "": unassigned. */
+    runsOn?: string | null;
+    private?: boolean;
 }
 export declare function saveRoutine(slug: string, input: SaveRoutineInput): Promise<Routine>;
 export declare function deleteRoutine(slug: string, id: string): Promise<void>;
@@ -70,10 +95,66 @@ export declare function allRoutines(workflows: {
     };
     workflows: string[];
 })[]>;
+/** Whether a routine fires on the machine whose identity is `me`: enabled and runs_on exactly that. */
+export declare const firesHere: (r: Routine, me: string) => boolean;
 export declare function routineStatuses(slug: string): Promise<RoutineStatus[]>;
 export declare function runRoutineNow(slug: string, id: string): Promise<{
     chatId: string;
 }>;
+/**
+ * The routines due at `now` that fire on this machine: enabled, runs_on
+ * exactly this identity, cron matching. Everything else — unassigned,
+ * another machine's, a retired identity's — is never due here.
+ */
+export declare function dueRoutines(now: Date, me?: string): Promise<{
+    slug: string;
+    routine: Routine;
+}[]>;
+export interface RunnerRef {
+    agent: string;
+    id: string;
+    name: string;
+    /** What runs_on said before (absent: unassigned). */
+    from?: string;
+}
+export interface RunnerFindings {
+    /** Enabled routines without runs_on: they fire nowhere. */
+    unassigned: RunnerRef[];
+    /** Routines whose runs_on is one of this machine's retired identities. */
+    retired: RunnerRef[];
+    /** Newest change to a routines.yml involved, ISO (the attention item's "since"). */
+    since?: string;
+}
+/** Every routine in the workspace that has no runner, or names a retired identity of this machine. */
+export declare function runnerFindings(): Promise<RunnerFindings>;
+export interface AdoptResult {
+    /** This machine's identity, now the runner of every routine listed. */
+    runsOn: string;
+    adopted: RunnerRef[];
+    /** routines.yml files written, relative to the workspace root. */
+    files: string[];
+    /** The git commit of those files; null when nothing changed. Not ok: written, but not committed (why in `error`). */
+    commit: {
+        ok: boolean;
+        error?: string;
+        committed?: number;
+    } | null;
+}
+/**
+ * "Run these here": make this machine the runner of the routines `pick`
+ * selects, write routines.yml and commit just the files it touched — the
+ * commit is what tells the other clones who runs them. A workspace without
+ * git sync, or a commit that fails, keeps the written files and says why.
+ */
+export declare function adoptRoutines(pick: (agent: string, r: Routine, previous: string[]) => boolean, message?: string): Promise<AdoptResult>;
+/** Adopt one routine (whatever its runs_on said). */
+export declare function adoptRoutine(slug: string, id: string): Promise<AdoptResult & {
+    routine: RoutineStatus;
+}>;
+/** Adopt every enabled routine without runs_on — and, with `retired`, every one naming a retired identity of this machine. */
+export declare function adoptUnassigned(opts?: {
+    retired?: boolean;
+}): Promise<AdoptResult>;
 /** Start the current workspace's scheduler; safe to call more than once. Ticks run in that workspace. */
 export declare function startRoutineScheduler(): void;
 /** Stop the current workspace's scheduler (the workspace closes): no routine of it fires any more. */