gogcli-mcp 2.29.1 → 3.0.0

package/src/tools/slides.ts

@@ -1,4 +1,4 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { accountParam, runOrDiagnose, registerRunTool } from './utils.js';
 
@@ -6,13 +6,13 @@ export function registerSlidesTools(server: McpServer): void {
   server.registerTool('gog_slides_export', {
     description: 'Export a Google Slides presentation to a local file (pdf or pptx).',
     annotations: { readOnlyHint: true },
-    inputSchema: {
+    inputSchema: z.object({
       presentationId: z.string().describe('Presentation ID'),
       out: z.string().optional().describe('Output file path'),
       format: z.enum(['pdf', 'pptx']).optional().describe('Export format (default: pptx)'),
       overwrite: z.boolean().optional().describe('Overwrite the output file if it already exists (gog refuses otherwise)'),
       account: accountParam,
-    },
+    }),
   }, async ({ presentationId, out, format, overwrite, account }) => {
     const args = ['slides', 'export', presentationId];
     if (out) args.push(`--out=${out}`);
@@ -24,22 +24,22 @@ export function registerSlidesTools(server: McpServer): void {
   server.registerTool('gog_slides_info', {
     description: 'Get metadata for a Google Slides presentation (title, ID, slide count, etc.).',
     annotations: { readOnlyHint: true },
-    inputSchema: {
+    inputSchema: z.object({
       presentationId: z.string().describe('Presentation ID'),
       account: accountParam,
-    },
+    }),
   }, async ({ presentationId, account }) => {
     return runOrDiagnose(['slides', 'info', presentationId], { account });
   });
 
   server.registerTool('gog_slides_create', {
     description: 'Create a new Google Slides presentation, optionally in a folder or copying from a template.',
-    inputSchema: {
+    inputSchema: z.object({
       title: z.string().describe('Presentation title'),
       parent: z.string().optional().describe('Destination folder ID'),
       template: z.string().optional().describe('Template presentation ID to copy from'),
       account: accountParam,
-    },
+    }),
   }, async ({ title, parent, template, account }) => {
     const args = ['slides', 'create', title];
     if (parent) args.push(`--parent=${parent}`);
@@ -49,12 +49,12 @@ export function registerSlidesTools(server: McpServer): void {
 
   server.registerTool('gog_slides_copy', {
     description: 'Copy a Google Slides presentation to a new presentation with the given title.',
-    inputSchema: {
+    inputSchema: z.object({
       presentationId: z.string().describe('Presentation ID to copy'),
       title: z.string().describe('Title for the new copy'),
       parent: z.string().optional().describe('Destination folder ID'),
       account: accountParam,
-    },
+    }),
   }, async ({ presentationId, title, parent, account }) => {
     const args = ['slides', 'copy', presentationId, title];
     if (parent) args.push(`--parent=${parent}`);
@@ -64,10 +64,10 @@ export function registerSlidesTools(server: McpServer): void {
   server.registerTool('gog_slides_list_slides', {
     description: 'List slides in a Google Slides presentation.',
     annotations: { readOnlyHint: true },
-    inputSchema: {
+    inputSchema: z.object({
       presentationId: z.string().describe('Presentation ID'),
       account: accountParam,
-    },
+    }),
   }, async ({ presentationId, account }) => {
     return runOrDiagnose(['slides', 'list-slides', presentationId], { account });
   });
@@ -75,12 +75,12 @@ export function registerSlidesTools(server: McpServer): void {
   server.registerTool('gog_slides_read_slide', {
     description: 'Read the content of a slide (text, shapes, speaker notes). Set detail=true to also include normalized element geometry, styled text runs, paragraphs, table-cell content, and image source URLs.',
     annotations: { readOnlyHint: true },
-    inputSchema: {
+    inputSchema: z.object({
       presentationId: z.string().describe('Presentation ID'),
       slideId: z.string().describe('Slide ID to read'),
       detail: z.boolean().optional().describe('Include normalized element geometry, styled text runs, paragraphs, table-cell content, and image source URLs'),
       account: accountParam,
-    },
+    }),
   }, async ({ presentationId, slideId, detail, account }) => {
     const args = ['slides', 'read-slide', presentationId, slideId];
     if (detail) args.push('--detail');

package/src/tools/tasks.ts

@@ -1,4 +1,4 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { accountParam, runOrDiagnose, registerRunTool } from './utils.js';
 
@@ -6,9 +6,9 @@ export function registerTasksTools(server: McpServer): void {
   server.registerTool('gog_tasks_lists', {
     description: 'List all Google Task lists.',
     annotations: { readOnlyHint: true },
-    inputSchema: {
+    inputSchema: z.object({
       account: accountParam,
-    },
+    }),
   }, async ({ account }) => {
     return runOrDiagnose(['tasks', 'lists', 'list'], { account });
   });
@@ -16,10 +16,10 @@ export function registerTasksTools(server: McpServer): void {
   server.registerTool('gog_tasks_list', {
     description: 'List tasks in a Google Task list.',
     annotations: { readOnlyHint: true },
-    inputSchema: {
+    inputSchema: z.object({
       tasklistId: z.string().describe('Task list ID (use gog_tasks_lists to find IDs)'),
       account: accountParam,
-    },
+    }),
   }, async ({ tasklistId, account }) => {
     return runOrDiagnose(['tasks', 'list', tasklistId], { account });
   });
@@ -27,11 +27,11 @@ export function registerTasksTools(server: McpServer): void {
   server.registerTool('gog_tasks_get', {
     description: 'Get a specific task by ID.',
     annotations: { readOnlyHint: true },
-    inputSchema: {
+    inputSchema: z.object({
       tasklistId: z.string().describe('Task list ID'),
       taskId: z.string().describe('Task ID'),
       account: accountParam,
-    },
+    }),
   }, async ({ tasklistId, taskId, account }) => {
     return runOrDiagnose(['tasks', 'get', tasklistId, taskId], { account });
   });
@@ -39,13 +39,13 @@ export function registerTasksTools(server: McpServer): void {
   server.registerTool('gog_tasks_add', {
     description: 'Add a task to a Google Task list.',
     annotations: { destructiveHint: false },
-    inputSchema: {
+    inputSchema: z.object({
       tasklistId: z.string().describe('Task list ID'),
       title: z.string().describe('Task title'),
       notes: z.string().optional().describe('Task notes/description'),
       due: z.string().optional().describe('Due date (YYYY-MM-DD or RFC3339)'),
       account: accountParam,
-    },
+    }),
   }, async ({ tasklistId, title, notes, due, account }) => {
     const args = ['tasks', 'add', tasklistId, `--title=${title}`];
     if (notes) args.push(`--notes=${notes}`);
@@ -56,11 +56,11 @@ export function registerTasksTools(server: McpServer): void {
   server.registerTool('gog_tasks_done', {
     description: 'Mark a task as completed.',
     annotations: { destructiveHint: true },
-    inputSchema: {
+    inputSchema: z.object({
       tasklistId: z.string().describe('Task list ID'),
       taskId: z.string().describe('Task ID'),
       account: accountParam,
-    },
+    }),
   }, async ({ tasklistId, taskId, account }) => {
     return runOrDiagnose(['tasks', 'done', tasklistId, taskId], { account });
   });
@@ -68,11 +68,11 @@ export function registerTasksTools(server: McpServer): void {
   server.registerTool('gog_tasks_delete', {
     description: 'Delete a task.',
     annotations: { destructiveHint: true },
-    inputSchema: {
+    inputSchema: z.object({
       tasklistId: z.string().describe('Task list ID'),
       taskId: z.string().describe('Task ID'),
       account: accountParam,
-    },
+    }),
   }, async ({ tasklistId, taskId, account }) => {
     // gog gates this delete behind a confirmation; the runner injects
     // --no-input, so without --force it refuses at runtime.

package/src/tools/utils.ts

@@ -1,6 +1,5 @@
 import { z } from 'zod';
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { McpServer, CallToolResult } from '@modelcontextprotocol/server';
 import { errorResult, rawTextResult, minifiedResult, stripMediaUrls } from '@chrischall/mcp-utils';
 import { run, isRunnerTransportError } from '../runner.js';
 import type { GogArg, RunnerFailureKind } from '../runner.js';
@@ -149,7 +148,7 @@ export function registerRunTool(
   server.registerTool(`gog_${service}_run`, {
     description,
     annotations: { destructiveHint: true },
-    inputSchema,
+    inputSchema: z.object(inputSchema),
   }, async (rawArgs) => {
     const { subcommand, args, account } = rawArgs as { subcommand: string; args: string[]; account?: string };
     return runOrDiagnose([service, subcommand, ...args], { account });

package/src/worker.ts

@@ -1,7 +1,6 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { McpAgent } from 'agents/mcp';
+import { McpServer } from '@modelcontextprotocol/server';
+import { createMcpHandler, getMcpAuthContext } from 'agents/mcp/server';
 import { OAuthProvider } from '@cloudflare/workers-oauth-provider';
-import { handleAuthorize } from '@chrischall/mcp-connector';
 import type { ToolRegistrar } from '@chrischall/mcp-utils';
 import {
   BASE_TOOL_REGISTRARS,
@@ -15,8 +14,9 @@ import { registerExtraSheetsTools } from '../../gogcli-mcp-sheets/src/tools/shee
 import { registerExtraGmailTools } from '../../gogcli-mcp-gmail/src/tools/gmail-extra.js';
 import { registerExtraDriveTools } from '../../gogcli-mcp-drive/src/tools/drive-extra.js';
 import { registerExtraDocsTools } from '../../gogcli-mcp-docs/src/tools/docs-extra.js';
-import { makeFlyExecutor, wrapServer } from './connector-runtime.js';
+import { createFlyExecutorResolver, wrapServer } from './connector-runtime.js';
 import { gogAuth, CONNECTOR_INSTRUCTIONS, type GogProps } from './connector-auth.js';
+import { handleAuthorize } from './connector-login.js';
 
 // The Cloudflare remote-connector entrypoint for gogcli-mcp.
 //
@@ -24,10 +24,9 @@ import { gogAuth, CONNECTOR_INSTRUCTIONS, type GogProps } from './connector-auth
 // every assembled `gog` arg-array by forwarding it to a Fly.io backend (a Worker
 // cannot spawn processes). The bridge is the `runExecutor` AsyncLocalStorage seam
 // in `runner.ts`: `wrapServer` scopes each tool handler in `runExecutor.run(...)`
-// so the handler's `run()` forwards to the per-session Fly executor.
+// so the handler's `run()` forwards to the authenticated caller's Fly executor.
 //
-// One Worker serves several MCP endpoints under one OAuth login, each a distinct
-// tool set backed by its own Durable Object:
+// One stateless Worker serves several MCP endpoints under one OAuth login:
 //   /mcp          all-services base (BASE_TOOL_REGISTRARS)
 //   /mcp/sheets   auth + Sheets base + Sheets extras
 //   /mcp/gmail    auth + Gmail base + Gmail extras
@@ -38,52 +37,48 @@ import { gogAuth, CONNECTOR_INSTRUCTIONS, type GogProps } from './connector-auth
 // connector with all ~360 tools at once. Add whichever paths you want as separate
 // connectors in claude.ai (each authorizes with the same connector key).
 
-const VERSION = '2.29.1'; // x-release-please-version
+const VERSION = '3.0.0'; // x-release-please-version
 
-// Build an McpAgent subclass whose init() registers `registrars` onto its server,
-// each handler wrapped in the ALS scope carrying the per-session Fly executor.
-// (Kept in worker.ts, not connector-runtime.ts, because it imports the Worker-only
-// `agents` runtime; the node-testable helpers stay in connector-runtime.ts.)
-function makeAgent(registrars: ToolRegistrar[]): typeof McpAgent {
-  class GogAgent extends McpAgent<unknown, unknown, GogProps> {
-    // `instructions` is the connector's only channel to the model that is not a
-    // tool description, and it carries the one thing the client UI gets wrong:
-    // "connected"/"refreshed" is a statement about the connector key, not about
-    // Google. See CONNECTOR_INSTRUCTIONS for why that has to be said out loud.
-    server = new McpServer(
-      { name: 'gogcli-mcp', version: VERSION },
-      { instructions: CONNECTOR_INSTRUCTIONS },
-    );
-    async init() {
-      // NO third argument, deliberately: the hosted connector supplies no
-      // per-caller access token, so `gog` runs as the Fly volume's own identity
-      // and refreshes from its own keyring. That is what makes the eviction +
-      // replay machinery in connector-runtime.ts INERT here — with no token
-      // source there is no module-level cache that can go stale, so a Google
-      // 401 on this path stops at the `no access token was supplied` guard and
-      // logs `replay.declined`. That record is the expected outcome for a
-      // hosted connector, not a bug; the transport-failure classification and
-      // the auth log itself do apply here.
-      //
-      // Inert is not the same as unobserved. Because `gog` is spawned fresh per
-      // /run and re-reads the keyring each time, a Google 401 here means the
-      // STORED credential was refused — which no retry can repair, so no retry
-      // is built. Instead that same guard first takes one live reading of the
-      // Google layer (`GET /health/google` on the runner) and records it as
-      // `refusal.google-ok` / `-unhealthy` / `-unmeasured`. It is throttled,
-      // deadline-bounded, cannot throw, and leaves the caller's error
-      // byte-identical; its whole job is to answer, in the log, the question
-      // that could not be answered after the incident: at the moment Google
-      // refused, was the refresh token on the volume alive or dead?
-      // (docs/DEPLOY-CONNECTOR.md, "Reading the auth log" and "Why a hosted
-      // Google 401 is measured rather than retried", says this for whoever is
-      // reading logs rather than code.)
-      const executor = makeFlyExecutor((this.env as { FLY_ENDPOINT: string }).FLY_ENDPOINT, this.props.key);
-      const wrapped = wrapServer(this.server, executor);
-      for (const register of registrars) register(wrapped);
-    }
-  }
-  return GogAgent as unknown as typeof McpAgent;
+type WorkerEnv = { FLY_ENDPOINT: string };
+
+// One resolver per Worker isolate. Reusing an executor for the same backend
+// credential preserves makeFlyExecutor's refusal-probe throttle across
+// stateless requests; different credentials retain independent throttles.
+const resolveFlyExecutor = createFlyExecutorResolver();
+
+// Build a fresh SDK v2 server for every HTTP request. That is the transport
+// model required by MCP 2026-07-28 multi round-trip requests: input_required
+// returns to the client, and the later request reconstructs the server from
+// the tool arguments plus protocol-managed inputResponses.
+function makeHandler(route: string, registrars: ToolRegistrar[]) {
+  return {
+    fetch(request: Request, env: WorkerEnv, ctx: ExecutionContext) {
+      const handler = createMcpHandler(() => {
+        // Resolve the OAuth props lazily while the tool runs. OAuthProvider
+        // establishes this request context before calling the MCP handler.
+        const executor = ((args, options) => {
+          const props = getMcpAuthContext()?.props as GogProps | undefined;
+          if (!props?.key) throw new Error('Missing authenticated gogcli connector key');
+          return resolveFlyExecutor(env.FLY_ENDPOINT, props.key)(args, options);
+        }) satisfies ReturnType<typeof resolveFlyExecutor>;
+
+        // `instructions` is the connector's only channel to the model that is
+        // not a tool description. It explains that connector authentication
+        // does not prove the Google credential itself is healthy.
+        const server = new McpServer(
+          { name: 'gogcli-mcp', version: VERSION },
+          { instructions: CONNECTOR_INSTRUCTIONS },
+        );
+        const wrapped = wrapServer(server, executor);
+        for (const register of registrars) register(wrapped);
+        return server;
+      }, {
+        route,
+        allowedHostnames: ['connector.gogcli.nullnet.app'],
+      });
+      return handler(request, env, ctx);
+    },
+  };
 }
 
 // auth + <service> base + <service> extras — the exact set each sub-package's
@@ -94,12 +89,6 @@ function makeAgent(registrars: ToolRegistrar[]): typeof McpAgent {
 const svc = (service: string, base: ToolRegistrar, extra: ToolRegistrar): ToolRegistrar[] =>
   [authToolsFor(service), base, extra];
 
-export class GogcliMcpAgent extends makeAgent(BASE_TOOL_REGISTRARS) {}
-export class GogcliSheetsAgent extends makeAgent(svc('sheets', registerSheetsTools, registerExtraSheetsTools)) {}
-export class GogcliGmailAgent extends makeAgent(svc('gmail', registerGmailTools, registerExtraGmailTools)) {}
-export class GogcliDriveAgent extends makeAgent(svc('drive,driveactivity,drivelabels', registerDriveTools, registerExtraDriveTools)) {}
-export class GogcliDocsAgent extends makeAgent(svc('docs', registerDocsTools, registerExtraDocsTools)) {}
-
 const defaultHandler = {
   fetch(request: Request, env: unknown): Response | Promise<Response> {
     const url = new URL(request.url);
@@ -113,12 +102,11 @@ const defaultHandler = {
 // (otherwise `/mcp` greedily swallows `/mcp/sheets`).
 const handler = new OAuthProvider({
   apiHandlers: {
-    '/mcp/sheets': GogcliSheetsAgent.serve('/mcp/sheets', { binding: 'SHEETS_MCP' }) as never,
-    '/mcp/gmail': GogcliGmailAgent.serve('/mcp/gmail', { binding: 'GMAIL_MCP' }) as never,
-    '/mcp/drive': GogcliDriveAgent.serve('/mcp/drive', { binding: 'DRIVE_MCP' }) as never,
-    '/mcp/docs': GogcliDocsAgent.serve('/mcp/docs', { binding: 'DOCS_MCP' }) as never,
-    '/mcp': GogcliMcpAgent.serve('/mcp') as never,
-    '/sse': GogcliMcpAgent.serveSSE('/sse') as never,
+    '/mcp/sheets': makeHandler('/mcp/sheets', svc('sheets', registerSheetsTools, registerExtraSheetsTools)) as never,
+    '/mcp/gmail': makeHandler('/mcp/gmail', svc('gmail', registerGmailTools, registerExtraGmailTools)) as never,
+    '/mcp/drive': makeHandler('/mcp/drive', svc('drive,driveactivity,drivelabels', registerDriveTools, registerExtraDriveTools)) as never,
+    '/mcp/docs': makeHandler('/mcp/docs', svc('docs', registerDocsTools, registerExtraDocsTools)) as never,
+    '/mcp': makeHandler('/mcp', BASE_TOOL_REGISTRARS) as never,
   },
   defaultHandler: defaultHandler as never,
   authorizeEndpoint: '/authorize',

package/tests/blob-upload.test.ts

@@ -0,0 +1,204 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { uploadToBlobStore, RUNNER_UPLOAD_TIMEOUT_MS } from '../src/blob-upload.js';
+
+// A minted PUT URL, with the two shapes the scrubber has to recognise: the
+// whole string, and the bare signature it carries.
+const SIG = 'AbCdEf-_1234';
+const PUT_URL = `https://host.example/b/reg_1/gmail/m1/Guest%20Copy.pdf?exp=1757000000000&sig=${SIG}`;
+
+const ENV = { GOG_RUNNER_URL: 'https://runner.example', GOG_RUNNER_KEY: 'runner-key' };
+
+const REQUEST = { path: '/tmp/gog-attachments/m1/Guest_Copy.pdf', url: PUT_URL, contentType: 'application/pdf' };
+
+function answers(status: number, body: unknown, ok = status >= 200 && status < 300) {
+  return vi.fn(async () => ({
+    ok,
+    status,
+    text: async () => (typeof body === 'string' ? body : JSON.stringify(body)),
+  }));
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.unstubAllEnvs();
+});
+
+describe('uploadToBlobStore', () => {
+  it('POSTs the path, the URL and the content type to the runner, bearing its key', async () => {
+    const fetchMock = answers(200, { ok: true, status: 200, bytes: 99723 });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const outcome = await uploadToBlobStore(REQUEST, { env: { ...ENV, GOG_RUNNER_URL: 'https://runner.example//' } });
+
+    expect(outcome).toEqual({ bytes: 99723, status: 200 });
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    // Trailing slashes trimmed — `<endpoint>//upload` is a different route.
+    expect(url).toBe('https://runner.example/upload');
+    expect(init.method).toBe('POST');
+    expect(init.headers).toMatchObject({
+      Authorization: 'Bearer runner-key',
+      'Content-Type': 'application/json',
+    });
+    expect(JSON.parse(init.body as string)).toEqual({
+      path: REQUEST.path,
+      url: PUT_URL,
+      contentType: 'application/pdf',
+    });
+    // A deadline of our own: the runner's 120 s is an INACTIVITY timer and
+    // cannot bound a transfer that keeps dribbling, so nothing else protects
+    // the MCP caller from a request that never ends.
+    expect(init.signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it('refuses, without dialling, when no gog runner is configured', async () => {
+    const fetchMock = answers(200, { ok: true });
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(uploadToBlobStore(REQUEST, { env: { GOG_RUNNER_URL: ENV.GOG_RUNNER_URL } }))
+      .rejects.toThrow(/GOG_RUNNER_URL.*GOG_RUNNER_KEY/s);
+    await expect(uploadToBlobStore(REQUEST, { env: { GOG_RUNNER_KEY: ENV.GOG_RUNNER_KEY } }))
+      .rejects.toThrow(/GOG_RUNNER_URL.*GOG_RUNNER_KEY/s);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('reports the blob store\'s own verdict when the runner relays a refusal', async () => {
+    vi.stubGlobal('fetch', answers(422, {
+      error: 'the blob store refused the upload with 403: forbidden',
+      status: 403,
+      retryable: false,
+    }));
+
+    await expect(uploadToBlobStore(REQUEST, { env: ENV }))
+      .rejects.toThrow(/the blob store refused the upload with 403: forbidden/);
+  });
+
+  it('names the runner\'s status when it answers with no error text', async () => {
+    vi.stubGlobal('fetch', answers(502, { retryable: true }));
+
+    await expect(uploadToBlobStore(REQUEST, { env: ENV })).rejects.toThrow(/502/);
+  });
+
+  it('survives an answer that is not JSON at all (a proxy\'s HTML error page)', async () => {
+    vi.stubGlobal('fetch', answers(504, '<html>gateway timeout</html>'));
+
+    // The body is quoted, not parsed — and the throw is about the upload, never
+    // a SyntaxError from somewhere inside this module.
+    await expect(uploadToBlobStore(REQUEST, { env: ENV })).rejects.toThrow(/504/);
+  });
+
+  // A signed URL is a credential with up to 24 h of anybody-who-holds-it access
+  // to the object. The runner scrubs its own words, but the far side's text is
+  // a third party's and may quote the request URL straight back — and an error
+  // thrown here is the one value on this path that is expected to be logged.
+  it('never lets the signed URL, or its bare signature, into the error it throws', async () => {
+    vi.stubGlobal('fetch', answers(422, { error: `refused: PUT ${PUT_URL} (sig ${SIG})`, status: 403 }));
+
+    const err = await uploadToBlobStore(REQUEST, { env: ENV }).catch((e: Error) => e);
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).not.toContain(PUT_URL);
+    expect((err as Error).message).not.toContain(SIG);
+    expect((err as Error).message).toContain('<signed url>');
+  });
+
+  it('scrubs a transport failure too — a rejected fetch may quote the URL', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => {
+      throw new Error(`connect ECONNREFUSED while sending ${PUT_URL}`);
+    }));
+
+    const err = await uploadToBlobStore(REQUEST, { env: ENV }).catch((e: Error) => e);
+    expect((err as Error).message).not.toContain(PUT_URL);
+    expect((err as Error).message).not.toContain(SIG);
+    expect((err as Error).message).toContain('ECONNREFUSED');
+  });
+
+  it('reports a transport failure that threw something other than an Error', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => { throw 'socket hang up'; }));
+
+    await expect(uploadToBlobStore(REQUEST, { env: ENV })).rejects.toThrow(/socket hang up/);
+  });
+
+  // The response ARRIVES and then its body fails to read — a severed or
+  // truncated answer. That is a third shape of transport failure, and the
+  // module's contract is about every one of them: nothing it throws carries the
+  // URL. undici's own body errors ('terminated', 'Premature close') happen to
+  // name nothing, so this is the guarantee being a property of the function
+  // rather than a fact about today's runtime.
+  it('scrubs a body that fails to read, as it scrubs a failed dial', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      text: async () => { throw new Error(`terminated while reading ${PUT_URL}`); },
+    })));
+
+    const err = await uploadToBlobStore(REQUEST, { env: ENV }).catch((e: Error) => e);
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).not.toContain(PUT_URL);
+    expect((err as Error).message).not.toContain(SIG);
+    expect((err as Error).message).toContain('terminated');
+  });
+
+  it('reports a body read that rejected with something other than an Error', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      text: async () => { throw 'premature close'; },
+    })));
+
+    await expect(uploadToBlobStore(REQUEST, { env: ENV })).rejects.toThrow(/premature close/);
+  });
+
+  // The whole-string replacement is what does the work for a URL with no `sig`
+  // at all — and a URL that is not parseable must still be redacted rather than
+  // throwing on the way to a redaction.
+  it('scrubs a URL that carries no signature and does not parse', async () => {
+    const odd = 'not a url at all';
+    vi.stubGlobal('fetch', answers(422, { error: `refused: ${odd}`, status: 400 }));
+
+    const err = await uploadToBlobStore({ ...REQUEST, url: odd }, { env: ENV }).catch((e: Error) => e);
+    expect((err as Error).message).not.toContain(odd);
+    expect((err as Error).message).toContain('<signed url>');
+  });
+
+  // `split('')` cuts a message into single characters and interleaves the
+  // replacement between every one of them, so an empty needle does not redact a
+  // message, it destroys it. Today's one call site always mints a URL first —
+  // this is a property of the function, which is why it is asserted on it.
+  it('an empty URL leaves the message intact rather than shredding it', async () => {
+    vi.stubGlobal('fetch', answers(422, { error: 'the blob store refused the upload', status: 403 }));
+
+    const err = await uploadToBlobStore({ ...REQUEST, url: '' }, { env: ENV }).catch((e: Error) => e);
+    expect((err as Error).message).toContain('the blob store refused the upload');
+    expect((err as Error).message).not.toContain('<signed url>');
+  });
+
+  it('reads the ambient environment, and its own deadline, when given neither', async () => {
+    const fetchMock = answers(200, { ok: true, status: 200, bytes: 12 });
+    vi.stubGlobal('fetch', fetchMock);
+    vi.stubEnv('GOG_RUNNER_URL', ENV.GOG_RUNNER_URL);
+    vi.stubEnv('GOG_RUNNER_KEY', ENV.GOG_RUNNER_KEY);
+
+    await expect(uploadToBlobStore(REQUEST)).resolves.toEqual({ bytes: 12, status: 200 });
+    expect((fetchMock.mock.calls[0] as [string, RequestInit])[0]).toBe('https://runner.example/upload');
+  });
+
+  it('exposes its deadline as a constant rather than a literal at the call site', () => {
+    expect(RUNNER_UPLOAD_TIMEOUT_MS).toBeGreaterThan(30_000);
+  });
+
+  // The rule this repo already applies at the other hop (`DEADLINE_GRACE_MS` in
+  // connector-runtime.ts: 30 s backend budget + 5 s): the CALLER's deadline sits
+  // ABOVE the backend's own, so the backend loses the race only when it
+  // genuinely cannot answer. The doc block here cited that rule while the
+  // numbers inverted it — 90 s against the runner's 120 s — so a socket that
+  // went quiet was aborted on this side 30 s before the runner's own timer could
+  // name it, turning "the upload timed out after 120000ms" into exactly the
+  // opaque client abort the rule exists to prevent.
+  //
+  // Restated rather than imported: `fly-gog-runner/server.mjs` must not be
+  // pulled into the Worker bundle (the same reason the attachment ceilings are
+  // restated in attachments.ts), so the two move by hand and this is the guard.
+  it('sits above the runner\'s own upload timeout, so the runner answers first', () => {
+    const UPLOAD_TIMEOUT_MS_ON_THE_BOX = 120_000; // server.mjs UPLOAD_TIMEOUT_MS
+    expect(RUNNER_UPLOAD_TIMEOUT_MS).toBeGreaterThan(UPLOAD_TIMEOUT_MS_ON_THE_BOX);
+  });
+});