Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
48.6 KB
Raw Blame
import { afterEach, describe, expect, it, vi } from 'vitest'
import { createCanvas } from '@napi-rs/canvas'
import { VISUAL_INPUT_LIMITS, VisualInputBudget } from '../visualInput/policy'
import type { GfscCallOptions, GfscWriteClient } from './gfs'
import {
  DEFAULT_GFS_ACCESS_FILE,
  type GfsRuntimeEnv,
  type GfsToolScopeInspection,
  GfscHttpError,
  createGfscClient,
  getGfsToolScopes,
  hasGfsRuntimeAccess,
  inspectGfsToolScopes,
} from './gfsClient'

function encodedClaims(scopes: unknown): string {
  const header = Buffer.from(JSON.stringify({ alg: 'none', typ: 'JWT' })).toString('base64url')
  const payload = Buffer.from(JSON.stringify({ scopes })).toString('base64url')
  return `${header}.${payload}.sig`
}

function jsonResponse(body: unknown, status = 200): Response {
  return new Response(JSON.stringify(body), {
    status,
    headers: { 'content-type': 'application/json' },
  })
}

// Every test client gets a budget far above any Retry-After used here, and a
// random source of 0 so the retry waits exactly the advertised delay.
const clientOptions = { maxRetryWaitMs: 60_000, random: () => 0 }

function textResponse(body: string, status: number, statusText = ''): Response {
  return new Response(body, { status, statusText })
}

describe('gfs runtime gfsc client', () => {
  it('detects mounted runtime access without exposing dead tools', () => {
    expect(
      hasGfsRuntimeAccess({
        get: () => undefined,
        fileExists: path => path === DEFAULT_GFS_ACCESS_FILE,
      })
    ).toBe(true)
    expect(
      hasGfsRuntimeAccess({
        get: () => undefined,
        fileExists: () => false,
      })
    ).toBe(false)
  })

  it('derives only recognized GFS tool scopes and fails closed', () => {
    expect([
      ...(getGfsToolScopes({ get: () => encodedClaims(['gfs.read', 'gfs.write']) }) ?? []),
    ]).toEqual(['gfs.read', 'gfs.write'])
    expect(getGfsToolScopes({ get: () => encodedClaims(['gfs.read', 'gfs.delete']) })).toBeNull()
    expect(getGfsToolScopes({ get: () => encodedClaims(['gfs.delete']) })).toBeNull()
    expect(getGfsToolScopes({ get: () => encodedClaims([]) })).toBeNull()
    expect(getGfsToolScopes({ get: () => encodedClaims('gfs.read') })).toBeNull()
    expect(getGfsToolScopes({ get: () => 'malformed' })).toBeNull()
  })

  describe('inspectGfsToolScopes (#666)', () => {
    const enoent = () =>
      Object.assign(new Error('ENOENT: no such file or directory'), {
        code: 'ENOENT',
        syscall: 'open',
      })
    const fileEnv = (configuredPath: string | undefined, read: (path: string) => string) => ({
      get: (key: string) => (key === 'MCP_HOST_GFS_TOKEN_FILE' ? configuredPath : undefined),
      readFileSync: read,
    })

    it('reports each token state, and getGfsToolScopes keeps its answer for each', () => {
      const cases: [GfsRuntimeEnv, GfsToolScopeInspection, string[] | null][] = [
        [
          { get: () => encodedClaims(['gfs.read', 'gfs.write']) },
          { status: 'ok', scopes: new Set(['gfs.read', 'gfs.write']) },
          ['gfs.read', 'gfs.write'],
        ],
        [{ get: () => encodedClaims([]) }, { status: 'ok', scopes: new Set() }, null],
        [
          { get: () => encodedClaims(['gfs.read', 'gfs.share']) },
          { status: 'scope_outside_allowlist' },
          null,
        ],
        [{ get: () => 'malformed' }, { status: 'token_undecodable' }, null],
        [{ get: () => encodedClaims('gfs.read') }, { status: 'token_undecodable' }, null],
        [
          fileEnv(undefined, () => {
            throw enoent()
          }),
          { status: 'not_configured' },
          null,
        ],
        [
          fileEnv('/mounted/token', () => {
            throw enoent()
          }),
          { status: 'token_unreadable' },
          null,
        ],
        [
          fileEnv(undefined, () => {
            throw Object.assign(new Error('EACCES'), { code: 'EACCES', syscall: 'open' })
          }),
          { status: 'token_unreadable' },
          null,
        ],
        [fileEnv(undefined, () => ' \n'), { status: 'token_unreadable' }, null],
        [
          fileEnv('/mounted/token', () => `${encodedClaims(['gfs.read'])}\n`),
          { status: 'ok', scopes: new Set(['gfs.read']) },
          ['gfs.read'],
        ],
      ]
      for (const [env, inspection, scopes] of cases) {
        expect(inspectGfsToolScopes(env)).toEqual(inspection)
        const legacy = getGfsToolScopes(env)
        expect(legacy === null ? null : [...legacy]).toEqual(scopes)
      }
    })

    it('reads the configured token file, or the default path when none is configured', () => {
      const read = vi.fn((_path: string) => encodedClaims(['gfs.read']))
      inspectGfsToolScopes(fileEnv('/mounted/token', read))
      inspectGfsToolScopes(fileEnv(undefined, read))
      expect(read.mock.calls.map(call => call[0])).toEqual([
        '/mounted/token',
        DEFAULT_GFS_ACCESS_FILE,
      ])
    })
  })

  it('calls gfsc accessible with runtime bearer auth', async () => {
    const fetchFn = vi.fn(async (_input: string, _init?: RequestInit) =>
      jsonResponse({ ok: true, data: { items: [] } })
    )
    const client = createGfscClient(
      {
        get: key => (key === 'MCP_HOST_GFS_TOKEN' ? 'gfs-access' : undefined),
        fetch: fetchFn,
      },
      clientOptions
    )
    await client.accessible({ drive: 'main' })
    expect(fetchFn.mock.calls[0]?.[0]).toBe(
      'http://gfsc.gfs.svc.cluster.local:8087/v1/accessible?drive=main'
    )
    expect(fetchFn.mock.calls[0]?.[1]?.headers).toMatchObject({
      authorization: 'Bearer gfs-access',
    })
    expect(fetchFn.mock.calls[0]?.[1]).toMatchObject({ redirect: 'error' })
  })

  it('routes writes to the gfsc writer service with conditional body', async () => {
    const fetchFn = vi.fn(async (_input: string, _init?: RequestInit) =>
      jsonResponse({ ok: true, data: { version: 3 } })
    )
    const client = createGfscClient(
      {
        get: key => (key === 'MCP_HOST_GFS_TOKEN' ? 'gfs-access' : undefined),
        fetch: fetchFn,
      },
      clientOptions
    )
    await client.write({ drive: 'main', resourceId: 'rid', content: 'new', ifMatch: 2 })
    expect(fetchFn.mock.calls[0]?.[0]).toBe(
      'http://gfsc-writer.gfs.svc.cluster.local:8087/v1/resources/rid/content?drive=main'
    )
    expect(fetchFn.mock.calls[0]?.[1]).toMatchObject({
      method: 'PUT',
      body: JSON.stringify({ content: 'new', ifMatch: 2 }),
    })
  })

  it('uses exact writer routes and bodies for create, rename, and copy', async () => {
    const fetchFn = vi.fn(async (_input: string, _init?: RequestInit) =>
      jsonResponse({ ok: true, data: {} })
    )
    const client = createGfscClient(
      {
        get: key => (key === 'MCP_HOST_GFS_TOKEN' ? 'gfs-access' : undefined),
        fetch: fetchFn,
      },
      clientOptions
    )
    await client.createFile({
      drive: 'main',
      parentResourceId: 'parent/id',
      name: 'note.txt',
      content: 'hello',
    })
    await client.createFolder({ drive: 'main', parentResourceId: 'parent/id', name: 'docs' })
    await client.rename({
      drive: 'main',
      resourceId: 'source/id',
      newName: 'renamed.txt',
      ifMatch: 4,
    })
    const copy = {
      drive: 'main',
      sourceResourceId: 'source',
      destinationParentId: 'destination',
      newName: 'source-copy',
      ifMatch: 7,
    }
    await client.copy(copy)

    expect(fetchFn.mock.calls.map(call => [call[0], call[1]?.method, call[1]?.body])).toEqual([
      [
        'http://gfsc-writer.gfs.svc.cluster.local:8087/v1/resources/parent%2Fid/children?drive=main',
        'POST',
        JSON.stringify({ name: 'note.txt', kind: 'file', content: 'hello' }),
      ],
      [
        'http://gfsc-writer.gfs.svc.cluster.local:8087/v1/resources/parent%2Fid/children?drive=main',
        'POST',
        JSON.stringify({ name: 'docs', kind: 'directory' }),
      ],
      [
        'http://gfsc-writer.gfs.svc.cluster.local:8087/v1/resources/source%2Fid',
        'PATCH',
        JSON.stringify({ drive: 'main', newName: 'renamed.txt', ifMatch: 4 }),
      ],
      ['http://gfsc-writer.gfs.svc.cluster.local:8087/v1/copy', 'POST', JSON.stringify(copy)],
    ])
  })

  it('fails loud when the mounted runtime token file is empty', async () => {
    const client = createGfscClient(
      {
        get: () => undefined,
        readFile: async () => '  \n',
        fetch: vi.fn(async () => jsonResponse({ ok: true })),
      },
      clientOptions
    )

    await expect(client.accessible({ drive: 'main' })).rejects.toThrow(
      /MCP_HOST_GFS_TOKEN_FILE is empty/
    )
  })

  it('surfaces gfsc authorization denials with the response body', async () => {
    const fetchFn = vi.fn(async () => textResponse('not authorized to write this resource', 403))
    const client = createGfscClient(
      {
        get: key => (key === 'MCP_HOST_GFS_TOKEN' ? 'gfs-access' : undefined),
        fetch: fetchFn,
      },
      clientOptions
    )

    await expect(
      client.write({ drive: 'main', resourceId: 'rid', content: 'new', ifMatch: 2 })
    ).rejects.toThrow(/gfsc 403: not authorized to write this resource/)
  })

  it('surfaces gfsc read denials with the response body', async () => {
    const fetchFn = vi.fn(async () => textResponse('not authorized to read this resource', 403))
    const client = createGfscClient(
      {
        get: key => (key === 'MCP_HOST_GFS_TOKEN' ? 'gfs-access' : undefined),
        fetch: fetchFn,
      },
      clientOptions
    )

    await expect(client.read({ drive: 'main', resourceId: 'rid' })).rejects.toThrow(
      /gfsc 403: not authorized to read this resource/
    )
  })

  it('surfaces the fail-closed not_mounted envelope intact on resolve (issue #775)', async () => {
    // Regression guard: the Desktop App and the agent distinguish a permission
    // store outage (503 not_mounted) from an authorization denial (403) by the
    // ERROR BODY this client propagates. Softening or rewrapping it would turn
    // an infrastructure failure into an ambiguous tool error.
    const envelope = JSON.stringify({
      ok: false,
      error: {
        code: 'not_mounted',
        message:
          'permission store unavailable: password authentication failed for user "gfs_controller"',
      },
    })
    const fetchFn = vi.fn(async () => textResponse(envelope, 503))
    const client = createGfscClient(
      {
        get: key => (key === 'MCP_HOST_GFS_TOKEN' ? 'gfs-access' : undefined),
        fetch: fetchFn,
      },
      clientOptions
    )

    await expect(client.resolve({ uri: 'gfs://main/docs/report.md' })).rejects.toThrow(
      `gfsc 503: ${envelope}`
    )
  })

  it('surfaces gfsc transient failures with the status text when the body is empty', async () => {
    const fetchFn = vi.fn(async () => textResponse('', 503, 'Service Unavailable'))
    const client = createGfscClient(
      {
        get: key => (key === 'MCP_HOST_GFS_TOKEN' ? 'gfs-access' : undefined),
        fetch: fetchFn,
      },
      clientOptions
    )

    await expect(client.stat({ drive: 'main', resourceId: 'rid' })).rejects.toThrow(
      /gfsc 503: Service Unavailable/
    )
  })

  it('surfaces gfsc list transient failures with the status text when the body is empty', async () => {
    const fetchFn = vi.fn(async () => textResponse('', 503, 'Service Unavailable'))
    const client = createGfscClient(
      {
        get: key => (key === 'MCP_HOST_GFS_TOKEN' ? 'gfs-access' : undefined),
        fetch: fetchFn,
      },
      clientOptions
    )

    await expect(client.list({ drive: 'main', resourceId: 'rid' })).rejects.toThrow(
      /gfsc 503: Service Unavailable/
    )
  })
})

const FILE_ID = '1234567890abcdef1234567890abcdef'
const FILE_URI = `gfs://main/${FILE_ID}`
const READ_ARGS = { drive: 'main', resourceId: FILE_ID }

function contentHarness(
  bytes: Buffer,
  options: {
    metadata?: Record<string, unknown>
    response?: () => Response
    headers?: Record<string, string>
  } = {}
) {
  const fetchFn = vi.fn(async (_url: string, _init?: RequestInit) => {
    if (!_url.includes('/content?'))
      return jsonResponse({
        ok: true,
        data: {
          resourceId: FILE_ID,
          rid: FILE_ID,
          drive: 'main',
          gfsUri: FILE_URI,
          kind: 'file',
          name: 'neutral.png',
          version: 3,
          bytes: bytes.length,
          ...options.metadata,
        },
      })
    return (
      options.response?.() ??
      new Response(new Uint8Array(bytes), {
        headers: {
          'content-type': 'application/octet-stream',
          'x-gfs-uri': FILE_URI,
          'x-gfs-version': '3',
          'content-length': String(bytes.length),
          ...options.headers,
        },
      })
    )
  })
  const client = createGfscClient(
    {
      get: () => undefined,
      // Synthetic runtime identity for the injected HTTP boundary; never a real grant.
      readFile: async () => 'unit-gfs-read-identity',
      fetch: fetchFn,
    },
    clientOptions
  )
  const budget = new VisualInputBudget()
  return { client, fetchFn, budget }
}

describe('GFS binary content snapshots', () => {
  it('shares admission across live downloads and releases only the cancelled read', async () => {
    const bytes = Buffer.alloc(100_000, 65)
    const budget = new VisualInputBudget(300_000)
    const controller = new AbortController()
    let entered!: () => void
    const reading = new Promise<void>(resolve => {
      entered = resolve
    })
    let hold = true
    const cancelled = vi.fn()
    const { client, fetchFn } = contentHarness(bytes, {
      response: () =>
        new Response(
          hold
            ? new ReadableStream({
                pull() {
                  entered()
                },
                cancel: cancelled,
              })
            : new Uint8Array(bytes),
          {
            headers: { 'x-gfs-uri': FILE_URI, 'x-gfs-version': '3' },
          }
        ),
    })
    const first = client.read(READ_ARGS, { budget, signal: controller.signal })
    const rejectedFirst = expect(first).rejects.toMatchObject({ code: 'cancelled' })
    await reading
    const heldBytes = budget.residentBytes
    await expect(client.read(READ_ARGS, { budget })).rejects.toMatchObject({
      code: 'limit_exceeded',
    })
    expect(budget.residentBytes).toBe(heldBytes)
    expect(fetchFn).toHaveBeenCalledTimes(2)
    controller.abort()
    await rejectedFirst
    expect(cancelled).toHaveBeenCalledOnce()
    expect(budget.residentBytes).toBe(0)
    hold = false
    const next = await client.read(READ_ARGS, { budget })
    expect(next.bytes.equals(bytes)).toBe(true)
    next.reservation.release()
    expect(budget.residentBytes).toBe(0)
  })

  it('reports a truncated stream without exposing its underlying error', async () => {
    const { client, budget } = contentHarness(Buffer.from('abc'), {
      response: () =>
        new Response(
          new ReadableStream({
            start(controller) {
              controller.error(new Error('private stream detail'))
            },
          }),
          { headers: { 'x-gfs-uri': FILE_URI, 'x-gfs-version': '3' } }
        ),
    })
    await expect(client.read(READ_ARGS, { budget })).rejects.toMatchObject({
      code: 'incomplete_response',
      message: 'GFS read failed (incomplete_response)',
    })
    expect(budget.residentBytes).toBe(0)
  })
  it('does not accumulate an invisible lifetime quota when independent reads reuse a client', async () => {
    const bytes = Buffer.alloc(VISUAL_INPUT_LIMITS.fileBytes, 65)
    const { client } = contentHarness(bytes, { metadata: { name: 'text.txt' } })
    for (let operation = 0; operation < 9; operation++) {
      const result = await client.read(READ_ARGS)
      expect(result.bytes.byteLength).toBe(bytes.byteLength)
      result.reservation.release()
    }
  })
  it('preserves complete PNG bytes and verified resource metadata', async () => {
    const canvas = createCanvas(2, 2)
    canvas.getContext('2d').fillRect(0, 0, 2, 2)
    const original = canvas.toBuffer('image/png')
    const { client, fetchFn, budget } = contentHarness(original)
    const result = await client.read(READ_ARGS, { budget })
    expect(result.bytes.equals(original)).toBe(true)
    expect(result.source).toMatchObject({ resourceId: FILE_ID, gfsUri: FILE_URI, version: 3 })
    expect(fetchFn.mock.calls.map(call => call[0])).toEqual([
      `http://gfsc.gfs.svc.cluster.local:8087/v1/resources/${FILE_ID}?drive=main`,
      `http://gfsc.gfs.svc.cluster.local:8087/v1/resources/${FILE_ID}/content?drive=main`,
    ])
    expect(fetchFn.mock.calls[1][1]).toMatchObject({
      redirect: 'error',
      signal: expect.any(AbortSignal),
    })
    expect(budget.readBytes).toBe(original.length)
    expect(budget.residentBytes).toBeGreaterThan(0)
    result.reservation.release()
    expect(budget.residentBytes).toBe(0)
  })

  it.each(['', 'Hola 🌴\r\n', '{"ok":false,"data":"file content"}'])(
    'preserves textual bytes without treating the file as an API envelope: %s',
    async text => {
      const { client, budget } = contentHarness(Buffer.from(text), {
        metadata: { name: 'data.json' },
      })
      const result = await client.read(READ_ARGS, { budget })
      expect(result.bytes.toString('utf8')).toBe(text)
      result.reservation.release()
      expect(budget.residentBytes).toBe(0)
    }
  )

  it.each([
    { version: -1 },
    { version: 1.5 },
    { bytes: -1 },
    { bytes: '3' },
    { drive: 'other' },
    { gfsUri: 'gfs://other/resource' },
    { rid: 'wrong' },
    { name: null },
  ])('rejects inconsistent metadata before content is requested: %j', async metadata => {
    const { client, fetchFn, budget } = contentHarness(Buffer.from('abc'), { metadata })
    await expect(client.read(READ_ARGS, { budget })).rejects.toMatchObject({
      code: 'invalid_response',
    })
    expect(fetchFn).toHaveBeenCalledTimes(1)
    expect(budget.residentBytes).toBe(0)
  })

  it('rejects an oversized snapshot before downloading it', async () => {
    const { client, fetchFn, budget } = contentHarness(Buffer.alloc(0), {
      metadata: { bytes: 16 * 1024 * 1024 + 1 },
    })
    await expect(client.read(READ_ARGS, { budget })).rejects.toMatchObject({
      code: 'limit_exceeded',
    })
    expect(fetchFn).toHaveBeenCalledTimes(1)
    expect(budget.residentBytes).toBe(0)
  })

  it.each([
    [{ 'x-gfs-version': '4' }, 'version_conflict'],
    [{ 'x-gfs-uri': 'gfs://main/wrong' }, 'identity_mismatch'],
    [{ 'content-length': '2' }, 'incomplete_response'],
    [{ 'content-length': 'not-a-size' }, 'incomplete_response'],
    [{ 'content-encoding': 'gzip' }, 'invalid_response'],
  ] as const)('rejects contradictory content headers %j', async (headers, code) => {
    const { client, budget } = contentHarness(Buffer.from('abc'), { headers })
    await expect(client.read(READ_ARGS, { budget })).rejects.toMatchObject({ code })
    expect(budget.residentBytes).toBe(0)
  })

  it('accepts exact chunked content without Content-Length', async () => {
    const { client, budget } = contentHarness(Buffer.from('abc'), {
      response: () =>
        new Response(
          new ReadableStream({
            start(controller) {
              controller.enqueue(Buffer.from('a'))
              controller.enqueue(Buffer.from('bc'))
              controller.close()
            },
          }),
          { headers: { 'x-gfs-uri': FILE_URI, 'x-gfs-version': '3' } }
        ),
    })
    const result = await client.read(READ_ARGS, { budget })
    expect(result.bytes.toString()).toBe('abc')
    result.reservation.release()
  })

  it('cancels a chunked overrun without retaining extra bytes or refunding read work', async () => {
    const cancel = vi.fn()
    const { client, budget } = contentHarness(Buffer.from('abc'), {
      response: () =>
        new Response(
          new ReadableStream({
            start(controller) {
              controller.enqueue(Buffer.from('abc'))
              controller.enqueue(Buffer.from('extra'))
            },
            cancel,
          }),
          { headers: { 'x-gfs-uri': FILE_URI, 'x-gfs-version': '3' } }
        ),
    })
    await expect(client.read(READ_ARGS, { budget })).rejects.toMatchObject({
      code: 'limit_exceeded',
    })
    expect(cancel).toHaveBeenCalled()
    expect(budget.residentBytes).toBe(0)
    expect(budget.readBytes).toBe(8)
  })

  it('charges rejected first chunks across retries and stops at the turn read limit', async () => {
    const { client, fetchFn } = contentHarness(Buffer.from('abc'), {
      response: () =>
        new Response(new Uint8Array(Buffer.from('over')), {
          headers: { 'x-gfs-uri': FILE_URI, 'x-gfs-version': '3' },
        }),
    })
    const budget = new VisualInputBudget(200_000, 8)

    await expect(client.read(READ_ARGS, { budget })).rejects.toMatchObject({
      code: 'limit_exceeded',
    })
    expect(budget.readBytes).toBe(4)
    await expect(client.read(READ_ARGS, { budget })).rejects.toMatchObject({
      code: 'limit_exceeded',
    })
    expect(budget.readBytes).toBe(8)
    await expect(client.read(READ_ARGS, { budget })).rejects.toMatchObject({
      code: 'limit_exceeded',
    })
    expect(fetchFn).toHaveBeenCalledTimes(4)
    expect(budget.residentBytes).toBe(0)
  })

  it('rejects short content and unsolicited partial responses', async () => {
    for (const status of [200, 206]) {
      const { client, budget } = contentHarness(Buffer.from('abc'), {
        response: () =>
          new Response('ab', { status, headers: { 'x-gfs-uri': FILE_URI, 'x-gfs-version': '3' } }),
      })
      await expect(client.read(READ_ARGS, { budget })).rejects.toMatchObject({
        code: status === 200 ? 'incomplete_response' : 'invalid_response',
      })
      expect(budget.residentBytes).toBe(0)
    }
  })

  it('does not fetch when the caller has already cancelled', async () => {
    const { client, fetchFn, budget } = contentHarness(Buffer.from('abc'))
    await expect(
      client.read(READ_ARGS, { budget, signal: AbortSignal.abort() })
    ).rejects.toMatchObject({ code: 'cancelled' })
    expect(fetchFn).not.toHaveBeenCalled()
  })

  it('cancels an in-progress response stream and returns no partial image', async () => {
    const controller = new AbortController()
    const cancelled = vi.fn()
    let reading!: () => void
    const entered = new Promise<void>(resolve => {
      reading = resolve
    })
    const { client, budget } = contentHarness(Buffer.from('abc'), {
      response: () =>
        new Response(
          new ReadableStream({
            pull() {
              reading()
            },
            cancel: cancelled,
          }),
          { headers: { 'x-gfs-uri': FILE_URI, 'x-gfs-version': '3' } }
        ),
    })
    const result = client.read(READ_ARGS, { budget, signal: controller.signal })
    const failure = expect(result).rejects.toMatchObject({ code: 'cancelled' })
    await entered
    controller.abort()
    await failure
    expect(cancelled).toHaveBeenCalled()
    expect(budget.residentBytes).toBe(0)
  })

  it('cancels stat when the caller aborts and cleans its timer and listener', async () => {
    vi.useFakeTimers()
    try {
      const budget = new VisualInputBudget()
      const controller = new AbortController()
      const remove = vi.spyOn(controller.signal, 'removeEventListener')
      let entered!: () => void
      const reading = new Promise<void>(resolve => {
        entered = resolve
      })
      const fetchFn = vi.fn((_url: string, init?: RequestInit) => {
        entered()
        return new Promise<Response>((_resolve, reject) => {
          init!.signal!.addEventListener('abort', () => reject(new Error('private detail')), {
            once: true,
          })
        })
      })
      const client = createGfscClient(
        {
          get: () => undefined,
          readFile: async () => 'unit-gfs-read-identity',
          fetch: fetchFn,
        },
        clientOptions
      )
      const failure = expect(
        client.read(READ_ARGS, { budget, signal: controller.signal })
      ).rejects.toMatchObject({ code: 'cancelled' })
      await reading
      controller.abort()
      await failure
      expect(fetchFn).toHaveBeenCalledTimes(1)
      expect(budget.residentBytes).toBe(0)
      expect(remove).toHaveBeenCalledWith('abort', expect.any(Function))
      expect(vi.getTimerCount()).toBe(0)
    } finally {
      vi.useRealTimers()
    }
  })

  it('bounds the entire metadata request by a deadline', async () => {
    vi.useFakeTimers()
    try {
      const budget = new VisualInputBudget()
      const client = createGfscClient(
        {
          get: () => undefined,
          readFile: async () => 'unit-gfs-read-identity',
          fetch: async (_url, init) =>
            new Promise((_resolve, reject) => {
              init!.signal!.addEventListener(
                'abort',
                () => reject(new Error('private upstream detail')),
                { once: true }
              )
            }),
        },
        clientOptions
      )
      const failed = expect(
        client.read(READ_ARGS, { budget, timeoutMs: 10 })
      ).rejects.toMatchObject({ code: 'timeout', message: 'GFS read failed (timeout)' })
      await vi.advanceTimersByTimeAsync(10)
      await failed
      expect(budget.residentBytes).toBe(0)
    } finally {
      vi.useRealTimers()
    }
  })
})

// gfsc's agent limiter names its bucket in X-GFS-RateLimit-Scope
// (serve.ts: `limit: write ? "agent_writes" : "agent_reads"`); only those
// scopes are retried.
function rateLimited(retryAfter?: string, scope = 'agent_reads'): Response {
  const headers: Record<string, string> = {
    'content-type': 'application/json',
    'x-gfs-ratelimit-scope': scope,
  }
  if (retryAfter !== undefined) headers['retry-after'] = retryAfter
  // gfsc's envelope also carries retryAfterSeconds; the client reads only the
  // header, so the no-header cases below prove the body is never consulted.
  return new Response(
    JSON.stringify({ ok: false, error: { code: 'rate_limited', retryAfterSeconds: 5 } }),
    { status: 429, headers }
  )
}

function tokenEnv(fetchFn: (input: string, init?: RequestInit) => Promise<Response>) {
  return {
    get: (key: string) => (key === 'MCP_HOST_GFS_TOKEN' ? 'gfs-access' : undefined),
    fetch: fetchFn,
  }
}

describe('gfsc client on a 429', () => {
  afterEach(() => {
    vi.useRealTimers()
    vi.restoreAllMocks()
  })

  it('retries once after the stated delay and resolves', async () => {
    vi.useFakeTimers()
    const callTimes: number[] = []
    const fetchFn = vi.fn(async () => {
      callTimes.push(Date.now())
      return callTimes.length === 1 ? rateLimited('2') : jsonResponse({ ok: true, version: 4 })
    })
    const client = createGfscClient(tokenEnv(fetchFn), clientOptions)

    const pending = client.stat({ drive: 'main', resourceId: 'rid' })
    await vi.advanceTimersByTimeAsync(0)
    expect(fetchFn).toHaveBeenCalledTimes(1)
    await vi.advanceTimersByTimeAsync(2000)
    expect(fetchFn).toHaveBeenCalledTimes(2)
    await expect(pending).resolves.toEqual({ ok: true, version: 4 })
    expect(callTimes[1]! - callTimes[0]!).toBe(2000)
  })

  it('waits exactly the advertised Retry-After, not a constant', async () => {
    vi.useFakeTimers()
    const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout')
    const bytes = Buffer.from('rate-limited read')
    const { client, fetchFn, budget } = contentHarness(bytes)
    fetchFn.mockResolvedValueOnce(rateLimited('7'))

    const pending = client.read(READ_ARGS, { budget })
    await vi.advanceTimersByTimeAsync(0)
    expect(setTimeoutSpy.mock.calls.map(call => call[1])).toContain(7000)
    await vi.advanceTimersByTimeAsync(6999)
    expect(fetchFn).toHaveBeenCalledTimes(1)
    await vi.advanceTimersByTimeAsync(1)
    const file = await pending
    expect(fetchFn).toHaveBeenCalledTimes(3)
    expect(file.bytes).toEqual(bytes)
    file.reservation.release()
    expect(budget.residentBytes).toBe(0)
  })

  it('retries a content 429 without discarding the validated metadata snapshot', async () => {
    vi.useFakeTimers()
    const bytes = Buffer.from('content after retry')
    let contentCalls = 0
    const { client, fetchFn, budget } = contentHarness(bytes, {
      response: () =>
        ++contentCalls === 1
          ? rateLimited('2')
          : new Response(new Uint8Array(bytes), {
              headers: {
                'x-gfs-uri': FILE_URI,
                'x-gfs-version': '3',
                'content-length': String(bytes.length),
              },
            }),
    })
    const pending = client.read(READ_ARGS, { budget })
    await vi.advanceTimersByTimeAsync(0)
    expect(fetchFn).toHaveBeenCalledTimes(2)
    await vi.advanceTimersByTimeAsync(2000)
    const file = await pending
    expect(fetchFn).toHaveBeenCalledTimes(3)
    expect(file.source).toMatchObject({ gfsUri: FILE_URI, version: 3 })
    expect(file.bytes).toEqual(bytes)
    file.reservation.release()
    expect(budget.residentBytes).toBe(0)
  })

  it('rejects a changed content version after retry', async () => {
    vi.useFakeTimers()
    const bytes = Buffer.from('replaced content')
    let contentCalls = 0
    const { client, budget } = contentHarness(bytes, {
      response: () =>
        ++contentCalls === 1
          ? rateLimited('1')
          : new Response(new Uint8Array(bytes), {
              headers: {
                'x-gfs-uri': FILE_URI,
                'x-gfs-version': '4',
                'content-length': String(bytes.length),
              },
            }),
    })
    const pending = client.read(READ_ARGS, { budget })
    const failure = expect(pending).rejects.toMatchObject({ code: 'version_conflict' })
    await vi.advanceTimersByTimeAsync(1000)
    await failure
    expect(contentCalls).toBe(2)
    expect(budget.residentBytes).toBe(0)
  })

  it('bounds a 429 error body before deciding whether its header permits retry', async () => {
    vi.useFakeTimers()
    const bytes = Buffer.from('bounded retry')
    const { client, fetchFn, budget } = contentHarness(bytes)
    fetchFn.mockResolvedValueOnce(
      new Response('x'.repeat(VISUAL_INPUT_LIMITS.errorBytes + 1), {
        status: 429,
        headers: { 'retry-after': '1', 'x-gfs-ratelimit-scope': 'agent_reads' },
      })
    )
    const pending = client.read(READ_ARGS, { budget })
    await vi.advanceTimersByTimeAsync(0)
    expect(fetchFn).toHaveBeenCalledTimes(1)
    await vi.advanceTimersByTimeAsync(1000)
    const file = await pending
    expect(file.bytes).toEqual(bytes)
    expect(fetchFn).toHaveBeenCalledTimes(3)
    file.reservation.release()
    expect(budget.residentBytes).toBe(0)
  })

  it('cancels a read during Retry-After without issuing another request', async () => {
    vi.useFakeTimers()
    const { client, fetchFn, budget } = contentHarness(Buffer.from('never read'))
    fetchFn.mockResolvedValueOnce(rateLimited('20'))
    const controller = new AbortController()
    const pending = client.read(READ_ARGS, { budget, signal: controller.signal })
    await vi.advanceTimersByTimeAsync(0)
    expect(fetchFn).toHaveBeenCalledTimes(1)
    controller.abort()
    await expect(pending).rejects.toMatchObject({ code: 'cancelled' })
    expect(fetchFn).toHaveBeenCalledTimes(1)
    expect(budget.residentBytes).toBe(0)
  })

  it('bounds a hanging 429 body by the single read deadline', async () => {
    vi.useFakeTimers()
    const { client, fetchFn, budget } = contentHarness(Buffer.from('never read'))
    fetchFn.mockResolvedValueOnce(
      new Response(new ReadableStream<Uint8Array>({ start() {} }), {
        status: 429,
        headers: { 'retry-after': '1', 'x-gfs-ratelimit-scope': 'agent_reads' },
      })
    )
    const pending = client.read(READ_ARGS, { budget, timeoutMs: 10 })
    const failure = expect(pending).rejects.toMatchObject({ code: 'timeout' })
    await vi.advanceTimersByTimeAsync(10)
    await failure
    expect(fetchFn).toHaveBeenCalledTimes(1)
    expect(budget.residentBytes).toBe(0)
  })

  it('gives up after one retry and keeps the hint on the thrown error', async () => {
    vi.useFakeTimers()
    const fetchFn = vi.fn(async () => rateLimited('2'))
    const client = createGfscClient(tokenEnv(fetchFn), clientOptions)

    const rejection = expect(
      client.write({ drive: 'main', resourceId: 'rid', content: 'x', ifMatch: 1 })
    ).rejects.toMatchObject({
      name: 'GfscHttpError',
      status: 429,
      retryAfterSeconds: 2,
      message: expect.stringMatching(/^gfsc 429: .* \(retry after 2s\)$/),
    })
    await vi.advanceTimersByTimeAsync(2000)
    await rejection
    await vi.advanceTimersByTimeAsync(60_000)
    expect(fetchFn).toHaveBeenCalledTimes(2)
  })

  it.each([
    ['absent', undefined],
    ['an HTTP-date', 'Wed, 23 Sep 2026 10:00:00 GMT'],
    ['zero', '0'],
    ['fractional', '1.5'],
  ])('throws at once without retrying when Retry-After is %s', async (_label, retryAfter) => {
    vi.useFakeTimers()
    const answers = [rateLimited(retryAfter), rateLimited('1'), jsonResponse({ ok: true })]
    const fetchFn = vi.fn(async () => answers.shift()!)
    const client = createGfscClient(tokenEnv(fetchFn), clientOptions)

    const error = await client.stat({ drive: 'main', resourceId: 'rid' }).catch(e => e)
    expect(error).toBeInstanceOf(GfscHttpError)
    expect(error).toMatchObject({ status: 429, retryAfterSeconds: undefined })
    expect(fetchFn).toHaveBeenCalledTimes(1)
    expect(vi.getTimerCount()).toBe(0)

    // Control on the same client: a 429 with a usable hint is retried, so
    // the single call above is the hint check at work, not a missing retry.
    const control = client.stat({ drive: 'main', resourceId: 'rid' })
    await vi.advanceTimersByTimeAsync(1000)
    await expect(control).resolves.toEqual({ ok: true })
    expect(fetchFn).toHaveBeenCalledTimes(3)
  })

  it('throws at once with the hint when Retry-After exceeds the tool budget', async () => {
    vi.useFakeTimers()
    const answers = [rateLimited('30'), rateLimited('10'), jsonResponse({ ok: true })]
    const fetchFn = vi.fn(async () => answers.shift()!)
    const client = createGfscClient(tokenEnv(fetchFn), { maxRetryWaitMs: 10_000, random: () => 0 })

    const error = await client.stat({ drive: 'main', resourceId: 'rid' }).catch(e => e)
    expect(error).toMatchObject({ status: 429, retryAfterSeconds: 30 })
    expect((error as Error).message).toContain('(retry after 30s)')
    expect(fetchFn).toHaveBeenCalledTimes(1)
    expect(vi.getTimerCount()).toBe(0)

    // Control at the boundary: a delay equal to the budget is still waited out.
    const control = client.stat({ drive: 'main', resourceId: 'rid' })
    await vi.advanceTimersByTimeAsync(10_000)
    await expect(control).resolves.toEqual({ ok: true })
    expect(fetchFn).toHaveBeenCalledTimes(3)
  })

  it('does not retry any other status, even with a Retry-After header', async () => {
    vi.useFakeTimers()
    const answers = [
      new Response('unavailable', { status: 503, headers: { 'retry-after': '2' } }),
      rateLimited('2'),
      jsonResponse({ ok: true }),
    ]
    const fetchFn = vi.fn(async () => answers.shift()!)
    const client = createGfscClient(tokenEnv(fetchFn), clientOptions)

    const error = await client.stat({ drive: 'main', resourceId: 'rid' }).catch(e => e)
    expect(error).toMatchObject({ status: 503, message: 'gfsc 503: unavailable' })
    expect(error).toMatchObject({ retryAfterSeconds: undefined })
    expect(fetchFn).toHaveBeenCalledTimes(1)
    expect(vi.getTimerCount()).toBe(0)

    // Control: the same header on a 429 is honoured.
    const control = client.stat({ drive: 'main', resourceId: 'rid' })
    await vi.advanceTimersByTimeAsync(2000)
    await expect(control).resolves.toEqual({ ok: true })
    expect(fetchFn).toHaveBeenCalledTimes(3)
  })

  it('rejects a construction without a usable retry budget', () => {
    const env = tokenEnv(vi.fn(async () => jsonResponse({})))
    expect(() => createGfscClient(env, { maxRetryWaitMs: Number.NaN })).toThrow(
      /maxRetryWaitMs must be a non-negative number/
    )
    expect(() => createGfscClient(env, { maxRetryWaitMs: -1 })).toThrow(
      /maxRetryWaitMs must be a non-negative number/
    )
    expect(createGfscClient(env, { maxRetryWaitMs: 0 })).toHaveProperty('stat')
  })
})

describe('gfsc client retry: cancellation, deadline, scope and jitter', () => {
  afterEach(() => {
    vi.useRealTimers()
    vi.restoreAllMocks()
  })

  it('M1: an abort during the Retry-After sleep rejects at once and never sends the retry', async () => {
    vi.useFakeTimers()
    const fetchFn = vi.fn(async () => rateLimited('45', 'agent_writes'))
    const client = createGfscClient(tokenEnv(fetchFn), clientOptions)
    const controller = new AbortController()

    const pending = client
      .write(
        { drive: 'main', resourceId: 'rid', content: 'x', ifMatch: 1 },
        { signal: controller.signal }
      )
      .catch(e => e)
    await vi.advanceTimersByTimeAsync(0)
    // Witness: the first attempt was sent and the client is now sleeping.
    expect(fetchFn).toHaveBeenCalledTimes(1)
    expect(vi.getTimerCount()).toBe(1)

    controller.abort()
    const error = await pending
    expect(error).toBeInstanceOf(DOMException)
    expect((error as DOMException).name).toBe('AbortError')
    expect(vi.getTimerCount()).toBe(0)
    await vi.advanceTimersByTimeAsync(60_000)
    expect(fetchFn).toHaveBeenCalledTimes(1)
  })

  it('M1: the caller signal reaches both the first request and the retry', async () => {
    vi.useFakeTimers()
    const signals: Array<AbortSignal | null | undefined> = []
    const fetchFn = vi.fn(async (_input: string, init?: RequestInit) => {
      signals.push(init?.signal)
      return signals.length === 1 ? rateLimited('2') : jsonResponse({ ok: true })
    })
    const client = createGfscClient(tokenEnv(fetchFn), clientOptions)
    const controller = new AbortController()

    const pending = client.stat({ drive: 'main', resourceId: 'rid' }, { signal: controller.signal })
    await vi.advanceTimersByTimeAsync(2000)
    await expect(pending).resolves.toEqual({ ok: true })
    expect(signals).toEqual([controller.signal, controller.signal])
  })

  it('M1: a Retry-After beyond the remaining deadline fails at once', async () => {
    vi.useFakeTimers()
    const fetchFn = vi.fn(async () => rateLimited('2'))
    const client = createGfscClient(tokenEnv(fetchFn), clientOptions)

    const error = await client
      .stat({ drive: 'main', resourceId: 'rid' }, { deadlineMs: Date.now() + 1500 })
      .catch(e => e)
    expect(error).toMatchObject({ status: 429, retryAfterSeconds: 2 })
    expect(fetchFn).toHaveBeenCalledTimes(1)
    expect(vi.getTimerCount()).toBe(0)
  })

  it('M1: the jittered wait is cut at the remaining deadline', async () => {
    vi.useFakeTimers()
    const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout')
    let calls = 0
    const fetchFn = vi.fn(async () => (++calls === 1 ? rateLimited('2') : jsonResponse({})))
    const client = createGfscClient(tokenEnv(fetchFn), {
      maxRetryWaitMs: 60_000,
      random: () => 0.5,
    })

    const pending = client.stat(
      { drive: 'main', resourceId: 'rid' },
      { deadlineMs: Date.now() + 2100 }
    )
    await vi.advanceTimersByTimeAsync(0)
    // 2000 ms + 200 ms of jitter would pass the deadline, so the wait is 2100 ms.
    expect(setTimeoutSpy.mock.calls.map(call => call[1])).toEqual([2100])
    await vi.advanceTimersByTimeAsync(2100)
    await expect(pending).resolves.toEqual({})
    expect(fetchFn).toHaveBeenCalledTimes(2)
  })

  // Every method, not only stat: a method that drops `call` would sleep past
  // the step's remaining time and could not be cancelled.
  const EVERY_METHOD: Array<[string, (client: GfscWriteClient, call: GfscCallOptions) => unknown]> =
    [
      ['accessible', (client, call) => client.accessible({ drive: 'main' }, call)],
      ['list', (client, call) => client.list({ drive: 'main', resourceId: 'rid' }, call)],
      ['stat', (client, call) => client.stat({ drive: 'main', resourceId: 'rid' }, call)],
      ['resolve', (client, call) => client.resolve({ uri: 'gfs://main/a.txt' }, call)],
      [
        'write',
        (client, call) =>
          client.write({ drive: 'main', resourceId: 'rid', content: 'x', ifMatch: 1 }, call),
      ],
      [
        'createFile',
        (client, call) =>
          client.createFile(
            { drive: 'main', parentResourceId: 'pid', name: 'a.txt', content: 'x' },
            call
          ),
      ],
      [
        'createFolder',
        (client, call) =>
          client.createFolder({ drive: 'main', parentResourceId: 'pid', name: 'dir' }, call),
      ],
      [
        'rename',
        (client, call) =>
          client.rename({ drive: 'main', resourceId: 'rid', newName: 'b.txt', ifMatch: 1 }, call),
      ],
      [
        'copy',
        (client, call) =>
          client.copy(
            {
              drive: 'main',
              sourceResourceId: 'rid',
              destinationParentId: 'pid',
              ifMatch: 1,
            },
            call
          ),
      ],
    ]

  it.each(EVERY_METHOD)('M1: %s passes the caller signal to fetch', async (_name, invoke) => {
    const signals: Array<AbortSignal | null | undefined> = []
    const fetchFn = vi.fn(async (_input: string, init?: RequestInit) => {
      signals.push(init?.signal)
      return jsonResponse({ ok: true })
    })
    const client = createGfscClient(tokenEnv(fetchFn), clientOptions)
    const controller = new AbortController()

    await expect(invoke(client, { signal: controller.signal })).resolves.toEqual({ ok: true })
    expect(signals).toEqual([controller.signal])
  })

  it('M1: read shares one cancel signal across metadata and content', async () => {
    const bytes = Buffer.from('granted file content')
    const { client, fetchFn, budget } = contentHarness(bytes)
    const controller = new AbortController()
    const file = await client.read(READ_ARGS, { budget, signal: controller.signal })
    const signals = fetchFn.mock.calls.map(([, init]) => init?.signal)
    expect(signals).toHaveLength(2)
    expect(signals[0]).toBe(signals[1])
    expect(signals[0]).not.toBe(controller.signal)
    file.reservation.release()
  })

  it('M1: read refuses a retry beyond the caller deadline', async () => {
    const { client, fetchFn, budget } = contentHarness(Buffer.from('body'))
    fetchFn.mockResolvedValueOnce(rateLimited('2'))
    const error = await client
      .read(READ_ARGS, { budget, deadlineMs: Date.now() + 1500 })
      .catch(e => e)
    expect(error).toMatchObject({ status: 429, retryAfterSeconds: 2 })
    expect(fetchFn).toHaveBeenCalledTimes(1)
    expect(budget.residentBytes).toBe(0)
  })

  it('keeps the typed 429 hint when content retry cannot fit the read deadline', async () => {
    const { client, fetchFn, budget } = contentHarness(Buffer.from('body'), {
      response: () => rateLimited('2'),
    })
    const error = await client
      .read(READ_ARGS, { budget, deadlineMs: Date.now() + 1500 })
      .catch(e => e)
    expect(error).toMatchObject({ status: 429, retryAfterSeconds: 2 })
    expect(fetchFn).toHaveBeenCalledTimes(2)
    expect(budget.residentBytes).toBe(0)
  })

  it.each(EVERY_METHOD)('M1: %s bounds the retry by the caller deadline', async (_name, invoke) => {
    vi.useFakeTimers()
    const fetchFn = vi.fn(async () => rateLimited('2', 'agent_writes'))
    const client = createGfscClient(tokenEnv(fetchFn), clientOptions)

    // Retry-After 2 s is within maxRetryWaitMs but not within the deadline.
    const error = await Promise.resolve(invoke(client, { deadlineMs: Date.now() + 1500 })).catch(
      e => e
    )
    expect(error).toMatchObject({ status: 429, retryAfterSeconds: 2 })
    expect(fetchFn).toHaveBeenCalledTimes(1)
    expect(vi.getTimerCount()).toBe(0)
  })

  it('L17: the retry waits Retry-After plus the injected jitter', async () => {
    vi.useFakeTimers()
    const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout')
    let calls = 0
    const fetchFn = vi.fn(async () => (++calls === 1 ? rateLimited('2') : jsonResponse({})))
    const client = createGfscClient(tokenEnv(fetchFn), {
      maxRetryWaitMs: 60_000,
      random: () => 0.5,
    })

    const pending = client.stat({ drive: 'main', resourceId: 'rid' })
    await vi.advanceTimersByTimeAsync(0)
    // Jitter is random × min(1000, 0.2 × 2000) = 0.5 × 400 = 200 ms.
    expect(setTimeoutSpy.mock.calls.map(call => call[1])).toEqual([2200])
    await vi.advanceTimersByTimeAsync(2199)
    expect(fetchFn).toHaveBeenCalledTimes(1)
    await vi.advanceTimersByTimeAsync(1)
    expect(fetchFn).toHaveBeenCalledTimes(2)
    await expect(pending).resolves.toEqual({})
  })

  it('L17: the jitter never exceeds one second for long delays', async () => {
    vi.useFakeTimers()
    const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout')
    let calls = 0
    const fetchFn = vi.fn(async () => (++calls === 1 ? rateLimited('30') : jsonResponse({})))
    const client = createGfscClient(tokenEnv(fetchFn), {
      maxRetryWaitMs: 60_000,
      random: () => 0.999,
    })

    const pending = client.stat({ drive: 'main', resourceId: 'rid' })
    await vi.advanceTimersByTimeAsync(0)
    expect(setTimeoutSpy.mock.calls.map(call => call[1])).toEqual([30_999])
    await vi.advanceTimersByTimeAsync(30_999)
    await expect(pending).resolves.toEqual({})
  })

  it.each(['active_sessions_subject', 'upload_bytes_subject', undefined])(
    'L16/I1: a 429 with scope %s is surfaced at once with its hint',
    async scope => {
      vi.useFakeTimers()
      const headers: Record<string, string> = { 'retry-after': '2' }
      if (scope !== undefined) headers['x-gfs-ratelimit-scope'] = scope
      const answers = [
        new Response('{}', { status: 429, headers }),
        rateLimited('2', 'agent_reads'),
        jsonResponse({ ok: true }),
      ]
      const fetchFn = vi.fn(async () => answers.shift()!)
      const client = createGfscClient(tokenEnv(fetchFn), clientOptions)

      const error = await client.stat({ drive: 'main', resourceId: 'rid' }).catch(e => e)
      expect(error).toMatchObject({ status: 429, retryAfterSeconds: 2 })
      expect(fetchFn).toHaveBeenCalledTimes(1)
      expect(vi.getTimerCount()).toBe(0)

      // Control on the same client: an agent scope is retried.
      const control = client.stat({ drive: 'main', resourceId: 'rid' })
      await vi.advanceTimersByTimeAsync(2000)
      await expect(control).resolves.toEqual({ ok: true })
      expect(fetchFn).toHaveBeenCalledTimes(3)
    }
  )

  it('L15: Retry-After accepts 1..3600 and drops anything larger', async () => {
    vi.useFakeTimers()
    const values = ['1', '3600', '3601', '99999', '100000000000000000000000']
    const fetchFn = vi.fn(async () => rateLimited(values.shift()!))
    // maxRetryWaitMs 0 means no retry is ever slept, so only the parse is observed.
    const client = createGfscClient(tokenEnv(fetchFn), { maxRetryWaitMs: 0, random: () => 0 })
    const hintFor = async (value: string) => {
      expect(values[0]).toBe(value)
      const error = (await client
        .stat({ drive: 'main', resourceId: 'rid' })
        .catch(e => e)) as GfscHttpError
      expect(error).toBeInstanceOf(GfscHttpError)
      return error.retryAfterSeconds
    }

    expect(await hintFor('1')).toBe(1)
    expect(await hintFor('3600')).toBe(3600)
    expect(await hintFor('3601')).toBeUndefined()
    expect(await hintFor('99999')).toBeUndefined()
    expect(await hintFor('100000000000000000000000')).toBeUndefined()
    expect(fetchFn).toHaveBeenCalledTimes(5)
  })

  it.each([
    [
      'write',
      'PUT',
      'http://gfsc-writer.gfs.svc.cluster.local:8087/v1/resources/rid/content?drive=main',
    ],
    [
      'createFile',
      'POST',
      'http://gfsc-writer.gfs.svc.cluster.local:8087/v1/resources/parent/children?drive=main',
    ],
  ] as const)(
    'M6: the %s retry repeats the same method, URL, body and credential',
    async (method, verb, url) => {
      vi.useFakeTimers()
      const sent: Array<{ url: string; init: RequestInit }> = []
      const fetchFn = vi.fn(async (input: string, init?: RequestInit) => {
        sent.push({ url: input, init: init! })
        return sent.length === 1 ? rateLimited('2', 'agent_writes') : jsonResponse({ ok: true })
      })
      const client = createGfscClient(tokenEnv(fetchFn), clientOptions)

      const pending =
        method === 'write'
          ? client.write({ drive: 'main', resourceId: 'rid', content: 'body-1', ifMatch: 7 })
          : client.createFile({
              drive: 'main',
              parentResourceId: 'parent',
              name: 'a.txt',
              content: 'body-1',
            })
      await vi.advanceTimersByTimeAsync(2000)
      await expect(pending).resolves.toEqual({ ok: true })

      expect(sent).toHaveLength(2)
      const [first, retry] = sent.map(({ url: sentUrl, init }) => ({
        url: sentUrl,
        method: init.method,
        body: init.body,
        authorization: (init.headers as Record<string, string>).authorization,
      }))
      expect(first).toEqual({
        url,
        method: verb,
        body: expect.stringContaining('"body-1"'),
        authorization: 'Bearer gfs-access',
      })
      expect(retry).toEqual(first)
    }
  )
})