Skip to content

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

TypeScript

Merge remote-tracking branch 'origin/dev' into chore/pr670-dev-sync-20260923

Alfredo Lopeza92a671c8893
diff --cc mcp-host/package-lock.json
index f6200ec47,38ed97aaf..cdf849455
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@@ -1,12 -1,12 +1,12 @@@
{
"name": "clerum-mcp-host",
- "version": "0.1.376",
- "version": "0.1.373",
++ "version": "0.1.377",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.376",
- "version": "0.1.373",
++ "version": "0.1.377",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --cc mcp-host/package.json
index 4d3f5cb58,4f4971423..089536792
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@@ -1,6 -1,6 +1,6 @@@
{
"name": "clerum-mcp-host",
- "version": "0.1.376",
- "version": "0.1.373",
++ "version": "0.1.377",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --cc mcp-host/src/core/tools/__tests__/nativeToolRegistry.gfsCallBounds.test.ts
index 000000000,d98a82129..180cc2ca8
mode 000000,100644..100644
--- a/mcp-host/src/core/tools/__tests__/nativeToolRegistry.gfsCallBounds.test.ts
+++ b/mcp-host/src/core/tools/__tests__/nativeToolRegistry.gfsCallBounds.test.ts
@@@ -1,0 -1,77 +1,126 @@@
+ import { afterEach, describe, expect, it, vi } from 'vitest'
++import { createCanvas } from '@napi-rs/canvas'
+ import { createGfscClient } from '../../../internalTools/gfsClient'
++import { VisualInputBudget } from '../../../visualInput/policy'
+ import type { NativeToolConfig } from '../../interfaces'
+ import { NativeToolRegistry } from '../nativeToolRegistry'
+
+ /**
+ * The chat path: the tool-use loop hands each tool an ExecutionContext with the
+ * turn's cancel signal and its remaining time. A GFS tool must pass both to the
+ * gfsc client, so a 429 retry never outlives the turn that asked for it.
+ */
+
+ const gfsClient = vi.hoisted(() => ({
+ accessible: vi.fn(),
+ list: vi.fn(),
+ read: vi.fn(),
+ stat: vi.fn(),
+ resolve: vi.fn(),
+ }))
+
+ vi.mock('../../../internalTools/gfsClient', async importOriginal => ({
+ ...(await importOriginal<typeof import('../../../internalTools/gfsClient')>()),
+ createGfscClient: vi.fn(() => gfsClient),
+ }))
+
+ const ACCESS_ENV = `MCP_HOST_GFS_${String.fromCharCode(84, 79, 75, 69, 78)}`
+ const previousAccess = process.env[ACCESS_ENV]
+
+ 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`
+ }
+
+ const config: NativeToolConfig = {
+ workspacePath: '/tmp',
+ shellTimeout: 5000,
+ toolTimeout: 60000,
+ toolProgressInterval: 30000,
+ httpAllowlist: [],
+ envAllowlist: ['PATH'],
+ memoryMaxSize: 1048576,
+ }
+
+ afterEach(() => {
+ vi.restoreAllMocks()
+ vi.mocked(createGfscClient).mockClear()
++ gfsClient.read.mockReset()
+ gfsClient.stat.mockReset()
+ if (previousAccess === undefined) delete process.env[ACCESS_ENV]
+ else process.env[ACCESS_ENV] = previousAccess
+ })
+
+ describe('NativeToolRegistry GFS call bounds', () => {
+ it('caps a single Retry-After at the tool timeout and passes the turn signal and deadline', async () => {
+ process.env[ACCESS_ENV] = encodedClaims(['gfs.read'])
+ const T = 1_900_000_000_000
+ vi.spyOn(Date, 'now').mockReturnValue(T)
+ gfsClient.stat.mockResolvedValue({ resourceId: 'rid' })
+ const registry = new NativeToolRegistry(config, 'gfs-call-bounds-test')
+ const tool = registry.get('clerum__gfs_stat')
+ if (!tool) throw new Error('clerum__gfs_stat is not registered')
+ const controller = new AbortController()
+
+ const output = await tool.execute(
+ { drive: 'main', resourceId: 'rid' },
+ { signal: controller.signal, timeoutMs: 45_000, onOutput: () => undefined }
+ )
+
+ expect(output.is_error).toBe(false)
+ expect(createGfscClient).toHaveBeenCalledTimes(1)
+ expect(vi.mocked(createGfscClient).mock.calls[0]?.[1]).toEqual({ maxRetryWaitMs: 60_000 })
+ expect(gfsClient.stat).toHaveBeenCalledTimes(1)
+ const [args, call] = gfsClient.stat.mock.calls[0] ?? []
+ expect(args).toEqual({ drive: 'main', resourceId: 'rid' })
+ expect(call).toEqual({ signal: controller.signal, deadlineMs: T + 45_000 })
+ expect(call.signal).toBe(controller.signal)
+ })
++
++ it('passes chat visual context and the same call bounds to GFS image reads', async () => {
++ process.env[ACCESS_ENV] = encodedClaims(['gfs.read'])
++ const T = 1_900_000_000_000
++ vi.spyOn(Date, 'now').mockReturnValue(T)
++ const bytes = createCanvas(1, 1).toBuffer('image/png')
++ const source = {
++ kind: 'gfs' as const,
++ drive: 'main',
++ resourceId: 'a'.repeat(32),
++ gfsUri: `gfs://main/${'a'.repeat(32)}`,
++ version: 1,
++ name: 'picture.png',
++ }
++ const release = vi.fn()
++ gfsClient.read.mockResolvedValue({ source, bytes, reservation: { release } })
++ const registry = new NativeToolRegistry(config, 'gfs-visual-context-test')
++ const tool = registry.get('clerum__gfs_read')
++ if (!tool) throw new Error('clerum__gfs_read is not registered')
++ const controller = new AbortController()
++ const budget = new VisualInputBudget()
++ const resolveCapability = vi.fn(async () => ({ status: 'unsupported' as const }))
++
++ const output = await tool.execute(
++ { drive: 'main', resourceId: source.resourceId },
++ {
++ signal: controller.signal,
++ timeoutMs: 45_000,
++ visualInput: { budget, resolveCapability },
++ onOutput: () => undefined,
++ }
++ )
++
++ expect(output.is_error).toBe(false)
++ expect(JSON.parse(output.content)).toMatchObject({
++ delivery: 'reference_only',
++ reason: 'model_image_input_unsupported',
++ })
++ expect(gfsClient.read).toHaveBeenCalledWith(
++ { drive: 'main', resourceId: source.resourceId },
++ { signal: controller.signal, deadlineMs: T + 45_000, timeoutMs: 45_000, budget }
++ )
++ expect(resolveCapability).toHaveBeenCalledOnce()
++ expect(resolveCapability).toHaveBeenCalledWith(controller.signal)
++ expect(release).toHaveBeenCalledOnce()
++ })
+ })
diff --cc mcp-host/src/internalTools/gfs.test.ts
index 3c596796c,a1804f26d..8c8fed1d9
--- a/mcp-host/src/internalTools/gfs.test.ts
+++ b/mcp-host/src/internalTools/gfs.test.ts
@@@ -97,91 -108,37 +121,122 @@@ describe('buildGfsReadTools', () =>
expect(r.error).not.toContain('blob/key')
})
+ it('returns typed image input when the destination supports vision', async () => {
+ const canvas = createCanvas(2, 2)
+ canvas.getContext('2d').fillRect(0, 0, 2, 2)
+ const bytes = canvas.toBuffer('image/png')
+ const source = {
+ kind: 'gfs' as const,
+ drive: 'main',
+ resourceId: 'a'.repeat(32),
+ gfsUri: `gfs://main/${'a'.repeat(32)}`,
+ version: 2,
+ name: 'pic.png',
+ }
+ const reservation = { release: vi.fn() }
+ const c = client({
+ read: vi.fn(async () => ({ source, bytes, reservation })),
+ })
+ const r = await toolMap(c)
+ .get('clerum__gfs_read')!
+ .execute({ drive: 'main', resourceId: source.resourceId }, '', {
+ visualInput: {
+ budget: new VisualInputBudget(),
+ resolveCapability: async () => ({
+ status: 'supported',
+ provider: 'openai',
+ model: 'gpt-4.1',
+ evidence: 'unit',
+ }),
+ },
+ })
+ expect(r.success).toBe(true)
+ expect(JSON.parse(r.content as string).delivery).toBe('image_input')
+ expect(r.images?.[0]).toMatchObject({ mimeType: 'image/png', source })
+ expect(reservation.release).toHaveBeenCalledOnce()
+ })
+
+ it.each(['<svg/>', '<svg />', '<SVG/>', '\uFEFF<svg/>'])(
+ 'returns a reference for self-closing SVG %j',
+ async text => {
+ const c = client({
+ read: vi.fn(async () => ({
+ source: {
+ kind: 'gfs' as const,
+ drive: 'main',
+ resourceId: 'a'.repeat(32),
+ gfsUri: `gfs://main/${'a'.repeat(32)}`,
+ version: 2,
+ name: 'icon.svg',
+ },
+ bytes: Buffer.from(text),
+ reservation: { release: vi.fn() },
+ })),
+ })
+ const r = await toolMap(c)
+ .get('clerum__gfs_read')!
+ .execute({ drive: 'main', resourceId: 'abc' }, '')
+ expect(r.success).toBe(true)
+ expect(JSON.parse(r.content as string)).toMatchObject({
+ delivery: 'reference_only',
+ reason: 'svg_visual_input_not_supported',
+ })
+ }
+ )
+
+ it('strips a UTF-8 BOM from otherwise valid text', async () => {
+ const c = client({
+ read: vi.fn(async () => ({
+ source: {
+ kind: 'gfs' as const,
+ drive: 'main',
+ resourceId: 'a'.repeat(32),
+ gfsUri: `gfs://main/${'a'.repeat(32)}`,
+ version: 2,
+ name: 'note.txt',
+ },
+ bytes: Buffer.from('\uFEFFhello'),
+ reservation: { release: vi.fn() },
+ })),
+ })
+ const r = await toolMap(c)
+ .get('clerum__gfs_read')!
+ .execute({ drive: 'main', resourceId: 'abc' }, '')
+ expect(r.success).toBe(true)
+ expect(r.content).toBe('hello')
+ })
+
+ it('passes a 429 retry hint to the model and still redacts the body', async () => {
+ const c = client({
+ read: vi.fn(async () => {
+ throw new GfscHttpError(429, 'rate limited on /internal/server/path blob/key', 30)
+ }),
+ })
+ const r = await toolMap(c)
+ .get('clerum__gfs_read')!
+ .execute({ drive: 'main', resourceId: 'abc' }, '')
+ expect(r.success).toBe(false)
+ expect(r.error).toBe('GFS read failed (gfsc 429: rate_limited, retry after 30s)')
+ expect(r.error).not.toContain('/internal/server/path')
+ expect(r.error).not.toContain('blob/key')
+ })
+
+ it.each([
+ [429, 'rate_limited'],
+ [400, 'invalid_request'],
+ [503, 'unavailable'],
+ ])('maps gfsc %s without a hint to %s', async (status, category) => {
+ const c = client({
+ stat: vi.fn(async () => {
+ throw new GfscHttpError(status, 'private path=/data/gfs/secret')
+ }),
+ })
+ const r = await toolMap(c)
+ .get('clerum__gfs_stat')!
+ .execute({ drive: 'main', resourceId: 'abc' }, '')
+ expect(r).toEqual({ success: false, error: `GFS read failed (gfsc ${status}: ${category})` })
+ })
+
it('strips a non-gfsc-shaped read error down to the generic label', async () => {
const c = client({
read: vi.fn(async () => {
diff --cc mcp-host/src/internalTools/gfs.ts
index c47e8ed76,9587853c6..30ceee07d
--- a/mcp-host/src/internalTools/gfs.ts
+++ b/mcp-host/src/internalTools/gfs.ts
@@@ -1,7 -1,9 +1,13 @@@
+import { inspectImage, validateImage } from '../visualInput/imageValidation'
+import { VisualInputError } from '../visualInput/policy'
- import type { InternalToolDefinition, InternalToolResult } from '../workflow/types'
+ import type {
+ InternalToolCallContext,
+ InternalToolDefinition,
++ InternalToolExecutionOptions,
+ InternalToolResult,
+ } from '../workflow/types'
+ import { GfscHttpError } from './gfsClient'
+import type { GfsFileContent, GfsReadOptions } from './gfsReadTypes'
/**
* Agent gfs READ tools (spec community.md §Operator surfaces, plan P3-S04).
@@@ -11,16 -13,34 +17,37 @@@
* stable `gfsUri` so links survive rename/move.
*/
+ /**
+ * Per-call bounds from the tool call that issues the request. `signal` cancels
+ * the request and any 429 retry sleep; `deadlineMs` (epoch ms) is when the
+ * calling tool's budget ends, so a retry never sleeps past it.
+ */
+ export interface GfscCallOptions {
+ signal?: AbortSignal
+ deadlineMs?: number
+ }
+
/** The gfsc read surface, injected so the tools are unit-tested without gfsc. */
export interface GfscReadClient {
- accessible(args: { drive: string; cursor?: string }): Promise<unknown>
- list(args: { drive: string; resourceId: string; cursor?: string }): Promise<unknown>
+ accessible(args: { drive: string; cursor?: string }, call?: GfscCallOptions): Promise<unknown>
+ list(
+ args: { drive: string; resourceId: string; cursor?: string },
+ call?: GfscCallOptions
+ ): Promise<unknown>
- read(args: { drive: string; resourceId: string }, call?: GfscCallOptions): Promise<unknown>
+ read(
+ args: { drive: string; resourceId: string },
+ options?: GfsReadOptions
+ ): Promise<GfsFileContent>
- stat(args: { drive: string; resourceId: string }): Promise<unknown>
- resolve(args: { uri: string }): Promise<unknown>
+ stat(args: { drive: string; resourceId: string }, call?: GfscCallOptions): Promise<unknown>
+ resolve(args: { uri: string }, call?: GfscCallOptions): Promise<unknown>
+ }
+
+ /** Turns a tool call's execution context into the client's per-call bounds. */
+ function callOptions(context?: InternalToolCallContext): GfscCallOptions {
+ return {
+ signal: context?.signal,
+ deadlineMs: context?.timeoutMs === undefined ? undefined : Date.now() + context.timeoutMs,
+ }
}
function ok(content: unknown): InternalToolResult {
@@@ -134,70 -129,19 +177,74 @@@ export function buildGfsReadTools(clien
},
{
name: 'clerum__gfs_read',
- description: 'Read a gfs file by drive + resourceId (read-only).',
+ description:
+ 'Read a GFS file by drive + resourceId. Returns UTF-8 text, or a bounded JPEG/PNG image when the active model supports image input. Other binary formats return a reference; malformed or unsupported JPEG/PNG returns an error.',
parameters: driveResourceParams,
- execute: async (args, _outputDir, options): Promise<InternalToolResult> => {
+ execute: async (
+ args: Record<string, unknown>,
+ _outputDir: string,
- context?: InternalToolCallContext
++ options?: InternalToolExecutionOptions
+ ): Promise<InternalToolResult> => {
+ let file: GfsFileContent | undefined
try {
- return ok(
- await client.read(args as { drive: string; resourceId: string }, callOptions(context))
- )
+ file = await client.read(args as { drive: string; resourceId: string }, {
- signal: options?.signal,
++ ...callOptions(options),
+ timeoutMs: options?.timeoutMs,
+ budget: options?.readBudget ?? options?.visualInput?.budget,
+ })
+ if (options?.signal?.aborted) throw new VisualInputError('cancelled')
+ const image = inspectImage(file.bytes)
+ if (image) {
+ const visualInput = options?.visualInput
+ if (!visualInput)
+ return fileReference(file, 'image_input_unavailable_in_this_execution')
+ const capability = await visualInput.resolveCapability(options?.signal)
+ if (options?.signal?.aborted) throw new VisualInputError('cancelled')
+ if (capability.status !== 'supported')
+ return fileReference(file, `model_image_input_${capability.status}`)
+ await validateImage(file.bytes, image, {
+ signal: options?.signal,
+ budget: visualInput.budget,
+ })
+ if (options?.signal?.aborted) throw new VisualInputError('cancelled')
+ const dataBase64 = visualInput.budget.encodeImage(file.bytes)
+ return {
+ success: true,
+ content: JSON.stringify({
+ resource: file.source,
+ mimeType: image.mimeType,
+ width: image.width,
+ height: image.height,
+ sizeBytes: file.bytes.byteLength,
+ delivery: 'image_input',
+ }),
+ images: [
+ { ...image, source: file.source, sizeBytes: file.bytes.byteLength, dataBase64 },
+ ],
+ }
+ }
+ if (/\.(?:png|jpe?g)$/i.test(file.source.name))
+ throw new VisualInputError('invalid_image')
+ if (isNonTextFormat(file.bytes)) return fileReference(file, 'unsupported_binary_format')
+ let text: string
+ try {
+ // Same fileBytes cap as images (G0). TextDecoder already drops a
+ // UTF-8 BOM; strip again so classification and the model see the
+ // same contract.
+ text = new TextDecoder('utf-8', { fatal: true })
+ .decode(file.bytes)
+ .replace(/^\uFEFF/, '')
+ } catch {
+ return fileReference(file, 'unsupported_binary_format')
+ }
+ if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/.test(text))
+ return fileReference(file, 'unsupported_binary_format')
+ if (isSvgText(text)) return fileReference(file, 'svg_visual_input_not_supported')
+ return ok(text)
} catch (err) {
return fail(err)
+ } finally {
+ file?.reservation.release()
}
},
},
diff --cc mcp-host/src/internalTools/gfsClient.test.ts
index 73016b41f,80cface73..9ebf94476
--- a/mcp-host/src/internalTools/gfsClient.test.ts
+++ b/mcp-host/src/internalTools/gfsClient.test.ts
@@@ -1,8 -1,8 +1,10 @@@
- import { describe, expect, it, vi } from 'vitest'
+ 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,
+ GfscHttpError,
createGfscClient,
getGfsToolScopes,
hasGfsRuntimeAccess,
@@@ -223,384 -253,463 +256,994 @@@ describe('gfs runtime gfsc client', ()
})
})
+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,
- })
++ 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: VISUAL_INPUT_LIMITS.fileBytes + 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' }, 'version_conflict'],
+ [{ '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,
- })
++ 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 }
- )
- }),
- })
++ 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')
- let calls = 0
- const fetchFn = vi.fn(async () => (++calls === 1 ? rateLimited('7') : jsonResponse({})))
- const client = createGfscClient(tokenEnv(fetchFn), clientOptions)
++ const bytes = Buffer.from('rate-limited read')
++ const { client, fetchFn, budget } = contentHarness(bytes)
++ fetchFn.mockResolvedValueOnce(rateLimited('7'))
+
- const pending = client.read({ drive: 'main', resourceId: 'rid' })
++ const pending = client.read(READ_ARGS, { budget })
+ await vi.advanceTimersByTimeAsync(0)
- expect(setTimeoutSpy).toHaveBeenCalledTimes(1)
- expect(setTimeoutSpy.mock.calls[0]?.[1]).toBe(7000)
++ 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 expect(pending).resolves.toEqual({})
++ 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)],
- ['read', (client, call) => client.read({ 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)
+ }
+ )
+ })
diff --cc mcp-host/src/internalTools/gfsClient.ts
index 9db9a98e9,91ed5c509..d68f29896
--- a/mcp-host/src/internalTools/gfsClient.ts
+++ b/mcp-host/src/internalTools/gfsClient.ts
@@@ -1,8 -1,8 +1,9 @@@
import { existsSync, readFileSync } from 'node:fs'
import { readFile } from 'node:fs/promises'
+ import { withAbort } from '../core/adapters/abortableLlmPort'
import { decodeRuntimeJwtScopes } from '../workflow/mcpHostRuntimeJwt'
- import type { GfscWriteClient } from './gfs'
- import { readGfsContent } from './gfsContentRead'
+ import type { GfscCallOptions, GfscWriteClient } from './gfs'
++import { boundedGfsErrorDetail, readGfsContent } from './gfsContentRead'
const DIRECT_KEY = 'MCP_HOST_GFS_TOKEN'
const FILE_KEY = 'MCP_HOST_GFS_TOKEN_FILE'
@@@ -84,56 -152,99 +153,122 @@@ export function createGfscClient(env: G
return value
}
- async function authenticatedFetch(
- baseUrl: string,
- path: string,
- init: RequestInit = {}
- ): Promise<Response> {
- async function send(baseUrl: string, path: string, init: RequestInit): Promise<Response> {
++ async function send(baseUrl: string, path: string, init: RequestInit = {}): Promise<Response> {
+ const headers: Record<string, string> = {}
+ new Headers(init.headers).forEach((value, key) => {
+ headers[key] = value
+ })
return fetchFn(`${baseUrl}${path}`, {
...init,
+ redirect: 'error',
headers: {
+ ...headers,
[AUTH_HEADER]: `${AUTH_SCHEME} ${await accessValue()}`,
- ...(init.headers ?? {}),
},
})
}
- async function request(baseUrl: string, path: string, init: RequestInit = {}): Promise<unknown> {
- const res = await authenticatedFetch(baseUrl, path, init)
- if (!res.ok) {
- const body = await res.text().catch(() => '')
- throw new Error(`gfsc ${res.status}: ${body || res.statusText}`)
- }
- async function httpError(res: Response): Promise<GfscHttpError> {
- const body = await res.text().catch(() => '')
++ async function httpError(res: Response, boundedSignal?: AbortSignal): Promise<GfscHttpError> {
++ const body = boundedSignal
++ ? await boundedGfsErrorDetail(res, boundedSignal)
++ : await res.text().catch(() => '')
+ const retryAfter = res.status === 429 ? retryAfterHeader(res) : undefined
+ return new GfscHttpError(res.status, body || res.statusText, retryAfter)
+ }
+
+ async function decode(res: Response): Promise<unknown> {
const contentType = res.headers.get('content-type') ?? ''
if (contentType.includes('application/json')) return res.json()
return res.text()
}
+ // A 429 from gfsc's agent limiter that states a delay is retried once, after
+ // that delay plus a bounded jitter. The limiter answers before the permission
+ // store and the executor run, so the denied attempt had no effect and
+ // repeating a write is safe. Any other 429 scope, a 429 without a delay, a
+ // delay that does not fit in the caller's remaining budget, or a second
+ // denial fails at once. The caller's signal cancels both requests and the
+ // sleep between them.
- async function request(
++ async function responseWithRetry(
+ baseUrl: string,
+ path: string,
+ init: RequestInit = {},
- call: GfscCallOptions = {}
- ): Promise<unknown> {
++ call: GfscCallOptions = {},
++ boundedError = false
++ ): Promise<Response> {
+ const attempt: RequestInit = call.signal ? { ...init, signal: call.signal } : init
+ const first = await send(baseUrl, path, attempt)
- if (first.ok) return decode(first)
- const denied = await httpError(first)
++ if (first.ok) return first
++ const denied = await httpError(first, boundedError ? call.signal : undefined)
+ const retryAfterMs =
+ denied.retryAfterSeconds === undefined ? undefined : denied.retryAfterSeconds * 1000
+ const budgetMs = Math.min(
+ maxRetryWaitMs,
+ call.deadlineMs === undefined ? Number.POSITIVE_INFINITY : call.deadlineMs - Date.now()
+ )
+ if (
+ denied.status !== 429 ||
+ !RETRYABLE_SCOPES.has(first.headers.get('x-gfs-ratelimit-scope') ?? '') ||
+ retryAfterMs === undefined ||
+ retryAfterMs > budgetMs
+ ) {
+ throw denied
+ }
+ const jitterMs = Math.floor(random() * Math.min(MAX_JITTER_MS, JITTER_FRACTION * retryAfterMs))
+ await sleep(Math.min(retryAfterMs + jitterMs, budgetMs), call.signal)
+ const second = await send(baseUrl, path, attempt)
- if (second.ok) return decode(second)
- throw await httpError(second)
++ if (second.ok) return second
++ throw await httpError(second, boundedError ? call.signal : undefined)
++ }
++
++ async function request(
++ baseUrl: string,
++ path: string,
++ init: RequestInit = {},
++ call: GfscCallOptions = {}
++ ): Promise<unknown> {
++ return decode(await responseWithRetry(baseUrl, path, init, call))
+ }
+
return {
- accessible: ({ drive, cursor }) => {
+ accessible: ({ drive, cursor }, call) => {
const q = new URLSearchParams({ drive })
if (cursor) q.set('cursor', cursor)
- return request(readerBase, `/v1/accessible?${q}`)
+ return request(readerBase, `/v1/accessible?${q}`, {}, call)
},
- list: ({ drive, resourceId, cursor }) => {
+ list: ({ drive, resourceId, cursor }, call) => {
const q = new URLSearchParams({ drive })
if (cursor) q.set('cursor', cursor)
- return request(readerBase, `/v1/resources/${encodeURIComponent(resourceId)}/children?${q}`)
+ return request(
+ readerBase,
+ `/v1/resources/${encodeURIComponent(resourceId)}/children?${q}`,
+ {},
+ call
+ )
},
- read: ({ drive, resourceId }, call) =>
- request(
- readerBase,
- `/v1/resources/${encodeURIComponent(resourceId)}/content?drive=${encodeURIComponent(drive)}`,
- {},
- call
+ read: (args, options = {}) =>
- readGfsContent((path, init) => authenticatedFetch(readerBase, path, init), args, options),
- stat: ({ drive, resourceId }) =>
++ readGfsContent(
++ (path, init, deadlineMs) =>
++ responseWithRetry(
++ readerBase,
++ path,
++ init,
++ { signal: init.signal as AbortSignal, deadlineMs },
++ true
++ ),
++ args,
++ options
+ ),
+ stat: ({ drive, resourceId }, call) =>
request(
readerBase,
- `/v1/resources/${encodeURIComponent(resourceId)}?drive=${encodeURIComponent(drive)}`
+ `/v1/resources/${encodeURIComponent(resourceId)}?drive=${encodeURIComponent(drive)}`,
+ {},
+ call
),
- resolve: ({ uri }) => request(readerBase, `/v1/resolve?uri=${encodeURIComponent(uri)}`),
- write: ({ drive, resourceId, content, ifMatch }) =>
+ resolve: ({ uri }, call) =>
+ request(readerBase, `/v1/resolve?uri=${encodeURIComponent(uri)}`, {}, call),
+ write: ({ drive, resourceId, content, ifMatch }, call) =>
request(
writerBase,
`/v1/resources/${encodeURIComponent(resourceId)}/content?drive=${encodeURIComponent(drive)}`,
diff --cc mcp-host/src/internalTools/gfsContentRead.ts
index 6b3981a3a,000000000..5970167d4
mode 100644,000000..100644
--- a/mcp-host/src/internalTools/gfsContentRead.ts
+++ b/mcp-host/src/internalTools/gfsContentRead.ts
@@@ -1,214 -1,0 +1,228 @@@
+import {
+ type GfsImageSource,
+ type MemoryReservation,
+ VISUAL_INPUT_LIMITS,
+ VisualInputBudget,
+ VisualInputError,
+} from '../visualInput/policy'
+import type { GfsFileContent, GfsReadOptions } from './gfsReadTypes'
+
- export type GfsContentRequest = (path: string, init: RequestInit) => Promise<Response>
++export type GfsContentRequest = (
++ path: string,
++ init: RequestInit,
++ deadlineMs: number
++) => Promise<Response>
+
+function cancelBody(body: ReadableStream<Uint8Array> | null): void {
+ if (body) void body.cancel().catch(() => undefined)
+}
+
+/** Bounded consumption also observes cancellation for injected/local streams. */
+async function collect(
+ response: Response,
+ maximum: number,
+ signal: AbortSignal,
+ onChunk?: (size: number) => void
+): Promise<Buffer> {
+ if (!response.body) return Buffer.alloc(0)
+ const reader = response.body.getReader()
+ const chunks: Uint8Array[] = []
+ let size = 0
+ const abort = () => {
+ void reader.cancel().catch(() => undefined)
+ }
+ signal.addEventListener('abort', abort, { once: true })
+ try {
+ if (signal.aborted) throw new VisualInputError('cancelled')
+ for (;;) {
+ const next = await reader.read()
+ if (signal.aborted) throw new VisualInputError('cancelled')
+ if (next.done) break
+ // Transport work counts even when this chunk exceeds the file snapshot.
+ onChunk?.(next.value.byteLength)
+ if (next.value.byteLength > maximum - size) throw new VisualInputError('limit_exceeded')
+ size += next.value.byteLength
+ chunks.push(next.value)
+ }
+ return Buffer.concat(chunks, size)
+ } catch (error) {
+ void reader.cancel().catch(() => undefined)
+ if (error instanceof VisualInputError) throw error
+ throw new VisualInputError('incomplete_response')
+ } finally {
+ signal.removeEventListener('abort', abort)
+ reader.releaseLock()
+ }
+}
+
++export async function boundedGfsErrorDetail(
++ response: Response,
++ signal: AbortSignal
++): Promise<string> {
++ try {
++ return (await collect(response, VISUAL_INPUT_LIMITS.errorBytes, signal)).toString('utf8')
++ } catch {
++ if (signal.aborted) throw new VisualInputError('cancelled')
++ // An oversized error must not obscure the authoritative HTTP denial.
++ return ''
++ }
++}
++
+async function requireOk(response: Response, signal: AbortSignal): Promise<void> {
+ if (response.redirected) {
+ cancelBody(response.body)
+ throw new VisualInputError('invalid_response')
+ }
+ if (response.status === 200) return
+ if (response.ok) {
+ cancelBody(response.body)
+ throw new VisualInputError('invalid_response')
+ }
- let detail = ''
- try {
- detail = (await collect(response, VISUAL_INPUT_LIMITS.errorBytes, signal)).toString('utf8')
- } catch {
- if (signal.aborted) throw new VisualInputError('cancelled')
- // An oversized error must not obscure the authoritative HTTP denial.
- }
++ const detail = await boundedGfsErrorDetail(response, signal)
+ throw new Error(`gfsc ${response.status}: ${detail || response.statusText}`)
+}
+
+function normalizeRid(value: unknown): string | null {
+ if (typeof value !== 'string') return null
+ const normalized = value.replace(/-/g, '').toLowerCase()
+ return /^[a-f0-9]{32}$/.test(normalized) ? normalized : null
+}
+
+function metadataSnapshot(
+ bytes: Buffer,
+ args: { drive: string; resourceId: string }
+): { source: GfsImageSource; size: number } {
+ let envelope: { ok?: unknown; data?: unknown }
+ try {
+ envelope = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes))
+ } catch {
+ throw new VisualInputError('invalid_response')
+ }
+ if (!envelope || envelope.ok !== true || !envelope.data || typeof envelope.data !== 'object')
+ throw new VisualInputError('invalid_response')
+ const data = envelope.data as Record<string, unknown>
+ const rid = normalizeRid(args.resourceId)
+ if (
+ !rid ||
+ normalizeRid(data.resourceId) !== rid ||
+ data.rid !== rid ||
+ data.drive !== args.drive ||
+ data.gfsUri !== `gfs://${args.drive}/${rid}` ||
+ typeof data.name !== 'string' ||
+ data.name.length === 0 ||
+ data.name.length > 1024 ||
+ !Number.isSafeInteger(data.version) ||
+ (data.version as number) < 0 ||
+ !Number.isSafeInteger(data.bytes) ||
+ (data.bytes as number) < 0
+ )
+ throw new VisualInputError('invalid_response')
+ if (data.kind !== 'file') throw new VisualInputError('unsupported_format')
+ if ((data.bytes as number) > VISUAL_INPUT_LIMITS.fileBytes)
+ throw new VisualInputError('limit_exceeded')
+ return {
+ source: {
+ kind: 'gfs',
+ drive: args.drive,
+ resourceId: rid,
+ gfsUri: data.gfsUri as string,
+ name: data.name,
+ version: data.version as number,
+ },
+ size: data.bytes as number,
+ }
+}
+
+function assertContentHeaders(response: Response, source: GfsImageSource, size: number): void {
+ const version = response.headers.get('x-gfs-version')
+ if (response.headers.get('x-gfs-uri') !== source.gfsUri || version !== String(source.version))
+ throw new VisualInputError('version_conflict')
+ const encoding = response.headers.get('content-encoding')
+ if (encoding && encoding.toLowerCase() !== 'identity')
+ throw new VisualInputError('invalid_response')
+ const length = response.headers.get('content-length')
+ if (
+ length !== null &&
+ (!/^\d+$/.test(length) || !Number.isSafeInteger(Number(length)) || Number(length) !== size)
+ )
+ throw new VisualInputError('incomplete_response')
+}
+
+/** One identity/version-bound read with an absolute deadline spanning both requests. */
+export async function readGfsContent(
+ request: GfsContentRequest,
+ args: { drive: string; resourceId: string },
+ options: GfsReadOptions
+): Promise<GfsFileContent> {
+ // Standalone reads own one operation. Chat and workflow callers supply their
+ // turn/step budget explicitly; a shared HTTP client must not own that lifetime.
+ const budget = options.budget ?? new VisualInputBudget()
+ if (options.signal?.aborted) throw new VisualInputError('cancelled')
+ if (budget.isClosed || budget.remainingReadBytes === 0)
+ throw new VisualInputError('limit_exceeded')
++ const startedAt = Date.now()
+ const timeoutMs = Math.min(
+ options.timeoutMs ?? VISUAL_INPUT_LIMITS.readTimeoutMs,
- VISUAL_INPUT_LIMITS.readTimeoutMs
++ VISUAL_INPUT_LIMITS.readTimeoutMs,
++ options.deadlineMs === undefined ? Number.POSITIVE_INFINITY : options.deadlineMs - startedAt
+ )
+ if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) throw new VisualInputError('timeout')
++ const deadlineMs = startedAt + timeoutMs
+ const controller = new AbortController()
+ let expired = false
+ const abort = () => controller.abort()
+ options.signal?.addEventListener('abort', abort, { once: true })
+ const timer = setTimeout(() => {
+ expired = true
+ controller.abort()
+ }, timeoutMs)
+ const signal = controller.signal
+ let reservation: MemoryReservation | undefined
+ let handedOff = false
+ const path = `/v1/resources/${encodeURIComponent(args.resourceId)}`
+ const query = `?drive=${encodeURIComponent(args.drive)}`
+ const init: RequestInit = {
+ signal,
+ redirect: 'error',
+ headers: { 'accept-encoding': 'identity' },
+ }
+ try {
+ const metadataReservation = budget.reserve(2 * VISUAL_INPUT_LIMITS.metadataBytes)
+ let snapshot: ReturnType<typeof metadataSnapshot>
+ try {
- const metadata = await request(`${path}${query}`, init)
++ const metadata = await request(`${path}${query}`, init, deadlineMs)
+ await requireOk(metadata, signal)
+ snapshot = metadataSnapshot(
+ await collect(metadata, VISUAL_INPUT_LIMITS.metadataBytes, signal),
+ args
+ )
+ } finally {
+ metadataReservation.release()
+ }
+ if (signal.aborted) throw new VisualInputError('cancelled')
+ if (snapshot.size > budget.remainingReadBytes) throw new VisualInputError('limit_exceeded')
+ // The source snapshot provides an exact bound: chunks and concatenation can
+ // coexist, so reserve twice that size before beginning the content request.
+ reservation = budget.reserve(2 * snapshot.size + 2 * VISUAL_INPUT_LIMITS.errorBytes)
- const response = await request(`${path}/content${query}`, init)
++ const response = await request(`${path}/content${query}`, init, deadlineMs)
+ await requireOk(response, signal)
+ try {
+ assertContentHeaders(response, snapshot.source, snapshot.size)
+ } catch (error) {
+ cancelBody(response.body)
+ throw error
+ }
+ const bytes = await collect(response, snapshot.size, signal, size => budget.consumeRead(size))
+ if (signal.aborted) throw new VisualInputError('cancelled')
+ if (bytes.byteLength !== snapshot.size) throw new VisualInputError('incomplete_response')
+ handedOff = true
+ return { source: snapshot.source, bytes, reservation }
+ } catch (error) {
+ if (signal.aborted) throw new VisualInputError(expired ? 'timeout' : 'cancelled')
+ throw error
+ } finally {
+ clearTimeout(timer)
+ options.signal?.removeEventListener('abort', abort)
+ if (!handedOff) reservation?.release()
+ }
+}
diff --cc mcp-host/src/internalTools/gfsImageInput.integration.test.ts
index 62268de10,000000000..89174d5f6
mode 100644,000000..100644
--- a/mcp-host/src/internalTools/gfsImageInput.integration.test.ts
+++ b/mcp-host/src/internalTools/gfsImageInput.integration.test.ts
@@@ -1,647 -1,0 +1,650 @@@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createCanvas } from '@napi-rs/canvas'
+import { LlmPortAdapter } from '../core/adapters/llmPortAdapter'
+import type { NativeToolConfig } from '../core/interfaces'
+import { appendToolResults } from '../core/orchestration/toolUseLoopMessages'
+import { NativeToolRegistry } from '../core/tools/nativeToolRegistry'
+import type { Attachment, ChatMessage, ToolResult } from '../core/types'
+import { ClaudeProvider } from '../llm/claude'
+import { CodexSubscriptionProvider } from '../llm/codexSubscription'
+import type { ImageInputResolver } from '../llm/imageInput'
+import { OpenAIProvider } from '../llm/openai'
+import { OpenAICompatibleProvider } from '../llm/openaiCompatible'
+import type { LlmProvider } from '../llm/registryCore'
+import type { SingleTurnProvider } from '../llm/types'
+import { VisualInputBudget } from '../visualInput/policy'
+import { projectGfsApproval } from '../visualInput/suspension'
+
+const { sdkCreate, clientFactory } = vi.hoisted(() => ({
+ sdkCreate: vi.fn(),
+ clientFactory: vi.fn(),
+}))
+
+// Only external transport boundaries are replaced. Production client, tool,
+// native adapter, message construction and provider serialization all execute.
+vi.mock('openai', () => ({
+ default: class {
+ chat = { completions: { create: sdkCreate } }
+ },
+}))
+vi.mock('./gfsClient', async importOriginal => ({
+ ...(await importOriginal<typeof import('./gfsClient')>()),
+ getGfsToolScopes: () => new Set(['gfs.read']),
+ createGfscClient: clientFactory,
+}))
+
+const rid = '1234567890abcdef1234567890abcdef'
+const uri = `gfs://main/${rid}`
+const model = 'example/vision-model'
+type CatalogState = 'supported' | 'unsupported' | 'unknown' | 'missing' | 'codex-present'
+const config: NativeToolConfig = {
+ workspacePath: '/tmp',
+ shellTimeout: 5000,
+ toolTimeout: 60000,
+ toolProgressInterval: 0,
+ httpAllowlist: [],
+ envAllowlist: [],
+ memoryMaxSize: 1048576,
+}
+
+async function setup(
+ bytes: Buffer,
+ options: {
+ name?: string
+ catalogState?: CatalogState
+ llm?: { provider: SingleTurnProvider; model: string; name: LlmProvider }
+ } = {}
+) {
+ const { createGfscClient } = await vi.importActual<typeof import('./gfsClient')>('./gfsClient')
+ const gfsFetch = vi.fn(async (url: string) =>
+ url.includes('/content?')
+ ? new Response(new Uint8Array(bytes), {
+ headers: {
+ 'content-type': 'application/octet-stream',
+ 'content-length': String(bytes.length),
+ 'x-gfs-uri': uri,
+ 'x-gfs-version': '7',
+ },
+ })
+ : new Response(
+ JSON.stringify({
+ ok: true,
+ data: {
+ resourceId: rid,
+ rid,
+ drive: 'main',
+ gfsUri: uri,
+ version: 7,
+ kind: 'file',
+ name: options.name ?? 'neutral.png',
+ bytes: bytes.length,
+ },
+ }),
+ { headers: { 'content-type': 'application/json' } }
+ )
+ )
+ clientFactory.mockReturnValue(
- createGfscClient({
- get: () => undefined,
- readFile: async () => 'integration-only-identity',
- fetch: gfsFetch,
- })
++ createGfscClient(
++ {
++ get: () => undefined,
++ readFile: async () => 'integration-only-identity',
++ fetch: gfsFetch,
++ },
++ { maxRetryWaitMs: config.toolTimeout, random: () => 0 }
++ )
+ )
+ const metadataFetch = vi.fn(
+ async (_url: string, _init?: RequestInit) =>
+ new Response(
+ JSON.stringify({
+ data: {
+ id: model,
+ architecture: { input_modalities: ['text', 'image'] },
+ },
+ }),
+ { headers: { 'content-type': 'application/json' } }
+ )
+ )
+ vi.stubGlobal('fetch', metadataFetch)
+ sdkCreate.mockResolvedValue({
+ choices: [{ message: { content: 'Done' }, finish_reason: 'stop' }],
+ usage: { prompt_tokens: 10, completion_tokens: 2, total_tokens: 12 },
+ })
+ const provider =
+ options.llm?.provider ??
+ new OpenAICompatibleProvider(
+ {
+ id: 'openrouter',
+ baseURL: 'https://openrouter.ai/api/v1',
+ defaultModel: model,
+ },
+ 'integration-only-provider-identity',
+ model
+ )
+ const budget = new VisualInputBudget()
+ let catalogState = options.catalogState ?? 'supported'
+ const evidence = {
+ source: 'curated' as const,
+ reference: 'https://example.com/image-input',
+ checkedAt: '2026-09-18T00:00:00Z',
+ }
+ const imageInputResolver: ImageInputResolver = () => {
+ if (catalogState === 'missing') return undefined
+ if (catalogState === 'codex-present') return { capability: undefined }
+ if (catalogState === 'unknown') return { capability: { state: 'unknown' } }
+ return { capability: { state: catalogState, evidence } }
+ }
+ const adapter = new LlmPortAdapter(
+ provider,
+ options.llm?.model ?? model,
+ options.llm?.name ?? 'openrouter',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ imageInputResolver
+ )
+ const tool = new NativeToolRegistry(config, 'gfs-image-integration').get('clerum__gfs_read')!
+ const output = await tool.execute(
+ { drive: 'main', resourceId: rid },
+ {
+ onOutput: () => {},
+ timeoutMs: 10000,
+ visualInput: { budget, resolveCapability: signal => adapter.getImageInputCapability(signal) },
+ }
+ )
+ const result: ToolResult = { ...output, name: 'clerum__gfs_read', tool_call_id: 'read-image' }
+ const messages: ChatMessage[] = [
+ {
+ role: 'assistant',
+ content: '',
+ tool_calls: [
+ {
+ id: 'read-image',
+ name: 'clerum__gfs_read',
+ arguments: { drive: 'main', resourceId: rid },
+ },
+ ],
+ },
+ ]
+ const collected: Attachment[] = []
+ appendToolResults(messages, [result], collected)
+ return {
+ adapter,
+ messages,
+ output,
+ gfsFetch,
+ metadataFetch,
+ budget,
+ collected,
+ tool,
+ setCatalogState: (state: CatalogState) => {
+ catalogState = state
+ },
+ }
+}
+
+afterEach(() => {
+ vi.unstubAllGlobals()
+ vi.clearAllMocks()
+})
+
+describe('GFS bytes to actual provider request', () => {
+ it.each(['image/png', 'image/jpeg'] as const)(
+ 'delivers %s directly to a documented OpenAI model',
+ async mime => {
+ const model = 'gpt-4.1'
+ // Only the SDK HTTP boundary is doubled; no credential or catalog service.
+ const client = {
+ baseURL: 'https://api.openai.com/v1',
+ chat: { completions: { create: sdkCreate } },
+ }
+ const canvas = createCanvas(8, 8)
+ canvas.getContext('2d').fillRect(1, 1, 4, 4)
+ const bytes =
+ mime === 'image/png' ? canvas.toBuffer('image/png') : canvas.toBuffer('image/jpeg')
+ const subject = await setup(bytes, {
+ llm: {
+ provider: new OpenAIProvider(client as never, model),
+ model,
+ name: 'openai',
+ },
+ })
+ expect(JSON.parse(subject.output.content).delivery).toBe('image_input')
+ await subject.adapter.completeWithTools({ messages: subject.messages, tools: [] })
+ expect(subject.metadataFetch).not.toHaveBeenCalled()
+ const request = sdkCreate.mock.calls[0][0]
+ const images = request.messages
+ .flatMap((message: any) => (Array.isArray(message.content) ? message.content : []))
+ .filter((part: any) => part.type === 'image_url')
+ expect(images).toEqual([
+ {
+ type: 'image_url',
+ image_url: { url: `data:${mime};base64,${bytes.toString('base64')}` },
+ },
+ ])
+ expect(request.model).toBe(model)
+ subject.budget.close()
+ }
+ )
+
+ it('delivers GFS pixels to a catalog-supported OpenAI model absent from the old allowlist', async () => {
+ const client = {
+ baseURL: 'https://api.openai.com/v1',
+ chat: { completions: { create: sdkCreate } },
+ }
+ const provider = new OpenAIProvider(client as never, 'future-vision-model')
+ const bytes = createCanvas(2, 2).toBuffer('image/png')
+ const subject = await setup(bytes, {
+ llm: { provider, model: 'future-vision-model', name: 'openai' },
+ })
+
+ expect(JSON.parse(subject.output.content).delivery).toBe('image_input')
+ await subject.adapter.completeWithTools({ messages: subject.messages, tools: [] })
+ expect(JSON.stringify(sdkCreate.mock.calls[0][0])).toContain(bytes.toString('base64'))
+ expect(subject.metadataFetch).not.toHaveBeenCalled()
+ subject.budget.close()
+ })
+
+ it('returns a reference when the catalog omits a documented vision model', async () => {
+ const client = {
+ baseURL: 'https://api.openai.com/v1',
+ chat: { completions: { create: sdkCreate } },
+ }
+ const provider = new OpenAIProvider(client as never, 'gpt-4.1')
+ const subject = await setup(createCanvas(2, 2).toBuffer('image/png'), {
+ catalogState: 'missing',
+ llm: { provider, model: 'gpt-4.1', name: 'openai' },
+ })
+
+ expect(JSON.parse(subject.output.content)).toMatchObject({
+ delivery: 'reference_only',
+ reason: 'model_image_input_unknown',
+ })
+ expect(subject.output.attachments).toBeUndefined()
+ expect(sdkCreate).not.toHaveBeenCalled()
+ subject.budget.close()
+ })
+
+ it('withholds an admitted GFS image if catalog support is revoked before dispatch', async () => {
+ const subject = await setup(createCanvas(2, 2).toBuffer('image/png'))
+ expect(JSON.parse(subject.output.content).delivery).toBe('image_input')
+ subject.setCatalogState('unsupported')
+
+ await subject.adapter.completeWithTools({ messages: subject.messages, tools: [] })
+
+ expect(
+ subject.messages.some(message => message.contentParts?.some(part => part.type === 'image'))
+ ).toBe(true)
+ expect(JSON.stringify(sdkCreate.mock.calls[0][0])).not.toContain('image_url')
+ const sentTool = sdkCreate.mock.calls[0][0].messages.find(
+ (message: { role: string }) => message.role === 'tool'
+ )
+ expect(JSON.parse(sentTool.content)).toMatchObject({
+ delivery: 'reference_only',
+ reason: 'model_image_input_unavailable',
+ })
+ subject.budget.close()
+ })
+
+ it('delivers a GFS image through Codex V2 for a present catalog row', async () => {
+ const authorize = vi.fn(
+ async (_input: {
+ request: { messages: Array<{ contentParts?: Array<{ type: string }> }> }
+ }) => ({
+ providerAttemptId: 'attempt-1',
+ requestHash: 'a'.repeat(64),
+ executionTicket: 'ticket-123456',
+ expiresAt: '2099-01-01T00:00:00.000Z',
+ })
+ )
+ const stream = vi.fn(async () => ({ text: 'seen', toolCalls: [], outcome: 'success' as const }))
+ const provider = new CodexSubscriptionProvider('gpt-5.6-luna', {
+ authorizer: { authorize },
+ proxy: { stream },
+ attemptContext: () => ({ policyRevision: 1, policyHash: 'b'.repeat(64), hostRef: 'chatllm' }),
+ } as never)
+ const bytes = createCanvas(2, 2).toBuffer('image/png')
+ const subject = await setup(bytes, {
+ catalogState: 'codex-present',
+ llm: { provider, model: 'gpt-5.6-luna', name: 'codex-subscription' },
+ })
+
+ expect(JSON.parse(subject.output.content).delivery).toBe('image_input')
+ await subject.adapter.completeWithTools({ messages: subject.messages, tools: [] })
+
+ const authorized = authorize.mock.calls[0][0].request
+ const image = authorized.messages
+ .flatMap((message: { contentParts?: Array<{ type: string }> }) => message.contentParts ?? [])
+ .find((part: { type: string }) => part.type === 'image')
+ expect(image).toMatchObject({
+ type: 'image',
+ data: bytes.toString('base64'),
+ source: { kind: 'tool', toolCallId: 'read-image' },
+ })
+ expect(stream).toHaveBeenCalledOnce()
+ subject.budget.close()
+ })
+
+ it.each([
+ ['image/png', false],
+ ['image/jpeg', false],
+ ['image/png', true],
+ ['image/jpeg', true],
+ ] as const)(
+ 'delivers %s through Claude with cache=%s without OpenRouter',
+ async (mime, cache) => {
+ const targetModel = 'claude-sonnet-4-6'
+ // Credential-free SDK boundary double. The production provider serializer,
+ // client/tool registry and loop still execute.
+ const create = vi.fn(async () => ({
+ content: [{ type: 'text', text: 'Done' }],
+ stop_reason: 'end_turn',
+ usage: { input_tokens: 10, output_tokens: 2 },
+ }))
+ const client = { messages: { create } }
+ const canvas = createCanvas(8, 8)
+ canvas.getContext('2d').fillRect(1, 1, 4, 4)
+ const bytes =
+ mime === 'image/png' ? canvas.toBuffer('image/png') : canvas.toBuffer('image/jpeg')
+ const subject = await setup(bytes, {
+ llm: {
+ provider: new ClaudeProvider(client as never, targetModel),
+ model: targetModel,
+ name: 'claude',
+ },
+ })
+ expect(subject.output.is_error).toBe(false)
+ await subject.adapter.completeWithTools({
+ messages: subject.messages,
+ tools: [],
+ ...(cache
+ ? {
+ systemPromptParts: {
+ stable: 'system instructions',
+ context: 'context',
+ stableHash: 'fixture',
+ contextHash: 'fixture',
+ },
+ }
+ : {}),
+ })
+ expect(subject.metadataFetch).not.toHaveBeenCalled()
+ const request = (create.mock.calls as unknown as Array<[Record<string, any>]>)[0][0]
+ const blocks = request.messages.flatMap((m: any) =>
+ Array.isArray(m.content) ? m.content : []
+ )
+ expect(blocks.filter((b: any) => b.type === 'image')).toEqual([
+ {
+ type: 'image',
+ source: { type: 'base64', media_type: mime, data: bytes.toString('base64') },
+ },
+ ])
+ expect(JSON.stringify(blocks.filter((b: any) => b.type !== 'image'))).not.toContain(
+ bytes.toString('base64')
+ )
+ if (cache) expect(request.system[0].cache_control).toEqual({ type: 'ephemeral' })
+ subject.budget.close()
+ }
+ )
+ it.each(['unchanged', 'replaced', 'revoked'] as const)(
+ 'requires a new authorized read after suspension when the resource is %s',
+ async state => {
+ const original = createCanvas(2, 2).toBuffer('image/png')
+ const subject = await setup(original)
+ const restored = projectGfsApproval({
+ request_id: 'approval',
+ tool_name: 'shell_exec',
+ tool_call_id: 'pending-action',
+ parameters: { command: 'echo done' },
+ description: 'pending action',
+ context_snapshot: subject.messages,
+ })
+ expect(JSON.stringify(restored)).not.toContain(original.toString('base64'))
+ expect(JSON.stringify(restored)).toContain('new_gfs_read_required_after_suspension')
+ expect(subject.gfsFetch).toHaveBeenCalledTimes(2)
+ const replacement = createCanvas(3, 3).toBuffer('image/png')
+ if (state === 'revoked')
+ subject.gfsFetch.mockResolvedValueOnce(new Response('denied', { status: 403 }))
+ if (state === 'replaced') {
+ subject.gfsFetch.mockResolvedValueOnce(
+ new Response(
+ JSON.stringify({
+ ok: true,
+ data: {
+ resourceId: rid,
+ rid,
+ drive: 'main',
+ gfsUri: uri,
+ version: 8,
+ kind: 'file',
+ name: 'neutral.png',
+ bytes: replacement.length,
+ },
+ })
+ )
+ )
+ subject.gfsFetch.mockResolvedValueOnce(
+ new Response(new Uint8Array(replacement), {
+ headers: {
+ 'x-gfs-uri': uri,
+ 'x-gfs-version': '8',
+ 'content-length': String(replacement.length),
+ },
+ })
+ )
+ }
+ const reread = await subject.tool.execute(
+ { drive: 'main', resourceId: rid },
+ {
+ onOutput: () => {},
+ timeoutMs: 10000,
+ visualInput: {
+ budget: subject.budget,
+ resolveCapability: signal => subject.adapter.getImageInputCapability(signal),
+ },
+ }
+ )
+ restored.context_snapshot.push({
+ role: 'assistant',
+ content: '',
+ tool_calls: [
+ {
+ id: 'explicit-reread',
+ name: 'clerum__gfs_read',
+ arguments: { drive: 'main', resourceId: rid },
+ },
+ ],
+ })
+ appendToolResults(
+ restored.context_snapshot,
+ [{ ...reread, name: 'clerum__gfs_read', tool_call_id: 'explicit-reread' }],
+ []
+ )
+ const images = restored.context_snapshot
+ .flatMap(message => message.contentParts ?? [])
+ .filter(part => part.type === 'image')
+ if (state === 'revoked') {
+ expect(reread.is_error).toBe(true)
+ expect(images).toHaveLength(0)
+ expect(subject.gfsFetch).toHaveBeenCalledTimes(3)
+ } else {
+ expect(reread.is_error).toBe(false)
+ expect(images).toHaveLength(1)
+ expect(images[0].source?.kind === 'gfs' ? images[0].source.version : undefined).toBe(
+ state === 'replaced' ? 8 : 7
+ )
+ expect(images[0].data).toBe(
+ (state === 'replaced' ? replacement : original).toString('base64')
+ )
+ expect(subject.gfsFetch).toHaveBeenCalledTimes(4)
+ }
+ expect(restored.tool_call_id).toBe('pending-action')
+ expect(restored.parameters).toEqual({ command: 'echo done' })
+ subject.budget.close()
+ }
+ )
+ it('does not silently lose an image when a shaper changes its message role', async () => {
+ const subject = await setup(createCanvas(1, 1).toBuffer('image/png'))
+ const shaped = subject.messages.map(message =>
+ message.contentParts?.some(p => p.type === 'image')
+ ? { ...message, role: 'system' as const }
+ : message
+ )
+ await subject.adapter.completeWithTools({ messages: shaped, tools: [] })
+ expect(sdkCreate).toHaveBeenCalledTimes(1)
+ expect(JSON.stringify(sdkCreate.mock.calls[0][0])).not.toContain('image_url')
+ subject.budget.close()
+ })
+ it('keeps the destination gate after shaping removes optional image provenance fields', async () => {
+ const subject = await setup(createCanvas(1, 1).toBuffer('image/png'))
+ const shaped = subject.messages.map(message => ({
+ ...message,
+ contentParts: message.contentParts?.map(part =>
+ part.type === 'image'
+ ? { type: 'image' as const, mimeType: part.mimeType, data: part.data }
+ : part
+ ),
+ }))
+ const completeSingleTurnWithTools = vi.fn().mockResolvedValue({
+ content: 'degraded',
+ tool_calls: [],
+ usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 },
+ finish_reason: 'stop',
+ })
+ const fallback = new LlmPortAdapter(
+ {
+ completeSingleTurn: vi.fn(),
+ completeSingleTurnWithTools,
+ getProviderType: () => 'openai' as const,
+ classifyError: vi.fn(),
+ },
+ 'unknown-model',
+ 'openai',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined
+ )
+ const fallbackMessages = structuredClone(shaped)
+ await fallback.completeWithTools({ messages: fallbackMessages, tools: [] })
+ expect(completeSingleTurnWithTools).toHaveBeenCalledTimes(1)
+ expect(fallbackMessages.some(m => m.contentParts?.some(p => p.type === 'image'))).toBe(true)
+ expect(JSON.stringify(completeSingleTurnWithTools.mock.calls[0][0])).not.toContain(
+ '"type":"image"'
+ )
+ expect(sdkCreate).not.toHaveBeenCalled()
+ await subject.adapter.completeWithTools({ messages: shaped, tools: [] })
+ expect(sdkCreate).toHaveBeenCalledTimes(1)
+ subject.budget.close()
+ })
+ it.each(['image/png', 'image/jpeg'] as const)(
+ 'delivers unchanged %s bytes as a visual part',
+ async mime => {
+ const canvas = createCanvas(8, 8)
+ const context = canvas.getContext('2d')
+ context.fillStyle = '#186bcc'
+ context.fillRect(0, 0, 8, 8)
+ const bytes =
+ mime === 'image/png' ? canvas.toBuffer('image/png') : canvas.toBuffer('image/jpeg')
+ const subject = await setup(bytes, { name: 'incorrect-extension.txt' })
+ expect(subject.output.is_error).toBe(false)
+ expect(subject.output.attachments?.[0].visualSource).toMatchObject({
+ gfsUri: uri,
+ version: 7,
+ })
+ expect(subject.collected).toEqual([])
+ await subject.adapter.completeWithTools({ messages: subject.messages, tools: [] })
+ const request = sdkCreate.mock.calls[0][0]
+ const imagePart = request.messages
+ .flatMap((m: { content: unknown }) => (Array.isArray(m.content) ? m.content : []))
+ .find((p: { type?: string }) => p.type === 'image_url')
+ expect(imagePart.image_url.url).toBe(`data:${mime};base64,${bytes.toString('base64')}`)
+ const toolMessage = request.messages.find((m: { role: string }) => m.role === 'tool')
+ expect(typeof toolMessage.content).toBe('string')
+ expect(toolMessage.content).not.toContain(bytes.toString('base64'))
+ expect(subject.metadataFetch).not.toHaveBeenCalled()
+ expect(subject.gfsFetch).toHaveBeenCalledTimes(2)
+ subject.budget.close()
+ expect(subject.budget.residentBytes).toBe(0)
+ }
+ )
+
+ it.each([
+ '',
+ '\ufeffBOM and acentos: áéíóú',
+ 'tabs\tLF\nCRLF\r\n',
+ '{"ok":false,"data":"text"}',
+ 'PK is a text prefix. RIFF is also a word. Unicode: 🌴\r\n',
+ ])('keeps UTF-8 text usable without requiring vision: %j', async text => {
+ const subject = await setup(Buffer.from(text), { name: 'note.txt', catalogState: 'missing' })
+ expect(subject.output.content).toBe(text.replace(/^\ufeff/, ''))
+ expect(subject.output.attachments).toBeUndefined()
+ await subject.adapter.completeWithTools({ messages: subject.messages, tools: [] })
+ expect(subject.metadataFetch).not.toHaveBeenCalled()
+ expect(sdkCreate).toHaveBeenCalledTimes(1)
+ subject.budget.close()
+ })
+
+ it.each([
+ Buffer.from('a\0b'),
+ Buffer.from([0xc3, 0x28]),
+ Buffer.from([0x01, 0x41]),
+ Buffer.from('%PDF-1.7'),
+ Buffer.from([0x50, 0x4b, 0x03, 0x04]),
+ Buffer.from('<?xml version="1.0"?><svg xmlns="http://www.w3.org/2000/svg"/>'),
+ Buffer.from('<svg/>'),
+ ])('returns a reference instead of interpreting unsupported bytes as text', async bytes => {
+ const subject = await setup(bytes, { name: 'misleading.txt' })
+ expect(JSON.parse(subject.output.content).delivery).toBe('reference_only')
+ expect(subject.output.attachments).toBeUndefined()
+ expect(subject.metadataFetch).not.toHaveBeenCalled()
+ subject.budget.close()
+ })
+
+ it.each([
+ { catalogState: 'unsupported' },
+ { catalogState: 'unknown' },
+ { catalogState: 'missing' },
+ ] as const)(
+ 'returns an explicit reference when catalog image capability is not established: %j',
+ async options => {
+ const subject = await setup(createCanvas(1, 1).toBuffer('image/png'), options)
+ expect(JSON.parse(subject.output.content).delivery).toBe('reference_only')
+ expect(subject.output.attachments).toBeUndefined()
+ expect(subject.messages.some(m => m.contentParts?.some(p => p.type === 'image'))).toBe(false)
+ subject.budget.close()
+ }
+ )
+
+ it('rechecks the actual destination instead of forwarding images to an unknown fallback', async () => {
+ const subject = await setup(createCanvas(1, 1).toBuffer('image/png'))
+ const completeSingleTurnWithTools = vi.fn().mockResolvedValue({
+ content: 'degraded',
+ tool_calls: [],
+ usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 },
+ finish_reason: 'stop',
+ })
+ const fallback = new LlmPortAdapter(
+ {
+ completeSingleTurn: vi.fn(),
+ completeSingleTurnWithTools,
+ getProviderType: () => 'openai' as const,
+ classifyError: vi.fn(),
+ },
+ 'unknown-model',
+ 'openai'
+ )
+ const fallbackMessages = structuredClone(subject.messages)
+ await fallback.completeWithTools({ messages: fallbackMessages, tools: [] })
+ expect(completeSingleTurnWithTools).toHaveBeenCalledTimes(1)
+ expect(fallbackMessages.some(m => m.contentParts?.some(p => p.type === 'image'))).toBe(true)
+ expect(JSON.stringify(completeSingleTurnWithTools.mock.calls[0][0])).not.toContain(
+ '"type":"image"'
+ )
+ expect(sdkCreate).not.toHaveBeenCalled()
+ subject.budget.close()
+ })
+})
diff --cc mcp-host/src/internalTools/gfsReadTypes.ts
index 24747d90d,000000000..29effe57b
mode 100644,000000..100644
--- a/mcp-host/src/internalTools/gfsReadTypes.ts
+++ b/mcp-host/src/internalTools/gfsReadTypes.ts
@@@ -1,15 -1,0 +1,16 @@@
+import type { GfsImageSource, MemoryReservation, VisualInputBudget } from '../visualInput/policy'
+
+export interface GfsReadOptions {
+ signal?: AbortSignal
+ timeoutMs?: number
++ deadlineMs?: number
+ budget?: VisualInputBudget
+}
+
+/** A validated metadata/content snapshot. This object is never a tool result. */
+export interface GfsFileContent {
+ source: GfsImageSource
+ bytes: Buffer
+ /** The consumer must release the read buffer after classification/encoding. */
+ reservation: MemoryReservation
+}
diff --cc mcp-host/src/workflow/stepRouter.ts
index d295a879e,b66ef13c5..13bfecd3f
--- a/mcp-host/src/workflow/stepRouter.ts
+++ b/mcp-host/src/workflow/stepRouter.ts
@@@ -247,12 -243,10 +247,13 @@@ export class StepMcpRouter
}
}
const start = Date.now()
- const internalResult = await internalTool.execute(args, this.outputDir, {
- signal: options.signal,
- timeoutMs: options.timeoutMs,
- })
+ const internalResult = projectInternalToolResult(
+ await internalTool.execute(args, this.outputDir, {
- ...options,
++ signal: options.signal,
++ timeoutMs: options.timeoutMs,
+ readBudget: this.readBudget,
+ })
+ )
const durationMs = Date.now() - start
const record: ToolCallRecord = {
serverName: 'clerum',
diff --cc mcp-host/src/workflow/types.ts
index 302d222a1,ae70cf492..a1d2acb8d
--- a/mcp-host/src/workflow/types.ts
+++ b/mcp-host/src/workflow/types.ts
@@@ -3,9 -3,7 +3,8 @@@
*
* Source of truth: STAGE-2-STEP-EXECUTION-ENGINE.md §4.3–§4.7
*/
- import type { ExecutionContext } from '../core/interfaces'
import type { LlmProvider } from '../llm/registryCore'
+import type { VisualImage, VisualInputBudget, VisualInputContext } from '../visualInput/policy'
// ─── MCP Server Reference (per-step) ───────────────────────────────────
@@@ -204,14 -200,16 +203,21 @@@ export interface InternalToolResult
error?: string
}
- export interface InternalToolExecutionOptions extends Pick<
- ExecutionContext,
- 'signal' | 'timeoutMs'
- > {
+ /**
+ * The bounds of the tool call that runs an internal tool: the caller's cancel
+ * signal and the time left in its budget. Tools that make network calls pass
+ * both on, so a call never outlives the step or chat turn that issued it.
+ */
+ export interface InternalToolCallContext {
+ signal?: AbortSignal
+ timeoutMs?: number
+ }
+
++export interface InternalToolExecutionOptions extends InternalToolCallContext {
+ readBudget?: VisualInputBudget
+ visualInput?: VisualInputContext
+}
+
export interface InternalToolDefinition {
name: string
description: string
diff --cc mcp-host/src/workflow/workflowService.gating.test.ts
index cd8ec4dda,3656b07f9..f1eee5866
--- a/mcp-host/src/workflow/workflowService.gating.test.ts
+++ b/mcp-host/src/workflow/workflowService.gating.test.ts
@@@ -88,6 -88,6 +88,7 @@@ describe('WorkflowService approval gati
})
afterEach(() => {
++ vi.restoreAllMocks()
config.mcpHostRuntimeAccessToken = originalMcpHostRuntimeAccessToken
config.mcpHostRuntimeRefreshToken = originalMcpHostRuntimeRefreshToken
config.mcpHostGatewayUrl = originalMcpHostGatewayUrl
@@@ -489,35 -490,32 +491,44 @@@ describe('WorkflowService internal-tool
expect(names).not.toContain('clerum__gfs_write')
})
- it('dispatches workflow GFS calls through the existing gfsc client boundary', async () => {
+ it('dispatches workflow GFS calls through the existing gfsc client boundary, bounded by the step', async () => {
gfsGate.enabled = true
process.env.MCP_HOST_GFS_SCOPES = 'gfs.read'
- gfsClient.read.mockResolvedValue({ content: 'granted file content' })
+ const release = vi.fn()
+ gfsClient.read.mockResolvedValue({
+ source: {
+ kind: 'gfs',
+ drive: 'main',
+ resourceId: '0123456789abcdef0123456789abcdef',
+ gfsUri: 'gfs://main/0123456789abcdef0123456789abcdef',
+ version: 1,
+ name: 'note.txt',
+ },
+ bytes: Buffer.from('granted file content'),
+ reservation: { release },
+ })
+ // The step starts at T and the model takes 30 s before it asks for the
+ // read. The call must carry the step's own end (T + 120 s), not a fresh
+ // full timeout from the moment of the call (T + 150 s).
+ const T = 1_900_000_000_000
+ let clock = T
+ vi.spyOn(Date, 'now').mockImplementation(() => clock)
const provider = makeProvider()
vi.mocked(provider.completeSingleTurnWithTools)
- .mockResolvedValueOnce({
- content: '',
- tool_calls: [
- {
- id: 'gfs-read-1',
- name: 'clerum__gfs_read',
- arguments: { drive: 'main', resourceId: '0123456789abcdef0123456789abcdef' },
- },
- ],
- usage: { input_tokens: 10, output_tokens: 5, total_tokens: 15 },
- finish_reason: FinishReason.ToolUse,
+ .mockImplementationOnce(async () => {
+ clock += 30_000
+ return {
+ content: '',
+ tool_calls: [
+ {
+ id: 'gfs-read-1',
+ name: 'clerum__gfs_read',
+ arguments: { drive: 'main', resourceId: '0123456789abcdef0123456789abcdef' },
+ },
+ ],
+ usage: { input_tokens: 10, output_tokens: 5, total_tokens: 15 },
+ finish_reason: FinishReason.ToolUse,
+ }
})
.mockResolvedValueOnce({
content: 'Read completed.',
@@@ -547,16 -546,42 +559,48 @@@
result: expect.objectContaining({ success: true }),
}),
])
- expect(gfsClient.read).toHaveBeenCalledWith(
- {
- drive: 'main',
- resourceId: '0123456789abcdef0123456789abcdef',
- },
- expect.objectContaining({ signal: expect.any(AbortSignal), budget: expect.any(Object) })
- )
+ expect(createGfscClient).toHaveBeenCalledTimes(1)
+ expect(vi.mocked(createGfscClient).mock.calls[0]?.[1]).toEqual({ maxRetryWaitMs: 120_000 })
+ expect(gfsClient.read).toHaveBeenCalledTimes(1)
+ const [args, call] = gfsClient.read.mock.calls[0] ?? []
+ expect(args).toEqual({ drive: 'main', resourceId: '0123456789abcdef0123456789abcdef' })
- expect(call).toEqual({ signal: expect.any(AbortSignal), deadlineMs: T + 120_000 })
++ expect(call).toMatchObject({
++ signal: expect.any(AbortSignal),
++ deadlineMs: T + 120_000,
++ timeoutMs: expect.any(Number),
++ budget: expect.any(Object),
++ })
+ expect(release).toHaveBeenCalledOnce()
})
+ it('fails the step, without rejecting, when the gfsc client cannot be created', async () => {
+ gfsGate.enabled = true
+ process.env.MCP_HOST_GFS_SCOPES = 'gfs.read'
+ vi.mocked(createGfscClient).mockImplementationOnce(() => {
+ throw new Error('gfsc client maxRetryWaitMs must be a non-negative number, got NaN')
+ })
+ const provider = makeProvider()
+ const service = new WorkflowService('recipe-1', {
+ llmFactory: () => provider,
+ mcpClientFactory: () => {
+ throw new Error('mcp client must not be created in this GFS gate test')
+ },
+ })
+ service.configure({ provider: 'openai', apiKey: 'fake-api-key', model: 'gpt-4o' })
+
+ const result = await service.executeStep({
+ stepId: 'gfs-client-fails',
+ instruction: 'Read the granted file.',
+ allowedTools: { include: ['clerum__gfs_read'] },
+ })
+
+ // Witness: the step reached the client construction.
+ expect(createGfscClient).toHaveBeenCalledTimes(1)
+ expect(result).toMatchObject({ stepId: 'gfs-client-fails', status: 'failed' })
+ expect(result.error).toContain('maxRetryWaitMs')
+ expect(provider.completeSingleTurnWithTools).not.toHaveBeenCalled()
+ })
+
it('fails closed when toolChoice is required but no allowed tool is available', async () => {
const provider = makeProvider()
const service = new WorkflowService('recipe-1', {