@pimote/pimote 0.3.0 → 0.4.0

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

@@ -0,0 +1,118 @@
+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();
+    return { slug: resolved, url: `/s/${resolved}/` };
+}
+/**
+ * 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/fsm/reducers/lifecycle.js

@@ -8,7 +8,7 @@
 //
 // Holds NO knowledge of the streaming / walkback machines. Those plug in
 // through the top-level dispatcher.
-import { VOICE_CALL_STARTED_SENTINEL } from '../../state-machine.js';
+import { VOICE_CALL_ENDED_SENTINEL, VOICE_CALL_STARTED_SENTINEL } from '../../state-machine.js';
 /**
  * Pure transition function for the lifecycle slice.
  *
@@ -55,11 +55,23 @@ export function reduceLifecycle(prev, event, ctx) {
             if (prev.kind === 'dormant') {
                 return { next: prev, interpreterAppliedNow: false, actions: [] };
             }
+            // Inject an explicit end-of-call sentinel into the conversation so
+            // the agent has an in-history signal that voice mode is over —
+            // mirrors the `<voice_call_started/>` sentinel on activate. Without
+            // it, a session resumed in text mode after a call sees a wall of
+            // prior `speak()` calls and tends to mimic one more before the
+            // tool-side guard rejects it.
+            //
+            // Crucially this is a *silent* injection: unlike the start sentinel
+            // (which deliberately triggers the greeting turn), the end sentinel
+            // must NOT trigger a turn — the call is over, the LLM has nothing
+            // to do right now, and a triggered turn would just provoke one more
+            // speak() attempt that we then have to reject.
             // Idempotent: close_ws is a no-op if no client is open.
             return {
                 next: { kind: 'dormant' },
                 interpreterAppliedNow: false,
-                actions: [{ kind: 'close_ws' }],
+                actions: [{ kind: 'inject_silent_user_message', customType: 'voice_call_ended', text: VOICE_CALL_ENDED_SENTINEL }, { kind: 'close_ws' }],
             };
         }
         case 'ws:opened': {

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';
@@ -141,6 +141,18 @@ export function createVoiceExtension(opts) {
                     pi.sendUserMessage(action.text, action.deliverAs ? { deliverAs: action.deliverAs } : undefined);
                     return;
                 }
+                case 'inject_silent_user_message': {
+                    // sendMessage() with a `custom` role + triggerTurn:false appends
+                    // an entry that converts to a `role:"user"` message for the LLM
+                    // (see core/messages.ts convertToLlm) but does not start a turn
+                    // now. Exactly what we want for the end-of-call sentinel.
+                    pi.sendMessage({
+                        customType: action.customType,
+                        content: action.text,
+                        display: true,
+                    }, { triggerTurn: false });
+                    return;
+                }
                 case 'open_ws': {
                     // Reentrancy guard: close any prior client first.
                     try {
@@ -156,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) {
@@ -179,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);
@@ -238,7 +253,12 @@ export function createVoiceExtension(opts) {
                     return { content: [{ type: 'text', text: 'ok' }], details: {} };
                 }
                 return {
-                    content: [{ type: 'text', text: 'speak() is only available during an active voice call.' }],
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Voice call has ended. The user is now in text mode — do NOT call speak() again. Reply with normal assistant text. Any further speak() calls in this session will be rejected.',
+                        },
+                    ],
                     details: {},
                     isError: true,
                 };
@@ -254,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.
@@ -302,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/state-machine.js

@@ -5,3 +5,10 @@
 // server-side VoiceOrchestrator.
 /** Sentinel user message appended on entry to the `active` state. */
 export const VOICE_CALL_STARTED_SENTINEL = '<voice_call_started/>';
+/**
+ * Sentinel user message appended on exit from `active`/`activating` back to
+ * `dormant`. Gives the agent an explicit in-history signal that the voice
+ * call has ended, so subsequent turns (including future text-mode pickups
+ * of the same session) don't keep mimicking prior `speak()` calls.
+ */
+export const VOICE_CALL_ENDED_SENTINEL = '<voice_call_ended/>';

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/server/dist/ws-handler.js

@@ -989,7 +989,8 @@ export class WsHandler {
             onSessionReset: (s) => this.handleSessionReset(s),
         };
         slot.connection = connection;
-        slot.sessionState.lastActivity = Date.now();
+        // Note: do NOT touch `idleSince` here. Idleness is an agent-level concept driven by
+        // agent_start/agent_end — a client claiming a session does not extend its idle clock.
         this.subscribedSessions.add(sessionId);
         // Bind extensions when needed. The bridge holds a direct reference to this
         // ManagedSlot — on reconnect we skip rebinding, but on session reset
@@ -1321,9 +1322,10 @@ export class WsHandler {
             const slot = this.sessionManager.getSession(sid);
             if (slot) {
                 slot.connection = null;
-                slot.sessionState.lastActivity = Date.now();
                 // Note: pending UI responses are NOT resolved here — they survive
                 // for replay on reconnect. They are resolved on session close or abort.
+                // Note: do NOT touch `idleSince`. Disconnecting does not reset idleness — if the
+                // agent finished 10 minutes ago, a peeking client should not extend the session's life.
             }
         }
         this.subscribedSessions.clear();

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 {