Admit image attachments on text-only model routes (the dispatch layer already degrades them)

[Youchun-show]

Summary

When the session model is text-only, attaching an image and sending the prompt is rejected at admission (session/attachment-invalid / MODEL_DOES_NOT_SUPPORT_IMAGES, thrown by the prompt admission in packages/api/session-controller/src/commands.ts). The message never enters the durable session log, so no turn starts — and per-turn extension points (prompt-context providers, vision-relay plugins) never run. The only user workarounds are switching models, or saving the image to disk and asking the agent to read it by file path.

Why admission can safely allow it

The LLM core already handles exactly this case at dispatch time — packages/llm/llm/src/index.ts projects image blocks to text placeholders whenever the resolved model's inputModalities lack image:

if (modelInfo.inputModalities !== undefined
  && !modelInfo.inputModalities.includes('image')
  && projectedMessages.some(message => contentHasImage(message.content))) {
  projectedMessages = projectImagesForTextModel(projectedMessages)
}

So the admission gate is a UX hard-block sitting on top of a dispatch pipeline that is already safe for text-only routes.

Proposal

Admit image-bearing prompts regardless of the model's image support:

• the message (with its image blocks) enters the durable log — turn-level hooks keep working;
• dispatch keeps degrading image blocks to text placeholders for text-only models (existing behavior);
• attachment-side failures (invalid base64, storage errors) keep their existing error mapping;
• the read_image tool's strict vision-model gate remains unchanged.

Local validation

We have been running this change locally since 2026-09-01: remove the admission block in commands.ts and update session-models.host.spec.ts to expect admission. On d347e70390 (0.1.3-alpha.1), vitest run packages/api/session-controller/tests/session-models.host.spec.ts passes 14/14. It enables a vision-relay plugin pattern in our setup: a plugin describes pasted images through a vision model and injects the descriptions as prompt context, so text-only sessions keep full image workflows.

Happy to share the full diff here if useful (CONTRIBUTING notes external PRs aren't accepted at the moment, so this is a discussion, not a PR).

Environment: DSH 0.1.3-alpha.1 (d347e70390), Windows, web GUI.

[argszero]

Good write-up — both anchors check out on master d347e70390, and I'd frame this as the mirror failure of a known modality-declaration family rather than a standalone UX bug, which shifts the fix calculus a little.

Confirmation:

• Admission gate: packages/api/session-controller/src/commands.ts:319-331 — when the content has an image, prompt() resolves the current selection's model info and throws MODEL_DOES_NOT_SUPPORT_IMAGES before createUserMessage (:338) / followup (:348) — so the message never enters the durable log and no turn-level hook runs. Correct.
• Dispatch safety net: packages/llm/llm/src/index.ts:1032-1039 — every dispatched request already projects files to handle text (:1034-1036) and, when the dispatch-time model info lacks image in inputModalities, projects image blocks to deterministic text placeholders (projectImagesForTextModel, content.ts:298). The pipeline below admission is provably image-safe today.

Why the admission gate is the wrong layer (three independent reasons):

1. Admission-time model ≠ dispatch-time model. The check resolves the selection at prompt() time; the actual dispatch can run under a different resolved route (per-turn overrides, steer/followup paths, subagent delegation). The gate validates a truth the dispatch layer re-checks anyway — with authority.
2. The declaration it trusts is exactly the unreliable one this family documents. Prior reports: `llm-pi-ai`: custom provider entries silently resolve to text-only when the model is actually multimodal (no auto-merge of provider catalog modalities, undocumented per-model `input` field, no vision badge in the model selector) #5837 — custom llm-pi-ai provider entries silently resolve text-only; the llm-deepseek schema defaults inputModalities to ["text"], wiping unknown branches. That axis is full of false negatives — routes that can take images but are declared text-only. Under this gate those false negatives become hard rejections of legitimate attachments: the mirror of `llm-pi-ai`: custom provider entries silently resolve to text-only when the model is actually multimodal (no auto-merge of provider catalog modalities, undocumented per-model `input` field, no vision badge in the model selector) #5837's silent non-delivery. Relaxing the gate while declarations stay wrong just moves the failure mode, so the declaration axis needs fixing in parallel.
3. Plugins are the victims. Per-turn extension points (prompt-context providers, vision-relay plugins) never run because rejection is pre-log. A relay/OCR plugin that would make genuinely text-only routes useful is structurally impossible until the gate admits.

On the proposal itself: admit-and-degrade is directionally right, but I'd keep some user-visible signal for genuinely text-only models. The projection silently replaces pixels with a text placeholder — a user who attached a diagram believing the model saw it gets an invisible loss. The model dropdown already carries per-model modality where the catalog/route metadata exposes it (the #5837/#5840 surface), so a non-fatal send-time warning ("this model is text-only; the image will be degraded to a text placeholder") preserves the intent of today's hard block without the dead-end. Admission + durable-log entry + running hooks is strictly more information-preserving than a hard reject, and genuinely invalid attachments can still surface as the attachment-side failure you describe.

Suggested shape: relax the gate to admit + warn, keep the dispatch projection as the safety net, and fix the declaration axis in parallel so image-capable routes stop being declared text-only. The core hunk is small (commands.ts:322-332) and sits in session-controller (core — upstream-fix candidate, not plugin-mountable), but it is also the unlock that makes vision-relay plugins viable, which is a real ecosystem win.

[Youchun-show]

Thanks for the careful review — the admission-time ≠ dispatch-time point and the #5837 modality-declaration family context are both fair, and we agree the gate is the wrong layer.

We've been running the admit-and-degrade change locally since 2026-09-01 (current master, tests updated, 14/14 green). On your warn-vs-silent point: fully agreed that a visible signal matters. In our setup the degradation is already observable — a vision-relay plugin injects an explicit <image-descriptions> envelope as prompt context, so the user sees exactly what the model was given. For the stock experience, your shape is the right call: a non-fatal send-time warning (where route metadata exposes modality) composes cleanly with this change — admission + durable-log entry + dispatch projection as the safety net.

The diff we run (commands.ts + session-models.host.spec.ts, includes bilingual agent notes):

commit 2e53349865460c9262a22f74bdad1e1f7d36a040
Author: kiness <aelanxu@qq.com>
Date:   Tue Sep 1 13:19:48 2026 +0800

    feat(session-controller): admit images on text-only routes
    
    纯文本路由的带图消息不再被入场门拒绝:消息与附件照常进入持久日志,
    请求层将图片块降级为文本占位,see-image 插件负责转述描述。
    附件侧失败(坏 base64/存储错误)的既有映射不变;read_image 严格门不变。
    配套:测试期望改为放行、Agent Note(implemented/feature)英中双语。

diff --git a/packages/api/session-controller/src/commands.ts b/packages/api/session-controller/src/commands.ts
index 8afa4b13d0..e70898307b 100644
--- a/packages/api/session-controller/src/commands.ts
+++ b/packages/api/session-controller/src/commands.ts
@@ -286,7 +286,12 @@ export class SessionCommandController {
   }
 
   /**
-   * Admit one browser prompt after explicit Agent resume and image validation.
+   * Admit one browser prompt after explicit Agent resume.
+   *
+   * Images ride along on text-only routes: the message enters the durable log
+   * and the request layer degrades image blocks to text placeholders (the
+   * see-image plugin relays descriptions for text-only sessions). Only
+   * attachment-side failures (invalid base64, store errors) reject here.
    * @param request - Session identity, prompt content, source metadata, and delivery mode.
    * @returns acknowledgement that the Agent accepted the prompt.
    */
@@ -319,17 +324,6 @@ export class SessionCommandController {
     const hasImage = request.content.some(part => part.type === 'image')
     const admit = async (): Promise<SessionPromptValue> => {
       try {
-        if (hasImage) {
-          const current = this.agents.selectionFor(agent).current
-          const model = await this.ctx.llm.resolveModelInfo(current.provider, current.model)
-          if (model.inputModalities !== undefined && !model.inputModalities.includes('image')) {
-            throw new RemoteError(
-              'session/attachment-invalid',
-              `Model "${current.model}" does not support image input.`,
-              { reason: 'MODEL_DOES_NOT_SUPPORT_IMAGES' },
-            )
-          }
-        }
         const admission = resolvePromptFileReceipts(
           request.content,
           receiptId => this.ctx.fileUploads.resolve(agent, receiptId),
diff --git a/packages/api/session-controller/tests/session-models.host.spec.ts b/packages/api/session-controller/tests/session-models.host.spec.ts
index 9fe2bd28bb..17bed4f7f2 100644
--- a/packages/api/session-controller/tests/session-models.host.spec.ts
+++ b/packages/api/session-controller/tests/session-models.host.spec.ts
@@ -645,7 +645,7 @@ describe('Web session model selection', () => {
     await ctx.fiber.dispose()
   })
 
-  it('maps image admission failures and accepts image-capable selections', async () => {
+  it('admits images on text-only routes and maps attachment failures', async () => {
     const { ctx, agent, sessionId } = await harness()
     registerTextOnly(ctx)
     ctx.llm.registerAdapter(['image-capable'], new class extends CatalogAdapter {
@@ -685,13 +685,13 @@ describe('Web session model selection', () => {
     expectValue(await remote.selectModel(request({
       sessionId, provider: 'text-only', model: 'plain',
     })))
-    expect(await remote.prompt(promptRequest({
+    // Text-only routes admit images: the message enters the durable log and the
+    // request layer degrades image blocks to text placeholders; the see-image
+    // plugin relays descriptions for text-only sessions.
+    expectValue(await remote.prompt(promptRequest({
       sessionId, mode: 'queue', content: [image],
-    }))).toMatchObject({
-      ok: false,
-      error: { code: 'session/attachment-invalid', details: { reason: 'MODEL_DOES_NOT_SUPPORT_IMAGES' } },
-    })
-
+    })))
+    expect(followup).toHaveBeenCalledOnce()
     expectValue(await remote.selectModel(request({
       sessionId, provider: 'image-capable', model: 'vision',
     })))
@@ -712,7 +712,7 @@ describe('Web session model selection', () => {
     }))).toMatchObject({ ok: false, error: { code: 'gateway/internal', message: 'fixture rejected' } })
     saveMode = 'success'
     expectValue(await remote.prompt(promptRequest({ sessionId, mode: 'queue', content: [image] })))
-    expect(followup).toHaveBeenCalledOnce()
+    expect(followup).toHaveBeenCalledTimes(2)
 
     ;(agent.inbox.nextTurn as UserMessage[]).push({
       id: 'pending-image', role: 'user', source: { kind: 'user' },

If it helps the maintainers evaluate, feel free to lift it — otherwise we'll keep carrying it locally. The declaration-axis fixes (#5837/#5840) sound like the right parallel track; happy to test downstream once those land.