Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
fix(mcp-host): absolute GFS retention and storage-full guidance
Alfredo Lopezb73e831b4c02
diff --git a/docs/operations/gfs-large-file-host-downloads.md b/docs/operations/gfs-large-file-host-downloads.mdindex 8e64caf2b..ee1675502 100644--- a/docs/operations/gfs-large-file-host-downloads.md+++ b/docs/operations/gfs-large-file-host-downloads.md@@ -175,7 +175,7 @@ a new ID, after fresh GFS authorization.6. The retained-storage budget, free space and the Host-wide active-transferlimit are shared by every caller on a Host; there is no per-caller byte orfile limit. A caller can therefore observe aggregate pressure from others- (`host_quota_exceeded`, Host-scope `download_busy`, or an eviction that+ (`host_quota_exceeded`, `disk_full`, Host-scope `download_busy`, or an eviction thatremoves one of its own unpinned copies), and one caller's admission canevict another caller's unpinned copies, which costs that caller are-download. These signals carry no identity, count, name or path of@@ -321,21 +321,30 @@ no per-caller limit on unpinned copies: those per-user limits were removed byuser decision, and one caller can hold any number of unpinned copies while thebudget has room.-Eviction cannot reclaim what a caller protects: the copies its tasks pin and-its active reservations. A caller's protected bytes (each copy once, whichever-of its tasks pins it) may therefore reach at most `floor(budget / 2)`, so one-caller's open tasks always leave half the budget reclaimable for everyone else.+Eviction cannot reclaim what a caller protects: the unexpired copies its tasks+pin and its active reservations. A caller's protected bytes (each copy once,+whichever of its tasks pins it) may therefore reach at most `floor(budget / 2)`.An admission that would take a caller over that half, or a reuse that would pina copy the caller does not protect yet, is refused with `host_quota_exceeded`(scope `caller`, reason `protected_bytes`) before any eviction. The decision andthe error use only that caller's own usage; the error is the same as a fullHost budget. A single download larger than half the budget is always refused(about 4.25 GiB on a 10 Gi volume at 85%, far above the per-file limit).--Before refusing, the store plans an eviction of complete, unpinned copies that-are not being transferred, in any caller's directory: adopted copies first-(oldest `createdAt` first), then published copies least recently used first-(publication, reuse or managed read). Pinned copies are never evicted. One+Re-pinning a copy the caller already protects adds nothing and is decided+before the volume is measured.++The cap bounds each caller, not their sum. Two callers at their caps together+protect the whole budget, and then every admission of a positive size is+refused until a task releases its pins or the pinned copies expire. This is an+accepted risk: a pin never outlives the copy's `expiresAt` (see+[Retention pins](#retention-pins-and-cold-resume)), so the state lasts at most+the retention period, `MCP_HOST_GFS_DOWNLOAD_TTL_HOURS` (168 hours by default).++Before refusing, the store plans an eviction of complete copies that are+unpinned or pinned but already expired and are not being transferred, in any+caller's directory: adopted copies first (oldest `createdAt` first), then+published copies least recently used first (publication, reuse or managed+read). Unexpired pinned copies are never evicted. Onecaller's admission can thus evict another caller's unpinned copies; that callerpays a re-download on its next use and learns nothing about who caused it, andthe denial is the same code whoever's copies fill the budget. The whole plan is@@ -349,12 +358,13 @@ evicts copies or the next sweep removes expired ones.Free space is checked before the plan and again after it. Free space must coverthe block-rounded size of the new download, every active reservation and a-16 MiB margin; otherwise the admission is refused with `host_quota_exceeded`+16 MiB margin; otherwise the admission is refused with `disk_full`(reason `free_space`). The first check runs before any eviction, so a volumethat cannot hold the download costs no cached copy. A `statfs` that reports a-block size or block count that is not positive cannot size a budget; the-admission is refused the same way, as `host_quota_exceeded` with reason-`free_space`. A Host runs at most 2+block size or block count that is not positive, or a negative available-block+count, cannot size a budget; the admission is refused as `host_quota_exceeded`+with reason `free_space`, not as `disk_full`, because an unmeasurable volume is+not evidence that the disk is full. A Host runs at most 2transfers at once, and a caller at most its configured concurrency; beyond thatadmission returns `download_busy`.@@ -371,8 +381,8 @@ lost by this, because a restart already makes every copy adopted.A sweep runs when the store initializes, before every admission, and hourlyafter that. It walks `users/*/.gfs-downloads/input-*` without following-symlinks. It removes incomplete directories and expired copies that no task-pins. It never touches a directory that is an active transfer of this process,+symlinks. It removes incomplete directories and expired copies, pinned ones+included. It never touches a directory that is an active transfer of this process,and it never replaces a published copy: another directory carrying the same IDis removed. A `.gfs-downloads` that is a symlink or not a directory is removedby the sweep without following it and recreated on the next admission.@@ -426,14 +436,18 @@ after refusing to remove it` with its error code.### Retention pins and cold resumeA task that prepares or downloads a copy pins it while its model, pending-approval or execution can still use it. A pin protects the copy from expiry and-eviction and is released when the task reaches a terminal state. Pins are per-caller: another caller using the same owner ID holds a different pin. Pins are-held in memory, so after a restart a resumed task finds its copy unpinned and-not reusable, and downloads it again. A shell command never pins a copy. A pin-is not bounded by the TTL or by the task's active-time budget (a task waiting-for approval keeps its pins), which is why a caller's pinned and reserved bytes-are capped at half the budget (see Quotas and eviction).+approval or execution can still use it. A pin protects the copy from eviction+until its `expiresAt`, never beyond, and is released when the task reaches a+terminal state. Expiry is absolute: once a pinned copy expires, it no longer+counts toward its caller's protected bytes, eviction may reclaim it, and the+next sweep removes it even though the task still holds its pin. A task that+still needs the file downloads it again. Pins are per caller: another caller+using the same owner ID holds a different pin. Pins are held in memory, so after+a restart a resumed task finds its copy unpinned and not reusable, and downloads+it again. A shell command never pins a copy. A pin is not bounded by the task's+active-time budget (a task waiting for approval keeps its pins), which is why a+caller's pinned and reserved bytes are capped at half the budget (see Quotas and+eviction).### Integrity@@ -449,21 +463,63 @@ byte is sent to a model.### Errors visible to the model-| Code | Meaning |-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |-| `host_quota_exceeded` | The Host's retained bytes would exceed the volume budget and eviction cannot make room, or free space would be exceeded. |-| `download_busy` | Too many active transfers, the store is closed or closing, or no such transfer exists. |-| `download_missing` | No copy this process published for this caller has that path, or the copy failed verification. |-| `download_expired` | The copy or the transfer is past its expiry. |-| `publication_cancelled` | The task was cancelled or ran out of time while the copy was being verified or published. |-| `storage_write_failed` | A filesystem operation failed during admission, publication or removal. |-| `workspace_unavailable` | The store is not initialized, or the Host root or caller directory is not a real directory inside the Host root. |-| `caller_mismatch` | The request carries no caller identity, one that is not its caller directory's key, or a malformed retention owner ID. |+| Code | Meaning |+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------- |+| `host_quota_exceeded` | The Host's retained bytes would exceed the volume budget and eviction cannot make room, or the volume is unmeasurable. |+| `disk_full` | Free space on the Host volume cannot hold the download, every active reservation and the 16 MiB margin. |+| `limit_exceeded` | The declared size is not a non-negative integer up to `MCP_HOST_GFS_MAX_FILE_BYTES`. |+| `download_busy` | Too many active transfers, the store is closed or closing, or no such transfer exists. |+| `download_missing` | No copy this process published for this caller has that path, or the copy failed verification. |+| `download_expired` | The copy or the transfer is past its expiry. |+| `publication_cancelled` | The task was cancelled or ran out of time while the copy was being verified or published. |+| `storage_write_failed` | A filesystem operation failed during admission, publication or removal. |+| `workspace_unavailable` | The store is not initialized, or the Host root or caller directory is not a real directory inside the Host root. |+| `caller_mismatch` | The request carries no caller identity, one that is not its caller directory's key, or a malformed retention owner ID. |Another caller's download is answered with the same code and message as an IDthat does not exist (`download_missing` for reads and publication,`download_busy` for a transfer being abandoned).+### Space refusals and the guidance the model receives++The two space refusals carry a fixed guidance text so the model can tell the+user what happened and offer a cleanup through an approved `shell_exec`:++- `disk_full`: the Host workspace disk is full. The model tells the user and+ offers to list the files in the user's own workspace (the shell working+ directory, e.g. `du -sh -- * .[!.]* 2>/dev/null | sort -h`) and to delete+ what the user no longer needs with a command the user approves. It never+ lists, reads or deletes another user's directory or anything outside the+ workspace.+- `host_quota_exceeded`: the Host's cache of downloaded files is full. Space+ frees as other tasks finish and cached copies expire. The model tells the+ user, who may delete their own downloaded copies under `.gfs-downloads` in+ their workspace that no running task is using, with an approved command,+ never another user's. A task that still needs a deleted copy downloads it+ again.++An unmeasurable volume (invalid `statfs`) is refused as `host_quota_exceeded`+and therefore carries the cache guidance; the condition is not expected on a+real volume. `limit_exceeded` and every other store code carry no guidance.++Neither text names, counts or hints at whose files use the space, and neither+interpolates any value. The texts live in+`mcp-host/src/internalTools/gfsSpaceGuidance.ts` and reach the model on two+paths:++- A direct `clerum__gfs_download` (or managed `clerum__gfs_read`) call returns+ the fixed envelope `GFS download store failed (<code>)` as the first line of+ the tool error and the guidance as the second line.+- A large file reference prepared before the turn is rendered as+ `prepared_gfs_file: ... status=unavailable code=disk_full` (or+ `code=quota_exceeded`), followed once per code by a+ `For code=<code>: <guidance>` line in the turn context. Preparation accepts+ the envelope alone or the envelope followed by exactly its own guidance line;+ any other second line maps to `download_failed`.++The `free_space` metric counts `disk_full` refusals and the unmeasurable-volume+refusals described in [Quotas and eviction](#quotas-and-eviction).+### Initialization and availability`initialize()` fails only when the Host root is not a usable directorydiff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.jsonindex 9b58097a3..1c01771b4 100644--- a/mcp-host/package-lock.json+++ b/mcp-host/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-mcp-host",- "version": "0.1.543",+ "version": "0.1.544","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-mcp-host",- "version": "0.1.543",+ "version": "0.1.544","license": "SEE LICENSE IN LICENSE","dependencies": {"@anthropic-ai/sdk": "^0.32.0",diff --git a/mcp-host/package.json b/mcp-host/package.jsonindex c8cebcaa8..e38e7e197 100644--- a/mcp-host/package.json+++ b/mcp-host/package.json@@ -1,6 +1,6 @@{"name": "clerum-mcp-host",- "version": "0.1.543",+ "version": "0.1.544","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__/gfsFilePreparation.test.ts b/mcp-host/src/agent/__tests__/gfsFilePreparation.test.tsindex 40064e58d..453dddbd9 100644--- a/mcp-host/src/agent/__tests__/gfsFilePreparation.test.ts+++ b/mcp-host/src/agent/__tests__/gfsFilePreparation.test.ts@@ -10,6 +10,10 @@ import type { Conversation } from '../../core/types'import type { ToolOutput } from '../../core/types'import { GFS_FILE_LIMITS } from '../../internalTools/gfsFilePolicy'import { GFS_LOCAL_PROCESSING_GUIDANCE } from '../../internalTools/gfsReadTypes'+import {+ GFS_CACHE_FULL_GUIDANCE,+ GFS_DISK_FULL_GUIDANCE,+} from '../../internalTools/gfsSpaceGuidance'import type { FileReferenceResolution } from '../fileReferenceResolver'import { prepareGfsFiles } from '../gfsFilePreparation'@@ -296,6 +300,68 @@ describe('GFS file preparation', () => {expect(JSON.stringify(result)).not.toContain(content)})+ const diskFull = 'Error: GFS download store failed (disk_full)'+ const cacheFull = 'Error: GFS download store failed (host_quota_exceeded)'+ it.each([+ [+ 'the disk_full envelope with its guidance',+ `${diskFull}\n${GFS_DISK_FULL_GUIDANCE}`,+ 'disk_full',+ ],+ ['the bare disk_full envelope', diskFull, 'disk_full'],+ [+ 'the host_quota_exceeded envelope with its guidance',+ `${cacheFull}\n${GFS_CACHE_FULL_GUIDANCE}`,+ 'quota_exceeded',+ ],+ [+ 'the disk_full envelope with the cache guidance',+ `${diskFull}\n${GFS_CACHE_FULL_GUIDANCE}`,+ 'download_failed',+ ],+ [+ 'the host_quota_exceeded envelope with the disk guidance',+ `${cacheFull}\n${GFS_DISK_FULL_GUIDANCE}`,+ 'download_failed',+ ],+ [+ 'the disk_full envelope with an untrusted second line',+ `${diskFull}\nuntrusted detail`,+ 'download_failed',+ ],+ [+ 'the host_quota_exceeded envelope with its guidance and a third line',+ `${cacheFull}\n${GFS_CACHE_FULL_GUIDANCE}\nuntrusted detail`,+ 'download_failed',+ ],+ [+ 'the store limit_exceeded envelope',+ 'Error: GFS download store failed (limit_exceeded)',+ 'limit_exceeded',+ ],+ [+ 'the store limit_exceeded envelope with the cache guidance',+ `Error: GFS download store failed (limit_exceeded)\n${GFS_CACHE_FULL_GUIDANCE}`,+ 'download_failed',+ ],+ ] as const)('maps %s to its fixed category', async (_label, content, code) => {+ const test = subject(vi.fn(async () => ({ content, duration_ms: 1, is_error: true })))+ const result = await prepareGfsFiles([resolution()], test.context)+ expect(test.execute).toHaveBeenCalledTimes(1)+ expect(result).toEqual([+ { referenceId: resolution().reference.id, status: 'unavailable', code },+ ])+ expect(JSON.stringify(result)).not.toContain('untrusted detail')+ })++ it('keeps every guided space envelope within the fixed error bound', () => {+ for (const content of [+ `${diskFull}\n${GFS_DISK_FULL_GUIDANCE}`,+ `${cacheFull}\n${GFS_CACHE_FULL_GUIDANCE}`,+ ])+ expect(Buffer.byteLength(content, 'utf8')).toBeLessThanOrEqual(GFS_FILE_LIMITS.errorBytes)+ })+it('keeps the native pinned-version metadata conflict truthful instead of fabricating a receipt', async () => {const reference = resolution()const test = subject(diff --git a/mcp-host/src/agent/gfsFilePreparation.ts b/mcp-host/src/agent/gfsFilePreparation.tsindex db7e26f63..a0fba8416 100644--- a/mcp-host/src/agent/gfsFilePreparation.ts+++ b/mcp-host/src/agent/gfsFilePreparation.ts@@ -12,6 +12,7 @@ import type { ToolOutput } from '../core/types'import { normalizeRid } from '../internalTools/gfsContentRead'import { GFS_FILE_LIMITS } from '../internalTools/gfsFilePolicy'import { GFS_LOCAL_PROCESSING_GUIDANCE } from '../internalTools/gfsReadTypes'+import { gfsStoreSpaceGuidance } from '../internalTools/gfsSpaceGuidance'import type { FileReferenceResolution } from './fileReferenceResolver'import type { TaskExecutionBudget } from './taskExecutionBudget'@@ -47,9 +48,20 @@ function failureCode(content: string): GfsPreparationFailure {if (status === 413) return 'limit_exceeded'return 'download_failed'}+ // A store space refusal carries its fixed guidance as an exact second line;+ // any other second line is not a recognised envelope.+ const space = /^Error: GFS download store failed \((disk_full|host_quota_exceeded)\)\n/.exec(+ content+ )+ if (space) {+ const code = space[1] as 'disk_full' | 'host_quota_exceeded'+ if (content.slice(space[0].length) !== gfsStoreSpaceGuidance(code)) return 'download_failed'+ return code === 'disk_full' ? 'disk_full' : 'quota_exceeded'+ }const fixed = /^Error: GFS (?:download(?: store)?|read) failed \(([a-z_]+)\)$/.exec(content)?.[1]if (fixed === 'version_conflict') return 'stale'if (fixed === 'download_missing' || fixed === 'download_expired') return 'missing'+ if (fixed === 'disk_full') return 'disk_full'if (fixed === 'host_quota_exceeded') return 'quota_exceeded'if (fixed === 'workspace_unavailable') return 'workspace_unavailable'if (fixed === 'limit_exceeded') return 'limit_exceeded'diff --git a/mcp-host/src/core/orchestration/__tests__/turnContext.test.ts b/mcp-host/src/core/orchestration/__tests__/turnContext.test.tsindex efc7c3d57..fe861db8f 100644--- a/mcp-host/src/core/orchestration/__tests__/turnContext.test.ts+++ b/mcp-host/src/core/orchestration/__tests__/turnContext.test.ts@@ -1,9 +1,14 @@import { describe, expect, it } from 'vitest'import type { FileReferenceV1 } from '@clerum/gfs-interaction-policy'import { GFS_LOCAL_PROCESSING_GUIDANCE } from '../../../internalTools/gfsReadTypes'+import {+ GFS_CACHE_FULL_GUIDANCE,+ GFS_DISK_FULL_GUIDANCE,+} from '../../../internalTools/gfsSpaceGuidance'import type { Attachment } from '../../types'import {ATTACHED_FILES_INSTRUCTION,+ type GfsPreparationFailure,PREPARED_GFS_FILES_INSTRUCTION,type PreparedGfsFile,REFERENCED_FILES_INSTRUCTION,@@ -76,6 +81,92 @@ describe('prepared GFS receipts', () => {expect(block).not.toContain('receipt=')expect(block).not.toContain('.gfs-downloads/')})++ const unavailable = (code: GfsPreparationFailure, referenceId = file.referenceId) =>+ buildTurnContextBlock({+ date: new Date('2026-10-02T00:00:00Z'),+ channel: { type: 'rpc', sender: 'caller-alice' },+ preparedGfsFiles: [{ referenceId, status: 'unavailable', code }],+ })++ it('tells the model the workspace disk is full and to offer a cleanup of the caller workspace only', () => {+ const block = unavailable('disk_full')+ expect(block).toContain('status=unavailable code=disk_full')+ expect(block).toContain(`For code=disk_full: ${GFS_DISK_FULL_GUIDANCE}`)+ expect(GFS_DISK_FULL_GUIDANCE).toContain('workspace disk is full')+ expect(GFS_DISK_FULL_GUIDANCE).toContain('Tell the user')+ expect(GFS_DISK_FULL_GUIDANCE).toContain('du -sh -- * .[!.]* 2>/dev/null | sort -h')+ expect(GFS_DISK_FULL_GUIDANCE).toContain('shell_exec command they approve')+ expect(GFS_DISK_FULL_GUIDANCE).toContain(+ "Never list, read or delete another user's directory or anything outside the workspace."+ )+ expect(block).not.toContain(GFS_CACHE_FULL_GUIDANCE)+ expect(block.split('\n').filter(line => line.includes(GFS_DISK_FULL_GUIDANCE))).toHaveLength(1)+ })++ it('tells the model the download cache is full and that only the caller may delete its own copies', () => {+ const block = unavailable('quota_exceeded')+ expect(block).toContain('status=unavailable code=quota_exceeded')+ expect(block).toContain(`For code=quota_exceeded: ${GFS_CACHE_FULL_GUIDANCE}`)+ expect(GFS_CACHE_FULL_GUIDANCE).toContain("Host's cache of downloaded files is full")+ expect(GFS_CACHE_FULL_GUIDANCE).toContain('cached copies expire')+ expect(GFS_CACHE_FULL_GUIDANCE).toContain('Tell the user')+ expect(GFS_CACHE_FULL_GUIDANCE).toContain('under .gfs-downloads in their workspace')+ expect(GFS_CACHE_FULL_GUIDANCE).toContain('that no running task is using')+ expect(GFS_CACHE_FULL_GUIDANCE).toContain(+ 'a task that still needs a deleted copy downloads it again'+ )+ expect(GFS_CACHE_FULL_GUIDANCE).toContain("Never delete another user's copies.")+ expect(block).not.toContain(GFS_DISK_FULL_GUIDANCE)+ expect(block.split('\n').filter(line => line.includes(GFS_CACHE_FULL_GUIDANCE))).toHaveLength(1)+ })++ it('keeps the two space guidances distinct from each other', () => {+ expect(GFS_DISK_FULL_GUIDANCE).not.toContain('cache')+ expect(GFS_DISK_FULL_GUIDANCE).not.toContain('.gfs-downloads')+ expect(GFS_CACHE_FULL_GUIDANCE).not.toContain('disk is full')+ expect(GFS_CACHE_FULL_GUIDANCE).not.toContain('du -sh')+ })++ it('names no caller, foreign path or count in either space guidance', () => {+ for (const guidance of [GFS_DISK_FULL_GUIDANCE, GFS_CACHE_FULL_GUIDANCE]) {+ // The only digit is the stderr redirect of the suggested listing command.+ expect(guidance.replace('2>/dev/null', '')).not.toMatch(/\d/)+ expect(guidance).not.toMatch(/caller-|@|\/home|\/workspace|\/users\//i)+ expect(guidance).not.toMatch(/[0-9a-f]{8}-[0-9a-f]{4}-/)+ }+ const block = unavailable('disk_full') + unavailable('quota_exceeded')+ // Witness: the sender is in the block, but never inside a guidance line.+ expect(block).toContain('sender: caller-alice')+ for (const line of block.split('\n').filter(line => line.startsWith('For code=')))+ expect(line).not.toContain('caller-alice')+ })++ it('adds each space guidance once for several refusals and none for other codes', () => {+ const block = buildTurnContextBlock({+ date: new Date('2026-10-02T00:00:00Z'),+ channel: { type: 'rpc' },+ preparedGfsFiles: [+ { referenceId: 'gfs:main:a@v1', status: 'unavailable', code: 'disk_full' },+ { referenceId: 'gfs:main:b@v1', status: 'unavailable', code: 'disk_full' },+ { referenceId: 'gfs:main:c@v1', status: 'unavailable', code: 'quota_exceeded' },+ ],+ })+ expect(block.split('\n').filter(line => line.startsWith('For code=disk_full: '))).toHaveLength(+ 1+ )+ expect(+ block.split('\n').filter(line => line.startsWith('For code=quota_exceeded: '))+ ).toHaveLength(1)++ const other = unavailable('approval_required')+ // Witness: the unavailable line and the instruction were rendered.+ expect(other).toContain('status=unavailable code=approval_required')+ expect(other).toContain(PREPARED_GFS_FILES_INSTRUCTION)+ expect(other).not.toContain('For code=')+ expect(other).not.toContain(GFS_DISK_FULL_GUIDANCE)+ expect(other).not.toContain(GFS_CACHE_FULL_GUIDANCE)+ })})describe('buildTurnContextBlock (T2.2)', () => {diff --git a/mcp-host/src/core/orchestration/turnContext.ts b/mcp-host/src/core/orchestration/turnContext.tsindex 90664936d..426ed1a1d 100644--- a/mcp-host/src/core/orchestration/turnContext.ts+++ b/mcp-host/src/core/orchestration/turnContext.ts@@ -22,6 +22,10 @@*/import { quotePromptValue } from '@clerum/gfs-interaction-policy'import type { GfsDownloadReceipt } from '../../internalTools/gfsDownloadStore'+import {+ GFS_CACHE_FULL_GUIDANCE,+ GFS_DISK_FULL_GUIDANCE,+} from '../../internalTools/gfsSpaceGuidance'import type { Attachment } from '../types'export interface TurnContextChannel {@@ -98,6 +102,9 @@ export type GfsPreparationFailure =| 'unauthenticated'| 'stale'| 'missing'+ /** The Host workspace disk has no room for the download. */+ | 'disk_full'+ /** The Host's cache of downloaded files has no room for the download. */| 'quota_exceeded'| 'limit_exceeded'| 'timeout'@@ -198,6 +205,13 @@ export function buildTurnContextBlock(input: TurnContextInput): string {)}lines.push(PREPARED_GFS_FILES_INSTRUCTION)+ // Fixed text, once per code: it names no file, size or owner.+ const codes = new Set(+ input.preparedGfsFiles.map(file => (file.status === 'unavailable' ? file.code : undefined))+ )+ if (codes.has('disk_full')) lines.push(`For code=disk_full: ${GFS_DISK_FULL_GUIDANCE}`)+ if (codes.has('quota_exceeded'))+ lines.push(`For code=quota_exceeded: ${GFS_CACHE_FULL_GUIDANCE}`)}return `<turn-context>\n${lines.join('\n')}\n</turn-context>\n\n`}diff --git a/mcp-host/src/internalTools/gfs.ts b/mcp-host/src/internalTools/gfs.tsindex 58c48fce9..56637d354 100644--- a/mcp-host/src/internalTools/gfs.ts+++ b/mcp-host/src/internalTools/gfs.ts@@ -27,6 +27,7 @@ import {type GfsFileContent,type GfsReadOptions,} from './gfsReadTypes'+import { gfsStoreSpaceGuidance } from './gfsSpaceGuidance'import { decodeTextContent } from './textContent'/**@@ -89,10 +90,19 @@ function ok(content: unknown): InternalToolResult {// Read failures get the same redaction floor as mutations (see mutationFail):// only gfsc's HTTP status and a coarse public category may reach the model —// never the response body, which could carry paths or server internals.+// A store space refusal keeps its fixed envelope as the first line and adds the+// fixed guidance for its code as a second line; gfsFilePreparation accepts that+// exact second line and nothing else.function fail(error: unknown): InternalToolResult {if (error instanceof VisualInputError) return { success: false, error: error.message }- if (error instanceof GfsDownloadError || error instanceof GfsDownloadStoreError)- return { success: false, error: error.message }+ if (error instanceof GfsDownloadStoreError) {+ const guidance = gfsStoreSpaceGuidance(error.code)+ return {+ success: false,+ error: guidance === undefined ? error.message : `${error.message}\n${guidance}`,+ }+ }+ if (error instanceof GfsDownloadError) return { success: false, error: error.message }return redactedFail('GFS read failed', error)}diff --git a/mcp-host/src/internalTools/gfsDownloadStore.test.ts b/mcp-host/src/internalTools/gfsDownloadStore.test.tsindex 588df37b1..817e70022 100644--- a/mcp-host/src/internalTools/gfsDownloadStore.test.ts+++ b/mcp-host/src/internalTools/gfsDownloadStore.test.ts@@ -543,7 +543,7 @@ describe('GFS download store: quotas and eviction', () => {const denied = await quotaCount('host', 'free_space')await expect(startTransfer(store, callerRoot, CALLER, 51, 4096)).rejects.toMatchObject({- code: 'host_quota_exceeded',+ code: 'disk_full',})expect(statfsBoundary).toHaveBeenCalled()expect(await quotaCount('host', 'free_space')).toBe(denied + 1)@@ -580,7 +580,7 @@ describe('GFS download store: quotas and eviction', () => {statfsBoundary.mockClear()lstatBoundary.mockClear()await expect(startTransfer(limited, callerRoot, CALLER, 70, 11)).rejects.toMatchObject({- code: 'host_quota_exceeded',+ code: 'limit_exceeded',})expect(statfsBoundary).not.toHaveBeenCalled()expect(lstatBoundary).not.toHaveBeenCalled()@@ -656,21 +656,23 @@ describe('GFS download store: sweep', () => {await expect(store.readManagedFile(kept.receipt.path, CALLER)).resolves.toEqual(kept.bytes)})- it('F17: the sweep removes expired complete downloads unless pinned', async () => {+ it('F17: the sweep removes expired complete downloads, pinned or not', async () => {const pinned = await completedCopy(store, callerRoot, CALLER, 100, 8, { owner: 'task-100' })const loose = await completedCopy(store, callerRoot, CALLER, 101, 8)const later = Date.now() + 2 * 60 * 60_000+ // Witness: before expiry the same sweep keeps both.+ await expect(store.cleanupExpired()).resolves.toMatchObject({ removedExpired: 0 })+ expect(await exists(downloadDirectory(callerRoot, loose.receipt.id))).toBe(true)+ expect(await exists(downloadDirectory(callerRoot, pinned.receipt.id))).toBe(true)++ // Expiry is absolute (Addendum 10): the open pin does not keep its copy.await expect(store.cleanupExpired(later)).resolves.toEqual({- removedExpired: 1,+ removedExpired: 2,removedIncomplete: 0,removeFailed: 0,})expect(await exists(downloadDirectory(callerRoot, loose.receipt.id))).toBe(false)- expect(await exists(downloadDirectory(callerRoot, pinned.receipt.id))).toBe(true)-- await store.releaseReceiptOwner('task-100', CALLER)- await expect(store.cleanupExpired(later)).resolves.toMatchObject({ removedExpired: 1 })expect(await exists(downloadDirectory(callerRoot, pinned.receipt.id))).toBe(false)})@@ -875,23 +877,21 @@ describe('GFS download store: managed reads', () => {})describe('GFS download store: pins, lifecycle and errors', () => {- it('F24: releaseReceiptOwner unpins only its own caller and a second store on the same root sees no pins', async () => {+ // Expiry no longer observes pins (Addendum 10): which caller a release+ // unpins, and that a second store holds no pins, are proven against the+ // protected-bytes cap in gfsDownloadStoreProtected.test.ts.+ it('F24: releaseReceiptOwner accepts an unknown owner and another caller owner id without removing any copy', async () => {const pinned = await completedCopy(store, callerRoot, CALLER, 130, 8, { owner: 'task-130' })const rootB = await callerDirectory(hostRoot, 'caller-b')// The same owner id under another caller is another pin, not a refusal.const other = await completedCopy(store, rootB, 'caller-b', 131, 8, { owner: 'task-130' })- const later = Date.now() + 2 * 60 * 60_000await expect(store.releaseReceiptOwner('unknown-owner', CALLER)).resolves.toBeUndefined()await expect(store.releaseReceiptOwner('task-130', 'caller-b')).resolves.toBeUndefined()- // Witness: caller-b's release freed only caller-b's copy; CALLER's pin holds.- await expect(store.cleanupExpired(later)).resolves.toMatchObject({ removedExpired: 1 })- expect(await exists(downloadDirectory(rootB, other.receipt.id))).toBe(false)- expect(await exists(downloadDirectory(callerRoot, pinned.receipt.id))).toBe(true)-- await store.close()- const second = await openStore(hostRoot)- await expect(second.cleanupExpired(later)).resolves.toMatchObject({ removedExpired: 1 })- expect(await exists(downloadDirectory(callerRoot, pinned.receipt.id))).toBe(false)+ // A release only unpins: both copies stay readable by their callers.+ await expect(store.readManagedFile(pinned.receipt.path, CALLER)).resolves.toEqual(pinned.bytes)+ await expect(store.readManagedFile(other.receipt.path, 'caller-b')).resolves.toEqual(+ other.bytes+ )})it('F25: close drains active transfers and refuses new admissions', async () => {diff --git a/mcp-host/src/internalTools/gfsDownloadStore.ts b/mcp-host/src/internalTools/gfsDownloadStore.tsindex 9fad21f9e..51daa6740 100644--- a/mcp-host/src/internalTools/gfsDownloadStore.ts+++ b/mcp-host/src/internalTools/gfsDownloadStore.ts@@ -53,10 +53,18 @@ const SHA256_RE = /^[0-9a-f]{64}$/export type GfsDownloadStoreErrorCode =| 'caller_mismatch'+ /** The Host volume's free space cannot hold the reservation plus its margin. */+ | 'disk_full'| 'download_busy'| 'download_expired'| 'download_missing'+ /**+ * The retained-download budget or one caller's protected share of it is+ * full, or the volume cannot be measured.+ */| 'host_quota_exceeded'+ /** The declared size is not a safe non-negative integer up to the file limit. */+ | 'limit_exceeded'| 'publication_cancelled'| 'storage_write_failed'| 'workspace_unavailable'@@ -490,7 +498,7 @@ export class GfsDownloadStore {input.sizeBytes < 0 ||input.sizeBytes > GFS_FILE_LIMITS.maxFileBytes)- throw new GfsDownloadStoreError('host_quota_exceeded')+ throw new GfsDownloadStoreError('limit_exceeded')if (typeof input.callerIdentity !== 'string' || input.callerIdentity.length === 0)throw new GfsDownloadStoreError('caller_mismatch')if (!isValidSource(input.source)) throw new RangeError('GFS download source is malformed')@@ -770,8 +778,12 @@ export class GfsDownloadStore {if (!entry) return undefined// Pinning a copy this caller does not protect yet adds it to the// caller's protected bytes; checked before hashing, so a refusal costs- // no read.- if (bounds?.retentionOwnerId !== undefined)+ // no read. A copy the caller already protects adds nothing, so that is+ // decided first and re-pinning it never depends on statfs.+ if (+ bounds?.retentionOwnerId !== undefined &&+ !this.protectedIds(callerIdentity).has(entry.id)+ )this.assertProtectedRoom(callerIdentity, retainedBudget(await this.measureVolume()), {id: entry.id,sizeBytes: entry.sizeBytes,@@ -985,8 +997,11 @@ export class GfsDownloadStore {/*** Walks `users/*\/.gfs-downloads/*` plus every indexed directory. Incomplete- * directories and expired, unpinned complete ones are removed; complete ones- * are (re)indexed, new ones as adopted. Active transfers of this process are+ * directories and expired complete ones are removed; complete ones are+ * (re)indexed, new ones as adopted. Expiry is absolute: a retention pin+ * protects a copy from eviction, never past its `expiresAt`, so a pinned+ * copy is removed at expiry like any other and a task that still needs the+ * file downloads it again. Active transfers of this process are* never touched, and a published entry is never replaced: another directory* carrying the id of a reservation or of a published copy is removed, and an* id found in several directories with neither is removed everywhere (a@@ -1021,9 +1036,11 @@ export class GfsDownloadStore {}// A duplicate this sweep could not remove is still on disk, so it stays// charged: a failed cleanup never turns into free capacity. Its charge is- // released only by a removal that succeeds or an lstat that answers- // ENOENT; an inspection or listing that fails carries the previous- // sweep's charge over instead of reading as zero.+ // released only by a removal that succeeds or an lstat that proves the+ // directory gone: ENOENT, ENOTDIR (a parent is no longer a directory) or+ // a path that is no longer a directory. An inspection or listing that+ // fails, or any other lstat answer, carries the previous sweep's charge+ // over instead of reading as zero.const previousHeld = this.heldconst held = new Map<string, HeldCopy>()const settled = new Set<string>()@@ -1081,7 +1098,7 @@ export class GfsDownloadStore {continue}const entry = state.entry- if (Date.parse(entry.expiresAt) <= now && !this.isPinned(id)) {+ if (Date.parse(entry.expiresAt) <= now) {const result = await this.removeDirectory(directory, 'expired_removed')if (result === 'removed') totals.removedExpired += 1if (result === 'failed') totals.removeFailed += 1@@ -1439,7 +1456,9 @@ export class GfsDownloadStore {/*** A statfs whose block size or block count is not positive cannot size- * anything; it refuses the admission as `free_space`, like a full volume.+ * anything; it records `free_space` but keeps `host_quota_exceeded`, because+ * an unmeasurable volume is not proof that the disk is full, and `disk_full`+ * tells the model to offer the user a workspace cleanup.*/private async measureVolume(): Promise<VolumeSpace> {const space = await fs.statfs(this.hostRoot, { bigint: true })@@ -1462,31 +1481,41 @@ export class GfsDownloadStore {for (const transfer of this.active.values()) required += reserve(transfer.sizeBytes)if (space.bavail * space.bsize < required) {recordGfsDownloadQuota('host', 'free_space')- throw new GfsDownloadStoreError('host_quota_exceeded')+ throw new GfsDownloadStoreError('disk_full')}return space}/*** Ids one caller holds out of eviction: its active reservations and the- * copies its retention owners pin, each id once.+ * unexpired copies its retention owners pin, each id once. An expired+ * pinned copy protects nothing: the sweep and eviction both remove it.*/private protectedIds(callerIdentity: string): Set<string> {const ids = new Set<string>()+ const now = Date.now()for (const transfer of this.active.values())if (transfer.callerIdentity === callerIdentity) ids.add(transfer.id)for (const [key, pinned] of this.pins)if ((JSON.parse(key) as [string, string])[0] === callerIdentity)- for (const id of pinned) ids.add(id)+ for (const id of pinned) {+ const entry = this.entries.get(id)+ if (entry !== undefined && Date.parse(entry.expiresAt) <= now) continue+ ids.add(id)+ }return ids}/**- * Eviction never reclaims a pinned copy or a reservation, so without a bound- * one caller's open tasks could hold the whole budget and refuse every other- * caller. A caller's protected bytes may therefore reach at most half the- * budget, which always leaves the other half reclaimable for anyone else.- * Only this caller's own usage decides; the refusal is the fixed code.+ * Eviction never reclaims an unexpired pinned copy or a reservation, so+ * without a bound one caller's open tasks could hold the whole budget and+ * refuse every other caller. One caller's protected bytes may therefore+ * reach at most half the budget. That bounds each caller, not their sum:+ * several callers together can protect the whole budget, and then every+ * positive-size admission is refused until protection is released or the+ * pinned copies expire (expiry is absolute, so the retention window bounds+ * that state). Only this caller's own usage decides; the refusal is the+ * fixed code.*/private assertProtectedRoom(callerIdentity: string,@@ -1522,7 +1551,9 @@ export class GfsDownloadStore {/*** Completed, unpinned copies are a cache, whoever downloaded them: one* caller's admission may evict another caller's copy, which costs that- * caller a re-download and reveals nothing. The whole eviction plan is+ * caller a re-download and reveals nothing. A pinned copy past its expiry+ * is evictable too; the admission sweep normally removes it first, so this+ * matters when that sweep could not inspect it. The whole eviction plan is* computed before anything is deleted: adopted copies first, so files* planted in one directory can never cost another caller a copy this* process published, then published copies least recently used first.@@ -1533,8 +1564,9 @@ export class GfsDownloadStore {*/private async reclaimForAdmission(sizeBytes: number, budget: bigint): Promise<void> {if (!this.overBudget(sizeBytes, budget)) return+ const now = Date.now()const candidates = [...this.entries.values()]- .filter(entry => !this.isPinned(entry.id))+ .filter(entry => !this.isPinned(entry.id) || Date.parse(entry.expiresAt) <= now).sort(evictionOrder)const plan = new Set<string>()for (const candidate of candidates) {diff --git a/mcp-host/src/internalTools/gfsDownloadStoreBoundaries.test.ts b/mcp-host/src/internalTools/gfsDownloadStoreBoundaries.test.tsindex 44d32264c..5dec6e8a2 100644--- a/mcp-host/src/internalTools/gfsDownloadStoreBoundaries.test.ts+++ b/mcp-host/src/internalTools/gfsDownloadStoreBoundaries.test.ts@@ -379,7 +379,7 @@ describe('GFS download store boundaries: quota and capacity', () => {const denied = await quotaCount('host', 'free_space')await expect(startTransfer(store, rootA, A, 320, size)).rejects.toMatchObject({- code: 'host_quota_exceeded',+ code: 'disk_full',})expect(await quotaCount('host', 'free_space')).toBe(denied + 1)@@ -803,7 +803,10 @@ describe('GFS download store boundaries: caller isolation', () => {)})- it('U4: an owner id another caller pins is neither refused nor released across callers', async () => {+ // Expiry no longer observes pins (Addendum 10): that B's release leaves A's+ // pin under the same owner id in place is proven against the+ // protected-bytes cap in gfsDownloadStoreProtected.test.ts.+ it('U4: an owner id another caller pins is not refused, and releasing it twice is a no-op', async () => {const pinnedA = await completedCopy(store, rootA, A, 73, 8, { owner: 'task-73' })const pinnedB = await completedCopy(store, rootB, B, 74, 8, { owner: 'task-73' })const reused = await store.reusableReceipt(B, sourceFor(74), 8, { retentionOwnerId: 'task-73' })@@ -811,12 +814,9 @@ describe('GFS download store boundaries: caller isolation', () => {await expect(store.releaseReceiptOwner('task-73', B)).resolves.toBeUndefined()await expect(store.releaseReceiptOwner('task-73', B)).resolves.toBeUndefined()- const later = Date.parse(pinnedA.receipt.expiresAt) + HOUR-- // Witness: B's release freed B's copy only; A's pin still holds A's.- await expect(store.cleanupExpired(later)).resolves.toMatchObject({ removedExpired: 1 })- expect(exists(downloadDirectory(rootB, pinnedB.receipt.id))).toBe(false)- expect(exists(downloadDirectory(rootA, pinnedA.receipt.id))).toBe(true)+ // A release only unpins: both copies stay readable by their callers.+ await expect(store.readManagedFile(pinnedA.receipt.path, A)).resolves.toEqual(pinnedA.bytes)+ await expect(store.readManagedFile(pinnedB.receipt.path, B)).resolves.toEqual(pinnedB.bytes)})})diff --git a/mcp-host/src/internalTools/gfsDownloadStoreBudget.test.ts b/mcp-host/src/internalTools/gfsDownloadStoreBudget.test.tsindex 15b530d34..17e65fe4c 100644--- a/mcp-host/src/internalTools/gfsDownloadStoreBudget.test.ts+++ b/mcp-host/src/internalTools/gfsDownloadStoreBudget.test.ts@@ -200,6 +200,95 @@ describe('GFS download store budget: share of the workspace volume', () => {})})+describe('GFS download store budget: a full disk and a full cache are distinct refusals', () => {+ it('DSK-1: a full disk refuses as disk_full while a full budget still refuses as host_quota_exceeded', async () => {+ // Budget floor(20 * 85 / 100) = 17; A and B pin 8 each, so 2 more bytes+ // exceed the budget while 1 more fits.+ volumeOf(20n)+ const store = await openStore()+ const C = 'caller-c'+ const rootC = callerDirectory(hostRoot, C)+ await completedCopy(store, rootA, A, 40, 8, { owner: 'task-a' })+ await completedCopy(store, rootB, B, 41, 8, { owner: 'task-b' })+ const budgetDenied = await quotaCount('host', 'storage_bytes')+ const diskDenied = await quotaCount('host', 'free_space')++ await expect(startTransfer(store, rootC, C, 42, 2)).rejects.toMatchObject({+ code: 'host_quota_exceeded',+ })+ expect(await quotaCount('host', 'storage_bytes')).toBe(budgetDenied + 1)+ expect(await quotaCount('host', 'free_space')).toBe(diskDenied)++ // The same volume with one byte less than the 16 MiB margin plus the request.+ statfsBoundary.mockImplementation(async (target: string) => ({+ ...(await nativeFs.statfs(target, { bigint: true })),+ bsize: 1n,+ blocks: 20n,+ bavail: 16n * BigInt(MIB),+ }))+ await expect(startTransfer(store, rootC, C, 43, 1)).rejects.toMatchObject({+ code: 'disk_full',+ message: 'GFS download store failed (disk_full)',+ })+ expect(await quotaCount('host', 'free_space')).toBe(diskDenied + 1)+ expect(await quotaCount('host', 'storage_bytes')).toBe(budgetDenied + 1)++ // Witness: with the real free space the same request fits the budget.+ volumeOf(20n)+ await expect(startTransfer(store, rootC, C, 43, 1)).resolves.toBeDefined()+ })++ it('DSK-2: statfs reporting a negative available-block count keeps host_quota_exceeded, not disk_full', async () => {+ const store = await openStore()+ const observed = await nativeFs.statfs(hostRoot, { bigint: true })+ statfsBoundary.mockResolvedValue({ ...observed, bavail: -1n })+ const denied = await quotaCount('host', 'free_space')++ const refusal = await startTransfer(store, rootA, A, 44, 4).catch((error: unknown) => error)+ expect(refusal).toBeInstanceOf(GfsDownloadStoreError)+ expect((refusal as GfsDownloadStoreError).code).toBe('host_quota_exceeded')+ expect(await quotaCount('host', 'free_space')).toBe(denied + 1)++ // Witness: the real statfs admits the same request.+ statfsBoundary.mockImplementation(nativeFs.statfs)+ await expect(startTransfer(store, rootA, A, 44, 4)).resolves.toBeDefined()+ })++ it.each([+ { name: 'one byte above the file limit', size: 11 },+ { name: 'a negative size', size: -1 },+ { name: 'a fractional size', size: 1.5 },+ ])('DSK-3: $name is refused as limit_exceeded without a space metric', async ({ size }) => {+ // Budget 850 bytes, so only the 10-byte file limit can refuse.+ volumeOf(1000n)+ const store = await limitedStore({ MCP_HOST_GFS_MAX_FILE_BYTES: '10' })+ const budgetDenied = await quotaCount('host', 'storage_bytes')+ const diskDenied = await quotaCount('host', 'free_space')+ statfsBoundary.mockClear()++ // Called directly: the kit's helper allocates the bytes before admission.+ const refused = store.createTransfer({+ callerIdentity: A,+ callerWorkspacePath: rootA,+ source: sourceFor(45),+ sizeBytes: size,+ expiresAt: new Date(Date.now() + 60 * 60_000).toISOString(),+ })+ await expect(refused).rejects.toMatchObject({+ code: 'limit_exceeded',+ message: 'GFS download store failed (limit_exceeded)',+ })+ expect(await quotaCount('host', 'storage_bytes')).toBe(budgetDenied)+ expect(await quotaCount('host', 'free_space')).toBe(diskDenied)+ expect(statfsBoundary).not.toHaveBeenCalled()++ // Witness: a size exactly at the file limit is admitted and measured.+ const admitted = await startTransfer(store, rootA, A, 45, 10)+ expect(admitted.transfer.sizeBytes).toBe(10)+ expect(statfsBoundary).toHaveBeenCalled()+ })+})+describe('GFS download store budget: no per-caller storage or file-count limit', () => {it('BUD-6: one caller fills the whole budget with 18 files of 16 MiB and another caller evicts its least recently used copy', async () => {const size = 16 * MIBdiff --git a/mcp-host/src/internalTools/gfsDownloadStoreProtected.test.ts b/mcp-host/src/internalTools/gfsDownloadStoreProtected.test.tsindex 890746f92..12e8009f3 100644--- a/mcp-host/src/internalTools/gfsDownloadStoreProtected.test.ts+++ b/mcp-host/src/internalTools/gfsDownloadStoreProtected.test.ts@@ -5,6 +5,10 @@* budget. Unpinned copies still use the whole budget. Ported from the final* review's SOL-R3-PINS repro. A 100-byte volume at the default 85% gives a* budget of 85 and a per-caller protected cap of floor(85 / 2) = 42.+ *+ * Addendum 10: expiry is absolute. A pin protects a copy from eviction, never+ * past its `expiresAt`: the sweep removes an expired pinned copy, it stops+ * counting toward its caller's cap, and eviction may reclaim it.*/import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'import * as syncFs from 'node:fs'@@ -22,12 +26,22 @@ import {} from '../__tests__/fixtures/gfsStoreTestKit'import { GfsDownloadStore, GfsDownloadStoreError } from './gfsDownloadStore'-const { statfsBoundary } = vi.hoisted(() => ({ statfsBoundary: vi.fn() }))+const { statfsBoundary, lstatBoundary } = vi.hoisted(() => ({+ statfsBoundary: vi.fn(),+ lstatBoundary: vi.fn(),+}))vi.mock('node:fs/promises', async original => ({...(await original<typeof fs>()),statfs: statfsBoundary,+ lstat: lstatBoundary,}))+const HOUR_MS = 60 * 60 * 1000++function ioError(code: string): NodeJS.ErrnoException {+ return Object.assign(new Error(`${code}: injected by the test`), { code })+}+const A = 'caller-a'const B = 'caller-b'const C = 'caller-c'@@ -75,6 +89,10 @@ beforeEach(async () => {const real = await nativeFs.statfs(target, { bigint: true })return { ...real, bsize: 1n, blocks: 100n, bavail: real.bavail * real.bsize }})+ lstatBoundary.mockReset()+ lstatBoundary.mockImplementation((...args: unknown[]) =>+ (nativeFs.lstat as (...forwarded: unknown[]) => Promise<unknown>)(...args)+ )hostRoot = syncFs.mkdtempSync(path.join(tmpdir(), 'gfs-store-protected-'))rootA = callerDirectory(hostRoot, A)rootB = callerDirectory(hostRoot, B)@@ -103,11 +121,10 @@ describe('GFS download store: a caller protects at most half the budget (R3-F1)'expect(await protectedRefusals()).toBe(protectedBefore + 1)expect(await hostRefusals()).toBe(hostBefore)- // The repro's denial: B and C are admitted, before and after expiry.+ // The repro's denial: B and C are admitted while A holds its cap. Expiry+ // of pinned copies is covered by the absolute-retention tests below.const b = await startTransfer(store, rootB, B, 10, 1)await store.fail(b.transfer.id, B)- vi.setSystemTime(Date.now() + 8 * 24 * 60 * 60 * 1000)- expect((await store.cleanupExpired()).removedExpired).toBe(0)const c = await startTransfer(store, rootC, C, 11, 1)await store.fail(c.transfer.id, C)for (const receipt of pinned) expect(exists(downloadDirectory(rootA, receipt.id))).toBe(true)@@ -217,15 +234,198 @@ describe('GFS download store: a caller protects at most half the budget (R3-F1)'it('a file larger than the cap is refused before any eviction', async () => {const store = await openStore()- const other = await completedCopy(store, rootB, B, 0, 5)+ // B holds 80 unpinned bytes, so A's 43 bytes would need eviction: a cap+ // check placed after reclaimForAdmission would delete B's copies first.+ const others = await copies(store, rootB, B, 0, 16)+ const before = await protectedRefusals()++ await expect(startTransfer(store, rootA, A, 100, 43)).rejects.toMatchObject({+ code: 'host_quota_exceeded',+ })+ expect(await protectedRefusals()).toBe(before + 1)+ for (const receipt of others) expect(exists(downloadDirectory(rootB, receipt.id))).toBe(true)+ const admitted = await startTransfer(store, rootA, A, 101, 42)+ await store.fail(admitted.transfer.id, A)+ expect(await protectedRefusals()).toBe(before + 1)+ })++ it('SOL-R4-ORDER: a caller at its cap is refused before eviction, so a full budget keeps the other caller copies', async () => {+ const store = await openStore()+ // B first: 43 unpinned bytes. Then A pins 42, the cap: 85 of 85.+ const others = [+ ...(await copies(store, rootB, B, 0, 8)),+ (await completedCopy(store, rootB, B, 8, 3)).receipt,+ ]+ await copies(store, rootA, A, 20, 8, 'task-a')+ await completedCopy(store, rootA, A, 28, 2, { owner: 'task-a' })const before = await protectedRefusals()- await expect(startTransfer(store, rootA, A, 1, 43)).rejects.toMatchObject({+ await expect(startTransfer(store, rootA, A, 30, 1)).rejects.toMatchObject({code: 'host_quota_exceeded',})expect(await protectedRefusals()).toBe(before + 1)- expect(exists(downloadDirectory(rootB, other.receipt.id))).toBe(true)- const admitted = await startTransfer(store, rootA, A, 2, 42)+ for (const receipt of others) expect(exists(downloadDirectory(rootB, receipt.id))).toBe(true)++ // Releasing A's owner unpins its 42 bytes: the same byte is admitted.+ await store.releaseReceiptOwner('task-a', A)+ const admitted = await startTransfer(store, rootA, A, 31, 1)await store.fail(admitted.transfer.id, A)+ expect(await protectedRefusals()).toBe(before + 1)+ })+})++describe('GFS download store: retention pins never outlive expiresAt (Addendum 10)', () => {+ it('the sweep removes a pinned copy once it is past its expiry', async () => {+ const store = await openStore()+ const pinned = await completedCopy(store, rootA, A, 0, 10, { owner: 'task-a' })+ const directory = downloadDirectory(rootA, pinned.receipt.id)++ // Witness: before expiry the same sweep keeps the pinned copy readable.+ expect((await store.cleanupExpired()).removedExpired).toBe(0)+ expect(exists(directory)).toBe(true)+ await expect(store.readManagedFile(pinned.receipt.path, A)).resolves.toEqual(pinned.bytes)++ // Past expiresAt, the owner still open: removed anyway.+ vi.setSystemTime(Date.now() + 2 * HOUR_MS)+ expect((await store.cleanupExpired()).removedExpired).toBe(1)+ expect(exists(directory)).toBe(false)+ await expect(store.readManagedFile(pinned.receipt.path, A)).rejects.toMatchObject({+ code: 'download_missing',+ })+ })++ it('an expired pinned copy stops counting toward its caller cap without releasing the owner', async () => {+ const store = await openStore()+ // A 20-byte unpinned copy that lives a day (first: its open reservation+ // beside 30 pinned bytes would itself exceed the cap), then 30 pinned+ // bytes expiring in one hour. Pinning the first one would make 50.+ const lasting = await completedCopy(store, rootA, A, 1, 20, {+ expiresAt: new Date(Date.now() + 24 * HOUR_MS).toISOString(),+ })+ await completedCopy(store, rootA, A, 0, 30, { owner: 'task-a' })+ const before = await protectedRefusals()+ await expect(+ store.reusableReceipt(A, sourceFor(1), 20, { retentionOwnerId: 'task-b' })+ ).rejects.toMatchObject({ code: 'host_quota_exceeded' })+ expect(await protectedRefusals()).toBe(before + 1)++ // Two hours later, with no sweep between and task-a never released, the+ // expired 30 bytes protect nothing: the same pin is admitted.+ vi.setSystemTime(Date.now() + 2 * HOUR_MS)+ await expect(+ store.reusableReceipt(A, sourceFor(1), 20, { retentionOwnerId: 'task-b' })+ ).resolves.toMatchObject({ id: lasting.receipt.id })+ expect(await protectedRefusals()).toBe(before + 1)++ // A new reservation is admitted under the cap as well: 20 + 22 = 42.+ const admitted = await startTransfer(store, rootA, A, 2, 22)+ await store.fail(admitted.transfer.id, A)+ expect(await protectedRefusals()).toBe(before + 1)+ })++ it('eviction reclaims an expired pinned copy the admission sweep could not inspect, and keeps unexpired pins', async () => {+ const store = await openStore()+ // A pins 42 bytes for one hour; B pins 42 bytes for a day. 84 of 85.+ const expiring = await completedCopy(store, rootA, A, 0, 42, { owner: 'task-a' })+ const lasting = await completedCopy(store, rootB, B, 1, 42, {+ owner: 'task-b',+ expiresAt: new Date(Date.now() + 24 * HOUR_MS).toISOString(),+ })+ vi.setSystemTime(Date.now() + 2 * HOUR_MS)++ // The admission sweep removes expired copies before eviction plans, so+ // the eviction path is isolated by making the sweep's one inspection of+ // A's copy fail transiently: the sweep keeps it indexed, unexamined.+ const sourceSuffix = path.join(`input-${expiring.receipt.id}`, 'source')+ let injected = 0+ const passThrough = lstatBoundary.getMockImplementation()!+ lstatBoundary.mockImplementation((...args: unknown[]) => {+ if (injected === 0 && String(args[0]).endsWith(sourceSuffix)) {+ injected += 1+ return Promise.reject(ioError('EIO'))+ }+ return passThrough(...args)+ })++ // C's 5 bytes need 4 bytes evicted: only A's expired copy can give them.+ const admitted = await startTransfer(store, rootC, C, 2, 5)+ expect(injected).toBe(1)+ expect(exists(downloadDirectory(rootA, expiring.receipt.id))).toBe(false)+ expect(exists(downloadDirectory(rootB, lasting.receipt.id))).toBe(true)+ await expect(store.readManagedFile(lasting.receipt.path, B)).resolves.toEqual(lasting.bytes)+ await store.fail(admitted.transfer.id, C)+ })+})++describe('GFS download store: re-pinning an already protected copy (R4-F1)', () => {+ it('reuses a copy the caller already protects without measuring the volume', async () => {+ const store = await openStore()+ const held = await completedCopy(store, rootA, A, 0, 30, { owner: 'task-a' })+ await completedCopy(store, rootA, A, 1, 5)+ statfsBoundary.mockRejectedValueOnce(ioError('EIO'))+ const callsBefore = statfsBoundary.mock.calls.length++ // Already pinned by task-a: task-b's pin adds nothing and needs no statfs,+ // so the armed EIO is not consumed.+ await expect(+ store.reusableReceipt(A, sourceFor(0), 30, { retentionOwnerId: 'task-b' })+ ).resolves.toMatchObject({ id: held.receipt.id })+ expect(statfsBoundary.mock.calls.length).toBe(callsBefore)++ // Control: a copy A does not protect yet must size the budget, and the+ // same armed EIO refuses it.+ await expect(+ store.reusableReceipt(A, sourceFor(1), 5, { retentionOwnerId: 'task-b' })+ ).rejects.toBeInstanceOf(Error)+ expect(statfsBoundary.mock.calls.length).toBe(callsBefore + 1)+ })+})++describe('GFS download store: pins are per caller and per process (F24/U4 ported)', () => {+ it('releasing an owner id unpins only the releasing caller; the same id under another caller keeps counting', async () => {+ const store = await openStore()+ // A pins 42 (its cap) and B pins 40, both under the same owner id.+ await copies(store, rootA, A, 0, 8, 'task-shared')+ await completedCopy(store, rootA, A, 8, 2, { owner: 'task-shared' })+ await copies(store, rootB, B, 20, 8, 'task-shared')+ const before = await protectedRefusals()++ // Before any release B is refused too: 40 + 3 > 42.+ await expect(startTransfer(store, rootB, B, 30, 3)).rejects.toMatchObject({+ code: 'host_quota_exceeded',+ })+ expect(await protectedRefusals()).toBe(before + 1)++ await expect(store.releaseReceiptOwner('task-shared', B)).resolves.toBeUndefined()+ await expect(store.releaseReceiptOwner('unknown-owner', A)).resolves.toBeUndefined()++ // B's release freed B: its 3 bytes are admitted (82 + 3 = 85 fits the+ // budget, so only the cap could refuse them).+ const admittedB = await startTransfer(store, rootB, B, 31, 3)+ await store.fail(admittedB.transfer.id, B)+ expect(await protectedRefusals()).toBe(before + 1)+ // A's pin under the same id still holds A at its cap.+ await expect(startTransfer(store, rootA, A, 32, 1)).rejects.toMatchObject({+ code: 'host_quota_exceeded',+ })+ expect(await protectedRefusals()).toBe(before + 2)+ })++ it('a second store on the same root holds no pins', async () => {+ const first = await openStore()+ await copies(first, rootA, A, 0, 8, 'task-a')+ await completedCopy(first, rootA, A, 8, 2, { owner: 'task-a' })+ const before = await protectedRefusals()+ // Witness: in the first store A's pins hold it at the cap.+ await expect(startTransfer(first, rootA, A, 9, 1)).rejects.toMatchObject({+ code: 'host_quota_exceeded',+ })+ expect(await protectedRefusals()).toBe(before + 1)++ await first.close(0)+ const second = await openStore()+ const admitted = await startTransfer(second, rootA, A, 10, 1)+ await second.fail(admitted.transfer.id, A)+ expect(await protectedRefusals()).toBe(before + 1)})})diff --git a/mcp-host/src/internalTools/gfsManagedImage.test.ts b/mcp-host/src/internalTools/gfsManagedImage.test.tsindex 1ffff8ee1..7a4921242 100644--- a/mcp-host/src/internalTools/gfsManagedImage.test.ts+++ b/mcp-host/src/internalTools/gfsManagedImage.test.ts@@ -12,6 +12,7 @@ import {GfsDownloadStoreError,type GfsDownloadStoreErrorCode,} from './gfsDownloadStore'+import { GFS_CACHE_FULL_GUIDANCE, GFS_DISK_FULL_GUIDANCE } from './gfsSpaceGuidance'const MIB = 1024 * 1024const target = { drive: 'main', resourceId: 'a'.repeat(32) }@@ -344,14 +345,23 @@ describe('GFS managed image projection', () => {describe('GFS download store errors at the tool boundary', () => {const codes: GfsDownloadStoreErrorCode[] = ['caller_mismatch',+ 'disk_full','download_busy','download_expired','download_missing','host_quota_exceeded',+ 'limit_exceeded','publication_cancelled','storage_write_failed','workspace_unavailable',]+ // Only the two space refusals carry guidance, as an exact second line.+ const toolError = (code: GfsDownloadStoreErrorCode): string =>+ code === 'disk_full'+ ? `GFS download store failed (disk_full)\n${GFS_DISK_FULL_GUIDANCE}`+ : code === 'host_quota_exceeded'+ ? `GFS download store failed (host_quota_exceeded)\n${GFS_CACHE_FULL_GUIDANCE}`+ : `GFS download store failed (${code})`it.each(codes)('surfaces store code %s to the model', async code => {const subject = scenario(largePng, {@@ -363,7 +373,7 @@ describe('GFS download store errors at the tool boundary', () => {expect(subject.store.readManagedFile).toHaveBeenCalledTimes(1)expect(result.success).toBe(false)- expect(result.error).toBe(`GFS download store failed (${code})`)+ expect(result.error).toBe(toolError(code))expect(subject.budget.residentBytes).toBe(0)})@@ -377,6 +387,6 @@ describe('GFS download store errors at the tool boundary', () => {expect(subject.client.download).toHaveBeenCalledTimes(1)expect(subject.store.readManagedFile).not.toHaveBeenCalled()expect(result.success).toBe(false)- expect(result.error).toBe(`GFS download store failed (${code})`)+ expect(result.error).toBe(toolError(code))})})diff --git a/mcp-host/src/internalTools/gfsSpaceGuidance.ts b/mcp-host/src/internalTools/gfsSpaceGuidance.tsnew file mode 100644index 000000000..a0e6d2961--- /dev/null+++ b/mcp-host/src/internalTools/gfsSpaceGuidance.ts@@ -0,0 +1,27 @@+import type { GfsDownloadStoreErrorCode } from './gfsDownloadStore'++/**+ * Fixed model-facing guidance for the two space refusals of the GFS download+ * store. Both texts are constants: they carry no size, count, path or caller+ * identity, so they cannot reveal whose files use the space.+ */+export const GFS_DISK_FULL_GUIDANCE =+ 'The Host workspace disk is full, so the file was not downloaded. Tell the user. ' ++ 'Offer to list the files in their own workspace, which is the shell working directory ' ++ '(for example `du -sh -- * .[!.]* 2>/dev/null | sort -h`), and to delete the ones they ' ++ 'no longer need with a shell_exec command they approve. Never list, read or delete ' ++ "another user's directory or anything outside the workspace."++export const GFS_CACHE_FULL_GUIDANCE =+ "The Host's cache of downloaded files is full, so the file was not downloaded. " ++ 'Space frees as other tasks finish and cached copies expire. Tell the user. ' ++ 'They may delete their own downloaded copies under .gfs-downloads in their workspace ' ++ 'that no running task is using, with a shell_exec command they approve; a task that ' ++ "still needs a deleted copy downloads it again. Never delete another user's copies."++/** The guidance a store refusal carries to the model, if it has one. */+export function gfsStoreSpaceGuidance(code: GfsDownloadStoreErrorCode): string | undefined {+ if (code === 'disk_full') return GFS_DISK_FULL_GUIDANCE+ if (code === 'host_quota_exceeded') return GFS_CACHE_FULL_GUIDANCE+ return undefined+}diff --git a/scripts/ci/pinned-vitest-cases/mcp-host.json b/scripts/ci/pinned-vitest-cases/mcp-host.jsonindex eb1c8b4f8..4b6a57fad 100644--- a/scripts/ci/pinned-vitest-cases/mcp-host.json+++ b/scripts/ci/pinned-vitest-cases/mcp-host.json@@ -483,10 +483,6 @@"suite": "gfsDownloadStoreBoundaries.test.ts","fullName": "GFS download store boundaries: caller isolation U3: publish and fail answer another caller's transfer exactly like an unknown id"},- {- "suite": "gfsDownloadStoreBoundaries.test.ts",- "fullName": "GFS download store boundaries: caller isolation U4: an owner id another caller pins is neither refused nor released across callers"- },{"suite": "gfsDownloadStoreBoundaries.test.ts","fullName": "GFS download store boundaries: path swapped between check and use K1: a removal whose parent is swapped after the check renames back and touches nothing outside"@@ -930,5 +926,141 @@{"suite": "gfsDownloadStoreProtected.test.ts","fullName": "GFS download store: a caller protects at most half the budget (R3-F1) a file larger than the cap is refused before any eviction"+ },+ {+ "suite": "gfsDownloadStore.test.ts",+ "fullName": "GFS download store: sweep F17: the sweep removes expired complete downloads, pinned or not"+ },+ {+ "suite": "gfsDownloadStore.test.ts",+ "fullName": "GFS download store: pins, lifecycle and errors F24: releaseReceiptOwner accepts an unknown owner and another caller owner id without removing any copy"+ },+ {+ "suite": "gfsDownloadStoreBoundaries.test.ts",+ "fullName": "GFS download store boundaries: caller isolation U4: an owner id another caller pins is not refused, and releasing it twice is a no-op"+ },+ {+ "suite": "gfsDownloadStoreBudget.test.ts",+ "fullName": "GFS download store budget: a full disk and a full cache are distinct refusals DSK-1: a full disk refuses as disk_full while a full budget still refuses as host_quota_exceeded"+ },+ {+ "suite": "gfsDownloadStoreBudget.test.ts",+ "fullName": "GFS download store budget: a full disk and a full cache are distinct refusals DSK-2: statfs reporting a negative available-block count keeps host_quota_exceeded, not disk_full"+ },+ {+ "suite": "gfsDownloadStoreBudget.test.ts",+ "fullName": "GFS download store budget: a full disk and a full cache are distinct refusals DSK-3: 'one byte above the file limit' is refused as limit_exceeded without a space metric"+ },+ {+ "suite": "gfsDownloadStoreBudget.test.ts",+ "fullName": "GFS download store budget: a full disk and a full cache are distinct refusals DSK-3: 'a negative size' is refused as limit_exceeded without a space metric"+ },+ {+ "suite": "gfsDownloadStoreBudget.test.ts",+ "fullName": "GFS download store budget: a full disk and a full cache are distinct refusals DSK-3: 'a fractional size' is refused as limit_exceeded without a space metric"+ },+ {+ "suite": "gfsDownloadStoreProtected.test.ts",+ "fullName": "GFS download store: a caller protects at most half the budget (R3-F1) SOL-R4-ORDER: a caller at its cap is refused before eviction, so a full budget keeps the other caller copies"+ },+ {+ "suite": "gfsDownloadStoreProtected.test.ts",+ "fullName": "GFS download store: retention pins never outlive expiresAt (Addendum 10) the sweep removes a pinned copy once it is past its expiry"+ },+ {+ "suite": "gfsDownloadStoreProtected.test.ts",+ "fullName": "GFS download store: retention pins never outlive expiresAt (Addendum 10) an expired pinned copy stops counting toward its caller cap without releasing the owner"+ },+ {+ "suite": "gfsDownloadStoreProtected.test.ts",+ "fullName": "GFS download store: retention pins never outlive expiresAt (Addendum 10) eviction reclaims an expired pinned copy the admission sweep could not inspect, and keeps unexpired pins"+ },+ {+ "suite": "gfsDownloadStoreProtected.test.ts",+ "fullName": "GFS download store: re-pinning an already protected copy (R4-F1) reuses a copy the caller already protects without measuring the volume"+ },+ {+ "suite": "gfsDownloadStoreProtected.test.ts",+ "fullName": "GFS download store: pins are per caller and per process (F24/U4 ported) releasing an owner id unpins only the releasing caller; the same id under another caller keeps counting"+ },+ {+ "suite": "gfsDownloadStoreProtected.test.ts",+ "fullName": "GFS download store: pins are per caller and per process (F24/U4 ported) a second store on the same root holds no pins"+ },+ {+ "suite": "gfsManagedImage.test.ts",+ "fullName": "GFS download store errors at the tool boundary surfaces store code disk_full to the model"+ },+ {+ "suite": "gfsManagedImage.test.ts",+ "fullName": "GFS download store errors at the tool boundary surfaces store code limit_exceeded to the model"+ },+ {+ "suite": "gfsManagedImage.test.ts",+ "fullName": "GFS download store errors at the tool boundary surfaces download admission code disk_full to the model"+ },+ {+ "suite": "gfsManagedImage.test.ts",+ "fullName": "GFS download store errors at the tool boundary surfaces download admission code limit_exceeded to the model"+ },+ {+ "suite": "gfsFilePreparation.test.ts",+ "fullName": "GFS file preparation maps the disk_full envelope with its guidance to its fixed category"+ },+ {+ "suite": "gfsFilePreparation.test.ts",+ "fullName": "GFS file preparation maps the bare disk_full envelope to its fixed category"+ },+ {+ "suite": "gfsFilePreparation.test.ts",+ "fullName": "GFS file preparation maps the host_quota_exceeded envelope with its guidance to its fixed category"+ },+ {+ "suite": "gfsFilePreparation.test.ts",+ "fullName": "GFS file preparation maps the disk_full envelope with the cache guidance to its fixed category"+ },+ {+ "suite": "gfsFilePreparation.test.ts",+ "fullName": "GFS file preparation maps the host_quota_exceeded envelope with the disk guidance to its fixed category"+ },+ {+ "suite": "gfsFilePreparation.test.ts",+ "fullName": "GFS file preparation maps the disk_full envelope with an untrusted second line to its fixed category"+ },+ {+ "suite": "gfsFilePreparation.test.ts",+ "fullName": "GFS file preparation maps the host_quota_exceeded envelope with its guidance and a third line to its fixed category"+ },+ {+ "suite": "gfsFilePreparation.test.ts",+ "fullName": "GFS file preparation maps the store limit_exceeded envelope to its fixed category"+ },+ {+ "suite": "gfsFilePreparation.test.ts",+ "fullName": "GFS file preparation maps the store limit_exceeded envelope with the cache guidance to its fixed category"+ },+ {+ "suite": "gfsFilePreparation.test.ts",+ "fullName": "GFS file preparation keeps every guided space envelope within the fixed error bound"+ },+ {+ "suite": "turnContext.test.ts",+ "fullName": "prepared GFS receipts tells the model the workspace disk is full and to offer a cleanup of the caller workspace only"+ },+ {+ "suite": "turnContext.test.ts",+ "fullName": "prepared GFS receipts tells the model the download cache is full and that only the caller may delete its own copies"+ },+ {+ "suite": "turnContext.test.ts",+ "fullName": "prepared GFS receipts keeps the two space guidances distinct from each other"+ },+ {+ "suite": "turnContext.test.ts",+ "fullName": "prepared GFS receipts names no caller, foreign path or count in either space guidance"+ },+ {+ "suite": "turnContext.test.ts",+ "fullName": "prepared GFS receipts adds each space guidance once for several refusals and none for other codes"}]