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.tsindex 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.tsindex 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.mdindex 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 CRDdiff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsdeleted file mode 100644index 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.tsindex 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): IncomingAdmessage: 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> | undefinedif (!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): IncomingAdnormalizedMessage.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.tsnew file mode 100644index 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.tsdeleted file mode 100644index 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.tsindex 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 !== undefinedif (m.contentParts && m.contentParts.length > 0) {diff --git a/mcp-host/src/config.ts b/mcp-host/src/config.tsindex 6b7a07e74..64cdf3883 100644--- a/mcp-host/src/config.ts+++ b/mcp-host/src/config.ts@@ -232,6 +232,10 @@ export interface Config {enableResponseAttachments: booleanattachmentMaxCount: numberattachmentMaxBytes: number+ /** Decoded bytes per incoming `kind:'file'` attachment (issue #666). */+ attachmentFileMaxBytes: number+ /** Bytes one `clerum__attachment_read` call may return (issue #666). */+ attachmentTextReadMaxBytes: numberactivityBufferSize: numberactivityMaxEventBytes: 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 deliveryenableResponseAttachments: 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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: Datechannel: TurnContextChannelcron?: 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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 fromStorediff --git a/mcp-host/src/core/types.ts b/mcp-host/src/core/types.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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 | nullsubmittedChannelType: string | nullsubmittedChannelId: 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 | nullcreatedAt: DatedispatchedAt?: Datediff --git a/mcp-host/src/main.ts b/mcp-host/src/main.tsindex 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.tsindex 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.tsindex 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.tsindex 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?: TaskErrormodel?: stringtaskId?: 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.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.