@rubytech/create-maxy 1.0.881 → 1.0.884

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

@@ -1,6 +1,7 @@
 import { initStderrTee } from "../../../../lib/mcp-stderr-tee/dist/index.js";
 initStderrTee("admin");
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { eagerTool } from "../../../../lib/mcp-eager/dist/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { readFile, writeFile } from "node:fs/promises";
@@ -217,7 +218,7 @@ function checkPort(port, timeoutMs = 1000) {
         socket.once("timeout", () => { socket.destroy(); res(false); });
     });
 }
-server.tool("system-status", "Check health of all Maxy platform services: Neo4j, Ollama, Cloudflare tunnel, crontab (Maxy cron entries), VNC, Chrome (CDP), specialist agents, and deployed brand identity.", {}, async () => {
+eagerTool(server, "system-status", "Check health of all Maxy platform services: Neo4j, Ollama, Cloudflare tunnel, crontab (Maxy cron entries), VNC, Chrome (CDP), specialist agents, and deployed brand identity.", {}, async () => {
     const checks = {};
     try {
         // Task 580: NEO4J_URI must be explicit. The outer try/catch surfaces the
@@ -403,7 +404,7 @@ server.tool("system-status", "Check health of all Maxy platform services: Neo4j,
         .join("\n");
     return { content: [{ type: "text", text: formatted }] };
 });
-server.tool("public-hostname", "Resolve this account's canonical public hostname. Reads cloudflared ingress + alias-domains.json — the same files the platform server trusts to route. Returns a single deterministic answer; use this immediately after publish-site to construct the full URL.", {}, async () => {
+eagerTool(server, "public-hostname", "Resolve this account's canonical public hostname. Reads cloudflared ingress + alias-domains.json — the same files the platform server trusts to route. Returns a single deterministic answer; use this immediately after publish-site to construct the full URL.", {}, async () => {
     const TAG = "[admin:public-hostname]";
     try {
         const result = resolvePublicHostname(CONFIG_DIR);
@@ -433,7 +434,7 @@ server.tool("public-hostname", "Resolve this account's canonical public hostname
         };
     }
 });
-server.tool("remote-auth-status", "Check whether the remote access password is configured. When not configured, emits a device-bound URL affordance (maxy-device-url fenced block) pointing at the password setup page — this URL opens on the device's own screen when the operator clicks it. The agent never constructs the password file path or runs shell commands — this tool is the single authority.", {}, async () => {
+eagerTool(server, "remote-auth-status", "Check whether the remote access password is configured. When not configured, emits a device-bound URL affordance (maxy-device-url fenced block) pointing at the password setup page — this URL opens on the device's own screen when the operator clicks it. The agent never constructs the password file path or runs shell commands — this tool is the single authority.", {}, async () => {
     const TAG = "[remote-auth-status]";
     const platformPort = parseInt(PLATFORM_PORT, 10);
     const setupUrl = `http://${osHostname()}.local:${platformPort}/__remote-auth/setup`;
@@ -469,7 +470,7 @@ server.tool("remote-auth-status", "Check whether the remote access password is c
         };
     }
 });
-server.tool("brand-settings", "Read the brand/styling configuration (name, tagline, colours, fonts, plugin sets). Reads from config/brand.json (stamped by the bundler at install time).", {}, async () => {
+eagerTool(server, "brand-settings", "Read the brand/styling configuration (name, tagline, colours, fonts, plugin sets). Reads from config/brand.json (stamped by the bundler at install time).", {}, async () => {
     try {
         const brandPath = resolve(PLATFORM_ROOT, "config", "brand.json");
         if (!existsSync(brandPath)) {
@@ -549,7 +550,7 @@ server.tool("onboarding-plugin-options", "Return the fully-assembled multi-selec
         return { content: [{ type: "text", text: `Failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
     }
 });
-server.tool("account-manage", "Read the account configuration (tier, domains, settings).", {}, async () => {
+eagerTool(server, "account-manage", "Read the account configuration (tier, domains, settings).", {}, async () => {
     try {
         const config = await readAccountConfig();
         return {
@@ -563,7 +564,7 @@ server.tool("account-manage", "Read the account configuration (tier, domains, se
         };
     }
 });
-server.tool("account-update", "Update a user-configurable setting in account.json. Valid fields: outputStyle (default|explanatory), thinkingView (default|expanded|collapsed), effort (low|medium|high|max|auto), adminModel (any Anthropic model ID), publicModel (any Anthropic model ID), defaultAgent (slug of an existing public agent, or empty string to clear). Changes take effect on the next session.", {
+eagerTool(server, "account-update", "Update a user-configurable setting in account.json. Valid fields: outputStyle (default|explanatory), thinkingView (default|expanded|collapsed), effort (low|medium|high|max|auto), adminModel (any Anthropic model ID), publicModel (any Anthropic model ID), defaultAgent (slug of an existing public agent, or empty string to clear). Changes take effect on the next session.", {
     field: z.enum(["outputStyle", "thinkingView", "effort", "adminModel", "publicModel", "defaultAgent"]),
     value: z.string(),
 }, async ({ field, value }) => {
@@ -686,7 +687,7 @@ server.tool("plugin-toggle-enabled", "Enable or disable a plugin in this account
 // ===================================================================
 // Admin user management tools
 // ===================================================================
-server.tool("admin-add", "Add a new admin user to this account. Creates a device-level user entry (users.json) and adds them to this account's admins list (account.json). PIN must be at least 4 digits. If no PIN is provided, a unique 4-digit PIN is generated. Returns the userId and PIN to share with the new admin.\n\nIMPORTANT — retry behaviour: if the user already stated a specific PIN earlier in the conversation and a first admin-add call failed (e.g. tier cap reached, PIN collision), every retry MUST re-pass that PIN as the `pin` parameter. Omitting `pin` on the retry auto-generates a different 4-digit PIN, silently substituting what the user asked for.", {
+eagerTool(server, "admin-add", "Add a new admin user to this account. Creates a device-level user entry (users.json) and adds them to this account's admins list (account.json). PIN must be at least 4 digits. If no PIN is provided, a unique 4-digit PIN is generated. Returns the userId and PIN to share with the new admin.\n\nIMPORTANT — retry behaviour: if the user already stated a specific PIN earlier in the conversation and a first admin-add call failed (e.g. tier cap reached, PIN collision), every retry MUST re-pass that PIN as the `pin` parameter. Omitting `pin` on the retry auto-generates a different 4-digit PIN, silently substituting what the user asked for.", {
     name: z.string().describe("Display name for the new admin (stored on the AdminUser node in Neo4j)."),
     pin: z.string().optional().describe("Optional PIN (minimum 4 digits). If omitted, a unique 4-digit PIN is generated."),
 }, async ({ name, pin: rawPin }) => {
@@ -873,7 +874,7 @@ server.tool("admin-add", "Add a new admin user to this account. Creates a device
             }],
     };
 });
-server.tool("admin-remove", "Remove an admin from this account. Removes them from the account's admins list (account.json) and deletes the ADMIN_OF relationship in Neo4j. Does NOT remove the device-level user entry (they may admin other accounts). Cannot remove the last admin on the account.", {
+eagerTool(server, "admin-remove", "Remove an admin from this account. Removes them from the account's admins list (account.json) and deletes the ADMIN_OF relationship in Neo4j. Does NOT remove the device-level user entry (they may admin other accounts). Cannot remove the last admin on the account.", {
     userId: z.string().describe("The userId of the admin to remove (use admin-list to find userIds)"),
 }, async ({ userId }) => {
     const TAG = "[admin]";
@@ -949,7 +950,7 @@ server.tool("admin-remove", "Remove an admin from this account. Removes them fro
             }],
     };
 });
-server.tool("admin-list", "List all admins for this account with their names and roles.", {}, async () => {
+eagerTool(server, "admin-list", "List all admins for this account with their names and roles.", {}, async () => {
     const TAG = "[admin]";
     let admins;
     try {
@@ -991,7 +992,7 @@ server.tool("admin-list", "List all admins for this account with their names and
         content: [{ type: "text", text: `Admins for this account:\n\n${lines.join("\n")}` }],
     };
 });
-server.tool("admin-update-pin", "Update an existing admin user's PIN. Defaults to the calling admin if no userId is given. PIN must be at least 4 digits and unique across all users on the device. PINs are device-level: updating another admin's PIN does not require shared account membership — any admin on the device can rotate any other admin's PIN, matching the existing trust model used by admin-remove.", {
+eagerTool(server, "admin-update-pin", "Update an existing admin user's PIN. Defaults to the calling admin if no userId is given. PIN must be at least 4 digits and unique across all users on the device. PINs are device-level: updating another admin's PIN does not require shared account membership — any admin on the device can rotate any other admin's PIN, matching the existing trust model used by admin-remove.", {
     userId: z.string().optional().describe("The userId of the admin whose PIN to update. Defaults to the caller (the admin invoking this tool)."),
     newPin: z.string().describe("The new PIN. Minimum 4 digits, no upper bound."),
 }, async ({ userId: targetUserId, newPin }) => {
@@ -1254,7 +1255,7 @@ server.tool("agent-list", "List all public (non-admin) agents with their full co
         };
     }
 });
-server.tool("logs-read", "Read recent logs. Stream logs (type=agent-stream/error/session/public) are per-conversation — pass `conversationId` to retrieve a single conversation's log from first [spawn] to final [process-exit]. type=agent-stream: per-conversation tool-use/tool-result archive (every `[tool-use]` and `[tool-result]` pair with full input + output JSON, plus raw Claude stream-json, agent events, and MCP server stderr via tee). USE THIS when investigating what an agent ACTUALLY did with its tools — server.log only carries `[persist] tool-call persisted` markers, not bodies. (`type=system` is a backwards-compatible alias for the same archive.) type=session: SSE events sent to client. type=error: Claude subprocess stderr (raw — NODE_DEBUG HTTP/NET/UNDICI traces land in agent-stream via the stream tee, not here). type=heartbeat: platform event dispatcher (check-due-events cron). type=public: public agent diagnostic log. type=server: platform server log. type=mcp: MCP server stderr (per-plugin raw). type=vnc: VNC browser viewer lifecycle. sessionKey: grep legacy sessionKey-tagged lines across all logs (useful for pre-per-conversation artefacts). When conversationId is provided, reads the single per-conversation file for the requested type (or dumps all type files for that conversationId if type is omitted).", {
+eagerTool(server, "logs-read", "Read recent logs. Stream logs (type=agent-stream/error/session/public) are per-conversation — pass `conversationId` to retrieve a single conversation's log from first [spawn] to final [process-exit]. type=agent-stream: per-conversation tool-use/tool-result archive (every `[tool-use]` and `[tool-result]` pair with full input + output JSON, plus raw Claude stream-json, agent events, and MCP server stderr via tee). USE THIS when investigating what an agent ACTUALLY did with its tools — server.log only carries `[persist] tool-call persisted` markers, not bodies. (`type=system` is a backwards-compatible alias for the same archive.) type=session: SSE events sent to client. type=error: Claude subprocess stderr (raw — NODE_DEBUG HTTP/NET/UNDICI traces land in agent-stream via the stream tee, not here). type=heartbeat: platform event dispatcher (check-due-events cron). type=public: public agent diagnostic log. type=server: platform server log. type=mcp: MCP server stderr (per-plugin raw). type=vnc: VNC browser viewer lifecycle. sessionKey: grep legacy sessionKey-tagged lines across all logs (useful for pre-per-conversation artefacts). When conversationId is provided, reads the single per-conversation file for the requested type (or dumps all type files for that conversationId if type is omitted).", {
     type: z.enum(["agent-stream", "system", "session", "error", "heartbeat", "public", "server", "mcp", "vnc"]).optional(),
     lines: z.number().optional(),
     sessionKey: z.string().optional(),
@@ -1491,7 +1492,7 @@ server.tool("logs-read", "Read recent logs. Stream logs (type=agent-stream/error
 // autoDeliverUserPlugins. The agent supplies pluginName/skillName/body —
 // path is computed by this tool from ACCOUNT_ID. Symmetric write counterpart
 // to plugin-read (Task 916).
-server.tool("store-skill", "Save an operator-authored skill on disk as part of an admin-managed plugin. " +
+eagerTool(server, "store-skill", "Save an operator-authored skill on disk as part of an admin-managed plugin. " +
     "The skill becomes immediately discoverable by the admin agent (and the public agent if publicEmbed=true). " +
     "Path is computed internally from the active account; the agent supplies content + names only. " +
     "Re-running for the same skillName overwrites in place (drops orphan reference files).", {
@@ -1614,7 +1615,7 @@ ${body}
         return { content: [{ type: "text", text: `Failed to write skill: ${msg}` }], isError: true };
     }
 });
-server.tool("plugin-read", "Read a plugin definition (PLUGIN.md) or one of its reference files.", {
+eagerTool(server, "plugin-read", "Read a plugin definition (PLUGIN.md) or one of its reference files.", {
     pluginName: z.string().describe("Name of the plugin directory (e.g. 'sales', 'business-assistant')"),
     file: z.string().optional().describe("Specific file to read (e.g. 'references/pricing.md'). Defaults to PLUGIN.md."),
 }, async ({ pluginName, file }) => {
@@ -1622,12 +1623,14 @@ server.tool("plugin-read", "Read a plugin definition (PLUGIN.md) or one of its r
         const resolvedFile = file ?? "PLUGIN.md";
         const pluginPath = resolve(PLATFORM_ROOT, "plugins", pluginName, resolvedFile);
         if (!existsSync(pluginPath)) {
-            // Task 964 — when the agent guesses the wrong pluginName for a file
-            // path shaped like `skills/<n>/...`, surface the owning plugin so
-            // the next call is deterministic instead of falling through to Glob.
-            const owner = computePluginReadHint(PLATFORM_ROOT, pluginName, resolvedFile);
-            const hintText = owner ? ` Did you mean pluginName="${owner}"?` : "";
-            console.log(`[plugin-read] ${pluginName}/${resolvedFile} not-found hint=${owner ?? "none"}`);
+            // Task 964/1000 — when the agent's pluginName/file combination misses
+            // a skill that DOES live under `plugins/*/skills/<slug>/SKILL.md`,
+            // surface the corrected pluginName AND the canonical file path so
+            // the next call is deterministic. Both wrong-`file` and wrong-`pluginName`
+            // shapes feed through `computePluginReadHint`.
+            const hint = computePluginReadHint(PLATFORM_ROOT, pluginName, resolvedFile);
+            const hintText = hint ? ` Did you mean pluginName="${hint.pluginName}", file="${hint.file}"?` : "";
+            console.log(`[plugin-read] ${pluginName}/${resolvedFile} not-found hint=${hint ? hint.pluginName : "none"}`);
             return {
                 content: [{ type: "text", text: `Plugin file not found: ${pluginPath}.${hintText}` }],
                 isError: true,
@@ -1739,7 +1742,7 @@ server.tool("skill-find", "Find which plugin owns a skill by name. Walks plugins
 // returns richer JSON so the doctrine grep
 // `render-component.*"rendered"` resolves to a persistence-aware handler
 // rather than a bare stub.
-server.tool("render-component", "Render a pre-built UI component inline in the conversation. " +
+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)"),
@@ -1766,10 +1769,10 @@ server.tool("render-component", "Render a pre-built UI component inline in the c
     }
     return { content: [{ type: "text", text: "rendered" }] };
 });
-server.tool("session-reset", "Reset the current session. Compacts conversation history to memory, clears the visible conversation, " +
+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" }] }));
-server.tool("session-resume", "Resume a previous session. Loads the selected session's message history into the chat timeline " +
+eagerTool(server, "session-resume", "Resume a previous session. Loads the selected session's message history into the chat timeline " +
     "and routes new messages to that conversation. Call after the user selects a session from the " +
     "session-list results. Pass the conversationId from the selected session.", { conversationId: z.string().uuid().describe("The conversationId of the session to resume") }, async () => ({ content: [{ type: "text", text: "resumed" }] }));
 server.tool("remote-auth-set-password", "Set the remote access password. Hashes with scrypt and writes to the platform's brand-specific config directory with mode 0600. " +
@@ -1813,7 +1816,7 @@ server.tool("remote-auth-set-password", "Set the remote access password. Hashes
         };
     }
 });
-server.tool("api-key-store", "Validate and store an Anthropic API key. Key must start with sk-ant- and be at least 90 characters. " +
+eagerTool(server, "api-key-store", "Validate and store an Anthropic API key. Key must start with sk-ant- and be at least 90 characters. " +
     "Writes to the platform's brand-specific config directory. Takes effect immediately for the public agent.", { apiKey: z.string() }, async ({ apiKey }) => {
     try {
         writeKey(apiKey);
@@ -1826,7 +1829,7 @@ server.tool("api-key-store", "Validate and store an Anthropic API key. Key must
         };
     }
 });
-server.tool("api-key-verify", "Verify the stored Anthropic API key works by making a minimal probe call. " +
+eagerTool(server, "api-key-verify", "Verify the stored Anthropic API key works by making a minimal probe call. " +
     "Returns one of: valid (key works, credits available), billing (key valid but credit balance too low — " +
     "user must add credits at console.anthropic.com/settings/billing), auth_error (key rejected — invalid or revoked), " +
     "missing (no key file found), error (could not verify — network issue or Anthropic outage). " +
@@ -1970,7 +1973,7 @@ function hasPublicEndpointConfigured() {
         reason: "no entries in alias-domains.json and no public.* hostname in cloudflared/config.yml",
     };
 }
-server.tool("anthropic-setup", "Deterministic state machine for Anthropic API key acquisition. " +
+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 " +
@@ -2309,7 +2312,7 @@ server.tool("onboarding-step9-mode", "Step 9 onboarding fork: record the operato
 // ===================================================================
 // Utility tools
 // ===================================================================
-server.tool("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.", {
+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.", {
     data: z.string().describe("The text or URL to encode in the QR code"),
     outputPath: z
         .string()
@@ -2360,7 +2363,7 @@ server.tool("qr-generate", "Generate a QR code from text or a URL. Returns the Q
 // ===================================================================
 // WiFi management (Task 429)
 // ===================================================================
-server.tool("wifi", "Manage WiFi connections on this device. Actions: " +
+eagerTool(server, "wifi", "Manage WiFi connections on this device. Actions: " +
     "scan (list visible networks with signal strength and security), " +
     "connect (join a network by SSID and password — warn user first if signal is below 30%), " +
     "status (current WiFi connection details), " +
@@ -2936,7 +2939,7 @@ server.tool("premium-deliver", "Deliver a purchased premium plugin. Copies plugi
 // ---------------------------------------------------------------------------
 // file-attach — copy a generated file into the attachment store for download
 // ---------------------------------------------------------------------------
-server.tool("file-attach", "Attach a file from the account directory for delivery to the user. " +
+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' " +
@@ -3226,7 +3229,7 @@ async function dispatchApprovedAction(plugin, tool, args, timeoutMs = 30_000) {
         await client.close().catch(() => { });
     }
 }
-server.tool("action-pending", "List actions that are queued for human approval. Returns each pending action's ID, " +
+eagerTool(server, "action-pending", "List actions that are queued for human approval. Returns each pending action's ID, " +
     "tool name, input summary, and when it was queued. Use this to review what the agent " +
     "wanted to do before approving or rejecting.", {}, async () => {
     const actions = readPendingActions();
@@ -3243,7 +3246,7 @@ server.tool("action-pending", "List actions that are queued for human approval.
         content: [{ type: "text", text: `## Pending Actions (${actions.length})\n\n${lines.join("\n\n")}` }],
     };
 });
-server.tool("action-approve", "Approve a pending action and execute it immediately. The original tool call is " +
+eagerTool(server, "action-approve", "Approve a pending action and execute it immediately. The original tool call is " +
     "executed via the target plugin's MCP server. The result is returned and an audit " +
     "record is written to Neo4j with approvalState: approved.", {
     actionId: z.string().describe("The action ID to approve (from action-pending)"),
@@ -3313,7 +3316,7 @@ server.tool("action-approve", "Approve a pending action and execute it immediate
         };
     }
 });
-server.tool("action-reject", "Reject a pending action. The action is not executed. An audit record is written " +
+eagerTool(server, "action-reject", "Reject a pending action. The action is not executed. An audit record is written " +
     "to Neo4j with approvalState: rejected.", {
     actionId: z.string().describe("The action ID to reject (from action-pending)"),
     reason: z.string().optional().describe("Optional reason for rejection"),
@@ -3354,7 +3357,7 @@ server.tool("action-reject", "Reject a pending action. The action is not execute
         content: [{ type: "text", text: `Action rejected. ${action.toolName} will not be executed.${reasonSuffix}` }],
     };
 });
-server.tool("action-edit", "Edit a pending action's input and then execute the modified version. The original " +
+eagerTool(server, "action-edit", "Edit a pending action's input and then execute the modified version. The original " +
     "input is preserved in the audit trail. Use this when the admin wants to modify the " +
     "action (e.g., change the email subject) before approving.", {
     actionId: z.string().describe("The action ID to edit (from action-pending)"),
@@ -3442,7 +3445,7 @@ server.tool("action-edit", "Edit a pending action's input and then execute the m
 // so the returned score matches the on-disk state byte-for-byte. File-only
 // access keeps the answer authoritative even if the Hono server is down.
 // ---------------------------------------------------------------------------
-server.tool("adherence-read", "Read the attention-weighted adherence ledger for an agent in this account. Returns the ledger JSON (rules with counts, rolling_7d, samples, streaks) and the score. Reads the file on every call — the value is authoritative and matches `{accountDir}/agents/<agent>/adherence-ledger.json` on disk. Use to answer 'what is my adherence score' or to surface the top offenders. Defaults to the admin agent when no name is supplied.", {
+eagerTool(server, "adherence-read", "Read the attention-weighted adherence ledger for an agent in this account. Returns the ledger JSON (rules with counts, rolling_7d, samples, streaks) and the score. Reads the file on every call — the value is authoritative and matches `{accountDir}/agents/<agent>/adherence-ledger.json` on disk. Use to answer 'what is my adherence score' or to surface the top offenders. Defaults to the admin agent when no name is supplied.", {
     agent: z.string().optional().describe("Agent name to query. Defaults to 'admin'."),
 }, async ({ agent }) => {
     const TAG = "[adherence-read]";