@clearlysh/beehaven 0.8.16

package/dist/daemon-omni-principal.js

@@ -0,0 +1,580 @@
+/**
+ * daemon-omni-principal — Omni's own tools, moved out of the Mac app.
+ *
+ * ## Why this exists
+ *
+ * Omni's tool set lived in `apps/electron/electron/ea-agent.ts` and was handed
+ * to an SDK `query()` that ELECTRON spawned. That made a second `claude` on the
+ * machine — the daemon already runs one properly (`daemon-omni.ts`) — on the
+ * same BYOK login, with neither aware of the other's conversation. Verified by
+ * process tree: two `claude --output-format stream-json` children, one under
+ * `Clearly Dev.app`, one under `daemon-entry.js`.
+ *
+ * These are the same tools, defined the same way — `createSdkMcpServer` +
+ * `tool()`, dispatched IN PROCESS with no subprocess, stdio or socket — just
+ * living where the session lives now. Nothing here speaks MCP over a wire; the
+ * name describes the schema shape, not a transport.
+ *
+ * ## The context is the whole design
+ *
+ * A tool needs one of two things, never both, and the split is what let this
+ * move at all:
+ *
+ *   • **`invokeRpc`** — the workspace. Memory, the board, design docs, comments.
+ *     These were already round-tripping to the DO from Electron, so moving them
+ *     changes only which process makes the call.
+ *   • **`emit` / `ask`** — the PRINCIPAL's screen. Replies, questions, windows,
+ *     previews. These are the reason the move is not trivial: the daemon has no
+ *     UI, so it emits and whatever is attached (the Mac app's chat, the avatar
+ *     panel, a CLI) renders. `ask` additionally BLOCKS until an answer returns,
+ *     which is what makes a question a question rather than a remark.
+ *
+ * ⚠ `ask` MUST be able to time out and MUST distinguish its outcomes. A turn is
+ * parked inside the tool call while it waits; "they chose B", "they dismissed
+ * it" and "they never saw it" warrant opposite behaviour, and collapsing them is
+ * how an agent decides silence is consent.
+ */
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+// ── shared helpers ───────────────────────────────────────────────────────────
+/**
+ * ⚠ `ticket.data` IS WRITTEN AS AN OBJECT AND READ BACK AS A JSON STRING, and
+ * `ticket-update` REPLACES it wholesale. Every write here is therefore
+ * read-merge-write; a blind write destroys `type`, sub-tasks, the design-doc
+ * link and any comments already on the card.
+ */
+function readData(raw) {
+    if (raw && typeof raw === 'object')
+        return raw;
+    if (typeof raw !== 'string' || !raw.trim())
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Project key for scoping memory — the folder BASENAME, not its path, so the
+ *  same repo cloned elsewhere is the same project. */
+function projectTag(cwd) {
+    const b = (cwd ?? '').replace(/\/+$/, '').split('/').filter(Boolean).pop() ?? '';
+    return b ? `project:${b.toLowerCase()}` : '';
+}
+/** The board's four columns. Legacy words still resolve server-side, but writing
+ *  one puts a card in a column the kanban does not draw. */
+const STATUSES = ['todo', 'in-progress', 'in-review', 'done'];
+// ── session state ────────────────────────────────────────────────────────────
+/**
+ * The card the session is working on — what the design gate checks against, and
+ * the default target for comments and design docs.
+ *
+ * Module-scoped rather than per-tool because it is genuinely session state: the
+ * gate in `daemon-omni-hooks` has to read the same value the tools write.
+ */
+let activeTicketId = '';
+let activeTicketTitle = '';
+export const getActiveTicket = () => ({ id: activeTicketId, title: activeTicketTitle });
+export function setActiveTicket(id, title = '') {
+    activeTicketId = id || '';
+    if (title)
+        activeTicketTitle = title;
+}
+/** ticketId → design doc id, so the write gate is not a network call per edit. */
+const designDocByTicket = new Map();
+/** Doc ids whose CONTENT has been read this session — the precondition for
+ *  closing a card, and what makes the pre-merge review more than a checkbox. */
+const designDocsRead = new Set();
+const designReviews = new Map();
+export const designReviewed = (t) => designReviews.has(t);
+export function resetPrincipalSession() {
+    activeTicketId = '';
+    activeTicketTitle = '';
+    designDocsRead.clear();
+    designReviews.clear();
+    designDocByTicket.clear();
+    /**
+     * ⚠ THE CONTEXT IS NOT CLEARED HERE, deliberately.
+     *
+     * `resetPrincipalSession` ends a CONVERSATION; the context belongs to the
+     * MOUNT and outlives it. Clearing it would turn the design gate off after the
+     * first session ended — `principalGateActive()` would go false and every
+     * subsequent edit would sail through ungated, which is the silent failure this
+     * whole mechanism exists to prevent. Unmount with `setPrincipalTools(null)`.
+     */
+}
+/**
+ * The live context, kept so the HOOKS can reach the workspace too.
+ *
+ * ⚠ The design gate runs in `daemon-omni-hooks`, which is a different module and
+ * has no context of its own — it only sees the SDK's hook input. Without this it
+ * could not resolve whether the active card has a design doc, which is the entire
+ * question it exists to answer.
+ */
+let _ctx = null;
+/** Whether the gate should apply at all. False for a headless session with no
+ *  principal attached — such a session has no board to write to, so gating its
+ *  edits on one would refuse every write forever. */
+export const principalGateActive = () => !!_ctx;
+/** Drop the held context. Called on UNMOUNT, never on session reset. */
+export function clearPrincipalContext() {
+    _ctx = null;
+}
+/**
+ * The ACTIVE card's lifecycle state, straight from the board.
+ *
+ * ⚠⚠ THIS REPLACES A LOOKUP THAT COULD NOT GO STALE-SAFE. `designDocIdFor` reads a `designDocId`
+ * out of the card's `data` blob and memoises it in `designDocByTicket` — a cache that is never
+ * invalidated, so DELETING the design document leaves the gate satisfied forever. It also knows
+ * about exactly one kind of artifact, found by a 200-row `ticket-list` scan.
+ *
+ * `work-status` answers all four gates from `ticket_artifacts`, and — the part that matters —
+ * RESOLVES each link before counting it, so a deleted target un-satisfies its gate.
+ *
+ * ⚠ RETURNS null ON ANY FAILURE, and every caller must treat that as "unknown", never as "no".
+ * An unreachable workspace must not start refusing edits.
+ */
+export async function activeWorkStatus() {
+    if (!_ctx || !activeTicketId)
+        return null;
+    try {
+        const r = await _ctx.invokeRpc('work-status', { ticketId: activeTicketId });
+        return r?.ok ? r : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Does the ACTIVE card have a design doc? The gate's only question. */
+export async function activeTicketHasDesignDoc() {
+    if (!_ctx || !activeTicketId)
+        return false;
+    try {
+        /**
+         * ⚠⚠ THE BOARD IS ASKED FIRST, because it is the only source that can tell a LIVE design doc
+         * from a deleted one. The legacy `designDocId` path memoises an id and never re-checks it, so
+         * deleting the document leaves this gate passing forever — a gate that cannot fail is not a
+         * gate.
+         */
+        const work = await activeWorkStatus();
+        if (work)
+            return work.gates['eng-design'] === true || work.gates.design === true;
+        // ⚠ FALLBACK, NOT A SECOND SOURCE OF TRUTH: only reached when `work-status` could not answer
+        //   (an older worker, or an unreachable workspace). Cards written before `ticket_artifacts`
+        //   existed still carry `designDocId`, and refusing them would be a regression.
+        return !!(await designDocIdFor(_ctx, activeTicketId));
+    }
+    catch {
+        // ⚠ FAIL OPEN. An unreachable workspace must not block every edit.
+        return true;
+    }
+}
+/** Comment on the active card from outside the tool set — the PR-link hook. */
+export async function commentOnActiveCard(body) {
+    if (!_ctx || !activeTicketId)
+        return false;
+    try {
+        const listed = await _ctx.invokeRpc('ticket-list', { limit: 200 });
+        const row = (listed?.tickets ?? []).find((t) => String(t.id) === activeTicketId);
+        if (!row)
+            return false;
+        const data = readData(row.data);
+        const comments = Array.isArray(data.comments) ? data.comments : [];
+        const activity = Array.isArray(data.activity) ? data.activity : [];
+        const now = Date.now();
+        comments.push({ id: `c-${now}-${Math.random().toString(36).slice(2, 7)}`, author: 'Omni', body: body.slice(0, 4000), ts: now });
+        activity.push({ ts: now, by: 'Omni', kind: 'comment', msg: 'commented' });
+        await _ctx.invokeRpc('ticket-update', { id: activeTicketId, updates: { data: { ...data, comments, activity } } });
+        _ctx.emit({ kind: 'workspace', text: 'PR linked on the card' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve a card's design doc — cache first, then the card's own `data`. */
+export async function designDocIdFor(ctx, ticketId) {
+    if (!ticketId)
+        return '';
+    const cached = designDocByTicket.get(ticketId);
+    if (cached)
+        return cached;
+    try {
+        const listed = await ctx.invokeRpc('ticket-list', { limit: 200 });
+        const row = (listed?.tickets ?? []).find((t) => String(t.id) === ticketId);
+        const id = String(readData(row?.data).designDocId || '');
+        if (id)
+            designDocByTicket.set(ticketId, id);
+        return id;
+    }
+    catch {
+        return '';
+    }
+}
+// ── the server ───────────────────────────────────────────────────────────────
+export function createPrincipalMcpServer(ctx) {
+    // Held for the hooks — see `_ctx`. Set here rather than in `setPrincipalTools`
+    // so the two can never disagree about which context is live.
+    _ctx = ctx;
+    const cwd = () => ctx.cwd?.();
+    /**
+     * ⚠ THE ONLY CHANNEL TO THE PRINCIPAL. Ordinary assistant text is not shown —
+     * it goes to the work log — so a turn that never calls this is a turn where
+     * Omni did work and said nothing.
+     */
+    const reply = tool('reply_to_principal', 'Say something to the principal. This is the ONLY way to reach them — your ordinary response text is never shown, it is your own working space. Plain executive prose in markdown: no code, no diffs, no file paths, no command output. Call it again mid-task to report progress.', {
+        text: z.string().describe('What the principal reads. Outcome first. Markdown — bold the one thing that matters, no headings, no code blocks.'),
+        tone: z.enum(['neutral', 'working', 'good', 'caution', 'problem', 'thinking']).optional()
+            .describe('How it should land. Drives both the motion and the speaking voice.'),
+    }, async (args) => {
+        const text = String(args.text ?? '').trim();
+        if (!text)
+            return { content: [{ type: 'text', text: 'Empty message — nothing was shown.' }], isError: true };
+        ctx.emit({ kind: 'prose', text, tone: args.tone });
+        return { content: [{ type: 'text', text: 'Delivered.' }] };
+    });
+    const askPrincipal = tool('ask_principal', 'Ask the principal a question and WAIT for the answer. Use at a genuine fork: two defensible options with different consequences, an ambiguous requirement, a destructive step. Prefer options over free text — one tap beats a paragraph. Never for reassurance or permission to start.', {
+        question: z.string().describe('The question, one line, in their language.'),
+        detail: z.string().optional().describe('Markdown above the options — the trade-off, what you found.'),
+        options: z.array(z.object({
+            value: z.string(), label: z.string(), detail: z.string().optional(),
+        })).optional().describe('2-4 options, your recommendation first. Omit ONLY when the answer cannot be enumerated.'),
+    }, async (args) => {
+        const hasOptions = Array.isArray(args.options) && args.options.length > 0;
+        const a = await ctx.ask({
+            kind: hasOptions ? 'choice' : 'text',
+            question: args.question,
+            detail: args.detail,
+            options: hasOptions ? args.options.slice(0, 4) : undefined,
+        });
+        if (a.outcome === 'timeout') {
+            return { content: [{ type: 'text', text: 'No answer — they may be away from the machine. Do NOT treat this as agreement. Take the reversible option and say you did, or stop and leave it for them.' }] };
+        }
+        if (a.outcome === 'dismissed') {
+            return { content: [{ type: 'text', text: 'They dismissed the question. Take that as "not now" — do not re-ask it this turn.' }] };
+        }
+        return { content: [{ type: 'text', text: `They answered: ${a.value}` }] };
+    });
+    const proposePlan = tool('propose_plan', 'Put a plan in front of the principal and wait for approval before building. Required before code changes when they have asked to approve plans; otherwise use it when building the wrong thing would be expensive.', {
+        summary: z.string().describe('One line: what you are going to do.'),
+        plan: z.string().describe('Markdown. What you will change, in what order, what it touches, what you are unsure about. Readable in thirty seconds.'),
+    }, async (args) => {
+        const a = await ctx.ask({
+            kind: 'approve',
+            question: args.summary,
+            detail: args.plan,
+            options: [
+                { value: 'approve', label: 'Go ahead', detail: 'Build it as described' },
+                { value: 'revise', label: 'Change something', detail: 'Tell them what to alter' },
+                { value: 'reject', label: 'Not this', detail: 'Do not build it' },
+            ],
+        });
+        if (a.outcome !== 'answered') {
+            return { content: [{ type: 'text', text: 'The plan was not answered. Do not start building — an unanswered plan is not an approved one. Say you are waiting on them.' }] };
+        }
+        if (a.value === 'approve')
+            return { content: [{ type: 'text', text: 'Approved. Make the card, write the design doc from this plan, then build it.' }] };
+        if (a.value === 'revise')
+            return { content: [{ type: 'text', text: 'They want changes. Ask what to change with ask_principal, then propose again. Do NOT start the original plan.' }] };
+        return { content: [{ type: 'text', text: 'Rejected. Do not build it. Ask what they would rather do, or move on.' }] };
+    });
+    // ── memory ────────────────────────────────────────────────────────────────
+    const remember = tool('remember', 'Save something worth knowing in every future conversation — how the principal works, a fact about this project, a constraint you discovered. Persists on the workspace across sessions and machines.', {
+        key: z.string().describe('Short stable identifier, kebab-case. Reusing a key UPDATES that memory rather than adding a second.'),
+        value: z.string().describe('The fact, one or two sentences, written to be read cold in six months.'),
+        category: z.enum(['fact', 'preference', 'context', 'decision', 'note']).optional(),
+        importance: z.number().min(0).max(1).optional().describe('0-1. Above 0.7 for things that change how you behave.'),
+        global: z.boolean().optional().describe('True when this is about the PRINCIPAL and applies everywhere, not just this folder.'),
+    }, async (args) => {
+        const tag = args.global ? '' : projectTag(cwd());
+        try {
+            const r = await ctx.invokeRpc('agent-memory-remember', {
+                key: String(args.key).trim(),
+                value: String(args.value).trim(),
+                category: args.category ?? 'note',
+                importance: typeof args.importance === 'number' ? args.importance : 0.5,
+                tags: tag ? [tag] : [],
+            });
+            if (r?.ok)
+                ctx.emit({ kind: 'workspace', text: `Remembered: ${args.key}` });
+            return { content: [{ type: 'text', text: r?.ok ? 'Saved.' : 'Could not save it; continue anyway.' }] };
+        }
+        catch {
+            return { content: [{ type: 'text', text: 'Could not save it; continue anyway.' }] };
+        }
+    });
+    const recall = tool('recall', 'Search your memory of this workspace for something not already in your context — an old decision and its reasoning, a fact about a part of the project you have not touched. Search before you assume something was never decided.', { query: z.string().describe('What you are looking for, in plain words.') }, async (args) => {
+        try {
+            const r = await ctx.invokeRpc('agent-memory-search', { query: args.query, limit: 12 });
+            const hits = r?.memories ?? [];
+            if (!hits.length) {
+                // ⚠ "Nothing found" and "the lookup failed" are the same string to a
+                // model and warrant opposite behaviour. Say which it was.
+                return { content: [{ type: 'text', text: `Nothing in memory for "${args.query}". Either it was never recorded, or the workspace is unreachable — do not treat this as proof it was never decided.` }] };
+            }
+            return { content: [{ type: 'text', text: hits.map((m) => `- [${m.category}] **${m.key}** — ${String(m.value ?? '').slice(0, 600)}`).join('\n') }] };
+        }
+        catch {
+            return { content: [{ type: 'text', text: 'Memory is unreachable right now — do not treat that as an absence.' }] };
+        }
+    });
+    // ── the board ─────────────────────────────────────────────────────────────
+    const createTicket = tool('create_ticket', 'Create a card on the project board. Do this BEFORE starting any coding work — one card per unit of work. Also use it to capture work you are NOT doing now (a bug you noticed, a follow-up) so it stops living in your head.', {
+        title: z.string().describe('One line, outcome-shaped.'),
+        body: z.string().optional().describe('What needs doing and how you will know it is done. The principal reads this.'),
+        status: z.enum(STATUSES).optional(),
+        priority: z.number().min(0).max(3).optional(),
+        issueType: z.enum(['epic', 'story', 'task', 'bug', 'subtask']).optional(),
+        parentId: z.string().optional().describe('The epic or story this belongs under.'),
+    }, async (args) => {
+        try {
+            // ⚠ `issueType`, NOT `type` — the wire protocol uses `type` as the ACTION
+            // discriminator, so a payload field of that name is overwritten by the
+            // action name before the handler sees it.
+            const r = await ctx.invokeRpc('ticket-create', {
+                title: String(args.title).slice(0, 200),
+                ...(args.body ? { body: String(args.body).slice(0, 8000) } : {}),
+                status: args.status ?? 'todo',
+                priority: typeof args.priority === 'number' ? args.priority : 1,
+                issueType: args.issueType ?? 'task',
+                ...(args.parentId ? { parentId: args.parentId } : {}),
+            });
+            const id = String(r?.id ?? '');
+            if (!id)
+                return { content: [{ type: 'text', text: 'Could not create the card. Carry on with the work and say the board is not recording it.' }] };
+            setActiveTicket(id, String(args.title));
+            ctx.emit({ kind: 'workspace', text: `Card: ${r?.key ? `${r.key} ` : ''}${args.title}` });
+            return { content: [{ type: 'text', text: `Created ${r?.key ?? id} — id \`${id}\`. This is now the active card. Write its design doc with design_doc before editing any file.` }] };
+        }
+        catch {
+            return { content: [{ type: 'text', text: 'Could not create the card. Carry on with the work and say so.' }] };
+        }
+    });
+    const updateTicket = tool('update_ticket', 'Move a card or change it. in-progress when you START, in-review when the work is done but unverified, done when you have VERIFIED it. A board that lags the work is worse than no board.', {
+        id: z.string(),
+        status: z.enum(STATUSES).optional(),
+        title: z.string().optional(),
+        body: z.string().optional(),
+        priority: z.number().min(0).max(3).optional(),
+    }, async (args) => {
+        const { id, ...updates } = args;
+        // ⚠ THE MERGE GATE — a card cannot reach `done` until its design doc was
+        // re-read THIS SESSION and a review recorded.
+        if (updates.status === 'done') {
+            const docId = await designDocIdFor(ctx, id);
+            if (docId && !designReviews.has(id)) {
+                return { content: [{ type: 'text', text: `Not moved. Before a card is done you re-read its design doc and compare it against what you built: design_doc op "read" for ${id}, then record_design_review. Write down any deviation — a documented one is fine, an undocumented one is how the doc becomes fiction.` }], isError: true };
+            }
+        }
+        try {
+            const r = await ctx.invokeRpc('ticket-update', { id, updates });
+            const ok = !!r && r.error == null;
+            if (ok && updates.status) {
+                ctx.emit({ kind: 'workspace', text: `Moved to ${updates.status}` });
+                if (updates.status === 'in-progress')
+                    setActiveTicket(id, updates.title ?? '');
+            }
+            return { content: [{ type: 'text', text: ok ? `Updated ${id}.` : `Could not update ${id}. Carry on with the work.` }] };
+        }
+        catch {
+            return { content: [{ type: 'text', text: `Could not update ${id}. Carry on with the work.` }] };
+        }
+    });
+    const listTickets = tool('list_tickets', 'Read the board. Call this when you need current state, want the done column, or are looking for a card you did not create.', { status: z.enum(STATUSES).optional() }, async (args) => {
+        try {
+            const r = await ctx.invokeRpc('ticket-list', { ...(args.status ? { status: args.status } : {}), limit: 100 });
+            const rows = r?.tickets ?? [];
+            if (!rows.length)
+                return { content: [{ type: 'text', text: args.status ? `No cards in ${args.status}.` : 'The board is empty.' }] };
+            return { content: [{ type: 'text', text: rows.map((t) => `- [${t.status}] ${t.key ? `${t.key} ` : ''}${t.title} — id \`${t.id}\``).join('\n') }] };
+        }
+        catch {
+            return { content: [{ type: 'text', text: 'The board is unreachable right now.' }] };
+        }
+    });
+    const commentOnCard = tool('comment_on_card', 'Post a comment on a card — a status update, what you found, why something took longer. Appears in the card\'s Comments tab. A PR opened with `gh pr create` posts its own link, so do not duplicate that.', {
+        ticketId: z.string().optional().describe('Defaults to the active card.'),
+        body: z.string().describe('Markdown.'),
+    }, async (args) => {
+        const ticketId = String(args.ticketId || activeTicketId || '');
+        if (!ticketId)
+            return { content: [{ type: 'text', text: 'No card is active — pass a ticketId.' }], isError: true };
+        try {
+            // Read-merge-write: `data` is replaced wholesale by ticket-update.
+            const listed = await ctx.invokeRpc('ticket-list', { limit: 200 });
+            const row = (listed?.tickets ?? []).find((t) => String(t.id) === ticketId);
+            if (!row)
+                return { content: [{ type: 'text', text: 'No such card.' }], isError: true };
+            const data = readData(row.data);
+            const comments = Array.isArray(data.comments) ? data.comments : [];
+            const activity = Array.isArray(data.activity) ? data.activity : [];
+            const now = Date.now();
+            // Shapes mirror the board page's CardComment / CardActivity exactly — a
+            // different shape renders as a blank row rather than failing visibly.
+            comments.push({ id: `c-${now}-${Math.random().toString(36).slice(2, 7)}`, author: 'Omni', body: String(args.body).slice(0, 4000), ts: now });
+            activity.push({ ts: now, by: 'Omni', kind: 'comment', msg: 'commented' });
+            await ctx.invokeRpc('ticket-update', { id: ticketId, updates: { data: { ...data, comments, activity } } });
+            ctx.emit({ kind: 'workspace', text: 'Commented on the card' });
+            return { content: [{ type: 'text', text: 'Comment posted.' }] };
+        }
+        catch {
+            return { content: [{ type: 'text', text: 'Could not post the comment. Carry on with the work.' }] };
+        }
+    });
+    // ── the design doc ────────────────────────────────────────────────────────
+    const designDoc = tool('design_doc', 'Write, read or revise the engineering design for a card. REQUIRED before any code change — you cannot edit a file until the active card has one. Also how you re-read a design before closing a card.', {
+        op: z.enum(['create', 'read', 'revise']),
+        ticketId: z.string().optional().describe('Defaults to the active card.'),
+        title: z.string().optional(),
+        problem: z.string().optional().describe('create: what is wrong today and who it affects. Concrete.'),
+        approach: z.string().optional().describe('create: what you will build, in enough detail that someone else could build the same thing.'),
+        rejected: z.string().optional().describe('create: what you considered and why not. The most valuable section and the one people skip.'),
+        touches: z.string().optional().describe('create: which files, routes, tables or services this changes.'),
+        verification: z.string().optional().describe('create: how you will KNOW it works — the test, the command, the thing you will open.'),
+        note: z.string().optional().describe('revise: what changed about the design and why.'),
+    }, async (args) => {
+        const ticketId = String(args.ticketId || activeTicketId || '');
+        if (!ticketId)
+            return { content: [{ type: 'text', text: 'No card is active. Create one with create_ticket first — a design doc documents a unit of work, so it needs the unit.' }], isError: true };
+        if (args.op === 'read') {
+            const docId = await designDocIdFor(ctx, ticketId);
+            if (!docId)
+                return { content: [{ type: 'text', text: `No design doc for card ${ticketId}.` }], isError: true };
+            try {
+                const d = await ctx.invokeRpc('document-get', { id: docId });
+                designDocsRead.add(docId);
+                return { content: [{ type: 'text', text: `# ${d?.title ?? ''}\n(document id \`${docId}\`)\n\n${d?.markdown ?? d?.html ?? ''}` }] };
+            }
+            catch {
+                return { content: [{ type: 'text', text: 'Could not read the design doc.' }], isError: true };
+            }
+        }
+        if (args.op === 'revise') {
+            const docId = await designDocIdFor(ctx, ticketId);
+            if (!docId)
+                return { content: [{ type: 'text', text: 'No design doc to revise.' }], isError: true };
+            try {
+                await ctx.invokeRpc('document-append', { id: docId, markdown: `\n\n## Design revised mid-flight\n${String(args.note ?? '').slice(0, 2000)}` });
+                return { content: [{ type: 'text', text: 'Revision appended to the design doc.' }] };
+            }
+            catch {
+                return { content: [{ type: 'text', text: 'Could not append the revision.' }] };
+            }
+        }
+        const missing = ['title', 'problem', 'approach', 'verification'].filter((k) => !String(args[k] ?? '').trim());
+        if (missing.length) {
+            return { content: [{ type: 'text', text: `Cannot create the design — missing: ${missing.join(', ')}. These four are required.` }], isError: true };
+        }
+        const title = `Design — ${args.title}`.slice(0, 200);
+        const markdown = [
+            `# ${title}`,
+            `\n## The problem`, args.problem,
+            `\n## The approach`, args.approach,
+            args.rejected ? `\n## Considered and rejected\n${args.rejected}` : '',
+            args.touches ? `\n## What it touches\n${args.touches}` : '',
+            `\n## How we will know it worked`, args.verification,
+        ].filter(Boolean).join('\n');
+        try {
+            const doc = await ctx.invokeRpc('document-create', { title, markdown });
+            const docId = String(doc?.id ?? '');
+            if (!docId)
+                throw new Error('no id');
+            designDocByTicket.set(ticketId, docId);
+            // Written by us, so it counts as read — re-fetching a document Omni just
+            // authored would be ceremony, not verification.
+            designDocsRead.add(docId);
+            // ⚠ MERGE the link into `data`, never overwrite it.
+            const listed = await ctx.invokeRpc('ticket-list', { limit: 200 });
+            const row = (listed?.tickets ?? []).find((t) => String(t.id) === ticketId);
+            await ctx.invokeRpc('ticket-update', { id: ticketId, updates: { data: { ...readData(row?.data), designDocId: docId } } });
+            ctx.emit({ kind: 'workspace', text: `Design doc: ${title}` });
+            return { content: [{ type: 'text', text: `Design filed — document id \`${docId}\`. You can now make the change.` }] };
+        }
+        catch {
+            /**
+             * ⚠ FAILS OPEN, AND SAYS SO. If the workspace is unreachable the design
+             * cannot be filed, and blocking every edit on that would make an offline
+             * daemon stop all work. The gate exists to make the doc habitual, not to
+             * make the daemon a dependency of the editor.
+             */
+            return { content: [{ type: 'text', text: 'Could not save the design doc (the workspace may be unreachable). Say so in your next reply, keep the design in the conversation, and carry on — but file it when the workspace is back.' }] };
+        }
+    });
+    const recordDesignReview = tool('record_design_review', 'Record your pre-merge check: you re-read the design doc and compared it against what you actually built. Required before a card can move to done.', {
+        ticketId: z.string().optional(),
+        verdict: z.string().describe('What you found. Whether it matches, and where it deviated and why. "Matches" alone is not a review.'),
+    }, async (args) => {
+        const ticketId = String(args.ticketId || activeTicketId || '');
+        if (!ticketId)
+            return { content: [{ type: 'text', text: 'No card is active.' }], isError: true };
+        const docId = await designDocIdFor(ctx, ticketId);
+        // ⚠ THE DOC MUST HAVE BEEN READ THIS SESSION, or this is a checkbox a model
+        // can tick about a document it has never seen.
+        if (!docId || !designDocsRead.has(docId)) {
+            return { content: [{ type: 'text', text: 'Read the design first — design_doc op "read" for this card. A review written without opening the document is not a review.' }], isError: true };
+        }
+        designReviews.set(ticketId, String(args.verdict));
+        try {
+            await ctx.invokeRpc('document-append', { id: docId, markdown: `\n\n## Pre-merge review\n${String(args.verdict).slice(0, 4000)}` });
+        }
+        catch { /* recorded in-session either way — losing the append must not block shipping verified work */ }
+        ctx.emit({ kind: 'workspace', text: 'Design review recorded' });
+        return { content: [{ type: 'text', text: 'Review recorded on the design doc. The card can move to done.' }] };
+    });
+    // ── their screen ──────────────────────────────────────────────────────────
+    /**
+     * ⚠ THE ONE CAPABILITY THAT IS NOT UNIVERSAL.
+     *
+     * Floating windows need a windowing surface — the Mac app. A terminal user has
+     * everything else (replies, questions, the board, design docs, memory, the
+     * preview URL), and this is the single thing they cannot have.
+     *
+     * The tool stays REGISTERED either way and reports honestly when it lands
+     * nowhere. Hiding it would be worse: the tool set would differ per surface, so
+     * the same prompt would behave differently depending on who was attached, and
+     * an agent told a capability exists and then silently denied it is exactly how
+     * a model ends up insisting it showed you something it did not.
+     */
+    const openWindow = tool('open_window', "Open something on the principal's screen in a floating window beside the conversation — the project board, a document, or a canvas composition. Several can be open at once. Only works when they are on the desktop app; on a terminal it does nothing and you will be told.", {
+        kind: z.enum(['board', 'document', 'composition']),
+        id: z.string().optional().describe('The specific document/composition/project. Omit to open the collection view.'),
+        title: z.string().optional(),
+    }, async (args) => {
+        const target = `${args.kind}:${args.id || 'all'}`;
+        ctx.emit({ kind: 'window', op: 'open', target, title: args.title });
+        if (ctx.canOpenWindows?.() === false) {
+            return { content: [{ type: 'text', text: `They are on a terminal, so no window opened. Describe what you would have shown, or use show_preview to hand them a URL.` }] };
+        }
+        return { content: [{ type: 'text', text: `Opened ${args.kind} (window id "${target}").` }] };
+    });
+    const closeWindow = tool('close_window', 'Close a floating window. Close things when they stop being relevant — a screen covered in windows from three topics ago is worse than none.', { windowId: z.string().optional(), all: z.boolean().optional() }, async (args) => {
+        ctx.emit({ kind: 'window', op: 'close', target: args.all ? '*' : String(args.windowId ?? '') });
+        return { content: [{ type: 'text', text: args.all ? 'Closed all windows.' : `Closed ${args.windowId}.` }] };
+    });
+    const showPreview = tool('show_preview', 'Show a live page you just made run — a dev server, a built page. It opens beside the conversation and reloads on later calls. NEVER tell the principal to open a URL themselves.', { url: z.string(), caption: z.string().optional() }, async (args) => {
+        ctx.emit({ kind: 'preview', url: String(args.url), caption: String(args.caption ?? 'Open it') });
+        return { content: [{ type: 'text', text: 'Shown.' }] };
+    });
+    const showImage = tool('show_image', 'Show an image — a chart, a screenshot of a failure, a diff worth seeing. Takes a data URI.', { dataUri: z.string(), caption: z.string().optional() }, async (args) => {
+        ctx.emit({ kind: 'image', dataUri: String(args.dataUri), caption: String(args.caption ?? '') });
+        return { content: [{ type: 'text', text: 'Shown.' }] };
+    });
+    return createSdkMcpServer({
+        name: 'principal',
+        version: '1.0.0',
+        /**
+         * ⚠ NEVER DEFERRED BEHIND TOOL SEARCH. These are the difference between
+         * showing the work and telling the principal to go and look for it — the
+         * model must always be able to see that they exist.
+         */
+        alwaysLoad: true,
+        tools: [
+            reply, askPrincipal, proposePlan,
+            remember, recall,
+            createTicket, updateTicket, listTickets, commentOnCard,
+            designDoc, recordDesignReview,
+            openWindow, closeWindow, showPreview, showImage,
+        ],
+    });
+}