@rubytech/create-realagent-code 0.1.30 → 0.1.32

package/payload/platform/plugins/admin/mcp/dist/index.js

@@ -8,9 +8,8 @@ import { readFile, writeFile } from "node:fs/promises";
 import { resolve, join } from "node:path";
 import { execFileSync } from "node:child_process";
 import { appendFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { writeKey, validateKey, hasKey, keyFilePath, deleteKey } from "../../../../lib/anthropic-key/dist/index.js";
+import { writeKey, validateKey, keyFilePath } from "../../../../lib/anthropic-key/dist/index.js";
 import { writeAdminEntry, removeAdminFromAccount } from "../../../../lib/admins-write/dist/index.js";
-import { isPersistentComponent } from "../../../../lib/persistent-components/dist/index.js";
 import { deviceUrlBlock } from "../../../../lib/device-url/dist/index.js";
 import { substituteBrandPlaceholders } from "../../../../lib/brand-templating/dist/index.js";
 import { resolveEntitlement } from "../../../../lib/entitlement/dist/index.js";
@@ -19,7 +18,6 @@ import { createConnection } from "node:net";
 import { homedir, hostname as osHostname } from "node:os";
 import QRCode from "qrcode";
 import { getSession, closeDriver } from "./lib/neo4j.js";
-import { getOnboardingState, completeOnboardingStep } from "./lib/onboarding.js";
 import { findSkillOwners, computePluginReadHint, loadSkill, parseRequiredInputs } from "./skill-resolution.js";
 import { resolvePublicHostname } from "./lib/public-hostname.js";
 const server = new McpServer({
@@ -486,70 +484,6 @@ eagerTool(server, "brand-settings", "Read the brand/styling configuration (name,
         };
     }
 });
-/* ── Plugin selector options (deterministic) ────────────────────── */
-const PLUGIN_DISPLAY = {
-    admin: { value: "admin", label: "admin", description: "Platform management — system status, account settings, logs, session control." },
-    memory: { value: "memory", label: "memory", description: "Graph memory — search, write, reindex, and ingest knowledge." },
-    docs: { value: "docs", label: "maxy-guide", description: "User guide and platform documentation — loaded on demand." },
-    cloudflare: { value: "cloudflare", label: "cloudflare", description: "Cloudflare Tunnel — expose your assistant publicly via a custom domain." },
-    anthropic: { value: "anthropic", label: "anthropic", description: "Claude connection — API key acquisition and configuration." },
-    scheduling: { value: "scheduling", label: "scheduling", description: "Calendar and scheduling — events, appointments, recurring triggers." },
-    email: { value: "email", label: "email", description: "Agent email account — setup, read, send, search." },
-    contacts: { value: "contacts", label: "contacts", description: "CRM contact management — create, lookup, update, list." },
-    tasks: { value: "tasks", label: "tasks", description: "Graph-backed task lifecycle — create, update, list, relate, complete." },
-    workflows: { value: "workflows", label: "workflows", description: "Persistent named workflows — reusable instruction sets." },
-    projects: { value: "projects", label: "projects", description: "Structured project execution — phased sprints, investigations, reviews, retrospectives." },
-    "business-assistant": { value: "business-assistant", label: "business-assistant", description: "Customer enquiries, scheduling, quoting, invoicing, daily briefings. Enhances: personal-assistant" },
-    sales: { value: "sales", label: "sales", description: "Buying signal detection, closing techniques, objection handling. Enhances: personal-assistant" },
-    "deep-research": { value: "deep-research", label: "deep-research", description: "Structured multi-source research — query decomposition, source evaluation, citation formatting. Enhances: research-assistant" },
-    telegram: { value: "telegram", label: "telegram", description: "Telegram bot setup — BotFather, admin and public channels. Enhances: personal-assistant" },
-    whatsapp: { value: "whatsapp", label: "whatsapp", description: "WhatsApp messaging, pairing, and conversation browsing. Enhances: personal-assistant" },
-    waitlist: { value: "waitlist", label: "waitlist", description: "Waitlist lifecycle — extract sign-ups, review, schedule automation." },
-    replicate: { value: "replicate", label: "replicate", description: "Image generation — photorealistic, design, and fast draft images via Replicate. Enhances: content-producer, research-assistant" },
-};
-server.tool("onboarding-plugin-options", "Return the fully-assembled multi-select options array for onboarding Step 1. Classification (core/recommended/available) is derived from brand.json — the agent renders the result directly via render-component without further transformation.", {}, async () => {
-    try {
-        const brandPath = resolve(PLATFORM_ROOT, "config", "brand.json");
-        if (!existsSync(brandPath)) {
-            return { content: [{ type: "text", text: "No brand.json found at " + brandPath + " — platform not properly installed." }], isError: true };
-        }
-        const brand = JSON.parse(readFileSync(brandPath, "utf-8"));
-        const plugins = brand?.plugins;
-        if (!plugins)
-            return { content: [{ type: "text", text: "brand.json has no plugins configuration." }], isError: true };
-        const coreSet = new Set(plugins.core ?? []);
-        const defaultSet = new Set(plugins.defaultEnabled ?? []);
-        const availableSet = new Set(plugins.available ?? []);
-        const options = [];
-        for (const name of plugins.core ?? []) {
-            const meta = PLUGIN_DISPLAY[name] ?? { value: name, label: name, description: "" };
-            options.push({ ...meta, badge: "Core", group: "Core — always active", locked: true, defaultSelected: true });
-        }
-        for (const name of plugins.defaultEnabled ?? []) {
-            if (coreSet.has(name))
-                continue;
-            const meta = PLUGIN_DISPLAY[name] ?? { value: name, label: name, description: "" };
-            options.push({ ...meta, badge: "Recommended", group: "Maxy", defaultSelected: true });
-        }
-        for (const name of plugins.available ?? []) {
-            if (coreSet.has(name) || defaultSet.has(name))
-                continue;
-            const meta = PLUGIN_DISPLAY[name] ?? { value: name, label: name, description: "" };
-            options.push({ ...meta, group: "Maxy" });
-        }
-        // Task 976: signal that the onboarding skill will append three Anthropic
-        // vertical entries from the claude-for-financial-services and
-        // knowledge-work-plugins marketplaces. The count is fixed because the
-        // skill prose always appends the same three (kyc-screener,
-        // meeting-prep-agent, pdf-viewer). Absence of this line post-install
-        // = the group was not surfaced (release blocker per task spec).
-        console.error(`[plugin-onboarding] group=anthropic-verticals presented=3`);
-        return { content: [{ type: "text", text: JSON.stringify(options, null, 2) }] };
-    }
-    catch (err) {
-        return { content: [{ type: "text", text: `Failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
-    }
-});
 eagerTool(server, "account-manage", "Read the account configuration (tier, domains, settings).", {}, async () => {
     try {
         const config = await readAccountConfig();
@@ -1769,50 +1703,15 @@ eagerTool(server, "skill-load", "Load a plugin skill's SKILL.md body by skill na
         };
     }
 });
-// Task 940 — `"rendered"` is a sentinel, not a persistence ack. The platform
-// UI's stream-parser intercepts this tool_use upstream of the SDK reply
-// (platform/ui/app/lib/claude-agent/stream-parser.ts:362) and emits a typed
-// `component` event that admin-agent.ts's persistMessage flushes to Neo4j as
-// a sibling :Component node.
-//
-// Task 942 — render-component is also the *server commitment surface* for
-// PERSISTENT_COMPONENTS (action-list, document-editor, rich-content-editor,
-// grid-editor). The actual file write + :KnowledgeDocument projection lives
-// in the admin server process (stream-parser path) because the SDK delivers
-// `tool_use.input` to the UI in the assistant message but the MCP handler's
-// return reaches only the agent — there is no path back to persistMessage
-// from here. This handler emits a one-line observability marker per
-// persistence-eligible call so operators can grep for the commitment, and
-// returns richer JSON so the doctrine grep
-// `render-component.*"rendered"` resolves to a persistence-aware handler
-// rather than a bare stub.
-eagerTool(server, "render-component", "Render a pre-built UI component inline in the conversation. " +
-    "Call this instead of describing a UI — the component handles input collection. " +
-    "Wait for the user's response before continuing.", {
-    name: z.string().describe("Component name from the UI suite (e.g. single-select, confirm, info-card, form, progress)"),
-    data: z.record(z.string(), z.unknown()),
-}, async ({ name, data }) => {
-    if (isPersistentComponent(name)) {
-        // Persistence-eligible: log the commitment so the live + audit grep
-        // (`[render-component-persist]`) can correlate the MCP call against
-        // the downstream :KnowledgeDocument MERGE. Byte counts come from
-        // data.html (preferred) or data.content; both being absent is a
-        // legitimate render of an empty editor and the projection is skipped
-        // server-side.
-        const html = typeof data?.html === "string" ? data.html : "";
-        const content = typeof data?.content === "string" ? data.content : "";
-        const bytes = html.length > 0 ? html.length : content.length;
-        const mimeType = html.length > 0 ? "text/html" : (content.length > 0 ? "text/markdown" : "");
-        console.error(`[render-component-persist] componentName=${name} bytes=${bytes} mimeType=${mimeType || "none"}`);
-        return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify({ rendered: true, name, persistent: true, bytes, mimeType }),
-                }],
-        };
-    }
-    return { content: [{ type: "text", text: "rendered" }] };
-});
+// Task 066 — the inline UI-component tool is gone from the admin surface
+// on native Claude Code. The PTY runtime has no host bridge for the UI
+// primitives the legacy tool wrapped; calling it logged a "rendered"
+// sentinel that read like a successful render to the agent while the
+// chat surface saw nothing. Admin flows now use plain markdown for
+// reviewable artefacts (`skills/file-presentation/SKILL.md`) and
+// `file-attach` for downloadable artefacts. The :Component / :KnowledgeDocument
+// persistence pipeline is preserved for historical conversations that
+// already carry the rows; no new conversations write to it.
 eagerTool(server, "session-reset", "Reset the current session. Compacts conversation history to memory, clears the visible conversation, " +
     "and starts a fresh session with a new greeting. Call when the user asks to start a new session, " +
     "clear the conversation, or start fresh.", {}, async () => ({ content: [{ type: "text", text: "reset" }] }));
@@ -1887,473 +1786,6 @@ eagerTool(server, "api-key-verify", "Verify the stored Anthropic API key works b
     };
 });
 // ===================================================================
-// Anthropic setup — deterministic state machine
-// ===================================================================
-/*
- * anthropic-setup state machine (action-relay pattern)
- *
- * Call 1: anthropic-setup({})
- *   ├─ no public endpoint   → { status: "not_needed" }   ← Phase 0 gate
- *   ├─ key stored + valid?  → { status: "complete" }
- *   ├─ key stored + billing → { status: "awaiting_credits" }
- *   ├─ key stored + error   → { status: "error" }
- *   └─ no key               → { status: "awaiting_signin", action }
- *
- * Call 2: anthropic-setup({ consoleResult: "..." })
- *   ├─ no_session  → { status: "awaiting_signin", action }
- *   ├─ no_org      → { status: "error" }
- *   ├─ no_credits  → { status: "awaiting_credits", action }
- *   ├─ success     → writeKey → validateKey → { status: "complete" }
- *   └─ *_failed    → { status: "error" }
- */
-const CONSOLE_BASE = "https://platform.claude.com";
-/**
- * JavaScript expression for browser_evaluate that runs the complete
- * Console API pipeline in one call: check session → find API org →
- * check credits → create key. Returns a structured JSON result.
- */
-function consoleEvaluateExpression(keyName) {
-    return `async () => {
-  try {
-    const orgsRes = await fetch("/api/organizations", { credentials: "include" });
-    if (orgsRes.status === 401 || orgsRes.status === 403) {
-      return JSON.stringify({ status: "no_session" });
-    }
-    if (!orgsRes.ok) {
-      return JSON.stringify({ status: "fetch_error", error: "organizations: " + orgsRes.status });
-    }
-    const orgs = await orgsRes.json();
-    const apiOrg = orgs.find(o => o.capabilities && o.capabilities.includes("api"));
-    if (!apiOrg) {
-      return JSON.stringify({ status: "no_org" });
-    }
-    const creditsRes = await fetch("/api/organizations/" + apiOrg.uuid + "/prepaid/credits", { credentials: "include" });
-    if (!creditsRes.ok) {
-      return JSON.stringify({ status: "fetch_error", error: "credits: " + creditsRes.status });
-    }
-    const credits = await creditsRes.json();
-    if (typeof credits.amount === "number" && credits.amount <= 0) {
-      return JSON.stringify({ status: "no_credits", orgId: apiOrg.uuid, orgName: apiOrg.name, creditUrl: "${CONSOLE_BASE}/settings/billing" });
-    }
-    const createRes = await fetch("/api/console/organizations/" + apiOrg.uuid + "/workspaces/default/api_keys", {
-      method: "POST",
-      credentials: "include",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ name: ${JSON.stringify(keyName)} })
-    });
-    if (!createRes.ok) {
-      return JSON.stringify({ status: "create_failed", error: "key creation: " + createRes.status });
-    }
-    const keyData = await createRes.json();
-    if (!keyData.raw_key) {
-      return JSON.stringify({ status: "create_failed", error: "no raw_key in response" });
-    }
-    return JSON.stringify({
-      status: "success",
-      key: keyData.raw_key,
-      keyId: keyData.id,
-      keyHint: keyData.partial_key_hint,
-      orgName: apiOrg.name,
-      credits: credits.amount
-    });
-  } catch (err) {
-    return JSON.stringify({ status: "fetch_error", error: String(err) });
-  }
-}`;
-}
-function anthropicResult(r) {
-    return {
-        content: [{ type: "text", text: JSON.stringify(r, null, 2) }],
-        ...(r.status === "error" ? { isError: true } : {}),
-    };
-}
-/**
- * Check whether a public-facing hostname is configured. The Anthropic API key
- * powers the public agent only — admin runs on Claude OAuth — so without a
- * public endpoint there is nothing for the key to power.
- *
- * Mirrors the runtime `isPublicHost(host)` predicate in
- * `platform/ui/server/index.ts`: a host is public iff it starts with `public.`
- * OR is listed in `~/{configDir}/alias-domains.json`. Step 7's form submit
- * handler at `platform/ui/server/routes/admin/cloudflare.ts` writes secondary
- * hostnames (apex + custom public labels) to `alias-domains.json` and skips
- * `public.*` because the prefix itself is the signal — so the two predicates
- * together cover every shape the form can produce.
- *
- * Returns true if any configured hostname satisfies either predicate.
- */
-function hasPublicEndpointConfigured() {
-    const aliasPath = join(CONFIG_DIR, "alias-domains.json");
-    if (existsSync(aliasPath)) {
-        try {
-            const parsed = JSON.parse(readFileSync(aliasPath, "utf-8"));
-            if (Array.isArray(parsed)) {
-                const entries = parsed.filter((h) => typeof h === "string" && h.length > 0);
-                if (entries.length > 0) {
-                    return { has: true, reason: `alias-domains.json: ${entries.join(", ")}` };
-                }
-            }
-        }
-        catch {
-            // Malformed file — treat as empty; matches the server-side reader's tolerance.
-        }
-    }
-    const cfConfigPath = join(CONFIG_DIR, "cloudflared", "config.yml");
-    if (existsSync(cfConfigPath)) {
-        try {
-            const yaml = readFileSync(cfConfigPath, "utf-8");
-            const hostnames = [...yaml.matchAll(/^\s*-\s*hostname:\s*(\S+)/gm)].map((m) => m[1]);
-            const publicPrefixed = hostnames.find((h) => h.startsWith("public."));
-            if (publicPrefixed) {
-                return { has: true, reason: `cloudflared/config.yml ingress: ${publicPrefixed}` };
-            }
-        }
-        catch {
-            // Unreadable — treat as no public host.
-        }
-    }
-    return {
-        has: false,
-        reason: "no entries in alias-domains.json and no public.* hostname in cloudflared/config.yml",
-    };
-}
-eagerTool(server, "anthropic-setup", "Deterministic state machine for Anthropic API key acquisition. " +
-    "Checks current state, advances as far as possible, and returns a structured JSON result. " +
-    "On first call (no consoleResult): first verifies a public-facing endpoint is configured " +
-    "(the key only powers the public agent); if not, returns status 'not_needed'. Otherwise " +
-    "checks if a valid key is already stored. If not, returns status 'awaiting_signin' with " +
-    "a browser_evaluate action — the agent must open the browser to platform.claude.com, run " +
-    "the action's function via browser_evaluate, and pass the string result back as " +
-    "consoleResult on the next call. " +
-    "On second call (with consoleResult): parses the Console API result, stores the key, " +
-    "verifies it, and returns status 'complete'. " +
-    "Statuses: complete (key stored and verified), not_needed (no public endpoint configured — " +
-    "skip the step), awaiting_signin (user must sign in to Console), awaiting_credits (signed in " +
-    "but no credits — user must add credits), error (fatal — relay message).", {
-    consoleResult: z.string().optional().describe("JSON string result from running the browser_evaluate action returned by a prior call. " +
-        "Omit on the first call."),
-}, async ({ consoleResult }) => {
-    const log = (msg) => console.error(`[anthropic-setup] ${msg}`);
-    // ── Phase 0: gate on public endpoint existence ─────────────
-    // The API key only powers the public-facing agent. If no public hostname
-    // is configured (operator skipped step 7, or completed it without a
-    // public/apex hostname) the key has no consumer — short-circuit before
-    // any Console interaction so we never create keys the operator cannot use.
-    if (!consoleResult) {
-        const publicCheck = hasPublicEndpointConfigured();
-        if (!publicCheck.has) {
-            log(`gate: no public endpoint (${publicCheck.reason}) — returning not_needed`);
-            return anthropicResult({
-                status: "not_needed",
-                message: "No public-facing endpoint is configured, so an Anthropic API key is not needed. " +
-                    "The key powers the public agent only — admin runs on your Claude OAuth session. " +
-                    "When you set up a public hostname via Cloudflare (or apex domain), come back and " +
-                    "ask to set up the API key then.",
-            });
-        }
-        log(`gate: public endpoint present (${publicCheck.reason})`);
-    }
-    // ── Phase 1: check stored key ──────────────────────────────
-    if (!consoleResult) {
-        log("checking stored key");
-        if (hasKey()) {
-            const verification = await validateKey();
-            log(`stored key verification: ${verification.status}`);
-            switch (verification.status) {
-                case "valid":
-                    log("key valid, returning complete");
-                    return anthropicResult({
-                        status: "complete",
-                        message: `API key is stored and working. Key file: ${keyFilePath()}.`,
-                    });
-                case "billing":
-                    log("key valid but billing issue");
-                    return anthropicResult({
-                        status: "awaiting_credits",
-                        message: "API key is stored and valid, but your account has insufficient credits. " +
-                            `Add credits at ${CONSOLE_BASE}/settings/billing, then call this tool again.`,
-                        data: { url: `${CONSOLE_BASE}/settings/billing` },
-                    });
-                case "auth_error":
-                    // Deterministic transition: the state machine knows the key file
-                    // path and the only recovery is to delete and restart sign-in.
-                    // Auto-reset here so the agent never has to rediscover the path
-                    // via filesystem probes.
-                    log(`auth_error → auto-resetting: deleting revoked key at ${keyFilePath()}`);
-                    try {
-                        deleteKey();
-                    }
-                    catch (err) {
-                        const msg = err instanceof Error ? err.message : String(err);
-                        log(`auto-reset failed: ${msg}`);
-                        return anthropicResult({
-                            status: "error",
-                            message: `The stored API key was rejected and auto-reset failed: ${msg}. ` +
-                                `Manual intervention needed — remove ${keyFilePath()} and call this tool again.`,
-                        });
-                    }
-                    // Fall through to the awaiting_signin path below.
-                    break;
-                case "missing":
-                    // hasKey() returned true but readKey() returned null — shouldn't happen
-                    log("hasKey true but validate returned missing — proceeding to setup");
-                    break;
-                case "error":
-                    log(`verification failed: ${verification.message}`);
-                    return anthropicResult({
-                        status: "error",
-                        message: `Could not verify the stored key: ${verification.message}. ` +
-                            "This may be a network issue or Anthropic outage. Try again later.",
-                    });
-            }
-        }
-        else {
-            log("no key stored");
-        }
-        // No valid key — return action for Console API calls
-        const expression = consoleEvaluateExpression(BRAND_NAME);
-        log("returning awaiting_signin with browser_evaluate action");
-        return anthropicResult({
-            status: "awaiting_signin",
-            message: "No valid API key stored. Open the browser to the Anthropic Console " +
-                `(${CONSOLE_BASE}) and sign in. This is a separate service from Claude — ` +
-                "you may need to sign in again even if you used the same credentials earlier. " +
-                "Once signed in, run the browser_evaluate action below, then call this tool " +
-                "again with the result as consoleResult.",
-            data: {
-                url: CONSOLE_BASE,
-                action: {
-                    tool: "browser_evaluate",
-                    params: { function: expression },
-                },
-            },
-        });
-    }
-    // ── Phase 2: process Console API result ────────────────────
-    log("processing consoleResult");
-    let parsed;
-    try {
-        parsed = JSON.parse(consoleResult);
-    }
-    catch {
-        log(`consoleResult parse failed: ${consoleResult.slice(0, 200)}`);
-        return anthropicResult({
-            status: "error",
-            message: "Failed to parse the browser result. The Console session may have " +
-                "been lost or the browser encountered an error. Please try again — " +
-                "open the browser to platform.claude.com, sign in, and re-run the action.",
-        });
-    }
-    log(`console result status: ${parsed.status}`);
-    switch (parsed.status) {
-        case "no_session": {
-            log("no Console session — user needs to sign in");
-            const expression = consoleEvaluateExpression(BRAND_NAME);
-            return anthropicResult({
-                status: "awaiting_signin",
-                message: "Not signed in to the Anthropic Console. Please sign in at " +
-                    `${CONSOLE_BASE} and then run the browser_evaluate action below.`,
-                data: {
-                    url: CONSOLE_BASE,
-                    action: {
-                        tool: "browser_evaluate",
-                        params: { function: expression },
-                    },
-                },
-            });
-        }
-        case "no_org":
-            log("no API organization found");
-            return anthropicResult({
-                status: "error",
-                message: "No API organization found in your Anthropic account. " +
-                    "You may be signed in to a Claude consumer account instead of the API Console. " +
-                    `Sign in at ${CONSOLE_BASE} with an account that has API access.`,
-            });
-        case "no_credits": {
-            log(`no credits — org: ${parsed.orgName ?? "unknown"}`);
-            const expression = consoleEvaluateExpression(BRAND_NAME);
-            return anthropicResult({
-                status: "awaiting_credits",
-                message: `Your API organization (${parsed.orgName ?? "unknown"}) has no credits. ` +
-                    `Add credits at ${parsed.creditUrl ?? CONSOLE_BASE + "/settings/billing"}, ` +
-                    "then run the browser_evaluate action below.",
-                data: {
-                    url: parsed.creditUrl ?? `${CONSOLE_BASE}/settings/billing`,
-                    action: {
-                        tool: "browser_evaluate",
-                        params: { function: expression },
-                    },
-                },
-            });
-        }
-        case "create_failed":
-            log(`key creation failed: ${parsed.error ?? "unknown"}`);
-            return anthropicResult({
-                status: "error",
-                message: `Failed to create API key: ${parsed.error ?? "unknown error"}. ` +
-                    "This may be a permissions issue or a temporary Console error. Try again.",
-            });
-        case "fetch_error":
-            log(`fetch error: ${parsed.error ?? "unknown"}`);
-            return anthropicResult({
-                status: "error",
-                message: `Console API error: ${parsed.error ?? "unknown"}. ` +
-                    "The Console may be temporarily unavailable. Try again.",
-            });
-        case "success": {
-            if (!parsed.key) {
-                log("success status but no key in result");
-                return anthropicResult({
-                    status: "error",
-                    message: "Key creation succeeded but the key was not returned. " +
-                        "This is unexpected. Please try again.",
-                });
-            }
-            log(`key created: ${parsed.keyId ?? "unknown"} (hint: ${parsed.keyHint ?? "n/a"}) — org: ${parsed.orgName ?? "unknown"}`);
-            // Store the key — persist AFTER confirmation (sprint learning: Task 201)
-            try {
-                writeKey(parsed.key);
-                log("key stored");
-            }
-            catch (err) {
-                log(`key storage failed: ${err instanceof Error ? err.message : String(err)}`);
-                return anthropicResult({
-                    status: "error",
-                    message: `Key was created in the Console but could not be stored locally: ` +
-                        `${err instanceof Error ? err.message : String(err)}`,
-                });
-            }
-            // Verify the stored key
-            const verification = await validateKey();
-            log(`post-store verification: ${verification.status}`);
-            switch (verification.status) {
-                case "valid":
-                    log("key stored and verified");
-                    return anthropicResult({
-                        status: "complete",
-                        message: `API key created, stored at ${keyFilePath()}, and verified. ` +
-                            `Organization: ${parsed.orgName ?? "unknown"}. ` +
-                            `Credits: $${((parsed.credits ?? 0) / 100).toFixed(2)}.`,
-                    });
-                case "billing":
-                    log("key stored but billing issue on verification");
-                    return anthropicResult({
-                        status: "awaiting_credits",
-                        message: "API key created and stored, but your account has insufficient credits. " +
-                            `Add credits at ${CONSOLE_BASE}/settings/billing, then verify the key with api-key-verify.`,
-                        data: { url: `${CONSOLE_BASE}/settings/billing` },
-                    });
-                default:
-                    log(`unexpected verification status after store: ${verification.status} — ${verification.message}`);
-                    return anthropicResult({
-                        status: "error",
-                        message: `Key was stored but verification returned: ${verification.status}. ` +
-                            `${verification.message}. Try running api-key-verify manually.`,
-                    });
-            }
-        }
-        default:
-            log(`unknown console result status: ${parsed.status}`);
-            return anthropicResult({
-                status: "error",
-                message: `Unexpected result from Console: status "${parsed.status}". ` +
-                    "Please try again.",
-            });
-    }
-});
-// ===================================================================
-// Onboarding tools
-// ===================================================================
-server.tool("onboarding-get", "Read the current onboarding state from the graph. Returns which setup steps " +
-    "have been completed and their timestamps. On first call for an account, " +
-    "migrates any existing onboardingStep from account.json to the graph and " +
-    "removes it from the file. If Neo4j is unreachable, returns an error — " +
-    "the agent should skip onboarding for this session and retry next time.", {}, async () => {
-    try {
-        const state = await getOnboardingState(getSession, ACCOUNT_ID, getAccountDir());
-        return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify(state, null, 2),
-                }],
-        };
-    }
-    catch (err) {
-        return {
-            content: [{
-                    type: "text",
-                    text: `Failed to read onboarding state: ${err instanceof Error ? err.message : String(err)}`,
-                }],
-            isError: true,
-        };
-    }
-});
-server.tool("onboarding-complete-step", "Mark an onboarding step as completed. Sets a completion timestamp on the step " +
-    "and updates currentStep to the highest completed step. Idempotent — completing " +
-    "an already-completed step preserves its original timestamp. Step must be 1–9. " +
-    "When step is 1, optionally pass acceptedAnthropicVerticals + declinedAnthropicVerticals " +
-    "(both required together) to emit the paired counter for the [plugin-onboarding] " +
-    "group=anthropic-verticals prefix; the skill derives both arrays from the closed set " +
-    "{kyc-screener, meeting-prep-agent, pdf-viewer} and the user's submission.", {
-    step: z.number().int().min(1).max(9).describe("The onboarding step number (1–9) to mark as completed"),
-    acceptedAnthropicVerticals: z.array(z.string()).optional().describe("Step 1 only: plugin slugs the user accepted from the Anthropic verticals group. Pass together with declinedAnthropicVerticals."),
-    declinedAnthropicVerticals: z.array(z.string()).optional().describe("Step 1 only: plugin slugs the user declined from the Anthropic verticals group. Pass together with acceptedAnthropicVerticals."),
-}, async ({ step, acceptedAnthropicVerticals, declinedAnthropicVerticals }) => {
-    try {
-        const state = await completeOnboardingStep(getSession, ACCOUNT_ID, step);
-        // Task 977: closed set lives in skill prose, not server validation — a fourth vertical updates the skill.
-        if (step === 1 && acceptedAnthropicVerticals !== undefined && declinedAnthropicVerticals !== undefined) {
-            console.error(`[plugin-onboarding] group=anthropic-verticals accepted=${acceptedAnthropicVerticals.length} declined=${declinedAnthropicVerticals.length}`);
-        }
-        return {
-            content: [{
-                    type: "text",
-                    text: JSON.stringify(state, null, 2),
-                }],
-        };
-    }
-    catch (err) {
-        return {
-            content: [{
-                    type: "text",
-                    text: `Failed to complete onboarding step: ${err instanceof Error ? err.message : String(err)}`,
-                }],
-            isError: true,
-        };
-    }
-});
-// Task 704: pin the operator's persona (personal/business-owner) at step 9
-// BEFORE any graph write happens. The agent calls this immediately on the
-// user's single-select submission. The tool's job is twofold:
-//   1. Emit a deterministic [onboarding-step9-mode] log line for the
-//      diagnostic-grep path on the Pi (matches [onboarding-step-complete]
-//      format — same accountId-prefix slicing, same surrounding code).
-//   2. Return the next-action prose so the agent's branching is anchored to
-//      the tool surface, not free-text inference.
-// No persistence — the graph state (LocalBusiness exists vs Person with
-// role=admin-personal exists) remains the source of truth for gate
-// satisfaction. Re-calling this tool with a different mode on the same
-// session is allowed; the most recent log line wins for diagnostic purposes.
-server.tool("onboarding-step9-mode", "Step 9 onboarding fork: record the operator's persona (personal or " +
-    "business-owner) before any graph write. Logs the choice for diagnostic " +
-    "grep and returns the deterministic next-action prose for the agent.", {
-    mode: z
-        .enum(["personal", "business-owner"])
-        .describe("The operator's persona: 'personal' for an individual using Maxy for personal operations (including someone with an employer that is NOT being registered here), or 'business-owner' for someone setting up Maxy as the operations agent for their own company."),
-}, async ({ mode }) => {
-    console.log(`[onboarding-step9-mode] accountId=${ACCOUNT_ID.slice(0, 8)}… mode=${mode}`);
-    const nextAction = mode === "business-owner"
-        ? "Invoke the `business-profile` skill to create AdminUser + LocalBusiness and capture the business identity. Mark step 9 complete only after both nodes exist in the graph."
-        : "Ask the user for their email (one sentence). Use their name from `admin-identity` in the system prompt; split into givenName + familyName. Call `memory-write` to create the AdminUser node, then call `memory-write` to create a Person node with `role: \"admin-personal\"`, the givenName, familyName, email, and an OWNS edge from the AdminUser. Then call `onboarding-complete-step` with step 9. Do not invoke the `business-profile` skill — personal mode does not register a LocalBusiness.";
-    return {
-        content: [{
-                type: "text",
-                text: JSON.stringify({ mode, nextAction }, null, 2),
-            }],
-    };
-});
-// ===================================================================
 // Utility tools
 // ===================================================================
 eagerTool(server, "qr-generate", "Generate a QR code from text or a URL. Returns the QR code as a data URI (PNG) or saves to a file path.", {
@@ -2984,10 +2416,11 @@ server.tool("premium-deliver", "Deliver a purchased premium plugin. Copies plugi
 // file-attach — copy a generated file into the attachment store for download
 // ---------------------------------------------------------------------------
 eagerTool(server, "file-attach", "Attach a file from the account directory for delivery to the user. " +
-    "Copies the file into the attachment store and returns metadata for rendering " +
-    "a download component. The file must be within the account directory tree. " +
-    "After calling this tool, call render-component with name 'file-attachment' " +
-    "and pass the returned metadata as data.", {
+    "Copies the file into the attachment store and returns metadata the chat " +
+    "surface uses to present the download. The file must be within the account " +
+    "directory tree. The returned metadata is the operator-visible record of the " +
+    "attachment; quote it back to the user in plain text so they have the filename " +
+    "and size on screen.", {
     filePath: z.string().describe("Absolute path to the file to attach"),
 }, async ({ filePath }) => {
     const TAG = "[file-attach]";