@cloudgrid-io/mcp 0.8.2 → 0.10.0

package/src/tools.js

@@ -36,6 +36,12 @@ export const MCP_VERSION = (() => {
 })();
 
 const ANON_HTML_MAX_BYTES = 2_000_000;
+// Signed-in inline drops get a larger cap than the anonymous 2MB. Kept
+// conservative — it must stay ≤ the platform's single-artifact byte limit.
+// TODO(platform-confirm): confirm the server's single-artifact limit (the
+// folder-plug path uses PLUG_MAX_TOTAL_BYTES = 100MB, but the single-artifact
+// inline limit is not yet confirmed) and raise this to match.
+const AUTHED_HTML_MAX_BYTES = 25_000_000;
 const CONSOLE_URL = "https://console.cloudgrid.io/";
 
 // ── Widget resources (ChatGPT Apps SDK, web edition only) ────────────────────
@@ -80,6 +86,9 @@ Operating rules:
 6. If a signed-in publish fails with a server error, do not fall back to anonymous publishing (it burns the anonymous quota and downgrades ownership); surface the error, use the CLI fallback if offered, or ask the user.
 7. When signed in and the user has more than one grid, do not assume a target — the publish tools will ask; relay the choice to the user and pass the chosen grid.
 8. When a build/deploy fails unexpectedly, offer to report it to the CloudGrid team — only with the user's explicit consent (ask first). Send just the error + the failed request by default (call gridctl_report), and never send the whole conversation unless the user agrees (include_conversation). Respect privacy.
+9. To modify an existing drop when you don't already have its HTML in context, first call gridctl_source to fetch the current HTML, apply your change, then call gridctl_drop/gridctl_plug with target_entity_id (the drop's entity_id) to update the SAME URL in place. Do not ask the user to paste the HTML back.
+10. Publishing a heavy or local file: in the local edition use the path parameter so it is read from disk (no inline size limit); never base64-encode HTML and never pass a file path (or an @-prefixed path) as html. If a drop looks empty, use gridctl_source to check what was actually published, then re-plug with the real HTML/path and target_entity_id.
+11. Persistence check: if the user needs to SAVE data, share state across users/sessions, log in, or store submissions, that's a runtime app-with-data (Mongo-backed), NOT a static page — static templates keep state only in memory and lose it on refresh. Use the app-with-data workflow. This requires the LOCAL edition (Claude Desktop/Code or the CLI); on the hosted edition, tell the user persistence isn't available there and offer a static version.
 
 Deploy is edition-dependent: on the hosted MCP call the drop tool with the HTML; on local MCP / CLI write the file and run the plug tool. An HTML page deploys synchronously, so you get a URL right away.`;
 
@@ -116,6 +125,7 @@ function readEntryDir(dirUrl) {
   });
   const pick =
     files.find((n) => n === "index.html") ||
+    files.find((n) => n === "index.md") ||
     files.find((n) => n.endsWith(".html")) ||
     files.find((n) => n.endsWith(".md")) ||
     (files.length === 1 ? files[0] : null);
@@ -216,30 +226,30 @@ const MIN_CLI_VERSION = "0.12.0";
 // Verb map for the drift guard: each CLI-wrapping tool's top-level verb(s).
 // The drift-guard test imports this and asserts every verb exists in `cloudgrid --help`.
 export const CLI_TOOL_VERBS = {
-  cloudgrid_init:     ["init"],
-  // cloudgrid_plug is NOT here: gridctl_plug is now a direct-API tool
+  gridctl_init:     ["init"],
+  // gridctl_plug is NOT here: gridctl_plug is now a direct-API tool
   // (POST /api/v2/plug, spec v2 §3), not a CLI wrapper.
-  cloudgrid_logs:     ["logs"],
-  cloudgrid_share:    ["visibility"],
-  cloudgrid_feedback: ["feedback"],
-  cloudgrid_whoami:   ["whoami"],
-  cloudgrid_use:      ["use"],
-  cloudgrid_logout:   ["logout"],
-  cloudgrid_status:   ["status"],
-  cloudgrid_info:     ["info"],
-  cloudgrid_get:          ["get"],
-  cloudgrid_describe_grid: ["describe"],
-  cloudgrid_pickup:        ["pickup"],
-  cloudgrid_rename:   ["rename"],
-  cloudgrid_unplug:   ["unplug"],
-  cloudgrid_delete:   ["delete"],
-  cloudgrid_rollback: ["rollback"],
-  cloudgrid_versions: ["versions"],
-  cloudgrid_env:      ["env"],
-  cloudgrid_secrets:  ["secrets"],
-  cloudgrid_scaffold: ["scaffold"],
-  cloudgrid_doctor:   ["doctor"],
-  cloudgrid_open:     ["open"],
+  gridctl_logs:     ["logs"],
+  gridctl_share:    ["visibility"],
+  gridctl_feedback: ["feedback"],
+  gridctl_whoami:   ["whoami"],
+  gridctl_use:      ["use"],
+  gridctl_logout:   ["logout"],
+  gridctl_status:   ["status"],
+  gridctl_info:     ["info"],
+  gridctl_get:          ["get"],
+  gridctl_describe_grid: ["describe"],
+  gridctl_pickup:        ["pickup"],
+  gridctl_rename:   ["rename"],
+  gridctl_unplug:   ["unplug"],
+  gridctl_delete:   ["delete"],
+  gridctl_rollback: ["rollback"],
+  gridctl_versions: ["versions"],
+  gridctl_env:      ["env"],
+  gridctl_secrets:  ["secrets"],
+  gridctl_scaffold: ["scaffold"],
+  gridctl_doctor:   ["doctor"],
+  gridctl_open:     ["open"],
 };
 
 // Simple semver comparison: true when `version` >= MIN_CLI_VERSION.
@@ -781,6 +791,50 @@ function looksLikeFullHtml(s) {
   return head.startsWith("<!doctype html") || head.startsWith("<html");
 }
 
+// A real user (heavy persona-deck in Claude Desktop) hit an agent that worried
+// about inline size, base64-encoded the HTML, and passed the base64 blob as
+// `html` — which used to get wrapped in an HTML shell and published as a wall of
+// text (an empty-looking page). Rescue that case: if the candidate text is not
+// already full HTML but is a strict-base64 blob that DECODES to full HTML, use
+// the decoded HTML. Applied to both the inline `html` string and the bytes read
+// via `path` (a base64 `.txt` file). Returns the original text unchanged when it
+// isn't base64-of-HTML, so genuine snippets are untouched.
+function decodeIfBase64Html(text) {
+  if (typeof text !== "string" || looksLikeFullHtml(text)) {
+    return { html: text, wasBase64: false };
+  }
+  const stripped = text.replace(/\s+/g, "");
+  if (
+    stripped.length < 64 ||
+    stripped.length % 4 !== 0 ||
+    !/^[A-Za-z0-9+/]+={0,2}$/.test(stripped)
+  ) {
+    return { html: text, wasBase64: false };
+  }
+  let decoded;
+  try {
+    decoded = Buffer.from(stripped, "base64").toString("utf8");
+  } catch {
+    return { html: text, wasBase64: false };
+  }
+  if (looksLikeFullHtml(decoded)) {
+    return { html: decoded, wasBase64: true };
+  }
+  return { html: text, wasBase64: false };
+}
+
+// Heuristic: does the string look like a bare filesystem path (not HTML)? Used
+// to catch a model that passes a file path — or an invented `@/home/...`
+// shorthand — as `html`. Single line, no HTML tag, path-ish shape.
+function looksLikePath(s) {
+  if (typeof s !== "string") return false;
+  const t = s.trim();
+  if (t.length === 0 || t.length > 4096) return false;
+  if (/[\n\r]/.test(t)) return false;
+  if (/<[a-z!/]/i.test(t)) return false; // contains a tag → not a path
+  return /^(~|\.{0,2}\/|[A-Za-z]:[\\/]|\/)/.test(t) || /\.[A-Za-z0-9]{1,8}$/.test(t);
+}
+
 // Anonymous drops are owned by the platform Guest Org, whose slug is the apex
 // the public URL hangs off (https://guest.cloudgrid.io/<slug>).
 const GUEST_ORG_SLUG = "guest";
@@ -826,6 +880,11 @@ export async function runDrop(
 ) {
   // `grid` is an accepted alias for `org` (Gilad's org→grid rename); `org` still works.
   const targetGrid = org ?? grid;
+  // The `deps` seam (readFile/exists) exists ONLY so the content-handling
+  // regression tests can drive the `path` / `@`-path routes offline. Production
+  // always calls this with no deps.
+  const { readFile: readFileImpl = readFile, fsExists = existsSync } = deps;
+
   // Defensive: the web edition schema excludes `path`, but if a model still
   // passes one (e.g. from a cached tool description), reject early with a
   // clear explanation.
@@ -835,30 +894,106 @@ export async function runDrop(
     );
   }
 
+  // An agent may pass an `@`-prefixed path (invented `@/home/claude/...`
+  // shorthand) or a bare filesystem path as `html`. Normalise: strip a leading
+  // `@`, and in the local edition promote a path-looking `html` to the `path`
+  // route (read from disk) when the file exists. On the hosted server there is
+  // no disk, so a path-looking `html` is a clear error.
+  let effectivePath = filePath;
+  let htmlInput = typeof html === "string" ? html : undefined;
+  if (!effectivePath && typeof htmlInput === "string") {
+    let candidate = htmlInput;
+    if (candidate.startsWith("@")) candidate = candidate.slice(1);
+    if (!looksLikeFullHtml(candidate) && looksLikePath(candidate)) {
+      if (ctx.edition === "web") {
+        throw new Error(
+          `This looks like a file path (\`${candidate.trim()}\`), but the hosted server cannot read local ` +
+            `files — pass the raw HTML inline as \`html\`.`,
+        );
+      }
+      const resolvedPath = candidate.trim();
+      if (fsExists(resolvedPath)) {
+        effectivePath = resolvedPath;
+        htmlInput = undefined;
+      } else {
+        throw new Error(
+          `The path \`${resolvedPath}\` does not exist. Pass a valid \`path\` to the .html file, or pass ` +
+            `the raw HTML inline as \`html\` (do not base64-encode it, and there is no artifact_files parameter).`,
+        );
+      }
+    } else if (candidate !== htmlInput) {
+      // Leading `@` on genuine inline content — strip it and keep the content.
+      htmlInput = candidate;
+    }
+  }
+
   let bytes;
   let name;
   let type;
-
-  if (filePath) {
-    bytes = await readFile(filePath);
-    name = filename || basename(filePath);
-    type = "application/octet-stream";
-  } else if (typeof html === "string" && html.length > 0) {
-    let content = html;
+  // Anonymous drops are inline-capped hard; signed-in drops get a larger cap.
+  // The cap is enforced AFTER auth is resolved (see below), so only inline
+  // routes flag themselves here — `path` (local, read from disk) is uncapped.
+  let enforceInlineCap = false;
+
+  if (effectivePath) {
+    const raw = await readFileImpl(effectivePath);
+    const asText = Buffer.isBuffer(raw) ? raw.toString("utf8") : String(raw);
+    const { html: decoded, wasBase64 } = decodeIfBase64Html(asText);
+    const lowerName = String(effectivePath).toLowerCase();
+    const nameIsHtml = lowerName.endsWith(".html") || lowerName.endsWith(".htm");
+    if (wasBase64) {
+      // A base64 `.txt` (or similar) that decoded to real HTML → publish the
+      // decoded HTML as text/html under an index.html name.
+      bytes = Buffer.from(decoded, "utf8");
+      type = "text/html";
+      name = filename || (nameIsHtml ? basename(effectivePath) : "index.html");
+    } else {
+      bytes = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+      // Content-type sniff (fix #4): serve HTML as text/html so it renders as a
+      // page instead of downloading as a blob.
+      if (looksLikeFullHtml(asText) || nameIsHtml) {
+        type = "text/html";
+        name = filename || (nameIsHtml ? basename(effectivePath) : "index.html");
+      } else {
+        type = "application/octet-stream";
+        name = filename || basename(effectivePath);
+      }
+    }
+  } else if (typeof htmlInput === "string" && htmlInput.length > 0) {
+    // Rescue a base64-of-HTML blob passed as `html` (real user repro).
+    const { html: resolved } = decodeIfBase64Html(htmlInput);
+    let content = resolved;
     if (!looksLikeFullHtml(content)) {
-      content =
-        `<!doctype html>\n<html lang="en">\n<head><meta charset="utf-8">` +
-        `<title>Shared on CloudGrid</title></head>\n<body>\n${content}\n</body>\n</html>\n`;
+      const stripped = content.replace(/\s+/g, "");
+      const looksBase64 =
+        stripped.length >= 64 && stripped.length % 4 === 0 && /^[A-Za-z0-9+/]+={0,2}$/.test(stripped);
+      const isShortFragment = Buffer.byteLength(content, "utf8") <= 8192;
+      const hasTag = /<[a-z][\s\S]*>/i.test(content);
+      if (isShortFragment && (hasTag || (!looksBase64 && !looksLikePath(content)))) {
+        // Legit "share this snippet" — wrap a small text/markup fragment into a
+        // full document (preserve existing friendly behavior).
+        content =
+          `<!doctype html>\n<html lang="en">\n<head><meta charset="utf-8">` +
+          `<title>Shared on CloudGrid</title></head>\n<body>\n${content}\n</body>\n</html>\n`;
+      } else {
+        // Large, or base64 that failed to decode to HTML, or a bare file path:
+        // refuse instead of silently publishing garbage.
+        const kind = looksBase64
+          ? "base64"
+          : looksLikePath(content)
+            ? "a file path"
+            : "raw data";
+        throw new Error(
+          `This doesn't look like an HTML document (it looks like ${kind}). Pass the raw HTML as \`html\`, ` +
+            `or in the local edition pass \`path\` to the .html file — do NOT base64-encode it. ` +
+            `There is no artifact_files parameter.`,
+        );
+      }
     }
     bytes = Buffer.from(content, "utf8");
     name = filename || "index.html";
     type = "text/html";
-    if (bytes.byteLength > ANON_HTML_MAX_BYTES) {
-      throw new Error(
-        `This HTML is ${(bytes.byteLength / 1e6).toFixed(2)} MB. Anonymous drops are capped at 2 MB. ` +
-          `Trim it, or sign in to publish larger.`,
-      );
-    }
+    enforceInlineCap = true;
   } else {
     throw new Error("Provide either `html` (inline content) or `path` (a local file).");
   }
@@ -920,6 +1055,26 @@ export async function runDrop(
   }
   const isAnonymousWire = mode === "anon-edit" || !authToken;
 
+  // Auth-aware inline size cap (relocated here — auth is only known now). Anon
+  // inline drops stay capped at 2MB; signed-in inline drops get the larger
+  // AUTHED cap. `path` (read from disk) is uncapped and does not set the flag.
+  if (enforceInlineCap) {
+    if (isAnonymousWire) {
+      if (bytes.byteLength > ANON_HTML_MAX_BYTES) {
+        throw new Error(
+          `This HTML is ${(bytes.byteLength / 1e6).toFixed(2)} MB. Anonymous drops are capped at 2 MB. ` +
+            `Trim it, or sign in to publish larger.`,
+        );
+      }
+    } else if (bytes.byteLength > AUTHED_HTML_MAX_BYTES) {
+      throw new Error(
+        `This HTML is ${(bytes.byteLength / 1e6).toFixed(2)} MB. Inline drops are capped at ` +
+          `${(AUTHED_HTML_MAX_BYTES / 1e6).toFixed(0)} MB. In the local edition pass \`path\` to the ` +
+          `.html file (read from disk — no inline size limit) instead of pasting it inline.`,
+      );
+    }
+  }
+
   const headers = {};
   if (!isAnonymousWire) {
     headers["Authorization"] = `Bearer ${authToken}`;
@@ -2089,38 +2244,131 @@ async function runVisibility(ctx, { target, visibility, org }) {
   };
 }
 
+// Max HTML we'll return inline from runSource. Past this, we return the first
+// slice with truncated:true — a re-plug needs the complete document, so a
+// truncated body is a signal the drop is likely multi-file rather than a single
+// editable HTML document.
+const SOURCE_MAX_BYTES = 1_500_000;
+
+// Reject anything whose host is not `*.cloudgrid.io` (apex `cloudgrid.io`
+// included). SSRF guard for runSource: we only ever fetch live CloudGrid drops
+// server-side, never arbitrary hosts. Returns true when the host is allowed.
+function isCloudgridHost(hostname) {
+  const h = String(hostname || "").toLowerCase();
+  return h === "cloudgrid.io" || h.endsWith(".cloudgrid.io");
+}
+
+// Fetch a drop's/inspiration's current deployed HTML inline as text so an agent
+// that lost the content can edit it and re-plug in place. Resolves the fetch URL
+// (explicit url → session lastDrop → composed grid+slug), enforces the
+// `*.cloudgrid.io` SSRF guard, caps the body at SOURCE_MAX_BYTES, and fails
+// gracefully on a non-200. Uses the global `fetch` seam so tests can mock it.
+export async function runSource(ctx, { entity_id, url, grid, slug } = {}) {
+  const last = ctx.state.lastDrop;
+  // Resolution order: explicit url → session lastDrop.url (if entity_id matches
+  // or no entity_id was given) → composePlugUrl(grid, slug) → fail.
+  let target = null;
+  if (typeof url === "string" && url.length > 0) {
+    target = url;
+  } else if (last?.url && (!entity_id || last.entity_id === entity_id)) {
+    target = last.url;
+  } else if (grid && slug) {
+    // Inspirations/HTML drops are path-based at the org apex.
+    target = composePlugUrl({ slug, grid });
+  }
+  if (!target) {
+    throw new Error(
+      "I don't have this drop's URL — pass the url (e.g. https://<grid>.cloudgrid.io/<slug>) or grid+slug.",
+    );
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(target);
+  } catch {
+    throw new Error(`Not a valid URL: ${target}`);
+  }
+  if (parsed.protocol !== "https:" || !isCloudgridHost(parsed.hostname)) {
+    throw new Error(
+      `Refusing to fetch ${target}: source retrieval is limited to https://*.cloudgrid.io drops.`,
+    );
+  }
+
+  const resolvedUrl = parsed.toString();
+  let res;
+  try {
+    res = await fetch(resolvedUrl, {
+      method: "GET",
+      redirect: "follow",
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch (err) {
+    throw new Error(`Could not reach the live drop at ${resolvedUrl}: ${err.message}`);
+  }
+
+  // A redirect must not escape the allow-list (fetch follows automatically; the
+  // final response URL is the one we actually read).
+  if (res.url && res.url !== resolvedUrl) {
+    let finalHost;
+    try { finalHost = new URL(res.url).hostname; } catch { finalHost = ""; }
+    if (!isCloudgridHost(finalHost)) {
+      throw new Error(
+        `Refusing to follow a redirect off CloudGrid (${res.url}): source retrieval is limited to https://*.cloudgrid.io.`,
+      );
+    }
+  }
+
+  if (!res.ok) {
+    // Graceful fail — never throw a raw fetch error at the model.
+    throw new Error(
+      `Couldn't read the live drop (HTTP ${res.status}). It may be expired, private, or claimed.`,
+    );
+  }
+
+  const buf = Buffer.from(await res.arrayBuffer());
+  const totalBytes = buf.length;
+  const truncated = totalBytes > SOURCE_MAX_BYTES;
+  const html = (truncated ? buf.subarray(0, SOURCE_MAX_BYTES) : buf).toString("utf-8");
+
+  const lines = [
+    `Current source for ${resolvedUrl} (${totalBytes} bytes) — edit this and re-plug with target_entity_id to update the same URL:`,
+  ];
+  if (truncated) {
+    lines.push(
+      "(too large to return in full; re-plug needs the complete document — consider that this drop may be multi-file)",
+    );
+  }
+  lines.push("", html);
+
+  return {
+    text: lines.join("\n"),
+    structured: {
+      url: resolvedUrl,
+      entity_id: entity_id ?? last?.entity_id ?? null,
+      bytes: totalBytes,
+      truncated,
+      html,
+    },
+  };
+}
+
 // ── Registration ───────────────────────────────────────────────────────────────
 // Registers the tools onto `server`. ctx.edition decides whether the CLI-wrapping
 // tools are included (they need a local machine).
 export function registerTools(server, ctx) {
-  // ── Tool naming: gridctl_* with deprecated cloudgrid_* aliases ────────────
-  // Every tool is registered under its new `gridctl_*` name AND its legacy
-  // `cloudgrid_*` alias (same handler), so nothing breaks mid-migration. The
-  // alias is marked deprecated in its description; both names resolve to the
-  // same handler. Aliases are removed in a later major. `reg` wraps the
+  // ── Tool naming: gridctl_* only ───────────────────────────────────────────
+  // Every tool is registered under its `gridctl_*` name only. The legacy
+  // deprecated `cloudgrid_*` aliases were removed in 0.10.0 — they doubled the
+  // connector tool list and de-duplicated poorly in permission UIs. Clients
+  // enumerate tools dynamically, so discovery is unaffected. `reg` wraps the
   // object-config `server.registerTool`; `regTool` wraps the positional
-  // `server.tool` shorthand. Both take the new gridctl_* name and derive the
-  // alias by swapping the prefix.
-  const aliasOf = (name) => name.replace(/^gridctl_/, "cloudgrid_");
-
+  // `server.tool` shorthand.
   const reg = (name, config, handler) => {
     server.registerTool(name, config, handler);
-    const alias = aliasOf(name);
-    if (alias !== name) {
-      server.registerTool(
-        alias,
-        { ...config, description: `(deprecated: use ${name}) ${config.description}` },
-        handler,
-      );
-    }
   };
 
   const regTool = (name, description, schema, annotations, handler) => {
     server.tool(name, description, schema, annotations, handler);
-    const alias = aliasOf(name);
-    if (alias !== name) {
-      server.tool(alias, `(deprecated: use ${name}) ${description}`, schema, annotations, handler);
-    }
   };
 
   // ── Widget resources (web edition, ChatGPT Apps SDK) ──────────────────────
@@ -2174,8 +2422,8 @@ export function registerTools(server, ctx) {
         ...dropReplugParams,
       }
     : {
-        html: z.string().optional().describe("Inline HTML to publish. A fragment is wrapped into a full document."),
-        path: z.string().optional().describe("Path to a local file to upload instead of inline HTML."),
+        html: z.string().optional().describe("Inline HTML to publish (a small fragment is wrapped into a full document). Pass the RAW HTML — do NOT base64-encode it, and do NOT pass an `@`-prefixed path or a file path here. For a large or image-heavy document, use `path` instead."),
+        path: z.string().optional().describe("Path to a local .html file to upload instead of inline HTML — read from disk with no inline size limit. Preferred for large or image-heavy documents. There is no `artifact_files` parameter."),
         filename: z.string().optional().describe("Filename to present. Defaults to index.html for inline HTML."),
         anonymous: z.boolean().optional().describe("Force an anonymous drop even if the user is signed in."),
         grid: z.string().optional().describe("Leave unset; the tool will ask the user which grid to publish into. Only set this after the user picks from the list the tool returns."),
@@ -2186,7 +2434,7 @@ export function registerTools(server, ctx) {
   reg(
     "gridctl_drop",
     {
-      description: "Publish an HTML page or file to CloudGrid and get a public shareable URL. Use when the user wants to share, publish, send, or 'deploy' an artifact, or wants a link to send a friend. Re-drops in the same session UPDATE THE SAME entity in place — same link, new content, expiry reset (pass fresh: true to force a new drop, or entity_id to target a specific earlier drop). If signed in, it publishes into the user's grid as an owned inspiration; if not, it drops anonymously into the Guest Grid, claimable later — the result includes an entity_id + owner_token to persist as the re-plug/claim handle for later sessions. Drops expire per the platform default (7 days) unless claimed/owned; every in-place edit resets the timer. Calls POST /api/v2/plug directly.",
+      description: "Publish an HTML page or file to CloudGrid and get a public shareable URL. Use when the user wants to share, publish, send, or 'deploy' an artifact, or wants a link to send a friend. Re-drops in the same session UPDATE THE SAME entity in place — same link, new content, expiry reset (pass fresh: true to force a new drop, or entity_id to target a specific earlier drop). If signed in, it publishes into the user's grid as an owned inspiration; if not, it drops anonymously into the Guest Grid, claimable later — the result includes an entity_id + owner_token to persist as the re-plug/claim handle for later sessions. Drops expire per the platform default (7 days) unless claimed/owned; every in-place edit resets the timer. If you want to edit an existing drop but no longer have its HTML, call gridctl_source first to retrieve it, then re-plug with target_entity_id. For a large or image-heavy document in the local edition, pass `path` to the .html file (read from disk — no inline size limit); do NOT base64-encode the content and do NOT pass an `@`-prefixed path or a file path as `html`. There is no `artifact_files` parameter. Calls POST /api/v2/plug directly.",
       inputSchema: dropInputSchema,
       outputSchema: {
         url: z.string().optional().describe("The public URL of the drop (stable across re-drops of the same entity)."),
@@ -2378,7 +2626,9 @@ export function registerTools(server, ctx) {
           ? "Pass the source inline via artifact_files."
           : "Pass the source as a local `path` (folder or file) or inline via artifact_files.") +
         " Note: in-place re-plug currently supports inspirations (HTML/static drops); to rebuild a deployed " +
-        "app/agent, use the CloudGrid CLI (`cloudgrid plug`) in its linked folder.",
+        "app/agent, use the CloudGrid CLI (`cloudgrid plug`) in its linked folder." +
+        " If you want to edit an existing drop but no longer have its HTML, call gridctl_source first to " +
+        "retrieve it, then re-plug with target_entity_id.",
       inputSchema: plugInputSchema,
       outputSchema: {
         entity_id: z.string().optional().describe("Globally unique — pass back as target_entity_id to re-plug."),
@@ -2502,6 +2752,42 @@ export function registerTools(server, ctx) {
     },
   );
 
+  // Source — both editions. Fetches a drop's current deployed HTML inline so an
+  // agent that lost the content can edit it and re-plug in place.
+  reg(
+    "gridctl_source",
+    {
+      description:
+        "Retrieve the CURRENT deployed HTML of an inspiration/drop inline as text, so you can edit it and " +
+        "re-plug the SAME URL when you no longer have its source in context (e.g. the user asks to 'change the " +
+        "color' of a drop you made earlier). Defaults to this session's last drop; otherwise pass the public " +
+        "url (or grid+slug). Works for single-document HTML drops/inspirations (the common case). For " +
+        "multi-file or runtime (app/agent) deploys, use gridctl_download (signed tarball URLs) instead. " +
+        "Fetches the public *.cloudgrid.io URL server-side; read-only, creates nothing.",
+      inputSchema: {
+        entity_id: z.string().optional().describe("The drop's durable id. Defaults to this session's last drop."),
+        url: z.string().optional().describe("The public URL of the drop (e.g. https://<grid>.cloudgrid.io/<slug>). Defaults to this session's last drop URL."),
+        grid: z.string().optional().describe("Grid slug — used only to construct the URL when neither url nor session state is available."),
+        slug: z.string().optional().describe("Entity slug — used with grid to construct the URL when neither url nor session state is available."),
+      },
+      outputSchema: {
+        url: z.string().describe("The URL that was fetched."),
+        entity_id: z.string().nullable().describe("The drop's entity id (echoed from input/session, if known)."),
+        bytes: z.number().describe("Total size of the live document in bytes."),
+        truncated: z.boolean().describe("True if the body exceeded 1.5MB and was cut — the drop may be multi-file."),
+        html: z.string().describe("The current deployed HTML (truncated to 1.5MB when oversized)."),
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    },
+    async (input) => {
+      try {
+        return okResult(await runSource(ctx, input || {}));
+      } catch (err) {
+        return fail(err.message);
+      }
+    },
+  );
+
   // Login — both editions. Local opens a browser and saves to the credentials
   // file; web returns the URL and saves to the session.
   reg(

package/src/widgets/live-result.html

@@ -124,7 +124,7 @@ body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;b
           var statusEl = document.getElementById("vis-status");
           if (statusEl) statusEl.textContent = "Updating\u2026";
           if (!window.openai || !window.openai.callTool) return;
-          window.openai.callTool("cloudgrid_visibility", { visibility: vis }).then(function (res) {
+          window.openai.callTool("gridctl_visibility", { visibility: vis }).then(function (res) {
             var newVis = res && res.structuredContent && res.structuredContent.visibility;
             if (newVis) {
               data.current_visibility = newVis;

package/src/widgets/org-picker.html

@@ -75,7 +75,7 @@ body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;b
           if (input.fresh !== undefined) args.fresh = input.fresh;
           args.grid = slug;
           args.org = slug; // alias kept for compatibility
-          window.openai.callTool("cloudgrid_drop", args).then(function () {
+          window.openai.callTool("gridctl_drop", args).then(function () {
             // The host will render the new result with the live-result card.
           }).catch(function () {
             for (var m = 0; m < all.length; m++) all[m].classList.remove("loading");