@cloudgrid-io/mcp 0.21.8 → 0.21.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.21.8",
+  "version": "0.21.10",
   "description": "MCP access to CloudGrid — the live runtime environment where the user's apps run WITH the infrastructure they need out of the box: managed MongoDB, Redis (cache/queues/pub-sub), a pgvector store, persistent disk, and built-in AI with no API keys, in any language or stack, no Docker or Kubernetes to manage. Brainstorm, build, plug, and improve apps, games, dashboards, and tools; instant single-page publishes and full runtime-app deploys with a live URL — for developers and non-technical users. Three editions: local stdio (full toolset), hosted web (light, CLI-free), and a public docs-search server.",
   "type": "module",
   "bin": {
@@ -69,6 +69,7 @@
     "test:web-identity": "node --test test/web-identity.test.mjs",
     "test:web-auth-integration": "node --test test/web-auth-integration.test.mjs",
     "test:web-restart-recovery": "node --test test/web-restart-recovery.test.mjs",
+    "test:oauth-client-persistence": "node --test test/oauth-client-persistence.test.mjs",
     "test:web-capabilities-log": "node --test test/web-capabilities-log.test.mjs",
     "test:internal-refs": "node --test test/no-internal-refs.test.mjs",
     "test:login-app": "node test/login-app.test.mjs",

package/src/oauth.js

@@ -8,15 +8,19 @@
 // then redirect back to the client with an authorization code. /oauth/token
 // exchanges it (PKCE-verified) for the CloudGrid JWT as the access token.
 //
-// No new identity provider. State is in-memory (single replica, like sessions).
+// No new identity provider. Client REGISTRATIONS are stateless (a signed,
+// self-describing client_id — durable across restarts and replicas, see #3060);
+// only the short-lived authorize sessions and auth codes are in-memory.
 
-import { randomUUID, createHash } from "node:crypto";
+import { randomUUID, createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { newLoginCode, buildLoginUrl, pollStatusOnce, decodeJwt } from "./auth.js";
 
 const CODE_TTL_MS = 5 * 60 * 1000; // authorize sessions + auth codes live 5 minutes
 
-// In-memory stores. { [id]: record } with created timestamps for TTL sweeps.
-const clients = new Map(); // client_id -> { redirect_uris }
+// In-memory stores for the SHORT-LIVED, single-flight halves of the flow. These
+// are 5-minute, retry-on-failure sessions: losing them to a restart just means
+// the user clicks "sign in" again, never that they must re-add the connector.
+// Client REGISTRATIONS are NOT here — they are stateless (see below, #3060).
 const authSessions = new Map(); // sid -> { cgCode, client_id, redirect_uri, state, code_challenge, created }
 const authCodes = new Map(); // code -> { jwt, client_id, redirect_uri, code_challenge, created }
 
@@ -29,6 +33,95 @@ function b64url(buf) {
   return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 
+// --- Stateless client registration (#3060) -----------------------------------
+// A `client_id` is a signed token that CARRIES its own redirect-URI set, not a
+// random handle into a process-local Map. Registration signs the (sorted,
+// deduped) set under a server secret; /oauth/authorize verifies by recomputing
+// the HMAC and checking `redirect_uri` against the signed set. This makes
+// registration durable across restarts, deploys, and ANY replica count with no
+// datastore, and removes the old unbounded-growth `clients` Map entirely.
+//
+// PKCE and redirect validation are untouched — if anything stricter: the
+// redirect set is now cryptographically bound into the client_id, so a tampered
+// client_id fails the HMAC and is rejected.
+//
+// SECRET: MCP_OAUTH_HMAC_SECRET, read from env, sourced from a Kubernetes Secret
+// (NEVER a ConfigMap), never logged. It is a whitespace/comma-separated list:
+// the FIRST entry signs, ALL entries verify.
+//
+// ROTATION (rolling-update safe — order matters). Do NOT simply prepend the new
+// secret: during a rollout, new pods would sign under a key the not-yet-updated
+// old pods cannot verify, so authorize returns transient 400s. Instead:
+//   1. APPEND the new secret (last position = verify-only) and deploy. Every pod
+//      now VERIFIES both keys; all pods still SIGN under the old first entry.
+//   2. Once the rollout is complete, PROMOTE the new secret to first position
+//      (the signing slot) and deploy. New client_ids are signed under it; the
+//      old key still verifies outstanding ones.
+//   3. Later, DROP the old key. client_ids minted under it stop verifying and
+//      those users re-add the connector ONCE — the deliberate-rotation cost,
+//      versus today's every-deploy breakage.
+// An attacker who obtains the secret can forge a client_id for an arbitrary
+// redirect set — but /oauth/register already mints one for any redirect set
+// unauthenticated, so the secret gates INTEGRITY, not registration; PKCE +
+// CloudGrid sign-in still gate getting a token.
+const CLIENT_ID_PREFIX = "cg1"; // versioned so the scheme can evolve
+
+// A client_id CARRIES its redirect set and travels in a query string, so the set
+// must stay bounded or the token grows without limit. Caps chosen well above any
+// real client (ChatGPT/Claude register one or two URIs).
+const MAX_REDIRECT_URIS = 10;
+const MAX_REDIRECT_URIS_BYTES = 4096;
+// A configured signing key shorter than this is weak for an HMAC secret; we warn
+// but still accept it — any configured key beats the ephemeral fallback (#3060).
+const MIN_SECRET_LENGTH = 32;
+
+function resolveClientSecrets(env = process.env) {
+  const configured = (env.MCP_OAUTH_HMAC_SECRET || "").split(/[\s,]+/).filter(Boolean);
+  if (configured.length > 0) return { secrets: configured, ephemeral: false };
+  // No configured secret: a per-process ephemeral one. The flow works within a
+  // single process, but registrations do NOT survive a restart — i.e. #3060 is
+  // unfixed. Production MUST set the secret; the boot log states which mode is
+  // active so a deploy can be verified.
+  return { secrets: [randomBytes(32).toString("hex")], ephemeral: true };
+}
+
+// Canonical form the signature covers: sorted + deduped, as JSON.
+function canonicalRedirectUris(uris) {
+  return JSON.stringify([...new Set(uris.map((u) => String(u)))].sort());
+}
+
+function signClientId(canonical, secret) {
+  const payload = b64url(Buffer.from(canonical, "utf8"));
+  const signingInput = `${CLIENT_ID_PREFIX}.${payload}`;
+  const sig = b64url(createHmac("sha256", secret).update(signingInput).digest());
+  return `${signingInput}.${sig}`;
+}
+
+// Verify a client_id against any accepted secret; returns { redirect_uris } or null.
+function verifyClientId(clientId, secrets) {
+  const parts = String(clientId).split(".");
+  if (parts.length !== 3 || parts[0] !== CLIENT_ID_PREFIX) return null;
+  const [, payload, sig] = parts;
+  const signingInput = `${CLIENT_ID_PREFIX}.${payload}`;
+  const given = Buffer.from(sig);
+  let ok = false;
+  for (const secret of secrets) {
+    const expected = Buffer.from(b64url(createHmac("sha256", secret).update(signingInput).digest()));
+    if (expected.length === given.length && timingSafeEqual(expected, given)) {
+      ok = true;
+      break;
+    }
+  }
+  if (!ok) return null;
+  try {
+    const json = Buffer.from(payload.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8");
+    const uris = JSON.parse(json);
+    return Array.isArray(uris) ? { redirect_uris: uris } : null;
+  } catch {
+    return null;
+  }
+}
+
 function corsOk(res) {
   res.setHeader("Access-Control-Allow-Origin", "*");
   res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
@@ -81,6 +174,33 @@ export function mountOAuth(app, publicBase, opts = {}) {
   if (!opts.requireAuth) return;
   const base = publicBase.replace(/\/+$/, "");
 
+  // Resolve the client-registration signing secret(s) once at mount. Log which
+  // mode is active — durable vs. ephemeral — so a production deploy can be
+  // verified from the boot log without ever printing the secret itself.
+  const clientSecrets = resolveClientSecrets();
+  if (clientSecrets.ephemeral) {
+    console.warn(
+      "[oauth] MCP_OAUTH_HMAC_SECRET is NOT set — OAuth client registrations use a per-process " +
+        "ephemeral secret (see #3060). This is NOT just a survives-restart issue: with more than " +
+        "one replica, each process mints under its own key, so a client_id registered on one " +
+        "replica fails on another — authorize breaks intermittently, per request, with no restart " +
+        "involved, which diagnoses as an unrelated bug. Set the secret in production.",
+    );
+  } else {
+    const weak = clientSecrets.secrets.filter((s) => s.length < MIN_SECRET_LENGTH).length;
+    if (weak > 0) {
+      console.warn(
+        `[oauth] MCP_OAUTH_HMAC_SECRET has ${weak} key(s) shorter than ${MIN_SECRET_LENGTH} chars — ` +
+          "weak for an HMAC signing key; use a long random value (e.g. `openssl rand -hex 32`). " +
+          "Accepted anyway (still better than the ephemeral fallback).",
+      );
+    }
+    console.log(
+      `[oauth] client-registration secret configured (${clientSecrets.secrets.length} key(s)); ` +
+        "registrations are durable across restarts and replicas.",
+    );
+  }
+
   const asMetadata = {
     issuer: base,
     authorization_endpoint: `${base}/oauth/authorize`,
@@ -122,14 +242,28 @@ export function mountOAuth(app, publicBase, opts = {}) {
       res.status(400).json({ error: "invalid_client_metadata", error_description: "redirect_uris is required." });
       return;
     }
-    const clientId = randomUUID();
-    clients.set(clientId, { redirect_uris: redirectUris, created: Date.now() });
+    if (redirectUris.length > MAX_REDIRECT_URIS) {
+      res.status(400).json({
+        error: "invalid_client_metadata",
+        error_description: `At most ${MAX_REDIRECT_URIS} redirect_uris are allowed.`,
+      });
+      return;
+    }
+    const canonical = canonicalRedirectUris(redirectUris);
+    if (Buffer.byteLength(canonical, "utf8") > MAX_REDIRECT_URIS_BYTES) {
+      res.status(400).json({
+        error: "invalid_client_metadata",
+        error_description: `redirect_uris exceed the ${MAX_REDIRECT_URIS_BYTES}-byte limit.`,
+      });
+      return;
+    }
+    const clientId = signClientId(canonical, clientSecrets.secrets[0]);
     res.status(201).json({
       client_id: clientId,
       token_endpoint_auth_method: "none",
       grant_types: ["authorization_code"],
       response_types: ["code"],
-      redirect_uris: redirectUris,
+      redirect_uris: JSON.parse(canonical),
     });
   });
 
@@ -137,7 +271,7 @@ export function mountOAuth(app, publicBase, opts = {}) {
   app.get("/oauth/authorize", (req, res) => {
     sweep(authSessions);
     const { client_id, redirect_uri, state, code_challenge, code_challenge_method, response_type } = req.query;
-    const client = clients.get(String(client_id));
+    const client = verifyClientId(client_id, clientSecrets.secrets);
     if (!client || !client.redirect_uris.includes(String(redirect_uri))) {
       res.status(400).send("Unknown client or redirect_uri. Re-add the connector and try again.");
       return;

package/src/tools/deploy.js

@@ -1480,22 +1480,16 @@ function plugErrorMessage(status, code, msg, ctxFlags = {}) {
   return guidance ? `${base} — ${guidance}` : base;
 }
 
-// ── WORKAROUND(#311): inline multi-file re-plug guard + FETCHSOURCE handoff ───
-// WHAT IS BROKEN: the hosted (web) server materializes the uploaded multipart
-// parts into a source tarball SERVER-SIDE; for a MULTI-FILE runtime app
-// re-plugged INLINE it emits a non-gzip stream that dies at the build container's
+// ── Corrupt-archive FETCHSOURCE handoff (defense in depth) ───────────────────
+// Historically the hosted (web) server materialized uploaded multipart parts
+// into a source tarball SERVER-SIDE and, for a multi-file runtime app re-plugged
+// inline, could emit a non-gzip stream that died at the build container's
 // FETCHSOURCE with "gzip: stdin: not in gzip format / tar: Child returned status
-// 1" — raw, unactionable output that stranded a real user (natalys-grid). This
-// client never gzips/tars anything (it uploads each file as an octet-stream part
-// — see buildForm; byte-exactness proven in test), so the corruption is a
-// SERVER-SIDE defect downstream of this process; the disk-based CLI uploads the
-// same files and works.
-// WHAT WOULD LET THIS BE REMOVED: the API-side fix to tarball materialization for
-// this shape (tracked on #311). Until then, two defenses live here:
-//   1. detect the shape BEFORE upload (the gate in runPlug) and hand over the
-//      CLI commands with the real entity handle — never fail at the build.
-//   2. if a corrupt-archive build failure still slips through, rewrite the raw
-//      tar/gzip log to the same actionable handoff (archiveCorruptionSignature).
+// 1" — raw, unactionable output. The server-side defect (cloudgrid#2977) is now
+// fixed and verified live, and the pre-upload gate that refused that shape has
+// been lifted (#315). This handoff stays as defense in depth: if a corrupt-archive
+// build failure ever recurs, rewrite the raw tar/gzip log to an actionable CLI
+// handoff (via archiveCorruptionSignature) instead of surfacing it verbatim.
 
 // The "continue this exact entity from a terminal" CLI commands, with the real
 // handle substituted. Prefers grid/slug (what `pull` takes, human-readable);
@@ -1512,7 +1506,7 @@ export function cliContinueHandoff({ entityId, grid, slug } = {}) {
   );
 }
 
-// True when a build failure is the #311 corrupt-archive signature (a FETCHSOURCE
+// True when a build failure is the corrupt-archive signature (a FETCHSOURCE
 // gunzip/tar failure), as opposed to a genuine app build error the developer can
 // act on (a missing dependency, a syntax error) — those keep their real log tail.
 export function archiveCorruptionSignature(text) {
@@ -1750,40 +1744,6 @@ export async function runPlug(ctx, input, deps = {}) {
 
   const isEdit = typeof targetEntityId === "string" && targetEntityId.length > 0;
 
-  // ── WORKAROUND(#311): pre-upload gate for inline multi-file runtime RE-PLUG ──
-  // WHAT IS BROKEN: the hosted server's tarball materialization corrupts the
-  // source archive for a multi-file runtime app re-plugged INLINE — it emits a
-  // non-gzip stream that dies at the build container's FETCHSOURCE with
-  // "gzip: stdin: not in gzip format / tar: Child returned status 1". This client
-  // uploads byte-exact octet-stream parts (proven in test), so the defect is
-  // SERVER-SIDE, not here. It stranded a real user (natalys-grid) twice.
-  // WHAT WOULD LET THIS BE REMOVED: the API-side fix to tarball materialization
-  // for this shape (tracked on #311). Once hosted rebuilds a multi-file inline
-  // re-plug reliably, delete this gate — the inline path would just work.
-  // Until then, detect the shape BEFORE uploading and hand over the CLI, which
-  // uploads from disk and updates the SAME entity. NARROW by design so it never
-  // touches the cases that work today: hosted (web) only, RE-PLUG only (a real
-  // entity id in hand to substitute), MULTIPLE files, and a ROOT cloudgrid.yaml
-  // that DECLARES services (i.e. a runtime app, not a static bundle). A single
-  // HTML page, or a few small text files with no service manifest, are untouched
-  // and still plug inline. Multi-file runtime CREATES are also untouched (issue
-  // #48 aligned that bundle) — only the re-plug shape that failed twice is gated.
-  if (ctx.edition === "web" && isEdit && hasArtifacts && artifacts.length > 1) {
-    const manifest = detectSourceManifest(input);
-    if (manifest && manifest.services.length > 0) {
-      const slugForMsg = pickupData?.slug || (typeof slug === "string" && slug ? slug : null);
-      const gridForMsg = pickupData?.grid || (typeof grid === "string" && grid ? grid : null);
-      throw new Error(
-        `This is a multi-file runtime app (${artifacts.length} files + a cloudgrid.yaml declaring ` +
-          `services: ${manifest.services.join(", ")}) being re-plugged inline on the hosted server. ` +
-          "The hosted server can't reliably rebuild a multi-file app from an inline upload — the source " +
-          "archive arrives corrupt at build (#311), which is why the identical source plugs fine from the " +
-          "CLI. " +
-          cliContinueHandoff({ entityId: targetEntityId, grid: gridForMsg, slug: slugForMsg }),
-      );
-    }
-  }
-
   // An inspiration edit content-versions the FIRST uploaded artifact — when a
   // multi-file folder rides a re-plug, put the primary entry first so the edit
   // swaps the right file (index.html > any .html > everything else).
@@ -2127,18 +2087,17 @@ export async function runPlug(ctx, input, deps = {}) {
       data.status = "live";
       data.poll_url = undefined;
     } else if (verdict.status === "failed") {
-      // WORKAROUND(#311): a corrupt-archive FETCHSOURCE failure is unactionable
-      // as raw tar output — never surface it verbatim. WHAT IS BROKEN: the
-      // server-side tarball materialization corrupts the archive for a multi-file
-      // runtime re-plug; WHAT WOULD LET THIS BE REMOVED: the API-side fix (#311),
-      // after which no corrupt-archive verdict reaches here. Name the CLI path
-      // with the real handle instead (defense-in-depth behind the pre-upload gate
-      // above; this catches any shape the gate didn't). Genuine app build errors
-      // keep their real log tail — those the developer CAN act on.
+      // Defense in depth: a corrupt-archive FETCHSOURCE failure is unactionable
+      // as raw tar output — never surface it verbatim. The server-side defect
+      // that produced it (cloudgrid#2977) is fixed and the pre-upload gate has
+      // been lifted (#315), so no corrupt-archive verdict is expected here; if the
+      // class ever recurs, name the CLI path with the real handle instead of the
+      // raw log. Genuine app build errors keep their real log tail — those the
+      // developer CAN act on.
       if (archiveCorruptionSignature(`${verdict.error || ""}\n${verdict.logTail || ""}`)) {
         throw new Error(
           "The uploaded source could not be read by the build (its archive was corrupt) — the URL is NOT " +
-            "live. This is a known limitation of inline multi-file uploads on the hosted server (#311). " +
+            "live. " +
             cliContinueHandoff({ entityId: data.entity_id, grid: data.grid, slug: data.slug }),
         );
       }
@@ -2271,16 +2230,32 @@ export async function runPlug(ctx, input, deps = {}) {
     lines.push("The owner_token was re-minted for the reset expiry — replace the stored one.");
   }
 
+  // Point the user at their grid (the console) after a deploy that is LIVE — new
+  // or re-plug (#321). The app URL says where the app lives; the console line says
+  // where the grid lives, so the common follow-up interaction (an edit) does not
+  // end with a bare URL and no way back. The console root self-routes per account
+  // state (sign-in wall → their grid → onboarding); there is no per-grid page to
+  // link, so keep the root — a `/grids/<slug>` path 404s today.
+  //
+  // NOT on the building branch: the line says "view it live", and a still-building
+  // app is not live — emitting it two lines under "Do NOT tell the user it is live"
+  // would hand a model the word "live" next to a pending app. For an async runtime
+  // build the console line arrives when liveness is confirmed, in runCheckDeploy's
+  // success branch.
+  if (data.entity_id && !isBuilding) {
+    structured.console_url = CONSOLE_URL;
+    lines.push(`You can view it live in your grid along with all the apps you build here: ${CONSOLE_URL}`);
+  }
+
   // 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).
+  // entity's existing visibility untouched (don't re-ask on every re-plug) — this
+  // stays `!isEdit` deliberately, decoupled from the console line above.
   if (!isEdit && data.entity_id) {
     const current = typeof data.visibility === "string" ? data.visibility : null;
-    structured.console_url = CONSOLE_URL;
     if (current) structured.current_visibility = current;
     structured.visibility_options = VISIBILITY_OPTIONS.map((v) => ({ value: v, label: VISIBILITY_LABELS[v] }));
-    lines.push(`Manage all your apps in your grid: ${CONSOLE_URL}`);
     lines.push(
       `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: ${
         VISIBILITY_OPTIONS
@@ -2758,8 +2733,12 @@ export async function runCheckDeploy(ctx, { poll_url, grid } = {}) {
   const url = ctx.state.lastDrop?.url;
   if (verdict.status === "success") {
     return {
-      text: `Live${url ? `: ${url}` : ""} — the build finished. Give the user the URL.`,
-      structured: { status: "success", live: true, ...(url ? { url } : {}) },
+      // The "now live" moment for an async runtime build lands here, not in
+      // runPlug (which returned "building"). Point the user at their grid too
+      // (#321) — this is where liveness is confirmed, so "view it live" is true.
+      text: `Live${url ? `: ${url}` : ""} — the build finished. Give the user the URL.\n` +
+        `You can view it live in your grid along with all the apps you build here: ${CONSOLE_URL}`,
+      structured: { status: "success", live: true, ...(url ? { url } : {}), console_url: CONSOLE_URL },
     };
   }
   if (verdict.status === "failed") {
@@ -2769,16 +2748,15 @@ export async function runCheckDeploy(ctx, { poll_url, grid } = {}) {
     // the source zip (grid_get_app_source → source_download_url) or the
     // pull command that downloads + links the folder so the SAME entity
     // continues locally.
-    // WORKAROUND(#311): a corrupt-archive FETCHSOURCE failure is unactionable raw
-    // tar output — do NOT echo it. WHAT IS BROKEN: server-side tarball
-    // materialization corrupts the archive for a multi-file runtime re-plug;
-    // WHAT WOULD LET THIS BE REMOVED: the API-side fix (#311). Name the CLI
-    // continue-path with the real handle instead.
+    // Defense in depth: a corrupt-archive FETCHSOURCE failure is unactionable raw
+    // tar output — do NOT echo it. The server-side defect that produced it
+    // (cloudgrid#2977) is fixed and the pre-upload gate has been lifted (#315);
+    // if the class ever recurs, name the CLI continue-path with the real handle
+    // instead of the raw log.
     if (archiveCorruptionSignature(`${verdict.error || ""}\n${verdict.logTail || ""}`)) {
       return {
         text: "The uploaded source could not be read by the build (its archive was corrupt) — the URL is " +
-          "not live. This is a known limitation of inline multi-file uploads on the hosted server (#311); the " +
-          "project files are NOT lost — they are saved on the entity. " +
+          "not live. The project files are NOT lost — they are saved on the entity. " +
           cliContinueHandoff({ entityId, grid: gridSlug, slug: ctx.state.lastDrop?.slug }),
         structured: {
           status: "failed",

package/src/tools/register.js

@@ -845,6 +845,7 @@ export function registerTools(server, ctx) {
         status: z.string().describe("The build status: success | failed | building | queued | unknown."),
         live: z.boolean().describe("True only when the build finished successfully and the URL serves."),
         url: z.string().optional().describe("The live URL, when known."),
+        console_url: z.string().optional().describe("On success: URL to view the app live in the grid alongside all the user's apps."),
         error: z.string().optional().describe("User-language failure reason, when the build failed."),
         build_log_tail: z.string().optional().describe("Sanitized tail of the Cloud Build log (the real error), when the build failed."),
         suggested_fix: z.string().optional().describe("A suggested fix for the failure, when the platform provides one."),
@@ -943,7 +944,7 @@ export function registerTools(server, ctx) {
           .object({
             active_grid: z.string().nullable().describe("The user's active grid/org slug, or null."),
             signed_in: z.boolean().describe("Whether the current session is signed in."),
-            email: z.string().optional().describe("The signed-in user's email, when available."),
+            email: z.string().optional().describe("The signed-in user's email — the CloudGrid account this session is authenticated as. Present whenever signed_in is true and the session token carries an email claim (the normal case). Absent only if signed_in is false, or on the rare token that lacks the claim; the identity line in this tool's text content states which case applies. Use this to answer 'which account/user am I?'."),
             session_expired: z.boolean().optional().describe("True when credentials exist but the JWT has expired. Run grid_login to sign in again."),
             identity_changed: z.boolean().optional().describe("True when the session's identity changed via a different transport Bearer. Session state was reset."),
             update_available: z
@@ -1007,8 +1008,22 @@ export function registerTools(server, ctx) {
       const wfLines = workflows.length
         ? workflows.map((w) => `  - ${w.name}: ${w.when || w.summary}`).join("\n")
         : "  (none available)";
+      // Identity banner — first line of the text channel, because the account
+      // this session is signed in as is only otherwise carried in
+      // structuredContent.context, which many clients/models never surface. A
+      // hosted assistant asked "which account am I?" was concluding no tool
+      // exposes it while the answer sat in structured output it had already
+      // received (#317). Stating it in the text the model actually reads makes
+      // "who am I" answerable without the CLI (whose separate session can point
+      // at a different account entirely).
+      const gridSuffix = activeGrid ? ` (active grid: ${activeGrid})` : "";
+      const identityLine = signedIn
+        ? signedInEmail
+          ? `You are signed in to CloudGrid as ${signedInEmail}${gridSuffix}. If the user asks which CloudGrid account, user, or email they are connected to, that is the answer.`
+          : `You are signed in to CloudGrid${gridSuffix}, but this session's token carries no email claim, so the account address is not available here. Do not guess it from grid memberships or the CLI (its session may be a different account).`
+        : `You are not signed in to CloudGrid. Run grid_login to sign in.`;
       let text =
-        `${PLAYBOOK}\n\nAvailable workflows:\n${wfLines}\n\n` +
+        `${identityLine}\n\n${PLAYBOOK}\n\nAvailable workflows:\n${wfLines}\n\n` +
         `Next: match the intent to a workflow and call grid_get_template({kind:"workflow", name}).` +
         (stale ? `\n\n${stale}` : "");
       if (sessionExpired) {