Skip to content

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

TypeScript

feat(files): admit inline kind:file attachments and read them with clerum__attachment_read

Alfredo Lopezeb8d0d2ada1f
diff --git a/desktop-app/ui/src/constants/attachments.ts b/desktop-app/ui/src/constants/attachments.ts
index 077a23776..0f3f75f0e 100644
--- a/desktop-app/ui/src/constants/attachments.ts
+++ b/desktop-app/ui/src/constants/attachments.ts
@@ -1,4 +1,4 @@
-// Must match INCOMING_IMAGE_MAX_COUNT in mcp-host/src/agent/incomingImageAttachments.ts.
+// Must match INCOMING_ATTACHMENT_MAX_COUNT in mcp-host/src/agent/incomingAttachments.ts.
export const COMPOSER_MAX_IMAGE_ATTACHMENTS = 20
/**
diff --git a/external-rest-api/src/releaseManifest.ts b/external-rest-api/src/releaseManifest.ts
index f70725a95..fdc83883b 100644
--- a/external-rest-api/src/releaseManifest.ts
+++ b/external-rest-api/src/releaseManifest.ts
@@ -9,7 +9,7 @@ export type ReleaseManifest = {
export const releaseManifest: ReleaseManifest = {
releaseId: 'v0.9.0',
externalRestApiVersion: '0.1.84',
- rpcProxyVersion: '0.1.89',
+ rpcProxyVersion: '0.1.90',
desktopVersion: '0.9.0',
minimumDesktopVersion: '0.1.252',
}
diff --git a/mcp-host/README.md b/mcp-host/README.md
index bea3be76e..8e3e74eb8 100644
--- a/mcp-host/README.md
+++ b/mcp-host/README.md
@@ -17,49 +17,51 @@ MCP Host is a Kubernetes-native service that reads Host CRD configuration and pr
### Environment Variables
-| Variable | Explanation | Canonical example |
-| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `CLERUM_DEV_MODE` | Enables local/dev bootstrap mode that bypasses Host CRD discovery and reads host/runtime config from env. | `CLERUM_DEV_MODE=true` |
-| `CLERUM_HOST_NAME` | Selects which Host CRD to load in production mode; in non-production fallback it defaults to `dev-host`. | `CLERUM_HOST_NAME=chatllm` |
-| `CLERUM_NAMESPACE` | Sets the Kubernetes namespace used for Host and Secret lookup when running in cluster mode. | `CLERUM_NAMESPACE=mcp-host` |
-| `CLERUM_SERVER_PORT` | Sets the HTTP listen port for the runtime API server. | `CLERUM_SERVER_PORT=8080` |
-| `CLERUM_CONTEXT_MAPPER_URL` | Points to the host-context-controller endpoint used to resolve MCP servers for a context. | `CLERUM_CONTEXT_MAPPER_URL=http://host-context-controller-api-gateway.control-plane.svc.cluster.local:8081` |
-| `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` | Controls polling interval (milliseconds) for MCP server config changes from context mapper. | `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL=30000` |
-| `HCC_AUTHORITY_MAX_STALENESS_MS` | Maximum time a previously published MCP fleet may survive an unavailable HCC (default 180000 ms; hard-capped at 600000 ms). It must be greater than `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` in cluster mode; invalid combinations fail startup. Minikube pins 60000 ms for its deterministic staleness E2E. | `HCC_AUTHORITY_MAX_STALENESS_MS=180000` |
-| `CLERUM_HOST_CONFIG` | Provides a full Host spec as JSON in dev mode, overriding provider/model context env composition. | `CLERUM_HOST_CONFIG={"host":"dev-host","contextRef":"dev-context","secretRef":"dev-secret","model":{"provider":"openai","name":"gpt-5.4-mini"}}` |
-| `CLERUM_MODEL_PROVIDER` | Chooses the model provider in dev mode when `CLERUM_HOST_CONFIG` is not set. | `CLERUM_MODEL_PROVIDER=openai` |
-| `CLERUM_MODEL_NAME` | Overrides the default provider model name in dev mode. Used only when `CLERUM_MODEL_PROVIDER` is also set; an auto-detected provider keeps its default model. | `CLERUM_MODEL_NAME=gpt-5.4-mini` |
-| `CLERUM_MCP_SERVERS` | Supplies dev MCP server definitions as JSON so you can run without context mapper. Each entry needs `name`, `contextRef`, `transport`, `enabled`, and a `status` object — a server whose `status.ready` is not `true` is parsed but skipped as "not ready". | `CLERUM_MCP_SERVERS=[{"name":"filesystem","contextRef":"dev-context","transport":{"type":"streamableHttp","url":"http://localhost:3101"},"enabled":true,"status":{"deployed":true,"ready":true}}]` |
-| `CLERUM_MCP_TOOL_TIMEOUT_MS` | Per-call timeout passed to MCP SDK `Client.callTool(...)` requests. The effective timeout is still bounded by any caller workflow or snippet step budget. | `CLERUM_MCP_TOOL_TIMEOUT_MS=1500000` |
-| `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS` | Maximum total MCP SDK tool-call budget used at the SDK request boundary. Operators may tune it up to the existing workflow step ceiling; invalid values fail closed at runtime. | `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS=1500000` |
-| `OPENAI_API_KEY` | OpenAI API key used by dev mode when provider selection resolves to OpenAI. | `OPENAI_API_KEY=sk-xxxx` |
-| `CLAUDE_API_KEY` | Anthropic API key used by dev mode when provider selection resolves to Claude. | `CLAUDE_API_KEY=sk-ant-xxxx` |
-| `ZAI_API_KEY` | ZAI API key used by dev mode when provider selection resolves to ZAI. | `ZAI_API_KEY=zai-xxxx` |
-| `BAILIAN_API_KEY` | Bailian API key used by dev mode when provider selection resolves to Bailian/Qwen. | `BAILIAN_API_KEY=ba-xxxx` |
-| `CLERUM_AGENT_TASK_DELAY` | Minimum interval in milliseconds between task dispatches; does not delay individual tool iterations. | `CLERUM_AGENT_TASK_DELAY=3` |
-| `CLERUM_AGENT_MAX_TASK_DURATION` | Maximum active task execution time in milliseconds (24 hours), accumulated across approval resumptions. Approval waiting is excluded. | `CLERUM_AGENT_MAX_TASK_DURATION=86400000` |
-| `CLERUM_AGENT_MAX_TOOL_CALLS` | Maximum LLM/tool iterations per task; each iteration may call multiple tools. Configured per Host process. | `CLERUM_AGENT_MAX_TOOL_CALLS=1000` |
-| `CLERUM_AGENT_MAX_QUEUE_SIZE` | Maximum pending queue size before new tasks are rejected/back-pressured. | `CLERUM_AGENT_MAX_QUEUE_SIZE=100` |
-| `CLERUM_ENABLE_APPROVAL` | Enables the approval gate workflow for tool execution decisions. | `CLERUM_ENABLE_APPROVAL=true` |
-| `CLERUM_APPROVAL_CONFIG` | JSON config for approval policy/channels when not sourced from Host CRD. | `CLERUM_APPROVAL_CONFIG={"defaultPolicy":"designated_approvers","channels":{"telegram":{"enabled":true,"approvers":["123456"]}}}` |
-| `CLERUM_ENABLE_NUDGE` | Enables the nudge controller that pushes model/tool retry guidance when output is rejected. | `CLERUM_ENABLE_NUDGE=false` |
-| `CLERUM_NUDGE_MAX_ITERATIONS` | Maximum number of nudge cycles allowed for a task. | `CLERUM_NUDGE_MAX_ITERATIONS=3` |
-| `CLERUM_CONTEXT_MAX_TOKENS` | Token budget used by context compaction when the model's allowlist row carries no context window. `codex-subscription` and `grok-subscription` models use 256000 instead; the Host logs `context_window_resolved` with the window and its source. | `CLERUM_CONTEXT_MAX_TOKENS=100000` |
-| `CLERUM_COMPACTION_PRE_PRUNE` | Master switch for pre-pruning the history (deduplication, one-lining, JSON truncation, media stripping). It runs only once the history reaches the compaction threshold (80% of the context window), before any compaction tier is chosen, and at history rehydration under the same threshold. On by default; set to `false` to disable every pass at once. | `CLERUM_COMPACTION_PRE_PRUNE=true` |
-| `CLERUM_WORKSPACE_PATH` | Base workspace path used by native tools and workspace-aware operations. | `CLERUM_WORKSPACE_PATH=/workspace` |
-| `CLERUM_SHELL_TIMEOUT` | Maximum execution time in milliseconds for shell native-tool commands. | `CLERUM_SHELL_TIMEOUT=1500000` |
-| `CLERUM_TOOL_TIMEOUT` | Maximum execution time in milliseconds for native tool wrapper calls. This is separate from the MCP SDK request timeout controlled by `CLERUM_MCP_TOOL_TIMEOUT_MS`. | `CLERUM_TOOL_TIMEOUT=1500000` |
-| `CLERUM_HTTP_ALLOWLIST` | Comma-separated allowlist of outbound hosts/URLs allowed for HTTP native tools. With an allowlist set, you can also skip per-call approval by adding `tools: { http_request: false }` under `Host.spec.approval` (see Host CRD). | `CLERUM_HTTP_ALLOWLIST=api.github.com,example.com` |
-| `CLERUM_ENV_ALLOWLIST` | Comma-separated list of environment variables forwarded into native tool execution contexts. | `CLERUM_ENV_ALLOWLIST=PATH,HOME,USER,SHELL,LANG,TERM` |
-| `CLERUM_MEMORY_MAX_SIZE` | Maximum bytes reserved for in-memory native tool buffers/state. | `CLERUM_MEMORY_MAX_SIZE=1048576` |
-| `CLERUM_ENABLE_RESPONSE_ATTACHMENTS` | Enables attachment passthrough in runtime responses when tools return supported media. | `CLERUM_ENABLE_RESPONSE_ATTACHMENTS=true` |
-| `CLERUM_ATTACHMENT_MAX_COUNT` | Maximum number of attachments returned per response. | `CLERUM_ATTACHMENT_MAX_COUNT=3` |
-| `CLERUM_ATTACHMENT_MAX_BYTES` | Maximum decoded size per attachment in bytes (oversized payloads are dropped). | `CLERUM_ATTACHMENT_MAX_BYTES=52428800` |
-| `CLERUM_MEMORY_ENABLED` | Enables workspace memory persistence features. | `CLERUM_MEMORY_ENABLED=true` |
-| `CLERUM_MEMORY_WORKSPACE_PATH` | Sets workspace directory path used when memory mode is enabled. | `CLERUM_MEMORY_WORKSPACE_PATH=/workspace` |
-| `CLERUM_PERSONALIZATION_ENABLED` | Enables identity/personalization seeding behavior. | `CLERUM_PERSONALIZATION_ENABLED=true` |
-| `CLERUM_IDENTITY_SEED` | JSON identity seed used to initialize personalization artifacts when enabled. | `CLERUM_IDENTITY_SEED={"displayName":"Clerum Agent","tone":"concise"}` |
-| `NODE_ENV` | Influences production checks and defaults (for example strict host-name requirement in production). | `NODE_ENV=production` |
+| Variable | Explanation | Canonical example |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CLERUM_DEV_MODE` | Enables local/dev bootstrap mode that bypasses Host CRD discovery and reads host/runtime config from env. | `CLERUM_DEV_MODE=true` |
+| `CLERUM_HOST_NAME` | Selects which Host CRD to load in production mode; in non-production fallback it defaults to `dev-host`. | `CLERUM_HOST_NAME=chatllm` |
+| `CLERUM_NAMESPACE` | Sets the Kubernetes namespace used for Host and Secret lookup when running in cluster mode. | `CLERUM_NAMESPACE=mcp-host` |
+| `CLERUM_SERVER_PORT` | Sets the HTTP listen port for the runtime API server. | `CLERUM_SERVER_PORT=8080` |
+| `CLERUM_CONTEXT_MAPPER_URL` | Points to the host-context-controller endpoint used to resolve MCP servers for a context. | `CLERUM_CONTEXT_MAPPER_URL=http://host-context-controller-api-gateway.control-plane.svc.cluster.local:8081` |
+| `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` | Controls polling interval (milliseconds) for MCP server config changes from context mapper. | `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL=30000` |
+| `HCC_AUTHORITY_MAX_STALENESS_MS` | Maximum time a previously published MCP fleet may survive an unavailable HCC (default 180000 ms; hard-capped at 600000 ms). It must be greater than `CLERUM_CONTEXT_MAPPER_POLL_INTERVAL` in cluster mode; invalid combinations fail startup. Minikube pins 60000 ms for its deterministic staleness E2E. | `HCC_AUTHORITY_MAX_STALENESS_MS=180000` |
+| `CLERUM_HOST_CONFIG` | Provides a full Host spec as JSON in dev mode, overriding provider/model context env composition. | `CLERUM_HOST_CONFIG={"host":"dev-host","contextRef":"dev-context","secretRef":"dev-secret","model":{"provider":"openai","name":"gpt-5.4-mini"}}` |
+| `CLERUM_MODEL_PROVIDER` | Chooses the model provider in dev mode when `CLERUM_HOST_CONFIG` is not set. | `CLERUM_MODEL_PROVIDER=openai` |
+| `CLERUM_MODEL_NAME` | Overrides the default provider model name in dev mode. Used only when `CLERUM_MODEL_PROVIDER` is also set; an auto-detected provider keeps its default model. | `CLERUM_MODEL_NAME=gpt-5.4-mini` |
+| `CLERUM_MCP_SERVERS` | Supplies dev MCP server definitions as JSON so you can run without context mapper. Each entry needs `name`, `contextRef`, `transport`, `enabled`, and a `status` object — a server whose `status.ready` is not `true` is parsed but skipped as "not ready". | `CLERUM_MCP_SERVERS=[{"name":"filesystem","contextRef":"dev-context","transport":{"type":"streamableHttp","url":"http://localhost:3101"},"enabled":true,"status":{"deployed":true,"ready":true}}]` |
+| `CLERUM_MCP_TOOL_TIMEOUT_MS` | Per-call timeout passed to MCP SDK `Client.callTool(...)` requests. The effective timeout is still bounded by any caller workflow or snippet step budget. | `CLERUM_MCP_TOOL_TIMEOUT_MS=1500000` |
+| `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS` | Maximum total MCP SDK tool-call budget used at the SDK request boundary. Operators may tune it up to the existing workflow step ceiling; invalid values fail closed at runtime. | `CLERUM_MCP_TOOL_MAX_TOTAL_TIMEOUT_MS=1500000` |
+| `OPENAI_API_KEY` | OpenAI API key used by dev mode when provider selection resolves to OpenAI. | `OPENAI_API_KEY=sk-xxxx` |
+| `CLAUDE_API_KEY` | Anthropic API key used by dev mode when provider selection resolves to Claude. | `CLAUDE_API_KEY=sk-ant-xxxx` |
+| `ZAI_API_KEY` | ZAI API key used by dev mode when provider selection resolves to ZAI. | `ZAI_API_KEY=zai-xxxx` |
+| `BAILIAN_API_KEY` | Bailian API key used by dev mode when provider selection resolves to Bailian/Qwen. | `BAILIAN_API_KEY=ba-xxxx` |
+| `CLERUM_AGENT_TASK_DELAY` | Minimum interval in milliseconds between task dispatches; does not delay individual tool iterations. | `CLERUM_AGENT_TASK_DELAY=3` |
+| `CLERUM_AGENT_MAX_TASK_DURATION` | Maximum active task execution time in milliseconds (24 hours), accumulated across approval resumptions. Approval waiting is excluded. | `CLERUM_AGENT_MAX_TASK_DURATION=86400000` |
+| `CLERUM_AGENT_MAX_TOOL_CALLS` | Maximum LLM/tool iterations per task; each iteration may call multiple tools. Configured per Host process. | `CLERUM_AGENT_MAX_TOOL_CALLS=1000` |
+| `CLERUM_AGENT_MAX_QUEUE_SIZE` | Maximum pending queue size before new tasks are rejected/back-pressured. | `CLERUM_AGENT_MAX_QUEUE_SIZE=100` |
+| `CLERUM_ENABLE_APPROVAL` | Enables the approval gate workflow for tool execution decisions. | `CLERUM_ENABLE_APPROVAL=true` |
+| `CLERUM_APPROVAL_CONFIG` | JSON config for approval policy/channels when not sourced from Host CRD. | `CLERUM_APPROVAL_CONFIG={"defaultPolicy":"designated_approvers","channels":{"telegram":{"enabled":true,"approvers":["123456"]}}}` |
+| `CLERUM_ENABLE_NUDGE` | Enables the nudge controller that pushes model/tool retry guidance when output is rejected. | `CLERUM_ENABLE_NUDGE=false` |
+| `CLERUM_NUDGE_MAX_ITERATIONS` | Maximum number of nudge cycles allowed for a task. | `CLERUM_NUDGE_MAX_ITERATIONS=3` |
+| `CLERUM_CONTEXT_MAX_TOKENS` | Token budget used by context compaction when the model's allowlist row carries no context window. `codex-subscription` and `grok-subscription` models use 256000 instead; the Host logs `context_window_resolved` with the window and its source. | `CLERUM_CONTEXT_MAX_TOKENS=100000` |
+| `CLERUM_COMPACTION_PRE_PRUNE` | Master switch for pre-pruning the history (deduplication, one-lining, JSON truncation, media stripping). It runs only once the history reaches the compaction threshold (80% of the context window), before any compaction tier is chosen, and at history rehydration under the same threshold. On by default; set to `false` to disable every pass at once. | `CLERUM_COMPACTION_PRE_PRUNE=true` |
+| `CLERUM_WORKSPACE_PATH` | Base workspace path used by native tools and workspace-aware operations. | `CLERUM_WORKSPACE_PATH=/workspace` |
+| `CLERUM_SHELL_TIMEOUT` | Maximum execution time in milliseconds for shell native-tool commands. | `CLERUM_SHELL_TIMEOUT=1500000` |
+| `CLERUM_TOOL_TIMEOUT` | Maximum execution time in milliseconds for native tool wrapper calls. This is separate from the MCP SDK request timeout controlled by `CLERUM_MCP_TOOL_TIMEOUT_MS`. | `CLERUM_TOOL_TIMEOUT=1500000` |
+| `CLERUM_HTTP_ALLOWLIST` | Comma-separated allowlist of outbound hosts/URLs allowed for HTTP native tools. With an allowlist set, you can also skip per-call approval by adding `tools: { http_request: false }` under `Host.spec.approval` (see Host CRD). | `CLERUM_HTTP_ALLOWLIST=api.github.com,example.com` |
+| `CLERUM_ENV_ALLOWLIST` | Comma-separated list of environment variables forwarded into native tool execution contexts. | `CLERUM_ENV_ALLOWLIST=PATH,HOME,USER,SHELL,LANG,TERM` |
+| `CLERUM_MEMORY_MAX_SIZE` | Maximum bytes reserved for in-memory native tool buffers/state. | `CLERUM_MEMORY_MAX_SIZE=1048576` |
+| `CLERUM_ENABLE_RESPONSE_ATTACHMENTS` | Enables attachment passthrough in runtime responses when tools return supported media. | `CLERUM_ENABLE_RESPONSE_ATTACHMENTS=true` |
+| `CLERUM_ATTACHMENT_MAX_COUNT` | Maximum number of attachments returned per response. | `CLERUM_ATTACHMENT_MAX_COUNT=3` |
+| `CLERUM_ATTACHMENT_MAX_BYTES` | Maximum decoded size per attachment in bytes (oversized payloads are dropped). | `CLERUM_ATTACHMENT_MAX_BYTES=52428800` |
+| `CLERUM_ATTACHMENT_FILE_MAX_BYTES` | Maximum decoded size in bytes of one incoming `kind:'file'` attachment; a larger file rejects the message with `FILE_ATTACHMENT_TOO_LARGE`. An invalid value stops the Host at startup. | `CLERUM_ATTACHMENT_FILE_MAX_BYTES=3145728` |
+| `CLERUM_ATTACHMENT_TEXT_READ_MAX_BYTES` | Maximum bytes one `clerum__attachment_read` call returns; longer text is returned with `truncated:true` and read on with `offset`. An invalid value stops the Host at startup. | `CLERUM_ATTACHMENT_TEXT_READ_MAX_BYTES=262144` |
+| `CLERUM_MEMORY_ENABLED` | Enables workspace memory persistence features. | `CLERUM_MEMORY_ENABLED=true` |
+| `CLERUM_MEMORY_WORKSPACE_PATH` | Sets workspace directory path used when memory mode is enabled. | `CLERUM_MEMORY_WORKSPACE_PATH=/workspace` |
+| `CLERUM_PERSONALIZATION_ENABLED` | Enables identity/personalization seeding behavior. | `CLERUM_PERSONALIZATION_ENABLED=true` |
+| `CLERUM_IDENTITY_SEED` | JSON identity seed used to initialize personalization artifacts when enabled. | `CLERUM_IDENTITY_SEED={"displayName":"Clerum Agent","tone":"concise"}` |
+| `NODE_ENV` | Influences production checks and defaults (for example strict host-name requirement in production). | `NODE_ENV=production` |
### Host CRD
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 6ebd1c014..b0fd768c4 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.441",
+ "version": "0.1.442",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.441",
+ "version": "0.1.442",
"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 e86c1940e..716888d5d 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.441",
+ "version": "0.1.442",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/__tests__/bodylimits.test.ts b/mcp-host/src/__tests__/bodylimits.test.ts
index 22471a7dd..13d2c2322 100644
--- a/mcp-host/src/__tests__/bodylimits.test.ts
+++ b/mcp-host/src/__tests__/bodylimits.test.ts
@@ -281,6 +281,82 @@ describe('mcp-host runtime message body budget', () => {
expect(captured).toHaveLength(0)
})
+ describe('kind:file attachments count against the 6MiB non-image budget (issue #666)', () => {
+ const NON_IMAGE_BUDGET = 6 * MIB
+ const KIB = 1024
+
+ function fileAttachment(dataBase64: string) {
+ return {
+ id: 'f1',
+ kind: 'file' as const,
+ mimeType: 'text/plain',
+ detectedMediaType: 'text/plain',
+ encoding: 'base64' as const,
+ dataBase64,
+ filename: 'notes.txt',
+ sizeBytes: 0,
+ digest: { algorithm: 'sha256' as const, hex: '0'.repeat(64) },
+ }
+ }
+
+ /** A message whose serialized body is exactly `targetBytes`, almost all of it file base64. */
+ function fileMessageOfBodySize(targetBytes: number) {
+ const overhead = Buffer.byteLength(JSON.stringify(messagePayload([fileAttachment('')])))
+ const fill = targetBytes - overhead
+ const dataBase64 = 'A'.repeat(fill - (fill % 4))
+ const payload = {
+ ...messagePayload([fileAttachment(dataBase64)]),
+ content: `look${'x'.repeat(fill % 4)}`,
+ }
+ expect(Buffer.byteLength(JSON.stringify(payload))).toBe(targetBytes)
+ return { payload, dataBase64 }
+ }
+
+ it('delivers a file body 1KiB under the budget', async () => {
+ captured = []
+ const { payload, dataBase64 } = fileMessageOfBodySize(NON_IMAGE_BUDGET - KIB)
+ const response = await postMessage(payload)
+ expect(response.status).toBe(200)
+ expect(captured).toHaveLength(1)
+ expect(captured[0]!.attachments?.[0]?.dataBase64.length).toBe(dataBase64.length)
+ })
+
+ it('rejects a file body 1KiB over the budget with 413', async () => {
+ captured = []
+ // Control: the same construction under the budget is delivered.
+ const under = fileMessageOfBodySize(NON_IMAGE_BUDGET - KIB)
+ expect((await postMessage(under.payload)).status).toBe(200)
+ captured = []
+ const response = await postMessage(fileMessageOfBodySize(NON_IMAGE_BUDGET + KIB).payload)
+ expect(response.status).toBe(413)
+ expect(captured).toHaveLength(0)
+ })
+
+ it('never credits PNG bytes sent as kind:file against the image budget', async () => {
+ const dataBase64 = pngBase64(7 * MIB)
+ captured = []
+ const asImage = await postMessage(
+ messagePayload([{ ...imageAttachment('a1', 7 * MIB), dataBase64 }])
+ )
+ expect(asImage.status).toBe(200)
+ expect(captured).toHaveLength(1)
+ captured = []
+ // Same MIME type and bytes as the image: only `kind` differs.
+ const asFile = await postMessage(
+ messagePayload([
+ {
+ ...fileAttachment(dataBase64),
+ mimeType: 'image/png',
+ detectedMediaType: 'image/png',
+ filename: 'photo.png',
+ },
+ ])
+ )
+ expect(asFile.status).toBe(413)
+ expect(captured).toHaveLength(0)
+ })
+ })
+
it('rejects a body past the 24MiB ceiling', async () => {
captured = []
const response = await postMessage({
diff --git a/mcp-host/src/__tests__/messageHandler.duplicate.test.ts b/mcp-host/src/__tests__/messageHandler.duplicate.test.ts
index ee5742318..bb6b619a7 100644
--- a/mcp-host/src/__tests__/messageHandler.duplicate.test.ts
+++ b/mcp-host/src/__tests__/messageHandler.duplicate.test.ts
@@ -12,6 +12,7 @@
*/
import { describe, expect, it, vi } from 'vitest'
import { EventEmitter } from 'events'
+import type { Attachment } from '../core/types'
import { TaskLifecycle } from '../lifecycle/taskLifecycle'
import { logger } from '../logger'
import { IncomingMessageHandler, PendingTaskEntry } from '../messageHandler'
@@ -214,6 +215,121 @@ describe('IncomingMessageHandler — duplicate delivery suppression', () => {
})
})
+/**
+ * #666 — rpc-proxy's wake-and-hold resends the same messageId after a socket
+ * death. The replay must name the attachments the first delivery admitted:
+ * a success without them reads as a Host that dropped them, and the client's
+ * retry under a fresh messageId would run the task twice.
+ */
+describe('IncomingMessageHandler — duplicate delivery keeps acceptedAttachmentIds', () => {
+ const attachments: Attachment[] = [
+ {
+ id: 'file-1',
+ kind: 'file',
+ mimeType: 'text/plain',
+ encoding: 'base64',
+ dataBase64: Buffer.from('notes').toString('base64'),
+ },
+ {
+ id: 'image-1',
+ kind: 'image',
+ mimeType: 'image/png',
+ encoding: 'base64',
+ dataBase64: 'iVBORw0KGgo=',
+ },
+ ]
+
+ function messageWithAttachments(messageId: string): IncomingMessage {
+ return { ...createTestMessage(messageId), attachments }
+ }
+
+ it('replays them for a duplicate of a COMPLETED task', async () => {
+ const deps = createMockDeps()
+ const message = messageWithAttachments('msg-att-completed')
+ const first = new IncomingMessageHandler(message, deps)
+ const firstPromise = first.execute()
+ await new Promise(r => setTimeout(r, 10))
+ const task = deps.messageQueue.dequeue()!
+ task.result = { response: 'first answer', model: 'test-model' }
+ deps.messageQueue.completeTask(task)
+ await task.responseCallback!({ response: 'first answer' })
+ await firstPromise
+
+ const second = await new IncomingMessageHandler(message, deps).execute()
+
+ expect(second).toMatchObject({
+ success: true,
+ status: 'completed',
+ response: 'first answer',
+ taskId: task.id,
+ acceptedAttachmentIds: ['file-1', 'image-1'],
+ })
+ expect(deps.taskLifecycle.getStats().total).toBe(1)
+ })
+
+ it('replays them for a duplicate while the original is still processing', async () => {
+ const deps = createMockDeps()
+ const message = messageWithAttachments('msg-att-inflight')
+ const first = new IncomingMessageHandler(message, deps)
+ const firstPromise = first.execute()
+ await new Promise(r => setTimeout(r, 10))
+ const task = deps.messageQueue.dequeue()!
+
+ const second = await new IncomingMessageHandler(message, deps).execute()
+
+ expect(second).toMatchObject({
+ success: true,
+ status: 'pending',
+ taskId: task.id,
+ acceptedAttachmentIds: ['file-1', 'image-1'],
+ })
+ await task.responseCallback!({ response: 'done' })
+ await firstPromise
+ })
+
+ it('does not attach them to the replayed error of a FAILED task', async () => {
+ const deps = createMockDeps()
+ const message = messageWithAttachments('msg-att-failed')
+ const first = new IncomingMessageHandler(message, deps)
+ const firstPromise = first.execute()
+ await new Promise(r => setTimeout(r, 10))
+ const task = deps.messageQueue.dequeue()!
+ deps.messageQueue.failTask(task, {
+ code: 'LLM_INSUFFICIENT_QUOTA',
+ message: 'out of credit',
+ retryable: false,
+ provider: 'openai',
+ })
+ await firstPromise
+
+ const second = await new IncomingMessageHandler(message, deps).execute()
+
+ // Witness: this is the replayed failure of the same task.
+ expect(second.success).toBe(false)
+ expect(second.error?.code).toBe('LLM_INSUFFICIENT_QUOTA')
+ expect(second.taskId).toBe(task.id)
+ expect('acceptedAttachmentIds' in second).toBe(false)
+ })
+
+ it('adds no field for a duplicate of a message without attachments', async () => {
+ const deps = createMockDeps()
+ const message = createTestMessage('msg-att-none')
+ const first = new IncomingMessageHandler(message, deps)
+ first.executeAsync()
+ const task = deps.messageQueue.dequeue()!
+ task.result = { response: 'plain answer', model: 'test-model' }
+ deps.messageQueue.completeTask(task)
+ await task.responseCallback!({ response: 'plain answer' })
+
+ const second = new IncomingMessageHandler(message, deps).executeAsync()
+
+ // Witness: the duplicate replayed the completed outcome.
+ expect(second.status).toBe('completed')
+ expect(second.response).toBe('plain answer')
+ expect('acceptedAttachmentIds' in second).toBe(false)
+ })
+})
+
/**
* Regression: stateless `pendingResults` idle gauge vs C3 recoverability cache.
*
diff --git a/mcp-host/src/agent/__tests__/attachmentRead.integration.test.ts b/mcp-host/src/agent/__tests__/attachmentRead.integration.test.ts
new file mode 100644
index 000000000..ebdc7bd4c
--- /dev/null
+++ b/mcp-host/src/agent/__tests__/attachmentRead.integration.test.ts
@@ -0,0 +1,260 @@
+/**
+ * #666 — a complete task with a `kind:'file'` attachment, through the real
+ * TaskExecutor, tool loop, native registry and safety. Only the model is a
+ * double: it reads the turn context, calls `clerum__attachment_read` and
+ * answers with what the tool returned.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createHash } from 'node:crypto'
+import { config as appConfig } from '../../config'
+import { ConversationManager } from '../../core/conversation/conversation'
+import { SimpleEventEmitter } from '../../core/orchestration/eventEmitter'
+import { ATTACHED_FILES_INSTRUCTION } from '../../core/orchestration/turnContext'
+import { type ChatMessage, FinishReason, type ToolCall } from '../../core/types'
+import { TaskLifecycle } from '../../lifecycle/taskLifecycle'
+import type { SingleTurnProvider } from '../../llm/types'
+import { McpManager } from '../../mcp/manager'
+import type { Task } from '../../queue/types'
+import { validateIncomingAttachments } from '../incomingAttachments'
+import { TaskExecutor, type TaskExecutorDeps } from '../taskExecutor'
+
+const SENTINEL = 'SENTINEL-666-integration'
+const usage = { input_tokens: 1, output_tokens: 1, total_tokens: 2 }
+
+function admittedFile(filename: string, mimeType: string, bytes: Buffer) {
+ const result = validateIncomingAttachments(
+ [
+ {
+ id: 'file-1',
+ kind: 'file',
+ mimeType,
+ detectedMediaType: mimeType,
+ encoding: 'base64',
+ dataBase64: bytes.toString('base64'),
+ filename,
+ sizeBytes: bytes.length,
+ digest: { algorithm: 'sha256', hex: createHash('sha256').update(bytes).digest('hex') },
+ },
+ ],
+ { maxCount: 20, maxBytes: 1_000_000, maxFileBytes: 3_145_728, messageId: 'message-1' }
+ )
+ if (!result.ok) throw new Error(`fixture rejected: ${result.error.code}`)
+ return result.attachments![0]!
+}
+
+function lastUserText(messages: ChatMessage[]): string {
+ const user = [...messages].reverse().find(message => message.role === 'user')
+ if (!user) throw new Error('the provider received no user message')
+ return user.content ?? ''
+}
+
+async function runTask(filename: string, mimeType: string, bytes: Buffer) {
+ const attachment = admittedFile(filename, mimeType, bytes)
+ return { ...(await runTaskWith(attachment)), attachment }
+}
+
+/** Without an attachment the double answers directly; with one it reads it first. */
+async function runTaskWith(attachment: ReturnType<typeof admittedFile> | undefined) {
+ const call: ToolCall = {
+ id: 'read-1',
+ name: 'clerum__attachment_read',
+ arguments: { attachmentId: 'file-1' },
+ }
+ const providerCalls: Array<{ messages: ChatMessage[]; toolNames: string[] }> = []
+ const provider: SingleTurnProvider = {
+ getProviderType: () => 'openai',
+ classifyError: () => {
+ throw new Error('Unexpected provider failure')
+ },
+ completeSingleTurn: async () => {
+ throw new Error('Unexpected non-tool completion')
+ },
+ completeSingleTurnWithTools: async (messages, tools) => {
+ providerCalls.push({
+ messages: structuredClone(messages),
+ toolNames: tools.map(tool => tool.name),
+ })
+ if (providerCalls.length === 1 && attachment) {
+ return { content: null, tool_calls: [call], usage, finish_reason: FinishReason.ToolUse }
+ }
+ const result = messages.find(
+ message => message.role === 'tool' && message.tool_call_id === call.id
+ )
+ return {
+ content: `The tool returned: ${result?.content ?? 'nothing'}`,
+ tool_calls: null,
+ usage,
+ finish_reason: FinishReason.Stop,
+ }
+ },
+ }
+ const task: Task = {
+ id: `attachment-read-${attachment?.filename ?? 'none'}`,
+ source: 'channel',
+ status: 'pending',
+ priority: 'normal',
+ createdAt: new Date(),
+ sourceMessage: {
+ sender: 'authenticated-user',
+ content: 'Analyze the attached file',
+ channelType: 'rpc',
+ channelId: 'isolated-channel',
+ messageId: 'message-1',
+ timestamp: new Date().toISOString(),
+ hostRef: 'fixture-host',
+ ...(attachment ? { attachments: [attachment] } : {}),
+ },
+ conversationHistory: [
+ { role: 'user', content: 'Analyze the attached file', timestamp: new Date() },
+ ],
+ responseCallback: vi.fn(async () => {}),
+ }
+ const lifecycle = new TaskLifecycle()
+ lifecycle.register(task)
+ const deps: TaskExecutorDeps = {
+ conversationManager: new ConversationManager(),
+ llmProvider: provider,
+ mcpManager: new McpManager(),
+ workspaceService: undefined,
+ modelName: 'test-model',
+ approvalConfig: undefined,
+ config: {
+ maxTaskDuration: 300000,
+ maxToolCallsPerTask: 10,
+ autoStart: true,
+ taskDelay: 0,
+ approvalTimeout: 300000,
+ },
+ coreEvents: new SimpleEventEmitter(),
+ cronScheduler: null,
+ taskLifecycle: lifecycle,
+ onApprovalNeeded: vi.fn(),
+ onComplete: vi.fn(),
+ onFail: vi.fn(),
+ dynamicEnvProvider: () => ({}),
+ }
+ const executor = new TaskExecutor(task, deps)
+ await executor.run()
+ return { attachment, call, deps, executor, providerCalls, task }
+}
+
+describe('clerum__attachment_read through a complete task (#666)', () => {
+ const saved = {
+ enableApproval: appConfig.enableApproval,
+ dynamicToolsEnabled: appConfig.dynamicToolsEnabled,
+ promptCacheEnabled: appConfig.promptCacheEnabled,
+ }
+
+ afterEach(() => {
+ Object.assign(appConfig, saved)
+ })
+
+ it('lists the text file, reads it in the same turn and answers with its sentinel', async () => {
+ Object.assign(appConfig, {
+ enableApproval: false,
+ dynamicToolsEnabled: false,
+ promptCacheEnabled: true,
+ })
+ const { attachment, call, deps, executor, providerCalls } = await runTask(
+ 'notes.txt',
+ 'text/plain',
+ Buffer.from(`Quarterly notes. ${SENTINEL}\n`)
+ )
+
+ expect(deps.onFail).not.toHaveBeenCalled()
+ expect(executor.executorState).toBe('completed')
+ expect(providerCalls).toHaveLength(2)
+
+ // Turn 1: the tool is presented and the file is listed, never inlined.
+ const reference = attachment.fileReference!
+ const firstUserText = lastUserText(providerCalls[0]!.messages)
+ expect(providerCalls[0]!.toolNames).toContain('clerum__attachment_read')
+ expect(firstUserText).toContain(
+ `attached_file: id=file-1 name="notes.txt" class=${reference.class} bytes=${reference.byteLength} reader=text\n`
+ )
+ expect(firstUserText).toContain(ATTACHED_FILES_INSTRUCTION)
+ expect(firstUserText).not.toContain(SENTINEL)
+
+ // Turn 2: the tool trace carries the call and its sanitized text result.
+ const second = providerCalls[1]!.messages
+ expect(second.flatMap(message => message.tool_calls ?? []).map(tool => tool.name)).toContain(
+ 'clerum__attachment_read'
+ )
+ const result = second.find(
+ message => message.role === 'tool' && message.tool_call_id === call.id
+ )
+ expect(result?.content).toContain(SENTINEL)
+ expect(result?.content).toContain('"kind":"text"')
+ expect(result?.content).not.toContain('�')
+ expect(deps.onComplete).toHaveBeenCalledTimes(1)
+ })
+
+ it('returns a binary result for a PDF, and the model never sees its bytes', async () => {
+ Object.assign(appConfig, {
+ enableApproval: false,
+ dynamicToolsEnabled: false,
+ promptCacheEnabled: true,
+ })
+ const { attachment, call, deps, executor, providerCalls } = await runTask(
+ 'report.pdf',
+ 'application/pdf',
+ Buffer.from(`%PDF-1.7\n${SENTINEL}\n%%EOF\n`)
+ )
+
+ expect(deps.onFail).not.toHaveBeenCalled()
+ expect(executor.executorState).toBe('completed')
+ expect(providerCalls).toHaveLength(2)
+ expect(lastUserText(providerCalls[0]!.messages)).toContain(
+ `attached_file: id=file-1 name="report.pdf" class=${attachment.fileReference!.class} bytes=${attachment.fileReference!.byteLength} reader=none\n`
+ )
+ const result = providerCalls[1]!.messages.find(
+ message => message.role === 'tool' && message.tool_call_id === call.id
+ )
+ // Witness: the tool answered with the typed binary result.
+ expect(result?.content).toContain('"kind":"binary"')
+ expect(result?.content).toContain('"reason":"no_reader_for_class"')
+ const everything = JSON.stringify(providerCalls.map(entry => entry.messages))
+ expect(everything).not.toContain(SENTINEL)
+ })
+
+ it('lists attached files with the prompt cache off, so the tool stays usable', async () => {
+ Object.assign(appConfig, {
+ enableApproval: false,
+ dynamicToolsEnabled: false,
+ promptCacheEnabled: false,
+ })
+ const { attachment, call, deps, executor, providerCalls } = await runTask(
+ 'notes.txt',
+ 'text/plain',
+ Buffer.from(`Quarterly notes. ${SENTINEL}\n`)
+ )
+
+ expect(deps.onFail).not.toHaveBeenCalled()
+ expect(executor.executorState).toBe('completed')
+ const firstUserText = lastUserText(providerCalls[0]!.messages)
+ expect(firstUserText.startsWith('<turn-context>')).toBe(true)
+ expect(firstUserText).toContain(
+ `attached_file: id=file-1 name="notes.txt" class=${attachment.fileReference!.class} bytes=${attachment.fileReference!.byteLength} reader=text\n`
+ )
+ const result = providerCalls[1]!.messages.find(
+ message => message.role === 'tool' && message.tool_call_id === call.id
+ )
+ expect(result?.content).toContain(SENTINEL)
+ })
+
+ it('adds no turn-context block with the prompt cache off and no attached file', async () => {
+ Object.assign(appConfig, {
+ enableApproval: false,
+ dynamicToolsEnabled: false,
+ promptCacheEnabled: false,
+ })
+ const { deps, executor, providerCalls } = await runTaskWith(undefined)
+
+ // Witness: the task ran and the model received the user's message.
+ expect(deps.onFail).not.toHaveBeenCalled()
+ expect(executor.executorState).toBe('completed')
+ expect(providerCalls).toHaveLength(1)
+ expect(lastUserText(providerCalls[0]!.messages)).toBe('Analyze the attached file')
+ expect(providerCalls[0]!.toolNames).not.toContain('clerum__attachment_read')
+ })
+})
diff --git a/mcp-host/src/agent/__tests__/incomingAdmission.modelSelection.test.ts b/mcp-host/src/agent/__tests__/incomingAdmission.modelSelection.test.ts
index 7733c3a92..fde740772 100644
--- a/mcp-host/src/agent/__tests__/incomingAdmission.modelSelection.test.ts
+++ b/mcp-host/src/agent/__tests__/incomingAdmission.modelSelection.test.ts
@@ -120,7 +120,7 @@ describe('image sends and the session model selection', () => {
)
)
admit = createIncomingAdmission({
- limits: { maxCount: 4, maxBytes: 1_000_000 },
+ limits: { maxCount: 4, maxBytes: 1_000_000, maxFileBytes: 1_000_000 },
queueReady: () => true,
degradedReason: () => null,
hostProvider: () => PROVIDER,
diff --git a/mcp-host/src/agent/__tests__/incomingAdmission.test.ts b/mcp-host/src/agent/__tests__/incomingAdmission.test.ts
index 8ac5e6bad..b78152c3d 100644
--- a/mcp-host/src/agent/__tests__/incomingAdmission.test.ts
+++ b/mcp-host/src/agent/__tests__/incomingAdmission.test.ts
@@ -7,6 +7,7 @@
* the resolver call, or the structured log line the branch had to emit).
*/
import { type Mock, describe, expect, it, vi } from 'vitest'
+import { createHash } from 'node:crypto'
import type { IncomingMessage, MessageResponse, SetModelResult } from '../../server/types'
import { type IncomingAdmissionDeps, createIncomingAdmission } from '../incomingAdmission'
@@ -71,7 +72,7 @@ function makeAdmission(overrides: Partial<IncomingAdmissionDeps> = {}): {
warn: vi.fn<IncomingAdmissionDeps['logger']['warn']>(),
}
const deps: IncomingAdmissionDeps = {
- limits: { maxCount: 4, maxBytes: 1_000_000 },
+ limits: { maxCount: 4, maxBytes: 1_000_000, maxFileBytes: 1_000_000 },
queueReady: () => true,
degradedReason: () => null,
hostProvider: () => 'zai',
@@ -374,3 +375,230 @@ describe('#654 incoming admission gate', () => {
)
})
})
+
+describe('#666 file attachments at admission', () => {
+ const NOTES = Buffer.from('# Notes\n\nSENTINEL-666\n', 'utf8')
+ const UNSUPPORTED = { state: 'unsupported', evidence: CURATED_SUPPORTED.evidence }
+
+ function fileAttachment() {
+ return {
+ id: 'file-1',
+ kind: 'file' as const,
+ mimeType: 'text/markdown',
+ detectedMediaType: 'text/markdown',
+ encoding: 'base64' as const,
+ dataBase64: NOTES.toString('base64'),
+ filename: 'secret-plan.md',
+ sizeBytes: NOTES.length,
+ digest: {
+ algorithm: 'sha256' as const,
+ hex: createHash('sha256').update(NOTES).digest('hex'),
+ },
+ }
+ }
+ // The wire shape is wider than the Host's `Attachment`; the gate validates it.
+ const fileMessage = (overrides: Partial<IncomingMessage> = {}) =>
+ message({ attachments: [fileAttachment() as never], ...overrides })
+
+ const admittedLogs = (spies: Spies) =>
+ spies.info.mock.calls
+ .map(call => call[0] as Record<string, unknown>)
+ .filter(fields => fields.event === 'attachment_admitted')
+
+ it('dispatches a file-only message on a model that cannot read images', async () => {
+ const { admit, spies } = makeAdmission({
+ resolveImageInput: vi.fn(() => ({ capability: UNSUPPORTED })),
+ })
+
+ const response = await admit(fileMessage())
+
+ expect(response).toEqual({
+ success: true,
+ taskId: 't-1',
+ status: 'pending',
+ acceptedAttachmentIds: ['file-1'],
+ })
+ // Witness: the task received the file with the reference the Host derived.
+ expect(spies.dispatch).toHaveBeenCalledTimes(1)
+ const [dispatched] = spies.dispatch.mock.calls[0][0].attachments ?? []
+ expect(dispatched).toMatchObject({
+ id: 'file-1',
+ kind: 'file',
+ fileReference: { class: 'markdown', reader: 'text', byteLength: NOTES.length },
+ })
+ // A file never reaches the image gate, so its verdict cannot refuse the turn.
+ expect(spies.resolveImageInput).not.toHaveBeenCalled()
+ expect(refusalLogs(spies)).toHaveLength(0)
+ })
+
+ it('still refuses an image sent with a file on a model that cannot read images', async () => {
+ const { admit, spies } = makeAdmission({
+ resolveImageInput: vi.fn(() => ({ capability: UNSUPPORTED })),
+ })
+
+ const response = await admit(
+ message({ attachments: [imageAttachment(), fileAttachment() as never] })
+ )
+
+ expect(response).toMatchObject({
+ success: false,
+ error: { code: 'LLM_IMAGE_INPUT_UNSUPPORTED', retryable: false, provider: 'zai' },
+ })
+ expect('acceptedAttachmentIds' in response).toBe(false)
+ // Witness: the image gate ran and recorded the refusal.
+ expect(spies.resolveImageInput).toHaveBeenCalledWith('zai', 'glm-5.3-flash')
+ expect(refusalLogs(spies)).toEqual([
+ expect.objectContaining({ code: 'LLM_IMAGE_INPUT_UNSUPPORTED' }),
+ ])
+ expect(spies.dispatch).toHaveBeenCalledTimes(0)
+ })
+
+ it('does not refuse a file-only message on an invalid revision', async () => {
+ const applySessionModelSelection = vi.fn(async () => ({
+ ok: true as const,
+ provider: 'zai',
+ model: 'glm-5.3-flash',
+ modelSelectionRevision: 2,
+ }))
+ const { admit, spies } = makeAdmission({ applySessionModelSelection })
+
+ const response = await admit(
+ fileMessage({ model: 'glm-5.3-flash', modelSelectionRevision: -1 })
+ )
+
+ expect(response).toMatchObject({
+ success: true,
+ acceptedAttachmentIds: ['file-1'],
+ modelSelectionRevision: 2,
+ })
+ // Witness: the turn was dispatched, and the selection was written as a
+ // text-only piggyback (no CAS revision, no skip-when-effective).
+ expect(spies.dispatch).toHaveBeenCalledTimes(1)
+ expect(applySessionModelSelection).toHaveBeenCalledWith(
+ 'user-1',
+ 'agent-1',
+ 'chat-1',
+ 'glm-5.3-flash',
+ undefined,
+ undefined
+ )
+ expect(refusalLogs(spies)).toHaveLength(0)
+ })
+
+ it('admits a file on a channel other than rpc through the same validation', async () => {
+ const { admit, spies } = makeAdmission()
+
+ const response = await admit(fileMessage({ channelType: 'telegram' }))
+
+ expect(response).toMatchObject({ success: true, acceptedAttachmentIds: ['file-1'] })
+ expect(spies.dispatch).toHaveBeenCalledTimes(1)
+ expect(spies.dispatch.mock.calls[0][0].attachments?.[0]?.fileReference?.source).toEqual({
+ kind: 'attachment',
+ attachmentId: 'file-1',
+ messageId: 'msg-1',
+ })
+ })
+
+ it('returns the validator error and never dispatches an invalid file', async () => {
+ const { admit, spies } = makeAdmission()
+ const tampered = { ...fileAttachment(), digest: { algorithm: 'sha256', hex: '0'.repeat(64) } }
+
+ // Control: the untampered file is admitted by the same gate.
+ expect(await admit(fileMessage({ messageId: 'msg-control' }))).toMatchObject({ success: true })
+ const response = await admit(message({ attachments: [tampered as never] }))
+
+ expect(response).toEqual({
+ success: false,
+ error: {
+ code: 'FILE_ATTACHMENT_DIGEST_MISMATCH',
+ message: 'A file does not match its declared digest. Attach the original file again.',
+ retryable: false,
+ provider: 'unknown',
+ },
+ })
+ expect(spies.dispatch).toHaveBeenCalledTimes(1)
+ })
+
+ describe('acceptedAttachmentIds', () => {
+ it('names every accepted image and file, on a sync response and on a promised one', async () => {
+ const sync = makeAdmission()
+ const promised = makeAdmission({
+ dispatch: vi.fn(async () => ({
+ success: true,
+ taskId: 't-2',
+ status: 'completed' as const,
+ })),
+ })
+ const both = { attachments: [imageAttachment(), fileAttachment() as never] }
+
+ expect(await sync.admit(message(both))).toMatchObject({
+ success: true,
+ taskId: 't-1',
+ acceptedAttachmentIds: ['image-1', 'file-1'],
+ })
+ expect(await promised.admit(message(both))).toMatchObject({
+ success: true,
+ taskId: 't-2',
+ acceptedAttachmentIds: ['image-1', 'file-1'],
+ })
+ })
+
+ it('is absent on a text-only message and on a dispatch failure', async () => {
+ const text = makeAdmission()
+ const failed = makeAdmission({
+ dispatch: vi.fn(() => ({
+ success: false,
+ error: { code: 'X', message: 'x', retryable: false, provider: 'zai' },
+ })),
+ })
+
+ const textResponse = await text.admit(message())
+ const failedResponse = await failed.admit(fileMessage())
+
+ // Witnesses: both turns were dispatched and answered.
+ expect(text.spies.dispatch).toHaveBeenCalledTimes(1)
+ expect(textResponse).toMatchObject({ success: true, taskId: 't-1' })
+ expect(failed.spies.dispatch).toHaveBeenCalledTimes(1)
+ expect(failedResponse).toMatchObject({ success: false, error: { code: 'X' } })
+ expect('acceptedAttachmentIds' in textResponse).toBe(false)
+ expect('acceptedAttachmentIds' in failedResponse).toBe(false)
+ })
+ })
+
+ it('logs classes, sizes and a digest prefix, never the name, bytes or text', async () => {
+ const { admit, spies } = makeAdmission()
+
+ await admit(fileMessage())
+
+ const digestHex = fileAttachment().digest.hex
+ // Witness first: the event was emitted with the fields it must carry.
+ expect(admittedLogs(spies)).toEqual([
+ {
+ event: 'attachment_admitted',
+ channel: 'rpc',
+ attachmentCount: 1,
+ fileClasses: ['markdown'],
+ byteLength: NOTES.length,
+ digestPrefixes: [digestHex.slice(0, 8)],
+ },
+ ])
+ const logged = JSON.stringify([...spies.info.mock.calls, ...spies.warn.mock.calls])
+ expect(logged).not.toContain('secret-plan')
+ expect(logged).not.toContain(NOTES.toString('base64'))
+ expect(logged).not.toContain('SENTINEL-666')
+ expect(logged).not.toContain(digestHex)
+ })
+
+ it('emits no attachment_admitted event for an image-only message', async () => {
+ const { admit, spies } = makeAdmission()
+
+ await admit(imageMessage())
+
+ // Witness: the same message was received and logged.
+ expect(spies.info).toHaveBeenCalledWith(
+ { channel: 'rpc', attachmentCount: 1 },
+ 'Received message'
+ )
+ expect(admittedLogs(spies)).toHaveLength(0)
+ })
+})
diff --git a/mcp-host/src/agent/__tests__/incomingAttachments.test.ts b/mcp-host/src/agent/__tests__/incomingAttachments.test.ts
new file mode 100644
index 000000000..c755416c6
--- /dev/null
+++ b/mcp-host/src/agent/__tests__/incomingAttachments.test.ts
@@ -0,0 +1,385 @@
+import { describe, expect, it } from 'vitest'
+import { createHash } from 'node:crypto'
+import { INCOMING_ATTACHMENT_MAX_COUNT, validateIncomingAttachments } from '../incomingAttachments'
+
+// The #669 image cases below are unchanged. They moved with the validator and
+// now also pass the file options (issue #666), which the image branch never reads.
+const fileOptions = { maxFileBytes: 64, messageId: 'message-1' }
+const limits = { maxCount: 2, maxBytes: 10, ...fileOptions }
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+const JPEG_SIGNATURE = Buffer.from([0xff, 0xd8, 0xff])
+// Bytes exercise the ingress encoding/size contract and the declared-type
+// check; they are still not a decodable image.
+const image = {
+ id: 'image-1',
+ kind: 'image',
+ mimeType: 'image/png',
+ encoding: 'base64',
+ dataBase64: PNG_SIGNATURE.toString('base64'),
+}
+
+describe('visual input validation', () => {
+ it('preserves text-only messages and valid image bytes', () => {
+ expect(validateIncomingAttachments(undefined, limits)).toEqual({
+ ok: true,
+ attachments: undefined,
+ fileReferences: [],
+ })
+ expect(validateIncomingAttachments([image], limits)).toEqual({
+ ok: true,
+ attachments: [image],
+ fileReferences: [],
+ })
+ const jpeg = {
+ ...image,
+ mimeType: 'image/jpeg',
+ dataBase64: JPEG_SIGNATURE.toString('base64'),
+ }
+ expect(validateIncomingAttachments([jpeg], limits)).toEqual({
+ ok: true,
+ attachments: [jpeg],
+ fileReferences: [],
+ })
+ })
+ it.each([
+ 'not-a-list',
+ [null],
+ [{ ...image, mimeType: 'image/gif' }],
+ [{ ...image, dataBase64: '' }],
+ [{ ...image, dataBase64: 'YQ=' }],
+ [{ ...image, dataBase64: 'YR==' }],
+ [image, image, image],
+ [image, { ...image, encoding: 'url' }],
+ ])('rejects the whole message for invalid input %#', raw => {
+ const result = validateIncomingAttachments(raw, limits)
+ expect(result).toMatchObject({
+ ok: false,
+ error: { code: 'LLM_INVALID_ATTACHMENT', retryable: false },
+ })
+ expect(result).not.toHaveProperty('attachments')
+ })
+ describe('size limit (maxBytes = 10)', () => {
+ // A well-formed PNG of exactly `size` bytes, so a rejection can only come
+ // from the size checks: the shape, re-encoding and signature checks pass.
+ const pngOfSize = (size: number) =>
+ Buffer.concat([PNG_SIGNATURE, Buffer.alloc(size - PNG_SIGNATURE.length)]).toString('base64')
+ // The pre-decode bound on the base64 length for maxBytes = 10.
+ const encodedBound = Math.ceil(limits.maxBytes / 3) * 4
+ const SIZE_MESSAGE = 'An image exceeds the attachment size limit.'
+
+ it('accepts a PNG of exactly maxBytes (control)', () => {
+ const dataBase64 = pngOfSize(10)
+ expect(validateIncomingAttachments([{ ...image, dataBase64 }], limits)).toEqual({
+ ok: true,
+ attachments: [{ ...image, dataBase64 }],
+ fileReferences: [],
+ })
+ })
+
+ it.each([11, 12])(
+ 'rejects a %i-byte PNG on its decoded size (its base64 fits the pre-decode bound)',
+ size => {
+ const dataBase64 = pngOfSize(size)
+ // Precondition: only the decoded-size check can reject this input.
+ expect(dataBase64.length).toBeLessThanOrEqual(encodedBound)
+ const result = validateIncomingAttachments([{ ...image, dataBase64 }], limits)
+ expect(result).toEqual({
+ ok: false,
+ error: {
+ code: 'LLM_INVALID_ATTACHMENT',
+ message: SIZE_MESSAGE,
+ retryable: false,
+ provider: 'unknown',
+ },
+ })
+ }
+ )
+
+ it('rejects a 13-byte PNG whose base64 already exceeds the pre-decode bound', () => {
+ const dataBase64 = pngOfSize(13)
+ expect(dataBase64.length).toBeGreaterThan(encodedBound)
+ const result = validateIncomingAttachments([{ ...image, dataBase64 }], limits)
+ expect(result.ok === false && result.error.message).toBe(SIZE_MESSAGE)
+ })
+
+ it('rejects oversized input before decoding it', () => {
+ // Too long for the bound AND not canonical base64 (length is not a
+ // multiple of 4). Only the pre-decode length check can answer with the
+ // size message; without it the shape check answers "invalid base64".
+ const dataBase64 = 'A'.repeat(encodedBound + 5)
+ const result = validateIncomingAttachments([{ ...image, dataBase64 }], limits)
+ expect(result.ok === false && result.error.message).toBe(SIZE_MESSAGE)
+ })
+ })
+
+ it('does not trust caller-supplied attachment metadata', () => {
+ expect(
+ validateIncomingAttachments(
+ [{ ...image, sourceTool: 'workflow_result', extra: true }],
+ limits
+ )
+ ).toEqual({ ok: true, attachments: [image], fileReferences: [] })
+ })
+
+ it('accepts a valid image whose base64 exceeds the old regex stack limit', () => {
+ // The grouped-quantifier base64 regex allocates one V8 backtrack frame per
+ // 4-character group and throws RangeError above ~4.47M characters. 3.5 MiB
+ // of image is ~4.67M characters, so this input reproduces that crash.
+ const bytes = Buffer.alloc(3_500_000)
+ PNG_SIGNATURE.copy(bytes, 0)
+ const dataBase64 = bytes.toString('base64')
+ expect(dataBase64.length).toBeGreaterThan(4_470_000)
+ const result = validateIncomingAttachments([{ ...image, dataBase64 }], {
+ maxCount: 2,
+ maxBytes: 4_000_000,
+ ...fileOptions,
+ })
+ expect(result.ok).toBe(true)
+ expect(result.ok && result.attachments?.[0]?.dataBase64.length).toBe(dataBase64.length)
+ })
+
+ it.each(['AAA', 'AAAA=AAA', 'A===', 'AA=A'])(
+ 'rejects the non-canonical base64 shape %s without decoding',
+ dataBase64 => {
+ const result = validateIncomingAttachments([{ ...image, dataBase64 }], {
+ maxCount: 2,
+ maxBytes: 4_000_000,
+ ...fileOptions,
+ })
+ expect(result).toMatchObject({
+ ok: false,
+ error: { code: 'LLM_INVALID_ATTACHMENT', retryable: false },
+ })
+ expect(result.ok === false && result.error.message).toContain('invalid base64 data')
+ }
+ )
+
+ it('rejects bytes whose signature does not match the declared mime', () => {
+ const result = validateIncomingAttachments(
+ [{ ...image, mimeType: 'image/jpeg', dataBase64: PNG_SIGNATURE.toString('base64') }],
+ limits
+ )
+ expect(result).toMatchObject({
+ ok: false,
+ error: { code: 'LLM_INVALID_ATTACHMENT', retryable: false },
+ })
+ expect(result.ok === false && result.error.message).toContain(
+ 'does not match its declared type'
+ )
+ })
+
+ it('admits 20 images per message and rejects the 21st', () => {
+ expect(INCOMING_ATTACHMENT_MAX_COUNT).toBe(20)
+ const hostLimits = { maxCount: INCOMING_ATTACHMENT_MAX_COUNT, maxBytes: 10, ...fileOptions }
+ const batch = (count: number) =>
+ Array.from({ length: count }, (_, index) => ({ ...image, id: `image-${index + 1}` }))
+
+ const admitted = validateIncomingAttachments(batch(20), hostLimits)
+ expect(admitted.ok && admitted.attachments?.length).toBe(20)
+
+ const rejected = validateIncomingAttachments(batch(21), hostLimits)
+ expect(rejected).toMatchObject({ ok: false, error: { code: 'LLM_INVALID_ATTACHMENT' } })
+ expect(rejected.ok === false && rejected.error.message).toContain('Too many image attachments')
+ })
+})
+
+describe('file attachment validation (issue #666)', () => {
+ const sha256 = (bytes: Buffer) => createHash('sha256').update(bytes).digest('hex')
+ const fileOf = (
+ content: Buffer | string,
+ filename: string,
+ mimeType: string,
+ detectedMediaType: string
+ ) => {
+ const bytes = Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8')
+ return {
+ id: `file-${filename}`,
+ kind: 'file',
+ mimeType,
+ detectedMediaType,
+ encoding: 'base64',
+ dataBase64: bytes.toString('base64'),
+ filename,
+ sizeBytes: bytes.length,
+ digest: { algorithm: 'sha256', hex: sha256(bytes) },
+ }
+ }
+ const notes = fileOf('# Notes\n\nplain text\n', 'notes.md', 'text/markdown', 'text/markdown')
+
+ const admitOne = (raw: unknown) => {
+ const result = validateIncomingAttachments([raw], limits)
+ if (!result.ok) throw new Error(`expected admission, got ${result.error.code}`)
+ expect(result.attachments).toHaveLength(1)
+ expect(result.fileReferences).toHaveLength(1)
+ return { attachment: result.attachments![0]!, reference: result.fileReferences[0]! }
+ }
+
+ it('admits a text file and derives its reference from the host-verified bytes', () => {
+ const { attachment, reference } = admitOne(notes)
+ expect(reference).toEqual({
+ schemaVersion: 1,
+ id: `att:message-1:file-notes.md@sha256:${notes.digest.hex}`,
+ source: { kind: 'attachment', attachmentId: 'file-notes.md', messageId: 'message-1' },
+ name: 'notes.md',
+ declaredMediaType: 'text/markdown',
+ detectedMediaType: 'text/markdown',
+ class: 'markdown',
+ detection: 'text_utf8',
+ mismatch: false,
+ byteLength: notes.sizeBytes,
+ digest: notes.digest,
+ textReadable: true,
+ reader: 'text',
+ modelImageInput: 'unsupported',
+ })
+ expect(attachment).toEqual({
+ id: 'file-notes.md',
+ kind: 'file',
+ mimeType: 'text/markdown',
+ encoding: 'base64',
+ dataBase64: notes.dataBase64,
+ filename: 'notes.md',
+ sizeBytes: notes.sizeBytes,
+ detectedMediaType: 'text/markdown',
+ digest: notes.digest,
+ fileReference: reference,
+ })
+ })
+
+ it.each([
+ [
+ 'an .svg as readable text',
+ fileOf(
+ '<svg xmlns="http://www.w3.org/2000/svg"></svg>',
+ 'logo.svg',
+ 'image/svg+xml',
+ 'image/svg+xml'
+ ),
+ { class: 'svg', reader: 'text', mismatch: false },
+ ],
+ [
+ 'a .bin as unreadable',
+ fileOf(
+ Buffer.from([0x00, 0x01, 0x02, 0xff, 0xfe, 0x00]),
+ 'blob.bin',
+ 'application/octet-stream',
+ 'application/octet-stream'
+ ),
+ { class: 'binary_unsupported', reader: 'none', mismatch: false },
+ ],
+ [
+ 'a .txt carrying PDF bytes as a pdf mismatch',
+ fileOf('%PDF-1.7\n%âãÏÓ\n', 'report.txt', 'text/plain', 'text/plain'),
+ { class: 'pdf', reader: 'none', mismatch: true },
+ ],
+ [
+ 'a PNG sent as kind:file without a reader',
+ fileOf(PNG_SIGNATURE, 'photo.png', 'image/png', 'image/png'),
+ { class: 'png', reader: 'none', mismatch: false },
+ ],
+ ])('admits %s, never rejecting on type', (_label, file, expected) => {
+ const { attachment, reference } = admitOne(file)
+ expect(reference).toMatchObject(expected)
+ expect(attachment.kind).toBe('file')
+ })
+
+ it('lets the host detection win over the declared one and records the disagreement', () => {
+ // The client claimed plain text; the host detects markdown from the extension.
+ const { attachment, reference } = admitOne({ ...notes, detectedMediaType: 'text/plain' })
+ expect(reference).toMatchObject({
+ class: 'markdown',
+ detectedMediaType: 'text/markdown',
+ mismatch: true,
+ })
+ expect(attachment.detectedMediaType).toBe('text/markdown')
+ })
+
+ it('admits a zero-byte file', () => {
+ const { reference } = admitOne(fileOf('', 'empty.txt', 'text/plain', 'text/plain'))
+ expect(reference).toMatchObject({ byteLength: 0, reader: 'text' })
+ })
+
+ it('admits images and files together and returns only the file references', () => {
+ const result = validateIncomingAttachments([image, notes], limits)
+ expect(result.ok).toBe(true)
+ expect(result.ok && result.attachments?.map(a => a.kind)).toEqual(['image', 'file'])
+ expect(result.ok && result.fileReferences.map(r => r.source)).toEqual([
+ { kind: 'attachment', attachmentId: 'file-notes.md', messageId: 'message-1' },
+ ])
+ })
+
+ it('counts images and files against one ceiling of 20', () => {
+ const hostLimits = { maxCount: INCOMING_ATTACHMENT_MAX_COUNT, maxBytes: 10, ...fileOptions }
+ const mixed = (count: number) =>
+ Array.from({ length: count }, (_, index) =>
+ index % 2 ? { ...notes, id: `file-${index}` } : { ...image, id: `image-${index}` }
+ )
+ const admitted = validateIncomingAttachments(mixed(20), hostLimits)
+ expect(admitted.ok && admitted.attachments?.length).toBe(20)
+ expect(admitted.ok && admitted.fileReferences.length).toBe(10)
+
+ const rejected = validateIncomingAttachments(mixed(21), hostLimits)
+ expect(rejected).toEqual({
+ ok: false,
+ error: {
+ code: 'LLM_INVALID_ATTACHMENT',
+ message: 'Too many attachments. Remove an attachment and try again.',
+ retryable: false,
+ provider: 'unknown',
+ },
+ })
+ })
+
+ const tooBig = fileOf('x'.repeat(65), 'big.txt', 'text/plain', 'text/plain')
+ it.each([
+ ['FILE_ATTACHMENT_INVALID', 'a missing digest', { ...notes, digest: undefined }],
+ [
+ 'FILE_ATTACHMENT_INVALID',
+ 'an uppercase digest',
+ { ...notes, digest: { algorithm: 'sha256', hex: notes.digest.hex.toUpperCase() } },
+ ],
+ ['FILE_ATTACHMENT_INVALID', 'a missing filename', { ...notes, filename: undefined }],
+ ['FILE_ATTACHMENT_INVALID', 'a url encoding', { ...notes, encoding: 'url' }],
+ [
+ 'FILE_ATTACHMENT_INVALID',
+ 'non-canonical base64',
+ { ...notes, dataBase64: 'YR==', sizeBytes: 1 },
+ ],
+ [
+ 'FILE_ATTACHMENT_INVALID',
+ 'a declared size the bytes contradict',
+ { ...notes, sizeBytes: notes.sizeBytes + 1 },
+ ],
+ [
+ 'FILE_ATTACHMENT_INVALID',
+ 'a name with a path separator',
+ { ...notes, filename: 'dir/notes.md' },
+ ],
+ ['FILE_ATTACHMENT_TOO_LARGE', 'decoded bytes over maxFileBytes', tooBig],
+ ['FILE_ATTACHMENT_TOO_LARGE', 'a declared size over maxFileBytes', { ...notes, sizeBytes: 65 }],
+ [
+ 'FILE_ATTACHMENT_TOO_LARGE',
+ 'base64 over the pre-decode bound',
+ { ...notes, dataBase64: 'A'.repeat(Math.ceil(64 / 3) * 4 + 5) },
+ ],
+ [
+ 'FILE_ATTACHMENT_DIGEST_MISMATCH',
+ 'a digest of other bytes',
+ { ...notes, digest: { algorithm: 'sha256', hex: sha256(Buffer.from('other')) } },
+ ],
+ ])('rejects the whole message with %s for %s', (code, _label, file) => {
+ // Control: the same message without the bad file is admitted.
+ expect(validateIncomingAttachments([image], limits).ok).toBe(true)
+ const result = validateIncomingAttachments([image, file], limits)
+ expect(result).toMatchObject({
+ ok: false,
+ error: { code, retryable: false, provider: 'unknown' },
+ })
+ expect(result).not.toHaveProperty('attachments')
+ })
+
+ it('keeps the #669 rejection for an unknown kind', () => {
+ const result = validateIncomingAttachments([{ ...notes, kind: 'document' }], limits)
+ expect(result).toMatchObject({ ok: false, error: { code: 'LLM_INVALID_ATTACHMENT' } })
+ })
+})
diff --git a/mcp-host/src/agent/__tests__/incomingImageAttachments.test.ts b/mcp-host/src/agent/__tests__/incomingImageAttachments.test.ts
deleted file mode 100644
index d48d0b16c..000000000
--- a/mcp-host/src/agent/__tests__/incomingImageAttachments.test.ts
+++ /dev/null
@@ -1,177 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import {
- INCOMING_IMAGE_MAX_COUNT,
- validateIncomingImageAttachments,
-} from '../incomingImageAttachments'
-
-const limits = { maxCount: 2, maxBytes: 10 }
-const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
-const JPEG_SIGNATURE = Buffer.from([0xff, 0xd8, 0xff])
-// Bytes exercise the ingress encoding/size contract and the declared-type
-// check; they are still not a decodable image.
-const image = {
- id: 'image-1',
- kind: 'image',
- mimeType: 'image/png',
- encoding: 'base64',
- dataBase64: PNG_SIGNATURE.toString('base64'),
-}
-
-describe('visual input validation', () => {
- it('preserves text-only messages and valid image bytes', () => {
- expect(validateIncomingImageAttachments(undefined, limits)).toEqual({
- ok: true,
- attachments: undefined,
- })
- expect(validateIncomingImageAttachments([image], limits)).toEqual({
- ok: true,
- attachments: [image],
- })
- const jpeg = {
- ...image,
- mimeType: 'image/jpeg',
- dataBase64: JPEG_SIGNATURE.toString('base64'),
- }
- expect(validateIncomingImageAttachments([jpeg], limits)).toEqual({
- ok: true,
- attachments: [jpeg],
- })
- })
- it.each([
- 'not-a-list',
- [null],
- [{ ...image, mimeType: 'image/gif' }],
- [{ ...image, dataBase64: '' }],
- [{ ...image, dataBase64: 'YQ=' }],
- [{ ...image, dataBase64: 'YR==' }],
- [image, image, image],
- [image, { ...image, encoding: 'url' }],
- ])('rejects the whole message for invalid input %#', raw => {
- const result = validateIncomingImageAttachments(raw, limits)
- expect(result).toMatchObject({
- ok: false,
- error: { code: 'LLM_INVALID_ATTACHMENT', retryable: false },
- })
- expect(result).not.toHaveProperty('attachments')
- })
- describe('size limit (maxBytes = 10)', () => {
- // A well-formed PNG of exactly `size` bytes, so a rejection can only come
- // from the size checks: the shape, re-encoding and signature checks pass.
- const pngOfSize = (size: number) =>
- Buffer.concat([PNG_SIGNATURE, Buffer.alloc(size - PNG_SIGNATURE.length)]).toString('base64')
- // The pre-decode bound on the base64 length for maxBytes = 10.
- const encodedBound = Math.ceil(limits.maxBytes / 3) * 4
- const SIZE_MESSAGE = 'An image exceeds the attachment size limit.'
-
- it('accepts a PNG of exactly maxBytes (control)', () => {
- const dataBase64 = pngOfSize(10)
- expect(validateIncomingImageAttachments([{ ...image, dataBase64 }], limits)).toEqual({
- ok: true,
- attachments: [{ ...image, dataBase64 }],
- })
- })
-
- it.each([11, 12])(
- 'rejects a %i-byte PNG on its decoded size (its base64 fits the pre-decode bound)',
- size => {
- const dataBase64 = pngOfSize(size)
- // Precondition: only the decoded-size check can reject this input.
- expect(dataBase64.length).toBeLessThanOrEqual(encodedBound)
- const result = validateIncomingImageAttachments([{ ...image, dataBase64 }], limits)
- expect(result).toEqual({
- ok: false,
- error: {
- code: 'LLM_INVALID_ATTACHMENT',
- message: SIZE_MESSAGE,
- retryable: false,
- provider: 'unknown',
- },
- })
- }
- )
-
- it('rejects a 13-byte PNG whose base64 already exceeds the pre-decode bound', () => {
- const dataBase64 = pngOfSize(13)
- expect(dataBase64.length).toBeGreaterThan(encodedBound)
- const result = validateIncomingImageAttachments([{ ...image, dataBase64 }], limits)
- expect(result.ok === false && result.error.message).toBe(SIZE_MESSAGE)
- })
-
- it('rejects oversized input before decoding it', () => {
- // Too long for the bound AND not canonical base64 (length is not a
- // multiple of 4). Only the pre-decode length check can answer with the
- // size message; without it the shape check answers "invalid base64".
- const dataBase64 = 'A'.repeat(encodedBound + 5)
- const result = validateIncomingImageAttachments([{ ...image, dataBase64 }], limits)
- expect(result.ok === false && result.error.message).toBe(SIZE_MESSAGE)
- })
- })
-
- it('does not trust caller-supplied attachment metadata', () => {
- expect(
- validateIncomingImageAttachments(
- [{ ...image, sourceTool: 'workflow_result', extra: true }],
- limits
- )
- ).toEqual({ ok: true, attachments: [image] })
- })
-
- it('accepts a valid image whose base64 exceeds the old regex stack limit', () => {
- // The grouped-quantifier base64 regex allocates one V8 backtrack frame per
- // 4-character group and throws RangeError above ~4.47M characters. 3.5 MiB
- // of image is ~4.67M characters, so this input reproduces that crash.
- const bytes = Buffer.alloc(3_500_000)
- PNG_SIGNATURE.copy(bytes, 0)
- const dataBase64 = bytes.toString('base64')
- expect(dataBase64.length).toBeGreaterThan(4_470_000)
- const result = validateIncomingImageAttachments([{ ...image, dataBase64 }], {
- maxCount: 2,
- maxBytes: 4_000_000,
- })
- expect(result.ok).toBe(true)
- expect(result.ok && result.attachments?.[0]?.dataBase64.length).toBe(dataBase64.length)
- })
-
- it.each(['AAA', 'AAAA=AAA', 'A===', 'AA=A'])(
- 'rejects the non-canonical base64 shape %s without decoding',
- dataBase64 => {
- const result = validateIncomingImageAttachments([{ ...image, dataBase64 }], {
- maxCount: 2,
- maxBytes: 4_000_000,
- })
- expect(result).toMatchObject({
- ok: false,
- error: { code: 'LLM_INVALID_ATTACHMENT', retryable: false },
- })
- expect(result.ok === false && result.error.message).toContain('invalid base64 data')
- }
- )
-
- it('rejects bytes whose signature does not match the declared mime', () => {
- const result = validateIncomingImageAttachments(
- [{ ...image, mimeType: 'image/jpeg', dataBase64: PNG_SIGNATURE.toString('base64') }],
- limits
- )
- expect(result).toMatchObject({
- ok: false,
- error: { code: 'LLM_INVALID_ATTACHMENT', retryable: false },
- })
- expect(result.ok === false && result.error.message).toContain(
- 'does not match its declared type'
- )
- })
-
- it('admits 20 images per message and rejects the 21st', () => {
- expect(INCOMING_IMAGE_MAX_COUNT).toBe(20)
- const hostLimits = { maxCount: INCOMING_IMAGE_MAX_COUNT, maxBytes: 10 }
- const batch = (count: number) =>
- Array.from({ length: count }, (_, index) => ({ ...image, id: `image-${index + 1}` }))
-
- const admitted = validateIncomingImageAttachments(batch(20), hostLimits)
- expect(admitted.ok && admitted.attachments?.length).toBe(20)
-
- const rejected = validateIncomingImageAttachments(batch(21), hostLimits)
- expect(rejected).toMatchObject({ ok: false, error: { code: 'LLM_INVALID_ATTACHMENT' } })
- expect(rejected.ok === false && rejected.error.message).toContain('Too many image attachments')
- })
-})
diff --git a/mcp-host/src/agent/incomingAdmission.ts b/mcp-host/src/agent/incomingAdmission.ts
index bb1e9be09..f1eae1126 100644
--- a/mcp-host/src/agent/incomingAdmission.ts
+++ b/mcp-host/src/agent/incomingAdmission.ts
@@ -17,7 +17,7 @@ import {
} from '../llm/imageInput'
import type { IncomingMessage, MessageResponse, SetModelResult } from '../server/types'
import { serializeSessionKey } from '../session/types.js'
-import { validateIncomingImageAttachments } from './incomingImageAttachments'
+import { type IncomingAttachmentLimits, validateIncomingAttachments } from './incomingAttachments'
import type { SessionModelSelectionOptions } from './sessionModelSelection'
/** The model a task would actually run on, as `resolveTaskModel` reports it. */
@@ -34,7 +34,8 @@ interface AdmissionImageFacts {
/** Live process state the gate reads. Every member is injected so the gate is
* testable without booting the Host. */
export interface IncomingAdmissionDeps {
- limits: { maxCount: number; maxBytes: number }
+ /** The message id is taken from each message, not configured. */
+ limits: Omit<IncomingAttachmentLimits, 'messageId'>
/** False while the message queue is not initialized yet. */
queueReady: () => boolean
/** Non-null while the Host refuses new tasks (missing LLM key, …). */
@@ -77,10 +78,17 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAd
message: IncomingMessage,
options?: { async?: boolean }
): MessageResponse | Promise<MessageResponse> {
- const validated = validateIncomingImageAttachments(message.attachments, deps.limits)
+ const validated = validateIncomingAttachments(message.attachments, {
+ ...deps.limits,
+ messageId: message.messageId,
+ })
if (!validated.ok) return { success: false, error: validated.error }
- const hasAttachments = Boolean(validated.attachments?.length)
+ // Only images engage the image-capability gate, the revision check and the
+ // visual model selection write. A file-only message runs on any model: the
+ // model reads it through a tool, not as image input (issue #666).
+ const hasImageAttachments = Boolean(validated.attachments?.some(a => a.kind === 'image'))
+ const acceptedAttachmentIds = validated.attachments?.map(a => a.id) ?? []
/** One structured line per refusal, so an operator can tell WHY a turn was
* dropped without the payload ever reaching the log. */
@@ -103,7 +111,7 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAd
}
if (
- hasAttachments &&
+ hasImageAttachments &&
message.modelSelectionRevision !== undefined &&
(!Number.isSafeInteger(message.modelSelectionRevision) || message.modelSelectionRevision < 0)
) {
@@ -139,6 +147,21 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAd
},
'Received message'
)
+ if (validated.fileReferences.length) {
+ // Classes, sizes and a digest prefix only: never the file name, the
+ // bytes or any decoded text.
+ deps.logger.info(
+ {
+ event: 'attachment_admitted',
+ channel: normalizedMessage.channelType,
+ attachmentCount: acceptedAttachmentIds.length,
+ fileClasses: validated.fileReferences.map(ref => ref.class),
+ byteLength: validated.fileReferences.reduce((sum, ref) => sum + ref.byteLength, 0),
+ digestPrefixes: validated.fileReferences.map(ref => ref.digest?.hex.slice(0, 8)),
+ },
+ 'Host runtime event'
+ )
+ }
let acceptedVisualSelection: Record<string, string> | undefined
if (!deps.queueReady()) {
@@ -169,7 +192,19 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAd
}
}
- const dispatchMessage = () => deps.dispatch(normalizedMessage, options)
+ // A successful response names every attachment the Host accepted, on the
+ // sync response and on the async ack alike. Its absence on a send that
+ // carried attachments is how a client detects a Host that dropped them.
+ const withAcceptedAttachments = (response: MessageResponse): MessageResponse =>
+ response.success && acceptedAttachmentIds.length
+ ? { ...response, acceptedAttachmentIds }
+ : response
+ const dispatchMessage = (): MessageResponse | Promise<MessageResponse> => {
+ const response = deps.dispatch(normalizedMessage, options)
+ return response instanceof Promise
+ ? response.then(withAcceptedAttachments)
+ : withAcceptedAttachments(response)
+ }
/** Decide whether the model a task resolved to can read this message's
* images. The refusal is the exact response the Desktop receives, so the
@@ -232,7 +267,7 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAd
}
const runHandler = (): MessageResponse | Promise<MessageResponse> => {
- if (!hasAttachments) return dispatchMessage()
+ if (!hasImageAttachments) return dispatchMessage()
return (async () => {
const key = serializeSessionKey({
userId: normalizedMessage.sender,
@@ -269,7 +304,7 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAd
// (not in the catalog, or a boot fallback serves another pair) the write
// gate and the per-task check below keep their existing verdicts.
const hostProvider = deps.hostProvider()
- if (hasAttachments && hostProvider) {
+ if (hasImageAttachments && hostProvider) {
const requested = deps.resolveTaskModel({ [hostProvider]: piggybackModel })
if (
!requested ||
@@ -290,14 +325,14 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAd
normalizedMessage.channelId,
normalizedMessage.threadId,
piggybackModel,
- hasAttachments ? message.modelSelectionRevision : undefined,
+ hasImageAttachments ? message.modelSelectionRevision : undefined,
// An image send carries the model the client displays, not a user
// pick: asking for the effective model must not pin it. Text-only
// piggybacks and `POST /v1/runtime/model` keep writing.
- hasAttachments ? { skipWriteWhenEffective: true } : undefined
+ hasImageAttachments ? { skipWriteWhenEffective: true } : undefined
)
if (!applied.ok) {
- if (hasAttachments) {
+ if (hasImageAttachments) {
const conflict = applied.reason === 'model_selection_conflict'
const code = conflict
? LlmErrorCode.ModelSelectionConflict
@@ -337,12 +372,12 @@ export function createIncomingAdmission(deps: IncomingAdmissionDeps): IncomingAd
},
'Host runtime event'
)
- } else if (hasAttachments) {
+ } else if (hasImageAttachments) {
acceptedVisualSelection = { [applied.provider]: applied.model }
}
} catch (error) {
applied = undefined
- if (hasAttachments) {
+ if (hasImageAttachments) {
deps.logger.warn({ err: error }, 'Visual model selection could not be confirmed')
logRefusal({
provider: deps.hostProvider() ?? 'unknown',
diff --git a/mcp-host/src/agent/incomingAttachments.ts b/mcp-host/src/agent/incomingAttachments.ts
new file mode 100644
index 000000000..488a56336
--- /dev/null
+++ b/mcp-host/src/agent/incomingAttachments.ts
@@ -0,0 +1,244 @@
+import { createHash } from 'node:crypto'
+import {
+ type FileReferenceV1,
+ buildAttachmentFileReference,
+ classifyBytes,
+} from '@clerum/gfs-interaction-policy'
+import { FileAttachmentErrorCode } from '../core/errors'
+import type { Attachment } from '../core/types'
+import {
+ type ImageAttachmentMimeType,
+ isCanonicalBase64Shape,
+ isImageAttachmentMime,
+} from '../llm/imageInput'
+import type { TaskError } from '../queue/types'
+
+/**
+ * Attachments (images and files together) accepted in one incoming message.
+ * Kept separate from `CLERUM_ATTACHMENT_MAX_COUNT`, which caps the attachments
+ * a response returns.
+ * Must match COMPOSER_MAX_IMAGE_ATTACHMENTS in desktop-app/ui/src/constants/attachments.ts.
+ * Per-image bytes stay on the channel `attachmentMaxBytes` (issue #654 / PR
+ * #669) — this module must not clamp general inbound traffic to the Codex
+ * `VISUAL_LIMITS`. The Codex chat hop is a separate 24 MiB parser with a
+ * 16 MiB credited image budget. Per-file bytes use `attachmentFileMaxBytes`
+ * (issue #666). This count is the fail-loud admission cap.
+ */
+export const INCOMING_ATTACHMENT_MAX_COUNT = 20
+
+export type IncomingAttachmentValidation =
+ | { ok: true; attachments: Attachment[] | undefined; fileReferences: FileReferenceV1[] }
+ | { ok: false; error: TaskError }
+
+export interface IncomingAttachmentLimits {
+ maxCount: number
+ /** Decoded bytes per `kind:'image'` attachment. */
+ maxBytes: number
+ /** Decoded bytes per `kind:'file'` attachment. */
+ maxFileBytes: number
+ /** The message the attachments arrived with; part of each file reference id. */
+ messageId: string
+}
+
+/**
+ * First bytes every accepted encoding must start with. The declared media type
+ * decides how the provider serializes the image, so a declaration the bytes
+ * contradict is rejected here rather than forwarded upstream (CWE-345).
+ */
+const MIME_SIGNATURES: Readonly<Record<ImageAttachmentMimeType, Buffer>> = {
+ 'image/png': Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+ 'image/jpeg': Buffer.from([0xff, 0xd8, 0xff]),
+}
+
+const SHA256_HEX = /^[0-9a-f]{64}$/
+
+function bytesMatchDeclaredMime(bytes: Buffer, mimeType: ImageAttachmentMimeType): boolean {
+ const signature = MIME_SIGNATURES[mimeType]
+ return bytes.length >= signature.length && bytes.subarray(0, signature.length).equals(signature)
+}
+
+type ItemResult = { ok: true; attachment: Attachment } | { ok: false; error: TaskError }
+
+function taskError(code: string, message: string): { ok: false; error: TaskError } {
+ return { ok: false, error: { code, message, retryable: false, provider: 'unknown' } }
+}
+
+const rejectImage = (message: string) => taskError('LLM_INVALID_ATTACHMENT', message)
+
+// The image branch is the #669 contract, unchanged: same checks, same order,
+// same code and messages.
+function validateImage(item: Record<string, unknown>, maxBytes: number): ItemResult {
+ if (
+ !isImageAttachmentMime(item.mimeType) ||
+ item.encoding !== 'base64' ||
+ typeof item.dataBase64 !== 'string' ||
+ typeof item.id !== 'string' ||
+ !item.id.trim()
+ ) {
+ return rejectImage('Only PNG or JPEG images encoded as base64 are supported.')
+ }
+ const data = item.dataBase64
+ // Check length before decoding so validation cannot allocate an oversized
+ // binary buffer. Canonical base64 avoids ambiguous/partially decoded input.
+ if (data.length > Math.ceil(maxBytes / 3) * 4)
+ return rejectImage('An image exceeds the attachment size limit.')
+ if (!isCanonicalBase64Shape(data)) {
+ return rejectImage('An image has invalid base64 data. Attach the original file again.')
+ }
+ const bytes = Buffer.from(data, 'base64')
+ if (bytes.length > maxBytes) return rejectImage('An image exceeds the attachment size limit.')
+ if (bytes.toString('base64') !== data)
+ return rejectImage('An image has invalid base64 data. Attach the original file again.')
+ if (!bytesMatchDeclaredMime(bytes, item.mimeType))
+ return rejectImage('An image does not match its declared type. Attach the original file again.')
+ return {
+ ok: true,
+ attachment: {
+ id: item.id,
+ kind: 'image',
+ mimeType: item.mimeType,
+ encoding: 'base64',
+ dataBase64: data,
+ ...(typeof item.filename === 'string' ? { filename: item.filename } : {}),
+ ...(typeof item.width === 'number' && Number.isFinite(item.width) && item.width > 0
+ ? { width: item.width }
+ : {}),
+ ...(typeof item.height === 'number' && Number.isFinite(item.height) && item.height > 0
+ ? { height: item.height }
+ : {}),
+ },
+ }
+}
+
+const rejectFile = (message: string) => taskError(FileAttachmentErrorCode.Invalid, message)
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+ return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * Any file type is admitted (D14). Only an invalid shape, an oversized file or
+ * a digest the bytes contradict is rejected; the class and reader are derived
+ * from the whole file and never from the caller's declaration.
+ */
+function validateFile(item: Record<string, unknown>, limits: IncomingAttachmentLimits): ItemResult {
+ const digest = item.digest
+ if (
+ typeof item.id !== 'string' ||
+ !item.id.trim() ||
+ typeof item.filename !== 'string' ||
+ typeof item.mimeType !== 'string' ||
+ typeof item.detectedMediaType !== 'string' ||
+ item.encoding !== 'base64' ||
+ typeof item.dataBase64 !== 'string' ||
+ typeof item.sizeBytes !== 'number' ||
+ !Number.isSafeInteger(item.sizeBytes) ||
+ item.sizeBytes < 0 ||
+ !isPlainRecord(digest) ||
+ digest.algorithm !== 'sha256' ||
+ typeof digest.hex !== 'string' ||
+ !SHA256_HEX.test(digest.hex)
+ ) {
+ return rejectFile('A file attachment is malformed. Attach the original file again.')
+ }
+ const data = item.dataBase64
+ const tooLarge = taskError(
+ FileAttachmentErrorCode.TooLarge,
+ 'A file exceeds the attachment size limit.'
+ )
+ // Same pre-decode bound as the image branch: never allocate an oversized buffer.
+ if (item.sizeBytes > limits.maxFileBytes || data.length > Math.ceil(limits.maxFileBytes / 3) * 4)
+ return tooLarge
+ // A zero-byte file is a file; its canonical base64 is the empty string.
+ if (data !== '' && !isCanonicalBase64Shape(data)) {
+ return rejectFile('A file has invalid base64 data. Attach the original file again.')
+ }
+ const bytes = Buffer.from(data, 'base64')
+ if (bytes.length > limits.maxFileBytes) return tooLarge
+ if (bytes.toString('base64') !== data)
+ return rejectFile('A file has invalid base64 data. Attach the original file again.')
+ if (bytes.length !== item.sizeBytes)
+ return rejectFile('A file does not match its declared size. Attach the original file again.')
+ const hex = createHash('sha256').update(bytes).digest('hex')
+ if (hex !== digest.hex) {
+ return taskError(
+ FileAttachmentErrorCode.DigestMismatch,
+ 'A file does not match its declared digest. Attach the original file again.'
+ )
+ }
+
+ const declaredMediaType = item.mimeType === '' ? null : item.mimeType
+ const classified = classifyBytes({
+ bytes,
+ totalByteLength: bytes.length,
+ declaredMediaType,
+ filename: item.filename,
+ })
+ // The host's detection wins over the one the client declared; a disagreement
+ // is recorded, never rejected.
+ const classification = {
+ ...classified,
+ mismatch: classified.mismatch || item.detectedMediaType !== classified.detectedMediaType,
+ }
+ const reference = buildAttachmentFileReference({
+ attachmentId: item.id,
+ messageId: limits.messageId,
+ name: item.filename,
+ declaredMediaType,
+ byteLength: bytes.length,
+ digestHex: hex,
+ classification,
+ })
+ if (!reference.ok) {
+ return rejectFile('A file attachment has an invalid name. Rename the file and attach it again.')
+ }
+ return {
+ ok: true,
+ attachment: {
+ id: item.id,
+ kind: 'file',
+ mimeType: item.mimeType,
+ encoding: 'base64',
+ dataBase64: data,
+ filename: reference.value.name,
+ sizeBytes: bytes.length,
+ detectedMediaType: classification.detectedMediaType,
+ digest: { algorithm: 'sha256', hex },
+ fileReference: reference.value,
+ },
+ }
+}
+
+/** Reject the whole message rather than silently sending only part of it. */
+export function validateIncomingAttachments(
+ raw: unknown,
+ limits: IncomingAttachmentLimits
+): IncomingAttachmentValidation {
+ if (raw == null) return { ok: true, attachments: undefined, fileReferences: [] }
+ if (!Array.isArray(raw)) return rejectImage('Image attachments must be a list.')
+ if (!raw.length) return { ok: true, attachments: undefined, fileReferences: [] }
+ // One ceiling over images and files together, checked before either branch.
+ if (raw.length > limits.maxCount) {
+ const carriesFiles = raw.some(item => isPlainRecord(item) && item.kind === 'file')
+ return rejectImage(
+ carriesFiles
+ ? 'Too many attachments. Remove an attachment and try again.'
+ : 'Too many image attachments. Remove an image and try again.'
+ )
+ }
+ const attachments: Attachment[] = []
+ const fileReferences: FileReferenceV1[] = []
+ for (const item of raw) {
+ const result = !isPlainRecord(item)
+ ? rejectImage('Only PNG or JPEG images encoded as base64 are supported.')
+ : item.kind === 'file'
+ ? validateFile(item, limits)
+ : item.kind === 'image'
+ ? validateImage(item, limits.maxBytes)
+ : rejectImage('Only PNG or JPEG images encoded as base64 are supported.')
+ if (!result.ok) return result
+ attachments.push(result.attachment)
+ if (result.attachment.fileReference) fileReferences.push(result.attachment.fileReference)
+ }
+ return { ok: true, attachments, fileReferences }
+}
diff --git a/mcp-host/src/agent/incomingImageAttachments.ts b/mcp-host/src/agent/incomingImageAttachments.ts
deleted file mode 100644
index 25788d878..000000000
--- a/mcp-host/src/agent/incomingImageAttachments.ts
+++ /dev/null
@@ -1,98 +0,0 @@
-import type { Attachment } from '../core/types'
-import {
- type ImageAttachmentMimeType,
- isCanonicalBase64Shape,
- isImageAttachmentMime,
-} from '../llm/imageInput'
-import type { TaskError } from '../queue/types'
-
-/**
- * Images accepted in one incoming message. Kept separate from
- * `CLERUM_ATTACHMENT_MAX_COUNT`, which caps the attachments a response returns.
- * Must match COMPOSER_MAX_IMAGE_ATTACHMENTS in desktop-app/ui/src/constants/attachments.ts.
- * Per-image bytes stay on the channel `attachmentMaxBytes` (issue #654 / PR
- * #669) — this module must not clamp general inbound traffic to the Codex
- * `VISUAL_LIMITS`. The Codex chat hop is a separate 24 MiB parser with a
- * 16 MiB credited image budget. This count is the fail-loud admission cap.
- */
-export const INCOMING_IMAGE_MAX_COUNT = 20
-
-export type IncomingImageValidation =
- | { ok: true; attachments: Attachment[] | undefined }
- | { ok: false; error: TaskError }
-
-/**
- * First bytes every accepted encoding must start with. The declared media type
- * decides how the provider serializes the image, so a declaration the bytes
- * contradict is rejected here rather than forwarded upstream (CWE-345).
- */
-const MIME_SIGNATURES: Readonly<Record<ImageAttachmentMimeType, Buffer>> = {
- 'image/png': Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
- 'image/jpeg': Buffer.from([0xff, 0xd8, 0xff]),
-}
-
-function bytesMatchDeclaredMime(bytes: Buffer, mimeType: ImageAttachmentMimeType): boolean {
- const signature = MIME_SIGNATURES[mimeType]
- return bytes.length >= signature.length && bytes.subarray(0, signature.length).equals(signature)
-}
-
-/** Reject the whole visual input rather than silently sending only its text. */
-export function validateIncomingImageAttachments(
- raw: unknown,
- limits: { maxCount: number; maxBytes: number }
-): IncomingImageValidation {
- const reject = (message: string): IncomingImageValidation => ({
- ok: false,
- error: { code: 'LLM_INVALID_ATTACHMENT', message, retryable: false, provider: 'unknown' },
- })
- if (raw == null) return { ok: true, attachments: undefined }
- if (!Array.isArray(raw)) return reject('Image attachments must be a list.')
- if (!raw.length) return { ok: true, attachments: undefined }
- if (raw.length > limits.maxCount)
- return reject('Too many image attachments. Remove an image and try again.')
- const attachments: Attachment[] = []
- for (const item of raw) {
- if (
- !item ||
- typeof item !== 'object' ||
- Array.isArray(item) ||
- item.kind !== 'image' ||
- !isImageAttachmentMime(item.mimeType) ||
- item.encoding !== 'base64' ||
- typeof item.dataBase64 !== 'string' ||
- typeof item.id !== 'string' ||
- !item.id.trim()
- ) {
- return reject('Only PNG or JPEG images encoded as base64 are supported.')
- }
- const data = item.dataBase64
- // Check length before decoding so validation cannot allocate an oversized
- // binary buffer. Canonical base64 avoids ambiguous/partially decoded input.
- if (data.length > Math.ceil(limits.maxBytes / 3) * 4)
- return reject('An image exceeds the attachment size limit.')
- if (!isCanonicalBase64Shape(data)) {
- return reject('An image has invalid base64 data. Attach the original file again.')
- }
- const bytes = Buffer.from(data, 'base64')
- if (bytes.length > limits.maxBytes) return reject('An image exceeds the attachment size limit.')
- if (bytes.toString('base64') !== data)
- return reject('An image has invalid base64 data. Attach the original file again.')
- if (!bytesMatchDeclaredMime(bytes, item.mimeType))
- return reject('An image does not match its declared type. Attach the original file again.')
- attachments.push({
- id: item.id,
- kind: 'image',
- mimeType: item.mimeType,
- encoding: 'base64',
- dataBase64: data,
- ...(typeof item.filename === 'string' ? { filename: item.filename } : {}),
- ...(typeof item.width === 'number' && Number.isFinite(item.width) && item.width > 0
- ? { width: item.width }
- : {}),
- ...(typeof item.height === 'number' && Number.isFinite(item.height) && item.height > 0
- ? { height: item.height }
- : {}),
- })
- }
- return { ok: true, attachments }
-}
diff --git a/mcp-host/src/agent/taskExecutor.ts b/mcp-host/src/agent/taskExecutor.ts
index afa7a8534..2767217d1 100644
--- a/mcp-host/src/agent/taskExecutor.ts
+++ b/mcp-host/src/agent/taskExecutor.ts
@@ -51,7 +51,10 @@ import {
collectToolAttachments,
mergeCollectedAttachments,
} from '../core/orchestration/toolUseLoopMessages'
-import { buildTurnContextBlock } from '../core/orchestration/turnContext'
+import {
+ attachedFilesForTurnContext,
+ buildTurnContextBlock,
+} from '../core/orchestration/turnContext'
import { DefaultReasoningFactory } from '../core/reasoning'
import {
CAPABILITY_CONTRACT_TEXT,
@@ -1091,7 +1094,12 @@ export class TaskExecutor {
// prompt and into a `<turn-context>` block prepended to the LAST user
// message of the turn. Only the first user message of the turn gets it;
// `tool` messages keep their content untouched.
- if (appConfig.promptCacheEnabled) {
+ // #666 — the block is also the only carrier of the `attached_file` lines,
+ // so a message with file attachments gets it with the cache off too; the
+ // same condition registers `clerum__attachment_read`.
+ const hasFileAttachments =
+ this.task.sourceMessage?.attachments?.some(attachment => attachment.kind === 'file') === true
+ if (appConfig.promptCacheEnabled || hasFileAttachments) {
this.prependTurnContextBlock(messages)
}
const promptAssemblyStart = Date.now()
@@ -1132,6 +1140,7 @@ export class TaskExecutor {
scheduledFor: new Date().toISOString(),
}
: undefined,
+ attachedFiles: attachedFilesForTurnContext(this.task.sourceMessage?.attachments),
})
const isCron = this.task.cronJobId !== undefined
if (m.contentParts && m.contentParts.length > 0) {
diff --git a/mcp-host/src/config.ts b/mcp-host/src/config.ts
index 6b7a07e74..64cdf3883 100644
--- a/mcp-host/src/config.ts
+++ b/mcp-host/src/config.ts
@@ -232,6 +232,10 @@ export interface Config {
enableResponseAttachments: boolean
attachmentMaxCount: number
attachmentMaxBytes: number
+ /** Decoded bytes per incoming `kind:'file'` attachment (issue #666). */
+ attachmentFileMaxBytes: number
+ /** Bytes one `clerum__attachment_read` call may return (issue #666). */
+ attachmentTextReadMaxBytes: number
activityBufferSize: number
activityMaxEventBytes: number
@@ -480,6 +484,12 @@ function buildDevHostConfig(provider?: LlmProvider, modelName?: string): HostSpe
}
const devMode = getEnvBool('CLERUM_DEV_MODE', false)
+// Read once: the top-level field documents the limit, `nativeTool` carries it
+// to `clerum__attachment_read` (#666).
+const attachmentTextReadMaxBytes = getExecutionLimit(
+ 'CLERUM_ATTACHMENT_TEXT_READ_MAX_BYTES',
+ 262_144
+)
const configuredWorkflowEnabled = getEnvBool('CLERUM_WORKFLOW_ENABLED', false)
const configuredRuntimeKind = resolveMcpHostRuntimeKind({
workflowEnabled: configuredWorkflowEnabled,
@@ -953,12 +963,15 @@ export const config: Config = {
// native tool registry (which only receives NativeToolConfig) can steer
// the cron_manage stateless notice.
statelessLifecycle: getEnvBool('CLERUM_STATELESS_LIFECYCLE', false),
+ attachmentTextReadMaxBytes,
},
// Attachment delivery
enableResponseAttachments: getEnvBool('CLERUM_ENABLE_RESPONSE_ATTACHMENTS', true),
attachmentMaxCount: parseInt(getEnv('CLERUM_ATTACHMENT_MAX_COUNT', '3')!, 10),
attachmentMaxBytes: parseInt(getEnv('CLERUM_ATTACHMENT_MAX_BYTES', '52428800')!, 10),
+ attachmentFileMaxBytes: getExecutionLimit('CLERUM_ATTACHMENT_FILE_MAX_BYTES', 3_145_728),
+ attachmentTextReadMaxBytes,
activityBufferSize: parseInt(getEnv('MCP_HOST_ACTIVITY_BUFFER_SIZE', '1000')!, 10),
activityMaxEventBytes: parseInt(getEnv('MCP_HOST_ACTIVITY_MAX_EVENT_BYTES', '2048')!, 10),
diff --git a/mcp-host/src/core/errors.ts b/mcp-host/src/core/errors.ts
index d77add7ed..ed002b79e 100644
--- a/mcp-host/src/core/errors.ts
+++ b/mcp-host/src/core/errors.ts
@@ -70,6 +70,20 @@ export enum LlmErrorCode {
ModelNotAllowed = 'LLM_MODEL_NOT_ALLOWED',
}
+/**
+ * Issue #666 — rejections of an inline `kind:'file'` attachment at admission.
+ * All terminal: resending the same bytes cannot succeed. No code rejects a file
+ * for its type; an unreadable class is admitted and reported as `reader:'none'`.
+ */
+export enum FileAttachmentErrorCode {
+ /** Shape, encoding, declared size or file name is invalid. */
+ Invalid = 'FILE_ATTACHMENT_INVALID',
+ /** The decoded file exceeds `CLERUM_ATTACHMENT_FILE_MAX_BYTES`. */
+ TooLarge = 'FILE_ATTACHMENT_TOO_LARGE',
+ /** The recomputed sha256 differs from the declared digest. */
+ DigestMismatch = 'FILE_ATTACHMENT_DIGEST_MISMATCH',
+}
+
export class LlmError extends AgentError {
constructor(
message: string,
diff --git a/mcp-host/src/core/interfaces.ts b/mcp-host/src/core/interfaces.ts
index d0899316e..e93b68ad5 100644
--- a/mcp-host/src/core/interfaces.ts
+++ b/mcp-host/src/core/interfaces.ts
@@ -252,4 +252,7 @@ export interface NativeToolConfig {
/** Cron×stateless (CLERUM_STATELESS_LIFECYCLE): steers the cron_manage
* stateless notice. Optional so existing construction sites stay valid. */
statelessLifecycle?: boolean
+ /** Per-call byte ceiling of `clerum__attachment_read` (#666). Registering the
+ * tool for a message with `kind:'file'` attachments requires it. */
+ attachmentTextReadMaxBytes?: number
}
diff --git a/mcp-host/src/core/orchestration/__tests__/turnContext.test.ts b/mcp-host/src/core/orchestration/__tests__/turnContext.test.ts
index 45ea4faae..d7bef93ef 100644
--- a/mcp-host/src/core/orchestration/__tests__/turnContext.test.ts
+++ b/mcp-host/src/core/orchestration/__tests__/turnContext.test.ts
@@ -1,5 +1,12 @@
import { describe, expect, it } from 'vitest'
-import { buildTurnContextBlock } from '../turnContext'
+import type { FileReferenceV1 } from '@clerum/gfs-interaction-policy'
+import type { Attachment } from '../../types'
+import {
+ ATTACHED_FILES_INSTRUCTION,
+ type TurnContextAttachedFile,
+ attachedFilesForTurnContext,
+ buildTurnContextBlock,
+} from '../turnContext'
describe('buildTurnContextBlock (T2.2)', () => {
it('includes date and channel; omits sender when not provided', () => {
@@ -39,3 +46,160 @@ describe('buildTurnContextBlock (T2.2)', () => {
expect(block.endsWith('</turn-context>\n\n')).toBe(true)
})
})
+
+describe('attached_file lines (issue #666)', () => {
+ const date = new Date('2026-05-19T14:30:00Z')
+ const notes: TurnContextAttachedFile = {
+ attachmentId: 'file-1',
+ name: 'notes.md',
+ class: 'markdown',
+ byteLength: 42,
+ reader: 'text',
+ mismatch: false,
+ declaredMediaType: 'text/markdown',
+ detectedMediaType: 'text/markdown',
+ }
+
+ it('lists each file after the channel lines, followed by the fixed instruction', () => {
+ const block = buildTurnContextBlock({
+ date,
+ channel: { type: 'rpc', sender: 'jose' },
+ attachedFiles: [
+ notes,
+ {
+ ...notes,
+ attachmentId: 'file-2',
+ name: 'report.pdf',
+ class: 'pdf',
+ byteLength: 9000,
+ reader: 'none',
+ declaredMediaType: 'application/pdf',
+ detectedMediaType: 'application/pdf',
+ },
+ ],
+ })
+ expect(block).toBe(
+ '<turn-context>\n' +
+ 'date: 2026-05-19T14:30:00.000Z\n' +
+ 'channel: rpc\n' +
+ 'sender: jose\n' +
+ 'attached_file: id=file-1 name="notes.md" class=markdown bytes=42 reader=text\n' +
+ 'attached_file: id=file-2 name="report.pdf" class=pdf bytes=9000 reader=none\n' +
+ "If the user's request refers to an attached file, read it with clerum__attachment_read before answering. Files with reader=none cannot be read in this turn; say so instead of guessing.\n" +
+ '</turn-context>\n\n'
+ )
+ expect(ATTACHED_FILES_INSTRUCTION).toBe(
+ "If the user's request refers to an attached file, read it with clerum__attachment_read before answering. Files with reader=none cannot be read in this turn; say so instead of guessing."
+ )
+ })
+
+ it('appends the declared and detected types when they disagree', () => {
+ const block = buildTurnContextBlock({
+ date,
+ channel: { type: 'rpc' },
+ attachedFiles: [
+ {
+ ...notes,
+ name: 'invoice.txt',
+ class: 'pdf',
+ reader: 'none',
+ mismatch: true,
+ declaredMediaType: 'text/plain',
+ detectedMediaType: 'application/pdf',
+ },
+ ],
+ })
+ expect(block).toContain(
+ 'attached_file: id=file-1 name="invoice.txt" class=pdf bytes=42 reader=none mismatch=true declared=text/plain detected=application/pdf\n'
+ )
+ })
+
+ it('writes declared=none when the file had no declared media type', () => {
+ const block = buildTurnContextBlock({
+ date,
+ channel: { type: 'rpc' },
+ attachedFiles: [{ ...notes, mismatch: true, declaredMediaType: null }],
+ })
+ expect(block).toContain('reader=text mismatch=true declared=none detected=text/markdown\n')
+ })
+
+ it('quotes the user-chosen name so an embedded quote cannot end the field', () => {
+ const block = buildTurnContextBlock({
+ date,
+ channel: { type: 'rpc' },
+ attachedFiles: [{ ...notes, name: 'a" reader=text b.md' }],
+ })
+ expect(block).toContain('name="a\\" reader=text b.md" class=markdown bytes=42 reader=text\n')
+ })
+
+ it('emits neither lines nor instruction for a turn without files', () => {
+ for (const attachedFiles of [undefined, []]) {
+ const block = buildTurnContextBlock({ date, channel: { type: 'rpc' }, attachedFiles })
+ // Witness: the block was built with its channel line.
+ expect(block).toBe(
+ '<turn-context>\ndate: 2026-05-19T14:30:00.000Z\nchannel: rpc\n</turn-context>\n\n'
+ )
+ expect(block).not.toContain('attached_file')
+ expect(block).not.toContain('clerum__attachment_read')
+ }
+ })
+})
+
+describe('attachedFilesForTurnContext (issue #666)', () => {
+ const fileReference: FileReferenceV1 = {
+ schemaVersion: 1,
+ id: `att:message-1:file-1@sha256:${'a'.repeat(64)}`,
+ source: { kind: 'attachment', attachmentId: 'file-1', messageId: 'message-1' },
+ name: 'notes.md',
+ declaredMediaType: 'text/markdown',
+ detectedMediaType: 'text/markdown',
+ class: 'markdown',
+ detection: 'text_utf8',
+ mismatch: false,
+ byteLength: 42,
+ digest: { algorithm: 'sha256', hex: 'a'.repeat(64) },
+ textReadable: true,
+ reader: 'text',
+ modelImageInput: 'unsupported',
+ }
+ const image: Attachment = {
+ id: 'image-1',
+ kind: 'image',
+ mimeType: 'image/png',
+ encoding: 'base64',
+ dataBase64: 'iVBORw0KGgo=',
+ }
+ const file: Attachment = {
+ id: 'file-1',
+ kind: 'file',
+ mimeType: 'text/markdown',
+ encoding: 'base64',
+ dataBase64: 'IyBub3Rlcw==',
+ filename: 'notes.md',
+ sizeBytes: 42,
+ fileReference,
+ }
+
+ it('maps each admitted file reference and skips images', () => {
+ expect(attachedFilesForTurnContext([image, file])).toEqual([
+ {
+ attachmentId: 'file-1',
+ name: 'notes.md',
+ class: 'markdown',
+ byteLength: 42,
+ reader: 'text',
+ mismatch: false,
+ declaredMediaType: 'text/markdown',
+ detectedMediaType: 'text/markdown',
+ },
+ ])
+ })
+
+ it('lists nothing for image-only, a file without reference, or absent attachments', () => {
+ // Witness: the same function lists the admitted file.
+ expect(attachedFilesForTurnContext([file])).toHaveLength(1)
+ expect(attachedFilesForTurnContext([image])).toEqual([])
+ expect(attachedFilesForTurnContext([{ ...file, fileReference: undefined }])).toEqual([])
+ expect(attachedFilesForTurnContext(undefined)).toEqual([])
+ })
+})
diff --git a/mcp-host/src/core/orchestration/turnContext.ts b/mcp-host/src/core/orchestration/turnContext.ts
index 1ef659129..9ed955f0f 100644
--- a/mcp-host/src/core/orchestration/turnContext.ts
+++ b/mcp-host/src/core/orchestration/turnContext.ts
@@ -15,8 +15,10 @@
* <original user message>
*
* For cron-originated turns we append two extra lines (`cron_job` /
- * `scheduled_for`) — see P1-004.
+ * `scheduled_for`) — see P1-004. Turns with `kind:'file'` attachments list
+ * one `attached_file` line per file plus a fixed read instruction (#666).
*/
+import type { Attachment } from '../types'
export interface TurnContextChannel {
type: string
@@ -28,10 +30,62 @@ export interface TurnContextCron {
scheduledFor: string
}
+/**
+ * A file attached to this turn (#666). Only metadata reaches the model: the
+ * content is read on demand with `clerum__attachment_read`.
+ */
+export interface TurnContextAttachedFile {
+ attachmentId: string
+ name: string
+ class: string
+ byteLength: number
+ reader: 'text' | 'none'
+ mismatch: boolean
+ declaredMediaType: string | null
+ detectedMediaType: string
+}
+
export interface TurnContextInput {
date: Date
channel: TurnContextChannel
cron?: TurnContextCron
+ attachedFiles?: TurnContextAttachedFile[]
+}
+
+export const ATTACHED_FILES_INSTRUCTION =
+ "If the user's request refers to an attached file, read it with clerum__attachment_read before answering. Files with reader=none cannot be read in this turn; say so instead of guessing."
+
+function attachedFileLine(file: TurnContextAttachedFile): string {
+ // The name is user-chosen: JSON quoting keeps a `"` inside it from ending the field.
+ const line = `attached_file: id=${file.attachmentId} name=${JSON.stringify(file.name)} class=${file.class} bytes=${file.byteLength} reader=${file.reader}`
+ if (!file.mismatch) return line
+ return `${line} mismatch=true declared=${file.declaredMediaType ?? 'none'} detected=${file.detectedMediaType}`
+}
+
+/**
+ * The `attached_file` entries for a source message: every `kind:'file'`
+ * attachment admitted with a `FileReferenceV1`. Images are not listed; they
+ * reach the model as content parts.
+ */
+export function attachedFilesForTurnContext(
+ attachments: readonly Attachment[] | undefined
+): TurnContextAttachedFile[] {
+ const files: TurnContextAttachedFile[] = []
+ for (const attachment of attachments ?? []) {
+ const reference = attachment.kind === 'file' ? attachment.fileReference : undefined
+ if (!reference) continue
+ files.push({
+ attachmentId: attachment.id,
+ name: reference.name,
+ class: reference.class,
+ byteLength: reference.byteLength,
+ reader: reference.reader,
+ mismatch: reference.mismatch,
+ declaredMediaType: reference.declaredMediaType,
+ detectedMediaType: reference.detectedMediaType,
+ })
+ }
+ return files
}
export function buildTurnContextBlock(input: TurnContextInput): string {
@@ -43,5 +97,9 @@ export function buildTurnContextBlock(input: TurnContextInput): string {
lines.push(`cron_job: ${input.cron.jobId}`)
lines.push(`scheduled_for: ${input.cron.scheduledFor}`)
}
+ if (input.attachedFiles && input.attachedFiles.length > 0) {
+ lines.push(...input.attachedFiles.map(attachedFileLine))
+ lines.push(ATTACHED_FILES_INSTRUCTION)
+ }
return `<turn-context>\n${lines.join('\n')}\n</turn-context>\n\n`
}
diff --git a/mcp-host/src/core/tools/__tests__/attachmentRead.test.ts b/mcp-host/src/core/tools/__tests__/attachmentRead.test.ts
new file mode 100644
index 000000000..d9134b9ab
--- /dev/null
+++ b/mcp-host/src/core/tools/__tests__/attachmentRead.test.ts
@@ -0,0 +1,234 @@
+/**
+ * #666 — `clerum__attachment_read`. Attachments are built by the real admission
+ * validator, so every `FileReferenceV1` here is one the host would produce.
+ */
+import { describe, expect, it } from 'vitest'
+import { createHash } from 'node:crypto'
+import { validateIncomingAttachments } from '../../../agent/incomingAttachments'
+import type { IncomingMessage } from '../../../server'
+import type { Attachment } from '../../types'
+import { AttachmentReadTool } from '../attachmentRead'
+
+const READ_LIMIT = 262_144
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+function rawFile(id: string, filename: string, mimeType: string, bytes: Buffer) {
+ return {
+ id,
+ kind: 'file',
+ mimeType,
+ detectedMediaType: mimeType,
+ encoding: 'base64',
+ dataBase64: bytes.toString('base64'),
+ filename,
+ sizeBytes: bytes.length,
+ digest: { algorithm: 'sha256', hex: createHash('sha256').update(bytes).digest('hex') },
+ }
+}
+
+function admitted(raw: unknown[]): Attachment[] {
+ const result = validateIncomingAttachments(raw, {
+ maxCount: 20,
+ maxBytes: 1_000_000,
+ maxFileBytes: 3_145_728,
+ messageId: 'message-1',
+ })
+ if (!result.ok) throw new Error(`fixture rejected: ${result.error.code}`)
+ return result.attachments!
+}
+
+function toolFor(attachments: Attachment[], limit = READ_LIMIT): AttachmentReadTool {
+ const message: IncomingMessage = {
+ content: 'Analyze the attached file',
+ channelType: 'rpc',
+ channelId: 'agent-1',
+ sender: 'user-1',
+ timestamp: '2026-09-24T10:00:00Z',
+ messageId: 'message-1',
+ hostRef: 'host-1',
+ attachments,
+ }
+ return new AttachmentReadTool(message, limit)
+}
+
+async function read(tool: AttachmentReadTool, params: Record<string, unknown>) {
+ const output = await tool.execute(params)
+ return { output, body: JSON.parse(output.content) as Record<string, unknown> }
+}
+
+const SENTINEL = 'SENTINEL-666-alpha'
+
+describe('clerum__attachment_read', () => {
+ it('declares a sanitized, approval-free tool bounded by the per-call limit', () => {
+ const tool = toolFor([])
+ expect(tool.name()).toBe('clerum__attachment_read')
+ expect(tool.requiresSanitization()).toBe(true)
+ expect(tool.requiresApproval()).toBe(false)
+ expect(tool.parametersSchema()).toMatchObject({
+ required: ['attachmentId'],
+ properties: { maxBytes: { minimum: 1, maximum: READ_LIMIT } },
+ })
+ })
+
+ it('returns the whole text of a small text file with its reference', async () => {
+ const [file] = admitted([
+ rawFile('file-1', 'notes.txt', 'text/plain', Buffer.from(`hello ${SENTINEL}\n`)),
+ ])
+ const { output, body } = await read(toolFor([file!]), { attachmentId: 'file-1' })
+ expect(output.is_error).toBe(false)
+ expect(body).toEqual({
+ reference: file!.fileReference,
+ kind: 'text',
+ text: `hello ${SENTINEL}\n`,
+ byteRange: { offset: 0, length: Buffer.byteLength(`hello ${SENTINEL}\n`) },
+ truncated: false,
+ })
+ })
+
+ it('returns a typed binary result for a reader=none file without decoding it', async () => {
+ const pdf = Buffer.from(`%PDF-1.7\n${SENTINEL}\n%%EOF\n`)
+ const [file] = admitted([rawFile('file-1', 'report.pdf', 'application/pdf', pdf)])
+ expect(file!.fileReference!.reader).toBe('none')
+ const { output, body } = await read(toolFor([file!]), { attachmentId: 'file-1' })
+ expect(output.is_error).toBe(false)
+ expect(body).toEqual({
+ reference: file!.fileReference,
+ kind: 'binary',
+ reader: 'none',
+ reason: 'no_reader_for_class',
+ })
+ expect(output.content).not.toContain(SENTINEL)
+ })
+
+ it('reads a PNG sent as kind:file as binary, never as image input', async () => {
+ const [file] = admitted([rawFile('file-1', 'photo.png', 'image/png', PNG_SIGNATURE)])
+ const { body } = await read(toolFor([file!]), { attachmentId: 'file-1' })
+ expect(body).toMatchObject({ kind: 'binary', reason: 'no_reader_for_class' })
+ })
+
+ it.each([
+ ['a DEL control byte', Buffer.from(`notes\u007f${SENTINEL}`)],
+ ['a GIF signature prefix', Buffer.from(`GIF89a notes ${SENTINEL}`)],
+ ])('answers binary for a reader=text file with %s', async (_label, bytes) => {
+ const [file] = admitted([rawFile('file-1', 'notes.txt', 'text/plain', bytes)])
+ // Witness: the classifier admitted it as readable text.
+ expect(file!.fileReference!.reader).toBe('text')
+ const { output, body } = await read(toolFor([file!]), { attachmentId: 'file-1' })
+ expect(output.is_error).toBe(false)
+ expect(body).toEqual({
+ reference: file!.fileReference,
+ kind: 'binary',
+ reader: 'none',
+ reason: 'text_decode_rejected',
+ })
+ expect(output.content).not.toContain(SENTINEL)
+ })
+
+ it('returns an empty page for a zero-byte text file', async () => {
+ const [file] = admitted([rawFile('file-1', 'empty.txt', 'text/plain', Buffer.alloc(0))])
+ const { output, body } = await read(toolFor([file!]), { attachmentId: 'file-1' })
+ expect(output.is_error).toBe(false)
+ expect(body).toMatchObject({
+ kind: 'text',
+ text: '',
+ byteRange: { offset: 0, length: 0 },
+ truncated: false,
+ })
+ })
+
+ it('pages a text over the per-call limit without splitting a code point', async () => {
+ // 'é' is two bytes; an odd prefix byte puts every page boundary mid-character.
+ const original = `x${'é'.repeat(150_000)}${SENTINEL}`
+ const bytes = Buffer.from(original)
+ expect(bytes.length).toBeGreaterThan(READ_LIMIT)
+ const [file] = admitted([rawFile('file-1', 'long.txt', 'text/plain', bytes)])
+ const tool = toolFor([file!])
+
+ const pages: string[] = []
+ let offset = 0
+ let truncated = true
+ let calls = 0
+ while (truncated) {
+ const { output, body } = await read(tool, { attachmentId: 'file-1', offset })
+ expect(output.is_error).toBe(false)
+ const range = body.byteRange as { offset: number; length: number }
+ expect(range.offset).toBe(offset)
+ expect(range.length).toBeGreaterThan(0)
+ expect(range.length).toBeLessThanOrEqual(READ_LIMIT)
+ pages.push(body.text as string)
+ offset += range.length
+ truncated = body.truncated as boolean
+ calls += 1
+ }
+ expect(calls).toBe(2)
+ // Witness: text came back, and none of it is a replacement character.
+ expect(pages[0]!.length).toBeGreaterThan(0)
+ expect(pages.join('')).toBe(original)
+ expect(pages.join('')).not.toContain('�')
+ expect(offset).toBe(bytes.length)
+ })
+
+ it('drops a byte order mark only at the start of the file', async () => {
+ const bytes = Buffer.concat([
+ Buffer.from([0xef, 0xbb, 0xbf]),
+ Buffer.from('ab'),
+ Buffer.from([0xef, 0xbb, 0xbf]),
+ Buffer.from('cd'),
+ ])
+ const [file] = admitted([rawFile('file-1', 'bom.txt', 'text/plain', bytes)])
+ const tool = toolFor([file!])
+ const whole = await read(tool, { attachmentId: 'file-1' })
+ expect(whole.body).toMatchObject({ text: 'abcd', byteRange: { offset: 0, length: 10 } })
+ const inner = await read(tool, { attachmentId: 'file-1', offset: 5 })
+ expect(inner.body).toMatchObject({ text: 'cd', byteRange: { offset: 5, length: 5 } })
+ })
+
+ it('answers attachment_not_found for an unknown id or an image id', async () => {
+ const [image, file] = admitted([
+ {
+ id: 'image-1',
+ kind: 'image',
+ mimeType: 'image/png',
+ encoding: 'base64',
+ dataBase64: PNG_SIGNATURE.toString('base64'),
+ },
+ rawFile('file-1', 'notes.txt', 'text/plain', Buffer.from(SENTINEL)),
+ ])
+ const tool = toolFor([image!, file!])
+ // Control: the listed file is readable through the same tool.
+ expect((await read(tool, { attachmentId: 'file-1' })).body.text).toBe(SENTINEL)
+ for (const attachmentId of ['file-2', 'image-1', undefined, 42]) {
+ const { output, body } = await read(tool, { attachmentId })
+ expect(output.is_error).toBe(true)
+ expect(body.error).toBe('attachment_not_found')
+ }
+ })
+
+ it.each([
+ ['offset past the end', { offset: 100 }],
+ ['negative offset', { offset: -1 }],
+ ['fractional offset', { offset: 1.5 }],
+ ['string offset', { offset: '0' }],
+ ['offset inside a character', { offset: 2 }],
+ ['maxBytes zero', { maxBytes: 0 }],
+ ['maxBytes over the per-call limit', { maxBytes: READ_LIMIT + 1 }],
+ ['maxBytes smaller than the character at offset', { offset: 1, maxBytes: 1 }],
+ ])('answers range_invalid for %s', async (_label, range) => {
+ // 'aé!' = 61 C3 A9 21: offset 2 is a continuation byte.
+ const [file] = admitted([rawFile('file-1', 'notes.txt', 'text/plain', Buffer.from('aé!'))])
+ const tool = toolFor([file!])
+ // Control: a valid page of the same file succeeds.
+ expect((await read(tool, { attachmentId: 'file-1', offset: 1, maxBytes: 2 })).body.text).toBe(
+ 'é'
+ )
+ const { output, body } = await read(tool, { attachmentId: 'file-1', ...range })
+ expect(output.is_error).toBe(true)
+ expect(body.error).toBe('range_invalid')
+ })
+
+ it('reads the end of the file as an empty, untruncated page', async () => {
+ const [file] = admitted([rawFile('file-1', 'notes.txt', 'text/plain', Buffer.from('abc'))])
+ const { body } = await read(toolFor([file!]), { attachmentId: 'file-1', offset: 3 })
+ expect(body).toMatchObject({ text: '', byteRange: { offset: 3, length: 0 }, truncated: false })
+ })
+})
diff --git a/mcp-host/src/core/tools/__tests__/nativeToolRegistry.attachmentRead.test.ts b/mcp-host/src/core/tools/__tests__/nativeToolRegistry.attachmentRead.test.ts
new file mode 100644
index 000000000..ae5103404
--- /dev/null
+++ b/mcp-host/src/core/tools/__tests__/nativeToolRegistry.attachmentRead.test.ts
@@ -0,0 +1,109 @@
+/**
+ * #666 — `clerum__attachment_read` is presented only for a message that
+ * carries `kind:'file'` attachments, and registering it requires its limit.
+ */
+import { describe, expect, it } from 'vitest'
+import { createHash } from 'node:crypto'
+import { validateIncomingAttachments } from '../../../agent/incomingAttachments'
+import type { IncomingMessage } from '../../../server'
+import type { NativeToolConfig } from '../../interfaces'
+import type { Attachment } from '../../types'
+import { NativeToolRegistry } from '../nativeToolRegistry'
+
+const config: NativeToolConfig = {
+ workspacePath: '/tmp',
+ shellTimeout: 5000,
+ toolTimeout: 60000,
+ toolProgressInterval: 30000,
+ httpAllowlist: [],
+ envAllowlist: ['PATH'],
+ memoryMaxSize: 1048576,
+ attachmentTextReadMaxBytes: 262_144,
+}
+
+function attachments(kind: 'file' | 'image'): Attachment[] {
+ const bytes =
+ kind === 'file'
+ ? Buffer.from('notes')
+ : Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+ const raw =
+ kind === 'file'
+ ? {
+ id: 'file-1',
+ kind: 'file',
+ mimeType: 'text/plain',
+ detectedMediaType: 'text/plain',
+ encoding: 'base64',
+ dataBase64: bytes.toString('base64'),
+ filename: 'notes.txt',
+ sizeBytes: bytes.length,
+ digest: { algorithm: 'sha256', hex: createHash('sha256').update(bytes).digest('hex') },
+ }
+ : {
+ id: 'image-1',
+ kind: 'image',
+ mimeType: 'image/png',
+ encoding: 'base64',
+ dataBase64: bytes.toString('base64'),
+ }
+ const result = validateIncomingAttachments([raw], {
+ maxCount: 20,
+ maxBytes: 1_000_000,
+ maxFileBytes: 3_145_728,
+ messageId: 'message-1',
+ })
+ if (!result.ok) throw new Error(`fixture rejected: ${result.error.code}`)
+ return result.attachments!
+}
+
+function message(attached?: Attachment[]): IncomingMessage {
+ return {
+ content: 'Analyze the attached file',
+ channelType: 'rpc',
+ channelId: 'agent-1',
+ sender: 'user-1',
+ timestamp: '2026-09-24T10:00:00Z',
+ messageId: 'message-1',
+ hostRef: 'host-1',
+ ...(attached ? { attachments: attached } : {}),
+ }
+}
+
+function toolNames(registry: NativeToolRegistry): string[] {
+ return registry.listDefinitions().map(definition => definition.name)
+}
+
+describe('NativeToolRegistry — clerum__attachment_read (#666)', () => {
+ it('registers the tool for a message with a kind:file attachment', () => {
+ const registry = new NativeToolRegistry(
+ config,
+ 'conv-1',
+ undefined,
+ message(attachments('file'))
+ )
+ expect(toolNames(registry)).toContain('clerum__attachment_read')
+ expect(registry.get('clerum__attachment_read')!.parametersSchema()).toMatchObject({
+ properties: { maxBytes: { maximum: 262_144 } },
+ })
+ })
+
+ it.each([
+ ['no source message', undefined],
+ ['no attachments', message()],
+ ['only image attachments', message(attachments('image'))],
+ ])('does not register the tool with %s', (_label, source) => {
+ const registry = new NativeToolRegistry(config, 'conv-1', undefined, source)
+ // Witness: the registry was built and presents its always-on native tools.
+ expect(toolNames(registry)).toContain('file_read')
+ expect(toolNames(registry)).not.toContain('clerum__attachment_read')
+ })
+
+ it('refuses to build without the per-call limit when a file is attached', () => {
+ const { attachmentTextReadMaxBytes: _omitted, ...withoutLimit } = config
+ // Control: the same config builds when no file is attached.
+ expect(() => new NativeToolRegistry(withoutLimit, 'conv-1', undefined, message())).not.toThrow()
+ expect(
+ () => new NativeToolRegistry(withoutLimit, 'conv-1', undefined, message(attachments('file')))
+ ).toThrow('NativeToolConfig.attachmentTextReadMaxBytes is required for file attachments')
+ })
+})
diff --git a/mcp-host/src/core/tools/attachmentRead.ts b/mcp-host/src/core/tools/attachmentRead.ts
new file mode 100644
index 000000000..30bd0105d
--- /dev/null
+++ b/mcp-host/src/core/tools/attachmentRead.ts
@@ -0,0 +1,182 @@
+/**
+ * #666 — `clerum__attachment_read` native tool.
+ *
+ * Reads a `kind:'file'` attachment of the message that started this turn. The
+ * turn context lists those files (`attached_file: id=… reader=…`); the content
+ * never reaches the model up front, only through this tool, and its output is
+ * sanitized like any other untrusted tool result.
+ *
+ * - `reader:'text'`: strict UTF-8 text, paged by byte `offset` and `maxBytes`
+ * (at most `attachmentTextReadMaxBytes` per call). A page never splits a
+ * code point, so the text never carries U+FFFD.
+ * - `reader:'none'`: a typed binary result; the bytes are never decoded.
+ *
+ * The text-or-binary rule is the one `clerum__gfs_read` applies
+ * (`decodeTextContent`), and it has the last word: the portable classifier
+ * accepts a few inputs it rejects (DEL, a `GIF8`/`RIFF` text prefix), which
+ * come back as `reason:'text_decode_rejected'`. The tool logs nothing:
+ * neither the name nor the text.
+ */
+import type { FileReferenceV1 } from '@clerum/gfs-interaction-policy'
+import { decodeTextContent } from '../../internalTools/textContent'
+import type { IncomingMessage } from '../../server'
+import type { Tool, ToolTraceDescriptor } from '../interfaces'
+import type { ToolOutput } from '../types'
+
+export type AttachmentReadErrorCode = 'attachment_not_found' | 'range_invalid'
+
+export type AttachmentReadResult =
+ | {
+ reference: FileReferenceV1
+ kind: 'text'
+ text: string
+ byteRange: { offset: number; length: number }
+ truncated: boolean
+ }
+ | { reference: FileReferenceV1; kind: 'binary'; reader: 'none'; reason: string }
+
+const ERROR_MESSAGES: Record<AttachmentReadErrorCode, string> = {
+ attachment_not_found: 'No file with this attachmentId is attached to the current message.',
+ range_invalid:
+ 'offset must be an integer within the file on a character boundary, and maxBytes an integer from 1 to the per-call limit that covers at least one character.',
+}
+
+function isUtf8Continuation(byte: number): boolean {
+ return (byte & 0xc0) === 0x80
+}
+
+export class AttachmentReadTool implements Tool {
+ constructor(
+ private readonly sourceMessage: IncomingMessage,
+ private readonly maxBytesPerCall: number
+ ) {}
+
+ name(): string {
+ return 'clerum__attachment_read'
+ }
+
+ description(): string {
+ return (
+ 'Read a file attached to the current message, by the attachmentId listed as attached_file in the turn context. ' +
+ 'Files with reader=text return UTF-8 text; read further pages with offset when truncated is true. ' +
+ 'Files with reader=none return a binary result without content. ' +
+ 'A reader=text file whose bytes fail the text check also returns a binary result; ' +
+ 'say the file cannot be read instead of guessing its content.'
+ )
+ }
+
+ parametersSchema(): Record<string, unknown> {
+ return {
+ type: 'object',
+ properties: {
+ attachmentId: {
+ type: 'string',
+ description: 'The id of an attached_file line in the turn context.',
+ },
+ offset: {
+ type: 'integer',
+ minimum: 0,
+ default: 0,
+ description:
+ 'Byte offset to start reading from (byteRange.offset + byteRange.length of the previous page).',
+ },
+ maxBytes: {
+ type: 'integer',
+ minimum: 1,
+ maximum: this.maxBytesPerCall,
+ default: this.maxBytesPerCall,
+ description: 'Maximum bytes to read in this call.',
+ },
+ },
+ required: ['attachmentId'],
+ }
+ }
+
+ requiresSanitization(): boolean {
+ return true
+ }
+
+ requiresApproval(): boolean {
+ return false
+ }
+
+ traceDescriptor(): ToolTraceDescriptor {
+ return { kind: 'internal_tool', sourceRef: 'mcp-host' }
+ }
+
+ async execute(params: Record<string, unknown>): Promise<ToolOutput> {
+ const start = Date.now()
+ const attachment = this.sourceMessage.attachments?.find(
+ candidate =>
+ candidate.kind === 'file' &&
+ candidate.id === params.attachmentId &&
+ candidate.fileReference !== undefined
+ )
+ const reference = attachment?.fileReference
+ if (!attachment || !reference) return this.error('attachment_not_found', start)
+
+ const offset = params.offset ?? 0
+ const maxBytes = params.maxBytes ?? this.maxBytesPerCall
+ if (
+ typeof offset !== 'number' ||
+ !Number.isSafeInteger(offset) ||
+ offset < 0 ||
+ typeof maxBytes !== 'number' ||
+ !Number.isSafeInteger(maxBytes) ||
+ maxBytes < 1 ||
+ maxBytes > this.maxBytesPerCall
+ ) {
+ return this.error('range_invalid', start)
+ }
+
+ if (reference.reader === 'none') {
+ return this.ok(
+ { reference, kind: 'binary', reader: 'none', reason: 'no_reader_for_class' },
+ start
+ )
+ }
+
+ const bytes = Buffer.from(attachment.dataBase64, 'base64')
+ if (decodeTextContent(bytes) === null) {
+ return this.ok(
+ { reference, kind: 'binary', reader: 'none', reason: 'text_decode_rejected' },
+ start
+ )
+ }
+ if (offset > bytes.length) return this.error('range_invalid', start)
+ if (offset < bytes.length && isUtf8Continuation(bytes[offset]!)) {
+ return this.error('range_invalid', start)
+ }
+ let end = Math.min(offset + maxBytes, bytes.length)
+ while (end < bytes.length && isUtf8Continuation(bytes[end]!)) end -= 1
+ if (end === offset && offset < bytes.length) return this.error('range_invalid', start)
+
+ // A byte order mark is dropped only at the start of the file; further in,
+ // U+FEFF is file content and stays.
+ const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: offset > 0 }).decode(
+ bytes.subarray(offset, end)
+ )
+ return this.ok(
+ {
+ reference,
+ kind: 'text',
+ text,
+ byteRange: { offset, length: end - offset },
+ truncated: end < bytes.length,
+ },
+ start
+ )
+ }
+
+ private ok(result: AttachmentReadResult, start: number): ToolOutput {
+ return { content: JSON.stringify(result), duration_ms: Date.now() - start, is_error: false }
+ }
+
+ private error(code: AttachmentReadErrorCode, start: number): ToolOutput {
+ return {
+ content: JSON.stringify({ error: code, message: ERROR_MESSAGES[code] }),
+ duration_ms: Date.now() - start,
+ is_error: true,
+ }
+ }
+}
diff --git a/mcp-host/src/core/tools/nativeToolRegistry.ts b/mcp-host/src/core/tools/nativeToolRegistry.ts
index 5312238d3..70ac65ea0 100644
--- a/mcp-host/src/core/tools/nativeToolRegistry.ts
+++ b/mcp-host/src/core/tools/nativeToolRegistry.ts
@@ -18,6 +18,7 @@ import { type ExecutionContext, NativeToolConfig, Tool, ToolRegistry } from '../
import type { SessionSearchService } from '../sessionSearch'
import type { SpilloverStorage } from '../spillover'
import { ToolDefinition, ToolOutput } from '../types'
+import { AttachmentReadTool } from './attachmentRead'
import { CronManageTool } from './cronManage'
import { FileReadTool } from './fileRead'
import { FileWriteTool } from './fileWrite'
@@ -259,6 +260,18 @@ export class NativeToolRegistry implements ToolRegistry {
this.register(new SessionSearchTool(sessionSearchService, sourceMessage))
}
+ // #666 — `clerum__attachment_read` reads the `kind:'file'` attachments of
+ // the message that started this turn. Only registered when there is one.
+ if (sourceMessage?.attachments?.some(a => a.kind === 'file')) {
+ const maxBytes = config.attachmentTextReadMaxBytes
+ if (maxBytes === undefined) {
+ throw new Error(
+ 'NativeToolConfig.attachmentTextReadMaxBytes is required for file attachments'
+ )
+ }
+ this.register(new AttachmentReadTool(sourceMessage, maxBytes))
+ }
+
const envGetter = (key: string): string | undefined => {
const fromStore = dynamicEnvProvider?.()[key]
if (typeof fromStore === 'string' && fromStore.length > 0) return fromStore
diff --git a/mcp-host/src/core/types.ts b/mcp-host/src/core/types.ts
index 2311f58ad..7ed757080 100644
--- a/mcp-host/src/core/types.ts
+++ b/mcp-host/src/core/types.ts
@@ -6,6 +6,7 @@
*
* Phase 1: Pure type definitions — no runtime behavior changes.
*/
+import type { FileReferenceDigest, FileReferenceV1 } from '@clerum/gfs-interaction-policy'
import type { GfsImageSource } from '../visualInput/policy'
import type { SystemPromptParts } from './reasoning/systemPrompt'
@@ -130,6 +131,15 @@ export interface Attachment {
producer?: string
/** Producer-validated provenance; never supplied by model arguments. */
visualSource?: GfsImageSource
+ /** Inline `kind:'file'` only: media type the host detected from the bytes. */
+ detectedMediaType?: string
+ /** Inline `kind:'file'` only: digest the host recomputed and verified. */
+ digest?: FileReferenceDigest
+ /**
+ * Inline `kind:'file'` only, set by admission. Internal: it is described to
+ * the model through the turn context and never serialized as content.
+ */
+ fileReference?: FileReferenceV1
}
// ─── Completion Types ───────────────────────────────────────
diff --git a/mcp-host/src/internalTools/gfs.ts b/mcp-host/src/internalTools/gfs.ts
index 30ceee07d..71932f09e 100644
--- a/mcp-host/src/internalTools/gfs.ts
+++ b/mcp-host/src/internalTools/gfs.ts
@@ -8,6 +8,7 @@ import type {
} from '../workflow/types'
import { GfscHttpError } from './gfsClient'
import type { GfsFileContent, GfsReadOptions } from './gfsReadTypes'
+import { decodeTextContent } from './textContent'
/**
* Agent gfs READ tools (spec community.md §Operator surfaces, plan P3-S04).
@@ -70,20 +71,6 @@ function fileReference(file: GfsFileContent, reason: string): InternalToolResult
})
}
-function isNonTextFormat(bytes: Buffer): boolean {
- const signature = bytes.byteLength >= 4 ? bytes.readUInt32LE(0) : 0
- const gif = bytes.subarray(0, 6).toString('ascii')
- return (
- bytes.subarray(0, 5).equals(Buffer.from('%PDF-')) ||
- [0x04034b50, 0x06054b50, 0x08074b50].includes(signature) ||
- gif === 'GIF87a' ||
- gif === 'GIF89a' ||
- (bytes.subarray(0, 4).equals(Buffer.from('RIFF')) &&
- ['WEBP', 'WAVE', 'AVI '].includes(bytes.subarray(8, 12).toString('ascii'))) ||
- (bytes[0] === 0x1f && bytes[1] === 0x8b)
- )
-}
-
function isSvgText(text: string): boolean {
let remaining = text.trimStart()
// Scan each prefix once; do not use a repeated, backtracking XML regex on
@@ -225,20 +212,9 @@ export function buildGfsReadTools(client: GfscReadClient): InternalToolDefinitio
}
if (/\.(?:png|jpe?g)$/i.test(file.source.name))
throw new VisualInputError('invalid_image')
- if (isNonTextFormat(file.bytes)) return fileReference(file, 'unsupported_binary_format')
- let text: string
- try {
- // Same fileBytes cap as images (G0). TextDecoder already drops a
- // UTF-8 BOM; strip again so classification and the model see the
- // same contract.
- text = new TextDecoder('utf-8', { fatal: true })
- .decode(file.bytes)
- .replace(/^\uFEFF/, '')
- } catch {
- return fileReference(file, 'unsupported_binary_format')
- }
- if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/.test(text))
- return fileReference(file, 'unsupported_binary_format')
+ // Same fileBytes cap as images (G0); same text rule as clerum__attachment_read.
+ const text = decodeTextContent(file.bytes)
+ if (text === null) return fileReference(file, 'unsupported_binary_format')
if (isSvgText(text)) return fileReference(file, 'svg_visual_input_not_supported')
return ok(text)
} catch (err) {
diff --git a/mcp-host/src/internalTools/textContent.ts b/mcp-host/src/internalTools/textContent.ts
new file mode 100644
index 000000000..52ebd5599
--- /dev/null
+++ b/mcp-host/src/internalTools/textContent.ts
@@ -0,0 +1,40 @@
+/**
+ * The text-or-binary decision shared by `clerum__gfs_read` and
+ * `clerum__attachment_read` (#666): one rule for every tool that hands file
+ * bytes to the model as text.
+ */
+
+/** Signatures of formats that must never be returned as text (PDF, ZIP, GIF, RIFF, gzip). */
+export function isNonTextFormat(bytes: Uint8Array): boolean {
+ const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+ const signature = buffer.byteLength >= 4 ? buffer.readUInt32LE(0) : 0
+ const gif = buffer.subarray(0, 6).toString('ascii')
+ return (
+ buffer.subarray(0, 5).equals(Buffer.from('%PDF-')) ||
+ [0x04034b50, 0x06054b50, 0x08074b50].includes(signature) ||
+ gif === 'GIF87a' ||
+ gif === 'GIF89a' ||
+ (buffer.subarray(0, 4).equals(Buffer.from('RIFF')) &&
+ ['WEBP', 'WAVE', 'AVI '].includes(buffer.subarray(8, 12).toString('ascii'))) ||
+ (buffer[0] === 0x1f && buffer[1] === 0x8b)
+ )
+}
+
+/**
+ * The file as text, or null when it is not text: a binary signature, bytes
+ * that are not strict UTF-8, or C0/C1 control characters other than TAB, LF
+ * and CR. A leading UTF-8 byte order mark is dropped.
+ */
+export function decodeTextContent(bytes: Uint8Array): string | null {
+ if (isNonTextFormat(bytes)) return null
+ let text: string
+ try {
+ // TextDecoder already drops a UTF-8 BOM; strip again so classification
+ // and the model see the same contract.
+ text = new TextDecoder('utf-8', { fatal: true }).decode(bytes).replace(/^/, '')
+ } catch {
+ return null
+ }
+ if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/.test(text)) return null
+ return text
+}
diff --git a/mcp-host/src/lifecycle/taskLifecycle.ts b/mcp-host/src/lifecycle/taskLifecycle.ts
index 24e58b528..0fabaa057 100644
--- a/mcp-host/src/lifecycle/taskLifecycle.ts
+++ b/mcp-host/src/lifecycle/taskLifecycle.ts
@@ -69,6 +69,9 @@ export class TaskLifecycle extends EventEmitter {
submittedBy: task.sourceMessage?.sender ?? null,
submittedChannelType: task.sourceMessage?.channelType ?? null,
submittedChannelId: task.sourceMessage?.channelId ?? null,
+ // Admission already replaced `attachments` with the validated list.
+ acceptedAttachmentIds:
+ task.sourceMessage?.attachments?.map(attachment => attachment.id) ?? [],
traceContext: task.traceContext ?? null,
createdAt: now,
}
diff --git a/mcp-host/src/lifecycle/types.ts b/mcp-host/src/lifecycle/types.ts
index 235f94dbf..c410aaaf3 100644
--- a/mcp-host/src/lifecycle/types.ts
+++ b/mcp-host/src/lifecycle/types.ts
@@ -72,6 +72,11 @@ export interface TaskRecord {
submittedBy: string | null
submittedChannelType: string | null
submittedChannelId: string | null
+ /**
+ * Ids of the incoming attachments admitted with this task (#666). A replayed
+ * delivery answers with them, exactly like the first response did.
+ */
+ acceptedAttachmentIds: readonly string[]
traceContext: TraceContextV1 | null
createdAt: Date
dispatchedAt?: Date
diff --git a/mcp-host/src/main.ts b/mcp-host/src/main.ts
index de5a4d44a..bb47a8ce2 100644
--- a/mcp-host/src/main.ts
+++ b/mcp-host/src/main.ts
@@ -19,8 +19,8 @@ import type { ResolvedTaskModel } from './agent'
import { agentToolEnvProvider } from './agent/agentToolEnv'
import type { PendingCronResult } from './agent/cronDispatch'
import { createIncomingAdmission } from './agent/incomingAdmission'
+import { INCOMING_ATTACHMENT_MAX_COUNT } from './agent/incomingAttachments'
import { IncomingDelivery } from './agent/incomingDelivery'
-import { INCOMING_IMAGE_MAX_COUNT } from './agent/incomingImageAttachments'
import {
type SessionModelSelectionOptions,
applySessionModelSelection as applySessionModelSelectionCore,
@@ -2000,7 +2000,11 @@ function handleIncomingMessage(
}
const prepareIncomingMessage = createIncomingAdmission({
- limits: { maxCount: INCOMING_IMAGE_MAX_COUNT, maxBytes: config.attachmentMaxBytes },
+ limits: {
+ maxCount: INCOMING_ATTACHMENT_MAX_COUNT,
+ maxBytes: config.attachmentMaxBytes,
+ maxFileBytes: config.attachmentFileMaxBytes,
+ },
queueReady: () => Boolean(messageQueue),
degradedReason: computeDegradedReason,
hostProvider: () => currentHost?.spec.model?.provider,
diff --git a/mcp-host/src/messageHandler.ts b/mcp-host/src/messageHandler.ts
index 7910568f6..0dfacfa82 100644
--- a/mcp-host/src/messageHandler.ts
+++ b/mcp-host/src/messageHandler.ts
@@ -325,6 +325,11 @@ export class IncomingMessageHandler {
'Duplicate delivery suppressed'
)
const record = this.deps.taskLifecycle.get(priorTaskId)
+ // #666 — a success names the attachments the first delivery admitted, as
+ // the first response did; without them a client reads a Host that dropped them.
+ const accepted = record?.acceptedAttachmentIds.length
+ ? { acceptedAttachmentIds: [...record.acceptedAttachmentIds] }
+ : {}
if (priorStatus === 'completed') {
return {
success: true,
@@ -333,6 +338,7 @@ export class IncomingMessageHandler {
attachments: this.deps.sanitizeAttachments(record?.attachments),
model: this.deps.getModel(),
taskId: priorTaskId,
+ ...accepted,
}
}
if (priorStatus === 'failed' || priorStatus === 'cancelled') {
@@ -355,6 +361,7 @@ export class IncomingMessageHandler {
success: true,
status: 'pending',
taskId: priorTaskId,
+ ...accepted,
}
}
diff --git a/mcp-host/src/server/__tests__/messageRoute.test.ts b/mcp-host/src/server/__tests__/messageRoute.test.ts
index 66e2750bd..5398d0f26 100644
--- a/mcp-host/src/server/__tests__/messageRoute.test.ts
+++ b/mcp-host/src/server/__tests__/messageRoute.test.ts
@@ -1,8 +1,11 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import type { Request, Response } from 'express'
+import { createHash } from 'node:crypto'
+import { type IncomingAdmissionDeps, createIncomingAdmission } from '../../agent/incomingAdmission'
import { config } from '../../config'
import { ConversationError, ConversationErrorCode } from '../../core/errors'
import { handleMessageRoute } from '../routes'
+import type { MessageResponse } from '../types'
import { makeHandlers } from './testHelpers'
interface CapturedRes {
@@ -300,3 +303,103 @@ describe('handleMessageRoute — async response serialization', () => {
expect(captured.jsonBody).toEqual(ack)
})
})
+
+describe('handleMessageRoute — acceptedAttachmentIds through the real admission (issue #666)', () => {
+ beforeEach(() => {
+ ;(config as { enableAuth: boolean }).enableAuth = true
+ })
+
+ const NOTES = Buffer.from('# Notes\n', 'utf8')
+ const file = {
+ id: 'file-1',
+ kind: 'file',
+ mimeType: 'text/markdown',
+ detectedMediaType: 'text/markdown',
+ encoding: 'base64',
+ dataBase64: NOTES.toString('base64'),
+ filename: 'notes.md',
+ sizeBytes: NOTES.length,
+ digest: { algorithm: 'sha256', hex: createHash('sha256').update(NOTES).digest('hex') },
+ }
+
+ function routeThroughAdmission(ack: MessageResponse) {
+ const dispatch = vi.fn<IncomingAdmissionDeps['dispatch']>(() => ack)
+ const messageHandler = createIncomingAdmission({
+ limits: { maxCount: 20, maxBytes: 1_000_000, maxFileBytes: 1_000_000 },
+ queueReady: () => true,
+ degradedReason: () => null,
+ hostProvider: () => 'zai',
+ getConversationByKey: async () => undefined,
+ resolveTaskModel: () => null,
+ resolveImageInput: () => undefined,
+ applySessionModelSelection: vi.fn(),
+ dispatch,
+ logger: { info: vi.fn(), warn: vi.fn() },
+ })
+ return { dispatch, handlers: makeHandlers({ messageHandler }) }
+ }
+
+ function rpcRequest(attachments: unknown[] | undefined, query: Record<string, string>) {
+ return {
+ runtimeCaller: { caller: 'rpc-proxy', hostRef: 'chatllm', userId: 'legit-user' },
+ body: {
+ sender: 'legit-user',
+ channelType: 'rpc',
+ channelId: 'agent-x',
+ threadId: 'chat-1',
+ content: 'Analyze the attached file',
+ timestamp: 'now',
+ messageId: 'm1',
+ hostRef: 'chatllm',
+ ...(attachments ? { attachments } : {}),
+ },
+ query,
+ } as unknown as Request
+ }
+
+ it('returns the accepted ids on the sync response', async () => {
+ const { dispatch, handlers } = routeThroughAdmission({ success: true, status: 'completed' })
+ const captured = makeRes()
+
+ await handleMessageRoute(rpcRequest([file], {}), captured.res, handlers)
+
+ expect(dispatch).toHaveBeenCalledWith(expect.objectContaining({ messageId: 'm1' }), undefined)
+ expect(captured.statusCode).toBe(200)
+ expect(captured.jsonBody).toEqual({
+ success: true,
+ status: 'completed',
+ acceptedAttachmentIds: ['file-1'],
+ })
+ })
+
+ it('returns the accepted ids on the async=true ack', async () => {
+ const { dispatch, handlers } = routeThroughAdmission({
+ success: true,
+ status: 'pending',
+ taskId: 'task-1',
+ })
+ const captured = makeRes()
+
+ await handleMessageRoute(rpcRequest([file], { async: 'true' }), captured.res, handlers)
+
+ expect(dispatch).toHaveBeenCalledWith(expect.anything(), { async: true })
+ expect(captured.jsonBody).toEqual({
+ success: true,
+ status: 'pending',
+ taskId: 'task-1',
+ acceptedAttachmentIds: ['file-1'],
+ })
+ })
+
+ it('omits the field on a text-only message', async () => {
+ const ack: MessageResponse = { success: true, status: 'pending', taskId: 'task-2' }
+ const { dispatch, handlers } = routeThroughAdmission(ack)
+ const captured = makeRes()
+
+ await handleMessageRoute(rpcRequest(undefined, { async: 'true' }), captured.res, handlers)
+
+ // Witness: the text turn was dispatched and its ack serialized.
+ expect(dispatch).toHaveBeenCalledTimes(1)
+ expect(captured.jsonBody).toEqual(ack)
+ })
+})
diff --git a/mcp-host/src/server/types.ts b/mcp-host/src/server/types.ts
index 83fb03c71..a4ca2a072 100644
--- a/mcp-host/src/server/types.ts
+++ b/mcp-host/src/server/types.ts
@@ -77,6 +77,14 @@ export interface MessageResponse {
error?: TaskError
model?: string
taskId?: string
+ /**
+ * Issue #666 — ids of every incoming attachment (images and files) the Host
+ * validated and handed to the task, on the sync response and on the
+ * `?async=true` ack. Absent on a text-only message and on every refusal. A
+ * client that sent files and gets a success without its ids is talking to a
+ * Host that cannot read file attachments.
+ */
+ acceptedAttachmentIds?: string[]
/**
* Issue #654 — the session's model-selection revision after the Host accepted
* a piggybacked `model`, or the winning revision on a CAS conflict.
diff --git a/rpc-proxy/package-lock.json b/rpc-proxy/package-lock.json
index 2c1a7913d..1e5967806 100644
--- a/rpc-proxy/package-lock.json
+++ b/rpc-proxy/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-rpc-proxy",
- "version": "0.1.89",
+ "version": "0.1.90",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-rpc-proxy",
- "version": "0.1.89",
+ "version": "0.1.90",
"dependencies": {
"cors": "^2.8.5",
"express": "^4.21.2",
diff --git a/rpc-proxy/package.json b/rpc-proxy/package.json
index c07c44edd..cf15847a3 100644
--- a/rpc-proxy/package.json
+++ b/rpc-proxy/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-rpc-proxy",
- "version": "0.1.89",
+ "version": "0.1.90",
"description": "External-facing RPC proxy for tenant-scoped MCP access",
"main": "dist/main.js",
"engines": {
diff --git a/rpc-proxy/src/__tests__/bodylimits.test.ts b/rpc-proxy/src/__tests__/bodylimits.test.ts
index 2b1263ad2..83c2fcd40 100644
--- a/rpc-proxy/src/__tests__/bodylimits.test.ts
+++ b/rpc-proxy/src/__tests__/bodylimits.test.ts
@@ -306,6 +306,97 @@ describe('rpc-proxy chat message body budget', () => {
expect(response.status).toBe(413)
})
+ describe('kind:file attachments (issue #666)', () => {
+ const NON_IMAGE_BUDGET = 6 * MIB
+ const KIB = 1024
+
+ function fileAttachment(dataBase64: string) {
+ return {
+ id: 'f1',
+ kind: 'file',
+ mimeType: 'text/plain',
+ detectedMediaType: 'text/plain',
+ encoding: 'base64',
+ dataBase64,
+ filename: 'notes.txt',
+ sizeBytes: 0,
+ digest: { algorithm: 'sha256', hex: '0'.repeat(64) },
+ }
+ }
+
+ /** A message whose serialized body is exactly `targetBytes`, almost all of it file base64. */
+ function fileMessageOfBodySize(targetBytes: number) {
+ const overhead = Buffer.byteLength(
+ JSON.stringify({ content: 'look', attachments: [fileAttachment('')] })
+ )
+ const fill = targetBytes - overhead
+ const payload = {
+ content: `look${'x'.repeat(fill % 4)}`,
+ attachments: [fileAttachment('A'.repeat(fill - (fill % 4)))],
+ }
+ expect(Buffer.byteLength(JSON.stringify(payload))).toBe(targetBytes)
+ return payload
+ }
+
+ function forwardedBody(): { attachments?: unknown[] } {
+ expect(serviceMock.forwardHostMessageToHost).toHaveBeenCalledTimes(1)
+ return serviceMock.forwardHostMessageToHost.mock.calls[0]![1] as { attachments?: unknown[] }
+ }
+
+ it('forwards a complete kind:file attachment without dropping a field', async () => {
+ const attachment = {
+ ...fileAttachment(Buffer.from('# notes\n').toString('base64')),
+ mimeType: 'text/markdown',
+ detectedMediaType: 'text/markdown',
+ filename: 'notes.md',
+ sizeBytes: 8,
+ digest: { algorithm: 'sha256', hex: 'ab'.repeat(32) },
+ }
+ const response = await postMessage({ content: 'look', attachments: [attachment] })
+ expect(response.status).toBe(200)
+ expect(forwardedBody().attachments).toEqual([attachment])
+ })
+
+ it('carries a file body 1KiB under the non-image budget', async () => {
+ const payload = fileMessageOfBodySize(NON_IMAGE_BUDGET - KIB)
+ const response = await postMessage(payload)
+ expect(response.status).toBe(200)
+ expect(forwardedBody().attachments).toEqual(payload.attachments)
+ })
+
+ it('rejects a file body 1KiB over the non-image budget with 413', async () => {
+ // Control: the same construction under the budget is forwarded.
+ expect((await postMessage(fileMessageOfBodySize(NON_IMAGE_BUDGET - KIB))).status).toBe(200)
+ expect(serviceMock.forwardHostMessageToHost).toHaveBeenCalledTimes(1)
+ vi.clearAllMocks()
+ const response = await postMessage(fileMessageOfBodySize(NON_IMAGE_BUDGET + KIB))
+ expect(response.status).toBe(413)
+ expect(serviceMock.forwardHostMessageToHost).not.toHaveBeenCalled()
+ })
+
+ it('never credits PNG bytes sent as kind:file against the image budget', async () => {
+ const image = imageAttachment('a1', 7 * MIB)
+ const asImage = await postMessage({ content: 'look', attachments: [image] })
+ expect(asImage.status).toBe(200)
+ expect(serviceMock.forwardHostMessageToHost).toHaveBeenCalledTimes(1)
+ vi.clearAllMocks()
+ // Same MIME type and bytes as the image: only `kind` differs.
+ const asFile = await postMessage({
+ content: 'look',
+ attachments: [
+ {
+ ...fileAttachment(image.dataBase64),
+ mimeType: 'image/png',
+ detectedMediaType: 'image/png',
+ filename: 'photo.png',
+ },
+ ],
+ })
+ expect(asFile.status).toBe(413)
+ expect(serviceMock.forwardHostMessageToHost).not.toHaveBeenCalled()
+ })
+ })
+
it('rejects a body past the 24MiB ceiling', async () => {
const response = await postMessage({ content: 'x'.repeat(25 * MIB), attachments: [] })
expect(response.status).toBe(413)
diff --git a/rpc-proxy/src/routes/rpc.ts b/rpc-proxy/src/routes/rpc.ts
index b7027712b..ddaae9b74 100644
--- a/rpc-proxy/src/routes/rpc.ts
+++ b/rpc-proxy/src/routes/rpc.ts
@@ -378,7 +378,7 @@ export function createRpcRouter(): Router {
if (body.attachments != null && !Array.isArray(body.attachments)) {
res
.status(400)
- .json({ error: 'invalid_attachments', message: 'Image attachments must be a list.' })
+ .json({ error: 'invalid_attachments', message: 'Attachments must be a list.' })
return
}
const forwardedBody: HostRuntimeMessageRequest = {
diff --git a/rpc-proxy/test/routes.rpc.test.ts b/rpc-proxy/test/routes.rpc.test.ts
index 97352b4f4..5b9131c8f 100644
--- a/rpc-proxy/test/routes.rpc.test.ts
+++ b/rpc-proxy/test/routes.rpc.test.ts
@@ -402,7 +402,7 @@ describe('routes/rpc', () => {
.set('authorization', 'Bearer rpc-token')
.send({ content: 'hi', attachments: 'nope' })
.expect(400)
- .expect({ error: 'invalid_attachments', message: 'Image attachments must be a list.' })
+ .expect({ error: 'invalid_attachments', message: 'Attachments must be a list.' })
// Witness: the request was authenticated. The shape is rejected before
// host resolution, so a malformed request never writes a binding.