Add web multimodal image attachments

packages/host/apiproxy/package.json

@@ -40,6 +40,7 @@
   ],
   "license": "BSD-3-Clause",
   "dependencies": {
+    "@deepseek-ai/dsh-attachment": "workspace:^",
     "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",

packages/host/apiproxy/src/api/host.schema.ts

@@ -5,6 +5,9 @@
 import { z } from 'zod'
 import type { RequestPayload, ResponseValue } from './rpc-map.ts'
 import type { Wire } from './rpc.schema.ts'
+import { imageMediaTypeSchema } from './sessions.schema.ts'
+
+const modalitySchema = z.union([z.literal('text'), z.literal('image')])
 
 /** host.describe request payload (empty object literal). */
 export const hostDescribeRequestSchema = z.object({}) satisfies z.ZodType<Wire<RequestPayload<'host.describe'>>>
@@ -15,5 +18,20 @@ export const hostDescribeValueSchema = z.object({
   cwd: z.string(),
   provider: z.string().optional(),
   model: z.string().optional(),
+  activeModel: z.object({
+    provider: z.string(),
+    id: z.string(),
+    name: z.string(),
+    description: z.string().optional(),
+    inputModalities: z.array(modalitySchema).optional(),
+    outputModalities: z.array(modalitySchema).optional(),
+  }).optional(),
+  imageLimits: z.object({
+    maxImageBytes: z.number().int().positive(),
+    maxImagesPerMessage: z.number().int().positive(),
+    maxMessageImageBytes: z.number().int().positive(),
+    maxImagePixels: z.number().int().positive(),
+    mediaTypes: z.array(imageMediaTypeSchema),
+  }).optional(),
   attachedSessions: z.number().int().nonnegative(),
 }) satisfies z.ZodType<Wire<ResponseValue<'host.describe'>>>

packages/host/apiproxy/src/api/host.ts

@@ -4,6 +4,8 @@
  */
 
 import type { RpcRequest, RpcResponse } from './rpc.ts'
+import type { ImageAttachmentLimits } from '@deepseek-ai/dsh-attachment'
+import type { LlmModelInfo } from '@deepseek-ai/dsh-llm/types'
 
 /** Host-level unary methods. */
 export interface HostApi {
@@ -20,6 +22,10 @@ export interface HostApi {
     cwd: string
     provider?: string
     model?: string
+    /** Catalog entry for the active route; absent means its capabilities are unknown. */
+    activeModel?: LlmModelInfo
+    /** Resolved authoritative image-upload limits. */
+    imageLimits?: ImageAttachmentLimits
     attachedSessions: number
   }>>
 }

packages/host/apiproxy/src/api/index.ts

@@ -19,7 +19,7 @@ export interface ApiProxy {
 }
 
 // ---- Domain interfaces and payload entities ----
-export type { HistoryEntry, SessionsApi, SessionSummary } from './sessions.ts'
+export type { HistoryEntry, PromptContentPart, SessionsApi, SessionSummary } from './sessions.ts'
 export type { HostApi } from './host.ts'
 export type { EventsApi, MuxFrame, HostFrame, ToolCallView, ToolEventView, ToolResultView } from './events.ts'
 export type { ApprovalResponsePayload } from './approvals.ts'

packages/host/apiproxy/src/api/rpc-map.ts

@@ -14,6 +14,7 @@ export interface RpcMethodMap {
   'session.create': SessionsApi['create']
   'session.history': SessionsApi['history']
   'session.prompt': SessionsApi['prompt']
+  'session.attachment': SessionsApi['attachment']
   'session.cancel': SessionsApi['cancel']
   'host.describe': HostApi['describe']
 }

packages/host/apiproxy/src/api/rpc.schema.ts

@@ -35,6 +35,7 @@ export const rpcErrorSchema: z.ZodType<RpcError> = z.discriminatedUnion('code',
   z.object({ code: z.literal('bad-request'), message: z.string(), details: z.object({ issues: z.array(z.custom<ZodIssue>()) }) }),
   z.object({ code: z.literal('session-not-found'), message: z.string(), details: z.object({ sessionId: z.string() }) }),
   z.object({ code: z.literal('agent-busy'), message: z.string(), details: z.object({ reason: z.string() }) }),
+  z.object({ code: z.literal('attachment-error'), message: z.string(), details: z.object({ reason: z.string() }) }),
   z.object({ code: z.literal('internal'), message: z.string(), details: z.object({}) }),
 ]) as unknown as z.ZodType<RpcError>
 

packages/host/apiproxy/src/api/rpc.ts

@@ -32,6 +32,7 @@ export interface RpcErrorDetailsMap {
   'bad-request': { issues: ZodIssue[] }
   'session-not-found': { sessionId: SessionId }
   'agent-busy': { reason: string }
+  'attachment-error': { reason: string }
   'internal': {}
 }
 

packages/host/apiproxy/src/api/sessions.schema.ts

@@ -11,6 +11,7 @@ import type { RequestPayload, ResponseValue } from './rpc-map.ts'
 import type { Wire } from './rpc.schema.ts'
 import type { HistoryEntry, SessionSummary } from './sessions.ts'
 import type { ToolEventView } from './events.ts'
+import type { AttachmentIdType, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
 
 /** SessionId: one brand cast after shape validation (the only cast point in this domain). */
 export const sessionIdSchema = z.string().min(1) as unknown as z.ZodType<SessionId>
@@ -84,14 +85,25 @@ export const sessionHistoryValueSchema = z.object({
   hasMore: z.boolean(),
 }) satisfies z.ZodType<Wire<ResponseValue<'session.history'>>>
 
-/** ContentBlock passthrough: core is merge-extensible — the type discriminant envelope is strict, the rest stays wide. */
-export const contentBlockSchema = z.looseObject({ type: z.string() })
+/** Raster image media types accepted by the version-one browser wire. */
+export const imageMediaTypeSchema = z.union([
+  z.literal('image/png'),
+  z.literal('image/jpeg'),
+  z.literal('image/webp'),
+  z.literal('image/gif'),
+])
+
+/** Prompt wire content is intentionally narrower than merge-extensible durable core content. */
+export const promptContentPartSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('text'), text: z.string() }),
+  z.object({ type: z.literal('image'), mediaType: imageMediaTypeSchema, data: z.string(), name: z.string().optional() }),
+])
 
 /** session.prompt request payload. */
 export const sessionPromptRequestSchema = z.object({
   sessionId: sessionIdSchema,
   mode: z.union([z.literal('queue'), z.literal('steer')]),
-  content: z.array(contentBlockSchema),
+  content: z.array(promptContentPartSchema),
 }) as unknown as z.ZodType<RequestPayload<'session.prompt'>>
 
 /** session.prompt response value. */
@@ -99,6 +111,31 @@ export const sessionPromptValueSchema = z.object({
   accepted: z.literal(true),
 }) satisfies z.ZodType<Wire<ResponseValue<'session.prompt'>>>
 
+/** Opaque attachment id after string-shape validation. */
+export const attachmentIdSchema = z.string().min(1) as unknown as z.ZodType<AttachmentIdType>
+
+/** Durable image reference returned from the authenticated session lookup. */
+export const imageAttachmentRefSchema = z.object({
+  attachmentId: attachmentIdSchema,
+  mediaType: imageMediaTypeSchema,
+  bytes: z.number().int().positive(),
+  width: z.number().int().positive(),
+  height: z.number().int().positive(),
+  name: z.string().optional(),
+}) as unknown as z.ZodType<ImageAttachmentRef>
+
+/** session.attachment request payload. */
+export const sessionAttachmentRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+  attachmentId: attachmentIdSchema,
+}) satisfies z.ZodType<Wire<RequestPayload<'session.attachment'>>>
+
+/** session.attachment response value. */
+export const sessionAttachmentValueSchema = z.object({
+  attachment: imageAttachmentRefSchema,
+  data: z.string(),
+}) satisfies z.ZodType<Wire<ResponseValue<'session.attachment'>>>
+
 /** session.cancel request payload. */
 export const sessionCancelRequestSchema = z.object({
   sessionId: sessionIdSchema,

packages/host/apiproxy/src/api/sessions.ts

@@ -4,7 +4,7 @@
  * else references RequestPayload<'session.*'> / ResponseValue<'session.*'>.
  */
 
-import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { AttachmentIdType, ImageAttachmentRef, ImageMediaType } from '@deepseek-ai/dsh-attachment'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types'
 import type { RpcId, RpcRequest, RpcResponse } from './rpc.ts'
 import type { ToolEventView } from './events.ts'
@@ -44,6 +44,11 @@ export interface SessionSummary {
   cwd?: string
 }
 
+/** Browser-submitted prompt content; image bytes are promoted to durable references by the host. */
+export type PromptContentPart =
+  | { type: 'text'; text: string }
+  | { type: 'image'; mediaType: ImageMediaType; data: string; name?: string }
+
 /** Session-domain unary methods (the map keys session.* of RpcMethodMap). */
 export interface SessionsApi {
   /** Lists persisted sessions (updatedAt descending). v1 returns everything; cursor is a reserved seat, unimplemented. */
@@ -64,10 +69,14 @@ export interface SessionsApi {
   history(request: RpcRequest<{ sessionId: SessionId; beforeSeq?: number; maxMessages?: number }>):
   Promise<RpcResponse<{ events: HistoryEntry[]; hasMore: boolean }>>
 
-  /** Sends a message. content is core's ContentBlock[] verbatim; mode maps 1:1 — queue→send, steer→steer. */
-  prompt(request: RpcRequest<{ sessionId: SessionId; mode: 'queue' | 'steer'; content: ContentBlock[] }>):
+  /** Sends text plus temporary base64 image uploads; the host persists images before calling the agent. */
+  prompt(request: RpcRequest<{ sessionId: SessionId; mode: 'queue' | 'steer'; content: PromptContentPart[] }>):
   Promise<RpcResponse<{ accepted: true }>>
 
+  /** Reads one durable image after proving that this session's log references its id. */
+  attachment(request: RpcRequest<{ sessionId: SessionId; attachmentId: AttachmentIdType }> ):
+  Promise<RpcResponse<{ attachment: ImageAttachmentRef; data: string }>>
+
   /** Stops: clears both FIFOs + aborts the current step (1:1 with agent.cancel). */
   cancel(request: RpcRequest<{ sessionId: SessionId }>): Promise<RpcResponse<{ accepted: true }>>
 }

packages/host/apiproxy/src/fetch/client.ts

@@ -16,6 +16,7 @@ import { hostFrameSchema, muxFrameSchema } from '../api/events.schema.ts'
 import { hostDescribeValueSchema } from '../api/host.schema.ts'
 import {
   sessionCancelValueSchema,
+  sessionAttachmentValueSchema,
   sessionCreateValueSchema,
   sessionHistoryValueSchema,
   sessionListValueSchema,
@@ -43,6 +44,7 @@ export interface IApiClient {
     create(payload: RequestPayload<'session.create'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.create'>>>
     history(payload: RequestPayload<'session.history'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.history'>>>
     prompt(payload: RequestPayload<'session.prompt'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.prompt'>>>
+    attachment(payload: RequestPayload<'session.attachment'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.attachment'>>>
     cancel(payload: RequestPayload<'session.cancel'>, signal?: AbortSignal): Promise<RpcResponse<ResponseValue<'session.cancel'>>>
   }
   host: {
@@ -65,6 +67,7 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType<Wire<ResponseV
   'session.create': sessionCreateValueSchema,
   'session.history': sessionHistoryValueSchema,
   'session.prompt': sessionPromptValueSchema,
+  'session.attachment': sessionAttachmentValueSchema,
   'session.cancel': sessionCancelValueSchema,
   'host.describe': hostDescribeValueSchema,
 }
@@ -246,6 +249,7 @@ export abstract class AbstractApiClient implements IApiClient {
     create: (payload, signal) => this.callUnary('session.create', payload, signal),
     history: (payload, signal) => this.callUnary('session.history', payload, signal),
     prompt: (payload, signal) => this.callUnary('session.prompt', payload, signal),
+    attachment: (payload, signal) => this.callUnary('session.attachment', payload, signal),
     cancel: (payload, signal) => this.callUnary('session.cancel', payload, signal),
   }
 

packages/host/apiproxy/src/fetch/handler.ts

@@ -16,6 +16,7 @@ import type { Wire } from '../api/rpc.schema.ts'
 import { clientRequestSchema, clientResponseSchema } from '../api/rpc.schema.ts'
 import {
   sessionCancelRequestSchema,
+  sessionAttachmentRequestSchema,
   sessionCreateRequestSchema,
   sessionHistoryRequestSchema,
   sessionListRequestSchema,
@@ -42,6 +43,7 @@ const UNARY_ROUTES: UnaryRoutes = {
   'session.create': { schema: sessionCreateRequestSchema, invoke: (api, r) => api.sessions.create(r) },
   'session.history': { schema: sessionHistoryRequestSchema, invoke: (api, r) => api.sessions.history(r) },
   'session.prompt': { schema: sessionPromptRequestSchema, invoke: (api, r) => api.sessions.prompt(r) },
+  'session.attachment': { schema: sessionAttachmentRequestSchema, invoke: (api, r) => api.sessions.attachment(r) },
   'session.cancel': { schema: sessionCancelRequestSchema, invoke: (api, r) => api.sessions.cancel(r) },
   'host.describe': { schema: hostDescribeRequestSchema, invoke: (api, r) => api.host.describe(r) },
 }

packages/host/apiproxy/tests/client-handler.spec.ts

@@ -30,6 +30,10 @@ function scriptedApi(overrides: {
       create: r => ok(r, { sessionId: sid('s-new') }),
       history: r => ok(r, { events: [], hasMore: false }),
       prompt: r => ok(r, { accepted: true as const }),
+      attachment: r => ok(r, {
+        attachment: { attachmentId: 'a' as never, mediaType: 'image/png', bytes: 1, width: 1, height: 1 },
+        data: 'AA==',
+      }),
       cancel: r => ok(r, { accepted: true as const }),
       ...overrides.sessions,
     },

packages/host/apiproxy/tests/fetch-carrier.spec.ts

@@ -33,6 +33,12 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
       async prompt(request) {
         return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
       },
+      async attachment(request) {
+        return {
+          rpcId: request.rpcId,
+          result: { ok: true, value: { attachment: { attachmentId: 'a' as never, mediaType: 'image/png' as const, bytes: 1, width: 1, height: 1 }, data: 'AA==' } },
+        }
+      },
       async cancel(request) {
         return { rpcId: request.rpcId, result: { ok: true, value: { accepted: true as const } } }
       },

packages/host/apiproxy/tests/rpc-schemas.spec.ts

@@ -6,7 +6,8 @@ import {
 } from '../src/api/rpc.schema.ts'
 import { z } from 'zod'
 import {
-  contentBlockSchema, sessionCancelRequestSchema, sessionCancelValueSchema, sessionCreateRequestSchema,
+  promptContentPartSchema, sessionAttachmentRequestSchema, sessionAttachmentValueSchema,
+  sessionCancelRequestSchema, sessionCancelValueSchema, sessionCreateRequestSchema,
   sessionCreateValueSchema, sessionEventSchema, sessionHistoryRequestSchema, sessionHistoryValueSchema,
   sessionIdSchema, sessionListRequestSchema, sessionListValueSchema, sessionPromptRequestSchema,
   sessionPromptValueSchema, sessionSummarySchema,
@@ -31,6 +32,7 @@ describe('rpcErrorSchema', () => {
     expect(rpcErrorSchema.parse({ code: 'bad-request', message: 'm', details: { issues: [] } }).code).toBe('bad-request')
     expect(rpcErrorSchema.parse({ code: 'session-not-found', message: 'm', details: { sessionId: 's' } }).code).toBe('session-not-found')
     expect(rpcErrorSchema.parse({ code: 'agent-busy', message: 'm', details: { reason: 'r' } }).code).toBe('agent-busy')
+    expect(rpcErrorSchema.parse({ code: 'attachment-error', message: 'm', details: { reason: 'r' } }).code).toBe('attachment-error')
     expect(rpcErrorSchema.parse({ code: 'internal', message: 'm', details: {} }).code).toBe('internal')
   })
 
@@ -105,7 +107,20 @@ describe('sessions domain schemas', () => {
     expect(sessionPromptValueSchema.parse({ accepted: true }).accepted).toBe(true)
     expect(sessionCancelRequestSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
     expect(sessionCancelValueSchema.parse({ accepted: true }).accepted).toBe(true)
-    expect(contentBlockSchema.parse({ type: 'text', text: 'x', extra: 1 })).toMatchObject({ extra: 1 })
+    expect(promptContentPartSchema.parse({ type: 'text', text: 'x', extra: 1 })).toEqual({ type: 'text', text: 'x' })
+    expect(promptContentPartSchema.parse({
+      type: 'image', mediaType: 'image/png', data: 'AA==', name: 'pixel.png',
+    })).toMatchObject({ type: 'image', mediaType: 'image/png', name: 'pixel.png' })
+    const attachment = {
+      attachmentId: `sha256:${'a'.repeat(64)}`,
+      mediaType: 'image/png' as const,
+      bytes: 1,
+      width: 1,
+      height: 1,
+    }
+    expect(sessionAttachmentRequestSchema.parse({ sessionId: 's1', attachmentId: attachment.attachmentId }))
+      .toMatchObject({ sessionId: 's1' })
+    expect(sessionAttachmentValueSchema.parse({ attachment, data: 'AA==' }).attachment).toEqual(attachment)
   })
 })
 

packages/host/apiproxy/tsconfig.json

@@ -11,6 +11,9 @@
     {
       "path": "../../util/brand"
     },
+    {
+      "path": "../../attachment/attachment"
+    },
     {
       "path": "../../llm/llm"
     },

packages/host/runtime/package.json

@@ -31,6 +31,7 @@
     "@cordisjs/plugin-timer": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-attachment-local": "workspace:^",
     "@deepseek-ai/dsh-bash-local": "workspace:^",
     "@deepseek-ai/dsh-client-connection": "workspace:^",
     "@deepseek-ai/dsh-client-i18n": "workspace:^",
@@ -46,6 +47,7 @@
     "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-llm-deepseek": "workspace:^",
+    "@deepseek-ai/dsh-llm-pi-ai": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-persistence": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",

packages/host/runtime/src/api-proxy.ts

@@ -9,10 +9,12 @@ import { randomUUID } from 'node:crypto'
 import { stat } from 'node:fs/promises'
 import type { Context } from 'cordis'
 import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
+import { AttachmentError } from '@deepseek-ai/dsh-attachment-local'
+import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment-local'
 import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
 import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
-import type { ApiProxy, HistoryEntry, HostFrame, MuxFrame, SessionSummary, ToolEventView } from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { ApiProxy, HistoryEntry, HostFrame, MuxFrame, PromptContentPart, SessionSummary, ToolEventView } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { ClientResponse, RpcError, RpcReceipt, RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
 import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
 
@@ -22,6 +24,69 @@ const DEFAULT_MAX_MESSAGES = 50
 /** Surface message event types (the pagination counting unit). */
 const MESSAGE_TYPES = new Set(['user/message', 'assistant/message', 'steering/message'])
 
+function decodeBase64(data: string): Uint8Array {
+  if (data.length === 0 || data.length % 4 !== 0 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(data)) {
+    throw new AttachmentError('Image upload is not canonical base64.', 'INVALID_IMAGE_BASE64')
+  }
+  const decoded = Buffer.from(data, 'base64')
+  if (decoded.toString('base64') !== data) throw new AttachmentError('Image upload is not canonical base64.', 'INVALID_IMAGE_BASE64')
+  return new Uint8Array(decoded)
+}
+
+async function durablePromptContent(ctx: Context, content: readonly PromptContentPart[]): Promise<ContentBlock[]> {
+  const limits = ctx.attachments.imageLimits
+  const prepared = content.map(part => part.type === 'text'
+    ? part
+    : { part, data: decodeBase64(part.data) })
+  const images = prepared.filter((part): part is Extract<typeof part, { data: Uint8Array }> => 'data' in part)
+  if (images.length > limits.maxImagesPerMessage) {
+    throw new AttachmentError('Prompt exceeds the configured image-count limit.', 'TOO_MANY_IMAGES')
+  }
+  const totalBytes = images.reduce((sum, image) => sum + image.data.byteLength, 0)
+  if (totalBytes > limits.maxMessageImageBytes) {
+    throw new AttachmentError('Prompt exceeds the configured aggregate image-byte limit.', 'IMAGES_TOO_LARGE')
+  }
+  return Promise.all(prepared.map(async (item): Promise<ContentBlock> => {
+    if (!('data' in item)) return { type: 'text', text: item.text }
+    const attachment = await ctx.attachments.saveImage({
+      data: item.data,
+      mediaType: item.part.mediaType,
+      ...item.part.name === undefined ? {} : { name: item.part.name },
+    })
+    return { type: 'image', attachment }
+  }))
+}
+
+function imageInContent(content: unknown, attachmentId: string): ImageAttachmentRef | undefined {
+  if (!Array.isArray(content)) return undefined
+  for (const value of content) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) continue
+    const block = value as { type?: unknown; attachment?: unknown; content?: unknown }
+    if (block.type === 'image' && typeof block.attachment === 'object' && block.attachment !== null) {
+      const ref = block.attachment as ImageAttachmentRef
+      if (String(ref.attachmentId) === attachmentId) return ref
+    }
+    if (block.type === 'tool-result') {
+      const nested = imageInContent(block.content, attachmentId)
+      if (nested !== undefined) return nested
+    }
+  }
+  return undefined
+}
+
+function referencedImage(events: readonly SessionEvent[], attachmentId: string): ImageAttachmentRef | undefined {
+  for (const event of events) {
+    const data = event.data as { content?: unknown; chunk?: { type?: unknown; block?: unknown } }
+    const direct = imageInContent(data.content, attachmentId)
+    if (direct !== undefined) return direct
+    if (event.type === 'assistant/chunk' && data.chunk?.type === 'block-end') {
+      const streamed = imageInContent([data.chunk.block], attachmentId)
+      if (streamed !== undefined) return streamed
+    }
+  }
+  return undefined
+}
+
 /**
  * Message-boundary pagination: count maxMessages surface messages backwards from
  * the window tail; the cut is the starting seq of the oldest message group
@@ -321,15 +386,52 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         // The rpcId rides MessageSource into user/message (merge declaration in api/sessions.ts; provisional correlation).
         const source: MessageSource = { kind: 'user', rpcId: request.rpcId }
         try {
-          if (mode === 'steer') agent.steer(content, { source })
-          else agent.send(content, { source })
+          if (content.some(part => part.type === 'image')) {
+            const activeModel = (await ctx.llm.listModels(defaults.provider)).find(model => model.id === defaults.model)
+            if (activeModel?.inputModalities !== undefined && !activeModel.inputModalities.includes('image')) {
+              return err(request, {
+                code: 'attachment-error',
+                message: `Model "${defaults.model}" does not support image input.`,
+                details: { reason: 'MODEL_DOES_NOT_SUPPORT_IMAGES' },
+              })
+            }
+          }
+          const durable = await durablePromptContent(ctx, content)
+          if (mode === 'steer') agent.steer(durable, { source })
+          else agent.send(durable, { source })
         } catch (error: unknown) {
+          if (error instanceof AttachmentError) {
+            return err(request, { code: 'attachment-error', message: error.message, details: { reason: error.code } })
+          }
           // A synchronous throw from send/steer means disposed or invalid input; surface as agent-busy with the reason attached.
           return err(request, { code: 'agent-busy', message: 'prompt rejected', details: { reason: String(error) } })
         }
         return ok(request, { accepted: true as const })
       },
 
+      async attachment(request) {
+        const { sessionId, attachmentId } = request.payload
+        const found = await agentFor(sessionId)
+        if ('error' in found) return err(request, found.error)
+        const ref = referencedImage(found.agent.session.events, String(attachmentId))
+        if (ref === undefined) {
+          return err(request, {
+            code: 'attachment-error',
+            message: 'Image is not referenced by this session.',
+            details: { reason: 'ATTACHMENT_NOT_REFERENCED' },
+          })
+        }
+        try {
+          const stored = await ctx.attachments.readImage(ref)
+          return ok(request, { attachment: stored.ref, data: Buffer.from(stored.data).toString('base64') })
+        } catch (error: unknown) {
+          if (error instanceof AttachmentError) {
+            return err(request, { code: 'attachment-error', message: error.message, details: { reason: error.code } })
+          }
+          return err(request, { code: 'internal', message: 'Unable to read image attachment.', details: {} })
+        }
+      },
+
       cancel(request) {
         const { sessionId } = request.payload
         const agent = ctx.agents.get(sessionId)
@@ -346,15 +448,21 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     },
 
     host: {
-      describe(request) {
+      async describe(request) {
+        const activeModel = (await ctx.llm.listModels(defaults.provider)).find(model => model.id === defaults.model)
         // TODO(step2): version should read apps/cli's package.json; placeholder for now.
-        return Promise.resolve(ok(request, {
+        return ok(request, {
           version: '0.0.1',
           cwd: process.cwd(),
           provider: defaults.provider,
           model: defaults.model,
+          ...activeModel === undefined ? {} : { activeModel },
+          imageLimits: {
+            ...ctx.attachments.imageLimits,
+            mediaTypes: [...ctx.attachments.imageLimits.mediaTypes],
+          },
           attachedSessions: ctx.agents.list().length,
-        }))
+        })
       },
     },
 

packages/host/runtime/src/boot.ts

@@ -7,6 +7,7 @@
 import { Context } from 'cordis'
 import Timer from '@cordisjs/plugin-timer'
 import LlmService from '@deepseek-ai/dsh-llm'
+import LocalAttachmentStore from '@deepseek-ai/dsh-attachment-local'
 import SessionStore from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
@@ -14,6 +15,8 @@ import AgentRegistry from '@deepseek-ai/dsh-agent'
 import TaskService from '@deepseek-ai/dsh-tasks'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
+import * as LlmPiAi from '@deepseek-ai/dsh-llm-pi-ai'
+import type { PiAiProviderProfile } from '@deepseek-ai/dsh-llm-pi-ai'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import LocalBashExecutor from '@deepseek-ai/dsh-bash-local'
 import * as toolBash from '@deepseek-ai/dsh-tool-bash'
@@ -42,10 +45,14 @@ import * as spillPolicy from '@deepseek-ai/dsh-spill-policy'
 export interface BootHostOptions {
   /** Root directory for JSONL session persistence. */
   persistenceRoot: string
+  /** Explicit harness home for durable attachments; omitted follows DSH_HOME then ~/.dsh. */
+  dshHome?: string
   /** Default provider route for created/resumed agents (defaults to 'deepseek', the only adapter bootHost registers). */
   provider?: string
   /** Default model id (defaults to 'deepseek-v4-flash', matching the demos). */
   model?: string
+  /** Additional pi-ai provider routes available to visual-capable Web sessions. */
+  piAiProviders?: PiAiProviderProfile[]
   /**
    * Default project directory for sessions created without an explicit cwd
    * (defaults to the host process working directory). A session's cwd is its
@@ -88,6 +95,9 @@ export async function bootHost(options: BootHostOptions): Promise<HostHandle> {
   const ctx = new Context()
   await ctx.plugin(Timer)
   await ctx.plugin(LlmService)
+  await ctx.plugin(LocalAttachmentStore, {
+    ...options.dshHome === undefined ? {} : { dshHome: options.dshHome },
+  })
   await ctx.plugin(SessionStore)
   await ctx.plugin(SystemPrompt, { persona: '' })
   await ctx.plugin(ToolRegistry)
@@ -95,6 +105,9 @@ export async function bootHost(options: BootHostOptions): Promise<HostHandle> {
   await ctx.plugin(TaskService)
   await ctx.plugin(AgentLoop, { agents: [] })
   await ctx.plugin(LlmDeepSeek, {})
+  if (options.piAiProviders !== undefined && options.piAiProviders.length > 0) {
+    await ctx.plugin(LlmPiAi, { providers: options.piAiProviders })
+  }
   await ctx.plugin(SessionPersistenceJsonl, { root: options.persistenceRoot, compression: 'none' })
   await ctx.plugin(LocalBashExecutor, {})
   // Tool suite mirroring the demo:repl composition (repl-agent/cordis.yml +

packages/host/runtime/tests/host-runtime.spec.ts

@@ -1,11 +1,11 @@
-import { mkdtempSync } from 'node:fs'
+import { existsSync, mkdtempSync, readFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { Context } from 'cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { agentEvents } from '@deepseek-ai/dsh-agent'
-import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, GenerateOptions, LlmModelInfo, ModelModality, StreamChunk } from '@deepseek-ai/dsh-llm'
 import { LlmAdapter } from '@deepseek-ai/dsh-llm'
 import type { SessionId } from '@deepseek-ai/dsh-session'
 import type { HostFrame, MuxFrame } from '@deepseek-ai/dsh-host-apiproxy/api'
@@ -15,10 +15,20 @@ import { bootHost, startHost, type HostHandle, type RunningHost } from '../src/i
 
 /** Scripted adapter: each model call consumes the next chunk list; 'hang' streams then waits for abort. */
 class ScriptedAdapter extends LlmAdapter {
-  constructor(private script: (StreamChunk[] | 'hang')[]) {
+  constructor(
+    private script: (StreamChunk[] | 'hang')[],
+    private readonly inputModalities: readonly ModelModality[] = ['text', 'image'],
+  ) {
     super()
   }
 
+  override listModels(provider: string): Promise<readonly LlmModelInfo[]> {
+    return Promise.resolve([{
+      provider, id: 'test-model', name: 'test-model',
+      inputModalities: this.inputModalities, outputModalities: ['text'],
+    }])
+  }
+
   async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
     const entry = this.script.shift()
     if (!entry) throw new Error('ScriptedAdapter: script exhausted')
@@ -48,6 +58,8 @@ function request<P>(payload: P): RpcRequest<P> {
 }
 let nextRpc = 1
 
+const PNG_BASE64 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII='
+
 function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
     const dispose = ctx.on('agent/status', (subject: Agent, status: string) => {
@@ -171,14 +183,83 @@ describe('sessions.prompt / cancel', () => {
   })
 
   it('maps a synchronous send throw to agent-busy', async () => {
-    const { api } = await boot()
+    const { api, ctx } = await boot()
     const { sessionId } = expectOk(await api.sessions.create(request({})))
-    const poisoned = [{ type: 'text', text: 'x', bad: () => 1 }] as never
-    const response = await api.sessions.prompt(request({ sessionId, mode: 'queue' as const, content: poisoned }))
+    vi.spyOn(ctx.agents.get(sessionId) as Agent, 'send').mockImplementation(() => {
+      throw new Error('disposed during prompt')
+    })
+    const response = await api.sessions.prompt(request({
+      sessionId, mode: 'queue' as const, content: [{ type: 'text' as const, text: 'x' }],
+    }))
     expect(response.result.ok).toBe(false)
     if (!response.result.ok) expect(response.result.error.code).toBe('agent-busy')
   })
 
+  it('persists uploaded bytes before the user event and serves them only through the owning session', async () => {
+    const persistenceRoot = mkdtempSync(join(tmpdir(), 'dsh-image-session-'))
+    const dshHome = mkdtempSync(join(tmpdir(), 'dsh-image-home-'))
+    host = await startHost({
+      boot: { persistenceRoot, dshHome, provider: 'scripted', model: 'test-model' },
+    })
+    host.ctx.llm.registerAdapter(['scripted'], new ScriptedAdapter([textResponse('seen')]))
+    const { sessionId } = expectOk(await host.api.sessions.create(request({})))
+    const agent = host.ctx.agents.get(sessionId) as Agent
+    const idle = waitForIdle(host.ctx, agent)
+    const response = await host.api.sessions.prompt(request({
+      sessionId,
+      mode: 'queue' as const,
+      content: [
+        { type: 'text' as const, text: 'describe' },
+        { type: 'image' as const, mediaType: 'image/png' as const, data: PNG_BASE64, name: '/tmp/pixel.png' },
+      ],
+    }))
+    expectOk(response)
+    await idle
+
+    const user = agent.session.events.find(event => event.type === 'user/message')
+    const content = (user?.data as { content?: ContentBlock[] } | undefined)?.content ?? []
+    const image = content.find(block => block.type === 'image')
+    expect(image?.type).toBe('image')
+    if (image?.type !== 'image') throw new Error('image block missing')
+    expect(JSON.stringify(user)).not.toContain(PNG_BASE64)
+    expect(image.attachment.name).toBe('pixel.png')
+    const sha256 = String(image.attachment.attachmentId).slice('sha256:'.length)
+    const object = join(dshHome, 'attachments', 'v1', 'objects', sha256.slice(0, 2), sha256)
+    expect(existsSync(object)).toBe(true)
+    expect(readFileSync(object).toString('base64')).toBe(PNG_BASE64)
+
+    const loaded = expectOk(await host.api.sessions.attachment(request({
+      sessionId, attachmentId: image.attachment.attachmentId,
+    })))
+    expect(loaded).toEqual({ attachment: image.attachment, data: PNG_BASE64 })
+    const { sessionId: other } = expectOk(await host.api.sessions.create(request({})))
+    const denied = await host.api.sessions.attachment(request({
+      sessionId: other, attachmentId: image.attachment.attachmentId,
+    }))
+    expect(denied.result).toMatchObject({
+      ok: false, error: { code: 'attachment-error', details: { reason: 'ATTACHMENT_NOT_REFERENCED' } },
+    })
+  })
+
+  it('rejects images for an explicitly text-only model without creating a session event', async () => {
+    const persistenceRoot = mkdtempSync(join(tmpdir(), 'dsh-text-session-'))
+    const dshHome = mkdtempSync(join(tmpdir(), 'dsh-text-home-'))
+    host = await startHost({
+      boot: { persistenceRoot, dshHome, provider: 'scripted', model: 'test-model' },
+    })
+    host.ctx.llm.registerAdapter(['scripted'], new ScriptedAdapter([], ['text']))
+    const { sessionId } = expectOk(await host.api.sessions.create(request({})))
+    const response = await host.api.sessions.prompt(request({
+      sessionId, mode: 'queue' as const,
+      content: [{ type: 'image' as const, mediaType: 'image/png' as const, data: PNG_BASE64 }],
+    }))
+    expect(response.result).toMatchObject({
+      ok: false, error: { code: 'attachment-error', details: { reason: 'MODEL_DOES_NOT_SUPPORT_IMAGES' } },
+    })
+    expect(host.ctx.agents.get(sessionId)?.session.events.some(event => event.type === 'user/message')).toBe(false)
+    expect(existsSync(join(dshHome, 'attachments'))).toBe(false)
+  })
+
   it('cancels an attached agent and rejects an unattached one', async () => {
     const running = await boot(['hang'])
     const { api, ctx } = running

packages/host/runtime/tsconfig.json

@@ -17,9 +17,15 @@
     {
       "path": "../../llm/llm"
     },
+    {
+      "path": "../../attachment/attachment-local"
+    },
     {
       "path": "../../llm/llm-deepseek"
     },
+    {
+      "path": "../../llm/llm-pi-ai"
+    },
     {
       "path": "../../core/session"
     },