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.jsonindex 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.jsonindex 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.tsindex 000000000,d98a82129..180cc2ca8mode 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.tsindex 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.tsindex 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 | undefinedtry {- 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.tsindex 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.tsindex 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: Greturn 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.tsindex 6b3981a3a,000000000..5970167d4mode 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.tsindex 62268de10,000000000..89174d5f6mode 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.tsindex 24747d90d,000000000..29effe57bmode 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.tsindex 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() - startconst record: ToolCallRecord = {serverName: 'clerum',diff --cc mcp-host/src/workflow/types.tsindex 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 InternalToolResulterror?: 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: stringdescription: stringdiff --cc mcp-host/src/workflow/workflowService.gating.test.tsindex 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 = originalMcpHostRuntimeAccessTokenconfig.mcpHostRuntimeRefreshToken = originalMcpHostRuntimeRefreshTokenconfig.mcpHostGatewayUrl = originalMcpHostGatewayUrl@@@ -489,35 -490,32 +491,44 @@@ describe('WorkflowService internal-toolexpect(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 = trueprocess.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', {