@byokit/herdr 0.1.0-next.dbe7142

package/dist/link.js

@@ -0,0 +1,324 @@
+// Host-side link adapter: the hd.* ops over @byokit/link, and the serve() wiring (duplicated per kit by design,
+// D3) — built in H7 (docs/runtime-kits.md 7.1-7.3).
+//
+// Permission shape: `allow` lets every request through and `handle`/`stream` refuse with the `link.notAllowed`
+// words sentence, so a refused device hears the kit's sentence (a bare `allow: false` would surface link's own
+// generic `view-only`/`not-allowed` words instead).
+import { createServer } from 'node:http';
+import { WebSocketServer } from 'ws';
+import { PublicLinkError, } from '@byokit/link';
+import { reach } from '@byokit/reach';
+import { stateWords, words } from "./words.js";
+import { decodeB64Url, sealNotice } from "./notices.js";
+// Ops a view-role grant may open; every other op needs the control role (7.1, *view* marks).
+const VIEW_OPS = new Set(['hd.state', 'hd.tree', 'hd.read', 'hd.blocked', 'hd.events']);
+const deny = () => {
+    throw new PublicLinkError(words('link.notAllowed'));
+};
+const findPane = (snap, paneId) => {
+    for (const w of snap.workspaces) {
+        for (const t of w.tabs) {
+            if (t.panes.some((p) => p.id === paneId))
+                return { workspaceId: w.id, tabId: t.id };
+        }
+    }
+    return undefined;
+};
+const inScope = (scope, workspaceId) => scope.workspaces === 'all' || scope.workspaces.includes(workspaceId);
+const filterSnapshot = (snap, scope) => {
+    if (scope.workspaces === 'all')
+        return snap;
+    return { ...snap, workspaces: snap.workspaces.filter((w) => scope.workspaces.includes(w.id)) };
+};
+const asRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) ? v : {};
+const asString = (v) => (typeof v === 'string' ? v : undefined);
+const asStrings = (v) => Array.isArray(v) && v.every((e) => typeof e === 'string') ? v : undefined;
+const asNumber = (v) => typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+export function herdrLink(kit, o) {
+    if (!kit || typeof o?.scopeOf !== 'function')
+        throw new Error('herdr: herdrLink needs a kit and scopeOf');
+    const passThrough = o.passThrough ?? (() => false);
+    const boxes = new Map(); // grant id → registered notice box key
+    // The latest grant object per id, refreshed on every request so scopeOf sees current meta.
+    const currentGrants = new Map();
+    const scopeOfSafe = (grant) => {
+        const scope = o.scopeOf(grant);
+        if (scope && (scope.workspaces === 'all' || Array.isArray(scope.workspaces)))
+            return scope;
+        return { workspaces: [] };
+    };
+    if (o.relay) {
+        const relay = o.relay;
+        // Herdr pushes carry no actions (7.3): the notice is the question, the answer rides hd.answer.
+        // The relay reads only the generic title; the sealed body opens with the device's own seed.
+        // (Herdr words have no approval.notice key — the title is the blocked sentence.)
+        kit.onBlocked((b, change) => {
+            if (change !== 'added')
+                return;
+            for (const [id, box] of boxes) {
+                const grant = currentGrants.get(id);
+                if (!grant || !inScope(scopeOfSafe(grant), b.workspaceId))
+                    continue;
+                const data = sealNotice(b, box);
+                void relay.notify({
+                    id: b.paneId, title: words('agent.blocked'),
+                    data: { v: 1, sealed: data.sealed }, to: [id], urgency: 'high',
+                }, { includeContent: true }).catch(() => { });
+            }
+        });
+    }
+    const handle = async (req, grant) => {
+        currentGrants.set(grant.id, grant);
+        const scope = scopeOfSafe(grant);
+        const args = asRecord(req.args);
+        switch (req.op) {
+            case 'hd.state': {
+                return { state: kit.state, words: stateWords(kit.state) };
+            }
+            case 'hd.tree': {
+                return filterSnapshot(kit.snapshot(), scope);
+            }
+            case 'hd.agent.start': {
+                if (grant.role !== 'control')
+                    deny();
+                const place = asRecord(args.place);
+                // New workspaces/tabs are creatable; existing anchors must already be in scope.
+                const anchorPane = asString(place.split) ?? asString(place.pane);
+                if (anchorPane !== undefined) {
+                    const where = findPane(kit.snapshot(), anchorPane);
+                    if (!where || !inScope(scope, where.workspaceId))
+                        deny();
+                }
+                if (place.tab !== undefined && typeof place.tab === 'object' && place.tab !== null) {
+                    const wid = asString(place.tab.workspaceId);
+                    if (!wid || !kit.snapshot().workspaces.some((w) => w.id === wid && inScope(scope, w.id)))
+                        deny();
+                }
+                return kit.startAgent(args);
+            }
+            case 'hd.prompt': {
+                if (grant.role !== 'control')
+                    deny();
+                const paneId = asString(args.paneId);
+                if (!paneId)
+                    throw new Error('herdr: hd.prompt needs a paneId');
+                const where = findPane(kit.snapshot(), paneId);
+                if (!where || !inScope(scope, where.workspaceId))
+                    deny();
+                return kit.prompt({ paneId }, String(args.text ?? ''));
+            }
+            case 'hd.keys': {
+                if (grant.role !== 'control')
+                    deny();
+                const paneId = asString(args.paneId);
+                const keys = asStrings(args.keys);
+                if (!paneId || !keys)
+                    throw new Error('herdr: hd.keys needs a paneId and keys');
+                const where = findPane(kit.snapshot(), paneId);
+                if (!where || !inScope(scope, where.workspaceId))
+                    deny();
+                await kit.sendKeys({ paneId }, keys);
+                return null;
+            }
+            case 'hd.read': {
+                const paneId = asString(args.paneId);
+                if (!paneId)
+                    throw new Error('herdr: hd.read needs a paneId');
+                const where = findPane(kit.snapshot(), paneId);
+                if (!where || !inScope(scope, where.workspaceId))
+                    deny();
+                return kit.read(paneId, {
+                    ...(typeof args.source === 'string' ? { source: args.source } : {}),
+                    ...(asNumber(args.lines) !== undefined ? { lines: asNumber(args.lines) } : {}),
+                });
+            }
+            case 'hd.blocked': {
+                return kit.blocked().filter((b) => inScope(scope, b.workspaceId));
+            }
+            case 'hd.answer': {
+                if (grant.role !== 'control')
+                    deny();
+                const paneId = asString(args.paneId);
+                const keys = asStrings(args.keys);
+                const revision = asNumber(args.revision);
+                if (!paneId || !keys || revision === undefined) {
+                    throw new Error('herdr: hd.answer needs paneId, keys and revision');
+                }
+                const where = findPane(kit.snapshot(), paneId);
+                if (!where || !inScope(scope, where.workspaceId))
+                    deny();
+                try {
+                    await kit.answer(paneId, keys, { revision });
+                }
+                catch (e) {
+                    // A stale revision is the question changing under the device, not a refusal.
+                    if (e?.code === 'approval-stale') {
+                        throw new PublicLinkError(words('approval.stale'));
+                    }
+                    throw e;
+                }
+                return null;
+            }
+            case 'hd.close': {
+                if (grant.role !== 'control')
+                    deny();
+                const snap = kit.snapshot();
+                const paneId = asString(args.pane);
+                const tabId = asString(args.tab);
+                const workspaceId = asString(args.workspace);
+                const picked = [paneId, tabId, workspaceId].filter((v) => v !== undefined);
+                if (picked.length !== 1)
+                    throw new Error('herdr: hd.close picks exactly one of pane, tab or workspace');
+                if (paneId !== undefined) {
+                    const where = findPane(snap, paneId);
+                    if (!where || !inScope(scope, where.workspaceId))
+                        deny();
+                    await kit.closePane(paneId);
+                    return null;
+                }
+                if (tabId !== undefined) {
+                    const owner = snap.workspaces.find((w) => w.tabs.some((t) => t.id === tabId));
+                    if (!owner || !inScope(scope, owner.id))
+                        deny();
+                    await kit.closeTab(tabId);
+                    return null;
+                }
+                if (!snap.workspaces.some((w) => w.id === workspaceId && inScope(scope, w.id)))
+                    deny();
+                await kit.closeWorkspace(workspaceId);
+                return null;
+            }
+            case 'hd.notices.register': {
+                if (grant.role !== 'control')
+                    deny();
+                const box = decodeB64Url(asString(args.boxPublicKey) ?? '');
+                if (!box || box.length !== 32)
+                    throw new Error('herdr: hd.notices.register needs a 32-byte boxPublicKey');
+                boxes.set(grant.id, box);
+                return null;
+            }
+            case 'hd.call': {
+                const method = asString(args.method);
+                if (!method)
+                    throw new Error('herdr: hd.call needs a method');
+                if (!passThrough(method, grant))
+                    deny();
+                return kit.call(method, asRecord(args.params));
+            }
+            default:
+                throw new Error(`herdr: unknown link op ${req.op}`);
+        }
+    };
+    const stream = (s, req, grant) => {
+        currentGrants.set(grant.id, grant);
+        const args = asRecord(req.args);
+        if (req.op === 'hd.events') {
+            const send = (frame) => {
+                void s.write(`${JSON.stringify(frame)}\n`).catch(() => { });
+            };
+            send({ type: 'snapshot', snapshot: filterSnapshot(kit.snapshot(), scopeOfSafe(grant)) });
+            const stopTree = kit.onChange((snap) => {
+                send({ type: 'snapshot', snapshot: filterSnapshot(snap, scopeOfSafe(currentGrants.get(grant.id) ?? grant)) });
+            });
+            const stopBlocked = kit.onBlocked((b, change) => {
+                if (inScope(scopeOfSafe(currentGrants.get(grant.id) ?? grant), b.workspaceId)) {
+                    send({ type: 'blocked', change, blocked: b });
+                }
+            });
+            s.onEnd = () => { stopTree(); stopBlocked(); };
+            return;
+        }
+        if (req.op === 'hd.terminal') {
+            const scope = scopeOfSafe(grant);
+            const paneId = asString(args.paneId);
+            if (!paneId) {
+                s.end('herdr: hd.terminal needs a paneId');
+                return;
+            }
+            const where = findPane(kit.snapshot(), paneId);
+            if (!where || !inScope(scope, where.workspaceId)) {
+                s.end(words('link.notAllowed'));
+                return;
+            }
+            // View grants get observe only; control grants get the mode they asked for (7.1).
+            const want = args.mode === 'control' ? 'control' : 'observe';
+            const mode = grant.role === 'control' ? want : 'observe';
+            const cols = asNumber(args.cols) ?? 80;
+            const rows = asNumber(args.rows) ?? 24;
+            let session;
+            try {
+                session = kit.terminal(paneId, { mode, cols, rows });
+            }
+            catch (e) {
+                s.end(e instanceof PublicLinkError ? e.message : 'failed');
+                return;
+            }
+            const text = new TextDecoder();
+            let pending = '';
+            session.onFrame((line) => {
+                void s.write(`${line}\n`).catch(() => { });
+            });
+            s.onData = (chunk) => {
+                pending += text.decode(chunk, { stream: true });
+                const lines = pending.split('\n');
+                pending = lines.pop() ?? '';
+                for (const line of lines) {
+                    if (line.length > 0)
+                        session.send(line);
+                }
+            };
+            s.onEnd = () => {
+                if (pending.length > 0)
+                    session.send(pending);
+                session.close();
+            };
+            void session.ready.catch((e) => {
+                s.end(e instanceof Error && e.code === 'missing/binary'
+                    ? words('herdr.missing') : 'failed');
+            });
+            void session.exited.then(() => s.end());
+            return;
+        }
+        s.end(`herdr: unknown link stream ${req.op}`);
+    };
+    return {
+        handle,
+        stream,
+        // Every refusal carries the kit's sentence from handle/stream (see the module note).
+        allow: () => true,
+    };
+}
+export function serve(o) {
+    return (async () => {
+        const r = await reach({ port: o.port, via: o.via, previous: o.previous });
+        const server = createServer((req, res) => {
+            if (o.http) {
+                o.http(req, res);
+                return;
+            }
+            res.statusCode = 404;
+            res.end();
+        });
+        const wss = new WebSocketServer({ server });
+        wss.on('connection', (ws, req) => {
+            o.host.accept(ws, { peer: req.socket.remoteAddress });
+        });
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(o.port, r.bind, () => {
+                server.off('error', reject);
+                resolve();
+            });
+        });
+        return {
+            urls: r.urls,
+            ...(r.ingress ? { ingress: r.ingress } : {}),
+            close: async () => {
+                wss.close();
+                await new Promise((resolve, reject) => {
+                    server.close((e) => (e ? reject(e) : resolve()));
+                });
+            },
+        };
+    })();
+}

package/dist/notices.d.ts

@@ -0,0 +1,14 @@
+import type { BlockedAgent } from './types.ts';
+/** Base64url without padding, hand-rolled so this file stays portable (no Buffer, no atob). */
+export declare function encodeB64Url(bytes: Uint8Array): string;
+/** The inverse; null when the text is not base64url. */
+export declare function decodeB64Url(s: string): Uint8Array | null;
+/** Seal a blocked agent for one device's box key; the relay carries only the returned envelope. */
+export declare function sealNotice(b: BlockedAgent, boxPublicKey: Uint8Array): {
+    v: 1;
+    sealed: string;
+};
+/** Open a notice envelope with the device's 32-byte seed; null when it is not ours or not a notice. */
+export declare function openNotice(data: Record<string, unknown>, seed: Uint8Array): BlockedAgent | null;
+/** The box public key a device registers for a seed (the host seals to this). */
+export declare function boxPublicKeyB64(seed: Uint8Array): string;

package/dist/notices.js

@@ -0,0 +1,88 @@
+// Sealed blocked-approval notices: the relay reads only a generic title, the phone opens the sealed body with its
+// own key (docs/runtime-kits.md 7.3). Portable: no Node import anywhere in it — `./device` re-exports `openNotice`.
+import { boxKeyPairFromSeed, openBox, sealBox } from '@byokit/seal';
+const ABC = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+/** Base64url without padding, hand-rolled so this file stays portable (no Buffer, no atob). */
+export function encodeB64Url(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const a = bytes[i];
+        const b = i + 1 < bytes.length ? bytes[i + 1] : 0;
+        const c = i + 2 < bytes.length ? bytes[i + 2] : 0;
+        out += ABC[a >> 2] + ABC[((a & 3) << 4) | (b >> 4)];
+        if (i + 1 < bytes.length)
+            out += ABC[((b & 15) << 2) | (c >> 6)];
+        if (i + 2 < bytes.length)
+            out += ABC[c & 63];
+    }
+    return out;
+}
+/** The inverse; null when the text is not base64url. */
+export function decodeB64Url(s) {
+    if (typeof s !== 'string' || s.length === 0 || /[^A-Za-z0-9\-_]/.test(s))
+        return null;
+    const vals = new Uint8Array(s.length);
+    for (let i = 0; i < s.length; i++) {
+        const n = ABC.indexOf(s[i]);
+        if (n < 0)
+            return null;
+        vals[i] = n;
+    }
+    const out = new Uint8Array(Math.floor((s.length * 6) / 8));
+    let at = 0;
+    let hold = 0;
+    let bits = 0;
+    for (const n of vals) {
+        hold = (hold << 6) | n;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[at++] = (hold >> bits) & 0xff;
+        }
+    }
+    return out.subarray(0, at);
+}
+const isBlockedAgent = (v) => {
+    const b = v;
+    return typeof b === 'object' && b !== null &&
+        typeof b.paneId === 'string' && typeof b.workspaceId === 'string' && typeof b.tabId === 'string' &&
+        typeof b.revision === 'number' && Number.isSafeInteger(b.revision) &&
+        typeof b.prompt === 'string' && typeof b.since === 'number' &&
+        (b.kind === undefined || typeof b.kind === 'string');
+};
+/** Seal a blocked agent for one device's box key; the relay carries only the returned envelope. */
+export function sealNotice(b, boxPublicKey) {
+    if (!(boxPublicKey instanceof Uint8Array) || boxPublicKey.length !== 32) {
+        throw new Error('herdr: box public key must be 32 bytes');
+    }
+    if (!isBlockedAgent(b))
+        throw new Error('herdr: cannot seal that notice');
+    return { v: 1, sealed: encodeB64Url(sealBox(new TextEncoder().encode(JSON.stringify(b)), boxPublicKey)) };
+}
+/** Open a notice envelope with the device's 32-byte seed; null when it is not ours or not a notice. */
+export function openNotice(data, seed) {
+    if (typeof data !== 'object' || data === null || data.v !== 1 || typeof data.sealed !== 'string')
+        return null;
+    if (!(seed instanceof Uint8Array) || seed.length !== 32)
+        return null;
+    const bundle = decodeB64Url(data.sealed);
+    if (bundle === null)
+        return null;
+    const bytes = openBox(bundle, seed);
+    if (bytes === null)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    catch {
+        return null;
+    }
+    return isBlockedAgent(parsed) ? parsed : null;
+}
+/** The box public key a device registers for a seed (the host seals to this). */
+export function boxPublicKeyB64(seed) {
+    if (!(seed instanceof Uint8Array) || seed.length !== 32)
+        throw new Error('herdr: notices seed must be 32 bytes');
+    return encodeB64Url(boxKeyPairFromSeed(seed).publicKey);
+}

package/dist/socket.d.ts

@@ -0,0 +1,2 @@
+import type { HerdrTransport } from './types.ts';
+export declare function socketTransport(socketPath: string): HerdrTransport;

package/dist/socket.js

@@ -0,0 +1,137 @@
+import { createConnection } from 'node:net';
+export function socketTransport(socketPath) {
+    const sockets = new Set();
+    const timers = new Set();
+    let closed = false;
+    let nextId = 0;
+    const later = (fn, ms) => {
+        const timer = setTimeout(() => { timers.delete(timer); fn(); }, ms);
+        timers.add(timer);
+    };
+    const connect = (onLine, onClose) => {
+        const socket = createConnection(socketPath);
+        sockets.add(socket);
+        let buffer = '';
+        let ended = false;
+        const end = () => {
+            if (ended)
+                return;
+            ended = true;
+            sockets.delete(socket);
+            onClose();
+        };
+        socket.setEncoding('utf8');
+        socket.on('data', (chunk) => {
+            buffer += chunk;
+            let pos;
+            while ((pos = buffer.indexOf('\n')) >= 0) {
+                const line = buffer.slice(0, pos);
+                buffer = buffer.slice(pos + 1);
+                if (line.trim()) {
+                    try {
+                        onLine(JSON.parse(line));
+                    }
+                    catch { /* malformed frame */ }
+                }
+            }
+        });
+        socket.on('error', end);
+        socket.on('close', end);
+        return socket;
+    };
+    return {
+        call(method, params, timeoutMs = 15_000) {
+            if (closed)
+                return Promise.reject(new Error('herdr: transport closed'));
+            return new Promise((resolve, reject) => {
+                const id = `byokit-${++nextId}`;
+                let done = false;
+                const finish = (error, result) => {
+                    if (done)
+                        return;
+                    done = true;
+                    clearTimeout(timer);
+                    socket.destroy();
+                    if (error)
+                        reject(error);
+                    else
+                        resolve(result);
+                };
+                const socket = connect((frame) => {
+                    if (frame.id !== id)
+                        return;
+                    if (frame.error) {
+                        const error = new Error(`herdr: ${frame.error.code}: ${frame.error.message}`);
+                        error.code = frame.error.code;
+                        finish(error);
+                    }
+                    else
+                        finish(undefined, frame.result);
+                }, () => finish(new Error('herdr: socket closed')));
+                const timer = setTimeout(() => finish(new Error('herdr: request timed out')), timeoutMs);
+                socket.on('connect', () => socket.write(`${JSON.stringify({ id, method, params })}\n`));
+            });
+        },
+        subscribe(subs, on, onError) {
+            let stopped = false;
+            let current;
+            let attempts = 0;
+            let acknowledge;
+            const ready = new Promise((resolve) => { acknowledge = resolve; });
+            let reconnect;
+            let disconnect;
+            let connectedBefore = false;
+            const open = () => {
+                if (stopped || closed)
+                    return;
+                const id = `byokit-${++nextId}`;
+                let ack = false;
+                let rejected = false;
+                current = connect((frame) => {
+                    if (frame.error && (frame.id === '' || frame.id === id)) {
+                        rejected = true;
+                        acknowledge?.(false);
+                        onError(String(frame.error.code), String(frame.error.message));
+                        current?.destroy();
+                    }
+                    else if (frame.id === id) {
+                        const again = connectedBefore;
+                        connectedBefore = true;
+                        ack = true;
+                        attempts = 0;
+                        acknowledge?.(true);
+                        if (again)
+                            reconnect?.();
+                    }
+                    else {
+                        const data = frame.data ?? frame;
+                        const type = frame.event ?? data.type;
+                        if (ack && typeof type === 'string')
+                            on({ ...data, type });
+                    }
+                }, () => {
+                    if (stopped || closed || rejected)
+                        return;
+                    if (ack)
+                        disconnect?.();
+                    later(open, ack ? (subs.some((s) => s.type === 'pane.agent_status_changed') ? 2000 : 1000)
+                        : [250, 500, 1000, 2000][Math.min(attempts++, 3)]);
+                });
+                current.on('connect', () => current?.write(`${JSON.stringify({ id, method: 'events.subscribe', params: { subscriptions: subs } })}\n`));
+            };
+            open();
+            const stop = () => { stopped = true; current?.destroy(); };
+            return Object.assign(stop, { ready, onReconnect(fn) { reconnect = fn; },
+                onDisconnect(fn) { disconnect = fn; } });
+        },
+        close() {
+            closed = true;
+            for (const timer of timers)
+                clearTimeout(timer);
+            timers.clear();
+            for (const socket of sockets)
+                socket.destroy();
+            sockets.clear();
+        },
+    };
+}

package/dist/supervise.d.ts

@@ -0,0 +1,17 @@
+import type { HerdrKitOptions, HerdrState, HerdrTransport } from './types.ts';
+export declare class Supervisor {
+    private transport?;
+    private child?;
+    private stopping;
+    private retry?;
+    private failures;
+    private readonly root?;
+    private readonly socketPath;
+    private readonly o;
+    private readonly onState;
+    constructor(o: HerdrKitOptions, onState: (s: HerdrState) => void);
+    env(): Record<string, string>;
+    private state;
+    start(): Promise<HerdrTransport>;
+    stop(): Promise<void>;
+}