@pimote/pimote 0.3.1 → 0.4.1

package/server/dist/static-host/registry.js

@@ -0,0 +1,58 @@
+/**
+ * Default in-memory implementation backed by a `Map<slug, StaticHostRegistration>`
+ * with a secondary `Map<sessionId, Set<slug>>` for fast `unregisterAllForSession`.
+ */
+export class InMemoryStaticHostRegistry {
+    bySlug = new Map();
+    bySession = new Map();
+    register(reg) {
+        if (this.bySlug.has(reg.slug)) {
+            throw new Error(`static-host slug already registered: ${reg.slug}`);
+        }
+        this.bySlug.set(reg.slug, reg);
+        let set = this.bySession.get(reg.sessionId);
+        if (!set) {
+            set = new Set();
+            this.bySession.set(reg.sessionId, set);
+        }
+        set.add(reg.slug);
+    }
+    unregister(slug) {
+        const entry = this.bySlug.get(slug);
+        if (!entry)
+            return;
+        this.bySlug.delete(slug);
+        const set = this.bySession.get(entry.sessionId);
+        if (set) {
+            set.delete(slug);
+            if (set.size === 0)
+                this.bySession.delete(entry.sessionId);
+        }
+    }
+    unregisterAllForSession(sessionId) {
+        const set = this.bySession.get(sessionId);
+        if (!set)
+            return;
+        for (const slug of set)
+            this.bySlug.delete(slug);
+        this.bySession.delete(sessionId);
+    }
+    lookup(slug) {
+        return this.bySlug.get(slug);
+    }
+    has(slug) {
+        return this.bySlug.has(slug);
+    }
+    listForSession(sessionId) {
+        const set = this.bySession.get(sessionId);
+        if (!set)
+            return [];
+        const out = [];
+        for (const slug of set) {
+            const entry = this.bySlug.get(slug);
+            if (entry)
+                out.push(entry);
+        }
+        return out;
+    }
+}

package/server/dist/static-host/store.js

@@ -0,0 +1,44 @@
+import { readFile, writeFile, mkdir, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Filesystem-backed `StaticHostStore`. One file per sessionId under `storeDir`.
+ */
+export class FileStaticHostStore {
+    storeDir;
+    constructor(storeDir) {
+        this.storeDir = storeDir;
+    }
+    pathFor(sessionId) {
+        return join(this.storeDir, `${sessionId}.json`);
+    }
+    async read(sessionId) {
+        const path = this.pathFor(sessionId);
+        let raw;
+        try {
+            raw = await readFile(path, 'utf-8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return undefined;
+            throw err;
+        }
+        return JSON.parse(raw);
+    }
+    async write(sessionId, file) {
+        await mkdir(this.storeDir, { recursive: true });
+        const finalPath = this.pathFor(sessionId);
+        const tmpPath = finalPath + '.tmp';
+        await writeFile(tmpPath, JSON.stringify(file, null, 2) + '\n', 'utf-8');
+        await rename(tmpPath, finalPath);
+    }
+    async remove(sessionId) {
+        try {
+            await unlink(this.pathFor(sessionId));
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return;
+            throw err;
+        }
+    }
+}

package/server/dist/static-host/tools.js

@@ -0,0 +1,120 @@
+import { stat } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+/**
+ * Validates and normalises a slug.
+ *
+ * Rules: lowercase alphanumerics and hyphens, no leading/trailing dash,
+ * non-empty, and a reasonable length cap (<= 64).
+ *
+ * Returns `null` if invalid.
+ */
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export function validateSlug(slug) {
+    if (typeof slug !== 'string')
+        return null;
+    if (slug.length === 0 || slug.length > 64)
+        return null;
+    if (!SLUG_RE.test(slug))
+        return null;
+    return slug;
+}
+/**
+ * Resolve a slug against the registry. Returns the input slug if it is free;
+ * otherwise appends `-2`, `-3`, ... until a free slug is found.
+ *
+ * The caller must have already validated the input slug via `validateSlug`.
+ */
+export function resolveSlugCollision(slug, registry) {
+    if (!registry.has(slug))
+        return slug;
+    for (let i = 2;; i++) {
+        const candidate = `${slug}-${i}`;
+        if (!registry.has(candidate))
+            return candidate;
+    }
+}
+/**
+ * Execute the `pimote_static_host` tool body.
+ *
+ * Throws on validation failure (invalid slug, missing folder, no index.html).
+ * On success: updates the in-memory list for the session, atomically rewrites
+ * the persistence file, calls `registry.register(...)`, and emits the panel
+ * snapshot.
+ *
+ * Concurrency assumption: pi serializes tool calls within a single session,
+ * so the read-modify-write sequence on `store` here is safe. If that ever
+ * changes (parallel tool execution per session), this body must be revisited
+ * — the existing read/write pair would race and the registry/disk could
+ * desync. Re-derive entries from `registry.listForSession(sessionId)` after
+ * `registry.register`, or add a per-session lock.
+ */
+export async function executeRegisterTool(input, deps) {
+    const validSlug = validateSlug(input.slug);
+    if (validSlug === null) {
+        throw new Error(`invalid slug: ${JSON.stringify(input.slug)}`);
+    }
+    if (typeof input.folder !== 'string' || !isAbsolute(input.folder)) {
+        throw new Error(`folder must be an absolute path: ${JSON.stringify(input.folder)}`);
+    }
+    let folderStat;
+    try {
+        folderStat = await stat(input.folder);
+    }
+    catch {
+        throw new Error(`folder does not exist: ${input.folder}`);
+    }
+    if (!folderStat.isDirectory()) {
+        throw new Error(`folder is not a directory: ${input.folder}`);
+    }
+    const indexPath = join(input.folder, 'index.html');
+    let indexStat;
+    try {
+        indexStat = await stat(indexPath);
+    }
+    catch {
+        throw new Error(`folder has no index.html: ${input.folder}`);
+    }
+    if (!indexStat.isFile()) {
+        throw new Error(`index.html is not a file: ${indexPath}`);
+    }
+    const resolved = resolveSlugCollision(validSlug, deps.registry);
+    const cardMetadata = {
+        title: input.title,
+        ...(input.tag !== undefined ? { tag: input.tag } : {}),
+        ...(input.color !== undefined ? { color: input.color } : {}),
+    };
+    const existing = (await deps.store.read(deps.sessionId)) ?? { version: 1, entries: [] };
+    const entries = [...existing.entries, { slug: resolved, folderPath: input.folder, cardMetadata }];
+    const file = { version: 1, entries };
+    await deps.store.write(deps.sessionId, file);
+    deps.registry.register({
+        slug: resolved,
+        folderPath: input.folder,
+        sessionId: deps.sessionId,
+        cardMetadata,
+    });
+    deps.emitPanelCards();
+    const url = `/s/${resolved}/`;
+    deps.emitNavigate(url);
+    return { slug: resolved, url };
+}
+/**
+ * Execute the `pimote_static_host_remove` tool body. Returns `{ removed: false }`
+ * when the slug is not owned by this session.
+ *
+ * Concurrency assumption: same as `executeRegisterTool` — relies on pi's
+ * per-session serialization of tool calls. If that changes, this body must
+ * be revisited.
+ */
+export async function executeRemoveTool(input, deps) {
+    const existing = deps.registry.lookup(input.slug);
+    if (!existing || existing.sessionId !== deps.sessionId) {
+        return { removed: false };
+    }
+    const file = (await deps.store.read(deps.sessionId)) ?? { version: 1, entries: [] };
+    const entries = file.entries.filter((e) => e.slug !== input.slug);
+    await deps.store.write(deps.sessionId, { version: 1, entries });
+    deps.registry.unregister(input.slug);
+    deps.emitPanelCards();
+    return { removed: true };
+}

package/server/dist/voice/index.js

@@ -16,7 +16,7 @@
 // messages because it was reset on the wrong event (a substring of
 // `assistantMessageEvent` that never fires inside `message_update`). The
 // FSM split + correct reset-on-message_start eliminates that bug class.
-import { Type } from '@sinclair/typebox';
+import { Type } from 'typebox';
 import { renderInterpreterPrompt } from './interpreter-prompt.js';
 import { createDefaultSpeechmuxClientFactory } from './speechmux-client.js';
 import { ensureIdleWithImplicitAbort } from './wait-for-idle.js';
@@ -168,6 +168,9 @@ export function createVoiceExtension(opts) {
                         client.onFrame((frame) => {
                             void dispatch({ type: 'ws:incoming', frame });
                         });
+                        client.onDisconnect(() => {
+                            void dispatch({ type: 'ws:disconnected' });
+                        });
                         await dispatch({ type: 'ws:opened' });
                     }
                     catch (err) {
@@ -191,7 +194,7 @@ export function createVoiceExtension(opts) {
                         console.warn('[voice] send_frame with no client — dropping', action.frame.type);
                         return;
                     }
-                    const preview = action.frame.type === 'token' ? action.frame.text.slice(0, 60) : null;
+                    const preview = action.frame.type === 'token' ? action.frame.text.slice(0, 60) : action.frame.type === 'error' ? action.frame.message.slice(0, 60) : null;
                     console.log('[voice_trace] send_frame', JSON.stringify({ type: action.frame.type, preview }));
                     try {
                         speechmuxClient.send(action.frame);
@@ -271,10 +274,6 @@ export function createVoiceExtension(opts) {
         // The `tool_call` hook is intentionally NOT registered. The streaming
         // reducer is the sole emitter of speak frames; bulk-emission via
         // tool_call was the source of the double-emit class of bugs.
-        //
-        // The `turn_end` safety net is also intentionally NOT registered.
-        // With per-speak `end` framing driven by `toolcall_end`, it was
-        // redundant and contributed to double-end emissions.
         pi.on('message_start', (event) => {
             // Only assistant messages reset the streaming state. User and
             // tool-result messages don't have content blocks we care about.
@@ -319,6 +318,32 @@ export function createVoiceExtension(opts) {
                     return;
             }
         });
+        pi.on('turn_end', (event) => {
+            if (state.lifecycle.kind !== 'active' || !speechmuxClient)
+                return;
+            const lastSpeakResult = [...event.toolResults].reverse().find((result) => result.toolName === 'speak');
+            if (!lastSpeakResult)
+                return;
+            try {
+                speechmuxClient.send(typeof lastSpeakResult.toolCallId === 'string' ? { type: 'floor_released', speak_id: lastSpeakResult.toolCallId } : { type: 'floor_released' });
+            }
+            catch (err) {
+                console.warn('[voice] speechmux send failed', 'floor_released', err);
+            }
+        });
+        pi.on('agent_end', (event) => {
+            if (state.lifecycle.kind !== 'active' || !speechmuxClient)
+                return;
+            const error = event.error;
+            if (typeof error !== 'string' || error.length === 0)
+                return;
+            try {
+                speechmuxClient.send({ type: 'error', message: error });
+            }
+            catch (err) {
+                console.warn('[voice] speechmux send failed', 'error', err);
+            }
+        });
         pi.on('context', (event, ctx) => {
             lastCtx = ctx;
             // The walkback reducer always runs walkBack (even when no rewrite

package/server/dist/voice/speechmux-client.js

@@ -10,8 +10,9 @@
  * Default `SpeechmuxClient` factory backed by the `ws` package. Opens a
  * WebSocket to `wsUrl` and routes incoming JSON text frames to registered
  * listeners. The LLM-WS protocol has no hello frame — the harness simply
- * connects and exchanges `user` / `token` / `end` / `abort` / `rollback`
- * frames (see speechmux/docs/llm-ws-protocol.md).
+ * connects and exchanges `user` / `token` / `end` / `floor_released` /
+ * `error` / `abort` / `rollback` frames (see
+ * speechmux/docs/llm-ws-protocol.md).
  *
  * Resolves once the socket is open. Rejects if the socket errors or closes
  * before opening.
@@ -28,10 +29,13 @@ export function createDefaultSpeechmuxClientFactory() {
         }
         const ws = new WsCtor(wsUrl);
         const listeners = new Set();
+        const disconnectListeners = new Set();
         // Buffer frames that arrive after `hello` but before the caller has had a
         // chance to attach an `onFrame` listener. Drained on the first attach.
         const pending = [];
         let closed = false;
+        let opened = false;
+        let disconnectNotified = false;
         // Install the message handler before resolving so frames sent between
         // open and the caller's onFrame attach are buffered instead of dropped.
         // See review finding 5 (speechmux-client race).
@@ -75,6 +79,7 @@ export function createDefaultSpeechmuxClientFactory() {
                 if (settled)
                     return;
                 settled = true;
+                opened = true;
                 cleanup();
                 resolve();
             };
@@ -101,8 +106,16 @@ export function createDefaultSpeechmuxClientFactory() {
             ws.once('open', onOpen);
             ws.once('error', onError);
         });
+        const notifyDisconnect = () => {
+            if (!opened || disconnectNotified)
+                return;
+            disconnectNotified = true;
+            for (const listener of disconnectListeners)
+                listener();
+        };
         ws.on('close', () => {
             closed = true;
+            notifyDisconnect();
         });
         return {
             send(frame) {
@@ -122,6 +135,10 @@ export function createDefaultSpeechmuxClientFactory() {
                 }
                 return () => listeners.delete(listener);
             },
+            onDisconnect(listener) {
+                disconnectListeners.add(listener);
+                return () => disconnectListeners.delete(listener);
+            },
             close() {
                 if (closed)
                     return;
@@ -144,7 +161,7 @@ function isIncomingFrame(value) {
         case 'user':
             return typeof v.text === 'string';
         case 'abort':
-            return true;
+            return v.reason === undefined || v.reason === 'user_speaking' || v.reason === 'barge_in' || v.reason === 'session_closed';
         case 'rollback':
             return typeof v.heard_text === 'string';
         default:

package/server/dist/voice-orchestrator-boot.js

@@ -1,12 +1,17 @@
 // Wire the VoiceOrchestrator together with its runtime dependencies at
 // server boot time. Kept separate from `index.ts` so the wiring is
-// testable (no network / child_process side-effects at import time) and
-// isolated from the plain HTTP/WS boot sequence.
-import { spawn } from 'node:child_process';
+// testable and isolated from the plain HTTP/WS boot sequence.
+//
+// Returns `null` when voice is not configured. Speechmux is treated as an
+// externally managed service (systemd, container, remote host, etc.); pimote
+// no longer spawns it as a sidecar.
 import { VoiceOrchestrator } from './voice-orchestrator.js';
+/** True iff the config has the URLs needed to bind a voice call. */
+export function isVoiceConfigured(config) {
+    return Boolean(config.voice?.speechmuxSignalUrl && config.voice?.speechmuxLlmWsUrl);
+}
 /**
  * Construct a VoiceOrchestrator backed by real seams:
- * - speechmux sidecar via `child_process.spawn`
  * - displacement = looks up current owner via clientRegistry and calls its
  *   `sendDisplacedEvent(sessionId)`
  *
@@ -14,10 +19,14 @@ import { VoiceOrchestrator } from './voice-orchestrator.js';
  * per-session TURN credentials are minted by speechmux and returned to the
  * PWA in its `/signal` `session` response. Pimote's orchestrator only
  * hands out the signalling URL.
+ *
+ * Returns `null` if voice is not configured \u2014 callers should skip all voice
+ * wiring in that case.
  */
 export function buildVoiceOrchestrator(args) {
     const { config, sessionManager, clientRegistry } = args;
-    let speechmuxProc = null;
+    if (!isVoiceConfigured(config))
+        return null;
     const busResolver = {
         getSlot: (sessionId) => sessionManager.getSlot(sessionId),
         getEventBus: (sessionId) => sessionManager.getSlot(sessionId)?.eventBusRef.current ?? null,
@@ -26,51 +35,6 @@ export function buildVoiceOrchestrator(args) {
         config,
         sessionManager,
         busResolver,
-        startSpeechmux: async () => {
-            const bin = config.voice?.speechmuxBinary;
-            if (!bin) {
-                console.log('[voice] speechmuxBinary not configured; assuming speechmux is externally managed (systemd, container, remote host, etc.)');
-                return;
-            }
-            if (speechmuxProc)
-                return;
-            speechmuxProc = spawn(bin, [], { stdio: ['ignore', 'inherit', 'inherit'] });
-            speechmuxProc.on('exit', (code, signal) => {
-                console.warn(`[voice] speechmux exited (code=${code}, signal=${signal})`);
-                speechmuxProc = null;
-            });
-            // NB: we do not wait for a ready marker here — speechmux emits readiness
-            // to its own logs. Callers should ensure startup ordering or implement a
-            // readiness probe as part of the Step 14 smoke.
-        },
-        stopSpeechmux: async () => {
-            if (!speechmuxProc)
-                return;
-            const proc = speechmuxProc;
-            speechmuxProc = null;
-            await new Promise((resolve) => {
-                const timer = setTimeout(() => {
-                    try {
-                        proc.kill('SIGKILL');
-                    }
-                    catch {
-                        /* ignore */
-                    }
-                    resolve();
-                }, 2000);
-                proc.once('exit', () => {
-                    clearTimeout(timer);
-                    resolve();
-                });
-                try {
-                    proc.kill('SIGTERM');
-                }
-                catch {
-                    clearTimeout(timer);
-                    resolve();
-                }
-            });
-        },
         displaceOwner: async (sessionId, _newOwner) => {
             const slot = sessionManager.getSlot(sessionId);
             const existingClientId = slot?.connection?.connectedClientId;

package/server/dist/voice-orchestrator.js

@@ -1,8 +1,10 @@
-// Voice orchestrator — owns the speechmux sidecar lifecycle and the per-call
-// bind dispatch. See docs/plans/voice-mode.md → "Voice orchestrator".
+// Voice orchestrator — owns per-call bind dispatch.
+// See docs/plans/voice-mode.md → "Voice orchestrator".
 //
-// This file defines the interface surface + a stub implementation. The impl
-// phase fills in start()/stop()/bindCall()/endCall() bodies.
+// Speechmux is treated as an externally managed service (systemd, container,
+// remote host, etc.). This orchestrator is only constructed when voice config
+// is present (`voice.speechmuxSignalUrl` + `voice.speechmuxLlmWsUrl`); when
+// it is absent, the server skips voice wiring entirely.
 /** Typed error carrying the discriminable reason code used in PimoteResponse.error. */
 export class CallBindError extends Error {
     code;
@@ -14,24 +16,12 @@ export class CallBindError extends Error {
 }
 export class VoiceOrchestrator {
     opts;
-    started = false;
     activeCalls = new Set();
     constructor(opts) {
         this.opts = opts;
     }
-    /** Spawns speechmux sidecar. Throws if it fails to start. */
-    async start() {
-        if (this.started)
-            return;
-        await this.opts.startSpeechmux();
-        this.started = true;
-    }
-    /** Kills speechmux. Idempotent. */
+    /** Drop all active-call bookkeeping. Idempotent. Called on server shutdown. */
     async stop() {
-        if (!this.started)
-            return;
-        await this.opts.stopSpeechmux();
-        this.started = false;
         this.activeCalls.clear();
     }
     /** Called by ws-handler for CallBindCommand. */
@@ -47,11 +37,9 @@ export class VoiceOrchestrator {
         if (alreadyOwned && args.force) {
             await this.opts.displaceOwner(args.sessionId, args.clientConnection);
         }
-        // Voice-disabled guard: if speechmux wiring isn't configured, fail the
-        // bind here rather than handing the client empty URLs. Speechmux is
-        // what mints the per-call TURN creds now (in the /signal `session`
-        // response) and what authenticates peers (via Cloudflare Access at the
-        // edge), so pimote no longer needs to mint anything.
+        // The orchestrator is only constructed when voice is configured, so
+        // these URLs are guaranteed present. Re-read them per call so live
+        // config edits (if/when supported) take effect on the next bind.
         const signalUrl = this.opts.config.voice?.speechmuxSignalUrl;
         const llmWsUrl = this.opts.config.voice?.speechmuxLlmWsUrl;
         if (!signalUrl || !llmWsUrl) {

package/shared/dist/protocol.d.ts

@@ -71,6 +71,8 @@ export interface PimoteAgentMessage {
      * these with an "interrupted" indicator rather than as empty bubbles.
      */
     aborted?: boolean;
+    /** Present on assistant messages whose turn failed before producing content. */
+    errorMessage?: string;
     [key: string]: unknown;
 }
 export type CardColor = 'accent' | 'success' | 'warning' | 'error' | 'muted';
@@ -88,6 +90,12 @@ export interface Card {
     };
     body?: BodySection[];
     footer?: string[];
+    /**
+     * Optional same-origin URL. When present, the client renders the entire
+     * card as a clickable link (same-tab navigation). No server-side validation
+     * — any string is allowed; the consumer is responsible for using a sane URL.
+     */
+    href?: string;
 }
 /** Session tree node transferred over the wire (preview-only, no full message content). */
 export interface PimoteTreeNode {
@@ -550,6 +558,21 @@ export interface PanelUpdateEvent {
     sessionId: string;
     cards: Card[];
 }
+/**
+ * Server-initiated client navigation request. Emitted by extensions that
+ * register a new same-origin surface (e.g. `pimote_static_host`) and want
+ * the client to jump to it on creation. The client decides whether to act —
+ * the static-host extension emits this only when the session is the one
+ * that issued the tool call, but clients should still ignore the event when
+ * the targeted `sessionId` is not the currently viewed session to avoid
+ * yanking users browsing elsewhere.
+ */
+export interface NavigateEvent {
+    type: 'pimote_navigate';
+    sessionId: string;
+    /** Same-origin URL to navigate to. */
+    url: string;
+}
 /**
  * Success response to a CallBindCommand. Carries the per-call WebRTC
  * signalling endpoint the client should connect to. The PWA obtains
@@ -601,7 +624,7 @@ export interface VersionMismatchEvent {
     type: 'version_mismatch';
     serverVersion: string;
 }
-export type PimoteEvent = PimoteSessionEvent | ExtensionUiRequestEvent | SessionConflictEvent | SessionOpenedEvent | SessionClosedEvent | SessionDeletedEvent | SessionRenamedEvent | SessionArchivedEvent | SessionReplacedEvent | SessionStateChangedEvent | ConnectionRestoredEvent | SessionRestoreEvent | BufferedEventsEvent | FullResyncEvent | PanelUpdateEvent | CallBindResponse | CallReadyEvent | CallEndedEvent | CallStatusEvent | VersionMismatchEvent;
+export type PimoteEvent = PimoteSessionEvent | ExtensionUiRequestEvent | SessionConflictEvent | SessionOpenedEvent | SessionClosedEvent | SessionDeletedEvent | SessionRenamedEvent | SessionArchivedEvent | SessionReplacedEvent | SessionStateChangedEvent | ConnectionRestoredEvent | SessionRestoreEvent | BufferedEventsEvent | FullResyncEvent | PanelUpdateEvent | NavigateEvent | CallBindResponse | CallReadyEvent | CallEndedEvent | CallStatusEvent | VersionMismatchEvent;
 export interface PimoteResponse<T = unknown> {
     /** Matches the `id` from the originating PimoteCommand */
     id: string;