gogcli-mcp-docs 2.20.0 → 2.21.1

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
-    "version": "2.20.0"
+    "version": "2.21.1"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "gogcli (Docs)",
       "source": "./",
       "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
-      "version": "2.20.0",
+      "version": "2.21.1",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gogcli-mcp-docs",
   "displayName": "gogcli (Docs)",
-  "version": "2.20.0",
+  "version": "2.21.1",
   "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
   "author": {
     "name": "Chris Hall",

package/dist/index.js

@@ -4264,8 +4264,8 @@ var require_core = __commonJS({
             return this;
           }
           case "object": {
-            const cacheKey = schemaKeyRef;
-            this._cache.delete(cacheKey);
+            const cacheKey2 = schemaKeyRef;
+            this._cache.delete(cacheKey2);
             let id = schemaKeyRef[this.opts.schemaId];
             if (id) {
               id = (0, resolve_1.normalizeId)(id);
@@ -23068,17 +23068,33 @@ function normalizeObjectSchema(schema) {
   }
   return void 0;
 }
+function getDotPath(path) {
+  if (path.length === 0) {
+    return "object root";
+  }
+  return path.reduce((acc, seg, index) => {
+    if (index === 0) {
+      return String(seg);
+    }
+    if (typeof seg === "number") {
+      return `${acc}[${seg}]`;
+    }
+    return `${acc}.${seg}`;
+  }, "");
+}
 function getParseErrorMessage(error51) {
   if (error51 && typeof error51 === "object") {
+    if ("issues" in error51 && Array.isArray(error51.issues) && error51.issues.length > 0) {
+      return error51.issues.map((i) => {
+        if (!i.path?.length) {
+          return i.message;
+        }
+        return `${i.message} at ${getDotPath(i.path)}`;
+      }).join("\n");
+    }
     if ("message" in error51 && typeof error51.message === "string") {
       return error51.message;
     }
-    if ("issues" in error51 && Array.isArray(error51.issues) && error51.issues.length > 0) {
-      const firstIssue = error51.issues[0];
-      if (firstIssue && typeof firstIssue === "object" && "message" in firstIssue) {
-        return String(firstIssue.message);
-      }
-    }
     try {
       return JSON.stringify(error51);
     } catch {
@@ -29693,16 +29709,7 @@ var Server = class extends Protocol {
     if (!methodSchema) {
       throw new Error("Schema is missing a method literal");
     }
-    let methodValue;
-    if (isZ4Schema(methodSchema)) {
-      const v4Schema = methodSchema;
-      const v4Def = v4Schema._zod?.def;
-      methodValue = v4Def?.value ?? v4Schema.value;
-    } else {
-      const v3Schema = methodSchema;
-      const legacyDef = v3Schema._def;
-      methodValue = legacyDef?.value ?? v3Schema.value;
-    }
+    const methodValue = getLiteralValue(methodSchema);
     if (typeof methodValue !== "string") {
       throw new Error("Schema method literal must be a string");
     }
@@ -30890,8 +30897,17 @@ var EMPTY_COMPLETION_RESULT = {
 import process3 from "node:process";
 
 // ../../node_modules/@modelcontextprotocol/sdk/dist/esm/shared/stdio.js
+var STDIO_DEFAULT_MAX_BUFFER_SIZE = 10 * 1024 * 1024;
 var ReadBuffer = class {
+  constructor(options) {
+    this._maxBufferSize = options?.maxBufferSize ?? STDIO_DEFAULT_MAX_BUFFER_SIZE;
+  }
   append(chunk) {
+    const newSize = (this._buffer?.length ?? 0) + chunk.length;
+    if (newSize > this._maxBufferSize) {
+      this.clear();
+      throw new Error(`ReadBuffer exceeded maximum size of ${this._maxBufferSize} bytes`);
+    }
     this._buffer = this._buffer ? Buffer.concat([this._buffer, chunk]) : chunk;
   }
   readMessage() {
@@ -30919,18 +30935,24 @@ function serializeMessage(message) {
 
 // ../../node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
 var StdioServerTransport = class {
-  constructor(_stdin = process3.stdin, _stdout = process3.stdout) {
+  constructor(_stdin = process3.stdin, _stdout = process3.stdout, options) {
     this._stdin = _stdin;
     this._stdout = _stdout;
-    this._readBuffer = new ReadBuffer();
     this._started = false;
     this._ondata = (chunk) => {
-      this._readBuffer.append(chunk);
-      this.processReadBuffer();
+      try {
+        this._readBuffer.append(chunk);
+        this.processReadBuffer();
+      } catch (error51) {
+        this.onerror?.(error51);
+        this.close().catch(() => {
+        });
+      }
     };
     this._onerror = (error51) => {
       this.onerror?.(error51);
     };
+    this._readBuffer = new ReadBuffer({ maxBufferSize: options?.maxBufferSize });
   }
   /**
    * Starts listening for messages on stdin.
@@ -31118,6 +31140,21 @@ import { delimiter, join } from "node:path";
 function isGogFileArg(arg) {
   return typeof arg !== "string";
 }
+var RUNNER_TRANSPORT_BRAND = /* @__PURE__ */ Symbol.for("gogcli.RunnerTransportError");
+var RunnerTransportError = class extends Error {
+  kind;
+  status;
+  constructor(message, kind, status) {
+    super(message);
+    this.name = "RunnerTransportError";
+    this.kind = kind;
+    this.status = status;
+    Object.defineProperty(this, RUNNER_TRANSPORT_BRAND, { value: true });
+  }
+};
+function isRunnerTransportError(err) {
+  return err instanceof Error && err[RUNNER_TRANSPORT_BRAND] === true;
+}
 var runExecutor = new AsyncLocalStorage();
 var defaultExecutor;
 function setDefaultGogExecutor(executor) {
@@ -31298,7 +31335,11 @@ async function run(args, options = {}) {
     }
     return redact(output);
   } catch (err) {
-    throw new Error(redact(err instanceof Error ? err.message : String(err)));
+    const message = redact(err instanceof Error ? err.message : String(err));
+    if (isRunnerTransportError(err)) {
+      throw new RunnerTransportError(message, err.kind, err.status);
+    }
+    throw new Error(message);
   }
 }
 
@@ -31562,7 +31603,9 @@ function registerRunTool(server, options) {
 function errorText(err) {
   return err instanceof Error ? `Error: ${err.message}` : String(err);
 }
-var AUTH_ERROR_PATTERN = /\b(401|unauthorized|token.*(expired|revoked)|invalid_grant)\b/i;
+var DEFINITE_AUTH_PATTERN = /\b(?:unauthorized|invalid_grant)\b|\b(?:error|status|code|http|responded|response)["']?[\s:=(,]{0,4}401\b/i;
+var STALE_TOKEN_PATTERN = /\b(?:access[ _-]?)?token\b[^.;\n]{0,40}\b(?:has\s+)?(?:been\s+)?(?:expired|revoked)\b|\b(?:expired|revoked)\s+(?:access[ _-]?)?token\b/i;
+var AUTH_ERROR_PATTERN = new RegExp(`${DEFINITE_AUTH_PATTERN.source}|${STALE_TOKEN_PATTERN.source}`, "i");
 var INVALID_GRANT_PATTERN = /invalid_grant|token has been expired or revoked/i;
 var TRANSIENT_ERROR_PATTERN = /\b429\b|\b5\d\d\b|\bquota\b|rateLimit|\bDEADLINE_EXCEEDED\b/i;
 var GRID_LIMIT_ERROR_PATTERN = /exceeds grid limits/i;
@@ -31570,6 +31613,14 @@ var AUTH_HINT = "\n\nAuthentication may have expired. Use gog_auth_add to re-aut
 var INVALID_GRANT_HINT = '\n\nThe stored refresh token was rejected (invalid_grant): it has expired or been revoked, so the whole account is signed out and re-authorization is required. The most common cause is the 7-day refresh-token limit Google applies to OAuth apps whose consent screen is still in "Testing" mode. Re-authorize with gog_auth_add (opens a browser) or gog_auth_add_url + gog_auth_add_complete (remote/headless). To stop this recurring, publish the OAuth consent screen to "In production" in the Google Cloud project that owns the OAuth client. Ask the user if they would like to re-authenticate.';
 var TRANSIENT_HINT = "\n\nThis error is often transient. Retry the same call before trying a different approach (do not fall back to smaller writes or row-by-row operations).";
 var GRID_LIMIT_HINT = "\n\nThe target range is outside the sheet's current grid. Add the missing rows or columns first with gog_sheets_insert (dimension: rows or cols), then retry the write.";
+var RUNNER_TRANSPORT_AUTH_HINT = "\n\nThis is the CONNECTOR's own transport auth failing, not your Google sign-in. The gog-runner backend rejected the bearer token this server sent, so the request never reached gog and no Google credential was checked \u2014 the Google account is not the problem and re-authorizing it cannot fix this. An operator must make the Worker secret GOG_RUNNER_KEY equal RUNNER_KEY on the Fly app (wrangler secret put GOG_RUNNER_KEY / fly secrets set RUNNER_KEY), then retry.";
+var RUNNER_TRANSPORT_HINTS = {
+  "transport-auth": RUNNER_TRANSPORT_AUTH_HINT,
+  // The request itself was malformed, so the runner will refuse it identically
+  // every time. Nothing to advise beyond the message the runner already gave.
+  "transport-request": "",
+  "transport-retryable": TRANSIENT_HINT
+};
 function formatAccountList(raw) {
   try {
     const parsed = JSON.parse(raw);
@@ -31582,11 +31633,12 @@ function formatAccountList(raw) {
 }
 async function diagnose(err) {
   const errText = errorText(err);
+  const transportHint = isRunnerTransportError(err) ? RUNNER_TRANSPORT_HINTS[err.kind] : void 0;
   const isInvalidGrant = INVALID_GRANT_PATTERN.test(errText);
-  const isAuthError = AUTH_ERROR_PATTERN.test(errText);
-  const isTransientError = !isAuthError && TRANSIENT_ERROR_PATTERN.test(errText);
+  const isTransientError = !DEFINITE_AUTH_PATTERN.test(errText) && TRANSIENT_ERROR_PATTERN.test(errText);
+  const isAuthError = !isTransientError && AUTH_ERROR_PATTERN.test(errText);
   const isGridLimitError = GRID_LIMIT_ERROR_PATTERN.test(errText);
-  const hint = isInvalidGrant ? INVALID_GRANT_HINT : isAuthError ? AUTH_HINT : isTransientError ? TRANSIENT_HINT : isGridLimitError ? GRID_LIMIT_HINT : "";
+  const hint = transportHint ?? (isInvalidGrant ? INVALID_GRANT_HINT : isAuthError ? AUTH_HINT : isTransientError ? TRANSIENT_HINT : isGridLimitError ? GRID_LIMIT_HINT : "");
   try {
     const accounts = formatAccountList(await run(["auth", "list"]));
     return errorResult(`${errText}
@@ -31651,7 +31703,7 @@ function formatAuthHealth(raw, now) {
 function registerAuthToolsWith(server, defaultServices) {
   const servicesDescribe = `Services to authorize: "all" or comma-separated list (e.g. "sheets,gmail,calendar"). Default: "${defaultServices}". Prefer the narrowest set you need \u2014 requesting a service whose Google API is not enabled on the OAuth client's project makes Google reject the WHOLE request with invalid_scope.`;
   server.registerTool("gog_auth_list", {
-    description: "List all Google accounts stored in gogcli. Use this to check which accounts are configured and available.",
+    description: "List the Google accounts stored in gogcli, with their scopes. This reads local configuration only \u2014 it does not contact Google and does NOT tell you whether an account still works: a signed-out account whose refresh token expired or was revoked is listed here exactly like a healthy one, scopes and all. Use gog_auth_health to check whether an account can actually authenticate.",
     annotations: { readOnlyHint: true },
     inputSchema: {}
   }, async () => {
@@ -31880,59 +31932,375 @@ var failIfNotEmptyParam = external_exports.boolean().optional().describe(
 );
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "2.20.0" : "0.0.0";
+var VERSION = true ? "2.21.1" : "0.0.0";
+
+// ../gogcli-mcp/src/auth-log.ts
+var FAILURES = /* @__PURE__ */ new Set([
+  "token.mint-failed",
+  "grant.dead",
+  "replay.failed",
+  "runner.auth-failed"
+]);
+var PREFIX = "gog-auth ";
+var TAG_CHARS = 12;
+function credentialTag(cacheKeyHash) {
+  return cacheKeyHash.slice(0, TAG_CHARS);
+}
+function logAuthTransition(event, context) {
+  const record2 = JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString(), event, ...context });
+  const write = FAILURES.has(event) ? console.error : console.warn;
+  write(PREFIX + redactSecrets2(record2));
+}
+
+// ../gogcli-mcp/src/google-token.ts
+var TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+var EXPIRY_MARGIN_MS = 12e4;
+var cache = /* @__PURE__ */ new Map();
+var inFlight = /* @__PURE__ */ new Map();
+async function cacheKey(refreshToken, clientId) {
+  const data = new TextEncoder().encode(`${clientId}\0${refreshToken}`);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function makeAccessTokenSource(env) {
+  const direct = readEnvVar("GOG_ACCESS_TOKEN", { env });
+  if (direct) return async () => direct;
+  const refreshToken = readEnvVar("GOG_REFRESH_TOKEN", { env });
+  if (!refreshToken) return void 0;
+  const clientId = readEnvVar("GOG_CLIENT_ID", { env });
+  const clientSecret = readEnvVar("GOG_CLIENT_SECRET", { env });
+  if (!clientId || !clientSecret) {
+    const missing = [!clientId && "GOG_CLIENT_ID", !clientSecret && "GOG_CLIENT_SECRET"].filter(Boolean).join(" and ");
+    return async () => {
+      throw new Error(
+        `GOG_REFRESH_TOKEN is set but ${missing} is not, so no access token can be minted. Set the OAuth client alongside the refresh token, or unset GOG_REFRESH_TOKEN to use the backend\u2019s own identity.`
+      );
+    };
+  }
+  let keyPromise;
+  const key = () => keyPromise ??= cacheKey(refreshToken, clientId);
+  const logCacheHits = parseBoolEnv("GOG_AUTH_LOG_CACHE_HITS", { env });
+  const read = async () => {
+    const k = await key();
+    const hit = cache.get(k);
+    if (hit && hit.expiresAt - EXPIRY_MARGIN_MS > Date.now()) {
+      if (logCacheHits) logAuthTransition("token.cache-hit", { credential: credentialTag(k) });
+      return hit.accessToken;
+    }
+    let pending = inFlight.get(k);
+    if (!pending) {
+      pending = exchange(refreshToken, clientId, clientSecret).then((minted2) => {
+        cache.set(k, minted2);
+        logAuthTransition("token.minted", {
+          credential: credentialTag(k),
+          reason: `valid for ${Math.round((minted2.expiresAt - Date.now()) / 1e3)}s`
+        });
+        return minted2;
+      }).catch((err) => {
+        logAuthTransition(err.grantDead ? "grant.dead" : "token.mint-failed", {
+          credential: credentialTag(k),
+          reason: err.message
+        });
+        throw err;
+      }).finally(() => inFlight.delete(k));
+      inFlight.set(k, pending);
+    }
+    const minted = await pending;
+    return minted.accessToken;
+  };
+  const invalidate = async (rejected) => {
+    const k = await key();
+    const hit = cache.get(k);
+    if (!hit || hit.accessToken !== rejected) {
+      logAuthTransition("token.evict-noop", {
+        credential: credentialTag(k),
+        reason: hit ? "a concurrent caller had already replaced this credential\u2019s token" : "no token was cached for this credential"
+      });
+      return false;
+    }
+    cache.delete(k);
+    logAuthTransition("token.evicted", {
+      credential: credentialTag(k),
+      reason: "Google rejected this access token; the next read will mint a new one"
+    });
+    return true;
+  };
+  return Object.assign(read, {
+    invalidate,
+    credentialId: async () => credentialTag(await key())
+  });
+}
+var TokenExchangeError = class extends Error {
+  /**
+   * The REFRESH token is dead (Google's `invalid_grant`), not merely the access
+   * token. Carried as a flag rather than re-read from the message, because
+   * inferring the author of a failure from prose several authors can produce is
+   * precisely the mistake this branch exists to undo. `instanceof` is safe: the
+   * class is thrown and caught inside this one module.
+   */
+  grantDead;
+  constructor(message, grantDead) {
+    super(message);
+    this.grantDead = grantDead;
+  }
+};
+async function exchange(refreshToken, clientId, clientSecret) {
+  let res;
+  try {
+    res = await fetch(TOKEN_ENDPOINT, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+        client_id: clientId,
+        client_secret: clientSecret
+      }).toString()
+    });
+  } catch (err) {
+    throw new TokenExchangeError(
+      `the Google token exchange could not be reached: ${err instanceof Error ? err.message : String(err)}`,
+      false
+    );
+  }
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    if (body.error === "invalid_grant") {
+      throw new TokenExchangeError(
+        'the stored refresh token was rejected (invalid_grant): it has expired or been revoked, so this account must be re-authorized (commonly the 7-day limit on OAuth consent screens still in "Testing" mode). Re-enrol with gog_auth_add_url + gog_auth_add_complete and store the new refresh token.',
+        true
+      );
+    }
+    throw new TokenExchangeError(
+      `the access token could not be refreshed (HTTP ${res.status}${body.error ? `, ${body.error}` : ""})`,
+      false
+    );
+  }
+  if (!body.access_token) {
+    throw new TokenExchangeError(
+      "the access token could not be refreshed: Google returned no access_token",
+      false
+    );
+  }
+  const expiresInMs = (body.expires_in ?? 3600) * 1e3;
+  return { accessToken: body.access_token, expiresAt: Date.now() + expiresInMs };
+}
 
 // ../gogcli-mcp/src/connector-runtime.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEADLINE_GRACE_MS = 5e3;
+var MIN_REPLAY_BUDGET_MS = 1e3;
 var RUNNER_GOG_FAILED = 422;
 var RUNNER_DRAINING = 503;
+var RUNNER_BAD_REQUEST = 400;
+var RUNNER_BAD_KEY = 401;
+var GogFailedError = class extends Error {
+  /** gog's stderr alone, with no echoed argv mixed in. */
+  stderr;
+  constructor(message, stderr) {
+    super(message);
+    this.stderr = stderr;
+  }
+};
+var GOOGLE_TOKEN_REJECTED_PATTERN = /Google API error \(401\b|invalid[ _]authentication[ _]credentials|\bACCESS_TOKEN_EXPIRED\b|\binvalid_token\b/i;
+var REFRESH_TOKEN_DEAD_PATTERN = /\binvalid_grant\b/i;
+var READ_ONLY_SUBCOMMANDS = /* @__PURE__ */ new Set([
+  "cat",
+  "describe",
+  "get",
+  "info",
+  "list",
+  "list-slides",
+  "ls",
+  "metadata",
+  "read-slide",
+  "search",
+  "services",
+  "status",
+  "structure"
+]);
+function gogTarget(args) {
+  const words = args.filter((arg) => typeof arg === "string");
+  let service;
+  for (let i = 0; i < words.length; i += 1) {
+    const word = words[i];
+    if (word.startsWith("-")) {
+      if (word === "--account") i += 1;
+      continue;
+    }
+    if (service === void 0) {
+      service = word;
+      continue;
+    }
+    return { service, subcommand: word };
+  }
+  return { service };
+}
+async function remintAfterGoogleRejection(err, used, args, readAccessToken, deadlineAt) {
+  if (!(err instanceof GogFailedError)) return void 0;
+  const grantDead = REFRESH_TOKEN_DEAD_PATTERN.test(err.stderr);
+  if (!grantDead && !GOOGLE_TOKEN_REJECTED_PATTERN.test(err.stderr)) return void 0;
+  const { service, subcommand } = gogTarget(args);
+  const credential = await readAccessToken?.credentialId?.();
+  const where = { credential, service };
+  if (grantDead) {
+    logAuthTransition("grant.dead", {
+      ...where,
+      reason: "gog reported invalid_grant: the stored refresh token is dead, so no token can be minted and this account must be re-authorized"
+    });
+    return void 0;
+  }
+  if (!used) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: "no access token was supplied with the call, so gog acted as the backend volume\u2019s own identity"
+    });
+    return void 0;
+  }
+  if (!readAccessToken?.invalidate) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: "this token source cannot mint a replacement, so a replay would resend the rejected token"
+    });
+    return void 0;
+  }
+  const evicted = await readAccessToken.invalidate(used);
+  if (subcommand === void 0 || !READ_ONLY_SUBCOMMANDS.has(subcommand)) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: `not replayable: '${subcommand ?? "(none)"}' is not a known read-only subcommand and a write could double-apply`
+    });
+    return void 0;
+  }
+  if (!evicted) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: "the rejected token was already superseded, so the cache holds the token a replay would send"
+    });
+    return void 0;
+  }
+  const fresh = await readAccessToken();
+  if (!fresh) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: "the token source produced no token after eviction; replaying without one would act as the backend"
+    });
+    return void 0;
+  }
+  const budgetMs = deadlineAt - Date.now();
+  if (budgetMs < MIN_REPLAY_BUDGET_MS) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: `only ${budgetMs}ms of the call\u2019s deadline remained, so a replay could only time out; the rejected token was evicted, so the next call mints a fresh one`
+    });
+    return void 0;
+  }
+  return { token: fresh, budgetMs, invalidate: readAccessToken.invalidate, ...where };
+}
 function makeFlyExecutor(endpoint, key, readAccessToken) {
   return async (args, opts) => {
     const deadlineMs = (opts?.timeout ?? DEFAULT_TIMEOUT_MS) + DEADLINE_GRACE_MS;
-    const accessToken = readAccessToken?.();
-    let res;
+    const accessToken = await readAccessToken?.();
+    const deadlineAt = Date.now() + deadlineMs;
     try {
-      res = await fetch(endpoint + "/run", {
-        method: "POST",
-        headers: {
-          Authorization: "Bearer " + key,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify(accessToken ? { args, accessToken } : { args }),
-        signal: AbortSignal.timeout(deadlineMs)
-      });
+      return await attempt(endpoint, key, args, accessToken, deadlineMs);
     } catch (err) {
-      const name = err instanceof Error ? err.name : "";
-      if (name === "TimeoutError" || name === "AbortError") {
-        throw new Error(
-          `gog-runner did not respond within ${deadlineMs}ms (${endpoint}) \u2014 the Fly backend may be cold or wedged`
-        );
+      const replay = await remintAfterGoogleRejection(
+        err,
+        accessToken,
+        args,
+        readAccessToken,
+        deadlineAt
+      );
+      if (replay === void 0) throw err;
+      const where = { credential: replay.credential, service: replay.service, endpoint };
+      logAuthTransition("replay.attempted", {
+        ...where,
+        reason: "Google rejected the access token; replaying this read once with a freshly minted one"
+      });
+      try {
+        const stdout = await attempt(endpoint, key, args, replay.token, replay.budgetMs);
+        logAuthTransition("replay.succeeded", where);
+        return stdout;
+      } catch (replayErr) {
+        logAuthTransition("replay.failed", { ...where, reason: String(replayErr) });
+        if (replayErr instanceof GogFailedError && GOOGLE_TOKEN_REJECTED_PATTERN.test(replayErr.stderr)) {
+          await replay.invalidate(replay.token);
+        }
+        throw replayErr;
       }
-      throw err;
     }
-    if (!res.ok) {
-      const body = await res.json().catch(() => null);
-      const detail = body && typeof body.error === "string" ? body.stderr && body.stderr.trim() && body.stderr.trim() !== body.error.trim() ? `${body.error}
+  };
+}
+async function attempt(endpoint, key, args, accessToken, deadlineMs) {
+  let res;
+  try {
+    res = await fetch(endpoint + "/run", {
+      method: "POST",
+      headers: {
+        Authorization: "Bearer " + key,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(accessToken ? { args, accessToken } : { args }),
+      signal: AbortSignal.timeout(deadlineMs)
+    });
+  } catch (err) {
+    const name = err instanceof Error ? err.name : "";
+    if (name === "TimeoutError" || name === "AbortError") {
+      throw new RunnerTransportError(
+        `gog-runner did not respond within ${deadlineMs}ms (${endpoint}) \u2014 the Fly backend may be cold or wedged`,
+        "transport-retryable"
+      );
+    }
+    throw err;
+  }
+  if (!res.ok) {
+    const body = await res.json().catch(() => null);
+    const detail = body && typeof body.error === "string" ? body.stderr && body.stderr.trim() && body.stderr.trim() !== body.error.trim() ? `${body.error}
 ${body.stderr}` : body.error : "";
-      if (res.status === RUNNER_GOG_FAILED) {
-        throw new Error(detail || "gog failed on the runner (no detail supplied)");
-      }
-      if (res.status === RUNNER_DRAINING || body?.retryable === true) {
-        throw new Error(
-          `gog-runner is restarting; retry this call.${detail ? ` ${detail}` : ""}`
-        );
-      }
-      if (detail) {
-        throw new Error(detail);
-      }
-      throw new Error(
-        `gog-runner HTTP ${res.status}: the response did not come from the runner, so the request never reached gog. The backend Machine was most likely starting or shutting down \u2014 this is transient, retry the same call.`
+    if (res.status === RUNNER_GOG_FAILED) {
+      throw new GogFailedError(
+        detail || "gog failed on the runner (no detail supplied)",
+        typeof body?.stderr === "string" ? body.stderr : ""
       );
     }
-    const { stdout } = await res.json();
-    return stdout;
-  };
+    if (res.status === RUNNER_BAD_KEY) {
+      logAuthTransition("runner.auth-failed", {
+        service: gogTarget(args).service,
+        endpoint,
+        reason: "the gog-runner rejected the connector\u2019s bearer token, so gog never ran and no Google credential was read; GOG_RUNNER_KEY does not match the Fly app\u2019s RUNNER_KEY"
+      });
+      throw new RunnerTransportError(
+        "gog-runner rejected the connector's bearer token, so the request never reached gog and no Google credential was involved. The Worker secret GOG_RUNNER_KEY no longer matches RUNNER_KEY on the Fly app; set them to the same value (wrangler secret put GOG_RUNNER_KEY / fly secrets set RUNNER_KEY) and retry.",
+        "transport-auth",
+        res.status
+      );
+    }
+    if (res.status === RUNNER_BAD_REQUEST) {
+      throw new RunnerTransportError(
+        detail || "gog-runner rejected the request (no detail supplied)",
+        "transport-request",
+        res.status
+      );
+    }
+    if (res.status === RUNNER_DRAINING || body?.retryable === true) {
+      throw new RunnerTransportError(
+        `gog-runner is restarting; retry this call.${detail ? ` ${detail}` : ""}`,
+        "transport-retryable",
+        res.status
+      );
+    }
+    if (detail) {
+      throw new Error(detail);
+    }
+    throw new RunnerTransportError(
+      `gog-runner HTTP ${res.status}: the response did not come from the runner, so the request never reached gog. The backend Machine was most likely starting or shutting down \u2014 this is transient, retry the same call.`,
+      "transport-retryable",
+      res.status
+    );
+  }
+  const { stdout } = await res.json();
+  return stdout;
 }
 
 // ../gogcli-mcp/src/remote-runner.ts
@@ -31941,7 +32309,7 @@ function useRemoteGogRunner(env = process.env) {
   const key = readEnvVar("GOG_RUNNER_KEY", { env });
   if (!endpoint || !key) return false;
   setDefaultGogExecutor(
-    makeFlyExecutor(endpoint.replace(/\/+$/, ""), key, () => readEnvVar("GOG_ACCESS_TOKEN", { env }))
+    makeFlyExecutor(endpoint.replace(/\/+$/, ""), key, makeAccessTokenSource(env))
   );
   return true;
 }

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-docs",
   "display_name": "gogcli (Docs)",
-  "version": "2.20.0",
+  "version": "2.21.1",
   "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
   "author": {
     "name": "Chris Hall",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-docs",
-  "version": "2.20.0",
+  "version": "2.21.1",
   "mcpName": "io.github.chrischall/gogcli-mcp-docs",
   "description": "Extended Google Docs MCP server via gogcli — all base tools plus full Docs support",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -24,8 +24,8 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.13.3",
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@chrischall/mcp-utils": "^0.14.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.4.3"
   },
   "license": "MIT",

package/server.json

@@ -7,12 +7,12 @@
     "source": "github",
     "subfolder": "packages/gogcli-mcp-docs"
   },
-  "version": "2.20.0",
+  "version": "2.21.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "gogcli-mcp-docs",
-      "version": "2.20.0",
+      "version": "2.21.1",
       "transport": {
         "type": "stdio"
       },