@cloudgrid-io/mcp 0.8.1 → 0.9.1

package/src/tools.js

@@ -25,7 +25,23 @@ export const API_BASE = (process.env.CLOUDGRID_API_URL || "https://api.cloudgrid
   "",
 );
 
+// This MCP server's version — mirrors the CLI's cli_version in a report's origin.
+// Read once from package.json; never throw (a report must never fail on this).
+export const MCP_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8")).version;
+  } catch {
+    return "unknown";
+  }
+})();
+
 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) ────────────────────
@@ -70,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.`;
 
@@ -106,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);
@@ -771,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";
@@ -816,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.
@@ -825,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).");
   }
@@ -910,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}`;
@@ -1165,11 +1330,27 @@ export function scrubReportContext(obj, depth = 0) {
 
 // Send a consent-gated bug report to the CloudGrid team. The agent calls this
 // ONLY after the user explicitly agrees (see errorGuidance + the PLAYBOOK rule).
-// Posts to POST /api/v2/errors/feedback with {app:"mcp", message, context,
-// node_version, platform}. Authed → Bearer; anon+web → the trusted-server
-// headers (works once Gilad opens the endpoint; until then a 401 degrades to a
-// friendly "sign in to report"). Never throws — always returns friendly text.
-export async function runReport(ctx, { message, context, include_conversation } = {}) {
+//
+// Matches the CLI reporter (packages/cli error-reporter.ts → client.reportError):
+// POST /api/v2/errors with the CLI payload shape
+//   { type:'error', category, app, message, stack?, context, trace_id?,
+//     failed_step?, http_status?, cli_version, node_version, platform }
+// so CLI + MCP reports land uniformly in the `errors` collection.
+//
+// Source attribution (Gilad's ask): every report says WHERE it came from —
+// source (mcp-stdio | mcp-hosted), client (the calling agent from MCP clientInfo),
+// platform, mcp_version. Sent BOTH as top-level fields AND mirrored in
+// `context.origin`. The POST /errors handler only persists known top-level keys
+// (it drops unknown ones), and `context` is stored + secret-stripped server-side,
+// so `context.origin` is the durable carrier — belt-and-suspenders.
+//
+// Auth: signed-in → Bearer; anon+web → the trusted-server headers (works once the
+// endpoint accepts the credential; until then a 401 degrades to "sign in to
+// report"). Honors CLOUDGRID_TELEMETRY=off (matches the CLI). Never throws.
+export async function runReport(
+  ctx,
+  { message, context, include_conversation, category, trace_id, failed_step, http_status } = {},
+) {
   const summary = typeof message === "string" ? message.trim() : "";
   if (!summary) {
     return okResult({
@@ -1178,19 +1359,69 @@ export async function runReport(ctx, { message, context, include_conversation }
     });
   }
 
-  // Belt-and-suspenders scrub before the value ever leaves the process.
-  const safeContext =
-    context && typeof context === "object" ? scrubReportContext(context) : undefined;
+  // Privacy escape hatch — no telemetry when explicitly disabled (matches the CLI
+  // reporter's CLOUDGRID_TELEMETRY=off). Consent still gates the call regardless;
+  // this is the belt-and-suspenders global opt-out. Nothing leaves the process.
+  if (process.env.CLOUDGRID_TELEMETRY === "off") {
+    return okResult({
+      text: "Error reporting is disabled (CLOUDGRID_TELEMETRY=off) — nothing was sent.",
+      structured: { status: "disabled" },
+    });
+  }
+
+  // ── Source attribution ──────────────────────────────────────────────────────
+  // source: mcp-stdio (local edition) | mcp-hosted (web edition).
+  const source = ctx.edition === "web" ? "mcp-hosted" : "mcp-stdio";
+  // client: the calling agent captured from the MCP clientInfo at initialize.
+  // Falls back to "unknown" — a report must never fail on missing client info.
+  const ci = ctx.state?.client;
+  const client =
+    ci && ci.name
+      ? ci.version
+        ? `${ci.name} ${ci.version}`
+        : String(ci.name)
+      : "unknown";
+  const platform = `${process.platform} ${process.arch}`;
+
+  // Belt-and-suspenders scrub before the value ever leaves the process. The
+  // origin block is authored by us (not user/agent input), so it is appended
+  // AFTER the scrub — it carries no secrets and must survive verbatim.
+  const scrubbed =
+    context && typeof context === "object" ? scrubReportContext(context) : {};
+  const safeContext = {
+    ...scrubbed,
+    origin: {
+      source,
+      client,
+      platform,
+      mcp_version: MCP_VERSION,
+    },
+  };
+
   // The full conversation is NEVER included unless the agent explicitly set the
   // flag (which the PLAYBOOK gates on the user's explicit yes). This tool only
   // records the flag alongside the report so intent is auditable — it does not
   // itself have the transcript.
   const body = {
+    type: "error",
+    // category: default "mcp" (or the failing tool name the agent passes).
+    category: typeof category === "string" && category.trim() ? category.trim() : "mcp",
     app: "mcp",
     message: summary.slice(0, 5000),
     context: safeContext,
+    // Diagnostic pivots (match the CLI) — only when the agent forwards them.
+    ...(typeof trace_id === "string" && trace_id ? { trace_id } : {}),
+    ...(typeof failed_step === "string" && failed_step ? { failed_step } : {}),
+    ...(typeof http_status === "number" && Number.isFinite(http_status) ? { http_status } : {}),
+    // Attribution, ALSO top-level (persisted once the handler accepts these keys;
+    // context.origin is the fallback until then).
+    source,
+    client,
+    platform,
+    // cli_version stays null for MCP-originated reports; mcp_version carries our
+    // version in context.origin (the CLI-analog lives there).
+    cli_version: null,
     node_version: process.version,
-    platform: process.platform,
     ...(include_conversation === true ? { include_conversation: true } : {}),
   };
 
@@ -1215,7 +1446,7 @@ export async function runReport(ctx, { message, context, include_conversation }
 
   let res;
   try {
-    res = await fetch(`${API_BASE}/api/v2/errors/feedback`, {
+    res = await fetch(`${API_BASE}/api/v2/errors`, {
       method: "POST",
       headers,
       body: JSON.stringify(body),
@@ -2013,6 +2244,114 @@ 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).
@@ -2098,8 +2437,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."),
@@ -2110,7 +2449,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)."),
@@ -2302,7 +2641,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."),
@@ -2426,6 +2767,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(
@@ -2705,10 +3082,26 @@ export function registerTools(server, ctx) {
           .boolean()
           .optional()
           .describe("Default false. Set true ONLY if the user explicitly agreed to include the full conversation."),
+        category: z
+          .string()
+          .optional()
+          .describe("Optional category, e.g. the failing tool name (\"deploy\"). Defaults to \"mcp\"."),
+        trace_id: z
+          .string()
+          .optional()
+          .describe("The server's trace/deploy id from the failed response, if any (helps support pivot to the trace)."),
+        failed_step: z
+          .string()
+          .optional()
+          .describe("The server-side pipeline step that failed, if known."),
+        http_status: z
+          .number()
+          .optional()
+          .describe("The HTTP status of the final failed request, if applicable."),
       },
       outputSchema: {
         status: z
-          .enum(["recorded", "rate_limited", "unauthorized", "error", "skipped"])
+          .enum(["recorded", "rate_limited", "unauthorized", "error", "skipped", "disabled"])
           .describe("Outcome of the report."),
       },
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
@@ -2719,6 +3112,10 @@ export function registerTools(server, ctx) {
           message: input?.message,
           context: input?.context,
           include_conversation: input?.include_conversation === true,
+          category: input?.category,
+          trace_id: input?.trace_id,
+          failed_step: input?.failed_step,
+          http_status: input?.http_status,
         });
       } catch (err) {
         // Belt-and-suspenders: never throw noisily out of a report attempt.

package/src/web.js

@@ -132,7 +132,18 @@ app.post("/mcp", async (req, res) => {
     }
   };
   const server = new McpServer({ name: "cloudgrid-mcp-web", version });
-  registerTools(server, makeWebContext(newSessionId));
+  const webCtx = makeWebContext(newSessionId);
+  registerTools(server, webCtx);
+  // Capture the calling agent's clientInfo (name+version) for this session once
+  // the MCP handshake completes, so gridctl_report can attribute the origin
+  // (which agent: Claude/ChatGPT/Cursor/…). Never fatal — missing → "unknown".
+  server.server.oninitialized = () => {
+    try {
+      webCtx.state.client = server.server.getClientVersion() ?? null;
+    } catch {
+      webCtx.state.client = null;
+    }
+  };
   await server.connect(transport);
   await transport.handleRequest(req, res, req.body);
 });