@clearlysh/beehaven 0.8.16

package/dist/daemon-gemini.js

@@ -0,0 +1,224 @@
+/**
+ * daemon-gemini (#46) — local Gemini CLI integration mirroring
+ * daemon-codex (#45) and daemon-omni (Claude).
+ *
+ * Why: completes the local-triumvirate. Claude (via daemon-omni),
+ * Codex (via daemon-codex), and Gemini all run as user-owned daemon
+ * processes. FAB model picker routes to whichever the user selects;
+ * the relay never sees the prompt for these paths.
+ *
+ * Architecture: identical to daemon-codex. The relay broadcasts
+ * `gemini:prompt` to the daemon over the IPC socket; this module:
+ *   - mints a Gemini-CLI session via @google/gemini-cli-core
+ *   - streams agent events back over IPC (matches the
+ *     `agent:text` / `agent:tool-call` / `agent:done` shape used by
+ *     daemon-omni so the FAB renderer is provider-agnostic)
+ *
+ * Lifecycle:
+ *   - LRU cache of N concurrent sessions, same as #49 daemon-omni
+ *   - Idle eviction after 5 min
+ *   - SessionId convention: 'gemini-<sessionId>' so the daemon's
+ *     active-session list distinguishes Claude / Codex / Gemini at
+ *     a glance
+ *
+ * Wiring (Mac app rebuild required):
+ *   1. Add `@google/gemini-cli-core` to packages/cli's deps.
+ *   2. In daemon.ts, route gemini:* IPC envelopes here.
+ *   3. In workspace.ts agent:prompt handler, add the gemini branch
+ *      that broadcasts `gemini:prompt` to the daemon when
+ *      model.startsWith('gemini-') && model.endsWith('-local').
+ *
+ * This file ships the integration; the wiring above is a Mac-app-side
+ * change that lands when the user rebuilds with the updated SDK.
+ */
+import { spawn } from 'child_process';
+/** Per-daemon session table keyed by sessionId. */
+const _sessions = new Map();
+const SESSION_TTL_MS = 5 * 60 * 1000;
+const MAX_CONCURRENT = 12;
+/**
+ * Start (or resume) a Gemini CLI session. Returns the session object;
+ * caller subscribes to its `proc.stdout` for streaming output.
+ *
+ * Idle eviction: every call sweeps the session map for entries older
+ * than SESSION_TTL_MS and kills them. Cheap (a few map iterations);
+ * bounds the daemon's process count.
+ */
+export function startGeminiSession(args) {
+    evictIdleSessions();
+    const existing = _sessions.get(args.sessionId);
+    if (existing) {
+        existing.lastActive = Date.now();
+        return existing;
+    }
+    // Cap concurrent sessions — LRU evicts oldest when full.
+    if (_sessions.size >= MAX_CONCURRENT) {
+        const oldest = [..._sessions.values()].sort((a, b) => a.lastActive - b.lastActive)[0];
+        if (oldest) {
+            try {
+                oldest.proc.kill('SIGTERM');
+            }
+            catch { }
+            _sessions.delete(oldest.sessionId);
+        }
+    }
+    // gemini CLI args. The SDK's CLI takes the prompt on stdin; we use
+    // --json-stream for structured output the daemon can parse.
+    const cliArgs = ['--json-stream'];
+    if (args.continueSession)
+        cliArgs.push('--continue');
+    if (args.appendSystemPrompt) {
+        cliArgs.push('--append-system-prompt', args.appendSystemPrompt);
+    }
+    // Default tool palette — mirrors daemon-omni's claude_code preset so
+    // Gemini gets the same surface (Read/Write/Edit/Bash/Glob/Grep/
+    // WebFetch). Without this, Gemini CLI ships with a conservative
+    // default that misses shell_command — and the entire beehaven CLI
+    // bridge (canvas RPCs, hive verbs, sql, etc.) runs through Bash.
+    // Caller can override with an explicit allowedTools.
+    const DEFAULT_GEMINI_TOOLS = [
+        'read_file',
+        'write_file',
+        'edit_file',
+        'ls',
+        'glob',
+        'grep',
+        'shell_command',
+        'web_fetch',
+    ];
+    const tools = (args.allowedTools && args.allowedTools.length > 0)
+        ? args.allowedTools
+        : DEFAULT_GEMINI_TOOLS;
+    cliArgs.push('--allowed-tools', tools.join(','));
+    const proc = spawn('gemini', cliArgs, {
+        cwd: args.cwd ?? process.cwd(),
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env },
+    });
+    const session = {
+        sessionId: args.sessionId,
+        compositionId: args.compositionId,
+        model: args.model ?? 'gemini-2.5-pro',
+        cwd: args.cwd ?? process.cwd(),
+        proc,
+        startedAt: Date.now(),
+        lastActive: Date.now(),
+        continueSession: !!args.continueSession,
+    };
+    _sessions.set(args.sessionId, session);
+    proc.on('exit', () => {
+        _sessions.delete(args.sessionId);
+    });
+    // Feed the prompt via stdin and close so Gemini knows the input
+    // is complete.
+    proc.stdin.write(args.prompt);
+    proc.stdin.end();
+    return session;
+}
+/**
+ * Pipe a session's JSON-stream output to an event emitter. The
+ * emitter normalizes Gemini's event shape into the shared {type,
+ * sessionId, ...} envelope the FAB expects.
+ */
+export function pipeGeminiEvents(session, emit) {
+    let buf = '';
+    session.proc.stdout.on('data', (chunk) => {
+        buf += chunk.toString('utf8');
+        let idx;
+        while ((idx = buf.indexOf('\n')) >= 0) {
+            const line = buf.slice(0, idx).trim();
+            buf = buf.slice(idx + 1);
+            if (!line)
+                continue;
+            try {
+                const ev = JSON.parse(line);
+                // Translate Gemini-CLI event shapes into the shared FAB envelope.
+                // Gemini-CLI's --json-stream emits {type: 'text-delta', text} +
+                // {type: 'tool-call', name, args} + {type: 'done', usage}.
+                if (ev.type === 'text-delta') {
+                    emit({
+                        type: 'agent:text',
+                        sessionId: session.sessionId,
+                        text: ev.text,
+                        done: false,
+                        meta: { model: session.model },
+                    });
+                }
+                else if (ev.type === 'tool-call') {
+                    emit({
+                        type: 'agent:tool-call',
+                        sessionId: session.sessionId,
+                        toolName: ev.name,
+                        toolInput: { args: ev.args },
+                        commandId: ev.id || `gemini-${Date.now()}`,
+                    });
+                }
+                else if (ev.type === 'tool-result') {
+                    emit({
+                        type: 'agent:tool-result',
+                        sessionId: session.sessionId,
+                        commandId: ev.id,
+                        toolName: ev.name,
+                        result: ev.result,
+                    });
+                }
+                else if (ev.type === 'done') {
+                    emit({
+                        type: 'agent:text',
+                        sessionId: session.sessionId,
+                        text: ev.text ?? '',
+                        done: true,
+                        meta: { model: session.model, usage: ev.usage },
+                    });
+                }
+            }
+            catch {
+                // Non-JSON line — ignore. Gemini-CLI sometimes prints status
+                // strings (e.g. "Starting Gemini agent…") that the FAB doesn't
+                // need.
+            }
+        }
+    });
+    session.proc.stderr.on('data', (chunk) => {
+        // Surface stderr as agent:error so a Gemini-CLI crash isn't
+        // invisible. Tail-only — full stderr stays in the daemon log.
+        emit({
+            type: 'agent:error',
+            sessionId: session.sessionId,
+            error: chunk.toString('utf8').slice(-500),
+        });
+    });
+}
+/** Kill an active session. Used by the FAB's "stop generation" affordance. */
+export function killGeminiSession(sessionId) {
+    const session = _sessions.get(sessionId);
+    if (!session)
+        return false;
+    try {
+        session.proc.kill('SIGTERM');
+    }
+    catch { }
+    _sessions.delete(sessionId);
+    return true;
+}
+function evictIdleSessions() {
+    const cutoff = Date.now() - SESSION_TTL_MS;
+    for (const [id, session] of _sessions) {
+        if (session.lastActive < cutoff) {
+            try {
+                session.proc.kill('SIGTERM');
+            }
+            catch { }
+            _sessions.delete(id);
+        }
+    }
+}
+/** Diagnostic — list active sessions for the daemon's status JSON. */
+export function listGeminiSessions() {
+    return [..._sessions.values()].map((s) => ({
+        sessionId: s.sessionId,
+        model: s.model,
+        cwd: s.cwd,
+        ageMs: Date.now() - s.startedAt,
+    }));
+}

package/dist/daemon-mcp-clearly.js

@@ -0,0 +1,353 @@
+/**
+ * daemon-mcp-clearly — in-SDK MCP server for daemon Claude (#421).
+ *
+ * Replaces the Bash + `beehaven call` indirection with structured MCP
+ * tool calls. Lives in the same Node process as the daemon — no
+ * subprocess, no stdio boundary, no serialization tax. The Anthropic
+ * Agent SDK's `createSdkMcpServer` helper turns each tool into a typed
+ * function callable directly inside the spawned Claude Code session.
+ *
+ * Why this exists:
+ *   - Security: structured args eliminate the shell-injection surface
+ *     that `beehaven call <verb> '<json>'` exposed. Args are parsed by
+ *     Zod schemas before they ever cross the daemon ↔ Claude boundary.
+ *   - Auditability: every tool call is logged with `{ tool, args }` —
+ *     forensics is a SQL query, not a shell-history scrape.
+ *   - Permission gates: `canUseTool('mcp__clearly__canvas_add_image', …)`
+ *     fires per RPC by name. The previous `canUseTool('Bash', …)` had
+ *     to regex-parse `beehaven call <verb>` out of the command string
+ *     which was brittle.
+ *   - Performance: in-process call eliminates the ~50-100ms Node-CLI
+ *     bootstrap per RPC. Ten calls per turn = ~1s reclaimed.
+ *   - Agent tier foundation (#398): when the Personal Agent ships, its
+ *     "never publish without approval" gate is trivially expressed via
+ *     `canUseTool` allowlists on named MCP tools. The Bash + CLI path
+ *     would have made that gate brittle.
+ *
+ * Architecture:
+ *   daemon-omni.ts spawns Claude Code with `mcpServers: { clearly: … }`.
+ *   The SDK's MCP transport calls our handlers directly in-process.
+ *   Each handler resolves to a `daemonContext.invokeRpc(action, args)`
+ *   call that forwards through the existing daemon → worker RPC plumbing
+ *   — so we don't duplicate any worker-side logic, just provide a typed
+ *   surface in front of it.
+ *
+ * ⚠⚠ WIRE-UP STATUS: MOUNTED. This header said "the file scaffolds the server… to enable
+ * per-session:" long after `daemon.ts` began calling `setClearlyTools` on every daemon start, and
+ * that stale sentence is why the tools were believed to be a design for so long. The snippet below
+ * is kept as the SHAPE of the wiring, not as an instruction — the real call is in `daemon.ts`.
+ *
+ * ⚠ AND `invokeRpc` IS WRAPPED IN `agent-invoke` THERE (2026-08-29). It used to be a raw relay
+ * dispatch, so every tool on this server ran with no `permission_scope` / `tool_allowlist` gate, no
+ * `agent_activity` row and no attribution — while the same action typed as `beehaven call` was
+ * fully governed. Read that note before changing the context this server is given.
+ *
+ *   import { createClearlyMcpServer } from './daemon-mcp-clearly.js';
+ *
+ *   await startOmniSession({
+ *     …existing options,
+ *     mcpServers: {
+ *       clearly: createClearlyMcpServer({
+ *         invokeRpc: (action, args) => daemonContext.invokeWorkerRpc(action, args),
+ *       }),
+ *     },
+ *     allowedTools: [
+ *       'mcp__clearly__*',  // unlock all Clearly MCP tools
+ *       'Bash', 'Read', 'Write', 'Edit', 'Grep', 'Glob',  // standard Claude Code
+ *     ],
+ *   });
+ *
+ * The Bash + `beehaven call` path stays available for discovery
+ * (`beehaven actions`, `canvas:actions` catalog browse) and for the
+ * long tail of RPCs not promoted to MCP tools yet — `clearly_invoke`
+ * below is the safety-valve wrapper. Plan is to ship MCP-first for
+ * the top 30 actions and migrate the rest as usage proves the pattern.
+ */
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { AVATAR_EXPRESSIONS, AVATAR_REACTIONS } from './avatar-protocol.js';
+/**
+ * Build the in-process MCP server. The `tools` array below is the
+ * "primary surface" — top-30 canvas RPCs that Claude reaches for daily.
+ * Anything else still works via the `clearly_invoke` fallback.
+ */
+export function createClearlyMcpServer(ctx) {
+    const log = ctx.log ?? ((level, msg, meta) => {
+        if (level === 'error')
+            console.warn(`[clearly-mcp:${level}] ${msg}`, meta ?? '');
+    });
+    /** Helper — every tool's handler shape is identical: forward args
+     *  to the worker, surface ok/error consistently. Centralizing lets
+     *  us add metrics, retry, audit hooks in one place later. */
+    const forward = (action) => async (args) => {
+        try {
+            const result = await ctx.invokeRpc(action, args);
+            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+        }
+        catch (err) {
+            log('error', `mcp:${action} failed: ${err?.message ?? err}`, { args });
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: String(err?.message ?? err) }) }],
+                isError: true,
+            };
+        }
+    };
+    /** Like forward(), but routes to the LOCAL avatar as Monet (the daemon's
+     *  own agent principal) instead of the cloud worker. */
+    const avatarForward = (action) => async (args) => {
+        if (!ctx.driveAvatar) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: 'avatar driving is not wired in this daemon' }) }],
+                isError: true,
+            };
+        }
+        try {
+            const result = await ctx.driveAvatar(action, args);
+            return { content: [{ type: 'text', text: JSON.stringify(result ?? { ok: true }) }] };
+        }
+        catch (err) {
+            log('error', `mcp:avatar:${action} failed: ${err?.message ?? err}`, { args });
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: String(err?.message ?? err) }) }],
+                isError: true,
+            };
+        }
+    };
+    // ── Coordinate schema reused across most canvas mutations ────────
+    // Optional x/y default to the camera-aware fallback in the worker
+    // (#148) — passing them explicitly lets Claude position deliberately.
+    const positionFields = {
+        x: z.number().optional().describe('Canvas x-coordinate (world space). Omit to let the worker pick a viewport-aware spot.'),
+        y: z.number().optional().describe('Canvas y-coordinate (world space). Omit for viewport-aware fallback.'),
+        width: z.number().positive().optional(),
+        height: z.number().positive().optional(),
+    };
+    const compositionRefShape = {
+        compositionId: z.string().describe('The composition (canvas) id. Use canvas-list-compositions to find one.'),
+    };
+    return createSdkMcpServer({
+        name: 'clearly',
+        version: '1.0.0',
+        tools: [
+            // ── Avatar (Monet drives the daemon's own on-screen avatar) ──
+            // Routes to the LOCAL avatar building as the 'monet' agent principal,
+            // so Monet's avatar is distinct from every terminal agent's avatar.
+            tool('avatar_say', 'Make the daemon\'s own avatar (Monet) show text in a speech bubble (no audio). Use for quick on-screen status.', { text: z.string().describe('Text for the speech bubble.') }, avatarForward('say')),
+            tool('avatar_speak', 'Make Monet speak text aloud via TTS (Kokoro). Use sparingly — audio plays on the user\'s machine.', { text: z.string().describe('Text to speak aloud.') }, avatarForward('speak')),
+            tool('avatar_get_state', 'Read the current avatar state, sticky mood, dynamic PAD mood, and speech status. Use this when the agent needs to know how the avatar currently feels.', {}, avatarForward('getState')),
+            // ⚠ `react`, not `emote`. The avatar building exposes `react` (one-shot
+            // animations: wave, cheer, hearts, laugh, dance, buzz, nod, shake, think,
+            // surprise, sleep) and `setEmotion` (a persistent expression). There has
+            // never been an `emote` action — this tool answered
+            // `Unknown action: emote` on every call, which nobody saw because the
+            // whole server was unmounted. The param is `reaction` for the same
+            // reason: the examples in the old description ("wave", "think") were
+            // reactions all along.
+            tool('avatar_react', 'Make Monet play a one-shot reaction animation.', {
+                reaction: z.enum(AVATAR_REACTIONS).describe('Reaction to play.'),
+                reason: z.string().max(200).optional().describe('Optional reason for the reaction.'),
+            }, avatarForward('react')),
+            tool('avatar_emote', 'Set Monet\'s mood or binary wake/sleep lifecycle. Thinking and celebrating are activity poses. For a one-shot animation use avatar_react.', {
+                emotion: z.enum(AVATAR_EXPRESSIONS).describe('Mood or wake/sleep lifecycle value.'),
+            }, avatarForward('setEmotion')),
+            // ── Discovery ──────────────────────────────────────────────
+            tool('canvas_list_compositions', 'List the user\'s compositions (canvases). Use this when you don\'t know which composition the user is working in. Returns id + title + updated_at.', {
+                limit: z.number().int().positive().max(100).default(10),
+            }, forward('canvas-list-compositions')),
+            tool('canvas_list_blocks', 'Inventory the blocks currently on a composition. Read BEFORE mutating so you understand the layout you\'re working with.', { ...compositionRefShape,
+                types: z.array(z.string()).optional().describe('Filter to specific block types — e.g., ["image", "text"].'),
+            }, forward('canvas-list-blocks')),
+            tool('canvas_get_block', 'Read a single block by id. Returns full data including content + position + metadata.', { ...compositionRefShape,
+                blockId: z.string(),
+            }, forward('canvas-get-block')),
+            /**
+             * ⚠ THE SCENE GRAPH — the two tools that were missing, and the reason
+             * Omni could add blocks to a canvas but not design on one.
+             *
+             * The `canvas_*_block` family above is the older COMPOSITION/BLOCKS model:
+             * add a text block, list blocks, patch a block. It cannot see the canvas,
+             * cannot address a node, and knows nothing about frames, arrows, tokens,
+             * components, alignment or the camera. `canvas-act` and `canvas-perceive`
+             * are the real surface — and both were reachable only through
+             * `clearly_invoke`, the generic escape hatch, which hands the model an
+             * action name with no signature and no hint that the vocabulary exists.
+             *
+             * Deliberately thin wrappers. The verb vocabulary is enormous and lives on
+             * the RPC's own description, which the agent discovers with
+             * `canvas.catalog` — duplicating it in a Zod schema here would be a second
+             * copy to drift, and the daemon is not the authority on what the canvas
+             * can do.
+             */
+            tool('canvas_perceive', 'SEE the canvas — the read half of the canvas pair. Returns the composition as a structural room: gaze (pan/zoom/visible rect), contents (every scene node with bounds, type, text, fill, selection), focus (selection + active tool), instruments (on-screen controls). Reads the live tab when one is open and falls back to the persisted scene otherwise (live:false). ALWAYS perceive before editing an existing canvas — it is how you get real node ids and avoid rebuilding something that is already there.', {
+                compositionId: z.string().optional().describe('Defaults to the active composition. Find one with canvas_list_compositions.'),
+                format: z.enum(['json', 'text']).optional().describe('"text" is a compact human-readable summary; "json" is the full room.'),
+                includePixels: z.boolean().optional().describe('Also render a PNG of the scene. Costly — only when you genuinely need to look at it.'),
+                includeGeometry: z.boolean().optional().describe('Emit each path node\'s editable vector network (vertices, segments, bezier handles) for vector editing.'),
+                maxObjects: z.number().optional(),
+            }, forward('canvas-perceive')),
+            tool('canvas_act', 'DO anything on the canvas — the ONE mutation path. Pass { action, args } for a single op or { batch: [{action,args}] } for an atomic multi-step edit. Most of the surface persists with NO tab open: frame.create, canvas.create-node, canvas.compose (lands a whole spec-correct block in one call), canvas.update-nodes, canvas.delete, canvas.group, canvas.auto-layout, canvas.component, canvas.tokens, canvas.align, canvas.export, arrow.create. Look up an action\'s ARGUMENTS with canvas_catalog BEFORE calling it — guessing costs a round trip. VERIFY your work with canvas_perceive. Do not refuse to draw or edit because no tab is open.', {
+                action: z.string().optional().describe('A single editor action id, e.g. "canvas.compose", "frame.create", "canvas.update-nodes".'),
+                // ⚠ `z.record` takes a KEY schema in this zod version — `z.record(z.any())`
+                // compiles as a one-arg call and fails the build.
+                args: z.record(z.string(), z.any()).optional().describe('Arguments for that action.'),
+                batch: z.array(z.object({
+                    action: z.string(),
+                    args: z.record(z.string(), z.any()).optional(),
+                })).optional().describe('Several ops applied atomically, in order. Use for create → select → modify sequences.'),
+                compositionId: z.string().optional().describe('Defaults to the active composition.'),
+                awaitResult: z.boolean().optional().describe('Wait for the handler\'s return value rather than a delivery ack.'),
+            }, forward('canvas-act')),
+            /**
+             * KNOW — the third of the triad, and the one that makes the other two
+             * usable.
+             *
+             * ⚠ IT IS ITS OWN RPC (`canvas-catalog`), NOT an action you pass to
+             * canvas_act. Reaching for `canvas_act { action: 'canvas.catalog' }` gets
+             * routed to the LIVE tab registry, which does not have it, and comes back
+             * `await-result-timeout` — a discovery call that looks like a broken
+             * canvas. Exposing it as a typed tool is what stops that guess.
+             *
+             * Without this, canvas_act's vocabulary is discoverable but its ARGUMENTS
+             * are not: an agent probing blind wrote `frame.create {preset}` (needs
+             * `name`) and `canvas.compose {spec:{type}}` (wants `kind` at top level),
+             * burning a retry on each. Both schemas are in here.
+             */
+            tool('canvas_catalog', 'KNOW what the canvas can do — the discovery half. Returns `rpcs` (the headless canvas RPC catalog with each action\'s ARGUMENT SCHEMA — always available, no tab needed), `headlessActions` (exactly which canvas_act actions persist with no browser open), and `actions` (the live editor registry, only when a tab is open). Search with { query }, narrow with { group }, or describe one action with { id }. Call this BEFORE canvas_act when you are unsure of an action\'s arguments — it is cheaper than a failed call.', {
+                query: z.string().optional().describe('Free-text search over the catalog, e.g. "align", "frame", "text".'),
+                group: z.string().optional().describe('Filter to one domain/group.'),
+                id: z.string().optional().describe('Describe exactly this action id, e.g. "canvas.compose".'),
+                surface: z.enum(['actions', 'rpcs', 'all']).optional().describe('"rpcs" = headless catalog only (always works); "actions" = live tab registry; default "all".'),
+                compositionId: z.string().optional(),
+            }, forward('canvas-catalog')),
+            // ── Composition lifecycle ─────────────────────────────────
+            tool('composition_create', 'Create a new composition (canvas). Avoid creating new compositions when the user has one open — use design-layer-add instead. Pass `force: true` only if the user explicitly asks for a new separate canvas.', {
+                title: z.string(),
+                data: z.string().optional().describe('JSON string of {"blocks":[],"backgroundColor":"#…"}. Omit for empty canvas.'),
+                frameWidth: z.number().positive().default(1920),
+                frameHeight: z.number().positive().default(1080),
+                force: z.boolean().default(false),
+            }, forward('composition-create')),
+            tool('composition_detail', 'Read composition metadata + share links + analytics + entitlements. Pass `includeBlocks: true` to also fetch the full block array (capped at 200 blocks, 64KB per block).', {
+                id: z.string(),
+                includeBlocks: z.boolean().default(false),
+            }, forward('composition-detail')),
+            tool('composition_patch', 'Patch fields on a composition. `patch.blocks` is MERGED BY ID (matching ids update, new ids append, omitted ids are preserved — explicit deletion requires composition-block-delete).', {
+                id: z.string(),
+                patch: z.record(z.string(), z.unknown()),
+            }, forward('composition-patch')),
+            // ── Adding content ────────────────────────────────────────
+            tool('canvas_add_text', 'Add a sticky-note style text block to the canvas.', { ...compositionRefShape,
+                text: z.string(),
+                fontSize: z.number().int().positive().default(18),
+                ...positionFields,
+            }, forward('canvas-add-text')),
+            tool('canvas_add_image', 'Add an image block. Pass either `r2_key` (already-uploaded asset) or `url` (Clearly will fetch + store).', { ...compositionRefShape,
+                r2_key: z.string().optional(),
+                url: z.string().url().optional(),
+                alt: z.string().optional(),
+                ...positionFields,
+            }, forward('canvas-add-image')),
+            tool('canvas_add_response_cards', 'Multi-section answer as spatial cards (3+ sections only — short replies should be plain narration). Each card has title + body.', { ...compositionRefShape,
+                title: z.string(),
+                cards: z.array(z.object({ title: z.string(), body: z.string() })).min(2),
+            }, forward('canvas-add-response-cards')),
+            tool('canvas_add_task', 'Task block (PM card) with status pill. Status: todo | doing | blocked | done. Tier: p0 | p1 | p2.', { ...compositionRefShape,
+                title: z.string(),
+                status: z.enum(['todo', 'doing', 'blocked', 'done']).default('todo'),
+                tier: z.enum(['p0', 'p1', 'p2']).optional(),
+                assignee: z.string().optional(),
+                dueAt: z.number().int().optional(),
+                ...positionFields,
+            }, forward('canvas-add-task')),
+            tool('canvas_add_terminal', 'Add a live FloatingTerminal block. The terminal\'s cwd defaults to ~/.clearly/compositions/<id>/ so `claude --continue` inside picks up THIS conversation.', { ...compositionRefShape,
+                ...positionFields,
+            }, forward('canvas-add-terminal')),
+            tool('canvas_add_claude_comm', 'Add a Claude-to-user comm block. Use for narration / build-result / status / suggestion / error one-way messages. Kind: narration | build-result | status | suggestion | error.', { ...compositionRefShape,
+                kind: z.enum(['narration', 'build-result', 'status', 'suggestion', 'error']),
+                title: z.string().optional(),
+                body: z.string(),
+                ...positionFields,
+            }, forward('canvas-add-claude-comm')),
+            // ── Updates / deletes ─────────────────────────────────────
+            tool('canvas_update_block', 'Patch fields on an existing block. Pass `blockId` + the fields to merge.', { ...compositionRefShape,
+                blockId: z.string(),
+                patch: z.record(z.string(), z.unknown()),
+            }, forward('canvas-update-block')),
+            tool('canvas_delete_block', 'Delete a block from a composition. Permanent — versions are kept in Chronicle but the block is removed from the live canvas.', { ...compositionRefShape,
+                blockId: z.string(),
+            }, forward('canvas-delete-block')),
+            // ── Memory ────────────────────────────────────────────────
+            tool('canvas_remember_fact', 'Save a durable fact about the user, project, or composition. Use SPARINGLY — only for facts that still matter weeks from now (preferences, brand decisions, project conventions). Not for transient state. Scope: composition (this canvas only) or global (all your work).', { ...compositionRefShape,
+                fact: z.string().max(500),
+                scope: z.enum(['composition', 'global']).default('composition'),
+                category: z.string().optional(),
+            }, forward('canvas-remember-fact')),
+            // ── Focus / presence ──────────────────────────────────────
+            tool('canvas_claude_focus', 'Signal which block(s) you\'re currently working on. The user sees a glow + the off-screen cursor cue tracks toward it. Mood: thinking | writing | reading | designing | done.', { ...compositionRefShape,
+                blockIds: z.array(z.string()),
+                mood: z.enum(['thinking', 'writing', 'reading', 'designing', 'done']),
+            }, forward('canvas-claude-focus')),
+            // ── Brand ─────────────────────────────────────────────────
+            tool('composition_set_brand', 'Bind a brand to a composition. Future prompts in this composition will get the brand auto-injected into your system prompt. Pass brandId="" to unbind.', { ...compositionRefShape,
+                brandId: z.string(),
+            }, forward('composition-set-brand')),
+            // ── Vector hive ───────────────────────────────────────────
+            tool('vector_segment_mask', 'AI background removal via SAM 3. Returns jobId; poll vector_segment_status. Pro+.', {
+                r2_key: z.string(),
+                compositionId: z.string().optional(),
+                blockId: z.string().optional(),
+            }, forward('vector:segment.mask')),
+            tool('vector_cut_kiss', 'Generate a CutContour kiss-cut layer with optional bleed for press-ready output. Pro+.', {
+                svg: z.string(),
+                bleedMm: z.number().min(0).max(10).default(2),
+            }, forward('vector:cut.kiss')),
+            /**
+             * ⚠⚠ THE IMAGE-EDIT TOOLS ARE WITHDRAWN — THEY DISPATCHED TO NOTHING.
+             *
+             * `image_edit_crop` / `_resize` / `_upscale` forwarded to `image:edit.crop`,
+             * `.resize` and `.upscale`. Those verbs are registered ONLY in
+             * `apps/cloudflare/src/rpc/image-rpcs.ts`, which is mounted nowhere — so every call
+             * answered `Unknown action: image:edit.crop`, verified live.
+             *
+             * ⚠ AND MOUNTING IT WOULD NOT HAVE FIXED THEM. All eleven `image:edit.*` handlers are
+             * one-liners delegating to `this._dispatchImageOp(...)`, and that method is called
+             * eleven times and DEFINED NOWHERE — the same ghost-function shape as the backup
+             * verbs' `_backupAdminCheck`. Mounted, they would throw instead of 404.
+             *
+             * ⚠ An advertised tool that dispatches to nothing is worse than a missing feature:
+             * the model spends a call discovering it, fails, and reports our bug as its own.
+             *
+             * TO BRING THEM BACK: implement `_dispatchImageOp` on the workspace, mount
+             * `ImageRpcs` (checking the `this.subscription.upsert` call in its Stripe claim
+             * handler first — that table is dead), then restore these three declarations.
+             */
+            /**
+             * ⚠⚠ FIVE MORE GHOST TOOLS WITHDRAWN — they dispatched to actions the workspace does
+             * not register. Verified against the LIVE registry (`list-actions`, 1,118 names), not
+             * by grep: `agent-facts-list`, `brand-propose-update`, `canvas-add-claude-template`,
+             * `canvas-add-document`, `vector:trace.preset`.
+             *
+             * ⚠ THE SYMPTOMS DIFFERED, WHICH IS WHY THEY SURVIVED. Four answered "Unknown message
+             * type"; `vector:trace.preset` answered a bare "Internal error", which reads like a
+             * transient fault rather than a missing verb. Only the registry told the truth.
+             *
+             * ⚠ `canvas_add_document` and `canvas_add_claude_template` are also documented in the
+             * `clearly-canvas` skill, so an agent is told twice to call something that does not
+             * exist. Fixing the skill is a separate edit outside this repo.
+             */
+            // ── Discovery + fallback ──────────────────────────────────
+            tool('canvas_actions', 'List every available canvas RPC with its arguments + an example. Use this when you need an RPC that isn\'t exposed as a typed tool here. Filter by domain or keyword search.', {
+                format: z.enum(['markdown', 'json']).default('markdown'),
+                compact: z.boolean().default(true),
+                domain: z.string().optional(),
+                q: z.string().optional(),
+            }, forward('canvas:actions')),
+            tool('clearly_invoke', 'Invoke any Clearly worker RPC by name. The fallback for actions not exposed as a typed tool above. Look up the action first via canvas_actions to see its argument schema. Prefer the typed tools — this one is the safety valve, not the default.', {
+                action: z.string().describe('The RPC name — e.g., "canvas-add-brand-snapshot", "smart-cutout-create", "claude-signature-sign".'),
+                args: z.record(z.string(), z.unknown()).describe('Arguments object for the action.'),
+            }, async ({ action, args }) => {
+                return forward(action)(args);
+            }),
+        ],
+    });
+}