@dalmasonto/taskflow-mcp 2.13.1 → 2.15.0

package/dist/server.js

@@ -14,12 +14,14 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { loadConfigFile, findConfigPath, resolveProfile, resolveProfileOrAsk, } from "./config.js";
 import { TaskflowClient, TaskflowApiError } from "./client.js";
-import { renderInstructions } from "./agent-instructions.js";
+import { renderInstructions, renderScopeNotice } from "./agent-instructions.js";
+import { agentsManageFailure } from "./agents-manage.js";
 import { resolveAttachments } from "./attachments.js";
 import { getMirrorStatus } from "./mirror.js";
 import { downloadAttachment } from "./attachment-download.js";
 import { detectTmuxPane } from "./tmux.js";
 import { AGENT_INSTRUCTIONS } from "./instructions.js";
+import { diffLines, installScript, installedStatus, uninstallScript, } from "./toolbox.js";
 import { sessionIdentifier } from "./session-identifier.js";
 import { getConnectionStatus } from "./connect.js";
 import { selectProfile } from "./runtime.js";
@@ -48,6 +50,17 @@ function fail(err) {
             : String(err);
     return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
 }
+/// #605: the failure of an agent-management call. A bare 403 would read as "not
+/// allowed" with no way forward, and the way forward is specific — and DIFFERENT
+/// for the two 403s (missing scope vs. self-revoke). See `agentsManageFailure`.
+function failAgentsManage(err) {
+    if (err instanceof TaskflowApiError) {
+        const message = agentsManageFailure(err);
+        if (message)
+            return { content: [{ type: "text", text: message }], isError: true };
+    }
+    return fail(err);
+}
 /**
  * The refusal returned instead of guessing an identity.
  *
@@ -119,10 +132,77 @@ export function collisionWarning(profileName, live) {
         `identity share one inbox and one read cursor, so messages meant for one will ` +
         `be marked read by the other. Tell your human before you continue.`);
 }
-/**
- * Construct the MCP server with all tools registered. The config is loaded
- * eagerly so a broken `.taskflow.json` fails fast at startup with a clear error.
- */
+/// The label a vetting record carries: the agent's own display name, so a
+/// teammate reading "vetted by Build 3" knows who to ask.
+async function agentLabelFor(client) {
+    try {
+        const identity = (await client.whoami());
+        return identity?.display_name ?? identity?.agent?.display_name ?? "an agent";
+    }
+    catch {
+        return "an agent";
+    }
+}
+async function toolboxIndexFor(client, projectRoot) {
+    try {
+        const listed = (await client.toolboxList());
+        const entries = (listed?.entries ?? []);
+        const scripts = entries.filter((entry) => entry.kind === "script");
+        const statuses = scripts.length
+            ? await installedStatus({
+                projectRoot,
+                serverScripts: scripts.map((script) => ({ name: script.name, version: script.version })),
+            })
+            : [];
+        const byName = new Map(statuses.map((status) => [status.name, status]));
+        return {
+            count: entries.length,
+            entries: entries.map((entry) => {
+                const status = byName.get(entry.name);
+                return {
+                    name: entry.name,
+                    kind: entry.kind,
+                    description: entry.description,
+                    status: entry.status,
+                    version: entry.version,
+                    install_state: status?.state ?? "n/a",
+                    installed_version: status?.installed_version ?? null,
+                    local_edit: status?.local_edit ?? false,
+                };
+            }),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** The readable half of the index: what an agent reads without calling anything
+ *  else. Kept SHORT — entries are one line each, and code never appears. */
+function renderToolboxIndex(index) {
+    if (!index || index.count === 0)
+        return null;
+    const lines = [
+        `Project toolbox — ${index.count} entr${index.count === 1 ? "y" : "ies"} already saved for this project:`,
+    ];
+    for (const entry of index.entries.slice(0, 24)) {
+        const marker = entry.kind === "memory"
+            ? "[memory]"
+            : entry.install_state === "current"
+                ? `[installed v${entry.installed_version}]`
+                : entry.install_state === "update-available"
+                    ? `[installed v${entry.installed_version}, update available: v${entry.version}]`
+                    : entry.install_state === "locally-edited"
+                        ? `[installed v${entry.installed_version}, EDITED LOCALLY — save the fix with toolbox_save or reinstall]`
+                        : "[script, not installed]";
+        const status = entry.status !== "approved" ? ` (${entry.status})` : "";
+        lines.push(`- ${entry.name} ${marker}${status} — ${entry.description}`);
+    }
+    if (index.entries.length > 24) {
+        lines.push(`…and ${index.entries.length - 24} more: call toolbox_list.`);
+    }
+    lines.push("Read one with toolbox_get (nothing loads code into your context until you ask). Check the toolbox BEFORE building tooling, and save what works.");
+    return lines.join("\n");
+}
 export function buildServer(options = {}) {
     const configPath = findConfigPath({
         configPath: options.configPath,
@@ -254,6 +334,12 @@ export function buildServer(options = {}) {
                 return picked.refusal;
             const { client } = picked;
             const identity = await client.whoami();
+            // #617: the toolbox index at connect. Progressive disclosure is the
+            // whole point: names and one-line descriptions (never code), plus what
+            // is already installed locally and what has a newer version — so the
+            // agent knows what exists and what it can run WITHOUT loading any of
+            // it. A toolbox that is unreachable must not break whoami.
+            const toolbox = await toolboxIndexFor(client, dirname(configPath));
             // The mirror's health rides along with identity because a dead mirror
             // is otherwise invisible: it only ever wrote one line to stderr, which
             // nobody reads, so "the dashboard terminal is stale" could only be
@@ -262,12 +348,20 @@ export function buildServer(options = {}) {
                 ...identity,
                 connection: getConnectionStatus(),
                 mirror: getMirrorStatus(),
+                ...(toolbox ? { toolbox } : {}),
             });
             // #615/#616: the JSON escapes every newline, so long markdown is
-            // unreadable there. Show it again as plain text when there is any.
-            const readable = renderInstructions(identity);
+            // unreadable there. Show it again as plain text when there is any —
+            // #605's scope notice rides in the same block, because both change what
+            // the agent should DO next.
+            const readable = [renderInstructions(identity), renderScopeNotice(identity)]
+                .filter((part) => !!part)
+                .join("\n\n");
             if (readable)
                 result.content.push({ type: "text", text: readable });
+            const toolboxText = renderToolboxIndex(toolbox);
+            if (toolboxText)
+                result.content.push({ type: "text", text: toolboxText });
             return result;
         }
         catch (err) {
@@ -365,6 +459,79 @@ export function buildServer(options = {}) {
             return fail(err);
         }
     });
+    // ---- agent management (#605) ---------------------------------------------
+    // These three need `agents:manage` on YOUR key. Without it the server answers
+    // 403 and the human must mint a scoped key from the dashboard's Connect-agents
+    // page — so the error text says exactly that instead of leaving a bare 403.
+    server.tool("create_agent", "Mint another agent in this project and return its key ONCE — use it to set up a worker without asking your human to link it. Requires the agents:manage scope on YOUR OWN key; the key you mint never carries a scope (only a human owner/admin can grant one).", {
+        display_name: z.string().min(1).describe("How the new agent appears in chat, on tasks and in activity."),
+        agent_profile: z
+            .string()
+            .min(1)
+            .describe("Its profile name inside .taskflow.json (lowercase letters, digits, - or _; e.g. reviewer)."),
+        instructions_markdown: z
+            .string()
+            .optional()
+            .describe("Its role instructions, applied at creation. It reads them through whoami."),
+        project_root: z.string().optional().describe("The repo the new agent will run in (absolute path)."),
+        runtime: z.string().optional().describe("Its runtime, e.g. claude-code."),
+        version: z.string().optional().describe("Its runtime version."),
+        ...profileArg,
+    }, async ({ display_name, agent_profile, instructions_markdown, project_root, runtime, version, profile }) => {
+        try {
+            const picked = await clientFor(profile);
+            if (!picked.ok)
+                return picked.refusal;
+            const { client } = picked;
+            const minted = await client.createAgent({
+                display_name,
+                profile: agent_profile,
+                ...(instructions_markdown !== undefined ? { instructions_markdown } : {}),
+                ...(project_root !== undefined ? { project_root } : {}),
+                ...(runtime !== undefined ? { runtime } : {}),
+                ...(version !== undefined ? { version } : {}),
+            });
+            return ok({
+                ...minted,
+                next: "The key is shown once — save it in the new agent's .taskflow.json now. It is an ordinary key: it cannot mint agents.",
+            });
+        }
+        catch (err) {
+            return failAgentsManage(err);
+        }
+    });
+    server.tool("set_agent_instructions", "Replace another agent's role instructions in this project (it picks them up on its next whoami, no new key, no restart). Requires the agents:manage scope on your key. Pass null to clear them.", {
+        agent: z.number().int().describe("The agent's id (from list_agents)."),
+        markdown: z.string().nullable().describe("The markdown role instructions, or null to clear them."),
+        ...profileArg,
+    }, async ({ agent, markdown, profile }) => {
+        try {
+            const picked = await clientFor(profile);
+            if (!picked.ok)
+                return picked.refusal;
+            const { client } = picked;
+            return ok(await client.setPeerInstructions(agent, markdown));
+        }
+        catch (err) {
+            return failAgentsManage(err);
+        }
+    });
+    server.tool("delete_agent", "Revoke another agent in this project: its keys, sessions and rosters go with it, so its key stops working at once; what it said (messages, reviews, task authorship) stays under its name. Requires the agents:manage scope, and an agent can never delete itself — ask your human for that.", {
+        agent: z.number().int().describe("The agent's id (from list_agents)."),
+        ...profileArg,
+    }, async ({ agent, profile }) => {
+        try {
+            const picked = await clientFor(profile);
+            if (!picked.ok)
+                return picked.refusal;
+            const { client } = picked;
+            await client.deletePeer(agent);
+            return ok({ deleted: agent });
+        }
+        catch (err) {
+            return failAgentsManage(err);
+        }
+    });
     // ---- tasks ----
     server.tool("create_task", "Create a task in the agent's project. Optionally self-claim it. Returns the created task.", {
         title: z.string().min(1).describe("Short task title."),
@@ -375,12 +542,16 @@ export function buildServer(options = {}) {
             .describe("Task priority (default: normal)."),
         notes: z.string().optional().describe("Markdown notes."),
         claim: z.boolean().optional().describe("If true, assign the new task to this agent."),
+        repo: z
+            .string()
+            .optional()
+            .describe("Which of the project's linked GitHub repos this task belongs to (owner/name). Omit for the project's default. Publish uses this repo, and an issue number is only meaningful with it."),
         files: z
             .array(z.string())
             .optional()
             .describe("Paths to attach to the new task, relative to the project root (or absolute, inside it). Max 25MB each."),
         ...profileArg,
-    }, async ({ title, description, notes, priority, claim, files, profile }) => {
+    }, async ({ title, description, notes, priority, claim, files, repo, profile }) => {
         try {
             const picked = await clientFor(profile);
             if (!picked.ok)
@@ -392,6 +563,7 @@ export function buildServer(options = {}) {
                 notes_markdown: notes,
                 priority,
                 claim,
+                repo,
             }));
             if (!files?.length)
                 return ok(task);
@@ -438,8 +610,13 @@ export function buildServer(options = {}) {
             .array(z.string())
             .optional()
             .describe("Paths to attach to this task, relative to the project root (or absolute, inside it). Max 25MB each. Attaching is additive — it never removes existing attachments."),
+        repo: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Move the task to one of the project's linked GitHub repos (owner/name), or pass null to put it back on the project default. Omit to leave it as it is."),
         ...profileArg,
-    }, async ({ task, title, description, notes, priority, files, profile }) => {
+    }, async ({ task, title, description, notes, priority, files, repo, profile }) => {
         try {
             const picked = await clientFor(profile);
             if (!picked.ok)
@@ -450,9 +627,10 @@ export function buildServer(options = {}) {
             const hasFields = title !== undefined ||
                 description !== undefined ||
                 notes !== undefined ||
-                priority !== undefined;
+                priority !== undefined ||
+                repo !== undefined;
             if (!hasFields && !files?.length) {
-                return fail(new Error("Nothing to update: pass at least one of title, description, notes, priority or files."));
+                return fail(new Error("Nothing to update: pass at least one of title, description, notes, priority, repo or files."));
             }
             let updated = undefined;
             if (hasFields) {
@@ -461,6 +639,7 @@ export function buildServer(options = {}) {
                     description_markdown: description,
                     notes_markdown: notes,
                     priority,
+                    repo,
                 });
             }
             if (!files?.length)
@@ -568,8 +747,37 @@ export function buildServer(options = {}) {
             .boolean()
             .optional()
             .describe("Ignored for placement — the destination channel decides where a message lands; kept only for compatibility. Design has its own room (one per project: the channel with is_design true in list_channels), so post design replies there."),
+        questions: z
+            .object({
+            title: z.string().optional().describe("Heading for the whole form."),
+            questions: z
+                .array(z.object({
+                key: z
+                    .string()
+                    .describe("Stable id for the answer, unique in this set (letters, digits, - _ :), max 40."),
+                label: z.string().describe("The question as the person reads it."),
+                type: z.enum(["radio", "select", "text", "date"]),
+                options: z
+                    .array(z.object({
+                    value: z.string().describe("What comes back as the answer."),
+                    label: z.string(),
+                    description: z.string().optional().describe("A supporting line under the option."),
+                }))
+                    .optional()
+                    .describe("radio/select: at least 2 required."),
+                allow_other: z.boolean().optional().describe("radio/select: offer an 'Other…' text input."),
+                required: z.boolean().optional().describe("The person cannot submit until it is answered."),
+                placeholder: z.string().optional().describe("text/date only."),
+                multiline: z.boolean().optional().describe("text only: a taller box for prose answers."),
+            }))
+                .describe("1-8 questions."),
+            submit_label: z.string().optional(),
+            cancel_label: z.string().optional(),
+        })
+            .optional()
+            .describe("A structured question set rendered as a form in the chat — prefer this over asking several things in prose: the person gets radio cards, a select, text and date inputs, and you get ONE readable reply. The answers arrive as a REPLY to this message, one bullet per question in the form `- <label> (<key>): <answer>`; a person who declines sends a reply starting with `Cancelled the question:`. Do not re-send a set that already has a reply."),
         ...profileArg,
-    }, async ({ channel, body, reply_to, priority, files, is_design, profile }) => {
+    }, async ({ channel, body, reply_to, priority, files, is_design, questions, profile }) => {
         try {
             const picked = await clientFor(profile);
             if (!picked.ok)
@@ -584,6 +792,7 @@ export function buildServer(options = {}) {
                 priority,
                 is_design,
                 attachments,
+                questions,
                 ...(reply_to === undefined ? {} : { reply_to }),
             }));
         }
@@ -899,6 +1108,111 @@ export function buildServer(options = {}) {
             return fail(err);
         }
     });
+    server.tool("design_rename_route", "Move a page's ROUTE — `/ai-coach` becomes `/pulse` — with every reference following it: the page file, links to it inside other pages (rewritten through the same validator, one recorded write each), the flow order, group memberships, the page's label, both ends of every arrow, and its pinned Flow position. The old page goes to the TRASH (restore it from the Pages panel if the rename was wrong); nothing else is deleted, and the response names what changed — including any page that could not be rewritten because someone edited it concurrently. This is not a label change: for the NAME the Pages panel shows, use design_arrange's set_label instead, which touches no route and no link.", {
+        from: z.string().min(1).describe("The route as it is now, e.g. '/ai-coach'."),
+        to: z.string().min(1).describe("The route it should become, e.g. '/pulse'. Must not already serve a page."),
+        ...designProjectArg,
+        ...profileArg,
+    }, async ({ from, to, project, profile }) => {
+        try {
+            const picked = await clientFor(profile);
+            if (!picked.ok)
+                return picked.refusal;
+            const { client } = picked;
+            return ok(await client.designRenameRoute(await resolveDesignProject(client, project), from, to));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("design_list_versions", "Every recorded version of ONE design file, newest first — #520's history. `path` is a file path (`pages/index.html`, `components/app-header.js`, `styles/tokens.json`). Each entry carries `version` (the file version to pass to design_read_version / design_restore_version), `project_revision` (its place in the project timeline), `bytes`, `updated_by`, and `deleted` (a trash is recorded too). Content is NOT included: read the version you want. Use this before assuming an old design is gone — a page's last 20 versions are kept, along with the tokens and components they rendered with.", {
+        path: z.string().min(1).describe("File path, e.g. 'pages/index.html'."),
+        ...designProjectArg,
+        ...profileArg,
+    }, async ({ path, project, profile }) => {
+        try {
+            const picked = await clientFor(profile);
+            if (!picked.ok)
+                return picked.refusal;
+            const { client } = picked;
+            return ok(await client.designVersions(await resolveDesignProject(client, project), path));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("design_read_version", "One recorded version's content, with `preview_revision` — the project revision to render it at, so the version can be SEEN with the tokens and components of its time (the sandbox takes `?rev=<preview_revision>`, and design_read_page/design_write_page work on the LIVE file). Reach for this when the owner says \"bring back how the pricing page looked last week\": list the versions, read the one they mean, then design_restore_version it.", {
+        path: z.string().min(1).describe("File path, e.g. 'pages/index.html'."),
+        version: z.number().int().describe("The file version from design_list_versions."),
+        ...designProjectArg,
+        ...profileArg,
+    }, async ({ path, version, project, profile }) => {
+        try {
+            const picked = await clientFor(profile);
+            if (!picked.ok)
+                return picked.refusal;
+            const { client } = picked;
+            return ok(await client.designVersion(await resolveDesignProject(client, project), path, version));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("design_restore_version", "Bring an old version back (#520). This is a NEW WRITE, not a rewind: the old content is written as a new version through the normal validator, so the history stays complete and the restore can itself be undone by restoring the version it replaced. Read the version first (design_read_version) when it matters what is in it — the restore does not ask. Answers with the new version and a `restored_from`.", {
+        path: z.string().min(1).describe("File path, e.g. 'pages/index.html'."),
+        version: z.number().int().describe("The file version to bring back."),
+        ...designProjectArg,
+        ...profileArg,
+    }, async ({ path, version, project, profile }) => {
+        try {
+            const picked = await clientFor(profile);
+            if (!picked.ok)
+                return picked.refusal;
+            const { client } = picked;
+            return ok(await client.designRestoreVersion(await resolveDesignProject(client, project), path, version));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("design_search", "Find what the design SAYS, without reading every page: one call answers \"which pages mention this term, and where\". USE THIS FIRST for any rename, audit or copy review (e.g. renaming \"AI coach\" to \"Pulse\"): search, then design_read_page / design_write_page ONLY the pages it returns. Never read every page to find a term. " +
+        "Searches stored design files server-side, not raw HTML: `text` (default scope) matches visible text runs; `attributes` matches the accessibility attributes a rename must not miss (alt, title, aria-label, placeholder, value); `code` matches class names, ids, data-* and scripts and is OFF unless you ask for it, so \"coach\" inside class=\"coach-card\" is not reported as copy; `page_names` matches page titles and Pages-panel labels; `groups` and `flow_labels` match the arrangement. Components are searched whole and reported ONCE with `used_by_routes` — one edit to a component fixes every route that uses it, so do not treat those routes as separate edits. " +
+        "Matching is whole-word by default (`whole_word: false` to match inside words, e.g. \"coach\" inside \"coaching\") and case-insensitive (`case_sensitive: true` to pin it). `regex: true` treats the query as a Rust regex. " +
+        "The answer is `total` (matches across the whole project), `variants` (each surface form with its count — a rename that ignores a variant leaves it behind), `files` (kind, route/name, file, version, count, and per-hit `what` + `line` + a `snippet` with the hit wrapped in <<>>), `labels` (matches that live in the arrangement, not in a file), and `next_cursor` when more files remain: pass it back as `cursor`. Each file's `version` is what a write's `base_version` takes.", {
+        query: z.string().min(1).describe("The term to find, e.g. 'AI coach'."),
+        regex: z.boolean().optional().describe("Treat the query as a Rust regex (default false)."),
+        case_sensitive: z.boolean().optional().describe("Default false: matching ignores case."),
+        whole_word: z.boolean().optional().describe("Default TRUE: 'coach' does not match 'coaching'. Pass false for substring matching."),
+        scope: z
+            .string()
+            .optional()
+            .describe("Comma-separated: text (default), attributes, code, page_names, groups, flow_labels."),
+        in: z.enum(["pages", "components", "both"]).optional().describe("Where to search (default both)."),
+        cursor: z.string().optional().describe("next_cursor from the previous call; files after it are returned."),
+        limit: z.number().int().min(1).max(100).optional().describe("Files per page (default 25, max 100)."),
+        ...designProjectArg,
+        ...profileArg,
+    }, async ({ query, regex, case_sensitive, whole_word, scope, in: where, cursor, limit, project, profile }) => {
+        try {
+            const picked = await clientFor(profile);
+            if (!picked.ok)
+                return picked.refusal;
+            const { client } = picked;
+            return ok(await client.designSearch(await resolveDesignProject(client, project), {
+                query,
+                regex,
+                caseSensitive: case_sensitive,
+                wholeWord: whole_word,
+                scope,
+                in: where,
+                cursor,
+                limit,
+            }));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
     server.tool("design_read_layout", "Read how the project's PAGES ARE ARRANGED: the named page groups and what each one holds, the flow (the order the pages are presented in and the canvas draws in), and the name each page is listed under. design_list_components returns the registry as a FLAT array with no group and no order, so the arrangement cannot be recovered from it — if you need to know how pages are grouped, or in which order they come, ask THIS. Nothing to select: the arrangement is one document per project, so there is no route, group id or name to pass. `view` is the canvas arrangement (rows/bands/groups/flow — `flow` is the user-flow canvas) and the grouping reads the same in every one. `version` is THIS arrangement's version — hand it to a layout write as `base_version` to be told if someone rearranged the board under you. (Note `revision` next to it is a different number: the manifest's, which moves when a page changes.) It also returns the USER FLOW drawn as arrows on the Flow canvas: `edges` is a list of `{id, from, to, label?}` — a user goes from route `from` to route `to`, and the optional label names the path (\"new user\" / \"existing user\") — and `positions` maps a route to its fixed `{x, y}` node on that canvas (an unlisted page is auto-placed). Arrange the board with design_create_group, design_update_group, design_reorder_group, design_reorder_page and design_delete_group; draw the flow with design_link_pages and design_unlink_pages — or several edits at once with design_arrange (which also takes update_link and place_page) — all of which take operations — never PUT a document built from this response back, because this is the panel's view and not the stored form.", 
     // The arrangement is one document per project, so there is nothing to
     // select: a route or a group id would be an argument this read has no use
@@ -1131,6 +1445,24 @@ export function buildServer(options = {}) {
     // tools make, in the route's own wire shape (plus #508's update_link and
     // place_page, which exist only here).
     const coord = z.number().finite();
+    /** #525: the text a delivered render contributes — where it went, and the
+     *  reminder that the pixels are NOT in this reply. */
+    const deliveredNote = (delivered) => {
+        if (!delivered || typeof delivered !== "object")
+            return "";
+        const record = delivered;
+        if (record.to === "message") {
+            const count = Array.isArray(record.attachments) ? record.attachments.length : 0;
+            return `\n\nDELIVERED to channel ${record.channel} as message ${record.message_id} (${count} attachment(s)). The image is NOT in this reply — the human has it; do not re-send it.`;
+        }
+        if (record.to === "url") {
+            const urls = Array.isArray(record.images)
+                ? record.images.map((image) => image.url).filter(Boolean).join(", ")
+                : "";
+            return `\n\nDELIVERED as file(s): ${urls}. The image is NOT in this reply.`;
+        }
+        return "";
+    };
     const layoutOpSchema = z.union([
         z.object({ create_group: z.object({ name: z.string() }).strict() }).strict(),
         z.object({ update_group: z.object({ group_id: z.string(), name: z.string() }).strict() }).strict(),
@@ -1176,7 +1508,7 @@ export function buildServer(options = {}) {
             .object({ place_page: z.object({ route: z.string().min(1), x: coord, y: coord }).strict() })
             .strict(),
     ]);
-    server.tool("design_arrange", "Apply SEVERAL arrangement edits as ONE write: `ops` is an ordered list, each item exactly one of {\"create_group\":{name}}, {\"update_group\":{group_id,name}}, {\"reorder_group\":{group_id,position}}, {\"reorder_page\":{route,group_id?,position?}}, {\"delete_group\":{group_id}}, and for the USER FLOW on the Flow canvas (arrows showing how a user moves between screens): {\"link_pages\":{from,to,label?}}, {\"unlink_pages\":{edge_id} or {from,to}}, {\"update_link\":{edge_id,label?}} (relabel an arrow; omit label to clear it), {\"place_page\":{route,x,y}} (pin a page's node at canvas coordinates, clamped to ±100000; this is NOT reorder_page, which moves a page in the list) — the same rules as the single tools of those names. Use it to file many pages into groups, reorder a whole section, or lay out a whole flow (link the screens and place each node) in one call. Link ids are minted by the server and reported in `changed.edges`; placed routes in `changed.positions`. The ops run in order, each on the result of the one before, and the batch is ALL OR NOTHING: if any op is refused, none is stored and the error names the failing index (`ops[2] (reorder_page) ...`). The whole batch is one version. A group created in the batch gets its id minted by the server, so a later op in the SAME batch cannot name it — create first, then arrange with the id from `changed.groups`. 1 to 100 ops; a one-item list behaves exactly like the single tool. " +
+    server.tool("design_arrange", "Apply SEVERAL arrangement edits as ONE write: `ops` is an ordered list, each item exactly one of {\"create_group\":{name}}, {\"update_group\":{group_id,name}}, {\"reorder_group\":{group_id,position}}, {\"reorder_page\":{route,group_id?,position?}}, {\"delete_group\":{group_id}}, and for the USER FLOW on the Flow canvas (arrows showing how a user moves between screens): {\"link_pages\":{from,to,label?}}, {\"unlink_pages\":{edge_id} or {from,to}}, {\"update_link\":{edge_id,label?}} (relabel an arrow; omit label to clear it), {\"place_page\":{route,x,y}} (pin a page's node at canvas coordinates, clamped to ±100000; this is NOT reorder_page, which moves a page in the list), and {\"set_label\":{route,label}} (name a page for the Pages panel; omit label (or send an empty string) to clear it back to the page's own title — bulk renaming a set of pages is a batch of these) — the same rules as the single tools of those names. Use it to file many pages into groups, reorder a whole section, or lay out a whole flow (link the screens and place each node) in one call. Link ids are minted by the server and reported in `changed.edges`; placed routes in `changed.positions`. The ops run in order, each on the result of the one before, and the batch is ALL OR NOTHING: if any op is refused, none is stored and the error names the failing index (`ops[2] (reorder_page) ...`). The whole batch is one version. A group created in the batch gets its id minted by the server, so a later op in the SAME batch cannot name it — create first, then arrange with the id from `changed.groups`. 1 to 100 ops; a one-item list behaves exactly like the single tool. " +
         baseVersionNote, {
         ...designProjectArg,
         ops: z.array(layoutOpSchema).min(1).max(100).describe("The edits, applied in order as one all-or-nothing write."),
@@ -1303,7 +1635,7 @@ export function buildServer(options = {}) {
             return fail(err);
         }
     });
-    server.tool("design_write_asset", "Write one file that is NOT a page, a component or the token scale. Two shapes: `assets/<name>` — an image file (`.svg`, `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.ico`; a bare name like 'logo.svg' means assets/logo.svg) — or `styles/resources.json`, the external-resources document naming the project's web fonts and external script links, which design_write_tokens does NOT write. THIS is where a webfont is loaded: its enabled sets go into the head of EVERY page, so a typeface is one token (typography.font-sans) plus this one file — never a <link> per page. Shape: {\"version\":1,\"sets\":[{\"id\":\"font\",\"name\":\"Font\",\"enabled\":true,\"links\":[{\"rel\":\"preconnect\",\"href\":\"https://cdn.jsdelivr.net\",\"crossorigin\":true},{\"rel\":\"stylesheet\",\"href\":\"https://cdn.jsdelivr.net/npm/@fontsource-variable/inter@5/index.css\"}]}]} (https only; rel stylesheet/preconnect/dns-prefetch). design_get_tokens returns the current document and its version in `resources`. The operator often manages its sets from the panel: when it exists, change only what you need (usually `enabled` flags) and keep every other set as is. Content is TEXT, exactly like every other design write: an SVG goes in as its own markup, and raster bytes as `data:<image/png>;base64,<payload>`, which the server decodes when the file is served. An asset is served from the sandbox origin at `/s/{token}/f/assets/<name>` with its own content type — but nothing rewrites an `src=` into a sandbox URL the way links are rewritten, so a page cannot point at it by a relative path: for an image a page shows today use an https URL or a data: URI inside the fragment. Caps unchanged: 128 KB per file (rule `size-cap`), and a NEW file must also fit the project's 200-file / 4 MB budget. Pass base_version only when replacing an existing file.", {
+    server.tool("design_write_asset", "Write one file that is NOT a page, a component or the token scale. Two shapes: `assets/<name>` — an image file (`.svg`, `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.ico`; a bare name like 'logo.svg' means assets/logo.svg) — or `styles/resources.json`, the external-resources document naming the project's web fonts and external script links, which design_write_tokens does NOT write. THIS is where a webfont is loaded: its enabled sets go into the head of EVERY page, so a typeface is one token (typography.font-sans) plus this one file — never a <link> per page. Shape: {\"version\":1,\"sets\":[{\"id\":\"font\",\"name\":\"Font\",\"enabled\":true,\"links\":[{\"rel\":\"preconnect\",\"href\":\"https://cdn.jsdelivr.net\",\"crossorigin\":true},{\"rel\":\"stylesheet\",\"href\":\"https://cdn.jsdelivr.net/npm/@fontsource-variable/inter@5/index.css\"}]}]} (https only; rel stylesheet/preconnect/dns-prefetch). design_get_tokens returns the current document and its version in `resources`. The operator often manages its sets from the panel: when it exists, change only what you need (usually `enabled` flags) and keep every other set as is. Content is TEXT, exactly like every other design write: an SVG goes in as its own markup, and raster bytes as `data:<image/png>;base64,<payload>`, which the server decodes when the file is served. An asset is served from the sandbox origin at `/s/{token}/f/assets/<name>` with its own content type — but nothing rewrites an `src=` into a sandbox URL the way links are rewritten, so a page cannot point at it by a relative path: for an image a page shows today use an https URL or a data: URI inside the fragment. Caps unchanged: 128 KB per file (rule `size-cap`), and a NEW file must also fit the project's 500-file / 16 MB budget. Pass base_version only when replacing an existing file.", {
         path: z.string().min(1).describe("'logo.svg' (bare name → assets/logo.svg), 'assets/logo.svg', or 'styles/resources.json'."),
         content: z.string().describe("File text. Raster images as a data:<mime>;base64,<payload> string."),
         base_version: z.number().int().optional().describe("Version from a prior read; omit to force a replacement."),
@@ -1364,6 +1696,17 @@ export function buildServer(options = {}) {
             return fail(err);
         }
     });
+    const deliverArg = z
+        .object({
+        to: z
+            .enum(["inline", "message", "url"])
+            .describe("'inline' (default, the image comes to you) | 'message' (post it to a channel) | 'url' (store it, get the URL)."),
+        channel: z.number().int().optional().describe("Required by 'message': the channel id to post in (see list_channels)."),
+        body: z.string().optional().describe("The message text when delivering to a channel."),
+        reply_to: z.number().int().optional().describe("Post as a reply to this message id, in the same channel."),
+    })
+        .optional()
+        .describe("Send the render to a PERSON instead of into your context (#525): use it whenever the human asked to see the design, and the picture costs you no tokens. The same rules as send_message apply (you must be able to post in that channel). `max_px`/`scale` still control the delivered file — pass max_px 0 for full resolution.");
     server.tool("design_screenshot", "Render a route in headless Chromium and return a PNG. You cannot see the UI otherwise — call this on a route BEFORE and AFTER your edits and self-critique the result. " +
         "Phone/tablet viewports render as a real mobile browser (touch, mobile user agent). " +
         "Size: a preset `viewport`, or a custom `width`+`height` (CSS px, 200–4000) with optional `dpr` (1–4). " +
@@ -1398,9 +1741,10 @@ export function buildServer(options = {}) {
             .optional()
             .describe("Longest side of the returned image (default 1568, what you can read; 0 = full resolution, e.g. to hand to a human)."),
         state: z.string().optional().describe("Overlay state to open on load, e.g. 'dialog:confirm-delete'."),
+        deliver: deliverArg,
         ...designProjectArg,
         ...profileArg,
-    }, async ({ route, viewport, width, height, dpr, mobile, full_page, frame, theme, tokens, css, max_px, state, project, profile }) => {
+    }, async ({ route, viewport, width, height, dpr, mobile, full_page, frame, theme, tokens, css, max_px, state, deliver, project, profile }) => {
         try {
             const picked = await clientFor(profile);
             if (!picked.ok)
@@ -1418,6 +1762,16 @@ export function buildServer(options = {}) {
                 tokens,
                 css,
                 max_px,
+                // Flattened: the route is a GET, so `deliver` travels as four query
+                // parameters rather than one nested object.
+                ...(deliver
+                    ? {
+                        deliver: deliver.to,
+                        ...(deliver.channel === undefined ? {} : { deliver_channel: deliver.channel }),
+                        ...(deliver.body === undefined ? {} : { deliver_body: deliver.body }),
+                        ...(deliver.reply_to === undefined ? {} : { deliver_reply_to: deliver.reply_to }),
+                    }
+                    : {}),
             });
             // `all` may be partial: an entry with an error and no picture becomes a
             // text line, not an image.
@@ -1428,7 +1782,9 @@ export function buildServer(options = {}) {
                     : [];
             const images = entries.filter((e) => !!e.png_base64);
             const failed = entries.filter((e) => !e.png_base64);
-            if (!images.length) {
+            // #525: a delivered render has no image BY DESIGN; that is not a failed
+            // render, and it must not throw.
+            if (!images.length && !shot.delivered) {
                 throw new Error(failed.length
                     ? `No theme could be rendered. ${failed.map((f) => `${f.theme}: ${f.error ?? "no image"}`).join("; ")}`
                     : "Renderer returned no image.");
@@ -1452,11 +1808,14 @@ export function buildServer(options = {}) {
                 : "";
             return {
                 content: [
-                    ...images.map((image) => ({ type: "image", data: image.png_base64, mimeType: "image/png" })),
+                    ...images
+                        .filter((image) => image.png_base64)
+                        .map((image) => ({ type: "image", data: image.png_base64, mimeType: "image/png" })),
                     {
                         type: "text",
                         text: `Screenshot of ${shot.route} at ${shot.viewport}${size}${shade}${shot.full_page ? ", full page" : ""}${dress}. ` +
-                            `Self-critique it against the tokens scale and your instruction before calling it done.${warnings}${failures}`,
+                            `Self-critique it against the tokens scale and your instruction before calling it done.${warnings}${failures}` +
+                            deliveredNote(shot.delivered),
                     },
                 ],
             };
@@ -1507,9 +1866,10 @@ export function buildServer(options = {}) {
         css: z.string().optional().describe("CSS every variant gets (before its own)."),
         include_apply: z.boolean().optional().describe("Return apply[label].patch per variant (default false)."),
         max_px: z.number().int().min(0).max(8000).optional().describe("Longest side of each image (default 1568; 0 = full size)."),
+        deliver: deliverArg,
         ...designProjectArg,
         ...profileArg,
-    }, async ({ routes, variants, themes, viewport, width, height, checks, scale, tokens, css, include_apply, max_px, project, profile }) => {
+    }, async ({ routes, variants, themes, viewport, width, height, checks, scale, tokens, css, include_apply, max_px, deliver, project, profile }) => {
         try {
             const picked = await clientFor(profile);
             if (!picked.ok)
@@ -1529,8 +1889,17 @@ export function buildServer(options = {}) {
                 css,
                 include_apply,
                 max_px,
+                ...(deliver
+                    ? {
+                        deliver: deliver.to,
+                        ...(deliver.channel === undefined ? {} : { deliver_channel: deliver.channel }),
+                        ...(deliver.body === undefined ? {} : { deliver_body: deliver.body }),
+                        ...(deliver.reply_to === undefined ? {} : { deliver_reply_to: deliver.reply_to }),
+                    }
+                    : {}),
             });
-            if (!out.images?.length)
+            // #525: a delivered grid has no images BY DESIGN.
+            if (!out.images?.length && !out.delivered)
                 throw new Error("Renderer returned no image.");
             const lines = [
                 `Compare grid: columns ${out.grid.columns.join(" | ")}; rows ${out.grid.rows.map((r) => `${r.label ?? r.route} (${r.theme})`).join(", ")}.`,
@@ -1553,9 +1922,16 @@ export function buildServer(options = {}) {
             if (out.warnings.length) {
                 lines.push("", "WARNINGS — the picture differs from a real browser here:", ...out.warnings.map((w) => `- ${w}`));
             }
+            const delivered = deliveredNote(out.delivered);
+            if (delivered)
+                lines.push(delivered);
             return {
                 content: [
-                    ...out.images.map((image) => ({ type: "image", data: image.png_base64, mimeType: "image/png" })),
+                    // #525: a delivered render carries no base64 — never an image
+                    // block with `undefined` data.
+                    ...out.images
+                        .filter((image) => image.png_base64)
+                        .map((image) => ({ type: "image", data: image.png_base64, mimeType: "image/png" })),
                     { type: "text", text: lines.join("\n") },
                 ],
             };
@@ -1605,6 +1981,221 @@ export function buildServer(options = {}) {
             return fail(err);
         }
     });
+    // ---- #617: the project toolbox -------------------------------------------
+    //
+    // Progressive disclosure, enforced and not merely described: `toolbox_list`
+    // returns names and descriptions and NEVER code, `toolbox_get` is the only
+    // way code reaches the context, and installing is gated on having seen the
+    // exact version this session (by fetching it, diffing to it, or writing it).
+    // name -> versions this session has SEEN. Process-local, so a reconnect
+    // starts clean and cannot install on an earlier session's reading.
+    const toolboxSeen = new Map();
+    const markSeen = (name, version) => {
+        const set = toolboxSeen.get(name) ?? new Set();
+        set.add(version);
+        toolboxSeen.set(name, set);
+    };
+    server.tool("toolbox_list", "What this project's toolbox already knows: memories (project facts, gotchas) and scripts other agents built, tested and saved. Titles, descriptions, tags, status, version and run stats ONLY — no code, no bodies. Call this BEFORE building tooling for a project: the report script you are about to reinvent probably already exists.", {
+        kind: z.enum(["memory", "script"]).optional().describe("Filter to one kind."),
+        tag: z.string().optional().describe("Only entries carrying this tag."),
+        query: z.string().optional().describe("Free text over name, title and description."),
+        ...profileArg,
+    }, async ({ kind, tag, query, profile }) => {
+        try {
+            const picked = await clientFor(profile);
+            if (!picked.ok)
+                return picked.refusal;
+            return ok(await picked.client.toolboxList({ kind, tag, query }));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("toolbox_get", "Read ONE toolbox entry in full: a memory's text, or a script's code with its params, requires_env and usage notes. The ONLY tool that puts an entry's code in front of you — use it when you need the entry, never to browse. For a script, read the code before running it; then toolbox_install to put it where you can run it.", {
+        name: z.string().min(1).describe("Entry name from toolbox_list or the connect-time index."),
+        ...profileArg,
+    }, async ({ name, profile }) => {
+        try {
+            const picked = await clientFor(profile);
+            if (!picked.ok)
+                return picked.refusal;
+            const entry = (await picked.client.toolboxGet(name));
+            if (entry?.name && typeof entry.version === "number")
+                markSeen(entry.name, entry.version);
+            return ok(entry);
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("toolbox_save", "Save a memory or a SCRIPT into the project toolbox, so every agent on the project — including on your colleagues' machines — starts from what you learned. A memory for a non-obvious project fact or gotcha; a script once you have RUN it and it works, not before. NEVER put credentials, tokens or private keys in the code: they are refused outright, and the right shape is requires_env plus reading the values at run time. Hosts, emails and IPs are REPLACED on save and reported back — parameterise them instead. Updating an existing entry needs `base_version` (from toolbox_get); a stale one is a 409.", {
+        name: z
+            .string()
+            .min(1)
+            .describe("Unique slug for this project: lowercase letters, digits, `-`, `_`. The handle everything else uses."),
+        kind: z.enum(["memory", "script"]).describe("memory = prose an agent reads; script = code an agent runs locally."),
+        title: z.string().min(1).describe("Human title."),
+        description: z
+            .string()
+            .min(1)
+            .describe("ONE line, and it must say WHEN to use the entry — this is what the index shows, so it is the retrieval signal."),
+        body_markdown: z.string().optional().describe("The memory itself, or a script's usage notes."),
+        code: z.string().optional().describe("Scripts only: the full source."),
+        language: z.string().optional().describe("Scripts only: bash, python, node, …"),
+        entrypoint: z.string().optional().describe("Scripts only: the file to run (defaults from the name and language)."),
+        params: z
+            .array(z.object({ name: z.string(), description: z.string().optional(), required: z.boolean().optional() }))
+            .optional()
+            .describe("Scripts only: the arguments a caller passes."),
+        requires_env: z
+            .array(z.string())
+            .optional()
+            .describe("Scripts only: environment VARIABLE NAMES the script reads. Never values."),
+        tags: z.array(z.string()).optional(),
+        base_version: z.number().int().optional().describe("Required to update an existing entry: the version you are editing."),
+        note: z.string().optional().describe("Why this version replaces the last — what a diff reader wants."),
+        dry_run: z.boolean().optional().describe("Check the redaction report without saving, so you can fix the source first."),
+        ...profileArg,
+    }, async (input) => {
+        try {
+            const picked = await clientFor(input.profile);
+            if (!picked.ok)
+                return picked.refusal;
+            const { name, profile: _profile, ...fields } = input;
+            const saved = (await picked.client.toolboxSave(name, fields));
+            if (!input.dry_run && saved?.entry?.name && typeof saved.entry.version === "number") {
+                // The author has necessarily read what it wrote, so this version is
+                // installable without a separate get.
+                markSeen(saved.entry.name, saved.entry.version);
+            }
+            return ok(saved);
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("toolbox_report_run", "Say how a toolbox script's run went, after you ran it. This is the feedback loop that makes a broken script visible as broken (and a fixed one as fixed) to the whole project — call it every time you run one.", {
+        name: z.string().min(1),
+        ok: z.boolean().describe("Did it do its job?"),
+        note: z.string().optional().describe("What happened, briefly — especially when ok is false."),
+        ...profileArg,
+    }, async ({ name, ok: ranOk, note, profile }) => {
+        try {
+            const picked = await clientFor(profile);
+            if (!picked.ok)
+                return picked.refusal;
+            return ok(await picked.client.toolboxReportRun(name, ranOk, note));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("toolbox_deprecate", "Retire a toolbox entry with a reason: a script a newer one replaces, a memory that stopped being true. Prefer this to leaving wrong knowledge in place — the reason is what the next agent reads.", {
+        name: z.string().min(1),
+        reason: z.string().min(1).describe("Why it should no longer be used."),
+        ...profileArg,
+    }, async ({ name, reason, profile }) => {
+        try {
+            const picked = await clientFor(profile);
+            if (!picked.ok)
+                return picked.refusal;
+            return ok(await picked.client.toolboxDeprecate(name, reason));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("toolbox_diff", "Show ONLY what changed between two versions of a script, so re-vetting an update is quick reading instead of re-reading everything. Use it when the connect-time index says an installed script has a newer version.", {
+        name: z.string().min(1),
+        from: z.number().int().describe("The version you vetted (the index's 'installed vX')."),
+        to: z.number().int().describe("The newer version."),
+        ...profileArg,
+    }, async ({ name, from, to, profile }) => {
+        try {
+            const picked = await clientFor(profile);
+            if (!picked.ok)
+                return picked.refusal;
+            const [before, after] = await Promise.all([
+                picked.client.toolboxGetVersion(name, from),
+                picked.client.toolboxGetVersion(name, to),
+            ]);
+            const beforeCode = before.code ?? "";
+            const afterCode = after.code ?? "";
+            markSeen(name, to);
+            return ok({
+                name,
+                from,
+                to,
+                identical: beforeCode === afterCode,
+                diff: diffLines(beforeCode, afterCode),
+                before,
+                after,
+            });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("toolbox_install", "Install a REVIEWED script into .taskflow/scripts/<name>/ in this checkout, so it runs directly from now on with no fetching and no re-reading. Requires `vetted_note`: your own sentence about what you checked ('read-only SSH, runs df and journalctl, prints to stdout, no deletes'). You must have seen THIS version already — via toolbox_get, toolbox_diff, or writing it yourself — because installing code nobody read is exactly what the gate prevents. The checkout keeps running its installed version; a newer server version is reported at connect but is NOT installed until you review the diff and install again.", {
+        name: z.string().min(1),
+        version: z.number().int().optional().describe("Defaults to the current version."),
+        vetted_note: z.string().min(4).describe("What you checked in the code before installing it."),
+        ...profileArg,
+    }, async ({ name, version, vetted_note, profile }) => {
+        try {
+            const picked = await clientFor(profile);
+            if (!picked.ok)
+                return picked.refusal;
+            const entry = (await picked.client.toolboxGet(name));
+            if (entry?.kind !== "script") {
+                return fail(new Error(`'${name}' is not a script — there is nothing to install. Read it with toolbox_get instead.`));
+            }
+            const target = version ?? entry.version;
+            if (!toolboxSeen.get(name)?.has(target)) {
+                return fail(new Error(`Read '${name}' v${target} first: toolbox_get, or toolbox_diff from the version you vetted. Installing a script you have not read is what the vetting gate prevents.`));
+            }
+            const source = target === entry.version
+                ? entry
+                : (await picked.client.toolboxGetVersion(name, target));
+            const agentLabel = await agentLabelFor(picked.client);
+            const install = await installScript({
+                projectRoot: dirname(configPath),
+                entry: { ...source, name, version: target },
+                vettedBy: agentLabel,
+                vettedNote: vetted_note,
+            });
+            // Record the vetting server-side so teammates can see who checked what.
+            // Best-effort: a failed record must not undo an install already on disk.
+            const vetted = await picked.client
+                .toolboxVet(name, target, agentLabel, vetted_note)
+                .then(() => true)
+                .catch(() => false);
+            return ok({
+                ...install,
+                vetted_recorded: vetted,
+                note: `Installed. Run it as ${install.run_command}, then call toolbox_report_run with how it went.${install.missing_env.length
+                    ? ` This machine is missing ${install.missing_env.join(", ")} — ask your human to set them (values never go through TaskFlow).`
+                    : ""}`,
+            });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.tool("toolbox_uninstall", "Remove an installed script from this checkout — its folder and its manifest row. The server copy is untouched; this only cleans the local scripts directory.", {
+        name: z.string().min(1),
+        ...profileArg,
+    }, async ({ name, profile }) => {
+        try {
+            const picked = await clientFor(profile);
+            if (!picked.ok)
+                return picked.refusal;
+            return ok(await uninstallScript({ projectRoot: dirname(configPath), name }));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
     return server;
 }
 //# sourceMappingURL=server.js.map