pikiloom 0.4.21 → 0.4.23

package/dist/pikichannel/host.js

@@ -0,0 +1,252 @@
+/**
+ * pikichannel/host.ts — the host SDK (transport- and agent-agnostic).
+ *
+ * `PikichannelHost` speaks the L2 protocol over any {@link ChannelConnection},
+ * driven by a {@link SessionSource} the embedder supplies. The host knows
+ * nothing about pikiloom: porting pikichannel to another agent runtime is a
+ * matter of implementing SessionSource (see adapter-pikiloom.ts).
+ *
+ * It owns three cross-cutting concerns the protocol requires:
+ *   - Auth: a peer must pass `authenticate(token, remote)` (loopback exempt by
+ *     policy) before ANY session data or control is processed.
+ *   - Delta: it holds the latest full snapshot per session and emits a `full`
+ *     patch on (re)subscribe / resync, deltas thereafter — O(n) per stream.
+ *   - Fan-out: one delta per update is broadcast to every caught-up subscriber;
+ *     a fresh subscriber gets a `full` so it shares the same baseline.
+ */
+import { PROTOCOL_VERSION, diffSnapshot, } from './protocol.js';
+import { encodeServer, decodeClient } from './codec.js';
+const SUBSCRIBE_ALL = '*';
+export class PikichannelHost {
+    source;
+    authenticate;
+    log;
+    peers = new Set();
+    unsubscribers = [];
+    started = false;
+    /** Latest full snapshot per session — the delta baseline shared by all peers. */
+    lastFull = new Map();
+    lastSeq = new Map();
+    constructor(source, authenticate = () => true, log = () => { }) {
+        this.source = source;
+        this.authenticate = authenticate;
+        this.log = log;
+    }
+    /** Wire host-level subscriptions to the source (once). */
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.unsubscribers.push(this.source.onUpdate((sessionKey, snapshot, seq) => this.onSourceUpdate(sessionKey, snapshot, seq)));
+        this.unsubscribers.push(this.source.onSessionsChanged((sessions) => this.broadcast({ type: 'sessions', sessions }, true)));
+    }
+    stop() {
+        for (const u of this.unsubscribers.splice(0)) {
+            try {
+                u();
+            }
+            catch { /* ignore */ }
+        }
+        for (const peer of this.peers) {
+            try {
+                peer.conn.close();
+            }
+            catch { /* ignore */ }
+        }
+        this.peers.clear();
+        this.lastFull.clear();
+        this.lastSeq.clear();
+        this.started = false;
+    }
+    /** Adopt a freshly-established connection from any transport binding. */
+    handleConnection(conn) {
+        if (!this.started)
+            this.start();
+        const peer = { conn, subs: new Set(), authed: false };
+        this.peers.add(peer);
+        this.log(`peer connected id=${conn.id} via=${conn.kind} remote=${conn.remote || '?'}`);
+        conn.onMessage((frame) => {
+            const msg = decodeClient(frame);
+            if (!msg)
+                return;
+            this.handleClientMessage(peer, msg).catch((err) => {
+                this.send(peer, { type: 'error', message: err?.message || String(err) });
+            });
+        });
+        conn.onClose(() => {
+            this.peers.delete(peer);
+            this.log(`peer disconnected id=${conn.id} via=${conn.kind}`);
+        });
+    }
+    // -- delta baseline ------------------------------------------------------
+    onSourceUpdate(sessionKey, full, seq) {
+        const prev = this.lastFull.get(sessionKey);
+        const patch = prev ? diffSnapshot(prev, full) : { full };
+        this.lastFull.set(sessionKey, full);
+        this.lastSeq.set(sessionKey, seq);
+        const frame = { type: 'session', sessionKey, seq, patch };
+        for (const peer of this.peers) {
+            if (peer.authed && (peer.subs.has(SUBSCRIBE_ALL) || peer.subs.has(sessionKey)))
+                this.send(peer, frame);
+        }
+    }
+    /** Send the current full snapshot for a session to one peer (subscribe / resync). */
+    sendFull(peer, sessionKey) {
+        let full = this.lastFull.get(sessionKey);
+        let seq = this.lastSeq.get(sessionKey);
+        if (!full) {
+            const snap = this.source.getSnapshot(sessionKey);
+            if (!snap)
+                return;
+            full = snap.snapshot;
+            seq = snap.seq;
+            this.lastFull.set(sessionKey, full);
+            this.lastSeq.set(sessionKey, seq);
+        }
+        this.send(peer, { type: 'session', sessionKey, seq: seq || 0, patch: { full } });
+    }
+    // -- inbound -------------------------------------------------------------
+    async handleClientMessage(peer, msg) {
+        // Ping is always allowed (RTT / keepalive). Everything else is gated on auth.
+        if (msg.type === 'ping') {
+            this.send(peer, { type: 'pong', t: msg.t });
+            return;
+        }
+        if (!peer.authed) {
+            if (msg.type !== 'hello') {
+                this.send(peer, { type: 'error', message: 'not authenticated', code: 'auth' });
+                return;
+            }
+            if (!this.authenticate(msg.token, peer.conn.remote)) {
+                this.log(`peer rejected id=${peer.conn.id} remote=${peer.conn.remote || '?'} (bad/absent token)`);
+                this.send(peer, { type: 'error', message: 'unauthorized', code: 'auth' });
+                peer.conn.close();
+                return;
+            }
+            peer.authed = true;
+            const info = this.source.hostInfo();
+            this.send(peer, {
+                type: 'welcome',
+                v: PROTOCOL_VERSION,
+                host: {
+                    name: info.name,
+                    version: info.version,
+                    transport: peer.conn.kind,
+                    capabilities: info.capabilities,
+                    authRequired: info.authRequired,
+                },
+                sessions: this.source.listSessions(),
+            });
+            if (msg.resume?.sessionKey) {
+                peer.subs.add(msg.resume.sessionKey);
+                this.sendFull(peer, msg.resume.sessionKey);
+            }
+            return;
+        }
+        switch (msg.type) {
+            case 'hello':
+                return; // already authenticated; ignore duplicate hello
+            case 'subscribe': {
+                peer.subs.add(msg.sessionKey);
+                if (msg.sessionKey === SUBSCRIBE_ALL) {
+                    for (const meta of this.source.listSessions())
+                        this.sendFull(peer, meta.sessionKey);
+                }
+                else {
+                    this.sendFull(peer, msg.sessionKey);
+                }
+                return;
+            }
+            case 'unsubscribe':
+                peer.subs.delete(msg.sessionKey);
+                return;
+            case 'getSnapshot':
+                this.sendFull(peer, msg.sessionKey);
+                return;
+            case 'listSessions':
+                this.send(peer, { type: 'sessions', sessions: this.source.listSessions() });
+                return;
+            case 'prompt': {
+                const result = await this.source.prompt({
+                    sessionKey: msg.sessionKey, prompt: msg.prompt, agent: msg.agent, workdir: msg.workdir,
+                    model: msg.model, effort: msg.effort, workflow: msg.workflow, attachments: msg.attachments,
+                });
+                if (result.ok && result.sessionKey) {
+                    peer.subs.add(result.sessionKey);
+                    this.send(peer, { type: 'accepted', sessionKey: result.sessionKey, taskId: result.taskId || '', clientRef: msg.clientRef });
+                    this.sendFull(peer, result.sessionKey);
+                }
+                else {
+                    this.send(peer, { type: 'error', message: result.error || 'prompt rejected', clientRef: msg.clientRef });
+                }
+                return;
+            }
+            case 'stop': {
+                const r = this.source.stop(msg.sessionKey);
+                if (!r.ok)
+                    this.send(peer, { type: 'error', message: r.error || 'stop failed' });
+                return;
+            }
+            case 'steer': {
+                const r = await this.source.steer(msg.taskId);
+                if (!r.ok)
+                    this.send(peer, { type: 'error', message: r.error || 'steer failed' });
+                return;
+            }
+            case 'recall': {
+                const r = this.source.recall(msg.taskId);
+                if (!r.ok)
+                    this.send(peer, { type: 'error', message: r.error || 'recall failed' });
+                return;
+            }
+            case 'interact': {
+                const r = this.source.interact(msg.promptId, msg.action, msg.value, msg.requestFreeform);
+                if (!r.ok)
+                    this.send(peer, { type: 'error', message: r.error || 'interaction failed' });
+                return;
+            }
+            case 'request': {
+                const id = msg.id;
+                // Only the management API is tunnelable — never static, the SPA shell,
+                // or loopback-gated endpoints (e.g. /pikichannel/pair would otherwise
+                // leak the token to a remote peer via the host's own fetch).
+                if (!msg.path || !msg.path.startsWith('/api/')) {
+                    this.send(peer, { type: 'response', id, status: 403, error: 'only /api/* is tunnelable' });
+                    return;
+                }
+                if (!this.source.handleRequest) {
+                    this.send(peer, { type: 'response', id, status: 501, error: 'tunnel not supported' });
+                    return;
+                }
+                try {
+                    const r = await this.source.handleRequest({ method: msg.method, path: msg.path, headers: msg.headers, body: msg.body, encoding: msg.encoding });
+                    this.send(peer, { type: 'response', id, status: r.status, headers: r.headers, body: r.body, encoding: r.encoding });
+                }
+                catch (err) {
+                    this.send(peer, { type: 'response', id, status: 500, error: err?.message || 'tunnel error' });
+                }
+                return;
+            }
+        }
+    }
+    // -- outbound ------------------------------------------------------------
+    broadcast(frame, authedOnly = false) {
+        for (const peer of this.peers)
+            if (!authedOnly || peer.authed)
+                this.send(peer, frame);
+    }
+    send(peer, frame) {
+        if (!peer.conn.isOpen())
+            return;
+        try {
+            peer.conn.send(encodeServer(frame));
+        }
+        catch { /* drop on closed pipe */ }
+    }
+    /** Number of live peers (for status / metrics). */
+    get peerCount() { return this.peers.size; }
+    /** Number of authenticated peers. */
+    get authedPeerCount() { let n = 0; for (const p of this.peers)
+        if (p.authed)
+            n++; return n; }
+}

package/dist/pikichannel/protocol.js

@@ -0,0 +1,105 @@
+/**
+ * pikichannel/protocol.ts — THE universal, agent-agnostic wire protocol (L2).
+ *
+ * This file is the single source of truth for the pikichannel contract. It is
+ * deliberately free of any pikiloom-internal or agent-specific type: a client
+ * SDK on any platform (Web / iOS / Android) only needs these shapes to speak to
+ * any pikichannel host. The browser SDK in `web/pikichannel-sdk.js` mirrors the
+ * string literals and shapes documented here — keep the two in lockstep.
+ *
+ * Layering:
+ *   transport (L1)  — moves opaque frames (a byte/string pipe): WebSocket, WebRTC
+ *                     datachannel, relay tunnel. Pluggable; see transport.ts.
+ *   protocol (L2)   — THIS file. The session/event semantics framed over L1.
+ *
+ * Design rules:
+ *   - Every message is a flat discriminated union on `type`. No nested envelopes
+ *     so clients can `switch (msg.type)` directly.
+ *   - The host→client `session` event carries a {@link SnapshotPatch}: a `full`
+ *     snapshot on first send / resync, then deltas (append-only suffixes for the
+ *     unbounded text/reasoning fields + changed scalar/struct fields). The host
+ *     remains the single source of truth — it holds the full snapshot and emits
+ *     `full` on (re)subscribe or whenever a client reports a `seq` gap, so the
+ *     wire is O(n) for a stream of total size n instead of O(n²).
+ *   - `seq` is monotonic per session for ordering / gap detection.
+ *   - Auth: a client authenticates in `hello` (token); loopback peers are exempt
+ *     by host policy. No session data or control is processed before auth.
+ *   - Versioned via PROTOCOL_VERSION; the handshake negotiates it.
+ *
+ * Extensibility (how this grows without forking the wire):
+ *   - ADDITIVE by default: new optional fields on existing messages and brand-new
+ *     `type`s are backward-compatible. Both host and client MUST ignore unknown
+ *     message `type`s and unknown fields (the switch statements fall through, not
+ *     throw) — so an old peer talks to a new peer safely.
+ *   - Optional features are negotiated via `HostCapability` (advertised in
+ *     `welcome`), not by version bumps — a client checks `host.capabilities`
+ *     before using a non-core verb.
+ *   - PROTOCOL_VERSION bumps only for a BREAKING change; `hello.v` lets either
+ *     side detect a mismatch and degrade.
+ *   - The transport (L1) is fully decoupled: a new binding (relay, WebTransport,
+ *     QUIC) implements ChannelConnection and carries this protocol unchanged.
+ */
+export const PROTOCOL_VERSION = 1;
+/** An empty baseline snapshot, used as the starting point before any patch. */
+export function emptySnapshot() {
+    return { phase: 'idle', updatedAt: 0 };
+}
+const APPEND_FIELDS = ['text', 'reasoning'];
+const STRUCT_FIELDS = ['plan', 'toolCalls', 'subAgents', 'usage', 'artifacts', 'interactions', 'queued'];
+const SCALAR_FIELDS = ['phase', 'taskId', 'agent', 'model', 'effort', 'prompt', 'activity', 'error', 'incomplete', 'startedAt', 'updatedAt'];
+/**
+ * Diff two full snapshots into a minimal patch. text/reasoning are encoded as
+ * append suffixes when the next value extends the prev (the streaming common
+ * case); any non-extension falls back to a `set`. Bounded fields are compared by
+ * value and sent whole when changed.
+ */
+export function diffSnapshot(prev, next) {
+    const patch = {};
+    let set;
+    const put = (k, v) => { (set ||= {})[k] = v; };
+    for (const f of APPEND_FIELDS) {
+        const a = prev[f] ?? '';
+        const b = next[f] ?? '';
+        if (a === b)
+            continue;
+        if (typeof b === 'string' && typeof a === 'string' && b.startsWith(a)) {
+            if (f === 'text')
+                patch.appendText = b.slice(a.length);
+            else
+                patch.appendReasoning = b.slice(a.length);
+        }
+        else {
+            put(f, b);
+        }
+    }
+    for (const f of SCALAR_FIELDS) {
+        if (prev[f] !== next[f])
+            put(f, next[f]);
+    }
+    for (const f of STRUCT_FIELDS) {
+        if (JSON.stringify(prev[f]) !== JSON.stringify(next[f]))
+            put(f, next[f]);
+    }
+    if (set)
+        patch.set = set;
+    return patch;
+}
+/** Apply a patch onto a prior snapshot, returning the new cumulative snapshot. */
+export function applySnapshotPatch(prev, patch) {
+    if (patch.full)
+        return patch.full;
+    const next = prev ? { ...prev } : emptySnapshot();
+    if (patch.appendText)
+        next.text = (next.text || '') + patch.appendText;
+    if (patch.appendReasoning)
+        next.reasoning = (next.reasoning || '') + patch.appendReasoning;
+    if (patch.set)
+        Object.assign(next, patch.set);
+    return next;
+}
+// ---------------------------------------------------------------------------
+// Type guards (host-side convenience)
+// ---------------------------------------------------------------------------
+export function isClientMessage(value) {
+    return !!value && typeof value === 'object' && typeof value.type === 'string';
+}

package/dist/pikichannel/rendezvous-broker.js

@@ -0,0 +1,114 @@
+/**
+ * pikichannel/rendezvous-broker.ts — the public signaling broker (NAT traversal).
+ *
+ * This is the "route, don't relay data" rendezvous from the original design. A
+ * pikiloom host that sits behind NAT dials OUT to a broker and registers a
+ * NodeID; a client dials the same broker by NodeID. The broker pairs them and
+ * relays ONLY signaling envelopes (SDP offer/answer + ICE candidates) — it never
+ * sees datachannel data, which flows directly P2P (DTLS-encrypted) once ICE
+ * hole-punches through. It is dependency-light (no werift) so any pikiloom can
+ * act as a broker for reachable peers, or it can be run standalone.
+ *
+ * Wire protocol (JSON over the rendezvous WebSocket):
+ *   host→  {t:'register', nodeId}            ← register to receive dials
+ *      ←   {t:'registered', nodeId} | {t:'error', message}
+ *   client→{t:'dial', nodeId}                ← reach a registered host
+ *      ←   {t:'dialed', sessionId} | {t:'error', message}
+ *   broker→host {t:'open', sessionId}        ← a client dialed; prepare answerer
+ *   peer↔  {t:'signal', sessionId, data}     ← relayed to the other end verbatim
+ *   broker→peer {t:'close', sessionId}       ← the other end went away
+ */
+import crypto from 'node:crypto';
+import { WebSocketServer } from 'ws';
+import { writeScopedLog } from '../core/logging.js';
+const rlog = (msg) => writeScopedLog('pikichannel', `[rendezvous] ${msg}`, { level: 'info' });
+export class RendezvousBroker {
+    wss = new WebSocketServer({ noServer: true });
+    hosts = new Map(); // nodeId → host socket
+    sessions = new Map(); // sessionId → pair
+    constructor() {
+        this.wss.on('connection', (ws) => this.onConnection(ws));
+    }
+    handleUpgrade(req, socket, head) {
+        this.wss.handleUpgrade(req, socket, head, (ws) => this.wss.emit('connection', ws, req));
+    }
+    stop() { this.wss.close(); }
+    get stats() { return { hosts: this.hosts.size, sessions: this.sessions.size }; }
+    send(ws, msg) {
+        if (ws.readyState === ws.OPEN) {
+            try {
+                ws.send(JSON.stringify(msg));
+            }
+            catch { /* ignore */ }
+        }
+    }
+    onConnection(ws) {
+        let myNodeId = null; // set if this socket registers as a host
+        const mySessions = new Set(); // sessions this socket participates in
+        ws.on('message', (raw) => {
+            let m;
+            try {
+                m = JSON.parse(String(raw));
+            }
+            catch {
+                return;
+            }
+            switch (m?.t) {
+                case 'register': {
+                    const nodeId = String(m.nodeId || '').trim();
+                    if (!nodeId) {
+                        this.send(ws, { t: 'error', message: 'nodeId required' });
+                        return;
+                    }
+                    // Last registration wins (a host reconnecting replaces its stale socket).
+                    this.hosts.set(nodeId, ws);
+                    myNodeId = nodeId;
+                    this.send(ws, { t: 'registered', nodeId });
+                    rlog(`host registered nodeId=${nodeId} (hosts=${this.hosts.size})`);
+                    return;
+                }
+                case 'dial': {
+                    const nodeId = String(m.nodeId || '').trim();
+                    const host = this.hosts.get(nodeId);
+                    if (!host || host.readyState !== host.OPEN) {
+                        this.send(ws, { t: 'error', message: 'node offline' });
+                        return;
+                    }
+                    const sessionId = crypto.randomUUID();
+                    this.sessions.set(sessionId, { client: ws, host, nodeId });
+                    mySessions.add(sessionId);
+                    this.send(ws, { t: 'dialed', sessionId });
+                    this.send(host, { t: 'open', sessionId });
+                    rlog(`dial nodeId=${nodeId} → session=${sessionId.slice(0, 8)}`);
+                    return;
+                }
+                case 'signal': {
+                    const sessionId = String(m.sessionId || '');
+                    const s = this.sessions.get(sessionId);
+                    if (!s)
+                        return;
+                    const other = ws === s.client ? s.host : s.client;
+                    mySessions.add(sessionId);
+                    this.send(other, { t: 'signal', sessionId, data: m.data });
+                    return;
+                }
+            }
+        });
+        const cleanup = () => {
+            if (myNodeId && this.hosts.get(myNodeId) === ws) {
+                this.hosts.delete(myNodeId);
+                rlog(`host gone nodeId=${myNodeId}`);
+            }
+            for (const sessionId of mySessions) {
+                const s = this.sessions.get(sessionId);
+                if (!s)
+                    continue;
+                const other = ws === s.client ? s.host : s.client;
+                this.send(other, { t: 'close', sessionId });
+                this.sessions.delete(sessionId);
+            }
+        };
+        ws.on('close', cleanup);
+        ws.on('error', cleanup);
+    }
+}

package/dist/pikichannel/rendezvous-host.js

@@ -0,0 +1,138 @@
+/**
+ * pikichannel/rendezvous-host.ts — the host's OUTBOUND registrar (NAT side).
+ *
+ * A pikiloom host behind NAT can't be dialed directly, so it dials OUT to a
+ * reachable {@link RendezvousBroker} and registers its NodeID. For each client
+ * that dials that NodeID, the broker relays signaling and this client drives a
+ * shared werift answerer — the resulting datachannel is a normal pikichannel
+ * connection, indistinguishable downstream from a direct or local one. The
+ * registration auto-reconnects so the host stays reachable.
+ *
+ * Imports werift (via webrtc-shared), so the server wiring loads it only inside
+ * the guarded WebRTC dynamic import.
+ */
+import WebSocket from 'ws';
+import { writeScopedLog } from '../core/logging.js';
+import { createAnswerer } from './transports/webrtc-shared.js';
+const rlog = (msg) => writeScopedLog('pikichannel', `[rendezvous-host] ${msg}`, { level: 'info' });
+export class RendezvousHostClient {
+    url;
+    nodeId;
+    onConnection;
+    ws = null;
+    answerers = new Map();
+    adopted = new Set();
+    stopped = false;
+    reconnectDelay = 1000;
+    constructor(url, nodeId, onConnection) {
+        this.url = url;
+        this.nodeId = nodeId;
+        this.onConnection = onConnection;
+    }
+    start() { this.stopped = false; this.connect(); }
+    stop() {
+        this.stopped = true;
+        const ws = this.ws;
+        this.ws = null;
+        try {
+            ws?.close();
+        }
+        catch { /* ignore */ }
+        for (const a of this.answerers.values())
+            a.close();
+        this.answerers.clear();
+        this.adopted.clear();
+    }
+    connect() {
+        if (this.stopped)
+            return;
+        let ws;
+        try {
+            ws = new WebSocket(this.url);
+        }
+        catch {
+            this.scheduleReconnect();
+            return;
+        }
+        this.ws = ws;
+        ws.on('open', () => {
+            this.reconnectDelay = 1000;
+            ws.send(JSON.stringify({ t: 'register', nodeId: this.nodeId }));
+            rlog(`registering nodeId=${this.nodeId} at ${this.url}`);
+        });
+        ws.on('message', (raw) => this.onMessage(raw));
+        ws.on('close', () => {
+            if (this.ws === ws)
+                this.ws = null;
+            for (const a of this.answerers.values())
+                a.close();
+            this.answerers.clear();
+            this.adopted.clear();
+            this.scheduleReconnect();
+        });
+        ws.on('error', () => { });
+    }
+    scheduleReconnect() {
+        if (this.stopped)
+            return;
+        setTimeout(() => this.connect(), this.reconnectDelay);
+        this.reconnectDelay = Math.min(this.reconnectDelay * 2, 15_000);
+    }
+    onMessage(raw) {
+        let m;
+        try {
+            m = JSON.parse(String(raw));
+        }
+        catch {
+            return;
+        }
+        switch (m?.t) {
+            case 'registered':
+                rlog(`registered nodeId=${m.nodeId}`);
+                return;
+            case 'error':
+                rlog(`broker error: ${m.message}`);
+                return;
+            case 'open':
+                this.ensureAnswerer(m.sessionId);
+                return;
+            case 'close': {
+                const a = this.answerers.get(m.sessionId);
+                if (a) {
+                    a.close();
+                    this.answerers.delete(m.sessionId);
+                }
+                this.adopted.delete(m.sessionId);
+                return;
+            }
+            case 'signal': {
+                if (this.adopted.has(m.sessionId))
+                    return; // datachannel already live; ignore late signals
+                const a = this.ensureAnswerer(m.sessionId);
+                void a.onSignal(m.data);
+                return;
+            }
+        }
+    }
+    ensureAnswerer(sessionId) {
+        let a = this.answerers.get(sessionId);
+        if (a)
+            return a;
+        a = createAnswerer({
+            remote: `rendezvous:${sessionId.slice(0, 8)}`,
+            log: rlog,
+            onConnection: (conn) => {
+                this.adopted.add(sessionId);
+                this.answerers.delete(sessionId); // pc now owned by the connection
+                this.onConnection(conn);
+            },
+            sendSignal: (data) => {
+                const ws = this.ws;
+                if (ws && ws.readyState === ws.OPEN)
+                    ws.send(JSON.stringify({ t: 'signal', sessionId, data }));
+            },
+        });
+        this.answerers.set(sessionId, a);
+        return a;
+    }
+}