pikiloom 0.4.21 → 0.4.23

package/dist/dashboard/server.js

@@ -9,7 +9,6 @@ import { serveStatic } from '@hono/node-server/serve-static';
 import path from 'node:path';
 import fs from 'node:fs';
 import { exec } from 'node:child_process';
-import { WebSocketServer } from 'ws';
 import configRoutes from './routes/config.js';
 import agentRoutes, { preloadAgentStatus } from './routes/agents.js';
 import sessionRoutes from './routes/sessions.js';
@@ -19,67 +18,15 @@ import modelsRoutes from './routes/models.js';
 import localModelsRoutes from './routes/local-models.js';
 import { runtime } from './runtime.js';
 import { registerProcessRuntime } from '../core/process-control.js';
+import { mountPikichannel } from '../pikichannel/server.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 const DASHBOARD_PORT_RETRY_LIMIT = 10;
-const WS_KEEPALIVE_MS = 25_000;
-function attachWebSocketServer(httpServer) {
-    const wss = new WebSocketServer({ noServer: true });
-    const clients = new Set();
-    httpServer.on('upgrade', (req, socket, head) => {
-        const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
-        if (url.pathname !== '/ws') {
-            socket.destroy();
-            return;
-        }
-        wss.handleUpgrade(req, socket, head, (ws) => {
-            wss.emit('connection', ws, req);
-        });
-    });
-    wss.on('connection', (ws) => {
-        clients.add(ws);
-        const keepalive = setInterval(() => {
-            if (ws.readyState === ws.OPEN)
-                ws.ping();
-        }, WS_KEEPALIVE_MS);
-        ws.on('message', (raw) => {
-            try {
-                const msg = JSON.parse(String(raw));
-                if (msg?.type === 'ping') {
-                    ws.send(JSON.stringify({ type: 'pong' }));
-                }
-            }
-            catch { /* ignore malformed messages */ }
-        });
-        ws.on('close', () => {
-            clients.delete(ws);
-            clearInterval(keepalive);
-        });
-        ws.on('error', () => {
-            clients.delete(ws);
-            clearInterval(keepalive);
-        });
-    });
-    const onEvent = (event) => {
-        const data = JSON.stringify(event);
-        for (const ws of clients) {
-            if (ws.readyState === ws.OPEN) {
-                ws.send(data);
-            }
-        }
-    };
-    runtime.events.on('dashboard-event', onEvent);
-    const closeAllClients = () => {
-        runtime.events.off('dashboard-event', onEvent);
-        for (const ws of clients)
-            ws.close();
-        clients.clear();
-        wss.close();
-    };
-    httpServer.on('close', closeAllClients);
-    return { closeAllClients };
-}
+// The dashboard's live push transport is pikichannel (`/pikichannel/ws`) — the
+// same universal channel mobile/web clients use. There is no separate dashboard
+// WebSocket layer anymore; the pikichannel adapter subscribes to the runtime
+// 'dashboard-event' bus directly, so the SPA and remote clients share one stack.
 // ---------------------------------------------------------------------------
 // Server
 // ---------------------------------------------------------------------------
@@ -103,6 +50,17 @@ export async function startDashboard(opts = {}) {
     app.route('/', cliRoutes);
     app.route('/', modelsRoutes);
     app.route('/', localModelsRoutes);
+    // -- pikichannel: pluggable agent-session transport (WebSocket + WebRTC) --
+    // Mounted BEFORE the static catch-all so its routes (demo page, browser SDK,
+    // status) win. Returns a handle whose upgrade router is attached per HTTP
+    // server below. Failure here must not block the dashboard, so it is guarded.
+    let pikichannel = null;
+    try {
+        pikichannel = await mountPikichannel(app);
+    }
+    catch (err) {
+        runtime.warn(`[pikichannel] mount failed: ${err?.message || err}`);
+    }
     // -- Static files: serve dashboard build output --
     // Resolve path relative to this file's location (src/ or dist/)
     const dashboardRoot = path.resolve(import.meta.dirname, '..', '..', 'dashboard', 'dist');
@@ -149,7 +107,6 @@ export async function startDashboard(opts = {}) {
     });
     // -- Process runtime registration --
     let nodeServer = null;
-    let wsHandle = null;
     const RESTART_CLOSE_TIMEOUT_MS = 3000;
     const unregisterProcessRuntime = registerProcessRuntime({
         label: 'dashboard',
@@ -158,9 +115,9 @@ export async function startDashboard(opts = {}) {
                 resolve();
                 return;
             }
-            // Close all WebSocket clients first — otherwise server.close() hangs
-            // waiting for persistent connections to end.
-            wsHandle?.closeAllClients();
+            // Tear down pikichannel peers first — otherwise server.close() hangs
+            // waiting for the persistent WebSocket/datachannel connections to end.
+            pikichannel?.stop();
             const timer = setTimeout(resolve, RESTART_CLOSE_TIMEOUT_MS);
             nodeServer.close(() => { clearTimeout(timer); resolve(); });
         }),
@@ -181,8 +138,14 @@ export async function startDashboard(opts = {}) {
                 // before Hono's request listener consumes the connection.
                 const requestListener = getRequestListener(app.fetch);
                 const server = http.createServer(requestListener);
-                // Attach WebSocket BEFORE listening — ensures upgrade events are captured
-                wsHandle = attachWebSocketServer(server);
+                // Single WebSocket-upgrade dispatcher (attached before listening so no
+                // upgrade is missed): pikichannel owns `/pikichannel/*` — its WS data
+                // channel and WebRTC signaling. Anything else is rejected.
+                server.on('upgrade', (req, socket, head) => {
+                    if (pikichannel?.handleUpgrade(req, socket, head))
+                        return;
+                    socket.destroy();
+                });
                 server.listen(port, () => {
                     if (settled)
                         return;

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