Skip to content

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

TypeScript

fix(mcp-host): close GFS namespace and recovery regressions

Alfredo Lopezacee429d4430
diff --git a/docs/operations/gfs-large-file-host-downloads.md b/docs/operations/gfs-large-file-host-downloads.md
index ae4f1b256..ce4915a69 100644
--- a/docs/operations/gfs-large-file-host-downloads.md
+++ b/docs/operations/gfs-large-file-host-downloads.md
@@ -158,6 +158,14 @@ Generic workspace tools reject direct and symlink-resolved access to `.gfs-downl
impossible or invalid request cannot evict another caller's files. Active,
pinned, inherited, corrupt and ambiguous entries are never pressure victims.
Quota limits still reject a request when no safe complete plan exists.
+- Before pressure effects, current verified filesystem capacity must cover the
+ incoming block-rounded reservation, the 16 MiB safety margin and pending
+ active reservations. Apparent file length and allocated blocks do not prove
+ how much a reflink or snapshot deletion will release. This generic policy does
+ not credit hypothetical physical reclamation; insufficient current capacity
+ rejects without deleting pressure victims. Quota eviction can still proceed
+ when current physical capacity is sufficient. Capacity is checked again after
+ settlement and before admission because external filesystem changes can race.
- Only positively identified expired or pressure-evictable entries are deleted.
Quota charges are released only after positive filesystem absence. A cleanup
failure remains charged and is observable for recovery.
@@ -194,6 +202,18 @@ starts after successful acquisition, including acquisition after retry.
Shutdown cancels scheduling, joins outstanding work and closes held writer
ownership even when delivery is unavailable.
+Lease admission verifies the checksum of every retained completed caller copy
+under store serialization. Its cost grows with retained caller bytes; the
+default caller budget is 256 MiB. This correctness check has not been benchmarked
+on every supported PVC. Stage 2 must measure concurrency and evaluate verified
+descriptor/state revalidation outside the mutex before changing that contract.
+
+A pending task pin can survive a Host restart and protect bytes beyond TTL.
+If the task never resumes, use the operator inventory and exact terminal-owner
+recovery protocol. A time limit or cache pressure cannot prove that owner is
+unused. Monitor bounded counts and retained bytes; do not label metrics with
+owner or caller IDs.
+
Execution safety binding is independent of delivery eligibility. Cron,
internal and approval-disabled tasks associated with this store cannot obtain
an unleased shared-root shell during recovery. Trusted system tasks use the
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 5084bf3fe..9a07b3343 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.491",
+ "version": "0.1.492",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.491",
+ "version": "0.1.492",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index b4e1ff97d..894f4eb5d 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.491",
+ "version": "0.1.492",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/agent/__tests__/approval.test.ts b/mcp-host/src/agent/__tests__/approval.test.ts
index 41a202248..736e22df8 100644
--- a/mcp-host/src/agent/__tests__/approval.test.ts
+++ b/mcp-host/src/agent/__tests__/approval.test.ts
@@ -1,6 +1,8 @@
import { beforeEach, describe, expect, it, vi } from 'vitest'
import type { ApprovalConfig } from '../../core/extensions/approvalTypes'
+import { UnifiedApprovalGateController } from '../../core/extensions/mcpApprovalGateController'
import { executeSingleTool, runToolUseLoop } from '../../core/orchestration/toolUseLoop'
+import { ShellTool } from '../../core/tools/shell'
import { ConversationState } from '../../core/types'
import { TaskLifecycle } from '../../lifecycle/taskLifecycle'
import { progressReporterRegistry } from '../../progress/sseProgressReporter'
@@ -232,10 +234,19 @@ describe('AgentStateMachine -- approval handling', () => {
})
it('should add tool to auto_approved_tools when alwaysApprove=true (6.auto)', async () => {
+ const shell = new ShellTool('/tmp', 5000, ['PATH'])
+ const gate = new UnifiedApprovalGateController({
+ get: name => (name === shell.name() ? shell : null),
+ register: () => {},
+ listDefinitions: () => [],
+ })
+ const decision = gate.beforeTool('shell_exec', { command: 'ls' })
+ if (typeof decision !== 'object') throw new Error('Ordinary shell producer did not suspend')
;(runToolUseLoop as ReturnType<typeof vi.fn>)
.mockResolvedValueOnce({
type: 'need_approval',
approval: {
+ ...decision.approval,
request_id: 'req-1',
tool_name: 'shell_exec',
parameters: { command: 'ls' },
diff --git a/mcp-host/src/agent/__tests__/callerRootBinding.test.ts b/mcp-host/src/agent/__tests__/callerRootBinding.test.ts
new file mode 100644
index 000000000..fa2ce5248
--- /dev/null
+++ b/mcp-host/src/agent/__tests__/callerRootBinding.test.ts
@@ -0,0 +1,180 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { buildGfsFileReference, classifyBytes } from '@clerum/gfs-interaction-policy'
+import { runToolUseLoop } from '../../core/orchestration/toolUseLoop'
+import { bootstrapGfsRuntime } from '../../gfsRuntime'
+import { TaskLifecycle } from '../../lifecycle/taskLifecycle'
+import { MessageQueue } from '../../queue'
+import type { Task } from '../../queue/types'
+import { resolveCallerRootBinding } from '../../workspace/callerRootBinding'
+import { type IncomingAdmissionDeps, createIncomingAdmission } from '../incomingAdmission'
+import { AgentStateMachine } from '../stateMachine'
+
+vi.mock('../../config', () => ({
+ config: {
+ enableApproval: false,
+ codexToolPresentation: 'direct',
+ dynamicToolsEnabled: false,
+ promptCacheEnabled: false,
+ contextMaxTokens: 100_000,
+ nativeTool: {
+ workspacePath: '/tmp',
+ shellTimeout: 5_000,
+ toolTimeout: 60_000,
+ toolProgressInterval: 0,
+ httpAllowlist: [],
+ envAllowlist: ['PATH'],
+ memoryMaxSize: 1_048_576,
+ },
+ },
+}))
+
+vi.mock('../../core/orchestration/toolUseLoop', () => ({
+ runToolUseLoop: vi.fn(),
+ executeSingleTool: vi.fn(),
+ validateToolLinkages: vi.fn(),
+}))
+
+function textTask(): Task {
+ return {
+ id: '11111111-1111-4111-8111-111111111112',
+ source: 'channel',
+ status: 'pending',
+ priority: 'normal',
+ createdAt: new Date(),
+ sourceMessage: {
+ sender: 'alice',
+ content: 'ordinary text only',
+ channelType: 'rpc',
+ channelId: 'agent',
+ messageId: 'message-1',
+ timestamp: new Date().toISOString(),
+ hostRef: 'host-1',
+ },
+ conversationHistory: [{ role: 'user', content: 'ordinary text only', timestamp: new Date() }],
+ responseCallback: vi.fn(async () => undefined),
+ }
+}
+
+describe('degraded GFS caller-root binding', () => {
+ beforeEach(() => {
+ vi.mocked(runToolUseLoop).mockResolvedValue({
+ type: 'response',
+ content: 'ordinary text completed',
+ usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 },
+ })
+ })
+
+ it('keeps ordinary text running while managed file/shell roots fail closed', async () => {
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gfs-degraded-binding-'))
+ try {
+ fs.mkdirSync(path.join(root, '.gfs-download-store'), { recursive: true })
+ fs.writeFileSync(path.join(root, '.gfs-download-store', 'ledger-v1.json'), '{invalid')
+ fs.writeFileSync(path.join(root, 'users'), 'not-a-directory', 'utf-8')
+ const runtime = await bootstrapGfsRuntime(root)
+ const queue = new MessageQueue()
+ const lifecycle = new TaskLifecycle()
+ const agent = new AgentStateMachine(queue, lifecycle, { autoStart: false, taskDelay: 0 })
+ const provider = {
+ completeSingleTurn: vi.fn(),
+ completeSingleTurnWithTools: vi.fn(),
+ getProviderType: () => 'openai' as const,
+ }
+ agent.setLLMProvider(provider as never)
+ agent.setGfsWorkspaceProvider(runtime.workspaceProvider)
+ agent.setGfsDownloadStore(runtime.store)
+
+ const task = textTask()
+ lifecycle.register(task)
+ lifecycle.transition(task.id, 'processing', 'dispatched')
+ vi.mocked(runToolUseLoop).mockImplementationOnce(async config => {
+ expect(config.toolRegistry.get('file_read')).toBeNull()
+ expect(config.toolRegistry.get('file_write')).toBeNull()
+ const shell = await config.toolRegistry.get('shell_exec')!.execute({ command: 'pwd' })
+ expect(shell.is_error).toBe(true)
+ expect(shell.content).toContain('Managed shell unavailable')
+ return {
+ type: 'response',
+ content: 'ordinary text completed',
+ usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 },
+ }
+ })
+ await agent.executeTask(task)
+
+ expect(runToolUseLoop).toHaveBeenCalledTimes(1)
+ expect(task.responseCallback).toHaveBeenCalledWith(
+ expect.objectContaining({ response: 'ordinary text completed' })
+ )
+ expect(fs.existsSync(path.join(root, 'host-root-write.txt'))).toBe(false)
+ } finally {
+ fs.rmSync(root, { recursive: true, force: true })
+ }
+ })
+
+ it('keeps real incoming admission dispatching when the GFS caller root is degraded', async () => {
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gfs-degraded-admission-'))
+ try {
+ fs.mkdirSync(path.join(root, '.gfs-download-store'), { recursive: true })
+ fs.writeFileSync(path.join(root, '.gfs-download-store', 'ledger-v1.json'), '{invalid')
+ fs.writeFileSync(path.join(root, 'users'), 'not-a-directory', 'utf-8')
+ const runtime = await bootstrapGfsRuntime(root)
+ const reference = buildGfsFileReference({
+ drive: 'main',
+ resourceId: 'a'.repeat(32),
+ gfsUri: `gfs://main/${'a'.repeat(32)}`,
+ version: 7,
+ name: 'input.csv',
+ byteLength: 10_240,
+ classification: classifyBytes({
+ bytes: Buffer.alloc(10_240),
+ totalByteLength: 10_240,
+ filename: 'input.csv',
+ declaredMediaType: null,
+ }),
+ })
+ if (!reference.ok) throw new Error(reference.message)
+ const dispatch = vi.fn(() => ({
+ success: true,
+ taskId: 'task-1',
+ status: 'pending' as const,
+ }))
+ const deps: IncomingAdmissionDeps = {
+ limits: { maxCount: 4, maxBytes: 1_000_000, maxFileBytes: 1_000_000 },
+ queueReady: () => true,
+ degradedReason: () => null,
+ hostProvider: () => 'openai',
+ getConversationByKey: async () => undefined,
+ resolveTaskModel: () => null,
+ resolveImageInput: () => undefined,
+ applySessionModelSelection: vi.fn(),
+ dispatch,
+ fileReferenceGfs: () => ({ status: 'unsupported' }),
+ gfsSurfaceRuntimeCapability: message => {
+ const binding = resolveCallerRootBinding(runtime.workspaceProvider, message)
+ const workspaceFile = Boolean(runtime.store.isAvailable() && binding.root)
+ return { workspaceFile, localExecutor: workspaceFile, visual: false }
+ },
+ logger: { info: vi.fn(), warn: vi.fn() },
+ }
+
+ const admit = createIncomingAdmission(deps)
+ const response = await admit({
+ content: 'read referenced file',
+ channelType: 'rpc',
+ channelId: 'agent',
+ sender: 'alice',
+ timestamp: new Date().toISOString(),
+ messageId: 'message-2',
+ hostRef: 'host-1',
+ fileReferences: [reference.value],
+ })
+
+ expect(response).toMatchObject({ success: true, taskId: 'task-1' })
+ expect(dispatch).toHaveBeenCalledTimes(1)
+ } finally {
+ fs.rmSync(root, { recursive: true, force: true })
+ }
+ })
+})
diff --git a/mcp-host/src/agent/__tests__/taskExecutor.gfsBatchReceipt.integration.test.ts b/mcp-host/src/agent/__tests__/taskExecutor.gfsBatchReceipt.integration.test.ts
new file mode 100644
index 000000000..9937678b9
--- /dev/null
+++ b/mcp-host/src/agent/__tests__/taskExecutor.gfsBatchReceipt.integration.test.ts
@@ -0,0 +1,310 @@
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+import { createHash, randomUUID } from 'node:crypto'
+import * as fs from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { config as appConfig } from '../../config'
+import { ConversationManager } from '../../core/conversation/conversation'
+import {
+ type StoreHandle,
+ makeSqliteStore,
+} from '../../core/conversation/persistence/__tests__/testHelpers'
+import { SqliteConversationStore } from '../../core/conversation/persistence/sqliteConversationStore'
+import { SimpleEventEmitter } from '../../core/orchestration/eventEmitter'
+import { type ChatMessage, FinishReason, type ToolCall } from '../../core/types'
+import { type GfsDownloadReceipt, GfsDownloadStore } from '../../internalTools/gfsDownloadStore'
+import { TaskLifecycle } from '../../lifecycle/taskLifecycle'
+import type { SingleTurnProvider } from '../../llm/types'
+import type { Task } from '../../queue/types'
+import { resolveVisualDeliveryLimits } from '../../visualInput/deliveryLimits'
+import { ScopedWorkspaceProvider } from '../../workspace/scopedWorkspace'
+import { TaskExecutor, type TaskExecutorDeps, resolveTaskSessionKey } from '../taskExecutor'
+
+const { clientFactory } = vi.hoisted(() => ({ clientFactory: vi.fn() }))
+// Double only GFSC's external transport and the model. The native registry,
+// store, decoder, shell, SQLite dispatcher and approval reconstruction stay real.
+vi.mock('../../internalTools/gfsClient', async importOriginal => ({
+ ...(await importOriginal<typeof import('../../internalTools/gfsClient')>()),
+ getGfsToolScopes: () => new Set(['gfs.read']),
+ createGfscClient: clientFactory,
+}))
+
+const { realPngOfSize } = createRequire(
+ join(__dirname, 'taskExecutor.gfsBatchReceipt.integration.test.ts')
+)('../../../../packages/llm-provider-attempt-contract/testImageFixtures.cjs') as {
+ realPngOfSize: (size: number, width: number, height: number, seed: number) => Buffer
+}
+const bytes = realPngOfSize(12 * 1024, 2, 2, 7)
+const digest = createHash('sha256').update(bytes).digest('hex')
+const rid = '1234567890abcdef1234567890abcdef'
+const uri = `gfs://main/${rid}`
+const saved = {
+ enableApproval: appConfig.enableApproval,
+ codexToolPresentation: appConfig.codexToolPresentation,
+ dynamicToolsEnabled: appConfig.dynamicToolsEnabled,
+ promptCacheEnabled: appConfig.promptCacheEnabled,
+}
+let root: string | undefined
+let store: GfsDownloadStore | undefined
+let handle: StoreHandle | undefined
+let taskOwner: { id: string; caller: string } | undefined
+
+beforeEach(() => {
+ Object.assign(appConfig, {
+ enableApproval: true,
+ codexToolPresentation: 'direct',
+ dynamicToolsEnabled: false,
+ promptCacheEnabled: false,
+ })
+})
+afterEach(async () => {
+ await handle?.shutdown()
+ // All task methods are awaited by the test. Release only this synthetic
+ // owner's remaining pin when a failing assertion interrupted the journey.
+ if (store && taskOwner) await store.releaseReceiptOwner(taskOwner.id, taskOwner.caller)
+ await store?.close()
+ if (root) await fs.rm(root, { recursive: true, force: true })
+ root = undefined
+ store = undefined
+ handle = undefined
+ taskOwner = undefined
+ Object.assign(appConfig, saved)
+ vi.clearAllMocks()
+})
+
+function shellCall(id: string, command: string): ToolCall {
+ return { id, name: 'shell_exec', arguments: { command } }
+}
+function shellQuote(value: string): string {
+ return `'${value.replaceAll("'", "'\\''")}'`
+}
+
+it('keeps the exact workspace receipt through same-batch image suspension, SQLite cold resume and fresh CLI consent', async () => {
+ root = await fs.mkdtemp(join(tmpdir(), 'gfs-batch-receipt-'))
+ store = new GfsDownloadStore(root)
+ await store.initialize()
+ const createTransfer = vi.spyOn(store, 'createTransfer')
+ const readManagedFile = vi.spyOn(store, 'readManagedFile')
+ const releaseOwner = vi.spyOn(store, 'releaseReceiptOwner')
+ handle = makeSqliteStore()
+ const manager = new ConversationManager(handle.store)
+ const receipts: GfsDownloadReceipt[] = []
+ let contentRequests = 0
+ const gfsFetch = vi.fn(async (url: string) => {
+ if (url.includes('/content?')) {
+ contentRequests += 1
+ return new Response(new Uint8Array(bytes), {
+ headers: {
+ 'content-type': 'application/octet-stream',
+ 'content-length': String(bytes.byteLength),
+ 'x-gfs-uri': uri,
+ 'x-gfs-version': '7',
+ },
+ })
+ }
+ return new Response(
+ JSON.stringify({
+ ok: true,
+ data: {
+ resourceId: rid,
+ rid,
+ drive: 'main',
+ gfsUri: uri,
+ version: 7,
+ kind: 'file',
+ name: 'synthetic.png',
+ bytes: bytes.byteLength,
+ },
+ }),
+ { headers: { 'content-type': 'application/json' } }
+ )
+ })
+ const { createGfscClient } = await vi.importActual<
+ typeof import('../../internalTools/gfsClient')
+ >('../../internalTools/gfsClient')
+ const client = createGfscClient(
+ { get: () => undefined, readFile: async () => 'unit-only-identity', fetch: gfsFetch },
+ { maxRetryWaitMs: 30_000, random: () => 0 }
+ )
+ const download = client.download!.bind(client)
+ vi.spyOn(client, 'download').mockImplementation(async (...args) => {
+ const receipt = await download(...args)
+ receipts.push(structuredClone(receipt))
+ return receipt
+ })
+ clientFactory.mockReturnValue(client)
+
+ const firstShell = shellCall('first-shell', 'printf batch-approved')
+ const readCall: ToolCall = {
+ id: 'read-image',
+ name: 'clerum__gfs_read',
+ arguments: { drive: 'main', resourceId: rid, expectedVersion: 7 },
+ }
+ const requests: ChatMessage[][] = []
+ const provider: SingleTurnProvider = {
+ getProviderType: () => 'codex-subscription',
+ getVisualDeliveryLimits: () => resolveVisualDeliveryLimits('codex-subscription'),
+ classifyError: () => ({
+ code: 'LLM_UNKNOWN_ERROR' as never,
+ retryable: false,
+ message: 'fixture classification',
+ }),
+ completeSingleTurn: async () => {
+ throw new Error('Unexpected plain completion')
+ },
+ completeSingleTurnWithTools: async messages => {
+ requests.push(structuredClone(messages))
+ let calls: ToolCall[] | null = null
+ if (requests.length === 1) calls = [readCall, firstShell]
+ if (requests.length === 2) {
+ const completed = messages.find(
+ message => message.tool_call_id === readCall.id && message.role === 'tool'
+ )!
+ const receipt = JSON.parse(completed.content) as GfsDownloadReceipt & { delivery: string }
+ expect(receipt.delivery).toBe('workspace_file')
+ expect(receipt).toMatchObject(receipts[0]!)
+ const program = `const fs=require("fs"),crypto=require("crypto");const b=fs.readFileSync(${JSON.stringify(receipt.path)});process.stdout.write(JSON.stringify({bytes:b.length,sha256:crypto.createHash("sha256").update(b).digest("hex")}))`
+ calls = [
+ shellCall(
+ 'process-retained',
+ `${shellQuote(process.execPath)} -e ${shellQuote(program)}`
+ ),
+ ]
+ }
+ return {
+ content: calls ? null : 'Retained input processed.',
+ tool_calls: calls,
+ usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 },
+ finish_reason: calls ? FinishReason.ToolUse : FinishReason.Stop,
+ }
+ },
+ }
+ const task: Task = {
+ id: randomUUID(),
+ source: 'channel',
+ status: 'pending',
+ priority: 'normal',
+ createdAt: new Date(),
+ sourceMessage: {
+ sender: 'batch-receipt-caller',
+ channelType: 'rpc',
+ channelId: 'batch-receipt-chat',
+ messageId: 'batch-receipt-message',
+ hostRef: 'unit-host',
+ timestamp: new Date().toISOString(),
+ content: 'Process the synthetic input',
+ },
+ conversationHistory: [
+ { role: 'user', content: 'Process the synthetic input', timestamp: new Date() },
+ ],
+ responseCallback: vi.fn(async () => undefined),
+ }
+ const callerRoot = new ScopedWorkspaceProvider(root).forSource(task.sourceMessage).userRootPath
+ taskOwner = { id: task.id, caller: task.sourceMessage!.sender }
+ const lifecycle = new TaskLifecycle()
+ lifecycle.register(task)
+ const onFail = vi.fn()
+ const onApprovalNeeded = vi.fn()
+ const onComplete = vi.fn()
+ const deps: TaskExecutorDeps = {
+ conversationManager: manager,
+ llmProvider: provider,
+ mcpManager: null,
+ workspaceService: undefined,
+ gfsDownloadStore: store,
+ gfsCallerWorkspacePath: callerRoot,
+ imageInput: () => ({}),
+ modelName: 'fixture-model',
+ approvalConfig: { defaultPolicy: 'channel_users', channels: {} },
+ config: {
+ maxTaskDuration: 30_000,
+ maxToolCallsPerTask: 10,
+ autoStart: true,
+ taskDelay: 0,
+ approvalTimeout: 30_000,
+ },
+ coreEvents: new SimpleEventEmitter(),
+ cronScheduler: null,
+ taskLifecycle: lifecycle,
+ onApprovalNeeded,
+ onComplete,
+ onFail,
+ dynamicEnvProvider: () => ({}),
+ }
+ const first = new TaskExecutor(task, deps)
+ await first.run()
+ expect(onFail).not.toHaveBeenCalled()
+ expect(first.executorState).toBe('waiting_approval')
+ expect(first.pendingApproval?.tool_call_id).toBe(firstShell.id)
+ expect(receipts).toHaveLength(1)
+ expect(createTransfer).toHaveBeenCalledWith(
+ expect.objectContaining({ retentionOwnerId: task.id })
+ )
+ expect(readManagedFile).toHaveBeenCalledOnce()
+ expect(contentRequests).toBe(1)
+ const completed = first.pendingApproval!.completed_results!.find(
+ item => item.tool_call_id === readCall.id
+ )!
+ const expected = {
+ ...receipts[0],
+ delivery: 'workspace_file',
+ visualDelivery: 'not_included',
+ visualReason: 'new_gfs_read_required_after_suspension',
+ usage: {
+ pathSemantics: 'relative-to-caller-workspace',
+ nextTool: 'shell_exec_when_local_processing_is_needed',
+ approval: 'user-approval-required',
+ visualDelivery: 'not_included',
+ visualReason: 'new_gfs_read_required_after_suspension',
+ writeOutputsTo: 'outputs/',
+ processLocally: true,
+ boundedOutputOnly: true,
+ wholeFileToContextAllowed: false,
+ },
+ }
+ expect(JSON.parse(completed.content)).toMatchObject(expected)
+ expect(completed.attachments).toBeUndefined()
+ expect(completed.spillover_ref).toBeUndefined()
+ expect(JSON.stringify(first.pendingApproval)).not.toContain(bytes.toString('base64'))
+ expect(releaseOwner).not.toHaveBeenCalled()
+
+ const coldManager = new ConversationManager(
+ new SqliteConversationStore(handle.persistQueue, { cacheSize: 8 })
+ )
+ const sessionKey = resolveTaskSessionKey(task)
+ const coldConversation = await coldManager.getOrCreate(sessionKey)
+ expect(coldConversation).not.toBe(manager.getStore().get(sessionKey))
+ expect(
+ JSON.parse(coldConversation.pending_approval!.completed_results![0].content)
+ ).toMatchObject(expected)
+ const cold = new TaskExecutor(task, { ...deps, conversationManager: coldManager })
+ await cold.rehydrateWaitingApproval(sessionKey, coldConversation.pending_approval!)
+ await cold.resumeAfterApproval(false)
+ expect(onFail).not.toHaveBeenCalled()
+ expect(cold.executorState).toBe('waiting_approval')
+ expect(cold.pendingApproval?.tool_call_id).toBe('process-retained')
+ expect(cold.pendingApproval?.authorization_scope).toBe('exact_invocation')
+ expect(requests[1].find(message => message.tool_call_id === firstShell.id)?.content).toContain(
+ 'batch-approved'
+ )
+ expect(
+ requests[1].flatMap(message => message.contentParts ?? []).some(part => part.type === 'image')
+ ).toBe(false)
+ expect(contentRequests).toBe(1)
+ expect(releaseOwner).not.toHaveBeenCalled()
+
+ await cold.resumeAfterApproval(false)
+ expect(onFail).not.toHaveBeenCalled()
+ expect(cold.executorState).toBe('completed')
+ expect(onComplete).toHaveBeenCalledExactlyOnceWith(task)
+ expect(onApprovalNeeded).toHaveBeenCalledTimes(2)
+ const output = requests[2].find(message => message.tool_call_id === 'process-retained')!.content
+ // Shell output keeps the production safety envelope around the bounded proof.
+ const proof = /\{"bytes":\d+,"sha256":"[0-9a-f]{64}"\}/.exec(output)?.[0]
+ expect(proof).toBeDefined()
+ expect(JSON.parse(proof!)).toEqual({ bytes: bytes.byteLength, sha256: digest })
+ expect(contentRequests).toBe(1)
+ expect(releaseOwner).toHaveBeenCalledExactlyOnceWith(task.id, task.sourceMessage!.sender)
+ expect(JSON.stringify(requests)).not.toContain(bytes.toString('base64'))
+})
diff --git a/mcp-host/src/agent/stateMachine.ts b/mcp-host/src/agent/stateMachine.ts
index e008fb806..f3d567ebf 100644
--- a/mcp-host/src/agent/stateMachine.ts
+++ b/mcp-host/src/agent/stateMachine.ts
@@ -53,6 +53,7 @@ import { SessionProcessor, serializeSessionKey } from '../session'
import { parseSessionKey } from '../session/types'
import { ApprovalPromptHistoryClient } from '../usage/approvalPromptHistoryClient.js'
import { GovernedRunReporter, UsageReporter } from '../usage/usageReporter.js'
+import { resolveCallerRootBinding } from '../workspace/callerRootBinding'
import type { ScopedWorkspaceProvider } from '../workspace/scopedWorkspace'
import { CronScheduler } from './cronScheduler'
import { TaskExecutor, resolveTaskSessionKey } from './taskExecutor'
@@ -1514,14 +1515,28 @@ export class AgentStateMachine extends EventEmitter {
): TaskExecutor {
if (!this.llmProvider) throw new Error('LLM provider not initialized')
+ const gfsCallerRoot = this.gfsDownloadStore
+ ? resolveCallerRootBinding(this.gfsWorkspaceProvider, task.sourceMessage)
+ : {}
+ if (gfsCallerRoot.failureCode) {
+ logger.warn(
+ {
+ component: 'Agent',
+ event: 'gfs_caller_root_unavailable',
+ code: gfsCallerRoot.failureCode,
+ taskId: task.id,
+ },
+ 'Managed GFS caller root unavailable; managed file and shell tools fail closed'
+ )
+ }
+
return new TaskExecutor(task, {
conversationManager: this.conversationManager,
llmProvider: effective?.provider ?? this.llmProvider,
mcpManager: this.mcpManager,
workspaceService: this.workspaceProvider?.forSource(task.sourceMessage),
gfsDownloadStore: this.gfsDownloadStore,
- gfsCallerWorkspacePath: this.gfsWorkspaceProvider?.forSource(task.sourceMessage)
- ?.userRootPath,
+ gfsCallerWorkspacePath: gfsCallerRoot.root,
config: this.config,
modelName: effective?.model ?? this.modelName,
contextWindowTokens: effective?.contextWindowTokens,
diff --git a/mcp-host/src/core/tools/nativeToolRegistry.ts b/mcp-host/src/core/tools/nativeToolRegistry.ts
index b91d689d6..78cbf8c4e 100644
--- a/mcp-host/src/core/tools/nativeToolRegistry.ts
+++ b/mcp-host/src/core/tools/nativeToolRegistry.ts
@@ -201,16 +201,17 @@ export class NativeToolRegistry implements ToolRegistry {
retentionOwnerId?: string
}
) {
- // file_read/file_write are scoped to the per-user root when a ScopedWorkspace
- // is wired (F1c) — they operate on a raw path string, not the Workspace
- // interface, so we read the per-user root off it explicitly. Falls back to
- // the shared root when there is no user context (e.g. the tool-name listing
- // registry in main.ts). ShellTool uses the caller root when governed local
- // processing is enabled. Its cwd/HOME boundary does not contain absolute-path
- // access — shell isolation remains a documented residual.
+ // A Host-owned GFS store establishes a trusted caller binding even when
+ // memory is disabled. In that mode file tools never fall back to the shared
+ // Host root; if the caller root cannot be verified they are omitted.
+ // Without that Host store, preserve the legacy memory/shared-root behavior.
const fileToolsRoot =
- workspace instanceof ScopedWorkspace ? workspace.userRootPath : config.workspacePath
- this.register(new FileReadTool(fileToolsRoot))
+ gfsDownload !== undefined
+ ? gfsDownload.callerWorkspacePath
+ : workspace instanceof ScopedWorkspace
+ ? workspace.userRootPath
+ : config.workspacePath
+ if (fileToolsRoot !== undefined) this.register(new FileReadTool(fileToolsRoot))
// NOTE (residual): FileWriteTool writes via raw fs and bypasses
// WorkspaceService.write → scanWriteContent. So a `file_write` to
// `daily/*` / `MEMORY.md` is NOT injection-scanned. It is scoped to the
@@ -219,7 +220,7 @@ export class NativeToolRegistry implements ToolRegistry {
// radius is self-injection of the user's own daily snapshot (low). Closing
// it (route memory/daily-class file_write through WorkspaceService) is future
// hardening, independent of F5.
- this.register(new FileWriteTool(fileToolsRoot))
+ if (fileToolsRoot !== undefined) this.register(new FileWriteTool(fileToolsRoot))
this.register(
new ShellTool(
gfsDownload ? gfsDownload.callerWorkspacePath : config.workspacePath,
diff --git a/mcp-host/src/db/migrations/__tests__/008-active-trace-context.test.ts b/mcp-host/src/db/migrations/__tests__/008-active-trace-context.test.ts
index 22ce1a048..55e1751c0 100644
--- a/mcp-host/src/db/migrations/__tests__/008-active-trace-context.test.ts
+++ b/mcp-host/src/db/migrations/__tests__/008-active-trace-context.test.ts
@@ -77,9 +77,13 @@ describe('migration 008 — active trace context', () => {
'013-pending-approval-connect',
'014-pending-approval-task-budget',
'015-session-model-selection-revision',
+ '016-pending-approval-authorization-scope',
],
pending: [],
})
+ expect(
+ db.prepare('SELECT name FROM migrations_meta WHERE name = ?').get('007-active-trace-context')
+ ).toEqual({ name: '007-active-trace-context' })
const sessionColumns = db.prepare('PRAGMA table_info(sessions)').all() as Array<{
name: string
}>
diff --git a/mcp-host/src/db/migrations/__tests__/015-session-model-selection-revision.test.ts b/mcp-host/src/db/migrations/__tests__/015-session-model-selection-revision.test.ts
index d4ba28335..e21f697ba 100644
--- a/mcp-host/src/db/migrations/__tests__/015-session-model-selection-revision.test.ts
+++ b/mcp-host/src/db/migrations/__tests__/015-session-model-selection-revision.test.ts
@@ -22,8 +22,16 @@ function preMigrationDb(): Database.Database {
}
describe('migration 015 — sessions.model_selection_revision', () => {
- it('appends last to the ordered migration list', () => {
- expect(migrations[migrations.length - 1]?.name).toBe(migration.name)
+ it('preserves the ordered 014, 015, 016 append sequence', () => {
+ const names = migrations.map(item => item.name)
+ const index = names.indexOf(migration.name)
+ expect(index).toBeGreaterThan(0)
+ expect(names.filter(name => name === migration.name)).toHaveLength(1)
+ expect(names.slice(index - 1, index + 2)).toEqual([
+ '014-pending-approval-task-budget',
+ migration.name,
+ '016-pending-approval-authorization-scope',
+ ])
})
it('adds a NOT NULL revision that reads 0 for every pre-existing row', () => {
diff --git a/mcp-host/src/db/worker/__tests__/dispatcher.test.ts b/mcp-host/src/db/worker/__tests__/dispatcher.test.ts
index d5f60f479..4939a2644 100644
--- a/mcp-host/src/db/worker/__tests__/dispatcher.test.ts
+++ b/mcp-host/src/db/worker/__tests__/dispatcher.test.ts
@@ -1,10 +1,17 @@
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
import Database from 'better-sqlite3'
+import { reconstructPendingApproval } from '../../../core/conversation/persistence/reconstruct'
import { runMigrations } from '../../migrate'
import { applyPragmas } from '../../pragmas'
import { prepareStatements } from '../../statements'
import { createDispatcher, dispatch } from '../dispatcher'
-import type { MessageRow, PersistedSession, ReapedSession, SessionRow } from '../protocol'
+import type {
+ MessageRow,
+ PendingApprovalRow,
+ PersistedSession,
+ ReapedSession,
+ SessionRow,
+} from '../protocol'
describe('dbWorker dispatcher', () => {
let db: Database.Database
@@ -644,6 +651,56 @@ describe('dbWorker dispatcher', () => {
expect(rows[0].session_key).toBe('u-3:rpc:agent:default')
})
+ it.each([undefined, null, 'exact_invocation', 'turn_tools'] as const)(
+ 'round-trips an optional authorization scope through the real dispatcher: %s',
+ async scope => {
+ const deps = createDispatcher(db)
+ const session = {
+ ...makeSession('conv-scope', 'conv-scope:rpc:agent:scope'),
+ state: 'awaiting_approval',
+ active_task_id: '11111111-1111-4111-8111-111111111111',
+ }
+ await dispatch({ kind: 'insert_session', payload: session }, deps)
+ const row: PendingApprovalRow = {
+ request_id: 'req-scope',
+ session_id: session.id,
+ task_id: session.active_task_id,
+ tool_name: 'shell_exec',
+ tool_call_id: 'tc-scope',
+ parameters: '{"command":"printf scoped"}',
+ description: 'Scope round trip',
+ context_snapshot: '[]',
+ completed_results: null,
+ intent_summary: null,
+ source_message: null,
+ registered_at: 0,
+ expires_at: 9999999999,
+ trace_context: null,
+ reason: null,
+ mcp_server_name: null,
+ task_budget: JSON.stringify({
+ elapsedActiveMs: 0,
+ iterationsUsed: 0,
+ durationMs: 30_000,
+ maxIterations: 10,
+ }),
+ ...(scope === undefined ? {} : { authorization_scope: scope }),
+ }
+ await dispatch({ kind: 'insert_pending_approval', payload: row }, deps)
+ const loaded = (await dispatch(
+ { kind: 'load_active_session', sessionKey: session.session_key },
+ deps
+ )) as PersistedSession
+
+ expect(loaded.pending_approval?.authorization_scope).toBe(scope ?? null)
+ expect(reconstructPendingApproval(loaded.pending_approval!).authorization_scope).toBe(
+ scope ?? undefined
+ )
+ expect(loaded.pending_approval?.parameters).toBe(row.parameters)
+ expect(loaded.pending_approval?.tool_call_id).toBe(row.tool_call_id)
+ }
+ )
+
it('projects the connect_required discriminator on the cold DB paths (page + summary)', async () => {
const deps = createDispatcher(db)
const session = {
diff --git a/mcp-host/src/db/worker/dispatcher.ts b/mcp-host/src/db/worker/dispatcher.ts
index cdca15711..5c54620b4 100644
--- a/mcp-host/src/db/worker/dispatcher.ts
+++ b/mcp-host/src/db/worker/dispatcher.ts
@@ -653,6 +653,9 @@ export async function dispatch(op: WorkerOp, deps: DispatcherDeps): Promise<unkn
...row,
source_message: sourceMessage,
task_budget: row.task_budget ?? null,
+ // Legacy protocol payloads may omit this field. SQL NULL keeps
+ // that unknown consent scope exact when the approval rehydrates.
+ authorization_scope: row.authorization_scope ?? null,
})
if (op.markAwaitingApproval)
db.prepare('UPDATE sessions SET state = ? WHERE id = ?').run(
diff --git a/mcp-host/src/db/worker/protocol.ts b/mcp-host/src/db/worker/protocol.ts
index 81cb8d2e3..bd729e9fe 100644
--- a/mcp-host/src/db/worker/protocol.ts
+++ b/mcp-host/src/db/worker/protocol.ts
@@ -89,7 +89,7 @@ export interface MessageRow {
export interface PendingApprovalRow {
/** Nullable for approvals created before migration 014. */
task_budget?: string | null
- /** NULL for legacy approvals; `turn_tools` or `exact_invocation` thereafter. */
+ /** Omitted write fields persist as legacy NULL; known scopes are `turn_tools` or `exact_invocation`. */
authorization_scope?: string | null
request_id: string
session_id: string
diff --git a/mcp-host/src/internalTools/gfsDownloadDiagnostics.test.ts b/mcp-host/src/internalTools/gfsDownloadDiagnostics.test.ts
index fcdec1ebb..82afd822d 100644
--- a/mcp-host/src/internalTools/gfsDownloadDiagnostics.test.ts
+++ b/mcp-host/src/internalTools/gfsDownloadDiagnostics.test.ts
@@ -1,4 +1,5 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { randomUUID } from 'node:crypto'
import { logger } from '../logger'
import { VisualInputError } from '../visualInput/policy'
import { type GfscReadClient, buildGfsReadTools } from './gfs'
@@ -13,6 +14,7 @@ const privateDetail =
'unit-only-server-detail /unit-only/storage.csv https://unit-only.invalid/body'
function harness() {
+ const retentionOwnerId = randomUUID()
const download = vi.fn<NonNullable<GfscReadClient['download']>>()
const client = {
accessible: vi.fn(),
@@ -28,8 +30,9 @@ function harness() {
downloadStore: new GfsDownloadStore('/unit-only-host-workspace'),
callerIdentity: 'unit-only-caller',
callerWorkspacePath: '/unit-only-host-workspace/caller',
+ retentionOwnerId,
}).find(item => item.name === 'clerum__gfs_download')!
- return { tool, download }
+ return { tool, download, retentionOwnerId }
}
beforeEach(() => {
@@ -42,7 +45,7 @@ afterEach(() => {
describe('GFS download failure diagnostics', () => {
it('logs only the normalized public target and HTTP prefix, preserving the redacted failure', async () => {
- const { tool, download } = harness()
+ const { tool, download, retentionOwnerId } = harness()
const error = Object.assign(new Error(`gfsc 403: ${privateDetail}`), {
name: 'unit-only-private-error-name',
code: 'unit-only-private-error-code',
@@ -63,6 +66,13 @@ describe('GFS download failure diagnostics', () => {
)
expect(result).toEqual({ success: false, error: 'GFS read failed (gfsc 403: forbidden)' })
+ expect(download).toHaveBeenCalledWith(
+ expect.objectContaining({
+ drive: 'main_1',
+ resourceId: 'AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA',
+ }),
+ expect.objectContaining({ retentionOwnerId, callerIdentity: 'unit-only-caller' })
+ )
expect(vi.mocked(logger.warn).mock.calls).toEqual([
[
{
diff --git a/mcp-host/src/internalTools/gfsDownloadStore.ts b/mcp-host/src/internalTools/gfsDownloadStore.ts
index 420edf1b3..cbc22f5b5 100644
--- a/mcp-host/src/internalTools/gfsDownloadStore.ts
+++ b/mcp-host/src/internalTools/gfsDownloadStore.ts
@@ -467,6 +467,7 @@ export class GfsDownloadStore {
}
if (input.retentionOwnerId !== undefined)
this.assertReceiptOwner(input.retentionOwnerId, input.callerIdentity)
+ await this.assertPhysicalCapacity(input.sizeBytes)
await this.reclaimForAdmission(input.callerIdentity, input.sizeBytes)
const denial = this.quotaDenial(input.callerIdentity, input.sizeBytes)
if (denial) {
@@ -475,25 +476,24 @@ export class GfsDownloadStore {
denial.scope === 'host' ? 'host_quota_exceeded' : 'caller_quota_exceeded'
)
}
- const space = await fs.statfs(this.storeRoot, { bigint: true })
- if (space.bavail * space.bsize < BigInt(input.sizeBytes + 16 * 1024 * 1024)) {
- recordGfsDownloadQuota('host', 'free_space')
- throw new GfsDownloadStoreError('host_quota_exceeded')
- }
+ await this.assertPhysicalCapacity(input.sizeBytes)
const previousOwner =
input.retentionOwnerId === undefined
? undefined
: this.ledger.retentionOwners?.[input.retentionOwnerId]
+ const previousLeases = this.ledger.processingLeases
try {
if (input.retentionOwnerId !== undefined)
this.retainReceiptRecord(record, input.retentionOwnerId)
this.ledger.records[id] = record
+ this.protectFutureRecord(record)
await this.persist()
} catch (error) {
// No filesystem transfer or worker has been exposed. In-memory
// admission rolls back; an uncertain durable write stays fail-closed.
delete this.ledger.records[id]
+ this.ledger.processingLeases = previousLeases
if (input.retentionOwnerId !== undefined) {
if (previousOwner) this.ledger.retentionOwners![input.retentionOwnerId] = previousOwner
else delete this.ledger.retentionOwners![input.retentionOwnerId]
@@ -529,9 +529,17 @@ export class GfsDownloadStore {
} catch (error) {
try {
await this.serialize(async () => {
+ // Other already-running commands can observe this new path too.
+ // Producer settlement releases its active slot, never their protection.
+ record.state = 'cleanup_failed'
+ // The producer's new pin has never exposed a transfer or receipt.
+ // With no executor protection, proven absence can roll it back too.
+ if (this.hasProcessingLease(id)) {
+ await this.persist()
+ return
+ }
// Delete/prove absence before releasing the durable reservation.
if (!(await this.removeRecordDirectory(record))) {
- record.state = 'cleanup_failed'
await this.persist()
throw new GfsDownloadStoreError('storage_write_failed')
}
@@ -700,27 +708,36 @@ export class GfsDownloadStore {
}
async fail(id: string, callerIdentity: string): Promise<void> {
- this.assertInitialized()
const record = this.record(id)
if (record.callerIdentity !== callerIdentity) throw new GfsDownloadStoreError('caller_mismatch')
- if (!this.activeIds.has(id) || this.hasProcessingLease(id))
+ if (!this.activeIds.has(id) && record.state !== 'cleanup_failed')
throw new GfsDownloadStoreError('download_busy')
try {
+ this.assertInitialized()
await this.serialize(async () => {
+ this.assertInitialized()
if (record.callerIdentity !== callerIdentity)
throw new GfsDownloadStoreError('caller_mismatch')
- // Publication and lease admission may have settled while this operation
- // waited. Only this writer's still-active failed transfer can be removed.
- if (!this.activeIds.has(id) || record.state === 'completed' || this.hasProcessingLease(id))
+ // Publication or another admission may have settled while this waited.
+ if (
+ (!this.activeIds.has(id) && record.state !== 'cleanup_failed') ||
+ record.state === 'completed'
+ )
throw new GfsDownloadStoreError('download_busy')
+ record.state = 'cleanup_failed'
+ if (this.hasProcessingLease(id) || this.hasReceiptOwner(id)) {
+ await this.persist()
+ return
+ }
if (!(await this.removeRecordDirectory(record))) {
- record.state = 'cleanup_failed'
await this.persist()
throw new GfsDownloadStoreError('storage_write_failed')
}
await this.releaseRecordCharge(record)
})
} finally {
+ // The caller invokes failure only after its stream/descriptor is settled.
+ // Uncertain bytes stay charged; an older executor has its separate lease.
this.releaseActive(record)
}
}
@@ -901,7 +918,7 @@ export class GfsDownloadStore {
const lease: GfsProcessingLeaseRecord = {
leaseId,
callerIdentity,
- recordIds: candidates.map(record => record.id),
+ recordIds: retained.map(record => record.id),
acquiredAt: new Date(admittedAt).toISOString(),
expiresAt,
writerSessionId: this.writerSessionId,
@@ -967,6 +984,7 @@ export class GfsDownloadStore {
throw error
}
this.liveProcessingLeases.delete(lease.leaseId)
+ await this.cleanupSettledFailedTransfers(callerIdentity)
})
}
@@ -985,6 +1003,7 @@ export class GfsDownloadStore {
this.ledger.retentionOwners![ownerId] = owner
throw error
}
+ await this.cleanupSettledFailedTransfers(callerIdentity)
})
}
@@ -1159,6 +1178,61 @@ export class GfsDownloadStore {
}
}
+ private protectFutureRecord(record: GfsDownloadRecord): void {
+ const next = { ...this.ledger.processingLeases }
+ for (const [leaseId, lease] of Object.entries(next)) {
+ if (
+ lease.callerIdentity !== record.callerIdentity ||
+ lease.writerSessionId !== this.writerSessionId ||
+ !this.liveProcessingLeases.has(leaseId)
+ )
+ continue
+ next[leaseId] = { ...lease, recordIds: [...new Set([...lease.recordIds, record.id])] }
+ }
+ // Committed atomically with the reservation, before its path is exposed.
+ this.ledger.processingLeases = next
+ }
+
+ private async cleanupSettledFailedTransfers(callerIdentity: string): Promise<void> {
+ for (const record of Object.values(this.ledger.records)) {
+ if (
+ record.callerIdentity !== callerIdentity ||
+ record.state !== 'cleanup_failed' ||
+ this.activeIds.has(record.id) ||
+ this.hasProcessingLease(record.id) ||
+ this.hasReceiptOwner(record.id)
+ )
+ continue
+ if (await this.removeRecordDirectory(record)) await this.releaseRecordCharge(record)
+ }
+ }
+
+ private async assertPhysicalCapacity(sizeBytes: number): Promise<void> {
+ const space = await fs.statfs(this.storeRoot, { bigint: true })
+ if (space.bsize <= 0n || space.bavail < 0n) {
+ recordGfsDownloadQuota('host', 'free_space')
+ throw new GfsDownloadStoreError('host_quota_exceeded')
+ }
+ const reserve = (bytes: number): bigint => {
+ const amount = BigInt(bytes)
+ return ((amount + space.bsize - 1n) / space.bsize) * space.bsize
+ }
+ let required = reserve(sizeBytes) + 16n * 1024n * 1024n
+ for (const id of this.activeIds) {
+ const record = this.ledger.records[id]
+ // Use the full outstanding reservation rather than optimistically
+ // crediting sparse, shared or concurrently written physical allocation.
+ if (record && record.state !== 'completed') required += reserve(record.sizeBytes)
+ }
+ // Allocated/apparent cache bytes are not proven freeable bytes on shared,
+ // reflink or snapshot filesystems. Require currently verified free capacity
+ // before any destructive quota reclaim, then measure it again afterward.
+ if (space.bavail * space.bsize < required) {
+ recordGfsDownloadQuota('host', 'free_space')
+ throw new GfsDownloadStoreError('host_quota_exceeded')
+ }
+ }
+
private quotaDenial(
callerIdentity: string,
sizeBytes: number,
@@ -1216,6 +1290,7 @@ export class GfsDownloadStore {
remaining.delete(next.id)
plan.push(next)
}
+ await this.assertPhysicalCapacity(sizeBytes)
for (const record of plan) {
if (!(await this.removeRecordDirectory(record))) continue
await this.releaseRecordCharge(record)
diff --git a/mcp-host/src/internalTools/gfsDownloadStoreFutureLeaseCapacity.test.ts b/mcp-host/src/internalTools/gfsDownloadStoreFutureLeaseCapacity.test.ts
new file mode 100644
index 000000000..6f54720c5
--- /dev/null
+++ b/mcp-host/src/internalTools/gfsDownloadStoreFutureLeaseCapacity.test.ts
@@ -0,0 +1,452 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { type ChildProcess, spawn } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import * as fs from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import * as path from 'node:path'
+import type { GfsDownloadStore } from './gfsDownloadStore'
+
+const { statfsBoundary } = vi.hoisted(() => ({ statfsBoundary: vi.fn() }))
+// Capacity is a deterministic filesystem boundary. Directory/file effects and
+// their physical allocation remain real in each isolated temporary store.
+vi.mock('node:fs/promises', async original => ({
+ ...(await original<typeof fs>()),
+ statfs: statfsBoundary,
+}))
+const MARGIN = 16 * 1024 * 1024
+const source = {
+ kind: 'gfs' as const,
+ drive: 'main',
+ resourceId: 'a'.repeat(32),
+ gfsUri: `gfs://main/${'a'.repeat(32)}`,
+ name: 'input.csv',
+ version: 7,
+}
+let nativeFs: typeof fs
+let roots: string[]
+let stores: GfsDownloadStore[]
+let children: ChildProcess[]
+beforeEach(async () => {
+ nativeFs = await vi.importActual<typeof fs>('node:fs/promises')
+ statfsBoundary.mockImplementation(nativeFs.statfs)
+ roots = []
+ stores = []
+ children = []
+})
+afterEach(async () => {
+ vi.restoreAllMocks()
+ statfsBoundary.mockImplementation(nativeFs.statfs)
+ for (const child of children)
+ if (child.exitCode === null && child.signalCode === null)
+ await new Promise<void>(resolve => {
+ child.once('exit', () => resolve())
+ child.kill('SIGKILL')
+ })
+ for (const store of stores)
+ await store.close(0).catch(async () => {
+ await (
+ store as unknown as { writerLease?: { release(): Promise<void> } }
+ ).writerLease?.release()
+ })
+ for (const root of roots) await nativeFs.rm(root, { recursive: true, force: true })
+})
+async function setup(extra: Record<string, string> = {}) {
+ const keys = {
+ MCP_HOST_GFS_MAX_FILE_BYTES: '20',
+ MCP_HOST_GFS_DOWNLOAD_STORAGE_BYTES: '100',
+ MCP_HOST_GFS_CALLER_DOWNLOAD_STORAGE_BYTES: '50',
+ ...extra,
+ }
+ const previous = new Map(Object.keys(keys).map(key => [key, process.env[key]]))
+ Object.assign(process.env, keys)
+ vi.resetModules()
+ const { GfsDownloadStore: Store } = await import('./gfsDownloadStore')
+ for (const [key, value] of previous) {
+ if (value === undefined) delete process.env[key]
+ else process.env[key] = value
+ }
+ const root = await nativeFs.mkdtemp(path.join(tmpdir(), 'gfs-future-capacity-'))
+ roots.push(root)
+ const store = new Store(root)
+ stores.push(store)
+ await store.initialize()
+ return { root, store }
+}
+async function caller(root: string, identity: string) {
+ const directory = path.join(root, 'users', identity)
+ await nativeFs.mkdir(directory, { recursive: true, mode: 0o700 })
+ return directory
+}
+async function copy(
+ store: GfsDownloadStore,
+ callerRoot: string,
+ identity: string,
+ bytes = 7,
+ owner?: string
+) {
+ const transfer = await store.createTransfer({
+ callerIdentity: identity,
+ callerWorkspacePath: callerRoot,
+ source,
+ sizeBytes: bytes,
+ expiresAt: new Date(Date.now() + 60_000).toISOString(),
+ retentionOwnerId: owner,
+ })
+ const body = Buffer.alloc(bytes, 65)
+ await nativeFs.writeFile(path.join(callerRoot, transfer.partialPath), body)
+ return store.publish(transfer.id, identity, createHash('sha256').update(body).digest('hex'))
+}
+async function capacity(root: string, bytes: number) {
+ const observed = await nativeFs.statfs(root, { bigint: true })
+ statfsBoundary.mockResolvedValue({
+ ...observed,
+ bsize: 4096n,
+ bavail: BigInt(Math.floor(bytes / 4096)),
+ })
+}
+async function ledger(root: string) {
+ return JSON.parse(
+ await nativeFs.readFile(path.join(root, '.gfs-download-store', 'ledger-v1.json'), 'utf8')
+ )
+}
+async function executor(callerRoot: string) {
+ const child = spawn(
+ process.execPath,
+ [
+ '-e',
+ `const fs=require('node:fs');process.send({ready:true});process.on('message',m=>{try{process.send({body:fs.readFileSync(m.path,'utf8')})}catch(e){process.send({error:e.code})}})`,
+ ],
+ { cwd: callerRoot, stdio: ['ignore', 'ignore', 'ignore', 'ipc'] }
+ )
+ children.push(child)
+ await new Promise(resolve => child.once('message', resolve))
+ return child
+}
+async function readFromExecutor(child: ChildProcess, filename: string) {
+ return new Promise<any>(resolve => {
+ child.once('message', resolve)
+ child.send({ path: filename })
+ })
+}
+async function settleExecutor(child: ChildProcess) {
+ await new Promise<void>(resolve => {
+ child.once('exit', () => resolve())
+ child.kill('SIGTERM')
+ })
+}
+
+describe('future execution protection and whole admission capacity', () => {
+ it('protects a future published copy through an already-running empty lease and owner release', async () => {
+ const { root, store } = await setup({ MCP_HOST_GFS_CALLER_DOWNLOAD_MAX_FILES: '1' })
+ const callerRoot = await caller(root, 'caller-a')
+ const provider = store.processingLeaseProvider('caller-a')
+ const lease = await provider.acquireProcessingLease({ durationMs: 500 })
+ const child = await executor(callerRoot)
+ const receipt = await copy(store, callerRoot, 'caller-a', 7, 'future-owner')
+ await store.releaseReceiptOwner('future-owner', 'caller-a')
+ await expect(
+ store.createTransfer({
+ callerIdentity: 'caller-a',
+ callerWorkspacePath: callerRoot,
+ source,
+ sizeBytes: 7,
+ expiresAt: new Date(Date.now() + 60_000).toISOString(),
+ })
+ ).rejects.toMatchObject({ code: 'caller_quota_exceeded' })
+ expect((await ledger(root)).processingLeases[lease.leaseId].recordIds).toContain(receipt.id)
+ expect(await readFromExecutor(child, path.join(callerRoot, receipt.path))).toEqual({
+ body: 'AAAAAAA',
+ })
+ await store.cleanupExpired(
+ Math.max(Date.parse(lease.expiresAt), Date.parse(receipt.expiresAt)) + 1
+ )
+ expect(store.debugUsage().files).toBe(1)
+ await expect(store.close(0)).rejects.toMatchObject({ code: 'download_busy' })
+ await settleExecutor(child)
+ await provider.releaseProcessingLease(lease)
+ })
+
+ it('settles a protected failed producer without freeing its bytes or occupying the active slot', async () => {
+ const { root, store } = await setup()
+ const callerRoot = await caller(root, 'caller-a')
+ const provider = store.processingLeaseProvider('caller-a')
+ const lease = await provider.acquireProcessingLease()
+ const transfer = await store.createTransfer({
+ callerIdentity: 'caller-a',
+ callerWorkspacePath: callerRoot,
+ source,
+ sizeBytes: 7,
+ expiresAt: new Date(Date.now() + 60_000).toISOString(),
+ retentionOwnerId: 'failed-owner',
+ })
+ await nativeFs.writeFile(path.join(callerRoot, transfer.partialPath), 'partial')
+ await store.fail(transfer.id, 'caller-a')
+ expect(store.debugRecord(transfer.id)).toMatchObject({ state: 'cleanup_failed', sizeBytes: 7 })
+ expect(store.debugUsage().files).toBe(1)
+ await store.releaseReceiptOwner('failed-owner', 'caller-a')
+ expect(await nativeFs.readFile(path.join(callerRoot, transfer.partialPath), 'utf8')).toBe(
+ 'partial'
+ )
+ const next = await store.createTransfer({
+ callerIdentity: 'caller-a',
+ callerWorkspacePath: callerRoot,
+ source,
+ sizeBytes: 7,
+ expiresAt: new Date(Date.now() + 60_000).toISOString(),
+ })
+ await store.fail(next.id, 'caller-a')
+ await provider.releaseProcessingLease(lease)
+ expect(store.debugUsage().files).toBe(0)
+ await store.close(0)
+ })
+
+ it('covers an already-transferring path when a new execution lease is admitted', async () => {
+ const { root, store } = await setup()
+ const callerRoot = await caller(root, 'caller-a')
+ const transfer = await store.createTransfer({
+ callerIdentity: 'caller-a',
+ callerWorkspacePath: callerRoot,
+ source,
+ sizeBytes: 7,
+ expiresAt: new Date(Date.now() + 60_000).toISOString(),
+ })
+ await nativeFs.writeFile(path.join(callerRoot, transfer.partialPath), 'partial')
+ const provider = store.processingLeaseProvider('caller-a')
+ const lease = await provider.acquireProcessingLease()
+ expect((await ledger(root)).processingLeases[lease.leaseId].recordIds).toContain(transfer.id)
+ await store.fail(transfer.id, 'caller-a')
+ expect(await nativeFs.readFile(path.join(callerRoot, transfer.partialPath), 'utf8')).toBe(
+ 'partial'
+ )
+ await provider.releaseProcessingLease(lease)
+ expect(store.debugUsage().files).toBe(0)
+ })
+
+ it('rolls back future lease references when reservation persistence fails before exposure', async () => {
+ const { root, store } = await setup()
+ const callerRoot = await caller(root, 'caller-a')
+ const provider = store.processingLeaseProvider('caller-a')
+ const lease = await provider.acquireProcessingLease()
+ const before = await ledger(root)
+ // Inject a failure before the real journal producer starts; no directory,
+ // record ID or consumer path has been physically exposed.
+ vi.spyOn(store as unknown as { persist(): Promise<void> }, 'persist').mockRejectedValueOnce(
+ new Error('reservation unavailable')
+ )
+ await expect(
+ store.createTransfer({
+ callerIdentity: 'caller-a',
+ callerWorkspacePath: callerRoot,
+ source,
+ sizeBytes: 7,
+ expiresAt: new Date(Date.now() + 60_000).toISOString(),
+ retentionOwnerId: 'unpublished-owner',
+ })
+ ).rejects.toThrow('reservation unavailable')
+ expect(store.debugUsage().files).toBe(0)
+ expect(await ledger(root)).toEqual(before)
+ await expect(nativeFs.lstat(path.join(callerRoot, '.gfs-downloads'))).rejects.toMatchObject({
+ code: 'ENOENT',
+ })
+ const privateStore = store as unknown as {
+ ledger: { processingLeases: Record<string, { recordIds: string[] }> }
+ }
+ expect(privateStore.ledger.processingLeases[lease.leaseId].recordIds).toEqual([])
+ await provider.releaseProcessingLease(lease)
+ })
+
+ it('settles cancelled publication while a preexisting executor retains its partial protection', async () => {
+ const { root, store } = await setup()
+ const callerRoot = await caller(root, 'caller-a')
+ const provider = store.processingLeaseProvider('caller-a')
+ const lease = await provider.acquireProcessingLease()
+ const transfer = await store.createTransfer({
+ callerIdentity: 'caller-a',
+ callerWorkspacePath: callerRoot,
+ source,
+ sizeBytes: 7,
+ expiresAt: new Date(Date.now() + 60_000).toISOString(),
+ })
+ await nativeFs.writeFile(path.join(callerRoot, transfer.partialPath), 'partial')
+ const controller = new AbortController()
+ controller.abort()
+ await expect(
+ store.publish(transfer.id, 'caller-a', createHash('sha256').update('partial').digest('hex'), {
+ signal: controller.signal,
+ })
+ ).rejects.toMatchObject({ code: 'publication_cancelled' })
+ await store.fail(transfer.id, 'caller-a')
+ expect(store.debugRecord(transfer.id)).toMatchObject({ state: 'cleanup_failed', sizeBytes: 7 })
+ expect((await ledger(root)).processingLeases[lease.leaseId].recordIds).toContain(transfer.id)
+ await expect(store.close(0)).rejects.toMatchObject({ code: 'download_busy' })
+ await provider.releaseProcessingLease(lease)
+ expect(store.debugUsage().files).toBe(0)
+ await store.close(0)
+ })
+
+ it('rejects impossible physical margin before evicting another caller at a logical quota boundary', async () => {
+ const { root, store } = await setup()
+ const otherRoot = await caller(root, 'caller-b')
+ const receipts = []
+ for (let index = 0; index < 5; index++)
+ receipts.push(await copy(store, otherRoot, 'caller-b', 10))
+ const requestRoot = await caller(root, 'caller-a')
+ // Add durable, protected charges to make aggregate 100 while requester has room.
+ for (const identity of ['caller-c', 'caller-d', 'caller-e', 'caller-f', 'caller-g'])
+ await copy(store, await caller(root, identity), identity, 10, `${identity}-owner`)
+ await capacity(root, 0)
+ await expect(
+ store.createTransfer({
+ callerIdentity: 'caller-a',
+ callerWorkspacePath: requestRoot,
+ source,
+ sizeBytes: 20,
+ expiresAt: new Date(Date.now() + 60_000).toISOString(),
+ })
+ ).rejects.toMatchObject({ code: 'host_quota_exceeded' })
+ expect(store.debugUsage()).toMatchObject({ bytes: 100, files: 10 })
+ for (const receipt of receipts) expect(store.debugRecord(receipt.id)).toBeDefined()
+ for (const identity of ['caller-c', 'caller-d', 'caller-e', 'caller-f', 'caller-g'])
+ await store.releaseReceiptOwner(`${identity}-owner`, identity)
+ })
+
+ it('keeps all default-cap small copies when current physical capacity is zero', async () => {
+ const { root, store } = await setup({
+ MCP_HOST_GFS_MAX_FILE_BYTES: '1024',
+ MCP_HOST_GFS_DOWNLOAD_STORAGE_BYTES: String(1024 * 1024),
+ MCP_HOST_GFS_CALLER_DOWNLOAD_STORAGE_BYTES: String(128 * 1024),
+ })
+ const receipts = []
+ for (let index = 0; index < 8; index++) {
+ const identity = `caller-${index}`
+ const directory = await caller(root, identity)
+ for (let file = 0; file < 8; file++) receipts.push(await copy(store, directory, identity, 1))
+ }
+ await capacity(root, 0)
+ await expect(
+ store.createTransfer({
+ callerIdentity: 'caller-new',
+ callerWorkspacePath: await caller(root, 'caller-new'),
+ source,
+ sizeBytes: 1,
+ expiresAt: new Date(Date.now() + 60_000).toISOString(),
+ })
+ ).rejects.toMatchObject({ code: 'host_quota_exceeded' })
+ expect(store.debugUsage().files).toBe(64)
+ for (const receipt of receipts) expect(store.debugRecord(receipt.id)).toBeDefined()
+ })
+
+ it('respects pending active reservations before any cache-pressure effect', async () => {
+ const { root, store } = await setup({ MCP_HOST_GFS_CALLER_DOWNLOAD_MAX_FILES: '1' })
+ const cachedRoot = await caller(root, 'caller-a')
+ const receipt = await copy(store, cachedRoot, 'caller-a', 7)
+ const active = await store.createTransfer({
+ callerIdentity: 'caller-b',
+ callerWorkspacePath: await caller(root, 'caller-b'),
+ source,
+ sizeBytes: 7,
+ expiresAt: new Date(Date.now() + 60_000).toISOString(),
+ })
+ await capacity(root, MARGIN + 4096)
+ await expect(
+ store.createTransfer({
+ callerIdentity: 'caller-a',
+ callerWorkspacePath: cachedRoot,
+ source,
+ sizeBytes: 7,
+ expiresAt: new Date(Date.now() + 60_000).toISOString(),
+ })
+ ).rejects.toMatchObject({ code: 'host_quota_exceeded' })
+ expect(store.debugRecord(receipt.id)).toBeDefined()
+ await store.fail(active.id, 'caller-b')
+ })
+
+ it('never credits sparse apparent bytes as available physical capacity', async () => {
+ const bytes = 16 * 1024 * 1024
+ const { root, store } = await setup({
+ MCP_HOST_GFS_MAX_FILE_BYTES: String(bytes),
+ MCP_HOST_GFS_DOWNLOAD_STORAGE_BYTES: String(bytes * 4),
+ MCP_HOST_GFS_CALLER_DOWNLOAD_STORAGE_BYTES: String(bytes * 2),
+ MCP_HOST_GFS_CALLER_DOWNLOAD_MAX_FILES: '1',
+ })
+ const callerRoot = await caller(root, 'caller-a')
+ const transfer = await store.createTransfer({
+ callerIdentity: 'caller-a',
+ callerWorkspacePath: callerRoot,
+ source,
+ sizeBytes: bytes,
+ expiresAt: new Date(Date.now() + 60_000).toISOString(),
+ })
+ const handle = await nativeFs.open(path.join(callerRoot, transfer.partialPath), 'r+')
+ await handle.truncate(bytes)
+ await handle.close()
+ const sparse = await nativeFs.stat(path.join(callerRoot, transfer.partialPath))
+ expect(sparse.blocks * 512).toBeLessThan(sparse.size)
+ const receipt = await store.publish(
+ transfer.id,
+ 'caller-a',
+ createHash('sha256').update(Buffer.alloc(bytes)).digest('hex')
+ )
+ await capacity(root, 0)
+ await expect(
+ store.createTransfer({
+ callerIdentity: 'caller-a',
+ callerWorkspacePath: callerRoot,
+ source,
+ sizeBytes: 7,
+ expiresAt: new Date(Date.now() + 60_000).toISOString(),
+ })
+ ).rejects.toMatchObject({ code: 'host_quota_exceeded' })
+ expect(store.debugRecord(receipt.id)).toBeDefined()
+ expect((await nativeFs.stat(path.join(callerRoot, receipt.path))).size).toBe(bytes)
+ })
+
+ it('refuses admission if real capacity changes after a positively settled victim', async () => {
+ const { root, store } = await setup({ MCP_HOST_GFS_CALLER_DOWNLOAD_MAX_FILES: '1' })
+ const callerRoot = await caller(root, 'caller-a')
+ const receipt = await copy(store, callerRoot, 'caller-a', 7)
+ const directory = path.join(callerRoot, path.dirname(receipt.path))
+ const observed = await nativeFs.statfs(root, { bigint: true })
+ statfsBoundary.mockImplementation(async () => {
+ try {
+ await nativeFs.lstat(directory)
+ return observed
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+ return { ...observed, bavail: 0n }
+ }
+ })
+ await expect(
+ store.createTransfer({
+ callerIdentity: 'caller-a',
+ callerWorkspacePath: callerRoot,
+ source,
+ sizeBytes: 7,
+ expiresAt: new Date(Date.now() + 60_000).toISOString(),
+ })
+ ).rejects.toMatchObject({ code: 'host_quota_exceeded' })
+ expect(store.debugUsage().files).toBe(0)
+ await expect(nativeFs.lstat(directory)).rejects.toMatchObject({ code: 'ENOENT' })
+ })
+
+ it('reclaims logical quota and admits when real physical capacity is already sufficient', async () => {
+ const { root, store } = await setup({ MCP_HOST_GFS_CALLER_DOWNLOAD_MAX_FILES: '1' })
+ const callerRoot = await caller(root, 'caller-a')
+ const receipt = await copy(store, callerRoot, 'caller-a', 7)
+ const before = await nativeFs.statfs(root, { bigint: true })
+ expect(before.bavail * before.bsize).toBeGreaterThan(BigInt(MARGIN + 4096))
+ const next = await store.createTransfer({
+ callerIdentity: 'caller-a',
+ callerWorkspacePath: callerRoot,
+ source,
+ sizeBytes: 7,
+ expiresAt: new Date(Date.now() + 60_000).toISOString(),
+ })
+ expect(store.debugRecord(receipt.id)).toBeUndefined()
+ await expect(
+ nativeFs.lstat(path.join(callerRoot, path.dirname(receipt.path)))
+ ).rejects.toMatchObject({ code: 'ENOENT' })
+ expect(store.debugRecord(next.id)).toBeDefined()
+ await store.fail(next.id, 'caller-a')
+ })
+})
diff --git a/mcp-host/src/internalTools/gfsManagedImage.test.ts b/mcp-host/src/internalTools/gfsManagedImage.test.ts
index 1dad5588a..1f4ef8ded 100644
--- a/mcp-host/src/internalTools/gfsManagedImage.test.ts
+++ b/mcp-host/src/internalTools/gfsManagedImage.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it, vi } from 'vitest'
-import { createHash } from 'node:crypto'
+import { createHash, randomUUID } from 'node:crypto'
import { createRequire } from 'node:module'
import { join } from 'node:path'
import { crc32, deflateSync } from 'node:zlib'
@@ -91,6 +91,7 @@ function scenario(
readManaged?: () => Promise<Buffer>
} = {}
) {
+ const retentionOwnerId = randomUUID()
const budget = options.budget ?? new VisualInputBudget()
const receipt = {
id: 'managed-image',
@@ -110,7 +111,10 @@ function scenario(
stat: vi.fn(),
resolve: vi.fn(),
readMetadata: vi.fn(async () => ({ source, size: receipt.sizeBytes })),
- download: vi.fn(async () => receipt),
+ download: vi.fn<NonNullable<GfscReadClient['download']>>(async (_target, options) => {
+ expect(options.retentionOwnerId).toBe(retentionOwnerId)
+ return receipt
+ }),
read: vi.fn(async () => {
const reservation = budget.reserve(bytes.byteLength)
budget.consumeRead(bytes.byteLength)
@@ -129,6 +133,7 @@ function scenario(
downloadStore: store as unknown as GfsDownloadStore,
callerIdentity: 'caller-a',
callerWorkspacePath: '/tmp/managed-image-caller',
+ retentionOwnerId,
}).find(item => item.name === 'clerum__gfs_read')!
return {
diff --git a/mcp-host/src/main.ts b/mcp-host/src/main.ts
index 35bdeda7a..840b3e89f 100644
--- a/mcp-host/src/main.ts
+++ b/mcp-host/src/main.ts
@@ -190,6 +190,7 @@ import {
stopRuntimeAuthProactiveRefresh,
} from './workflow/runtimeAuthRefreshScheduler'
import { type McpHostRuntimeAuth, refreshWithRecovery } from './workflow/userApprovalRequester'
+import { resolveCallerRootBinding } from './workspace/callerRootBinding'
import { ScopedWorkspaceProvider } from './workspace/scopedWorkspace'
// Global state
@@ -2050,7 +2051,18 @@ const prepareIncomingMessage = createIncomingAdmission({
dispatch: dispatchIncomingMessage,
fileReferenceGfs: fileReferenceGfsGate,
gfsSurfaceRuntimeCapability: message => {
- const callerWorkspacePath = gfsWorkspaceProvider?.forSource(message)?.userRootPath
+ const callerRootBinding = resolveCallerRootBinding(gfsWorkspaceProvider, message)
+ if (callerRootBinding.failureCode) {
+ logger.warn(
+ {
+ component: 'gfs-runtime',
+ event: 'gfs_caller_root_unavailable',
+ code: callerRootBinding.failureCode,
+ },
+ 'GFS caller workspace unavailable; managed delivery and shell stay disabled'
+ )
+ }
+ const callerWorkspacePath = callerRootBinding.root
const shellApprovalEnabled =
(currentHost?.spec.approval || config.approvalConfig)?.tools?.shell_exec !== false
const workspaceFile = Boolean(
diff --git a/mcp-host/src/visualInput/messageProjection.test.ts b/mcp-host/src/visualInput/messageProjection.test.ts
index 57b7e7d0d..0b2501ab9 100644
--- a/mcp-host/src/visualInput/messageProjection.test.ts
+++ b/mcp-host/src/visualInput/messageProjection.test.ts
@@ -76,8 +76,13 @@ describe('per-attempt GFS receipt projection', () => {
})
})
- it('does not relabel a receipt from another resource version', () => {
- const original = messages(JSON.stringify({ ...receipt, source: { ...source, version: 8 } }))
+ it.each([
+ { drive: 'other' },
+ { resourceId: 'b'.repeat(32) },
+ { gfsUri: `gfs://main/${'b'.repeat(32)}` },
+ { version: 8 },
+ ])('does not relabel a receipt from another source: %j', changed => {
+ const original = messages(JSON.stringify({ ...receipt, source: { ...source, ...changed } }))
const before = structuredClone(original)
expect(() =>
projectGfsMessages(
diff --git a/mcp-host/src/visualInput/messageProjection.ts b/mcp-host/src/visualInput/messageProjection.ts
index 800b6366a..3290af67f 100644
--- a/mcp-host/src/visualInput/messageProjection.ts
+++ b/mcp-host/src/visualInput/messageProjection.ts
@@ -37,7 +37,8 @@ export function gfsReference(source: GfsImageSource) {
}
}
-function projectReceipt(
+/** Demote transient pixels while preserving a source-bound workspace receipt. */
+export function projectGfsReceipt(
content: string,
source: GfsImageSource,
reason: GfsReferenceReason
@@ -102,7 +103,7 @@ export function projectGfsMessages(
return messages.map(message => {
if (message.role === 'tool' && message.name === 'clerum__gfs_read' && message.tool_call_id) {
const source = selectedByCall.get(message.tool_call_id)
- const content = source ? projectReceipt(message.content, source, reason) : undefined
+ const content = source ? projectGfsReceipt(message.content, source, reason) : undefined
if (content !== undefined) {
const {
spillover_ref: _spillover,
diff --git a/mcp-host/src/visualInput/suspension.test.ts b/mcp-host/src/visualInput/suspension.test.ts
index 11121c368..69231d4b0 100644
--- a/mcp-host/src/visualInput/suspension.test.ts
+++ b/mcp-host/src/visualInput/suspension.test.ts
@@ -30,6 +30,114 @@ const result = (id = 'read-1'): ToolResult => ({
})
describe('current-turn GFS image lifecycle', () => {
+ const workspaceReceipt = {
+ delivery: 'workspace_file',
+ id: '11111111-1111-4111-8111-111111111111',
+ path: '.gfs-downloads/input-11111111-1111-4111-8111-111111111111/source',
+ sha256: 'b'.repeat(64),
+ sizeBytes: 8193,
+ expiresAt: '2099-01-01T00:00:00.000Z',
+ source,
+ visualDelivery: 'included',
+ usage: {
+ pathSemantics: 'relative-to-caller-workspace',
+ nextTool: 'shell_exec_when_local_processing_is_needed',
+ approval: 'user-approval-required',
+ visualDelivery: 'included',
+ processLocally: true,
+ boundedOutputOnly: true,
+ wholeFileToContextAllowed: false,
+ writeOutputsTo: 'outputs/',
+ },
+ }
+ const workspaceResult = (): ToolResult => ({
+ ...result(),
+ content: JSON.stringify(workspaceReceipt),
+ rawContent: image.dataBase64,
+ spillover_ref: 'spillover://task-1/read-1',
+ })
+ const pending = (completed: ToolResult[]): PendingApproval => ({
+ request_id: 'approval-workspace',
+ tool_name: 'shell_exec',
+ tool_call_id: 'pending-shell',
+ authorization_scope: 'exact_invocation',
+ description: 'Use the retained workspace file',
+ parameters: { command: 'printf approved' },
+ context_snapshot: [],
+ completed_results: completed,
+ })
+
+ it('preserves a completed workspace receipt and ordinary attachments while stripping GFS pixels and spillover links', () => {
+ const ordinary = { ...image, id: 'ordinary-shot', visualSource: undefined, dataBase64: 'QUJD' }
+ const gfs = workspaceResult()
+ gfs.attachments = [image, ordinary]
+ const other: ToolResult = {
+ tool_call_id: 'other-1',
+ name: 'http_request',
+ content: 'ordinary result',
+ is_error: false,
+ }
+ const approval = pending([gfs, other])
+ const before = structuredClone(approval)
+ const projected = projectGfsApproval(approval)
+ const completed = projected.completed_results![0]!
+
+ expect(JSON.parse(completed.content)).toEqual({
+ ...workspaceReceipt,
+ visualDelivery: 'not_included',
+ visualReason: 'new_gfs_read_required_after_suspension',
+ usage: {
+ ...workspaceReceipt.usage,
+ visualDelivery: 'not_included',
+ visualReason: 'new_gfs_read_required_after_suspension',
+ },
+ })
+ expect(completed.rawContent).toBe(completed.content)
+ expect(completed.spillover_ref).toBeUndefined()
+ expect(completed.attachments).toEqual([ordinary])
+ expect(projected.completed_results?.map(item => item.tool_call_id)).toEqual([
+ 'read-1',
+ 'other-1',
+ ])
+ expect(projected.completed_results![1]).toBe(other)
+ expect(projected.request_id).toBe(approval.request_id)
+ expect(projected.parameters).toBe(approval.parameters)
+ expect(projected.authorization_scope).toBe('exact_invocation')
+ expect(JSON.stringify(projected)).not.toContain(image.dataBase64)
+ expect(projectGfsApproval(projected)).toEqual(projected)
+ expect(approval).toEqual(before)
+ })
+
+ it.each([
+ { drive: 'other' },
+ { resourceId: 'b'.repeat(32) },
+ { gfsUri: `gfs://main/${'b'.repeat(32)}` },
+ { version: 4 },
+ ])('refuses to project a completed workspace receipt against another source: %j', changed => {
+ const completed = workspaceResult()
+ completed.content = JSON.stringify({ ...workspaceReceipt, source: { ...source, ...changed } })
+ const approval = pending([completed])
+ const before = structuredClone(approval)
+
+ expect(() => projectGfsApproval(approval)).toThrow('invalid_response')
+ expect(approval).toEqual(before)
+ })
+
+ it('keeps a legacy completed image receipt as a reference with no transient pixels', () => {
+ const completed = {
+ ...result(),
+ content: JSON.stringify({ delivery: 'image_input', resource: source }),
+ }
+ const projected = projectGfsApproval(pending([completed]))
+
+ expect(JSON.parse(projected.completed_results![0].content)).toMatchObject({
+ delivery: 'reference_only',
+ reason: 'new_gfs_read_required_after_suspension',
+ resource: source,
+ })
+ expect(JSON.stringify(projected)).not.toContain(image.dataBase64)
+ })
+
it('projects the GFS receipt and mixed visual carrier together on suspension', () => {
const gfs = {
...result('read-gfs'),
diff --git a/mcp-host/src/visualInput/suspension.ts b/mcp-host/src/visualInput/suspension.ts
index 91803a690..26033bdb9 100644
--- a/mcp-host/src/visualInput/suspension.ts
+++ b/mcp-host/src/visualInput/suspension.ts
@@ -1,16 +1,29 @@
import type { PendingApproval, ToolResult } from '../core/types'
-import { gfsImageParts, gfsReference, projectGfsMessages } from './messageProjection'
+import {
+ gfsImageParts,
+ gfsReference,
+ projectGfsMessages,
+ projectGfsReceipt,
+} from './messageProjection'
function projectResult(result: ToolResult): ToolResult {
const removed = result.attachments?.filter(a => a.visualSource?.kind === 'gfs') ?? []
if (!removed.length) return result
const attachments = result.attachments?.filter(a => a.visualSource?.kind !== 'gfs')
- const content = JSON.stringify({
+ const sources = removed.flatMap(a => (a.visualSource?.kind === 'gfs' ? [a.visualSource] : []))
+ const reason = 'new_gfs_read_required_after_suspension'
+ let content: string | undefined
+ for (const source of sources) {
+ // Use the same identity validation and receipt demotion as message history.
+ // A mismatched source must fail rather than silently relabel retained bytes.
+ content = projectGfsReceipt(result.content, source, reason) ?? content
+ }
+ // Legacy tool results without structured receipts retain their existing
+ // bounded references; only governed workspace receipts keep local usability.
+ content ??= JSON.stringify({
delivery: 'reference_only',
- reason: 'new_gfs_read_required_after_suspension',
- resources: removed.flatMap(a =>
- a.visualSource?.kind === 'gfs' ? [gfsReference(a.visualSource)] : []
- ),
+ reason,
+ resources: sources.map(gfsReference),
})
return {
tool_call_id: result.tool_call_id,
diff --git a/mcp-host/src/workspace/__tests__/gfsCallerRootBinding.test.ts b/mcp-host/src/workspace/__tests__/gfsCallerRootBinding.test.ts
new file mode 100644
index 000000000..34246c072
--- /dev/null
+++ b/mcp-host/src/workspace/__tests__/gfsCallerRootBinding.test.ts
@@ -0,0 +1,163 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import type { NativeToolConfig } from '../../core/interfaces'
+import { NativeToolRegistry } from '../../core/tools/nativeToolRegistry'
+import { GfsDownloadStore } from '../../internalTools/gfsDownloadStore'
+import type { IncomingMessage } from '../../server/types'
+import { type CallerRootBinding, resolveCallerRootBinding } from '../callerRootBinding'
+import { ScopedWorkspaceProvider } from '../scopedWorkspace'
+
+const config: NativeToolConfig = {
+ workspacePath: '',
+ shellTimeout: 5_000,
+ toolTimeout: 60_000,
+ toolProgressInterval: 0,
+ httpAllowlist: [],
+ envAllowlist: ['PATH'],
+ memoryMaxSize: 1_048_576,
+}
+
+describe('NativeRegistry GFS caller file-tool binding', () => {
+ let root: string
+ let store: GfsDownloadStore
+ const stores: GfsDownloadStore[] = []
+
+ beforeEach(() => {
+ root = fs.mkdtempSync(path.join(os.tmpdir(), 'gfs-caller-binding-'))
+ })
+
+ afterEach(async () => {
+ for (const item of stores.splice(0)) await item.close().catch(() => undefined)
+ fs.rmSync(root, { recursive: true, force: true })
+ })
+
+ function source(): IncomingMessage {
+ return {
+ content: 'process file',
+ channelType: 'rpc',
+ channelId: 'agent',
+ sender: 'alice',
+ timestamp: new Date().toISOString(),
+ messageId: 'message-1',
+ hostRef: 'host-1',
+ }
+ }
+
+ function registry(callerRoot: string | undefined, deliveryAvailable = true) {
+ return new NativeToolRegistry(
+ { ...config, workspacePath: root },
+ 'conversation-1',
+ undefined,
+ source(),
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ false,
+ undefined,
+ {
+ store,
+ deliveryAvailable,
+ callerIdentity: 'alice',
+ callerWorkspacePath: callerRoot,
+ processingLeaseProvider: store.processingLeaseProvider('alice'),
+ retentionOwnerId: '11111111-1111-4111-8111-111111111111',
+ }
+ )
+ }
+
+ it('binds memory-off file tools to the verified caller root and reserves store accounting', async () => {
+ store = new GfsDownloadStore(root)
+ stores.push(store)
+ await store.initialize()
+ const callerRoot = new ScopedWorkspaceProvider(root).forSource(source()).userRootPath
+ const registryForCaller = registry(callerRoot)
+
+ await registryForCaller.get('file_write')!.execute({ path: 'own.txt', content: 'own' })
+ expect(fs.existsSync(path.join(callerRoot, 'own.txt'))).toBe(true)
+ expect(fs.existsSync(path.join(root, 'own.txt'))).toBe(false)
+
+ const ledger = path.join(root, '.gfs-download-store', 'ledger-v1.json')
+ const before = fs.readFileSync(ledger, 'utf-8')
+ const directRead = await registryForCaller.get('file_read')!.execute({
+ path: '.gfs-download-store/ledger-v1.json',
+ })
+ const directWrite = await registryForCaller.get('file_write')!.execute({
+ path: '.gfs-download-store/ledger-v1.json',
+ content: 'stolen',
+ })
+ expect(directRead.is_error).toBe(true)
+ expect(directWrite.is_error).toBe(true)
+ expect(fs.readFileSync(ledger, 'utf-8')).toBe(before)
+ })
+
+ it('blocks another caller cache and symlink aliases through the caller root', async () => {
+ store = new GfsDownloadStore(root)
+ stores.push(store)
+ await store.initialize()
+ const provider = new ScopedWorkspaceProvider(root)
+ const aliceRoot = provider.forSource(source()).userRootPath
+ const bobRoot = provider.forUser('bob').userRootPath
+ const bobLedger = path.join(bobRoot, '.gfs-download-store', 'ledger-v2.json')
+ fs.mkdirSync(path.dirname(bobLedger), { recursive: true })
+ fs.writeFileSync(bobLedger, 'bob accounting', 'utf-8')
+ fs.symlinkSync(bobLedger, path.join(aliceRoot, 'other-caller-ledger.md'))
+ const registryForCaller = registry(aliceRoot)
+
+ const sibling = await registryForCaller.get('file_read')!.execute({
+ path: 'other-caller-ledger.md',
+ })
+ const traversal = await registryForCaller.get('file_read')!.execute({
+ path: '../bob/.gfs-download-store/ledger-v2.json',
+ })
+ expect(sibling.is_error).toBe(true)
+ expect(traversal.is_error).toBe(true)
+ })
+
+ it('keeps the verified caller root when delivery is recovery-required', async () => {
+ fs.mkdirSync(path.join(root, '.gfs-download-store'), { recursive: true })
+ fs.writeFileSync(path.join(root, '.gfs-download-store', 'ledger-v1.json'), '{invalid')
+ store = new GfsDownloadStore(root)
+ stores.push(store)
+ await store.initialize().catch(() => undefined)
+ const callerRoot = new ScopedWorkspaceProvider(root).forSource(source()).userRootPath
+ const degraded = registry(callerRoot, false)
+
+ await degraded.get('file_write')!.execute({ path: 'degraded.txt', content: 'still scoped' })
+ expect(fs.existsSync(path.join(callerRoot, 'degraded.txt'))).toBe(true)
+ expect(fs.existsSync(path.join(root, 'degraded.txt'))).toBe(false)
+ })
+
+ it('omits managed file tools when no verified caller root exists', () => {
+ store = new GfsDownloadStore(root)
+ stores.push(store)
+ const missingRoot = registry(undefined, false)
+ expect(missingRoot.get('file_read')).toBeNull()
+ expect(missingRoot.get('file_write')).toBeNull()
+ })
+
+ it('contains concrete filesystem binding failures and propagates programming errors', () => {
+ const eaccES = () => {
+ const error = new Error('unit') as NodeJS.ErrnoException
+ error.code = 'EACCES'
+ throw error
+ }
+ const unexpected = () => {
+ throw new TypeError('unit programming error')
+ }
+ const provider = (thrower: () => never) =>
+ ({ forSource: thrower }) as unknown as ScopedWorkspaceProvider
+ const expected: CallerRootBinding = resolveCallerRootBindingForTest(provider(eaccES))
+ expect(expected).toEqual({ failureCode: 'EACCES' })
+ expect(() => resolveCallerRootBindingForTest(provider(unexpected))).toThrow(TypeError)
+ })
+})
+
+function resolveCallerRootBindingForTest(provider: ScopedWorkspaceProvider): CallerRootBinding {
+ return resolveCallerRootBinding(provider, undefined)
+}
diff --git a/mcp-host/src/workspace/__tests__/protectedWorkspacePaths.test.ts b/mcp-host/src/workspace/__tests__/protectedWorkspacePaths.test.ts
index 205c199a1..569fab0f3 100644
--- a/mcp-host/src/workspace/__tests__/protectedWorkspacePaths.test.ts
+++ b/mcp-host/src/workspace/__tests__/protectedWorkspacePaths.test.ts
@@ -22,6 +22,18 @@ describe('protected workspace paths', () => {
fs.writeFileSync(path.join(downloadDir, 'source.md'), 'xylophone quixotic zenith', 'utf-8')
fs.writeFileSync(path.join(root, 'note.md'), 'public-token', 'utf-8')
fs.symlinkSync(path.join(downloadDir, 'source.md'), path.join(root, 'alias.md'))
+ const storeAccounting = path.join(root, '.gfs-download-store')
+ fs.mkdirSync(storeAccounting, { recursive: true })
+ for (const name of [
+ 'ledger-v1.json',
+ 'writer-v2.sqlite',
+ 'writer-v2.sqlite-journal',
+ 'writer.lock',
+ ]) {
+ fs.writeFileSync(path.join(storeAccounting, name), 'accounting-sentinel', 'utf-8')
+ }
+ fs.writeFileSync(path.join(storeAccounting, 'ledger-v1.json.tmp-1'), 'journal', 'utf-8')
+ fs.symlinkSync(storeAccounting, path.join(root, 'store-alias'))
})
afterEach(() => {
@@ -42,6 +54,25 @@ describe('protected workspace paths', () => {
await expect(workspace.search('public-token')).resolves.toHaveLength(1)
})
+ it('blocks the whole GFS accounting namespace and all of its artifacts', async () => {
+ const workspace = new WorkspaceService(root)
+ const paths = [
+ '.gfs-download-store/ledger-v1.json',
+ '.gfs-download-store/writer-v2.sqlite',
+ '.gfs-download-store/writer-v2.sqlite-journal',
+ '.gfs-download-store/writer.lock',
+ '.gfs-download-store/ledger-v1.json.tmp-1',
+ 'store-alias/ledger-v1.json',
+ ]
+ for (const relativePath of paths) {
+ await expect(workspace.read(relativePath)).rejects.toBeInstanceOf(GfsDownloadPathError)
+ }
+ await expect(workspace.list()).resolves.not.toContainEqual(
+ expect.objectContaining({ name: '.gfs-download-store' })
+ )
+ await expect(workspace.search('accounting-sentinel')).resolves.toEqual([])
+ })
+
it('blocks direct and symlinked access through file tools', async () => {
const read = new FileReadTool(root)
const direct = await read.execute({ path: '.gfs-downloads/input-1/source.md' })
diff --git a/mcp-host/src/workspace/callerRootBinding.ts b/mcp-host/src/workspace/callerRootBinding.ts
new file mode 100644
index 000000000..1153be48e
--- /dev/null
+++ b/mcp-host/src/workspace/callerRootBinding.ts
@@ -0,0 +1,43 @@
+import type { IncomingMessage } from '../server/types'
+import type { ScopedWorkspaceProvider } from './scopedWorkspace'
+
+export interface CallerRootBinding {
+ root?: string
+ failureCode?: 'EACCES' | 'EEXIST' | 'EIO' | 'ENOENT' | 'ENOSPC' | 'ENOTDIR' | 'EPERM' | 'EROFS'
+}
+
+function bindingFailureCode(error: unknown): CallerRootBinding['failureCode'] {
+ const code = (error as NodeJS.ErrnoException)?.code
+ if (
+ code === 'EACCES' ||
+ code === 'EEXIST' ||
+ code === 'EIO' ||
+ code === 'ENOENT' ||
+ code === 'ENOSPC' ||
+ code === 'ENOTDIR' ||
+ code === 'EPERM' ||
+ code === 'EROFS'
+ ) {
+ return code
+ }
+ return undefined
+}
+
+/**
+ * Derive a verified caller root without turning filesystem degradation into a
+ * fake system identity or shared-root fallback. Unexpected programming errors
+ * propagate; only concrete caller-root creation/access failures return undefined.
+ */
+export function resolveCallerRootBinding(
+ provider: ScopedWorkspaceProvider | null | undefined,
+ sourceMessage?: Pick<IncomingMessage, 'sender' | 'channelType'> | null
+): CallerRootBinding {
+ if (!provider) return {}
+ try {
+ return { root: provider.forSource(sourceMessage).userRootPath }
+ } catch (error) {
+ const failureCode = bindingFailureCode(error)
+ if (failureCode === undefined) throw error
+ return { failureCode }
+ }
+}
diff --git a/mcp-host/src/workspace/protectedPaths.ts b/mcp-host/src/workspace/protectedPaths.ts
index f0f8c5a0e..874967824 100644
--- a/mcp-host/src/workspace/protectedPaths.ts
+++ b/mcp-host/src/workspace/protectedPaths.ts
@@ -2,6 +2,7 @@ import * as path from 'path'
export const PROTECTED_WORKSPACE_DIRS: ReadonlySet<string> = new Set([
'.clerum-state',
+ '.gfs-download-store',
'.gfs-downloads',
])
@@ -50,7 +51,7 @@ export function isGfsDownloadPath(relativePath: string): boolean {
const segments = normalizeWorkspacePath(relativePath)
.split('/')
.filter(segment => segment.length > 0 && segment !== '.')
- return segments.some(segment => segment === '.gfs-downloads')
+ return segments.some(segment => segment === '.gfs-downloads' || segment === '.gfs-download-store')
}
export function stateDbProtectedMessage(filename: string): string {
@@ -74,7 +75,7 @@ export class StateDbPathError extends ProtectedWorkspacePathError {
export class GfsDownloadPathError extends ProtectedWorkspacePathError {
constructor(filename: string) {
super(
- `${filename} is a governed GFS download and cannot be accessed through workspace file tools.`
+ `${filename} is a governed GFS download/accounting artifact and cannot be accessed through workspace file tools.`
)
this.name = 'GfsDownloadPathError'
}