@pimote/pimote 0.3.1 → 0.4.0

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';
@@ -147,19 +147,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 +186,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 +198,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,117 @@
+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 toolDeps(pi, sessionId) {
+        return {
+            registry,
+            store,
+            sessionId,
+            emitPanelCards: () => emitPanelCards(pi, sessionId),
+        };
+    }
+    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');

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