@netnodeag/kraftwerk 0.71.0 → 0.72.0

package/README.md

@@ -452,6 +452,13 @@ Everything between the phone and the machine is end to end encrypted:
 - One trust remains: the remote page's code comes from the cloud that serves
   it. A native app will remove that.
 
+**Push notifications.** The kraftwerk iOS app gets a notification when
+something new needs you: an approval, a question from an agent, a failed run
+or routine. Each paired phone gives the machine a key of its own, and the
+machine seals every notification with it. The relay and Apple pass along only
+"Something needs you" and the badge count. The app opens the sealed text on
+the phone. Turning notifications off on the phone, or unpairing it, stops them.
+
 The machine's key and its relay secret live in `~/.kraftwerk/relay.json`
 (owner only). The daemon must run (`kraftwerk daemon install`), and the Mac
 must be awake.

package/dist/cli/daemon.js

@@ -2,7 +2,8 @@ import chalk from "chalk";
 import { DAEMON_PORT, findDaemon, lastOpenRoots, writeDaemonFile } from "../core/daemon.js";
 import { tildify } from "../core/instances.js";
 import { networkUrls } from "../server/bind.js";
-import { applyRelay } from "../server/relay.js";
+import { startPushWatcher } from "../server/push.js";
+import { applyRelay, relayPush } from "../server/relay.js";
 import { startHub } from "../server/server.js";
 import { getPkgVersion } from "../server/version.js";
 import { ensureBuilt, supervise } from "./ui.js";
@@ -49,6 +50,8 @@ export async function runDaemon(opts) {
         console.log(chalk.dim("  no workspace open yet — `kraftwerk ui` in a workspace folder opens it here"));
     // The relay (`kraftwerk remote on`): devices reach this machine from anywhere, end to end encrypted.
     const relay = await applyRelay(hub.port, await getPkgVersion(), (line) => console.log(chalk.dim(line)));
+    // What needs you, pushed to the phones that asked (through the relay, sealed per device).
+    startPushWatcher(hub, relayPush);
     if (relay.state !== "off")
         console.log(`${chalk.green("✔")} Reachable from anywhere through ${chalk.cyan(relay.url ?? "")} ${chalk.dim("(`kraftwerk remote pair` pairs a device)")}`);
     const lan = networkUrls(hub.port);

package/dist/client/relay.js

@@ -158,8 +158,9 @@ const OPEN = 1;
 export async function connectTunnel(opts) {
     const id = await relayId(opts.publicKey);
     const url = `${opts.relayUrl}${opts.relayUrl.includes("?") ? "&" : "?"}id=${encodeURIComponent(id)}`;
-    const ws = opts.connect ? opts.connect(url) : new WebSocket(url);
+    // The keys first: once the socket exists, its events may fire at any await — the listeners below must already be there.
     const hs = await clientHandshake(opts.publicKey);
+    const ws = opts.connect ? opts.connect(url) : new WebSocket(url);
     let channel = null;
     let closedWhy = "";
     let resolveClosed;

package/dist/client/routes.d.ts

@@ -44,11 +44,13 @@ export declare const ROUTES: {
     readonly "chats.steer": readonly ["POST", "/api/chats/:id/steer"];
     readonly "chats.stopTask": readonly ["POST", "/api/chats/:id/task-stop"];
     readonly "devices.code": readonly ["POST", "/api/devices/code"];
+    readonly "devices.dropPush": readonly ["DELETE", "/api/devices/push"];
     readonly "devices.list": readonly ["GET", "/api/devices"];
     readonly "devices.pair": readonly ["POST", "/api/pair"];
     readonly "devices.relay": readonly ["GET", "/api/devices/relay"];
     readonly "devices.revoke": readonly ["DELETE", "/api/devices/:id"];
     readonly "devices.self": readonly ["GET", "/api/devices/self"];
+    readonly "devices.setPush": readonly ["POST", "/api/devices/push"];
     readonly "devices.setRelay": readonly ["POST", "/api/devices/relay"];
     readonly "files.delete": readonly ["DELETE", "/api/files"];
     readonly "files.list": readonly ["GET", "/api/files/list"];

package/dist/client/routes.js

@@ -45,11 +45,13 @@ export const ROUTES = {
     "chats.steer": ["POST", "/api/chats/:id/steer"],
     "chats.stopTask": ["POST", "/api/chats/:id/task-stop"],
     "devices.code": ["POST", "/api/devices/code"],
+    "devices.dropPush": ["DELETE", "/api/devices/push"],
     "devices.list": ["GET", "/api/devices"],
     "devices.pair": ["POST", "/api/pair"],
     "devices.relay": ["GET", "/api/devices/relay"],
     "devices.revoke": ["DELETE", "/api/devices/:id"],
     "devices.self": ["GET", "/api/devices/self"],
+    "devices.setPush": ["POST", "/api/devices/push"],
     "devices.setRelay": ["POST", "/api/devices/relay"],
     "files.delete": ["DELETE", "/api/files"],
     "files.list": ["GET", "/api/files/list"],

package/dist/core/devices.d.ts

@@ -15,6 +15,18 @@ export interface Device {
     name: string;
     createdAt: string;
     lastSeenAt?: string;
+    /** Whether the device gets push notifications (its app registered for them). */
+    push?: boolean;
+}
+/**
+ * Where a device's push notifications go: its APNs token and environment, and
+ * the key (32 bytes, base64) the device made for this machine — what is pushed
+ * is sealed with it, so the relay and Apple carry it without reading it.
+ */
+export interface PushTarget {
+    token: string;
+    environment: "sandbox" | "production";
+    key: string;
 }
 /** How long a pairing code works. */
 export declare const PAIR_CODE_TTL_MS: number;
@@ -33,3 +45,12 @@ export declare function deviceForToken(token: string): Promise<Device | null>;
 export declare function listDevices(): Promise<Device[]>;
 /** Unpair a device: its token stops working at once. */
 export declare function revokeDevice(id: string): Promise<boolean>;
+/** Register (or, with null, drop) where a device's push notifications go. */
+export declare function setDevicePush(id: string, target: PushTarget | null): Promise<boolean>;
+/** Every device that gets push notifications, with where they go. */
+export declare function pushTargets(): Promise<Array<{
+    id: string;
+    name: string;
+} & PushTarget>>;
+/** Apple says a token is gone (the app was deleted): stop pushing to it. */
+export declare function dropPushToken(token: string): Promise<void>;

package/dist/core/devices.js

@@ -88,7 +88,7 @@ function update(change) {
     chain = run.catch(() => { });
     return run;
 }
-const view = ({ tokenHash: _h, ...d }) => d;
+const view = ({ tokenHash: _h, pushTarget, ...d }) => ({ ...d, ...(pushTarget ? { push: true } : {}) });
 /** A new one-time pairing code, valid for PAIR_CODE_TTL_MS. Shown once; the store keeps its hash. */
 export async function createPairCode() {
     let code = "";
@@ -154,3 +154,28 @@ export async function revokeDevice(id) {
         return store.devices.length < before;
     });
 }
+/** Register (or, with null, drop) where a device's push notifications go. */
+export async function setDevicePush(id, target) {
+    return update((store) => {
+        const d = store.devices.find((x) => x.id === id);
+        if (!d)
+            return false;
+        if (target)
+            d.pushTarget = target;
+        else
+            delete d.pushTarget;
+        return true;
+    });
+}
+/** Every device that gets push notifications, with where they go. */
+export async function pushTargets() {
+    return (await read()).devices.filter((d) => d.pushTarget).map((d) => ({ id: d.id, name: d.name, ...d.pushTarget }));
+}
+/** Apple says a token is gone (the app was deleted): stop pushing to it. */
+export async function dropPushToken(token) {
+    await update((store) => {
+        for (const d of store.devices)
+            if (d.pushTarget?.token === token)
+                delete d.pushTarget;
+    });
+}

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

@@ -5,7 +5,9 @@ export declare const deviceRoutes: (import("./router.js").Route<"devices.code",
     expiresAt: string;
     urls: string[];
     remote?: string | undefined;
-}, "/api/devices/code", undefined> | import("./router.js").Route<"devices.list", {
+}, "/api/devices/code", undefined> | import("./router.js").Route<"devices.dropPush", {
+    ok: boolean;
+}, "/api/devices/push", undefined> | import("./router.js").Route<"devices.list", {
     devices: import("../../core/devices.js").Device[];
 }, "/api/devices", undefined> | import("./router.js").Route<"devices.pair", import("./router.js").Reply<{
     token: string;
@@ -29,7 +31,16 @@ export declare const deviceRoutes: (import("./router.js").Route<"devices.code",
 }, "/api/devices/:id", undefined> | import("./router.js").Route<"devices.self", {
     trust: "device" | "local" | "none";
     device?: import("../../core/devices.js").Device | undefined;
-}, "/api/devices/self", undefined> | import("./router.js").Route<"devices.setRelay", {
+}, "/api/devices/self", undefined> | import("./router.js").Route<"devices.setPush", {
+    ok: boolean;
+}, "/api/devices/push", z.ZodObject<{
+    token: z.ZodString;
+    environment: z.ZodEnum<{
+        production: "production";
+        sandbox: "sandbox";
+    }>;
+    key: z.ZodString;
+}, z.core.$strip>> | import("./router.js").Route<"devices.setRelay", {
     state: import("../relay.js").RelayState;
     id?: string;
     key?: string;

package/dist/server/api/devices.js

@@ -1,5 +1,5 @@
 import * as z from "zod";
-import { createPairCode, listDevices, redeemPairCode, revokeDevice } from "../../core/devices.js";
+import { createPairCode, listDevices, redeemPairCode, revokeDevice, setDevicePush } from "../../core/devices.js";
 import { networkUrls } from "../bind.js";
 import { currentHub } from "../hub-context.js";
 import { applyRelay, keyFingerprint, readRelaySettings, relayStatus, remoteLink, setRelay } from "../relay.js";
@@ -48,6 +48,31 @@ export const deviceRoutes = [
         trust: c.trust.kind,
         ...(c.trust.kind === "device" ? { device: c.trust.device } : {}),
     })),
+    // A paired device's app says where its push notifications go (and the key it seals them with); see server/push.ts.
+    route({
+        name: "devices.setPush",
+        method: "POST",
+        path: "/api/devices/push",
+        summary: "this device's push notifications {token, environment, key}",
+        errors: 400,
+        body: z.object({
+            token: z.string().regex(/^[0-9a-fA-F]{32,200}$/),
+            environment: z.enum(["sandbox", "production"]),
+            key: z.string().regex(/^[A-Za-z0-9+/]{43}=$/),
+        }),
+    }, async (c) => {
+        if (c.trust.kind !== "device")
+            fail(400, "only a paired device gets push notifications");
+        const { token, environment, key } = await c.body();
+        await setDevicePush(c.trust.device.id, { token: token.toLowerCase(), environment, key });
+        return { ok: true };
+    }),
+    route({ name: "devices.dropPush", method: "DELETE", path: "/api/devices/push", summary: "no more push notifications for this device", errors: 400 }, async (c) => {
+        if (c.trust.kind !== "device")
+            fail(400, "only a paired device gets push notifications");
+        await setDevicePush(c.trust.device.id, null);
+        return { ok: true };
+    }),
     route({ name: "devices.list", method: "GET", path: "/api/devices", summary: "every paired device", access: "local" }, async () => ({ devices: await listDevices() })),
     // The code is shown once; the addresses are where a device on the network opens kraftwerk (none while bound to this machine only),
     // and with the relay on, `remote` is the link that pairs a device from anywhere (code and machine key in its fragment).

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

@@ -289,7 +289,9 @@ export declare const routes: (Route<"agents.addJournal", {
     expiresAt: string;
     urls: string[];
     remote?: string | undefined;
-}, "/api/devices/code", undefined> | Route<"devices.list", {
+}, "/api/devices/code", undefined> | Route<"devices.dropPush", {
+    ok: boolean;
+}, "/api/devices/push", undefined> | Route<"devices.list", {
     devices: import("../../core/devices.js").Device[];
 }, "/api/devices", undefined> | Route<"devices.pair", import("./router.js").Reply<{
     token: string;
@@ -313,7 +315,16 @@ export declare const routes: (Route<"agents.addJournal", {
 }, "/api/devices/:id", undefined> | Route<"devices.self", {
     trust: "device" | "local" | "none";
     device?: import("../../core/devices.js").Device | undefined;
-}, "/api/devices/self", undefined> | Route<"devices.setRelay", {
+}, "/api/devices/self", undefined> | Route<"devices.setPush", {
+    ok: boolean;
+}, "/api/devices/push", z.ZodObject<{
+    token: z.ZodString;
+    environment: z.ZodEnum<{
+        production: "production";
+        sandbox: "sandbox";
+    }>;
+    key: z.ZodString;
+}, z.core.$strip>> | Route<"devices.setRelay", {
     state: import("../relay.js").RelayState;
     id?: string;
     key?: string;

package/dist/server/push.d.ts

@@ -0,0 +1,52 @@
+import { type AttentionItem } from "../core/attention.js";
+import type { Hub } from "./server.js";
+/**
+ * Push notifications for what needs you: the daemon looks at every open
+ * workspace's attention list (approvals, questions, failures) and, for each
+ * item that is new, sends every device that asked for pushes a notification
+ * through the relay — sealed with the key that device made for this machine
+ * (AES-256-GCM), so the relay and Apple carry it without reading it. On the
+ * phone, the app's notification extension opens it and shows the text; what
+ * travels in the clear is only "something needs you" and the badge count.
+ *
+ *   → relay  {t:"push", pushes:[{token, environment, sealed, badge, thread}]}
+ *   ← relay  {t:"push_invalid", token}     Apple says the token is gone
+ *
+ * Items present when the daemon starts are not pushed (a restart must not
+ * ring every phone); a resolved item that comes back is new again.
+ */
+/** What a notification says, before it is sealed. The phone reads these names. */
+export interface PushContent {
+    title: string;
+    body: string;
+    subtitle?: string;
+    /** The workspace (slug) and the chat to open on tap. */
+    ws: string;
+    chat?: string;
+    kind: AttentionItem["kind"];
+}
+export interface PushMessage {
+    token: string;
+    environment: "sandbox" | "production";
+    /** base64(nonce ‖ ciphertext ‖ tag) of the JSON PushContent. */
+    sealed: string;
+    badge: number;
+    /** Groups a workspace's notifications on the phone. */
+    thread: string;
+}
+/** Seal a notification's content with a device's key (base64, 32 bytes). */
+export declare function sealPush(keyBase64: string, content: PushContent): string;
+export declare function contentOf(item: AttentionItem, workspace: {
+    slug: string;
+    name: string;
+}): PushContent;
+export interface PushWatcher {
+    /** Look now (tests; the timer does it every `everyMs`). */
+    scan(): Promise<number>;
+    stop(): void;
+}
+/**
+ * Watch the hub's workspaces and hand each new item's notifications to `send`
+ * (the relay link); returns how many were sent per scan.
+ */
+export declare function startPushWatcher(hub: Hub, send: (pushes: PushMessage[]) => boolean, everyMs?: number): PushWatcher;

package/dist/server/push.js

@@ -0,0 +1,67 @@
+import { createCipheriv, randomBytes } from "node:crypto";
+import { listAttention } from "../core/attention.js";
+import { pushTargets } from "../core/devices.js";
+/** Seal a notification's content with a device's key (base64, 32 bytes). */
+export function sealPush(keyBase64, content) {
+    const key = Buffer.from(keyBase64, "base64");
+    if (key.length !== 32)
+        throw new Error("a push key is 32 bytes");
+    const nonce = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key, nonce);
+    const ct = Buffer.concat([cipher.update(JSON.stringify(content), "utf8"), cipher.final()]);
+    return Buffer.concat([nonce, ct, cipher.getAuthTag()]).toString("base64");
+}
+const LABEL = { approval: "Approval", question: "Question", failed: "Failed" };
+export function contentOf(item, workspace) {
+    return {
+        title: `${LABEL[item.kind] ?? "Needs you"} · ${workspace.name}`,
+        body: item.title,
+        ...(item.chatTitle ? { subtitle: item.chatTitle } : {}),
+        ws: workspace.slug,
+        ...(item.chatId ? { chat: item.chatId } : {}),
+        kind: item.kind,
+    };
+}
+/**
+ * Watch the hub's workspaces and hand each new item's notifications to `send`
+ * (the relay link); returns how many were sent per scan.
+ */
+export function startPushWatcher(hub, send, everyMs = 10_000) {
+    let seen = null;
+    let running = false;
+    const scan = async () => {
+        if (running)
+            return 0;
+        running = true;
+        try {
+            const now = new Map();
+            for (const open of hub.list()) {
+                const view = await open.ws.run(() => listAttention()).catch(() => null);
+                for (const item of view?.items ?? [])
+                    now.set(`${open.slug}\n${item.id}`, { item, ws: { slug: open.slug, name: open.name } });
+            }
+            const first = seen === null;
+            const fresh = first ? [] : [...now.entries()].filter(([k]) => !seen.has(k)).map(([, v]) => v);
+            seen = new Set(now.keys());
+            if (!fresh.length)
+                return 0;
+            const targets = await pushTargets();
+            if (!targets.length)
+                return 0;
+            const pushes = [];
+            for (const { item, ws } of fresh) {
+                const content = contentOf(item, ws);
+                for (const t of targets) {
+                    pushes.push({ token: t.token, environment: t.environment, sealed: sealPush(t.key, content), badge: now.size, thread: ws.slug });
+                }
+            }
+            return send(pushes) ? pushes.length : 0;
+        }
+        finally {
+            running = false;
+        }
+    };
+    const timer = setInterval(() => void scan().catch(() => { }), everyMs);
+    timer.unref?.();
+    return { scan, stop: () => clearInterval(timer) };
+}

package/dist/server/relay.d.ts

@@ -1,3 +1,4 @@
+import type { PushMessage } from "./push.js";
 /**
  * The daemon's end of the relay (see src/client/relay.ts for the protocol):
  * an outgoing socket to the relay, one encrypted channel per client behind
@@ -53,6 +54,8 @@ export declare const relayEndpoint: (cloudUrl: string, role: "server" | "client"
 export declare function remoteLink(cloudUrl: string, key: string, code?: string, remoteUrl?: string | undefined): string;
 export interface RelayLink {
     status(): RelayStatus;
+    /** Hand push notifications to the relay (server/push.ts); false while not connected. */
+    push(pushes: PushMessage[]): boolean;
     stop(): void;
 }
 export interface RelayOptions {
@@ -62,6 +65,8 @@ export interface RelayOptions {
     version: string;
     /** Opens the relay socket (default: Node's global WebSocket) — tests pass their own. */
     connect?: (url: string) => WebSocket;
+    /** Give up on a connection the relay has not accepted (`ok`) within this long, and try again (default 15 s). */
+    handshakeTimeoutMs?: number;
     log?: (line: string) => void;
 }
 /** Hold the daemon's socket to the relay, reconnecting with backoff, and answer every client behind it. */
@@ -70,6 +75,8 @@ export declare function startRelay(opts: RelayOptions): Promise<RelayLink>;
 export declare const keyFingerprint: (key: string) => string;
 /** Start, restart or stop this daemon's relay link to match ~/.kraftwerk/relay.json. */
 export declare function applyRelay(port: number, version: string, log?: (line: string) => void): Promise<RelayStatus>;
+/** Hand push notifications to this daemon's relay link; false without one. */
+export declare const relayPush: (pushes: PushMessage[]) => boolean;
 /** The link's state; "off" when this process holds none (not the daemon, or the relay is off). */
 export declare const relayStatus: () => RelayStatus;
 export declare function stopRelay(): void;

package/dist/server/relay.js

@@ -5,6 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import { daemonHandshake, exportKeyPair, generateKeyPair, importKeyPair, relayId, toBase64, fromBase64, } from "../client/relay.js";
 import { CLOUD_DEFAULT_URL } from "../config.js";
+import { dropPushToken } from "../core/devices.js";
 const settingsFile = () => path.join(os.homedir(), ".kraftwerk", "relay.json");
 export async function readRelaySettings() {
     try {
@@ -189,6 +190,22 @@ export async function startRelay(opts) {
             return schedule();
         }
         ws = socket;
+        // A relay that restarts can leave a new socket hanging half-open, neither opening nor
+        // closing: without this, the link would wait for it forever.
+        const handshake = setTimeout(() => {
+            if (ws !== socket || status.state === "connected")
+                return;
+            ws = null;
+            try {
+                socket.close();
+            }
+            catch { }
+            status.state = "error";
+            status.error = "the relay did not answer";
+            log("relay: no answer from the relay — trying again");
+            schedule();
+        }, opts.handshakeTimeoutMs ?? 15_000);
+        handshake.unref?.();
         socket.addEventListener("open", () => {
             lastHeard = Date.now();
             socket.send(JSON.stringify({ t: "auth", id, key: opts.settings.publicKey, secret: opts.settings.secret, version: opts.version }));
@@ -203,6 +220,7 @@ export async function startRelay(opts) {
                 return;
             }
             if (msg.t === "ok") {
+                clearTimeout(handshake);
                 attempt = 0;
                 status.state = "connected";
                 status.error = undefined;
@@ -224,8 +242,13 @@ export async function startRelay(opts) {
             }
             else if (msg.t === "close" && msg.c)
                 dropConn(msg.c);
+            else if (msg.t === "push_invalid" && typeof msg.token === "string") {
+                // Apple no longer knows the token (the app was deleted, or pushes turned off): stop sending to it.
+                void dropPushToken(msg.token).catch(() => { });
+            }
         });
         socket.addEventListener("close", (ev) => {
+            clearTimeout(handshake);
             if (ws !== socket)
                 return;
             ws = null;
@@ -233,6 +256,8 @@ export async function startRelay(opts) {
                 dropConn(c);
             if (stopped)
                 return;
+            if (status.state === "connected")
+                log("relay: connection lost — reconnecting");
             status.state = "error";
             status.error = ev.code === 4401 ? `the relay refused this machine: ${ev.reason || "wrong secret"}` : ev.reason || "the relay connection closed";
             if (ev.code === 4401)
@@ -263,6 +288,14 @@ export async function startRelay(opts) {
     connect();
     return {
         status: () => ({ ...status }),
+        push(pushes) {
+            if (status.state !== "connected" || !pushes.length)
+                return false;
+            // At most 100 per message: a burst (a routine failing in every workspace) stays well under the relay's message limit.
+            for (let i = 0; i < pushes.length; i += 100)
+                send({ t: "push", pushes: pushes.slice(i, i + 100) });
+            return true;
+        },
         stop() {
             stopped = true;
             if (retry)
@@ -293,6 +326,8 @@ export async function applyRelay(port, version, log) {
         link = await startRelay({ port, settings, version, log });
     return relayStatus();
 }
+/** Hand push notifications to this daemon's relay link; false without one. */
+export const relayPush = (pushes) => link?.push(pushes) ?? false;
 /** The link's state; "off" when this process holds none (not the daemon, or the relay is off). */
 export const relayStatus = () => link?.status() ?? { state: "off", clients: 0 };
 export function stopRelay() {

package/dist/server/ws.js

@@ -9,6 +9,7 @@ const GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
 /** One message (all its fragments) may not exceed this. */
 const MAX_MESSAGE = 4_000_000;
 const PING_MS = 25_000;
+const CLOSE_GRACE_MS = 2_000;
 /** Complete the upgrade, or answer 400 and return null when the request is not a WebSocket handshake. */
 export function acceptWebSocket(req, socket, head) {
     const key = req.headers["sec-websocket-key"];
@@ -55,6 +56,8 @@ export function acceptWebSocket(req, socket, head) {
         payload.writeUInt16BE(code, 0);
         payload.write(reason, 2);
         socket.end(frame(0x8, payload));
+        // The peer should close its side now; one that does not (or never saw the frame) must not keep the connection — or us — waiting.
+        setTimeout(() => socket.destroy(), CLOSE_GRACE_MS).unref?.();
         finish();
     };
     const parse = () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netnodeag/kraftwerk",
-  "version": "0.71.0",
+  "version": "0.72.0",
   "description": "Open-source agentic workspace for teams — where people and AI agents get work done together: agents (Claude Code, Codex, Pi), skills, shared knowledge, repeatable workflows, and deterministic verification",
   "keywords": [
     "agents",