@pimote/pimote 0.3.1 → 0.4.1

package/server/dist/config.js

@@ -69,7 +69,6 @@ function parseVoiceConfig(v) {
         return undefined;
     const o = v;
     return {
-        speechmuxBinary: typeof o.speechmuxBinary === 'string' ? o.speechmuxBinary : undefined,
         speechmuxSignalUrl: typeof o.speechmuxSignalUrl === 'string' ? o.speechmuxSignalUrl : undefined,
         speechmuxLlmWsUrl: typeof o.speechmuxLlmWsUrl === 'string' ? o.speechmuxLlmWsUrl : undefined,
     };

package/server/dist/extension-ui-bridge.js

@@ -144,9 +144,26 @@ export function createExtensionUIBridge(slot, pushNotificationService, options)
         setWorkingMessage() {
             // no-op
         },
+        setWorkingVisible() {
+            // TODO(pimote-bridge): forward to client so extensions can hide/show the working indicator row.
+            // Web client renders its own streaming UI; no-op is safe but loses extension control.
+        },
+        setWorkingIndicator() {
+            // TODO(pimote-bridge): forward custom working-indicator frames/colors to client renderer.
+            // Web client renders its own spinner; no-op is safe but loses extension control.
+        },
         setHiddenThinkingLabel() {
             // no-op
         },
+        addAutocompleteProvider() {
+            // TODO(pimote-bridge): wire extension autocomplete factory into the client autocomplete stack.
+            // Today the client only has built-in slash/path completion; extension providers are dropped.
+        },
+        getEditorComponent() {
+            // TODO(pimote-bridge): decide whether to surface a stub EditorFactory for chained extension editors.
+            // Web client has no TUI editor component to wrap, so undefined is the honest answer.
+            return undefined;
+        },
         setFooter() {
             // no-op
         },

package/server/dist/folder-index.js

@@ -1,6 +1,6 @@
 import { readdir, stat, unlink } from 'node:fs/promises';
 import { join, basename } from 'node:path';
-import { SessionManager } from '@mariozechner/pi-coding-agent';
+import { SessionManager } from '@earendil-works/pi-coding-agent';
 /** Project marker files/directories that identify a folder as a project. */
 const PROJECT_MARKERS = ['.git', 'package.json'];
 /**

package/server/dist/index.js

@@ -6,9 +6,10 @@ import { PimoteSessionManager } from './session-manager.js';
 import { FolderIndex } from './folder-index.js';
 import { PushNotificationService } from './push-notification.js';
 import { FilePushSubscriptionStore, WebPushSender, migratePushSubscriptionStore } from './push-infrastructure.js';
-import { LEGACY_PIMOTE_PUSH_SUBSCRIPTIONS_PATH, PIMOTE_PUSH_SUBSCRIPTIONS_PATH, PIMOTE_SESSION_METADATA_PATH } from './paths.js';
+import { LEGACY_PIMOTE_PUSH_SUBSCRIPTIONS_PATH, PIMOTE_PUSH_SUBSCRIPTIONS_PATH, PIMOTE_SESSION_METADATA_PATH, PIMOTE_STATIC_HOST_DIR } from './paths.js';
 import { FileSessionMetadataStore } from './session-metadata.js';
 import { buildVoiceOrchestrator } from './voice-orchestrator-boot.js';
+import { InMemoryStaticHostRegistry, FileStaticHostStore, gcStaticHostStore, createStaticHostExtension } from './static-host/index.js';
 export async function main(options = {}) {
     let config = await loadConfig();
     config = await ensureVapidKeys(config);
@@ -23,7 +24,33 @@ export async function main(options = {}) {
     await pushNotificationService.initialize();
     const sessionMetadataStore = new FileSessionMetadataStore(PIMOTE_SESSION_METADATA_PATH);
     await sessionMetadataStore.initialize();
-    const sessionManager = new PimoteSessionManager(config, pushNotificationService);
+    // Static-host bootstrap: GC orphan persistence files, then construct the
+    // registry/store/factory singletons shared by the session manager and the
+    // HTTP route handler. The registry is process-lifetime; sessions register
+    // and unregister against it as they load and shut down.
+    let validSessionIds = new Set();
+    try {
+        const folders = await folderIndex.scan();
+        for (const folder of folders) {
+            const records = await folderIndex.listSessionRecords(folder.path);
+            for (const rec of records)
+                validSessionIds.add(rec.id);
+        }
+    }
+    catch (err) {
+        // Critical: do NOT run GC with an empty allow-list — that would delete
+        // every persisted bundle on a transient I/O hiccup at boot. Skip the
+        // sweep entirely and let the next clean boot reclaim orphans.
+        console.warn('[pimote] static-host GC: failed to enumerate sessions, skipping sweep this boot', err);
+        validSessionIds = null;
+    }
+    if (validSessionIds) {
+        await gcStaticHostStore({ storeDir: PIMOTE_STATIC_HOST_DIR, validSessionIds });
+    }
+    const staticHostRegistry = new InMemoryStaticHostRegistry();
+    const staticHostStore = new FileStaticHostStore(PIMOTE_STATIC_HOST_DIR);
+    const staticHostFactory = createStaticHostExtension({ registry: staticHostRegistry, store: staticHostStore });
+    const sessionManager = new PimoteSessionManager(config, pushNotificationService, { staticHostFactory });
     // Build the voice orchestrator before createServer so each WsHandler can be
     // handed a reference. The orchestrator needs a client-registry lookup, but
     // the real registry is created inside createServer below — so we hand it a
@@ -37,27 +64,32 @@ export async function main(options = {}) {
             get: (clientId) => clientRegistryRef.current.get(clientId),
         },
     });
-    const server = await createServer(config, sessionManager, folderIndex, pushNotificationService, sessionMetadataStore, voiceBoot.orchestrator);
+    if (!voiceBoot) {
+        console.log('[voice] dormant: voice config absent (set voice.speechmuxSignalUrl and voice.speechmuxLlmWsUrl to enable)');
+    }
+    const server = await createServer(config, sessionManager, folderIndex, pushNotificationService, sessionMetadataStore, voiceBoot?.orchestrator, staticHostRegistry);
     clientRegistryRef.current = server.clientRegistry;
-    // Suppress push notifications for sessions currently owned by a voice call.
-    // The user is on the line — we don't need to ping their phone for idle
-    // signals or extension UI prompts. Pushes resume automatically once the
-    // call ends and `isCallActive` flips back to false.
-    pushNotificationService.setSuppressionPredicate((sessionId) => voiceBoot.orchestrator.isCallActive(sessionId));
-    // Tear down orchestrator bookkeeping when a session is being closed (idle
-    // reap, explicit close). Emits call_ended{server_ended} to the owner.
-    sessionManager.onBeforeSessionClose = async (sessionId) => {
-        if (!voiceBoot.orchestrator.isCallActive(sessionId))
-            return;
-        const slot = sessionManager.getSlot(sessionId);
-        const ownerClientId = slot?.connection?.connectedClientId;
-        await voiceBoot.orchestrator.endCall({ sessionId, reason: 'server_ended' });
-        if (ownerClientId) {
-            const handler = server.clientRegistry.get(ownerClientId);
-            handler?.sendCallEndedEvent(sessionId, 'server_ended');
-        }
-    };
-    await voiceBoot.orchestrator.start();
+    if (voiceBoot) {
+        const orchestrator = voiceBoot.orchestrator;
+        // Suppress push notifications for sessions currently owned by a voice call.
+        // The user is on the line — we don't need to ping their phone for idle
+        // signals or extension UI prompts. Pushes resume automatically once the
+        // call ends and `isCallActive` flips back to false.
+        pushNotificationService.setSuppressionPredicate((sessionId) => orchestrator.isCallActive(sessionId));
+        // Tear down orchestrator bookkeeping when a session is being closed (idle
+        // reap, explicit close). Emits call_ended{server_ended} to the owner.
+        sessionManager.onBeforeSessionClose = async (sessionId) => {
+            if (!orchestrator.isCallActive(sessionId))
+                return;
+            const slot = sessionManager.getSlot(sessionId);
+            const ownerClientId = slot?.connection?.connectedClientId;
+            await orchestrator.endCall({ sessionId, reason: 'server_ended' });
+            if (ownerClientId) {
+                const handler = server.clientRegistry.get(ownerClientId);
+                handler?.sendCallEndedEvent(sessionId, 'server_ended');
+            }
+        };
+    }
     // Start idle session reaping with client connectivity check
     sessionManager.startIdleCheck(config.idleTimeout, (clientId) => server.clientRegistry.has(clientId));
     await server.start(port);
@@ -70,7 +102,7 @@ export async function main(options = {}) {
     // Graceful shutdown
     const shutdown = async () => {
         console.log('\n[pimote] Shutting down...');
-        await voiceBoot.shutdown();
+        await voiceBoot?.shutdown();
         await sessionManager.dispose();
         await server.close();
         process.exit(0);

package/server/dist/message-mapper.js

@@ -171,5 +171,6 @@ export function mapAgentMessage(msg) {
         content,
         ...(msg.id ? { entryId: msg.id } : {}),
         ...(aborted ? { aborted: true } : {}),
+        ...(role === 'assistant' && typeof msg.errorMessage === 'string' ? { errorMessage: msg.errorMessage } : {}),
     };
 }

package/server/dist/paths.js

@@ -11,4 +11,6 @@ export const PIMOTE_STATE_DIR = join(getXdgStateHome(), 'pimote');
 export const PIMOTE_CONFIG_PATH = join(PIMOTE_CONFIG_DIR, 'config.json');
 export const PIMOTE_PUSH_SUBSCRIPTIONS_PATH = join(PIMOTE_STATE_DIR, 'push-subscriptions.json');
 export const PIMOTE_SESSION_METADATA_PATH = join(PIMOTE_STATE_DIR, 'session-metadata.json');
+/** Directory holding per-session static-host persistence files (`<sessionId>.json`). */
+export const PIMOTE_STATIC_HOST_DIR = join(PIMOTE_STATE_DIR, 'static-host');
 export const LEGACY_PIMOTE_PUSH_SUBSCRIPTIONS_PATH = join(PIMOTE_CONFIG_DIR, 'push-subscriptions.json');

package/server/dist/server.js

@@ -4,6 +4,7 @@ import { join, extname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { WebSocketServer } from 'ws';
 import { WsHandler } from './ws-handler.js';
+import { serveStaticHostRoute } from './static-host/index.js';
 import crypto from 'node:crypto';
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 const CLIENT_DIR = process.env.CLIENT_DIR || join(__dirname, '..', '..', 'client', 'build');
@@ -79,7 +80,7 @@ async function serveFallback(res) {
         res.end(JSON.stringify({ error: 'not found' }));
     }
 }
-export async function createServer(config, sessionManager, folderIndex, pushNotificationService, sessionMetadataStore, voiceOrchestrator) {
+export async function createServer(config, sessionManager, folderIndex, pushNotificationService, sessionMetadataStore, voiceOrchestrator, staticHostRegistry) {
     const clientVersion = await loadClientVersion();
     if (clientVersion) {
         console.log(`[pimote] Client build version: ${clientVersion}`);
@@ -106,6 +107,13 @@ export async function createServer(config, sessionManager, folderIndex, pushNoti
             if (served)
                 return;
         }
+        // 3b. Static-host route — /s/<slug>/* serves agent-registered bundles.
+        // Unknown slugs return 404 from the handler and do NOT fall through to the SPA.
+        if (req.method === 'GET' || req.method === 'HEAD') {
+            const handled = await serveStaticHostRoute(req, res, staticHostRegistry);
+            if (handled)
+                return;
+        }
         // 4. SPA fallback — serve index.html for unmatched GET routes
         if (req.method === 'GET') {
             await serveFallback(res);

package/server/dist/session-manager.js

@@ -1,4 +1,4 @@
-import { createAgentSessionRuntime, createAgentSessionServices, createAgentSessionFromServices, createEventBus, AuthStorage, ModelRegistry, getAgentDir, SessionManager as PiSessionManager, } from '@mariozechner/pi-coding-agent';
+import { createAgentSessionRuntime, createAgentSessionServices, createAgentSessionFromServices, createEventBus, AuthStorage, ModelRegistry, getAgentDir, SessionManager as PiSessionManager, } from '@earendil-works/pi-coding-agent';
 import { EventBuffer } from './event-buffer.js';
 import { applyPanelMessage, getMergedPanelCards } from './panel-state.js';
 import { getGitBranch } from './git-branch.js';
@@ -119,7 +119,13 @@ function setupSlotPanelListeners(eventBus, state, sessionId, sendEvent) {
         applyPanelMessage(state.panelState, data);
         scheduleSlotPanelPush(state, sessionId, sendEvent);
     });
-    return [unsub1, unsub2];
+    const unsub3 = eventBus.on('pimote:navigate', (data) => {
+        const url = data?.url;
+        if (typeof url !== 'string' || url.length === 0)
+            return;
+        sendEvent({ type: 'pimote_navigate', sessionId, url });
+    });
+    return [unsub1, unsub2, unsub3];
 }
 /** Schedule a throttled panel push (~200ms) for a SessionState. */
 function scheduleSlotPanelPush(state, sessionId, sendEvent) {
@@ -147,19 +153,25 @@ export class PimoteSessionManager {
      *  reap, explicit close). Consumers use this to drop external bookkeeping
      *  (e.g. `VoiceOrchestrator.endCall`) while the session is still addressable. */
     onBeforeSessionClose;
-    constructor(config, pushNotificationService) {
+    staticHostFactory;
+    constructor(config, pushNotificationService, options = {}) {
         this.config = config;
         this.pushNotificationService = pushNotificationService;
         this.authStorage = AuthStorage.create();
         this.modelRegistry = ModelRegistry.create(this.authStorage);
+        this.staticHostFactory = options.staticHostFactory;
     }
     /**
      * Build the voice extension factory for this server's config, if possible.
-     * Returns undefined (and logs a warning) when neither voice-specific model
-     * refs nor fallback defaultProvider/defaultModel are configured — existing
-     * non-voice deployments continue to work unchanged.
+     * Returns undefined when voice is not configured (no speechmux URLs) or
+     * when neither voice-specific model refs nor fallback defaultProvider/
+     * defaultModel are configured. Non-voice deployments continue to work
+     * unchanged — sessions simply don't load `@pimote/voice` at all.
      */
     buildVoiceExtensionFactory() {
+        if (!this.config.voice?.speechmuxSignalUrl || !this.config.voice?.speechmuxLlmWsUrl) {
+            return undefined;
+        }
         const interpreter = this.config.defaultInterpreterModel ??
             (this.config.defaultProvider && this.config.defaultModel ? { provider: this.config.defaultProvider, modelId: this.config.defaultModel } : undefined);
         const worker = this.config.defaultWorkerModel ??
@@ -180,6 +192,8 @@ export class PimoteSessionManager {
         const sessionManager = sessionFilePath ? PiSessionManager.open(sessionFilePath) : PiSessionManager.create(folderPath);
         const effectiveFolderPath = sessionFilePath ? sessionManager.getCwd() : folderPath;
         const voiceExtensionFactory = this.buildVoiceExtensionFactory();
+        const staticHostFactory = this.staticHostFactory;
+        const extensionFactories = [...(voiceExtensionFactory ? [voiceExtensionFactory] : []), ...(staticHostFactory ? [staticHostFactory] : [])];
         const factory = async ({ cwd, agentDir, sessionManager, sessionStartEvent }) => {
             const eventBus = createEventBus();
             eventBusRef.current = eventBus;
@@ -190,7 +204,7 @@ export class PimoteSessionManager {
                 modelRegistry: sharedModelRegistry,
                 resourceLoaderOptions: {
                     eventBus,
-                    ...(voiceExtensionFactory ? { extensionFactories: [voiceExtensionFactory] } : {}),
+                    ...(extensionFactories.length ? { extensionFactories } : {}),
                 },
             });
             return {

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

@@ -0,0 +1,42 @@
+/**
+ * Boot-time garbage collection of the per-session static-host persistence dir.
+ *
+ * Reads `storeDir`, deletes any `<sessionId>.json` whose sessionId is not in
+ * `validSessionIds`. The directory not existing is not an error (returns OK
+ * without doing anything). Has no knowledge of the registry, the extension,
+ * or the HTTP layer.
+ *
+ * Called from `server/src/index.ts` after `FolderIndex` initialisation and
+ * before `server.start()` so the HTTP route never sees a stale slug pointing
+ * at a folder that the agent has long since deleted.
+ */
+import { readdir, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+export async function gcStaticHostStore(args) {
+    const { storeDir, validSessionIds } = args;
+    let entries;
+    try {
+        entries = await readdir(storeDir);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    const suffix = '.json';
+    for (const name of entries) {
+        if (!name.endsWith(suffix))
+            continue;
+        const sessionId = name.slice(0, -suffix.length);
+        if (validSessionIds.has(sessionId))
+            continue;
+        try {
+            await unlink(join(storeDir, name));
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                continue;
+            throw err;
+        }
+    }
+}

package/server/dist/static-host/http-handler.js

@@ -0,0 +1,170 @@
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+const MIME_TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.htm': 'text/html; charset=utf-8',
+    '.js': 'application/javascript; charset=utf-8',
+    '.mjs': 'application/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.txt': 'text/plain; charset=utf-8',
+    '.md': 'text/markdown; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.map': 'application/json; charset=utf-8',
+};
+// Match `/s/<slug>/<remainder>` — the trailing slash after the slug is
+// REQUIRED. Without it, browsers resolve relative asset URLs against `/s/`
+// instead of `/s/<slug>/` and every asset 404s. `/s/<slug>` (no slash) is
+// handled separately below with a 301 redirect to `/s/<slug>/`.
+const PREFIX_RE = /^\/s\/([a-z0-9-]+)\/(.*)$/;
+const PREFIX_NO_SLASH_RE = /^\/s\/([a-z0-9-]+)$/;
+function send404(res) {
+    res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'no-cache, no-store, must-revalidate' });
+    res.end('Not Found');
+}
+/**
+ * HTTP handler for the `/s/<slug>/*` route prefix.
+ *
+ * Behaviour:
+ *   - Path does not match `/s/<slug>/...` => returns `false` (caller falls
+ *     through to the SPA fallback).
+ *   - Slug not in the registry => 404, returns `true` (does NOT fall through).
+ *   - Resolved path escapes the registered folder (e.g. `..` traversal) => 404.
+ *   - Resolved path is a directory => append `index.html`.
+ *   - File missing => 404. File present => 200, content-type by extension,
+ *     streamed body, no-cache response headers.
+ *
+ * Returns `true` if the request was handled (any 2xx/4xx response written),
+ * `false` only on prefix mismatch.
+ */
+export async function serveStaticHostRoute(req, res, registry) {
+    if (req.method !== 'GET' && req.method !== 'HEAD')
+        return false;
+    let pathname;
+    try {
+        pathname = new URL(req.url ?? '', 'http://x').pathname;
+    }
+    catch {
+        return false;
+    }
+    // `/s/<slug>` (no trailing slash) — redirect to the canonical form so the
+    // browser resolves relative asset URLs against `/s/<slug>/`.
+    const noSlashMatch = PREFIX_NO_SLASH_RE.exec(pathname);
+    if (noSlashMatch) {
+        const [, slug] = noSlashMatch;
+        if (!registry.lookup(slug)) {
+            send404(res);
+            return true;
+        }
+        res.writeHead(301, { Location: `/s/${slug}/`, 'Cache-Control': 'no-cache, no-store, must-revalidate' });
+        res.end();
+        return true;
+    }
+    const m = PREFIX_RE.exec(pathname);
+    if (!m)
+        return false;
+    const [, slug, rawRemainder = ''] = m;
+    const reg = registry.lookup(slug);
+    if (!reg) {
+        send404(res);
+        return true;
+    }
+    let decoded;
+    try {
+        decoded = decodeURIComponent(rawRemainder);
+    }
+    catch {
+        send404(res);
+        return true;
+    }
+    // Defence-in-depth: reject any decoded path containing backslash, NUL,
+    // or `..` segments before resolving.
+    if (decoded.includes('\\') || decoded.includes('\u0000')) {
+        send404(res);
+        return true;
+    }
+    const segments = decoded.split('/');
+    if (segments.some((s) => s === '..')) {
+        send404(res);
+        return true;
+    }
+    const folderPath = reg.folderPath;
+    let resolved = path.resolve(folderPath, decoded);
+    if (resolved !== folderPath && !resolved.startsWith(folderPath + path.sep)) {
+        send404(res);
+        return true;
+    }
+    let st;
+    try {
+        st = await stat(resolved);
+    }
+    catch {
+        send404(res);
+        return true;
+    }
+    if (st.isDirectory()) {
+        resolved = path.join(resolved, 'index.html');
+        try {
+            st = await stat(resolved);
+        }
+        catch {
+            send404(res);
+            return true;
+        }
+    }
+    if (!st.isFile()) {
+        send404(res);
+        return true;
+    }
+    const ext = path.extname(resolved).toLowerCase();
+    const mime = MIME_TYPES[ext] || 'application/octet-stream';
+    res.writeHead(200, {
+        'Content-Type': mime,
+        'Cache-Control': 'no-cache, no-store, must-revalidate',
+    });
+    if (req.method === 'HEAD') {
+        res.end();
+        return true;
+    }
+    // Stream errors AFTER `writeHead(200)` cannot be turned into a 5xx — headers
+    // are already on the wire. Destroy the response and resolve cleanly so the
+    // rejection does not bubble out of the async request handler as an
+    // unhandled rejection.
+    await new Promise((resolvePromise) => {
+        const stream = createReadStream(resolved);
+        let settled = false;
+        const settle = () => {
+            if (settled)
+                return;
+            settled = true;
+            resolvePromise();
+        };
+        stream.on('error', (err) => {
+            console.warn('[static-host] stream error while serving', resolved, err);
+            try {
+                res.destroy();
+            }
+            catch {
+                // ignore
+            }
+            settle();
+        });
+        stream.on('end', settle);
+        res.on('close', () => {
+            stream.destroy();
+            settle();
+        });
+        stream.pipe(res);
+    });
+    return true;
+}

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

@@ -0,0 +1,121 @@
+import { Type } from 'typebox';
+import { executeRegisterTool, executeRemoveTool } from './tools.js';
+import { STATIC_HOST_TOOL_DESCRIPTION } from './prompt.js';
+export { InMemoryStaticHostRegistry } from './registry.js';
+export { FileStaticHostStore } from './store.js';
+export { serveStaticHostRoute } from './http-handler.js';
+export { gcStaticHostStore } from './gc.js';
+/**
+ * Build the pi `ExtensionFactory` for the static-host extension.
+ *
+ * The returned factory is threaded into every pi session via
+ * `resourceLoaderOptions.extensionFactories`. It captures `registry` and
+ * `store` by closure and resolves the per-session `sessionId` lazily through
+ * the `ctx.sessionManager.getSessionId()` available on event handlers (the pi
+ * `ExtensionFactory` itself receives only `ExtensionAPI`, not the sessionId).
+ *
+ * Lifecycle for one session S:
+ *   - First handler invocation (`session_start`): reads
+ *     `${storeDir}/${S}.json` if present, replays each entry into the registry,
+ *     emits a panel snapshot.
+ *   - Tools (`pimote_static_host`, `pimote_static_host_remove`): update the
+ *     in-memory list, atomically rewrite the file, update the registry,
+ *     re-emit the panel snapshot.
+ *   - `session_shutdown` => `registry.unregisterAllForSession(S)`. The file
+ *     stays on disk for the next session load.
+ */
+export function createStaticHostExtension(opts) {
+    const { registry, store } = opts;
+    function buildCardsFor(sessionId) {
+        return registry.listForSession(sessionId).map((entry) => {
+            const card = {
+                id: `static-host:${entry.slug}`,
+                header: {
+                    title: entry.cardMetadata.title,
+                    ...(entry.cardMetadata.tag !== undefined ? { tag: entry.cardMetadata.tag } : {}),
+                },
+                href: `/s/${entry.slug}/`,
+                ...(entry.cardMetadata.color !== undefined ? { color: entry.cardMetadata.color } : {}),
+            };
+            return card;
+        });
+    }
+    function emitPanelCards(pi, sessionId) {
+        const cards = buildCardsFor(sessionId);
+        pi.events.emit('pimote:panels', { type: 'cards', namespace: 'static-host', cards });
+    }
+    function emitNavigate(pi, url) {
+        pi.events.emit('pimote:navigate', { url });
+    }
+    function toolDeps(pi, sessionId) {
+        return {
+            registry,
+            store,
+            sessionId,
+            emitPanelCards: () => emitPanelCards(pi, sessionId),
+            emitNavigate: (url) => emitNavigate(pi, url),
+        };
+    }
+    return (pi) => {
+        pi.registerTool({
+            name: 'pimote_static_host',
+            label: 'Host static bundle',
+            description: STATIC_HOST_TOOL_DESCRIPTION,
+            parameters: Type.Object({
+                slug: Type.String({ description: 'Short URL slug, lowercase [a-z0-9-]+ with no leading/trailing dash.' }),
+                folder: Type.String({ description: 'Absolute path to the folder containing the bundle (must contain index.html).' }),
+                title: Type.String({ description: 'Title displayed on the panel card.' }),
+                tag: Type.Optional(Type.String({ description: 'Optional short tag shown next to the title.' })),
+                color: Type.Optional(Type.Union([Type.Literal('accent'), Type.Literal('success'), Type.Literal('warning'), Type.Literal('error'), Type.Literal('muted')], {
+                    description: 'Optional card color.',
+                })),
+            }),
+            execute: async (_callId, input, _abort, _meta, ctx) => {
+                const sessionId = ctx.sessionManager.getSessionId();
+                const out = await executeRegisterTool(input, toolDeps(pi, sessionId));
+                return { content: [{ type: 'text', text: JSON.stringify(out) }], details: out };
+            },
+        });
+        pi.registerTool({
+            name: 'pimote_static_host_remove',
+            label: 'Remove hosted bundle',
+            description: 'Unregister a previously hosted static bundle by slug.',
+            parameters: Type.Object({
+                slug: Type.String({ description: 'Slug of the bundle to remove.' }),
+            }),
+            execute: async (_callId, input, _abort, _meta, ctx) => {
+                const sessionId = ctx.sessionManager.getSessionId();
+                const out = await executeRemoveTool(input, toolDeps(pi, sessionId));
+                return { content: [{ type: 'text', text: JSON.stringify(out) }], details: out };
+            },
+        });
+        pi.on('session_start', async (_ev, ctx) => {
+            const sessionId = ctx.sessionManager.getSessionId();
+            const file = await store.read(sessionId);
+            if (!file)
+                return;
+            for (const entry of file.entries) {
+                try {
+                    registry.register({
+                        slug: entry.slug,
+                        folderPath: entry.folderPath,
+                        sessionId,
+                        cardMetadata: entry.cardMetadata,
+                    });
+                }
+                catch (err) {
+                    // Defensive: a slug conflict (e.g. two sessions persisted the same
+                    // slug, or another session reloaded earlier this boot) must not
+                    // abort the whole replay loop and leave the session partially
+                    // loaded. Skip the conflicting entry and continue.
+                    console.warn(`[static-host] session_start: skipping persisted entry ${entry.slug} for session ${sessionId}`, err);
+                }
+            }
+            emitPanelCards(pi, sessionId);
+        });
+        pi.on('session_shutdown', async (_ev, ctx) => {
+            const sessionId = ctx.sessionManager.getSessionId();
+            registry.unregisterAllForSession(sessionId);
+        });
+    };
+}

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

@@ -0,0 +1,19 @@
+// Description text attached to the `pimote_static_host` tool. The string
+// is visible to the model in the system prompt's tool listing and must
+// substantively cover the two primary use cases, the mandatory responsive-
+// layout rule (with explicit mobile + desktop breakpoints), the no-secrets
+// rule, and a brief workflow note. See `docs/plans/static-resources.md`.
+export const STATIC_HOST_TOOL_DESCRIPTION = [
+    "Host a static HTML/asset bundle from a local folder so the user can view it in their browser. Returns a URL and creates a tappable card in the user's session pointing at the bundle.",
+    '',
+    '**When to use this:**',
+    '',
+    '1. **On-the-fly reports and visualisations.** Reach for this whenever you need to present information that would benefit from richer formatting than plain markdown — charts, comparison tables across many dimensions, syntax-highlighted code walkthroughs, before/after diffs, navigable trees of nested structures. A well-designed HTML report is much easier to read and navigate than a wall of markdown in the chat.',
+    '2. **Ad-hoc interactive tools.** Small single-purpose tools the user can play with for a little while — calculators, form-driven explorers, lightweight UIs that call external APIs via embedded JavaScript, in-memory data playgrounds, anything where interactivity adds value beyond static text. The bundle is real same-origin JS; it can fetch, do DOM things, persist to localStorage, whatever. Use this when the user needs a temporary tool tailored to the task at hand rather than a hand-rolled answer.',
+    '',
+    '**Mandatory: responsive, mobile-and-desktop layout.** Always design the bundle to work equally well on both desktop and mobile form factors. The user may view the same report on either device — even the same report on both. Use fluid layouts, relative units, and media queries. Mentally test your layout at ~360px wide and ~1440px wide before considering it done.',
+    '',
+    '**No secrets in the bundle.** Bundle files are served verbatim to the browser. Do not embed API keys, tokens, or any other credentials, and do not build bundles that depend on calling services that require them — there is no secret-management story for static-hosted bundles. Stick to public endpoints, in-memory state, and APIs that work without auth.',
+    '',
+    "**Workflow.** Generate the bundle (with at minimum an `index.html`) in a folder, then call this tool with the folder's absolute path, a short descriptive slug, and a title for the card. The user sees a card in their session; tapping it navigates them to the bundle, and browser-back returns them to the main pimote UI.",
+].join('\n');