Skip to content

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

TypeScript

feat(mcp-host): protect GFS processing leases and admission surfaces

Alfredo Lopez6e0f6c766f10
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 660e6c099..a7fba88cd 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.480",
+ "version": "0.1.481",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.480",
+ "version": "0.1.481",
"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 8efd07c91..0724ea0e8 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.480",
+ "version": "0.1.481",
"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__/fileReferenceResolver.test.ts b/mcp-host/src/agent/__tests__/fileReferenceResolver.test.ts
index eff995bfa..12c0cf365 100644
--- a/mcp-host/src/agent/__tests__/fileReferenceResolver.test.ts
+++ b/mcp-host/src/agent/__tests__/fileReferenceResolver.test.ts
@@ -203,7 +203,19 @@ describe('resolveFileReferences (#666)', () => {
const result = await resolveFileReferences([ref], gfsc)
expect(result).toEqual({
ok: true,
- resolutions: [{ availability: 'available', reference: ref }],
+ resolutions: [
+ {
+ availability: 'available',
+ reference: ref,
+ surfaces: {
+ metadata: true,
+ inline: true,
+ workspace: false,
+ localExecutor: false,
+ visual: false,
+ },
+ },
+ ],
})
expect(gfsc.resolve).toHaveBeenCalledTimes(1)
expect(gfsc.resolve.mock.calls[0]![0]).toEqual({ uri: `gfs://main/${RID}` })
@@ -608,7 +620,19 @@ describe('resolveFileReferences (#666)', () => {
)
expect(await resolveFileReferences([gfsReference()], realClient(readable, fetch))).toEqual({
ok: true,
- resolutions: [{ availability: 'available', reference: gfsReference() }],
+ resolutions: [
+ {
+ availability: 'available',
+ reference: gfsReference(),
+ surfaces: {
+ metadata: true,
+ inline: true,
+ workspace: false,
+ localExecutor: false,
+ visual: false,
+ },
+ },
+ ],
})
expect(fetch).toHaveBeenCalledTimes(1)
})
diff --git a/mcp-host/src/agent/__tests__/gfsReferenceSurfaces.test.ts b/mcp-host/src/agent/__tests__/gfsReferenceSurfaces.test.ts
index 46c65ee3f..58fd2a42e 100644
--- a/mcp-host/src/agent/__tests__/gfsReferenceSurfaces.test.ts
+++ b/mcp-host/src/agent/__tests__/gfsReferenceSurfaces.test.ts
@@ -1,4 +1,11 @@
import { describe, expect, it } from 'vitest'
+import {
+ type FileReferenceV1,
+ buildGfsFileReference,
+ classifyBytes,
+} from '@clerum/gfs-interaction-policy'
+import { resolveFileReferences } from '../fileReferenceResolver'
+import type { FileReferenceGfscClient } from '../fileReferenceResolver'
import { classifyGfsReferenceSurfaces } from '../gfsReferenceSurfaces'
describe('classifyGfsReferenceSurfaces', () => {
@@ -75,4 +82,65 @@ describe('classifyGfsReferenceSurfaces', () => {
)
).toMatchObject({ inline: false, workspace: false, localExecutor: false })
})
+
+ it('attaches fail-closed delivery surfaces to available resolver results', async () => {
+ const resourceId = '0123456789abcdef0123456789abcdef'
+ const built = buildGfsFileReference({
+ drive: 'main',
+ resourceId,
+ gfsUri: `gfs://main/${resourceId}`,
+ version: 7,
+ name: 'incident.csv',
+ declaredMediaType: 'text/csv',
+ byteLength: 3_836_961,
+ classification: classifyBytes({
+ bytes: new Uint8Array(),
+ totalByteLength: 3_836_961,
+ declaredMediaType: 'text/csv',
+ filename: 'incident.csv',
+ }),
+ })
+ if (!built.ok) throw new Error(built.message)
+ const reference = built.value as FileReferenceV1
+ const client: FileReferenceGfscClient = {
+ resolve: async () => ({
+ ok: true,
+ data: {
+ kind: 'file',
+ rid: resourceId,
+ drive: 'main',
+ resourceId,
+ gfsUri: `gfs://main/${resourceId}`,
+ name: 'incident.csv',
+ version: 7,
+ bytes: 3_836_961,
+ },
+ }),
+ }
+
+ const failClosed = await resolveFileReferences([reference], client)
+ expect(failClosed.ok).toBe(true)
+ if (!failClosed.ok) return
+ expect(failClosed.resolutions[0]!.surfaces).toEqual({
+ metadata: true,
+ inline: false,
+ workspace: false,
+ localExecutor: false,
+ visual: false,
+ })
+
+ const enabled = await resolveFileReferences([reference], client, undefined, {
+ workspaceFile: true,
+ localExecutor: true,
+ visual: false,
+ })
+ expect(enabled.ok).toBe(true)
+ if (!enabled.ok) return
+ expect(enabled.resolutions[0]!.surfaces).toMatchObject({
+ inline: false,
+ workspace: true,
+ localExecutor: true,
+ visual: false,
+ })
+ })
})
diff --git a/mcp-host/src/agent/__tests__/incomingAdmission.fileReferences.test.ts b/mcp-host/src/agent/__tests__/incomingAdmission.fileReferences.test.ts
index 43d08f616..c23bd0f1a 100644
--- a/mcp-host/src/agent/__tests__/incomingAdmission.fileReferences.test.ts
+++ b/mcp-host/src/agent/__tests__/incomingAdmission.fileReferences.test.ts
@@ -164,7 +164,17 @@ describe('incoming admission with file references (#666)', () => {
const response = await admit(message({ fileReferences: [ref] }))
expect(resolve).toHaveBeenCalledTimes(1)
expect(dispatched(dispatch).fileReferenceResolutions).toEqual([
- { availability: 'available', reference: ref },
+ {
+ availability: 'available',
+ reference: ref,
+ surfaces: {
+ metadata: true,
+ inline: true,
+ workspace: false,
+ localExecutor: false,
+ visual: false,
+ },
+ },
])
expect(response).toEqual({
success: true,
diff --git a/mcp-host/src/agent/fileReferenceResolver.ts b/mcp-host/src/agent/fileReferenceResolver.ts
index 4c0df0f44..0422a89e8 100644
--- a/mcp-host/src/agent/fileReferenceResolver.ts
+++ b/mcp-host/src/agent/fileReferenceResolver.ts
@@ -15,6 +15,10 @@ import { GfscHttpError } from '../internalTools/gfsClient'
import { GFS_FILE_LIMITS } from '../internalTools/gfsFilePolicy'
import { logger } from '../logger'
import { VISUAL_INPUT_LIMITS } from '../visualInput/policy'
+import {
+ type GfsSurfaceRuntimeCapability,
+ classifyGfsReferenceSurfaces,
+} from './gfsReferenceSurfaces'
export type FileReferenceAvailability =
| 'available'
@@ -30,6 +34,8 @@ export interface FileReferenceResolution {
reference: FileReferenceV1
/** The version gfsc reports now, when it differs from the reference's. */
resolvedVersion?: number
+ /** Delivery surfaces proven for this Host/runtime; absent on old resolutions. */
+ surfaces?: ReturnType<typeof classifyGfsReferenceSurfaces>
}
/** The code each unavailable reference is reported under (log and turn block). */
@@ -262,7 +268,8 @@ function resolvedView(
async function resolveOne(
reference: FileReferenceV1,
client: FileReferenceGfscClient | null,
- call: { signal: AbortSignal; deadlineMs: number }
+ call: { signal: AbortSignal; deadlineMs: number },
+ runtimeSurfaces: GfsSurfaceRuntimeCapability
): Promise<FileReferenceResolution> {
const source = reference.source
if (source.kind !== 'gfs' || !client) return { availability: 'unsupported', reference }
@@ -288,7 +295,11 @@ async function resolveOne(
// misstates the file, not a change to it.
if (view.bytes !== reference.byteLength) throw new ResolutionFailure('invalid', 'SizeMismatch')
if (view.bytes > GFS_FILE_LIMITS.maxFileBytes) return { availability: 'too_large', reference }
- return { availability: 'available', reference }
+ return {
+ availability: 'available',
+ reference,
+ surfaces: classifyGfsReferenceSurfaces(reference, runtimeSurfaces),
+ }
}
/**
@@ -298,14 +309,19 @@ async function resolveOne(
export async function resolveFileReferences(
references: readonly FileReferenceV1[],
client: FileReferenceGfscClient | null,
- timeoutMs: number = VISUAL_INPUT_LIMITS.validationTimeoutMs
+ timeoutMs: number = VISUAL_INPUT_LIMITS.validationTimeoutMs,
+ runtimeSurfaces: GfsSurfaceRuntimeCapability = {
+ workspaceFile: false,
+ localExecutor: false,
+ visual: false,
+ }
): Promise<FileReferenceResolutionResult> {
const controller = new AbortController()
const timer = setTimeout(() => controller.abort(), timeoutMs)
const call = { signal: controller.signal, deadlineMs: Date.now() + timeoutMs }
try {
const resolutions = await Promise.all(
- references.map(reference => resolveOne(reference, client, call))
+ references.map(reference => resolveOne(reference, client, call, runtimeSurfaces))
)
return { ok: true, resolutions }
} catch (error) {
diff --git a/mcp-host/src/agent/incomingAdmission.ts b/mcp-host/src/agent/incomingAdmission.ts
index ea65eae61..2caa1d478 100644
--- a/mcp-host/src/agent/incomingAdmission.ts
+++ b/mcp-host/src/agent/incomingAdmission.ts
@@ -24,6 +24,7 @@ import {
type FileReferenceResolutionResult,
resolveFileReferences,
} from './fileReferenceResolver'
+import type { GfsSurfaceRuntimeCapability } from './gfsReferenceSurfaces'
import { type IncomingAttachmentLimits, validateIncomingAttachments } from './incomingAttachments'
import type { SessionModelSelectionOptions } from './sessionModelSelection'
@@ -75,6 +76,8 @@ export interface IncomingAdmissionDeps {
* called; a token that cannot be read or decoded refuses the message.
*/
fileReferenceGfs: () => FileReferenceGfsAccess
+ /** Host-owned surface capability; omitted means every optional surface fails closed. */
+ gfsSurfaceRuntimeCapability?: (message: IncomingMessage) => GfsSurfaceRuntimeCapability
logger: {
info: (obj: Record<string, unknown>, msg: string) => void
warn: (obj: Record<string, unknown>, msg: string) => void
@@ -482,12 +485,19 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAd
const access: FileReferenceGfsAccess = fileReferences.some(ref => ref.source.kind === 'gfs')
? deps.fileReferenceGfs()
: { status: 'unsupported' }
+ const runtimeSurfaces = deps.gfsSurfaceRuntimeCapability?.(normalizedMessage) ?? {
+ workspaceFile: false,
+ localExecutor: false,
+ visual: false,
+ }
const resolved: FileReferenceResolutionResult =
access.status === 'credentials_failed'
? { ok: false, failure: 'credentials', errorClass: access.errorClass }
: await resolveFileReferences(
fileReferences,
- access.status === 'available' ? access.client : null
+ access.status === 'available' ? access.client : null,
+ undefined,
+ runtimeSurfaces
)
if (!resolved.ok) {
deps.logger.warn(
diff --git a/mcp-host/src/agent/taskExecutor.ts b/mcp-host/src/agent/taskExecutor.ts
index 58c0fdfdd..4055881ee 100644
--- a/mcp-host/src/agent/taskExecutor.ts
+++ b/mcp-host/src/agent/taskExecutor.ts
@@ -2067,20 +2067,25 @@ export class TaskExecutor {
this.deps.failover?.policy.fallbacks
)
const gfsCallerIdentity = this.task.sourceMessage?.sender
+ const gfsProcessingLeaseProvider =
+ this.deps.gfsProcessingLeaseProvider ??
+ (this.deps.gfsDownloadStore && gfsCallerIdentity
+ ? this.deps.gfsDownloadStore.processingLeaseProvider(gfsCallerIdentity)
+ : undefined)
const gfsDownload = gfsWorkspaceExecutionEnabled({
approvalEnabled: appConfig.enableApproval,
source: this.task.source,
callerIdentity: gfsCallerIdentity,
store: this.deps.gfsDownloadStore,
callerWorkspacePath: this.deps.gfsCallerWorkspacePath,
- processingLeaseProvider: this.deps.gfsProcessingLeaseProvider,
+ processingLeaseProvider: gfsProcessingLeaseProvider,
approvalConfig: this.deps.approvalConfig,
})
? {
store: this.deps.gfsDownloadStore!,
callerIdentity: gfsCallerIdentity!,
callerWorkspacePath: this.deps.gfsCallerWorkspacePath!,
- processingLeaseProvider: this.deps.gfsProcessingLeaseProvider!,
+ processingLeaseProvider: gfsProcessingLeaseProvider!,
}
: undefined
const nativeRegistry = new NativeToolRegistry(
diff --git a/mcp-host/src/core/adapters/__tests__/llmImageCompatibility.test.ts b/mcp-host/src/core/adapters/__tests__/llmImageCompatibility.test.ts
index c05ce9188..bcca56473 100644
--- a/mcp-host/src/core/adapters/__tests__/llmImageCompatibility.test.ts
+++ b/mcp-host/src/core/adapters/__tests__/llmImageCompatibility.test.ts
@@ -515,7 +515,10 @@ describe('image source identity compatibility (#650)', () => {
expect(imagePartsOf(binding.completeWithTools[0].messages)).toHaveLength(4)
expect(
imagePartsOf(binding.completeWithTools[0].messages).every(
- part => part.source?.kind === 'tool' || part.source?.kind === 'attachment'
+ part =>
+ part.source?.kind === 'tool' ||
+ part.source?.kind === 'attachment' ||
+ part.source?.kind === 'gfs'
)
).toBe(true)
expect(messages).toEqual(snapshot)
diff --git a/mcp-host/src/core/extensions/approvalController.ts b/mcp-host/src/core/extensions/approvalController.ts
index 81a6ef5d7..5a3728d38 100644
--- a/mcp-host/src/core/extensions/approvalController.ts
+++ b/mcp-host/src/core/extensions/approvalController.ts
@@ -18,7 +18,7 @@
import { LoopController } from '../interfaces'
import { ChatMessage, PendingApproval, ToolDefinition } from '../types'
import type { Conversation } from '../types'
-import { getMcpServerPrefix, isMcpToolName } from './mcpApprovalGateController'
+import { getMcpServerPrefix } from './mcpApprovalGateController'
/**
* Decorator that checks auto_approved_tools before delegating to base controller.
diff --git a/mcp-host/src/internalTools/gfs.ts b/mcp-host/src/internalTools/gfs.ts
index 1959b2b1f..32ca68d77 100644
--- a/mcp-host/src/internalTools/gfs.ts
+++ b/mcp-host/src/internalTools/gfs.ts
@@ -167,7 +167,10 @@ async function readManagedImageBytes(
): Promise<Buffer> {
const target = await resolveManagedImagePath(receipt, callerWorkspacePath)
- const handle = await fs.open(target, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW)
+ const handle = await fs.open(
+ target,
+ fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_EXCL
+ )
try {
const stat = await handle.stat()
if (
@@ -191,7 +194,10 @@ async function readManagedImagePrefix(
callerWorkspacePath: string
): Promise<Buffer> {
const target = await resolveManagedImagePath(receipt, callerWorkspacePath)
- const handle = await fs.open(target, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW)
+ const handle = await fs.open(
+ target,
+ fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_EXCL
+ )
try {
const prefix = Buffer.alloc(16)
const { bytesRead } = await handle.read(prefix, 0, prefix.length, 0)
@@ -526,10 +532,11 @@ export function buildGfsReadTools(
reason: 'workspace_delivery_is_required_for_this_file_size',
})
}
- recordGfsDownloadAdmission('inline_attempt')
- if (expectedVersion === undefined) expectedVersion = metadata.source.version
}
}
+ recordGfsDownloadAdmission('inline_attempt')
+ if (expectedVersion === undefined && snapshot?.source.version !== undefined)
+ expectedVersion = snapshot.source.version
file = await client.read(target as { drive: string; resourceId: string }, {
...callOptions(options),
timeoutMs: options?.timeoutMs,
diff --git a/mcp-host/src/internalTools/gfsContentRead.expectedVersion.test.ts b/mcp-host/src/internalTools/gfsContentRead.expectedVersion.test.ts
index e493bb750..95e648802 100644
--- a/mcp-host/src/internalTools/gfsContentRead.expectedVersion.test.ts
+++ b/mcp-host/src/internalTools/gfsContentRead.expectedVersion.test.ts
@@ -77,7 +77,7 @@ describe('readGfsContent expectedVersion (#666)', () => {
)
it.each([
- ['grew past the file limit', { bytes: VISUAL_INPUT_LIMITS.fileBytes + 1 }, 'limit_exceeded'],
+ ['grew past the file limit', { bytes: GFS_FILE_LIMITS.maxFileBytes + 1 }, 'limit_exceeded'],
['became a directory', { kind: 'directory' }, 'unsupported_format'],
])(
'reports a pinned read as version_conflict when the newer version %s',
diff --git a/mcp-host/src/internalTools/gfsDownloadStore.ts b/mcp-host/src/internalTools/gfsDownloadStore.ts
index 319a61885..d0d9d1ae5 100644
--- a/mcp-host/src/internalTools/gfsDownloadStore.ts
+++ b/mcp-host/src/internalTools/gfsDownloadStore.ts
@@ -8,6 +8,11 @@ import {
GFS_HOST_ACTIVE_DOWNLOADS,
GFS_HOST_RETAINED_FILES,
} from './gfsFilePolicy'
+import type {
+ GfsProcessingLease,
+ GfsProcessingLeaseAcquisition,
+ GfsProcessingLeaseProvider,
+} from './gfsProcessingLease'
export type GfsDownloadStoreErrorCode =
| 'caller_mismatch'
@@ -65,6 +70,15 @@ export interface GfsDownloadReceipt {
interface StoreLedger {
schemaVersion: 1
records: Record<string, GfsDownloadRecord>
+ processingLeases?: Record<string, GfsProcessingLeaseRecord>
+}
+
+interface GfsProcessingLeaseRecord {
+ leaseId: string
+ callerIdentity: string
+ recordIds: string[]
+ acquiredAt: string
+ expiresAt: string
}
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
@@ -87,7 +101,7 @@ function parseLedger(raw: string): StoreLedger {
throw new GfsDownloadStoreError('corrupt_store_ledger')
const records = (parsed as { records: Record<string, unknown> }).records
- const result: StoreLedger = { schemaVersion: 1, records: {} }
+ const result: StoreLedger = { schemaVersion: 1, records: {}, processingLeases: {} }
for (const [id, value] of Object.entries(records)) {
if (!UUID_RE.test(id) || typeof value !== 'object' || value === null)
throw new GfsDownloadStoreError('corrupt_store_ledger')
@@ -130,6 +144,31 @@ function parseLedger(raw: string): StoreLedger {
throw new GfsDownloadStoreError('corrupt_store_ledger')
result.records[id] = record
}
+ const rawProcessingLeases = (parsed as { processingLeases?: unknown }).processingLeases
+ if (rawProcessingLeases !== undefined) {
+ if (typeof rawProcessingLeases !== 'object' || rawProcessingLeases === null)
+ throw new GfsDownloadStoreError('corrupt_store_ledger')
+ for (const [id, value] of Object.entries(rawProcessingLeases)) {
+ const lease = value as GfsProcessingLeaseRecord
+ if (
+ !UUID_RE.test(id) ||
+ typeof value !== 'object' ||
+ value === null ||
+ lease.leaseId !== id ||
+ typeof lease.callerIdentity !== 'string' ||
+ lease.callerIdentity.length === 0 ||
+ !Array.isArray(lease.recordIds) ||
+ lease.recordIds.some(recordId => !UUID_RE.test(recordId)) ||
+ new Set(lease.recordIds).size !== lease.recordIds.length ||
+ lease.recordIds.some(recordId => result.records[recordId] === undefined) ||
+ !Number.isFinite(Date.parse(lease.acquiredAt)) ||
+ !Number.isFinite(Date.parse(lease.expiresAt)) ||
+ Date.parse(lease.expiresAt) <= Date.parse(lease.acquiredAt)
+ )
+ throw new GfsDownloadStoreError('corrupt_store_ledger')
+ result.processingLeases![id] = lease
+ }
+ }
return result
}
@@ -166,25 +205,29 @@ async function syncDirectory(directory: string): Promise<void> {
}
}
-async function sha256File(path: string): Promise<string> {
+async function sha256FileHandle(handle: fs.FileHandle): Promise<string> {
const digest = createHash('sha256')
+ const chunk = Buffer.alloc(64 * 1024)
+ let position = 0
+ for (;;) {
+ const { bytesRead } = await handle.read(chunk, 0, chunk.byteLength, position)
+ if (bytesRead === 0) break
+ digest.update(chunk.subarray(0, bytesRead))
+ position += bytesRead
+ }
+ return digest.digest('hex')
+}
+
+async function sha256File(path: string): Promise<string> {
const handle = await fs.open(
path,
constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK
)
try {
- const chunk = Buffer.alloc(64 * 1024)
- let position = 0
- for (;;) {
- const { bytesRead } = await handle.read(chunk, 0, chunk.byteLength, position)
- if (bytesRead === 0) break
- digest.update(chunk.subarray(0, bytesRead))
- position += bytesRead
- }
+ return await sha256FileHandle(handle)
} finally {
await handle.close()
}
- return digest.digest('hex')
}
/** One Host/PVC-owned durable store; task registries receive bound handles. */
@@ -194,9 +237,10 @@ export class GfsDownloadStore {
private ledgerPath: string
private lockPath: string
private writerLeaseId?: string
- private ledger: StoreLedger = { schemaVersion: 1, records: {} }
+ private ledger: StoreLedger = { schemaVersion: 1, records: {}, processingLeases: {} }
private readonly activeByCaller = new Map<string, number>()
private readonly activeIds = new Set<string>()
+ private readonly liveProcessingLeases = new Set<string>()
private active = 0
private mutationTail = Promise.resolve()
private initialized = false
@@ -365,12 +409,23 @@ export class GfsDownloadStore {
throw new GfsDownloadStoreError('download_expired')
const partial = path.join(this.hostRoot, `${record.hostPath}.partial`)
const source = path.join(this.hostRoot, record.hostPath)
- const info = await fs.lstat(partial).catch(() => undefined)
- if (!info?.isFile() || info.isSymbolicLink() || info.size !== record.sizeBytes)
- throw new GfsDownloadStoreError('download_missing')
- if ((await sha256File(partial)) !== sha256)
- throw new GfsDownloadStoreError('corrupt_store_ledger')
- await fs.rename(partial, source)
+ const partialHandle = await fs
+ .open(
+ partial,
+ constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_EXCL | constants.O_NONBLOCK
+ )
+ .catch(() => undefined)
+ if (!partialHandle) throw new GfsDownloadStoreError('download_missing')
+ try {
+ const info = await partialHandle.stat()
+ if (!info.isFile() || info.isSymbolicLink() || info.size !== record.sizeBytes)
+ throw new GfsDownloadStoreError('download_missing')
+ if ((await sha256FileHandle(partialHandle)) !== sha256)
+ throw new GfsDownloadStoreError('corrupt_store_ledger')
+ await fs.rename(partial, source)
+ } finally {
+ await partialHandle.close()
+ }
await syncDirectory(path.dirname(source))
record.state = 'completed'
record.sha256 = sha256
@@ -463,6 +518,91 @@ export class GfsDownloadStore {
}
}
+ processingLeaseProvider(callerIdentity: string): GfsProcessingLeaseProvider {
+ return {
+ acquireProcessingLease: (options?: GfsProcessingLeaseAcquisition) =>
+ this.acquireProcessingLease(callerIdentity, options),
+ releaseProcessingLease: (lease: GfsProcessingLease) =>
+ this.releaseProcessingLease(callerIdentity, lease),
+ }
+ }
+
+ private async acquireProcessingLease(
+ callerIdentity: string,
+ options?: GfsProcessingLeaseAcquisition
+ ): Promise<GfsProcessingLease> {
+ this.assertInitialized()
+ if (this.closing) throw new GfsDownloadStoreError('download_busy')
+ if (typeof callerIdentity !== 'string' || callerIdentity.length === 0)
+ throw new GfsDownloadStoreError('caller_mismatch')
+ const requestedMs = options?.durationMs ?? 60_000
+ if (!Number.isSafeInteger(requestedMs) || requestedMs <= 0 || requestedMs > 3_600_000)
+ throw new GfsDownloadStoreError('download_busy')
+
+ const now = Date.now()
+ const candidates = Object.values(this.ledger.records).filter(
+ record =>
+ record.callerIdentity === callerIdentity &&
+ record.state === 'completed' &&
+ record.sha256 !== undefined &&
+ Date.parse(record.expiresAt) > now
+ )
+ if (candidates.length === 0) {
+ return {
+ leaseId: randomUUID(),
+ expiresAt: new Date(now + requestedMs).toISOString(),
+ }
+ }
+
+ return this.serialize(async () => {
+ for (const record of candidates) await this.inspect(record.path, callerIdentity)
+ const leaseId = randomUUID()
+ const expiresAt = new Date(now + requestedMs).toISOString()
+ const lease: GfsProcessingLeaseRecord = {
+ leaseId,
+ callerIdentity,
+ recordIds: candidates.map(record => record.id),
+ acquiredAt: new Date(now).toISOString(),
+ expiresAt,
+ }
+ this.ledger.processingLeases ??= {}
+ this.ledger.processingLeases[leaseId] = lease
+ try {
+ await this.persist()
+ } catch (error) {
+ delete this.ledger.processingLeases[leaseId]
+ throw error
+ }
+ this.liveProcessingLeases.add(leaseId)
+ return { leaseId, expiresAt }
+ })
+ }
+
+ private async releaseProcessingLease(
+ callerIdentity: string,
+ lease: GfsProcessingLease
+ ): Promise<void> {
+ this.assertInitialized()
+ await this.serialize(async () => {
+ const record = this.ledger.processingLeases?.[lease.leaseId]
+ if (!record) {
+ this.liveProcessingLeases.delete(lease.leaseId)
+ return
+ }
+ if (record.callerIdentity !== callerIdentity || record.expiresAt !== lease.expiresAt)
+ throw new GfsDownloadStoreError('caller_mismatch')
+ delete this.ledger.processingLeases![lease.leaseId]
+ try {
+ await this.persist()
+ } catch (error) {
+ this.ledger.processingLeases![lease.leaseId] = record
+ this.liveProcessingLeases.add(lease.leaseId)
+ throw error
+ }
+ this.liveProcessingLeases.delete(lease.leaseId)
+ })
+ }
+
debugRecord(id: string): GfsDownloadRecord | undefined {
return this.ledger.records[id]
}
@@ -479,10 +619,13 @@ export class GfsDownloadStore {
if (!this.initialized) return
this.closing = true
const deadline = Date.now() + drainTimeoutMs
- while (this.activeIds.size > 0 && Date.now() < deadline) {
+ while (
+ (this.activeIds.size > 0 || this.liveProcessingLeases.size > 0) &&
+ Date.now() < deadline
+ ) {
await new Promise(resolve => setTimeout(resolve, 25))
}
- if (this.activeIds.size > 0) {
+ if (this.activeIds.size > 0 || this.liveProcessingLeases.size > 0) {
this.closing = false
throw new GfsDownloadStoreError('download_busy')
}
@@ -503,9 +646,17 @@ export class GfsDownloadStore {
await this.serialize(async () => {
const removed: string[] = []
let stateChanged = false
+ for (const [leaseId, lease] of Object.entries(this.ledger.processingLeases ?? {})) {
+ if (Date.parse(lease.expiresAt) <= now) {
+ delete this.ledger.processingLeases![leaseId]
+ this.liveProcessingLeases.delete(leaseId)
+ stateChanged = true
+ }
+ }
for (const record of Object.values(this.ledger.records)) {
if (Date.parse(record.expiresAt) > now) continue
if (this.activeIds.has(record.id)) continue
+ if (this.hasProcessingLease(record.id, now)) continue
const directory = path.join(this.hostRoot, record.directory)
try {
const info = await fs.lstat(directory)
@@ -640,6 +791,12 @@ export class GfsDownloadStore {
return record
}
+ private hasProcessingLease(recordId: string, now: number): boolean {
+ return Object.values(this.ledger.processingLeases ?? {}).some(
+ lease => Date.parse(lease.expiresAt) > now && lease.recordIds.includes(recordId)
+ )
+ }
+
private releaseActive(record: GfsDownloadRecord): void {
if (!this.activeIds.has(record.id)) return
this.active = Math.max(0, this.active - 1)
diff --git a/mcp-host/src/internalTools/gfsDownloadStoreProcessingLease.test.ts b/mcp-host/src/internalTools/gfsDownloadStoreProcessingLease.test.ts
new file mode 100644
index 000000000..bfbe63c77
--- /dev/null
+++ b/mcp-host/src/internalTools/gfsDownloadStoreProcessingLease.test.ts
@@ -0,0 +1,124 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createHash } from 'node:crypto'
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import type { GfsImageSource } from '../visualInput/policy'
+import { GfsDownloadStore } from './gfsDownloadStore'
+
+const source: GfsImageSource = {
+ kind: 'gfs',
+ drive: 'main',
+ resourceId: '0123456789abcdef0123456789abcdef',
+ gfsUri: 'gfs://main/0123456789abcdef0123456789abcdef',
+ name: 'input.csv',
+ version: 7,
+}
+
+describe('GfsDownloadStore processing leases', () => {
+ let hostRoot: string
+ let callerRoot: string
+ let store: GfsDownloadStore
+
+ beforeEach(() => {
+ hostRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'gfs-processing-lease-'))
+ callerRoot = path.join(hostRoot, 'users', 'caller-a')
+ fs.mkdirSync(callerRoot, { recursive: true, mode: 0o700 })
+ store = new GfsDownloadStore(hostRoot)
+ })
+
+ afterEach(() => {
+ vi.restoreAllMocks()
+ fs.rmSync(hostRoot, { recursive: true, force: true })
+ })
+
+ async function publishFixture(expiresAt = new Date(Date.now() + 60_000).toISOString()) {
+ await store.initialize()
+ const bytes = Buffer.from('fixture')
+ const transfer = await store.createTransfer({
+ callerIdentity: 'caller-a',
+ callerWorkspacePath: callerRoot,
+ source,
+ sizeBytes: bytes.byteLength,
+ expiresAt,
+ })
+ fs.writeFileSync(path.join(callerRoot, transfer.partialPath), bytes)
+ return store.publish(transfer.id, 'caller-a', createHash('sha256').update(bytes).digest('hex'))
+ }
+
+ it('acquires and releases a caller-bound durable lease', async () => {
+ const receipt = await publishFixture()
+ const provider = store.processingLeaseProvider('caller-a')
+ const lease = await provider.acquireProcessingLease({ durationMs: 60_000 })
+
+ expect(lease.leaseId).toMatch(/^[0-9a-f-]{36}$/)
+ expect(lease.expiresAt).toBeDefined()
+ await provider.releaseProcessingLease(lease)
+ expect(store.debugRecord(receipt.id)).toBeDefined()
+ })
+
+ it('rejects release by another caller', async () => {
+ await publishFixture()
+ const lease = await store.processingLeaseProvider('caller-a').acquireProcessingLease()
+ await expect(
+ store.processingLeaseProvider('caller-b').releaseProcessingLease(lease)
+ ).rejects.toMatchObject({ code: 'caller_mismatch' })
+ })
+
+ it('protects an expired download from cleanup while leased', async () => {
+ const receipt = await publishFixture()
+ const lease = await store
+ .processingLeaseProvider('caller-a')
+ .acquireProcessingLease({ durationMs: 60_000 })
+
+ await store.cleanupExpired(Date.parse(receipt.expiresAt) + 1)
+ expect(store.debugRecord(receipt.id)).toBeDefined()
+
+ await store.processingLeaseProvider('caller-a').releaseProcessingLease(lease)
+ await store.cleanupExpired(Date.parse(receipt.expiresAt) + 1)
+ expect(store.debugRecord(receipt.id)).toBeUndefined()
+ })
+
+ it('recovers a lease conservatively after a store restart', async () => {
+ const receipt = await publishFixture(new Date(Date.now() + 250).toISOString())
+ const lease = await store
+ .processingLeaseProvider('caller-a')
+ .acquireProcessingLease({ durationMs: 1_000 })
+ await expect(store.close(10)).rejects.toMatchObject({ code: 'download_busy' })
+ ;(
+ store as unknown as {
+ liveProcessingLeases: Set<string>
+ }
+ ).liveProcessingLeases.delete(lease.leaseId)
+ await store.close()
+ await new Promise(resolve => setTimeout(resolve, 300))
+
+ const restarted = new GfsDownloadStore(hostRoot)
+ await restarted.initialize()
+ await restarted.cleanupExpired(Date.parse(receipt.expiresAt) + 1)
+ expect(restarted.debugRecord(receipt.id)).toBeDefined()
+
+ await new Promise(resolve => setTimeout(resolve, 1_000))
+ await restarted.cleanupExpired(Date.parse(lease.expiresAt) + 1)
+ expect(restarted.debugRecord(receipt.id)).toBeUndefined()
+ await restarted.close()
+ })
+
+ it('retains protection when lease release persistence fails', async () => {
+ const receipt = await publishFixture()
+ const provider = store.processingLeaseProvider('caller-a')
+ const lease = await provider.acquireProcessingLease({ durationMs: 60_000 })
+ vi.spyOn(store as unknown as { persist: () => Promise<void> }, 'persist').mockRejectedValueOnce(
+ new Error('disk unavailable')
+ )
+
+ await expect(provider.releaseProcessingLease(lease)).rejects.toThrow()
+ await store.cleanupExpired(Date.parse(receipt.expiresAt) + 1)
+ expect(store.debugRecord(receipt.id)).toBeDefined()
+
+ vi.restoreAllMocks()
+ await provider.releaseProcessingLease(lease)
+ await store.cleanupExpired(Date.parse(receipt.expiresAt) + 1)
+ expect(store.debugRecord(receipt.id)).toBeUndefined()
+ })
+})
diff --git a/mcp-host/src/main.ts b/mcp-host/src/main.ts
index 3ceeee2a8..f49ff419a 100644
--- a/mcp-host/src/main.ts
+++ b/mcp-host/src/main.ts
@@ -233,6 +233,7 @@ let contextMapperClient: ContextMapperClient | null = null
let mcpAuthorityLastSuccessAt = 0
let activityHub: HostActivityHub | null = null
let workspaceProvider: ScopedWorkspaceProvider | null = null
+let gfsWorkspaceProvider: ScopedWorkspaceProvider | null = null
let gfsDownloadStore: GfsDownloadStore | null = null
let gfsDownloadCleanupTimer: NodeJS.Timeout | null = null
let spilloverStorage: SpilloverStorage | null = null
@@ -1726,7 +1727,7 @@ async function initializeAgent(): Promise<void> {
agent.setDynamicEnvProvider(() => agentToolEnvProvider(configStore))
agent.setSecretEntriesProvider(() => configStore?.listSecretEntries() ?? [])
- const gfsWorkspaceProvider = new ScopedWorkspaceProvider(config.nativeTool.workspacePath)
+ gfsWorkspaceProvider = new ScopedWorkspaceProvider(config.nativeTool.workspacePath)
gfsDownloadStore = new GfsDownloadStore(config.nativeTool.workspacePath)
await gfsDownloadStore.initialize()
agent.setGfsWorkspaceProvider(gfsWorkspaceProvider)
@@ -2055,6 +2056,24 @@ const prepareIncomingMessage = createIncomingAdmission({
applySessionModelSelection,
dispatch: dispatchIncomingMessage,
fileReferenceGfs: fileReferenceGfsGate,
+ gfsSurfaceRuntimeCapability: message => {
+ const callerWorkspacePath = gfsWorkspaceProvider?.forSource(message)?.userRootPath
+ const shellApprovalEnabled =
+ (currentHost?.spec.approval || config.approvalConfig)?.tools?.shell_exec !== false
+ const workspaceFile = Boolean(
+ config.enableApproval &&
+ message.sender &&
+ gfsDownloadStore &&
+ callerWorkspacePath &&
+ shellApprovalEnabled
+ )
+ return {
+ workspaceFile,
+ localExecutor: workspaceFile,
+ // Visual support is decided per physical provider attempt, never here.
+ visual: false,
+ }
+ },
logger,
})