pikiloom 0.4.26 → 0.4.28

package/dist/model/provider-models.js

@@ -1,29 +1,6 @@
-/**
- * Provider model-list cache.
- *
- * Backs the GET /api/models/providers/:id/models endpoint and the agent-status
- * + IM /models surfaces. Each entry is a list of model ids the provider's
- * /models endpoint reported, plus a fetch timestamp for TTL invalidation.
- *
- * Cache is in-memory only — providers' validation state already persists in
- * setting.json; the model list itself can be re-fetched cheaply on demand.
- */
 import { getProvider } from './store.js';
 import { validateProvider } from './validation.js';
-const TTL_MS = 30 * 60 * 1000; // 30 minutes
-// Cache is pinned to globalThis so module re-instantiation under tsx ESM
-// (e.g. when the same file is imported via different specifier strings) can't
-// fragment it into multiple disjoint maps. Without this, `getProviderModelList`
-// from `dashboard/routes/models.ts` (barrel) and `peekProviderModelList` from
-// `dashboard/routes/agents.ts` (also barrel) were writing/reading two
-// different Map instances, making the peek perpetually miss.
-// Cache pinned to globalThis so module re-instantiation under tsx ESM
-// (where the same file imported via different specifier strings ends up as
-// separate ESM module instances) can't fragment it into multiple disjoint
-// maps. Without this, `getProviderModelList` from `dashboard/routes/models.ts`
-// and `peekProviderModelList` from `dashboard/routes/agents.ts` would be
-// writing/reading two different Map instances and the peek would
-// perpetually miss.
+const TTL_MS = 30 * 60 * 1000;
 const GLOBAL_KEY = Symbol.for('pikiloom.providerModelsCache');
 const _existing = globalThis[GLOBAL_KEY];
 const cache = _existing || new Map();
@@ -34,10 +11,6 @@ function isFresh(entry, provider) {
         return false;
     return (Date.now() - entry.fetchedAt) < TTL_MS;
 }
-/**
- * Get the model list for a provider, fetching from /models on cache miss or
- * when the provider config has been updated since the last fetch.
- */
 export async function getProviderModelList(providerId, opts = {}) {
     const provider = getProvider(providerId);
     if (!provider)
@@ -66,19 +39,9 @@ export async function getProviderModelList(providerId, opts = {}) {
         fromCache: false,
     };
 }
-/**
- * Invalidate cached model list (e.g. after a provider edit/delete).
- */
 export function invalidateProviderModels(providerId) {
     cache.delete(providerId);
 }
-/**
- * Synchronous peek for a single model's cached metadata (context length,
- * pricing). Returns `null` on cache miss or when the entry is stale relative
- * to the provider's `updatedAt` — callers should treat that as "unknown" and
- * fall back to whatever the agent CLI reports. Pair with
- * `prefetchProviderModels` to populate the cache lazily for the next call.
- */
 export function peekProviderModelInfo(providerId, modelId) {
     const provider = getProvider(providerId);
     if (!provider)
@@ -88,11 +51,6 @@ export function peekProviderModelInfo(providerId, modelId) {
         return null;
     return entry.modelInfos.find(info => info.id === modelId) ?? null;
 }
-/**
- * Synchronous peek for the full cached model list of a provider. Returns
- * `null` on cache miss / stale entry — callers should fall back and let a
- * background refresh populate it (`prefetchProviderModels`).
- */
 export function peekProviderModelList(providerId) {
     const provider = getProvider(providerId);
     if (!provider)
@@ -102,11 +60,6 @@ export function peekProviderModelList(providerId) {
         return null;
     return entry.modelInfos;
 }
-/**
- * Fire-and-forget cache fill. Safe to call repeatedly: no-ops when the cache
- * is already fresh, otherwise triggers a single in-flight fetch and discards
- * the result (the next sync peek will see the populated cache).
- */
 export function prefetchProviderModels(providerId) {
     void getProviderModelList(providerId).catch(() => { });
 }

package/dist/model/responses-bridge.js

@@ -1,27 +1,3 @@
-/**
- * Responses↔Chat bridge.
- *
- * Codex 0.140+ speaks ONLY the OpenAI Responses API (`wire_api = "chat"` was
- * removed). Many OpenAI-compatible providers — DeepSeek, Kimi/Moonshot,
- * MiniMax, 豆包/Doubao, Qwen/DashScope, Zhipu, … — implement ONLY the Chat
- * Completions API. This in-process HTTP server bridges the two so codex can
- * drive any chat-only provider:
- *
- *   codex ──(Responses API)──▶ bridge ──(Chat Completions)──▶ upstream provider
- *
- * One server instance routes every upstream: the upstream base URL is encoded
- * (base64url) into the request path (`/u/<token>/responses`). The caller's
- * Authorization header is forwarded verbatim, so the bridge never reads or
- * stores credentials — codex injects `Authorization: Bearer <key>` from the
- * provider's `env_key`, and we relay it upstream.
- *
- * Translation is intentionally NON-incremental: we call the upstream with
- * `stream:false`, then synthesise a complete, spec-shaped Responses SSE stream.
- * Codex rebuilds a turn from `response.output_item.done` items plus the final
- * `response.completed`, so a fully-populated terminal payload is authoritative;
- * this sidesteps fragile per-token delta bookkeeping while still surfacing
- * assistant text AND tool/function calls (apply_patch, shell, MCP tools).
- */
 import http from 'node:http';
 import { writeScopedLog } from '../core/logging.js';
 const SCOPE = 'model-bridge';
@@ -36,7 +12,6 @@ function genId(prefix) {
     return `${prefix}_${Date.now().toString(36)}${idCounter.toString(36)}`;
 }
 function num(v) { return typeof v === 'number' && Number.isFinite(v) ? v : 0; }
-/** base64url-encode an upstream base URL so it survives as a single path segment. */
 export function upstreamToken(baseURL) {
     return Buffer.from(baseURL, 'utf8').toString('base64url');
 }
@@ -48,7 +23,6 @@ function decodeUpstream(token) {
         return null;
     }
 }
-/** Start (or reuse) the singleton bridge server; resolves to its localhost port. */
 export async function ensureResponsesBridge() {
     if (server && listenPort)
         return listenPort;
@@ -76,13 +50,10 @@ export function shutdownResponsesBridge() {
     try {
         server?.close();
     }
-    catch { /* ignore */ }
+    catch { }
     server = null;
     listenPort = 0;
 }
-// ---------------------------------------------------------------------------
-// HTTP handling
-// ---------------------------------------------------------------------------
 function handleRequest(req, res) {
     const url = new URL(req.url || '/', 'http://127.0.0.1');
     const m = url.pathname.match(/^\/u\/([^/]+)\/(responses|models)$/);
@@ -96,8 +67,6 @@ function handleRequest(req, res) {
         return;
     }
     if (m[2] === 'models') {
-        // Codex's model-catalog refresh is best-effort; an empty list keeps it quiet
-        // and never blocks the turn.
         res.writeHead(200, { 'content-type': 'application/json' });
         res.end(JSON.stringify({ object: 'list', data: [], models: [] }));
         return;
@@ -148,11 +117,6 @@ async function handleResponses(req, res, upstreamBase, body) {
         sendResponsesError(res, `upstream ${upstreamResp.status}: ${raw.slice(0, 500)}`);
         return;
     }
-    // Forward the upstream Chat Completions SSE incrementally, translating each
-    // delta into Responses events, so codex (and the dashboard) render the answer
-    // progressively — token-by-token — instead of popping it in at once. Codex
-    // still rebuilds the turn from the terminal `response.output_item.done` +
-    // `response.completed`, which we always emit.
     res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
     res.flushHeaders?.();
     let seq = 0;
@@ -285,7 +249,7 @@ function sendResponsesError(res, message) {
         try {
             res.end();
         }
-        catch { /* ignore */ }
+        catch { }
         return;
     }
     res.writeHead(200, {
@@ -300,9 +264,6 @@ function sendResponsesError(res, message) {
     emit({ type: 'response.failed', response: { id, object: 'response', status: 'failed', error: { code: 'bridge_error', message }, output: [] } });
     res.end();
 }
-// ---------------------------------------------------------------------------
-// Request translation: Responses → Chat Completions
-// ---------------------------------------------------------------------------
 function asText(content) {
     if (typeof content === 'string')
         return content;
@@ -352,7 +313,6 @@ function toChatRequest(body) {
             });
         }
         else if (type === 'reasoning') {
-            // Chat models cannot ingest prior reasoning items — drop.
         }
     }
     const tools = Array.isArray(body.tools)
@@ -388,13 +348,11 @@ function toChatTool(t) {
             },
         };
     }
-    // Codex built-in custom tools (e.g. local_shell) and web_search aren't
-    // expressible as chat functions — drop; codex falls back to its function tools.
     return null;
 }
 function toChatToolChoice(tc) {
     if (typeof tc === 'string')
-        return tc; // auto | none | required
+        return tc;
     if (tc?.type === 'function' && tc.name)
         return { type: 'function', function: { name: tc.name } };
     if (tc?.type === 'function' && tc.function)

package/dist/model/store.js

@@ -1,13 +1,6 @@
-/**
- * Persistence for Provider / Profile / activeProfileByAgent.
- * Reads and writes the `models` section of ~/.pikiloom/setting.json.
- */
 import { randomUUID } from 'node:crypto';
 import { loadUserConfig, saveUserConfig } from '../core/config/user-config.js';
 import { persistSecret, forgetSecret } from '../core/secrets/index.js';
-// ---------------------------------------------------------------------------
-// Read helpers
-// ---------------------------------------------------------------------------
 function getModelLayer() {
     const config = loadUserConfig();
     return config.models || {};
@@ -62,11 +55,9 @@ export async function updateProvider(id, patch) {
         credential = patch.credentialRef;
     else if (patch.apiKey !== undefined) {
         if (existing.credential.source === 'keychain') {
-            // overwrite same keychain slot
             credential = await persistSecret(existing.credential.account, patch.apiKey);
         }
         else {
-            // upgrade from inline/env/command to keychain
             credential = await persistSecret(`provider/${id}`, patch.apiKey);
         }
     }
@@ -92,13 +83,11 @@ export async function removeProvider(id) {
     if (!existing)
         return false;
     delete providers[id];
-    // also drop any profiles bound to this provider
     const profiles = { ...(layer.profiles || {}) };
     for (const [pid, prof] of Object.entries(profiles)) {
         if (prof.providerId === id)
             delete profiles[pid];
     }
-    // and any active bindings
     const bindings = { ...(layer.activeProfileByAgent || {}) };
     for (const agentId of Object.keys(bindings)) {
         const profileId = bindings[agentId];
@@ -127,9 +116,6 @@ export function getProfile(id) {
     return layer.profiles?.[id] || null;
 }
 function defaultProfileName(_providerName, modelId, _effort) {
-    // Keep the auto-generated label short: the brand icon already carries the
-    // provider, and effort lives in its own pill on the card. Just the model id
-    // gives the cleanest tile + IM list, with the user free to override.
     return modelId;
 }
 export function addProfile(input) {
@@ -188,9 +174,6 @@ export function removeProfile(id) {
     writeModelLayer({ ...layer, profiles, activeProfileByAgent: bindings });
     return true;
 }
-// ---------------------------------------------------------------------------
-// Active binding
-// ---------------------------------------------------------------------------
 export function getActiveProfileId(agentId) {
     const layer = getModelLayer();
     return layer.activeProfileByAgent?.[agentId] || null;

package/dist/model/types.js

@@ -1,13 +1 @@
-/**
- * Pikiloom "Model" layer — Provider/Profile data model.
- *
- *   Provider  = a configured endpoint + credential reference (e.g. "OpenRouter
- *               personal", "Anthropic direct"). Holds baseURL + extra headers.
- *   Profile   = a Provider + modelId + tuning params (effort, max output).
- *               This is the unit a user binds to an agent.
- *
- * Profiles are the smallest selectable unit because Hermes (and most coding
- * agents) only support one model per session. Binding `activeProfileByAgent`
- * tells the driver which Profile to use when spawning that agent.
- */
 export {};

package/dist/model/validation.js

@@ -1,10 +1,3 @@
-/**
- * Provider credential validation — Feishu-style explicit check.
- *
- * Validation strategy: GET ${baseURL}/models with the resolved API key.
- * Status semantics mirror ChannelSetupState in core/config/validation.ts:
- *   missing | invalid | error | ready
- */
 import { request } from 'undici';
 import { resolveCredential } from '../core/secrets/index.js';
 const VALIDATION_TIMEOUT_MS = 10_000;
@@ -12,13 +5,10 @@ function buildHeaders(provider, apiKey) {
     const base = { 'Accept': 'application/json' };
     switch (provider.kind) {
         case 'anthropic':
-            // Anthropic models endpoint is /v1/models with x-api-key + anthropic-version
             base['x-api-key'] = apiKey;
             base['anthropic-version'] = '2023-06-01';
             break;
         case 'google':
-            // Google AI Studio uses ?key= query param, not Authorization header.
-            // Caller appends ?key= in URL builder below.
             break;
         case 'openai':
         case 'openai-compatible':
@@ -33,14 +23,12 @@ function buildHeaders(provider, apiKey) {
 function modelsUrl(provider, apiKey) {
     const base = provider.baseURL.replace(/\/+$/, '');
     if (provider.kind === 'google') {
-        // Google AI Studio: GET https://generativelanguage.googleapis.com/v1beta/models?key=API_KEY
         const sep = base.includes('?') ? '&' : '?';
         return `${base}/models${sep}key=${encodeURIComponent(apiKey)}`;
     }
     if (provider.kind === 'anthropic') {
         return `${base}/v1/models`;
     }
-    // OpenAI-compatible
     return `${base}/models`;
 }
 function toNumber(value) {
@@ -53,11 +41,6 @@ function toNumber(value) {
     }
     return undefined;
 }
-/**
- * Convert a per-token USD price (the format OpenRouter & most OpenAI-compatible
- * APIs use) to USD per 1M tokens. We preserve up to 4 decimals so micro-prices
- * don't round to zero.
- */
 function perTokenToPerMillion(value) {
     const n = toNumber(value);
     if (n === undefined)
@@ -177,7 +160,7 @@ export async function validateProvider(provider) {
     try {
         parsed = JSON.parse(bodyText);
     }
-    catch { /* unparsed body — still treat 2xx as ready */ }
+    catch { }
     const modelInfos = extractModelInfos(parsed);
     const models = modelInfos.map(info => info.id);
     return {

package/dist/pikichannel/adapter-pikiloom.js

@@ -1,19 +1,3 @@
-/**
- * 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';
@@ -45,8 +29,6 @@ function projectInteractions(snap) {
         })),
     }));
 }
-/** 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];
@@ -57,7 +39,6 @@ function compact(obj) {
     }
     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;
@@ -105,34 +86,24 @@ 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) {
@@ -154,7 +125,6 @@ export class PikiloomSessionSource {
         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;
@@ -172,7 +142,6 @@ export class PikiloomSessionSource {
             }
         });
     }
-    // -- control plane (delegates to the shared session-control surface) -----
     async prompt(cmd) {
         const config = loadUserConfig();
         const workdir = cmd.workdir || runtime.getRequestWorkdir(config);

package/dist/pikichannel/code.js

@@ -1,15 +1,3 @@
-/**
- * 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)

package/dist/pikichannel/codec.js

@@ -1,22 +1,10 @@
-/**
- * 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;
@@ -24,7 +12,6 @@ function frameToText(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));
@@ -36,7 +23,6 @@ export function decodeClient(raw, _fmt = DEFAULT_WIRE_FORMAT) {
         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));

package/dist/pikichannel/host.js

@@ -1,19 +1,3 @@
-/**
- * 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 = '*';
@@ -24,7 +8,6 @@ export class PikichannelHost {
     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 = () => { }) {
@@ -32,7 +15,6 @@ export class PikichannelHost {
         this.authenticate = authenticate;
         this.log = log;
     }
-    /** Wire host-level subscriptions to the source (once). */
     start() {
         if (this.started)
             return;
@@ -45,20 +27,19 @@ export class PikichannelHost {
             try {
                 u();
             }
-            catch { /* ignore */ }
+            catch { }
         }
         for (const peer of this.peers) {
             try {
                 peer.conn.close();
             }
-            catch { /* ignore */ }
+            catch { }
         }
         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();
@@ -78,7 +59,6 @@ export class PikichannelHost {
             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 };
@@ -90,7 +70,6 @@ export class PikichannelHost {
                 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);
@@ -105,9 +84,7 @@ export class PikichannelHost {
         }
         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;
@@ -145,7 +122,7 @@ export class PikichannelHost {
         }
         switch (msg.type) {
             case 'hello':
-                return; // already authenticated; ignore duplicate hello
+                return;
             case 'subscribe': {
                 peer.subs.add(msg.sessionKey);
                 if (msg.sessionKey === SUBSCRIBE_ALL) {
@@ -207,9 +184,6 @@ export class PikichannelHost {
             }
             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;
@@ -229,7 +203,6 @@ export class PikichannelHost {
             }
         }
     }
-    // -- outbound ------------------------------------------------------------
     broadcast(frame, authedOnly = false) {
         for (const peer of this.peers)
             if (!authedOnly || peer.authed)
@@ -241,11 +214,9 @@ export class PikichannelHost {
         try {
             peer.conn.send(encodeServer(frame));
         }
-        catch { /* drop on closed pipe */ }
+        catch { }
     }
-    /** 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

@@ -1,58 +1,10 @@
-/**
- * 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;
@@ -84,7 +36,6 @@ export function diffSnapshot(prev, next) {
         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;
@@ -97,9 +48,6 @@ export function applySnapshotPatch(prev, patch) {
         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';
 }