dsh-edit-turn 0.2.18 → 0.2.19

package/lib/index.js

@@ -19,6 +19,17 @@
 //      pair can be left dangling.
 //
 //
+// A revised PROMPT carries the message itself: the carrier's content is the
+// user's block list after the edit, rebuilt block by block. A block the user
+// did not touch is copied out of the original message verbatim - same object,
+// same fields, same attachment reference - a block the user added is admitted
+// through the platform's attachment store (`ctx.get('attachments')`, the seam
+// dsh-acp uses) and a block the user removed is simply not written. The revised
+// text lands where the original's first text block was, so the layout survives
+// the edit. Nothing in that path names a block shape: the only test in the
+// module is "does this block carry text", which is the editor's own field, so a
+// block type the platform adds later needs no change here.
+//
 // The silent replacement carrier is an EMPTY `developer/message` (0.2.12;
 // before that an empty `system/message`, which no reader accepts - see the
 // README). Empty content projects to no model message, so the rollback adds
@@ -37,6 +48,7 @@
 // degrades to "no config form, defaults apply" instead, which costs a settings
 // surface rather than the feature. Every field is optional in `apply` anyway.
 import { randomUUID } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 
@@ -57,7 +69,7 @@ export const PLUGIN_ID = 'dsh-edit-turn'
 export const name = PLUGIN_ID
 
 /** Keep in sync with package.json and lib/client.js. */
-export const PLUGIN_VERSION = '0.2.18'
+export const PLUGIN_VERSION = '0.2.19'
 
 // A ring of the last few requests, answering "did the browser half even ask, and
 // what did it get?" without needing its console. Read-only diagnostics: the
@@ -81,6 +93,30 @@ const SESSION_ID_RE = /^(session-)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{
 const MAX_TEXT = 200_000
 const FLUSH_DEADLINE_MS = 5_000
 
+// A revised block list travels as base64 inside the JSON body, so the body limit
+// IS the upload limit. The platform's own per-image ceiling defaults to 20 MiB
+// (dsh-attachment-local), which base64 carries in ~27 MiB of text; the store
+// enforces its own limit independently, this one only bounds the socket read.
+const MAX_BODY_BYTES = 64 * 1024 * 1024
+const MAX_UPLOAD_BYTES = 20 * 1024 * 1024
+// A preview is a courtesy: above this the chip keeps its label and asks for
+// nothing. Never worth streaming a whole file to draw a thumbnail.
+const MAX_PREVIEW_BYTES = 32 * 1024 * 1024
+// One message cannot carry more blocks than this. The cap exists so a malformed
+// or hostile body cannot make the host loop over an unbounded list.
+const MAX_PARTS = 64
+
+/**
+ * Service names the durable attachment store is reachable under.
+ *
+ * `attachments` is the platform's own registration (the `AttachmentStore`
+ * base class in @deepseek-ai/dsh-attachment, and every `ctx.get('attachments')`
+ * consumer such as dsh-acp); the other two are the package names, accepted so a
+ * rename cannot silently cost the feature. Absence is a supported state, never
+ * an error: the edit degrades to the text-only rewrite it was before blocks.
+ */
+const ATTACHMENT_SERVICES = ['attachments', 'attachment', 'attachment-local']
+
 /**
  * Model-visible text of the replacement carrier.
  *
@@ -295,30 +331,287 @@ export function isAssistantReply(event) {
   return Boolean(event) && event.type === 'assistant/message'
 }
 
+/**
+ * Whether one content block carries the editable text.
+ *
+ * This is the module's ONLY block-shape test, and it is deliberately about the
+ * field the editor owns rather than about a block class. Every other block - a
+ * picture, a file, and whatever type a later platform adds - is carried through
+ * an edit untouched unless the user removed it, so no code below ever has to
+ * learn a new name.
+ *
+ * @param block - one content block.
+ * @returns true when the block holds text the editor prefills.
+ */
+export function isTextBlock(block) {
+  return Boolean(block) && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string'
+}
+
+/**
+ * The content blocks of a message payload, in message order.
+ *
+ * `user/message` carries its message fields on `data`; the other three surface
+ * types nest them under `data.message`, so both shapes read the same way now
+ * that the model's replies are editable too.
+ *
+ * @param event - raw session event.
+ * @returns the block array, or an empty one when the message carries none.
+ */
+export function readMessageBlocks(event) {
+  const data = (event && event.data) || {}
+  const message = data.message && typeof data.message === 'object' ? data.message : data
+  return Array.isArray(message.content) ? message.content : []
+}
+
 /**
  * Read the plain text of a message payload, plus how many non-text parts it
- * carries. Editing is text-only, so a caller must be told when a rewrite would
- * drop attachments.
+ * carries. The count is what tells a reader that a text-only carrier would drop
+ * something, and it stays exactly what it always was.
  * @param event - raw session event.
  * @returns `{ text, attachments }`.
  */
 export function readMessageText(event) {
-  const data = (event && event.data) || {}
-  // `user/message` carries its message fields on `data`; the other three surface
-  // types nest them under `data.message`. Both shapes have to read the same way
-  // now that the model's replies are editable too.
-  const message = data.message && typeof data.message === 'object' ? data.message : data
-  const blocks = Array.isArray(message.content) ? message.content : []
   let text = ''
   let attachments = 0
-  for (const block of blocks) {
+  for (const block of readMessageBlocks(event)) {
     if (!block || typeof block !== 'object') continue
-    if (block.type === 'text' && typeof block.text === 'string') text += (text === '' ? '' : '\n') + block.text
+    if (isTextBlock(block)) text += (text === '' ? '' : '\n') + block.text
     else attachments += 1
   }
   return { text, attachments }
 }
 
+/**
+ * The non-text blocks of a message, described for the editor's chips.
+ *
+ * Read by FIELD PRESENCE, never by type. A block that carries a durable
+ * `attachment` reference is described from that reference (name, media type,
+ * byte length, pixel size) whatever the platform calls the block; a block
+ * without one is described by its own type name alone, which is what a chip can
+ * honestly show. This list is for DRAWING and for offering a delete - it never
+ * decides what an edit writes, and a block the user keeps is copied verbatim
+ * whether or not this function could describe it.
+ *
+ * @param blocks - the message content, in message order.
+ * @param preview - whether the deployment can hand these bytes back for a thumbnail.
+ * @returns one entry per non-text block, in message order.
+ */
+export function blockSummaries(blocks, preview = false) {
+  const out = []
+  for (let index = 0; index < blocks.length; index += 1) {
+    const block = blocks[index]
+    if (!block || typeof block !== 'object' || isTextBlock(block)) continue
+    const raw = block.attachment
+    const attachment = raw && typeof raw === 'object' ? raw : null
+    const summary = {
+      index,
+      type: typeof block.type === 'string' && block.type !== '' ? block.type : 'block',
+      preview: false,
+    }
+    if (attachment !== null) {
+      if (typeof attachment.name === 'string' && attachment.name !== '') summary.name = attachment.name
+      if (typeof attachment.mediaType === 'string' && attachment.mediaType !== '') summary.mediaType = attachment.mediaType
+      if (typeof attachment.bytes === 'number') summary.bytes = attachment.bytes
+      if (typeof attachment.width === 'number') summary.width = attachment.width
+      if (typeof attachment.height === 'number') summary.height = attachment.height
+      summary.preview = preview && typeof attachment.attachmentId === 'string' && attachment.attachmentId !== ''
+    }
+    out.push(summary)
+  }
+  return out
+}
+
+/**
+ * Whether two JSON values are the same value.
+ *
+ * Used to answer "did this edit change anything at all": the rebuilt block list
+ * is compared against the original one, field by field. Key ORDER is not part
+ * of a JSON value - a session reader is free to hand the same object back with
+ * its keys in another order - so this walks the keys instead of comparing
+ * stringified text.
+ *
+ * @param a - first JSON value.
+ * @param b - second JSON value.
+ * @returns true when the two are indistinguishable JSON.
+ */
+export function sameJson(a, b) {
+  if (a === b) return true
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false
+    for (let index = 0; index < a.length; index += 1) {
+      if (!sameJson(a[index], b[index])) return false
+    }
+    return true
+  }
+  if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') return false
+  const keys = Object.keys(a)
+  if (keys.length !== Object.keys(b).length) return false
+  for (const key of keys) {
+    if (!Object.prototype.hasOwnProperty.call(b, key)) return false
+    if (!sameJson(a[key], b[key])) return false
+  }
+  return true
+}
+
+/**
+ * Normalise one submitted block list.
+ *
+ * The wire vocabulary is exactly two entries:
+ *
+ *   `{ keep: <index> }` - the original block at that index, untouched;
+ *   `{ add: { data, mediaType?, name? } }` - bytes the user just picked.
+ *
+ * Text is never listed: the revised text rides in its own field and the host
+ * puts it back where the original's first text block was. A `keep` that names
+ * a text block is therefore not an error - it is the text, and the text is
+ * already accounted for.
+ *
+ * @param raw - the submitted `parts` array.
+ * @param blockCount - how many blocks the original message carries.
+ * @returns `[{ keep } | { add }]` in submitted order.
+ * @throws {HttpError} 400 `invalid` for anything this vocabulary does not name.
+ */
+export function normalizeParts(raw, blockCount) {
+  if (!Array.isArray(raw)) throw new HttpError(400, 'invalid', 'parts must be an array')
+  if (raw.length > MAX_PARTS) throw new HttpError(400, 'invalid', `a message cannot carry more than ${MAX_PARTS} blocks`)
+  const parts = []
+  for (const entry of raw) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw new HttpError(400, 'invalid', 'every part must be an object')
+    }
+    if (entry.keep !== undefined) {
+      const index = entry.keep
+      if (!Number.isInteger(index) || index < 0 || index >= blockCount) {
+        throw new HttpError(400, 'invalid', 'a kept block index is out of range')
+      }
+      if (parts.some((part) => part.keep === index)) throw new HttpError(400, 'invalid', 'a block was kept twice')
+      parts.push({ keep: index })
+      continue
+    }
+    const upload = entry.add
+    if (upload && typeof upload === 'object' && typeof upload.data === 'string') {
+      parts.push({
+        add: {
+          data: upload.data,
+          ...(typeof upload.mediaType === 'string' && upload.mediaType !== '' ? { mediaType: upload.mediaType } : {}),
+          ...(typeof upload.name === 'string' && upload.name !== '' ? { name: upload.name } : {}),
+        },
+      })
+      continue
+    }
+    throw new HttpError(400, 'invalid', 'every part is either a kept block or an upload')
+  }
+  return parts
+}
+
+/**
+ * The ordered slots a submitted block list describes, plus where the text goes.
+ *
+ * Layout is the original message's, never a re-invention: the revised text is
+ * placed where the original's FIRST text block stood (the editor holds every
+ * text block at once, so the others merge into it), and the kept blocks keep
+ * their relative order around it. A message with no text block at all - a
+ * picture-only prompt - gets its text appended, which is the only position that
+ * does not move something the user did not touch.
+ *
+ * @param originalBlocks - the message content before the edit.
+ * @param parts - normalised parts (see {@link normalizeParts}).
+ * @returns `{ slots, textAt, added }`; `textAt` indexes `slots`.
+ */
+export function planBlockLayout(originalBlocks, parts) {
+  const slots = []
+  let added = 0
+  for (const part of parts) {
+    if (part.keep !== undefined) {
+      // The text blocks are the editor's own content, carried by `text`.
+      if (isTextBlock(originalBlocks[part.keep])) continue
+      slots.push({ kind: 'original', index: part.keep })
+      continue
+    }
+    slots.push({ kind: 'add', upload: part.add })
+    added += 1
+  }
+  let firstText = -1
+  for (let index = 0; index < originalBlocks.length; index += 1) {
+    if (isTextBlock(originalBlocks[index])) {
+      firstText = index
+      break
+    }
+  }
+  let textAt = slots.length
+  if (firstText >= 0) {
+    // The text stands before the first kept block that came after it in the
+    // original message. When no kept block did - everything after it was
+    // removed, or it was the last block of all - it keeps its own place at the
+    // head of what is left, ahead of the blocks that used to stand before it.
+    let anchored = false
+    for (let index = 0; index < slots.length; index += 1) {
+      const slot = slots[index]
+      if (slot.kind === 'original' && slot.index > firstText) {
+        textAt = index
+        anchored = true
+        break
+      }
+    }
+    if (!anchored) {
+      let before = 0
+      for (const slot of slots) {
+        if (slot.kind === 'original' && slot.index < firstText) before += 1
+      }
+      textAt = before
+    }
+  }
+  return { slots, textAt, added }
+}
+
+/**
+ * Build the carrier content from a layout.
+ *
+ * A kept block is copied out of the original VERBATIM - a structured clone of
+ * the very object the message carries, so an attachment reference, a name, a
+ * dimension and every field a later platform adds cross the edit untouched and
+ * byte-identical. Nothing here inspects what the block is.
+ *
+ * @param originalBlocks - the message content before the edit.
+ * @param layout - the layout from {@link planBlockLayout}.
+ * @param admitted - blocks for the layout's `add` slots, in slot order.
+ * @param text - the revised text.
+ * @returns the block array the carrier is written with.
+ */
+export function assembleBlocks(originalBlocks, layout, admitted, text) {
+  const content = []
+  let next = 0
+  for (let index = 0; index <= layout.slots.length; index += 1) {
+    if (index === layout.textAt) content.push({ type: 'text', text })
+    const slot = layout.slots[index]
+    if (slot === undefined) continue
+    if (slot.kind === 'original') content.push(copyBlock(originalBlocks[slot.index]))
+    else content.push(admitted[next++])
+  }
+  return content
+}
+
+/**
+ * A verbatim copy of one block.
+ *
+ * `structuredClone` is what makes "untouched" literally true rather than
+ * nearly true: the carrier is serialized into the session log, so an identical
+ * copy and the same reference produce identical bytes - the clone only removes
+ * the chance that a later writer mutates the original through it.
+ *
+ * @param block - one content block.
+ * @returns an independent copy of the same JSON value.
+ */
+function copyBlock(block) {
+  try {
+    return structuredClone(block)
+  } catch {
+    // Not clonable (an exotic in-memory block): the block itself is still the
+    // verbatim value, which is what this function promises.
+    return block
+  }
+}
+
 /**
  * Rebuild this plugin's rollback ledger from the log alone.
  *
@@ -462,6 +755,9 @@ export function planRollback(events, surfaceNodes, request) {
     throw new EditPlanError('not-editable', 'the target does not open a rollback window')
   }
   const { text, attachments } = readMessageText(target)
+  // The blocks themselves travel with the plan: the carrier is rebuilt from
+  // them, so no caller has to re-read the message to know what it carries.
+  const blocks = readMessageBlocks(target)
   const turn = turnOf.get(target.seq)
   const data = target.data && typeof target.data === 'object' ? target.data : {}
   const message = data.message && typeof data.message === 'object' ? data.message : data
@@ -481,6 +777,7 @@ export function planRollback(events, surfaceNodes, request) {
     model: source && typeof source.model === 'string' ? source.model : null,
     original: text,
     attachments,
+    blocks,
   }
 }
 
@@ -493,9 +790,11 @@ export function planRollback(events, surfaceNodes, request) {
  *
  * @param events - complete contiguous raw event log.
  * @param surfaceNodes - current surface seqs in model order.
+ * @param options - `{ preview }`: whether the deployment can hand attachment
+ *   bytes back, which decides if a chip may offer a thumbnail.
  * @returns one entry per editable prompt, in conversation order.
  */
-export function editableTurns(events, surfaceNodes) {
+export function editableTurns(events, surfaceNodes, options = {}) {
   const eventBySeq = new Map(events.map((event) => [event.seq, event]))
   const turnOf = turnIndex(events)
   const head = surfaceNodes[0]
@@ -516,6 +815,9 @@ export function editableTurns(events, surfaceNodes) {
       messageId: messageIdOf(event) ?? null,
       text,
       attachments,
+      // What the editor draws beside the text: one chip per non-text block,
+      // described by field presence only (see blockSummaries).
+      blocks: blockSummaries(readMessageBlocks(event), options.preview === true),
     })
   }
   return out
@@ -727,6 +1029,166 @@ async function flushSession(ctx, session) {
   return { flushed: false, flushError: errors.join(' | ') }
 }
 
+// --- attachment admission ----------------------------------------------------
+//
+// The platform's durable store is the only path by which bytes become a
+// reference a session may cite (@deepseek-ai/dsh-attachment's `AttachmentStore`;
+// the local backend is @deepseek-ai/dsh-attachment-local). It is resolved at
+// REQUEST time, never assumed: a deployment that mounts none must keep working
+// exactly as this plugin did before blocks travelled at all - text only, with
+// the editor saying so - and one that mounts a store later starts working with
+// no restart.
+
+/**
+ * The durable attachment store this deployment mounts, when it has one.
+ *
+ * Candidate names are probed the way the platform's own consumers reach it
+ * (`ctx.get('attachments')`, e.g. dsh-acp). An object is only accepted when it
+ * can actually admit something: a service that merely shares the name must not
+ * make the editor promise to keep a block the host cannot store.
+ *
+ * @param ctx - plugin context.
+ * @returns the store, or null when the deployment mounts none.
+ */
+export function resolveAttachmentStore(ctx) {
+  if (!ctx || typeof ctx.get !== 'function') return null
+  for (const name of ATTACHMENT_SERVICES) {
+    let store
+    try {
+      store = ctx.get(name)
+    } catch {
+      store = null
+    }
+    if (!store || typeof store !== 'object') continue
+    if (typeof store.saveImage === 'function' || typeof store.saveFile === 'function') return store
+  }
+  return null
+}
+
+/**
+ * Whether this deployment can hand attachment bytes back for a chip thumbnail.
+ * @param store - the resolved store, or null.
+ * @returns true when a read path exists.
+ */
+export function canPreviewAttachments(store) {
+  return Boolean(store) && (typeof store.readImage === 'function' || typeof store.fileHostPath === 'function')
+}
+
+/**
+ * Decode one upload exactly the way the platform's wire admission does.
+ *
+ * Canonical base64 only (the platform's `admission.js` test): a payload whose
+ * re-encoding differs is refused rather than silently decoded into different
+ * bytes than the browser meant to send.
+ *
+ * @param data - base64 text.
+ * @returns the decoded bytes.
+ * @throws {HttpError} 400 `invalid` for anything but bounded canonical base64.
+ */
+function decodeUpload(data) {
+  if (typeof data !== 'string' || data === '') throw new HttpError(400, 'invalid', 'an upload carried no data')
+  if (data.length > MAX_UPLOAD_BYTES * 2) throw new HttpError(400, 'invalid', 'an upload is too large')
+  const decoded = Buffer.from(data, 'base64')
+  if (decoded.toString('base64') !== data) throw new HttpError(400, 'invalid', 'an upload is not canonical base64')
+  if (decoded.byteLength > MAX_UPLOAD_BYTES) throw new HttpError(400, 'invalid', 'an upload is too large')
+  return new Uint8Array(decoded)
+}
+
+/**
+ * Admit one uploaded payload and hand back the block that cites it.
+ *
+ * The STORE decides the shape, not this plugin: bytes it accepts as an image
+ * become the platform's image block, anything else is stored verbatim as a file
+ * block. That is the platform's own vocabulary (`AttachmentStore.saveImage` /
+ * `saveFile`, and `admitPromptContent` builds the same two shapes), and it is
+ * the only place a block type is named in the whole edit path - a block the
+ * user did not touch never passes through here at all.
+ *
+ * @param store - the resolved attachment store.
+ * @param upload - `{ data, mediaType?, name? }`.
+ * @returns the content block citing the durable reference.
+ * @throws {HttpError} 400 `attachment-refused` when the store refuses it.
+ */
+export async function admitUpload(store, upload) {
+  const data = decodeUpload(upload.data)
+  const name = typeof upload.name === 'string' && upload.name !== '' ? upload.name : undefined
+  const mediaType = typeof upload.mediaType === 'string' && upload.mediaType !== '' ? upload.mediaType : undefined
+  // The store's own advertised media types decide whether it can take this as
+  // an image; without that list, the declared type family is the only signal.
+  const imageTypes = store.imageLimits && Array.isArray(store.imageLimits.mediaTypes) ? store.imageLimits.mediaTypes : null
+  const asImage = mediaType !== undefined && typeof store.saveImage === 'function' &&
+    (imageTypes === null ? mediaType.startsWith('image/') : imageTypes.includes(mediaType))
+  try {
+    if (asImage) {
+      const ref = await store.saveImage(name === undefined ? { data, mediaType } : { data, mediaType, name })
+      return { type: 'image', attachment: ref }
+    }
+    if (typeof store.saveFile !== 'function') {
+      throw new HttpError(400, 'attachment-refused', 'this deployment can only store images')
+    }
+    const ref = await store.saveFile(name === undefined ? { data } : { data, name })
+    return { type: 'file', attachment: ref }
+  } catch (error) {
+    if (error instanceof HttpError) throw error
+    // The store's own refusal (too many images, wrong bytes, an unwritable
+    // root) is reported as-is and NOTHING is written: admission runs before the
+    // first append, so a refused upload can never leave a half-built carrier.
+    const detail = String((error && error.message) || error)
+    throw new HttpError(400, 'attachment-refused', detail)
+  }
+}
+
+/**
+ * The bytes of one block's attachment, for a chip's thumbnail.
+ *
+ * A display-only read, deliberately kept out of the edit path. It answers from
+ * whatever read seam the mounted store offers - an image reader, or the host
+ * path of a verbatim file - and gives up quietly when neither exists, because a
+ * chip without a picture is still a usable chip. The block is located by the
+ * seq of the message and its index inside that message's content, and the only
+ * authorization is that the session's own log really does cite it: the same bar
+ * the platform's attachment RPC applies before handing bytes over.
+ *
+ * @param ctx - plugin context.
+ * @param sessionId - the session whose log owns the block.
+ * @param seq - seq of the message event.
+ * @param index - the block's index in that message's content.
+ * @returns `{ data, mediaType }`, or null when there is nothing to serve.
+ */
+export async function attachmentBytes(ctx, sessionId, seq, index) {
+  const events = await readEvents(ctx, sessionId)
+  if (!events) return null
+  const event = events.find((item) => item && item.seq === seq)
+  if (!event) return null
+  const block = readMessageBlocks(event)[index]
+  if (!block || typeof block !== 'object') return null
+  const ref = block.attachment
+  if (!ref || typeof ref !== 'object' || typeof ref.attachmentId !== 'string' || ref.attachmentId === '') return null
+  if (typeof ref.bytes === 'number' && ref.bytes > MAX_PREVIEW_BYTES) return null
+  const store = resolveAttachmentStore(ctx)
+  if (store === null) return null
+  if (typeof store.readImage === 'function') {
+    try {
+      const stored = await store.readImage(ref)
+      if (stored && stored.data) {
+        const mediaType = stored.ref && typeof stored.ref.mediaType === 'string' ? stored.ref.mediaType : ref.mediaType
+        return { data: Buffer.from(stored.data), mediaType: typeof mediaType === 'string' ? mediaType : undefined }
+      }
+    } catch {
+      // Not an image reference; a stored file is read below.
+    }
+  }
+  if (typeof store.fileHostPath === 'function') {
+    try {
+      const path = store.fileHostPath(ref)
+      if (typeof path === 'string' && path !== '') return { data: await readFile(path), mediaType: undefined }
+    } catch {
+      // The reference resolves to nothing this deployment can serve.
+    }
+  }
+  return null
+}
+
 // --- operations --------------------------------------------------------------
 
 async function stateOf(ctx, sessionId, config) {
@@ -738,7 +1200,11 @@ async function stateOf(ctx, sessionId, config) {
   const folded = foldSurface(events)
   const ledger = rollbackLedger(events)
   const live = findLiveSession(ctx, sessionId)
-  const turns = editableTurns(events, folded.nodes)
+  // Probed per request: the editor offers what THIS deployment can do right
+  // now, so a store that is unmounted (or not yet mounted) cannot leave the
+  // editor promising to keep blocks the host would have to drop.
+  const store = resolveAttachmentStore(ctx)
+  const turns = editableTurns(events, folded.nodes, { preview: canPreviewAttachments(store) })
   const replies = editableReplies(events, folded.nodes)
   noteRequest({
     kind: 'state',
@@ -764,6 +1230,11 @@ async function stateOf(ctx, sessionId, config) {
     live: Boolean(live),
     busy: isBusy(events),
     lastSeq: events.length > 0 ? events[events.length - 1].seq : -1,
+    // What this deployment can do with a block list. `attachments` is the
+    // admission path (a chip the editor may keep) and `preview` is the read
+    // path (a chip that may draw its own thumbnail); both are answered from a
+    // live service probe, so the editor never promises what the host cannot do.
+    capabilities: { attachments: store !== null, preview: canPreviewAttachments(store) },
     config: { confirm: config.confirm },
     version: PLUGIN_VERSION,
   }
@@ -775,9 +1246,13 @@ async function stateOf(ctx, sessionId, config) {
  * @param plan - the planned window.
  * @param lastTurn - highest turn number in the log, for a coherent bracket.
  * @param config - resolved deployment policy.
+ * @param content - the block list the revised prompt carries. Omitted, the
+ *   carrier falls back to the marker text alone, which is what every caller
+ *   that predates block-preserving edits (and the silent developer carrier)
+ *   still asks for.
  * @returns `{ type, data }` for `session.append`.
  */
-export function buildCarrier(plan, lastTurn, config) {
+export function buildCarrier(plan, lastTurn, config, content) {
   const silent = config.carrier !== 'user/message'
   if (silent) {
     // The silent carrier is an empty message that projects to no model message.
@@ -807,7 +1282,7 @@ export function buildCarrier(plan, lastTurn, config) {
     data: {
       id: randomUUID(),
       role: 'user',
-      content: [{ type: 'text', text: config.markerText }],
+      content: Array.isArray(content) && content.length > 0 ? content : [{ type: 'text', text: config.markerText }],
       // `kind: 'user'`, NOT a plugin-owned kind. This carrier stands in a human's
       // place - it IS the wording the user is asking with now - and the platform
       // owns that judgement: a human prompt is exactly a `user/message` whose
@@ -898,7 +1373,25 @@ async function applyEdit(ctx, sessionId, body, config) {
     if (!surfaceNodes.includes(seq)) throw new HttpError(409, 'stale', 'the session changed, retry')
   }
 
-  // Nothing to write when the revision IS the live text.
+  // The submitted block list, when the browser half sent one: which of the
+  // message's blocks the user kept, in order, plus anything they just picked.
+  // A caller that sends `text` only is a client from before blocks travelled -
+  // a supported caller, not a broken one: it gets exactly the text-only carrier
+  // this plugin has always written, and the answer says what that cost.
+  let parts = plan.mode === 'prompt' && Array.isArray(body.parts) ? normalizeParts(body.parts, plan.blocks.length) : null
+  let layout = parts === null ? null : planBlockLayout(plan.blocks, parts)
+  // What this deployment can admit, probed NOW rather than remembered: with no
+  // store mounted, nothing can be uploaded and no block may be promised, so the
+  // edit degrades to the text-only carrier - the exact behaviour every release
+  // before this one had - and the answer reports the blocks it had to leave
+  // behind instead of writing a reference nothing can resolve.
+  const store = plan.mode === 'prompt' ? resolveAttachmentStore(ctx) : null
+  if (layout !== null && store === null) {
+    parts = null
+    layout = null
+  }
+
+  // Nothing to write when the revision changes nothing.
   //
   // The editor opens prefilled with exactly this text - it comes from
   // `readMessageText`, the same parse behind `/state`'s `turns[].text` and
@@ -908,6 +1401,14 @@ async function applyEdit(ctx, sessionId, body, config) {
   // unchanged save used to add a revision with no revision behind it and a whole
   // turn to the rail while the conversation had not moved at all.
   //
+  // Since blocks travel, the same question is asked of the whole message: the
+  // carrier is rebuilt from the submitted list and compared against the original
+  // block for block (see sameJson), so a save that keeps every block where it was
+  // writes nothing either. A caller that sends text only keeps the original,
+  // narrower test - its carrier IS text-only by construction, and comparing that
+  // against a message with a picture in it would turn "I changed nothing" into a
+  // write that drops the picture.
+  //
   // Compared verbatim, deliberately, which is the same caliber the editor was
   // filled with: a trailing space is a real difference and keeps the old
   // behaviour, and nothing here trims (the only trim in this function is the
@@ -917,7 +1418,9 @@ async function applyEdit(ctx, sessionId, body, config) {
   // first and re-runs regardless, and its whole point is that the user wants the
   // turn regenerated even when the wording is what it already was. So the caller
   // decides what happens next, and this returns before anything is appended.
-  if (text === plan.original) {
+  const keepsEveryBlock = parts !== null && layout !== null && layout.added === 0 &&
+    sameJson(assembleBlocks(plan.blocks, layout, [], text), plan.blocks)
+  if (text === plan.original && (parts === null || keepsEveryBlock)) {
     return {
       kind: plan.mode,
       applied: false,
@@ -926,9 +1429,30 @@ async function applyEdit(ctx, sessionId, body, config) {
       // hide a row on account of this answer.
       shadowed: [],
       original: plan.original,
+      // Nothing was written, so nothing was left behind either - and the
+      // message's blocks are the ones it already had.
+      dropped: false,
+      blocks: blockSummaries(plan.blocks, canPreviewAttachments(store)),
     }
   }
 
+  // Admission happens here, BEFORE the first append and outside the try blocks
+  // below: a refused upload must not be able to leave a rollback (or a synthetic
+  // turn) behind in the log. The blocks come back in slot order, which is the
+  // order the layout put them in.
+  const admitted = []
+  if (layout !== null) {
+    for (const slot of layout.slots) {
+      if (slot.kind === 'add') admitted.push(await admitUpload(store, slot.upload))
+    }
+  }
+  const content = layout === null ? [{ type: 'text', text }] : assembleBlocks(plan.blocks, layout, admitted, text)
+  // Whether this save left non-text blocks behind, told to the caller instead of
+  // being discovered later: true for a reply (its tool calls and reasoning
+  // cannot survive a replacement) and true for a message rewritten without its
+  // blocks. False whenever the carrier really did carry them.
+  const dropped = layout === null && plan.blocks.some((block) => !isTextBlock(block))
+
   // A revised prompt has to (a) replace the old wording in the model context and
   // (b) NOT be answered. The platform answers any user message it finds on the
   // surface, so the revision cannot be *appended* - appending one made the loop
@@ -941,7 +1465,7 @@ async function applyEdit(ctx, sessionId, body, config) {
   // (it projects `lastTurn` from every turn/start it observes). A prompt edit
   // does not: `user/message` carries the revision and needs no turn.
   const editTurn = plan.mode === 'reply' ? nextTurnOf(events) : lastTurnOf(events)
-  const carrier = buildCarrier(plan, editTurn, plan.mode === 'prompt' ? { ...config, carrier: 'user/message', markerText: text } : config)
+  const carrier = buildCarrier(plan, editTurn, plan.mode === 'prompt' ? { ...config, carrier: 'user/message', markerText: text } : config, content)
   if (plan.mode === 'reply') {
     try {
       session.append('turn/start', { turn: editTurn })
@@ -952,6 +1476,7 @@ async function applyEdit(ctx, sessionId, body, config) {
         applied: false,
         applyError: `could not open a turn for the correction: ${String((error && error.message) || error)}`,
         shadowed: plan.shadowed,
+        dropped,
       }
     }
   }
@@ -998,6 +1523,7 @@ async function applyEdit(ctx, sessionId, body, config) {
         applied: false,
         applyError: `the corrected reply was refused: ${String((error && error.message) || error)}`,
         shadowed: plan.shadowed,
+        dropped,
         ...flush,
       }
     }
@@ -1022,6 +1548,7 @@ async function applyEdit(ctx, sessionId, body, config) {
       applied: true,
       loopTurn,
       shadowed: plan.shadowed,
+      dropped,
       ...corrected,
     }
   }
@@ -1037,6 +1564,12 @@ async function applyEdit(ctx, sessionId, body, config) {
     replacementSeq: replacement.seq,
     applied: true,
     shadowed: plan.shadowed,
+    dropped,
+    // What the carrier now carries, described exactly the way /state describes
+    // it. The browser half adopts this for the row it re-draws before its own
+    // refresh lands - without it a second save could not know which blocks are
+    // still there and would rewrite the message text-only.
+    blocks: blockSummaries(content, canPreviewAttachments(store)),
     ...flush,
   }
 }
@@ -1143,16 +1676,32 @@ function sendJson(res, status, body) {
   res.end(payload)
 }
 
-function readBody(req) {
+// The body limit is the upload limit: a revised message with blocks arrives as
+// base64 inside this JSON, so /apply asks for a larger ceiling than the tiny
+// default. The read is refused rather than truncated, and the socket keeps
+// draining so the refusal can still be answered.
+function readBody(req, limit = 1e6) {
   return new Promise((resolve, reject) => {
     let data = ''
+    let refused = false
     req.on('data', (chunk) => {
+      if (refused) return
       data += chunk
-      if (data.length > 1e6) req.destroy()
+      if (data.length > limit) {
+        refused = true
+        data = ''
+        reject(new HttpError(413, 'invalid', 'the request body is too large'))
+      }
+    })
+    req.on('end', () => {
+      if (!refused) resolve(data)
+    })
+    req.on('error', (error) => {
+      if (!refused) reject(error)
+    })
+    req.on('aborted', () => {
+      if (!refused) reject(new Error('aborted'))
     })
-    req.on('end', () => resolve(data))
-    req.on('error', reject)
-    req.on('aborted', () => reject(new Error('aborted')))
   })
 }
 
@@ -1238,6 +1787,49 @@ export function apply(ctx, config) {
       }),
     )
 
+    // The bytes behind one block, for the editor's chips. Read-only, loopback
+    // and same-origin like everything else here, and answered only for a block
+    // the session's own log cites.
+    fiber.effect(() =>
+      webServer.register({
+        kind: 'exact',
+        path: `${ROUTE_PREFIX}/attachment`,
+        handler: async (req, res) => {
+          if (!guard(req, res)) return
+          if (req.method !== 'GET') {
+            sendJson(res, 405, { ok: false, code: 'method', error: 'GET only' })
+            return
+          }
+          try {
+            const url = new URL(req.url, 'http://localhost')
+            const sessionId = requireSessionId((url.searchParams.get('sessionId') || '').trim())
+            const seq = Number(url.searchParams.get('seq'))
+            const index = Number(url.searchParams.get('index'))
+            if (!Number.isInteger(seq) || seq < 0 || !Number.isInteger(index) || index < 0) {
+              throw new HttpError(400, 'invalid', 'seq and index must be whole numbers')
+            }
+            const found = await attachmentBytes(ctx, sessionId, seq, index)
+            if (found === null) {
+              // Deliberately without a code: the editor translates codes into
+              // sentences, and "this chip has no picture" is not one the user
+              // needs to read - the chip simply draws its label.
+              sendJson(res, 404, { ok: false, error: 'no attachment bytes for this block' })
+              return
+            }
+            res.writeHead(200, {
+              'content-type': typeof found.mediaType === 'string' && found.mediaType !== '' ? found.mediaType : 'application/octet-stream',
+              'content-length': found.data.byteLength,
+              // The stored object is immutable and content-addressed.
+              'cache-control': 'private, max-age=600',
+            })
+            res.end(found.data)
+          } catch (error) {
+            failure(res, error)
+          }
+        },
+      }),
+    )
+
     // Read-only diagnostics. The browser half's own state cannot be observed
     // from here, so the next best thing is an honest record of what its requests
     // asked for and what they got back.
@@ -1266,9 +1858,20 @@ export function apply(ctx, config) {
             sendJson(res, 405, { ok: false, code: 'method', error: 'POST only' })
             return
           }
+          let raw
+          try {
+            // A block list travels as base64 inside this body, so the ceiling is
+            // the upload ceiling (see MAX_BODY_BYTES) - and an oversized body is
+            // reported as such instead of being read as far as it goes.
+            raw = await readBody(req, MAX_BODY_BYTES)
+          } catch (error) {
+            const status = error instanceof HttpError ? error.status : 400
+            const detail = error instanceof HttpError ? error.message : 'malformed JSON body'
+            sendJson(res, status, { ok: false, code: 'invalid', error: detail })
+            return
+          }
           let body = {}
           try {
-            const raw = await readBody(req)
             if (raw) body = JSON.parse(raw)
           } catch {
             sendJson(res, 400, { ok: false, code: 'invalid', error: 'malformed JSON body' })
@@ -1292,6 +1895,10 @@ export function apply(ctx, config) {
               // shows nothing for it, so this ring is the only place that records
               // "the user pressed save and nothing needed saving".
               unchanged: result.unchanged === true,
+              // Whether non-text blocks were left behind by this save (see
+              // applyEdit). The log cannot show this: the carrier is one event
+              // either way.
+              dropped: result.dropped === true,
             })
             sendJson(res, 200, { ok: true, ...result })
           } catch (error) {