pikiloom 0.4.21 → 0.4.22

package/dist/pikichannel/adapter-pikiloom.js

@@ -0,0 +1,220 @@
+/**
+ * pikichannel/adapter-pikiloom.ts — the reference {@link SessionSource}.
+ *
+ * Binds the universal protocol to pikiloom's live runtime *without touching the
+ * bot*. It is a peer consumer of the very same surfaces the Web Dashboard uses:
+ *   - data plane: the `runtime.events` 'dashboard-event' bus (same bus the
+ *     dashboard WebSocket layer listens to). We must NOT call
+ *     `bot.onStreamSnapshot` — that is a single-slot callback already owned by
+ *     the runtime; re-registering it would silently break the dashboard.
+ *   - control plane: the exported session-control functions
+ *     (`queueDashboardSessionTask`, `stopSessionTasks`, …) — the same entry
+ *     points the dashboard REST routes call.
+ *
+ * The StreamSnapshot → UniversalSnapshot projection lives here, keeping the
+ * protocol package free of any pikiloom-internal type.
+ */
+import { EventEmitter } from 'node:events';
+import { runtime } from '../dashboard/runtime.js';
+import { queueDashboardSessionTask, stopSessionTasks, steerSessionTask, cancelSessionTask, interactionSelectOption, interactionSubmitText, interactionSkip, interactionCancel, } from '../dashboard/session-control.js';
+import { loadUserConfig } from '../core/config/user-config.js';
+import { VERSION } from '../core/version.js';
+const CAPABILITIES = ['prompt', 'stop', 'steer', 'recall', 'interact', 'subscribe-all', 'artifacts', 'tunnel'];
+function splitKey(sessionKey) {
+    const idx = sessionKey.indexOf(':');
+    if (idx < 0)
+        return { agent: '', sessionId: sessionKey };
+    return { agent: sessionKey.slice(0, idx), sessionId: sessionKey.slice(idx + 1) };
+}
+function projectInteractions(snap) {
+    if (!snap.interactions?.length)
+        return undefined;
+    return snap.interactions.map((it) => ({
+        promptId: it.promptId,
+        kind: it.kind,
+        title: it.title,
+        hint: it.hint,
+        currentIndex: it.currentIndex,
+        questions: (it.questions || []).map((q) => ({
+            id: String(q.id),
+            text: String(q.text ?? q.label ?? ''),
+            type: q.type,
+            choices: Array.isArray(q.choices)
+                ? q.choices.map((c) => ({ label: String(c.label ?? c), description: c.description }))
+                : undefined,
+        })),
+    }));
+}
+/** Strip empty optionals so the projection is lean AND deterministic (the diff
+ *  baseline must be stable: a field is either consistently present or absent). */
+function compact(obj) {
+    for (const k of Object.keys(obj)) {
+        const v = obj[k];
+        const emptyArr = Array.isArray(v) && v.length === 0;
+        const emptyObj = v && typeof v === 'object' && !Array.isArray(v) && Object.keys(v).length === 0;
+        if (v === null || v === undefined || v === '' || emptyArr || emptyObj)
+            delete obj[k];
+    }
+    return obj;
+}
+/** Project pikiloom's StreamSnapshot into the agent-agnostic wire snapshot. */
+export function projectSnapshot(sessionKey, snap) {
+    const { agent } = splitKey(sessionKey);
+    const meta = snap.previewMeta;
+    return compact({
+        phase: snap.phase,
+        taskId: snap.taskId ?? undefined,
+        agent: agent || undefined,
+        model: snap.model ?? undefined,
+        effort: snap.effort ?? undefined,
+        prompt: snap.question ?? undefined,
+        text: snap.text || undefined,
+        reasoning: snap.thinking || undefined,
+        activity: snap.activity || undefined,
+        plan: snap.plan
+            ? { explanation: snap.plan.explanation, steps: snap.plan.steps.map((s) => ({ text: s.step, status: s.status })) }
+            : undefined,
+        toolCalls: meta?.toolCalls?.map((t) => ({
+            id: t.id, name: t.name, summary: t.summary, input: t.input, result: t.result, status: t.status,
+        })),
+        subAgents: meta?.subAgents?.map((s) => ({
+            id: s.id, kind: s.kind, description: s.description, model: s.model, tools: s.tools, status: s.status,
+        })),
+        usage: meta
+            ? compact({
+                inputTokens: meta.inputTokens,
+                outputTokens: meta.outputTokens,
+                cachedInputTokens: meta.cachedInputTokens,
+                contextUsedTokens: meta.contextUsedTokens,
+                contextPercent: meta.contextPercent,
+                turnOutputTokens: meta.turnOutputTokens,
+                providerName: meta.providerName,
+                generatingImages: meta.generatingImages,
+            })
+            : undefined,
+        artifacts: snap.artifacts,
+        interactions: projectInteractions(snap),
+        queued: snap.queuedTasks?.length ? snap.queuedTasks.map((q) => ({ taskId: q.taskId, prompt: q.prompt })) : undefined,
+        error: snap.error ?? undefined,
+        ...(snap.incomplete ? { incomplete: true } : {}),
+        startedAt: snap.startedAt,
+        updatedAt: snap.updatedAt,
+    });
+}
+function metaFromSnapshot(sessionKey, snap) {
+    const title = (snap.prompt || snap.text || '').slice(0, 80) || null;
+    return { sessionKey, agent: snap.agent, title, phase: snap.phase, updatedAt: snap.updatedAt };
+}
+/**
+ * The pikiloom SessionSource. One instance per process; it attaches to the
+ * runtime event bus lazily on first `onUpdate`.
+ */
+export class PikiloomSessionSource {
+    forwarder;
+    seqs = new Map();
+    known = new Map();
+    bus = new EventEmitter();
+    wired = false;
+    /** @param forwarder forwards tunneled `/api/*` requests to the HTTP router. */
+    constructor(forwarder) {
+        this.forwarder = forwarder;
+    }
+    hostInfo() {
+        return { name: 'pikiloom', version: VERSION, capabilities: CAPABILITIES, authRequired: true };
+    }
+    /** Control-plane HTTP tunnel — delegates to the embedder-supplied forwarder
+     *  (the dashboard's Hono router). The host has already enforced auth + the
+     *  `/api/*` allowlist before we get here. */
+    async handleRequest(req) {
+        if (!this.forwarder)
+            return { status: 503, body: 'tunnel forwarder not configured' };
+        return this.forwarder(req);
+    }
+    listSessions() {
+        // Most-recent first, bounded so a long-lived host never ships an unbounded
+        // list over the wire (remote clients want a recent picker, not all history).
+        return Array.from(this.known.values()).sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0)).slice(0, 50);
+    }
+    getSnapshot(sessionKey) {
+        const bot = runtime.getBotRef();
+        const raw = bot?.getStreamSnapshot(sessionKey);
+        if (!raw)
+            return null;
+        return { snapshot: projectSnapshot(sessionKey, raw), seq: this.seqs.get(sessionKey) || 0 };
+    }
+    onUpdate(cb) {
+        this.ensureWired();
+        const handler = (k, s, seq) => cb(k, s, seq);
+        this.bus.on('update', handler);
+        return () => this.bus.off('update', handler);
+    }
+    onSessionsChanged(cb) {
+        this.ensureWired();
+        const handler = () => cb(this.listSessions());
+        this.bus.on('sessions', handler);
+        return () => this.bus.off('sessions', handler);
+    }
+    /** Subscribe once to the runtime's dashboard-event bus and fan out internally. */
+    ensureWired() {
+        if (this.wired)
+            return;
+        this.wired = true;
+        runtime.events.on('dashboard-event', (event) => {
+            if (event.type === 'stream-update' && event.key && event.snapshot) {
+                const snapshot = projectSnapshot(event.key, event.snapshot);
+                const seq = (this.seqs.get(event.key) || 0) + 1;
+                this.seqs.set(event.key, seq);
+                this.known.set(event.key, metaFromSnapshot(event.key, snapshot));
+                this.bus.emit('update', event.key, snapshot, seq);
+            }
+            else if (event.type === 'sessions-changed') {
+                this.bus.emit('sessions');
+            }
+        });
+    }
+    // -- control plane (delegates to the shared session-control surface) -----
+    async prompt(cmd) {
+        const config = loadUserConfig();
+        const workdir = cmd.workdir || runtime.getRequestWorkdir(config);
+        const agent = cmd.agent || runtime.getRuntimeDefaultAgent(config);
+        const sessionId = cmd.sessionKey ? splitKey(cmd.sessionKey).sessionId : '';
+        const res = await queueDashboardSessionTask({
+            workdir,
+            agent,
+            sessionId,
+            prompt: cmd.prompt,
+            model: cmd.model,
+            effort: cmd.effort,
+            workflow: cmd.workflow,
+            attachments: cmd.attachments,
+        });
+        if (!res?.ok)
+            return { ok: false, error: res?.error || 'submit failed' };
+        return { ok: true, sessionKey: res.sessionKey, taskId: res.taskId };
+    }
+    stop(sessionKey) {
+        const { agent, sessionId } = splitKey(sessionKey);
+        const r = stopSessionTasks(agent, sessionId);
+        return r?.ok ? { ok: true } : { ok: false, error: r?.error || 'stop failed' };
+    }
+    async steer(taskId) {
+        const r = await steerSessionTask(taskId);
+        return r?.ok ? { ok: true } : { ok: false, error: r?.error || 'steer failed' };
+    }
+    recall(taskId) {
+        const r = cancelSessionTask(taskId);
+        return r?.ok ? { ok: true } : { ok: false, error: r?.error || 'recall failed' };
+    }
+    interact(promptId, action, value, requestFreeform) {
+        let r;
+        if (action === 'select')
+            r = interactionSelectOption(promptId, value || '', { requestFreeform });
+        else if (action === 'text')
+            r = interactionSubmitText(promptId, value || '');
+        else if (action === 'skip')
+            r = interactionSkip(promptId);
+        else
+            r = interactionCancel(promptId);
+        return r?.ok ? { ok: true } : { ok: false, error: r?.error || 'interaction failed' };
+    }
+}

package/dist/pikichannel/code.js

@@ -0,0 +1,35 @@
+/**
+ * pikichannel/code.ts — the shareable connection code (server side).
+ *
+ * One short string a host shows and a client pastes. Same format the browser
+ * `endpoint.ts` decodes — keep the keys (h/r/n/t) in lockstep:
+ *   h = direct host authority   r = rendezvous URL   n = nodeId   t = token
+ *
+ * `buildServerCode` picks the best reachability for THIS host:
+ *   - public address set → DIRECT code {h,t}     (public-IP server; no NAT hop)
+ *   - else rendezvous on → REMOTE code {r,n,t}   (NAT traversal)
+ *   - else                → none                 (only reachable locally)
+ */
+export function encodeConnectionCode(d) {
+    const lean = {};
+    if (d.host)
+        lean.h = d.host;
+    if (d.rendezvous)
+        lean.r = d.rendezvous;
+    if (d.nodeId)
+        lean.n = d.nodeId;
+    if (d.token)
+        lean.t = d.token;
+    return Buffer.from(JSON.stringify(lean), 'utf8').toString('base64url');
+}
+export function buildServerCode(opts) {
+    const token = (opts.token || '').trim();
+    const publicHost = (opts.publicHost || '').trim();
+    const rendezvous = (opts.rendezvous || '').trim();
+    const nodeId = (opts.nodeId || '').trim();
+    if (publicHost)
+        return { mode: 'direct', code: encodeConnectionCode({ host: publicHost, token }), detail: publicHost };
+    if (rendezvous && nodeId)
+        return { mode: 'remote', code: encodeConnectionCode({ rendezvous, nodeId, token }), detail: rendezvous };
+    return { mode: 'none', code: '', detail: '' };
+}

package/dist/pikichannel/codec.js

@@ -0,0 +1,50 @@
+/**
+ * pikichannel/codec.ts — frame (de)serialization for the L2 protocol.
+ *
+ * The transport layer (L1) moves opaque frames; this module is the only place
+ * that knows how a {@link ServerMessage} / {@link ClientMessage} becomes a frame
+ * and back. Today that is newline-free JSON text. The indirection is deliberate:
+ * swapping to a binary codec (CBOR / protobuf) later is a change here alone, with
+ * the wire-format tag negotiated in the handshake — no transport or host edits.
+ */
+export const DEFAULT_WIRE_FORMAT = 'json';
+/** Encode a host→client message into a transport frame. */
+export function encodeServer(msg, _fmt = DEFAULT_WIRE_FORMAT) {
+    return JSON.stringify(msg);
+}
+/** Encode a client→host message into a transport frame. */
+export function encodeClient(msg, _fmt = DEFAULT_WIRE_FORMAT) {
+    return JSON.stringify(msg);
+}
+/** Coerce a transport frame (string / Buffer / ArrayBuffer) into text. */
+function frameToText(raw) {
+    if (typeof raw === 'string')
+        return raw;
+    if (Buffer.isBuffer(raw))
+        return raw.toString('utf8');
+    return Buffer.from(new Uint8Array(raw)).toString('utf8');
+}
+/** Decode a client→host frame. Returns null on malformed input (never throws). */
+export function decodeClient(raw, _fmt = DEFAULT_WIRE_FORMAT) {
+    try {
+        const value = JSON.parse(frameToText(raw));
+        if (!value || typeof value !== 'object' || typeof value.type !== 'string')
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+/** Decode a host→client frame. Returns null on malformed input (never throws). */
+export function decodeServer(raw, _fmt = DEFAULT_WIRE_FORMAT) {
+    try {
+        const value = JSON.parse(frameToText(raw));
+        if (!value || typeof value !== 'object' || typeof value.type !== 'string')
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}

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';
+}