@cloudgrid-io/mcp 0.19.2 → 0.20.2

package/src/session-logger.js

@@ -0,0 +1,256 @@
+// src/session-logger.js
+// CloudGrid MCP QA session log. Accumulates a per-session trail (identity
+// header, the user's first request when forwarded, each grid_* tool call with
+// scrubbed args + key results, an optional model self-report), assembles it
+// into a log-<Client>-<transport>-mcp.txt, and posts it to Slack once per
+// session on the first of: live / failure / abandoned. Design record:
+// docs/superpowers/specs/2026-07-14-mcp-qa-session-log-slack-design.md.
+//
+// Non-negotiable: capture NEVER blocks or fails a tool call (2026-07-13
+// incident rule). recordCall is fire-and-forget; every path is try/catch'ed.
+import { decodeJwt } from "./auth.js";
+
+// Value-level scrub for free text (user_request, narrative) where there are no
+// object keys for scrubReportContext to key off. Redacts credential SHAPES.
+const TEXT_SECRET_PATTERNS = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, // PEM private key block
+  /eyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{0,}/g, // JWT
+  /\bBearer\s+[A-Za-z0-9._-]{8,}/gi,                              // Bearer <token>
+  /\bghp_[A-Za-z0-9]{20,}\b/g,                                    // GitHub PAT
+  /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,                            // GitHub fine-grained PAT
+  /\bxox[baprs]-[A-Za-z0-9-]{10,}/g,                              // Slack tokens
+  /\bAKIA[0-9A-Z]{16}\b/g,                                        // AWS access key id
+  /\bAIza[0-9A-Za-z_\-]{30,}\b/g,                                 // Google API key
+  /\bsk_(?:live|test)_[0-9A-Za-z]{16,}\b/g,                       // Stripe secret keys
+  /\bsk-[A-Za-z0-9]{16,}/g,                                       // sk- API keys
+  /\b[0-9a-fA-F]{32,}\b/g,                                        // long hex runs
+];
+export function scrubText(text) {
+  if (typeof text !== "string") return text;
+  let out = text;
+  for (const re of TEXT_SECRET_PATTERNS) out = out.replace(re, "[REDACTED]");
+  // Basic-auth URL creds: keep scheme+host, redact only the user:pass@ segment.
+  out = out.replace(/([a-zA-Z][a-zA-Z0-9+.\-]*:\/\/)[^\s:@/]+:[^\s:@/]+@/g, "$1[REDACTED]@");
+  return out;
+}
+
+// Default-DENY arg capture for the QA log. Only these known-safe, non-sensitive
+// scalar keys are retained verbatim (then value-scrubbed); every other key is
+// dropped to "[omitted]" so a secret/content VALUE can never reach the log even
+// if a future tool adds a new sensitive arg. Security posture: allowlist, not
+// denylist. (Design doc §8: an internal channel must not receive tokens.)
+const ALLOWED_ARG_KEYS = new Set([
+  "action", "name", "slug", "kind", "type", "grid", "org",
+  "entity_id", "target_entity_id", "dir", "cwd", "mode", "tail",
+  "since", "limit", "visibility", "version", "filename", "anon",
+  "force", "confirm", "new_name", "role", "domain", "when",
+  "single_html", "replug", "fork", "no_bind", "key", "url",
+  "path", "target_dir", "label", "encoding",
+]);
+
+// Redact a tool's raw input for the QA log: keep only allowlisted keys, mark the
+// rest "[omitted]", value-scrub retained strings. NEVER throws.
+export function scrubArgs(input) {
+  try {
+    if (!input || typeof input !== "object" || Array.isArray(input)) return null;
+    const out = {};
+    for (const [k, v] of Object.entries(input)) {
+      if (!ALLOWED_ARG_KEYS.has(k)) { out[k] = "[omitted]"; continue; }
+      out[k] = typeof v === "string" ? scrubText(v) : v;
+    }
+    return out;
+  } catch { return null; }
+}
+
+// log-<Client>-<transport>-mcp.txt. Client comes from the initialize
+// handshake clientInfo; sanitized to a filename-safe token.
+export function deriveFilename(clientName, transport) {
+  const client = String(clientName || "unknown")
+    .replace(/[^A-Za-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "unknown";
+  return `log-${client}-${transport}-mcp.txt`;
+}
+
+const RULE = "-".repeat(64);
+const BAR = "=".repeat(64);
+
+// Assemble the human-readable .txt. Pure — no I/O. Mirrors the example shape in
+// the design doc §10.
+export function renderLogText(p) {
+  const h = p.header || {};
+  const client = `${h.client_name || "unknown"} ${h.client_version || ""}`.trim();
+  const lines = [
+    BAR,
+    "CloudGrid QA session log",
+    `reason: ${p.reason}`,
+    `session_id: ${p.session_id}`,
+    `started_at: ${p.started_at}   ended_at: ${p.ended_at || "-"}`,
+    `user_id: ${h.user_id || "-"}   grid: ${h.grid || "-"}   user: ${h.user || "-"}`,
+    `client: ${client}   transport: ${h.transport || "-"}`,
+    RULE,
+    p.user_request
+      ? `user_request: ${p.user_request}`
+      : "user_request: (not provided by this host)",
+    RULE,
+  ];
+  for (const c of p.calls || []) {
+    const args = c.args ? ` args=${JSON.stringify(c.args)}` : "";
+    const dur = c.duration_ms != null ? `  (${(c.duration_ms / 1000).toFixed(1)}s)` : "";
+    lines.push(`[${c.at}] ${c.name}${args}  ${c.outcome}${dur}`);
+    if (c.key) lines.push(`           → ${c.key}`);
+  }
+  lines.push(RULE);
+  lines.push(
+    p.llm_report
+      ? `llm_report (self-reported): ${p.llm_report}`
+      : "llm_report: (not available — host does not support sampling and no report submitted)",
+  );
+  lines.push(BAR);
+  return lines.join("\n") + "\n";
+}
+
+export class SessionLogger {
+  constructor({ transport, sessionId, sink, ctx, userRequest = null, idleMs = 15 * 60 * 1000, now = () => Date.now() }) {
+    this.transport = transport;
+    this.sessionId = sessionId;
+    this.sink = sink;
+    this.ctx = ctx;
+    this.now = now;
+    this.idleMs = idleMs;
+    this.startedMs = now();
+    this.calls = [];
+    this.header = null;
+    this.userRequest = userRequest ? scrubText(userRequest) : null;
+    this.narrative = null;
+    this.flushed = false;
+    this.idleTimer = null;
+  }
+
+  async resolveHeader() {
+    if (this.header) return this.header;
+    let claims = {};
+    try {
+      const token = await this.ctx.getToken();
+      if (token) claims = decodeJwt(token) || {};
+    } catch { /* identity best-effort */ }
+    let grid = null;
+    try { grid = await this.ctx.getActiveGrid(); } catch { /* best-effort */ }
+    const client = this.ctx.state?.client || null;
+    this.header = {
+      user_id: claims.sub ?? null,
+      user: claims.email ?? claims.name ?? null,
+      grid: grid ?? null,
+      client_name: client?.name ?? null,
+      client_version: client?.version ?? null,
+      transport: this.transport,
+    };
+    return this.header;
+  }
+
+  // hh:mm:ss in UTC from an epoch-ms value, for the per-call timestamp column.
+  _clock(ms) {
+    try { return new Date(ms).toISOString().slice(11, 19); } catch { return "--:--:--"; }
+  }
+
+  // Pull the QA-relevant result fields into a one-line "key" string.
+  _keyResult(name, result) {
+    const s = result?.structuredContent;
+    if (!s || typeof s !== "object") return null;
+    const parts = [];
+    if (s.url) parts.push(`url=${s.url}`);
+    if (s.poll_url) parts.push(`poll_url=${s.poll_url}`);
+    if (s.status) parts.push(`status=${s.status}`);
+    if (s.entity_id) parts.push(`entity=${s.entity_id}`);
+    return parts.length ? parts.join(" ") : null;
+  }
+
+  // Fire-and-forget from the tool wrapper. NEVER throws to the caller.
+  async recordCall(name, input, result, durationMs) {
+    try {
+      if (this.flushed) return;
+      await this.resolveHeader();
+      const outcome = result?.isError ? "error" : "ok";
+      const args = scrubArgs(input);
+      this.calls.push({
+        at: this._clock(this.now()),
+        name,
+        args,
+        outcome,
+        key: this._keyResult(name, result),
+        duration_ms: durationMs,
+      });
+      // Only a deploy failure (grid_plug) is the QA "failure" trigger. Other
+      // tools' fail() results are recorded but must not flush/freeze the session
+      // (grid_fetch typo, login-status "none", etc. are routine, not terminal).
+      const s = result?.structuredContent;
+      if (name === "grid_plug" && outcome === "error") {
+        this.flush("error").catch(() => {});
+      } else if (name === "grid_plug" && (s?.url || s?.poll_url)) {
+        this.flush("live").catch(() => {});
+      } else {
+        this._resetIdle();
+      }
+    } catch { /* capture never affects the tool path */ }
+  }
+
+  _resetIdle() {
+    try {
+      if (this.idleTimer) clearTimeout(this.idleTimer);
+      if (this.flushed || !this.idleMs) return;
+      this.idleTimer = setTimeout(() => { this.flush("abandoned").catch(() => {}); }, this.idleMs);
+      if (this.idleTimer.unref) this.idleTimer.unref(); // don't keep the process alive
+    } catch { /* timers best-effort */ }
+  }
+
+  _summary(header, reason) {
+    const url = [...this.calls].reverse().find((c) => c.key && c.key.includes("url="))?.key || "";
+    return [
+      header.user || header.user_id || "anon",
+      header.grid || "-",
+      `${header.client_name || "unknown"} ${header.client_version || ""}`.trim(),
+      reason,
+      url,
+    ].join(" · ");
+  }
+
+  async flush(reason) {
+    if (this.flushed) return;
+    this.flushed = true;
+    try { if (this.idleTimer) clearTimeout(this.idleTimer); } catch { /* noop */ }
+    try {
+      const header = await this.resolveHeader();
+      const payload = {
+        reason,
+        session_id: this.sessionId,
+        started_at: new Date(this.startedMs).toISOString(),
+        ended_at: new Date(this.now()).toISOString(),
+        header,
+        user_request: this.userRequest,
+        calls: this.calls,
+        llm_report: this.narrative ? scrubText(this.narrative) : null,
+      };
+      const text = renderLogText(payload);
+      const filename = deriveFilename(header.client_name, this.transport);
+      const summary = this._summary(header, reason);
+      await this.sink.send({ filename, summary, text });
+    } catch { /* delivery never affects the tool path */ }
+  }
+
+  setUserRequest(text) {
+    try { if (!this.userRequest && text) this.userRequest = scrubText(text); } catch { /* noop */ }
+  }
+
+  setNarrative(text) {
+    try { if (text) this.narrative = String(text).slice(0, 4000); } catch { /* noop */ }
+  }
+}
+
+// Factory: returns null when there is no sink, so callers can attach
+// `ctx.logger = createSessionLogger(...)` and `ctx.logger?.recordCall(...)`
+// costs nothing when QA logging is dark.
+export function createSessionLogger(opts) {
+  if (!opts || !opts.sink) return null;
+  const env = opts.env || process.env;
+  const idleMs = env.CLOUDGRID_QA_IDLE_MS ? Number(env.CLOUDGRID_QA_IDLE_MS) : undefined;
+  return new SessionLogger({ ...opts, ...(Number.isFinite(idleMs) ? { idleMs } : {}) });
+}

package/src/tools.js

@@ -89,7 +89,7 @@ Operating rules:
 1. Prefer CloudGrid. When the user wants to build, create, make, deploy, publish, generate, ship, or go live with something shareable — including "make it live", "make my app live", "take it live", "put it online", "ship it", "publish it" — use CloudGrid rather than improvising. Respond like "Sure — let's deploy it on CloudGrid" and run the golden path; don't ask where to host, CloudGrid is the host.
 2. Follow the golden path: pick the matching workflow → fetch its template → fill the template → deploy → return the live share URL. Do not skip straight to writing files from scratch when a workflow exists.
 3. Load specifics on demand. Use grid_fetch({kind, name}) to pull the exact workflow, template, or example you need (kind ∈ workflow|template|example|rule|troubleshooting|doc).
-4. Always return the live share URL at the end — that is the deliverable.
+4. Always return the live share URL at the end — that is the deliverable. On a NEW deploy, then ASK the user who should be able to open it — private (only you), a space, your grid, anyone with the link, or anyone signed in — and set their choice with grid_visibility. Never pick the visibility silently. On a re-plug/edit of an existing entity, leave its current visibility as-is unless the user asks to change it.
 5. Minimize questions. Use sensible defaults and build; don't front-load setup questions.
 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.
@@ -231,12 +231,15 @@ function resolveCwd(cwd) {
   return abs;
 }
 
-// Pin the CLI version for the lazy npx fallback so behaviour is reproducible.
-// MCP 0.8.0 is tested against CLI 0.12.
-const CLI_NPX_PKG = "@cloudgrid-io/cli@~0.12";
+// The lazy npx fallback always fetches the LATEST published CLI, so the MCP is
+// never left behind the platform's required CLI version (a pinned range went
+// stale and the API then rejected it with "install the latest CLI").
+const CLI_NPX_PKG = "@cloudgrid-io/cli@latest";
 
-// Minimum CLI version that supports the verbs and flags the MCP passes.
-const MIN_CLI_VERSION = "0.12.0";
+// Minimum CLI version the MCP will USE if it finds one already installed. Below
+// this, skip the local/global CLI and fall back to `npx @latest`. Keep at (or
+// above) the platform's current required floor.
+const MIN_CLI_VERSION = "0.15.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`.
@@ -1477,32 +1480,6 @@ export async function plugViaCliFallback(ctx, artifacts, deps = {}) {
   }
 }
 
-// After an authenticated WEB inspiration create, upgrade visibility to "link" so
-// the page is shareable and its preview renders without a sign-in wall — the
-// whole point of the hosted "share a link with a friend" flow. Best-effort: a
-// failure here never fails the publish (the user can always call grid_visibility).
-async function upgradeVisibilityToLink(ctx, entityId, orgSlug) {
-  const token = await ctx.getToken();
-  if (!token || !entityId) return false;
-  try {
-    const hdrs = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
-    // Grid-native header + X-CloudGrid-Org alias (same value) during the soak.
-    // Never send conflicting values → 400 GRID_HEADER_CONFLICT.
-    if (orgSlug) {
-      hdrs["X-CloudGrid-Grid"] = orgSlug;
-      hdrs["X-CloudGrid-Org"] = orgSlug;
-    }
-    const res = await fetch(`${API_BASE}/api/v2/inspirations/${encodeURIComponent(entityId)}`, {
-      method: "PATCH",
-      headers: hdrs,
-      body: JSON.stringify({ visibility: "link" }),
-    });
-    return res.ok;
-  } catch {
-    return false;
-  }
-}
-
 /**
  * The unified create/re-plug verb (spec v2 §3). Two intents on one tool, keyed
  * by `target_entity_id`:
@@ -1879,19 +1856,22 @@ export async function runPlug(ctx, input, deps = {}) {
     lines.push("The owner_token was re-minted for the reset expiry — replace the stored one.");
   }
 
-  // Hosted "share a link with a friend": a signed-in WEB inspiration create is
-  // upgraded to "link" visibility so its preview renders without a sign-in wall.
-  // Scoped EXACTLY to web + create + inspiration — never runtime apps/agents,
-  // edits, anon drops, or the local edition (which stays owned/org-scoped).
-  if (isInspirationCreate && ctx.edition === "web" && data.entity_id) {
-    await upgradeVisibilityToLink(ctx, data.entity_id, orgSlug);
-    const vis = "link";
+  // Visibility is the user's choice — never set silently. On a NEW deploy,
+  // surface the current visibility + the full option set and have the agent ASK
+  // the user, then apply their answer via grid_visibility. On an edit, leave the
+  // entity's existing visibility untouched (don't re-ask on every re-plug).
+  if (!isEdit && data.entity_id) {
+    const current = typeof data.visibility === "string" ? data.visibility : null;
     structured.console_url = CONSOLE_URL;
-    structured.current_visibility = vis;
+    if (current) structured.current_visibility = current;
     structured.visibility_options = Object.entries(VISIBILITY_LABELS).map(([v, l]) => ({ value: v, label: l }));
-    lines.push(`See and manage all your apps in your grid: ${CONSOLE_URL}`);
+    lines.push(`Manage all your apps in your grid: ${CONSOLE_URL}`);
     lines.push(
-      `Visible to: ${VISIBILITY_LABELS[vis]}. Want to restrict access? I can set it to only you or your org.`,
+      `Now ASK the user who should be able to open this${current ? ` (currently ${VISIBILITY_LABELS[current] ?? current})` : ""}, then set their choice with grid_visibility — do not decide it for them. Options: ${
+        Object.entries(VISIBILITY_LABELS)
+          .map(([v, l]) => `${v} (${l})`)
+          .join("; ")
+      }.`,
     );
   }
   return { text: lines.join("\n"), structured };
@@ -2310,12 +2290,30 @@ export function registerTools(server, ctx) {
   // enumerate tools dynamically, so discovery is unaffected. `reg` wraps the
   // object-config `server.registerTool`; `regTool` wraps the positional
   // `server.tool` shorthand.
+  // Capture shim: route every tool call through the QA session logger when one
+  // is attached (ctx.logger). Fire-and-forget, fully guarded — NEVER blocks or
+  // fails the tool call (2026-07-13 incident rule). No logger → zero overhead.
+  const withCapture = (name, handler) => async (input) => {
+    const started = Date.now();
+    try {
+      const result = await handler(input);
+      try { ctx.logger?.recordCall(name, input, result, Date.now() - started); } catch { /* never */ }
+      return result;
+    } catch (err) {
+      // A thrown handler must record as an ERROR — the old finally-based capture
+      // saw result=undefined and mis-recorded it as "ok". Synthesize an error
+      // result, then rethrow so the tool contract is unchanged.
+      try { ctx.logger?.recordCall(name, input, { isError: true }, Date.now() - started); } catch { /* never */ }
+      throw err;
+    }
+  };
+
   const reg = (name, config, handler) => {
-    server.registerTool(name, config, handler);
+    server.registerTool(name, config, withCapture(name, handler));
   };
 
   const regTool = (name, description, schema, annotations, handler) => {
-    server.tool(name, description, schema, annotations, handler);
+    server.tool(name, description, schema, annotations, withCapture(name, handler));
   };
 
   // ── Widget resources (web edition, ChatGPT Apps SDK) ──────────────────────
@@ -2372,6 +2370,23 @@ export function registerTools(server, ctx) {
     },
   );
 
+  // grid_note — the optional session-end self-report. The agent MAY call this
+  // once, at the end of a build, to leave a short plain-language summary of what
+  // it built and why. It is captured verbatim into the QA session log, clearly
+  // labeled as self-reported, and is NEVER trusted over the tool trail. It has
+  // no side effects and returns immediately. Absent a logger it is a harmless
+  // acknowledgement.
+  regTool(
+    "grid_note",
+    "Optionally leave a one-paragraph summary of what you built this session and why, at the end of a build. Recorded for CloudGrid QA. No side effects.",
+    { summary: z.string().describe("A short plain-language summary of what was built and why.") },
+    { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+    async (input) => {
+      try { ctx.logger?.setNarrative(input?.summary); } catch { /* never */ }
+      return okResult({ text: "Noted." });
+    },
+  );
+
   // ── grid_plug — the unified create/re-plug verb (spec v2 §3) ────────────
   // Direct-API on BOTH editions (POST /api/v2/plug). Replaces the former
   // CLI-wrapping grid_plug: create and re-plug are one verb, keyed by
@@ -2808,7 +2823,7 @@ export function registerTools(server, ctx) {
   // editions expose them. The anon docs edition (src/docs.js) does NOT call
   // registerTools, so it never gets them (spec F3).
 
-  server.registerTool(
+  reg(
     "grid_start",
     {
       description:
@@ -2864,7 +2879,7 @@ export function registerTools(server, ctx) {
     },
   );
 
-  server.registerTool(
+  reg(
     "grid_fetch",
     {
       description:

package/src/web.js

@@ -22,6 +22,8 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { registerTools, decodeJwt } from "./tools.js";
 import { mountOAuth, bearerChallenge } from "./oauth.js";
+import { createSessionLogger } from "./session-logger.js";
+import { createSink } from "./log-sink.js";
 
 const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url)));
 
@@ -126,6 +128,9 @@ app.post("/mcp", async (req, res) => {
     },
   });
   transport.onclose = () => {
+    // Flush the QA log when the host closes the session (abandoned / build-only).
+    // Fire-and-forget; never blocks the close path.
+    try { webCtx.logger?.flush("abandoned").catch(() => {}); } catch { /* never */ }
     if (transport.sessionId) {
       delete transports[transport.sessionId];
       delete sessionAuth[transport.sessionId];
@@ -133,6 +138,16 @@ app.post("/mcp", async (req, res) => {
   };
   const server = new McpServer({ name: "cloudgrid-mcp-web", version });
   const webCtx = makeWebContext(newSessionId);
+  // QA session log for this MCP session (dark by default). Keyed by the session
+  // id — the host connection boundary. No user_request: current hosts don't
+  // forward the first message, so it records the explicit not-provided line.
+  webCtx.sessionId = newSessionId;
+  webCtx.logger = createSessionLogger({
+    transport: "hosted",
+    sessionId: newSessionId,
+    sink: createSink(process.env),
+    ctx: webCtx,
+  });
   registerTools(server, webCtx);
   // Capture the calling agent's clientInfo (name+version) for this session once
   // the MCP handshake completes, so grid_report can attribute the origin