@matatbread/matbot-core 0.4.6 → 0.4.8

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.4.6",
+  "version": "0.4.8",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@matatbread/matbot-plugin-api": "^0.4.6"
+    "@matatbread/matbot-plugin-api": "^0.4.8"
   },
   "devDependencies": {
     "typescript": "^6.0.3"

package/src/about.ts

@@ -1,24 +1,45 @@
-import type { Tool, ToolExecutor, ToolContract, ToolResultOf, ToolContext } from '@matatbread/matbot-plugin-api';
+import type {
+  Tool, ToolExecutor, ToolContract, ToolResultOf, ToolContext, MatbotMachine, SystemContextPart,
+} from '@matatbread/matbot-plugin-api';
 
 declare module '@matatbread/matbot-plugin-api' {
   interface ToolContracts {
-    about_matbot: ToolContract<{ version: string; about: string, currentProvider: string | undefined }, Record<string, never>>;
+    about_matbot: ToolContract<{
+      version:         string;
+      about:           string;
+      currentProvider: string | undefined;
+      /** The system prompt in force, exactly as the model receives it — the joined `systemContext`
+       *  texts. `null` when no contributor produced anything (there is then no system message at all). */
+      systemPrompt:    string | null;
+      /** The same text kept apart and attributed, so a contribution can be traced to its plugin. */
+      systemContext:   SystemContextPart[];
+    }, Record<string, never>>;
   }
 }
 
 const ABOUT = 'Matbot composable LLM harness';
 
 /**
- * Reports what the model is running: the harness `version` and a one-line description. The harness is
- * not a plugin (so it has no row in `plugin list`), and its version is a singleton fact rather than a
- * per-plugin one — hence a dedicated tool. The factory lives in core (like `single_turn`) because it is
- * the one cross-runtime home both the node app and the browser bundle register it from, each passing its
- * own app package version.
+ * Reports what the model is running: the harness `version`, a one-line description, the provider
+ * driving this turn, and the system prompt in force. The harness is not a plugin (so it has no row in
+ * `plugin list`), and its version is a singleton fact rather than a per-plugin one — hence a dedicated
+ * tool. The factory lives in core (like `single_turn`) because it is the one cross-runtime home both the
+ * node app and the browser bundle register it from, each passing its own app package version.
+ *
+ * The system prompt is REBUILT here rather than read back: it is assembled once per submit and never
+ * persisted (see `runner`'s `system-context` event), so there is nothing on the session to read. Rebuilt
+ * against this turn's session it is the same text the turn was given, unless a contributor's own source
+ * changed mid-turn — a skill added, a plugin loaded — in which case it correctly reports what the NEXT
+ * call will carry.
  */
-export function createAboutMatbotTool(version: string): Tool<ToolResultOf<'about_matbot'>> {
+export function createAboutMatbotTool(version: string, services: MatbotMachine): Tool<ToolResultOf<'about_matbot'>> {
   const executor: ToolExecutor<ToolResultOf<'about_matbot'>> = {
     async *execute(_input: unknown, ctx: ToolContext) {
-      yield { type: 'result', value: { version, about: ABOUT, currentProvider: ctx.provider } };
+      const systemContext = await services.systemContext.parts({ session: ctx.session, signal: ctx.signal });
+      // Joined exactly as the registry joins it for the wire — one source, so the reported prompt and the
+      // sent prompt cannot differ in their separators.
+      const systemPrompt = systemContext.length > 0 ? systemContext.map(p => p.text).join('\n\n') : null;
+      yield { type: 'result', value: { version, about: ABOUT, currentProvider: ctx.provider, systemPrompt, systemContext } };
     },
   };
 
@@ -26,9 +47,12 @@ export function createAboutMatbotTool(version: string): Tool<ToolResultOf<'about
     name: 'about_matbot',
     description:
       'Report what you are running right now: the current model / LLM and provider profile powering THIS ' +
-      'conversation, plus the matbot harness version and a one-line description. Use it whenever asked ' +
-      '"what model / LLM are you using?", "which provider is this?", what version of matbot this is, or for ' +
-      'an "about" of the harness itself — distinct from the `provider` tool (which lists all configured ' +
+      'conversation, the matbot harness version and a one-line description, and the SYSTEM PROMPT in force ' +
+      'for this conversation — both as one string (`systemPrompt`, exactly what you were given) and broken ' +
+      'down per contributing plugin (`systemContext`), which is how to answer "why are you being told that?" ' +
+      'or "what is in your system prompt?". Use it whenever asked "what model / LLM are you using?", "which ' +
+      'provider is this?", what version of matbot this is, what your instructions or system prompt are, or ' +
+      'for an "about" of the harness itself — distinct from the `provider` tool (which lists all configured ' +
       'provider profiles) and the `plugin` tool (which lists loaded plugins).',
     inputSchema: { type: 'object', properties: {} },
     executor,

package/src/index.ts

@@ -10,11 +10,12 @@ export {
   notAPluginError, isNotAPluginError,
   promptCancelledError, isPromptCancelledError,
   readOnlyError, isReadOnlyError,
+  mediaRejectedError, isMediaRejectedError,
   StoreQueryError,
 } from '@matatbread/matbot-plugin-api';
 export type {
   MissingSecretError, IncompatibleRuntimeError, NotAPluginError, PromptCancelledError, ReadOnlyError,
-  MatbotErrorKind,
+  MediaRejectedError, MatbotErrorKind,
 } from '@matatbread/matbot-plugin-api';
 export { applyCreateSecret }  from '@matatbread/matbot-plugin-api';
 export { isTruncatedToolResult, notifyingStore, ItemChangeKind, RegistryChangeKind } from '@matatbread/matbot-plugin-api';
@@ -49,6 +50,7 @@ export * from './tool-registry.js';
 export * from './provider-registry.js';
 export * from './system-context.js';
 export * from './single-turn.js';
+export * from './media.js';
 export * from './about.js';
 export * from './config/index.js';
 export * from './security/index.js';

package/src/media.ts

@@ -0,0 +1,266 @@
+import type { MediaStore, Message, MessageContent, MimeType, UserContent } from './types.js';
+import { collectBytes, decodeBase64, encodeBase64, mediaRejectedError } from '@matatbread/matbot-plugin-api';
+
+/**
+ * User-supplied session media: the two ends of the one path. Bytes arrive by value at the submission
+ * boundary, are written through the `MediaStore` and replaced by a `file-ref` before anything is
+ * enqueued ({@link ingestMedia}); the runner resolves those refs back to inline bytes on the *outgoing
+ * copy only*, newest-first and inside a byte budget ({@link resolveSessionMedia}).
+ *
+ * Contrast the tool-media (`model-content`) path, which is wire-only in both directions and never had a
+ * store: there the model pulls, here a person pushed. What the two share is the invariant — no base64
+ * ever reaches a session document.
+ */
+
+/** Namespace session media is written under, so it is distinguishable from workspace files sharing a store. */
+export const MEDIA_NAMESPACE = 'session-media';
+
+/**
+ * How many bytes of media the outgoing copy may carry. Walked newest-first, so the freshest attachment
+ * always makes it and an old one falls out; beyond the budget the `file-ref` is left alone and the
+ * converters degrade it to `[Attached file: x]` — honest, already written, and the file is still there.
+ *
+ * A byte budget rather than a turn count because the cost being bounded is denominated in bytes: three
+ * turns is a fine window for a thumbnail and a ruinous one for a 40MB PDF, and a count cannot tell them
+ * apart. One knob; measure before adding a second.
+ */
+export const MEDIA_RESIDENCY_BYTES = 8 * 1024 * 1024;
+
+/** Per-file ceiling at the submission boundary. Refusing here — naming the file — is the point: the
+ *  alternative is a provider 400 part-way through a turn the user already believes was sent.
+ *
+ *  It IS the residency budget rather than a second, larger number, because a file bigger than the
+ *  window can never be resident: `spent + size > budget` is true on the very first item with
+ *  `spent === 0`, so such a file would be stored, charged to the session quota, and then degraded to
+ *  `[Attached file: x]` on every turn for the rest of the session — accepted, permanently invisible,
+ *  and with no boundary having said a word. Deriving it makes that state unrepresentable rather than a
+ *  second check to remember; raise the window and the cap follows. */
+export const MAX_MEDIA_BYTES_PER_FILE = MEDIA_RESIDENCY_BYTES;
+
+/** Per-session total, derived by summing what the store already holds for the session rather than kept
+ *  as a counter: a counter is wrong after a restart, a swap, or anything deleting a file behind it. */
+export const MAX_MEDIA_BYTES_PER_SESSION = 50 * 1024 * 1024;
+
+const INLINE_ARMS = new Set(['image', 'document', 'audio']);
+
+/**
+ * Image types a vision endpoint actually decodes.
+ *
+ * `image/*` is the one prefix that cannot be admitted by prefix alone: a provider TRIES to decode
+ * whatever the image arm carries and 400s on what it cannot, where an unrecognised document or audio
+ * type degrades to a text note instead. So HEIC (what an iPhone camera roll hands back, and what a
+ * `<input type="file">` with no `accept` will happily offer), SVG (XML — `read` gives the source, which
+ * is the better answer anyway), BMP and TIFF have to be refused at the boundary rather than routed to
+ * an arm that will fail: by the time the 400 arrives the `file-ref` is in persisted history, where it
+ * resolves into every subsequent outgoing copy and fails the session for good.
+ *
+ * Same list and same reasoning as `workspace`'s `showArm`. The two stay separate because they answer
+ * for separate stores; if a third ever needs it, this is the one to hoist.
+ */
+const DECODABLE_IMAGE: ReadonlySet<string> = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+
+/**
+ * Which inline arm a stored file comes back as, or null for a type that must not be sent at all. What
+ * each adapter then does with an arm differs: google inlines all three; anthropic inlines images and
+ * PDF/text documents and degrades the rest to a note; openai-compat inlines images only. A degraded arm
+ * becomes a text note, never nothing — which is precisely why only `image/*` needs gating.
+ *
+ * Exported because `single_turn` resolves attachments through the same mapping: a mime-routing rule
+ * with two copies is one that gets fixed in one of them.
+ */
+export function armFor(mimeType: string): 'image' | 'audio' | 'document' | null {
+  const base = mimeType.split(';')[0]!.trim().toLowerCase();
+  if (base.startsWith('image/')) return DECODABLE_IMAGE.has(base) ? 'image' : null;
+  if (base.startsWith('audio/')) return 'audio';
+  return 'document';
+}
+
+/**
+ * Leading bytes that unambiguously identify a format. Only the types where a mismatch is a GUARANTEED
+ * provider rejection — a model endpoint decodes these itself and 400s on anything it cannot parse.
+ * Nothing else is sniffed: for `text/*`, audio, or an octet-stream we genuinely do not know, and
+ * guessing would refuse valid files.
+ */
+const MAGIC: ReadonlyArray<{ mime: string; at: number; sig: readonly number[] }> = [
+  { mime: 'image/png',  at: 0, sig: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] },
+  { mime: 'image/jpeg', at: 0, sig: [0xff, 0xd8, 0xff] },
+  { mime: 'image/gif',  at: 0, sig: [0x47, 0x49, 0x46, 0x38] },                        // "GIF8"
+  { mime: 'image/webp', at: 0, sig: [0x52, 0x49, 0x46, 0x46] },                        // "RIFF" (…WEBP at 8)
+  { mime: 'image/webp', at: 8, sig: [0x57, 0x45, 0x42, 0x50] },                        // "WEBP"
+  { mime: 'application/pdf', at: 0, sig: [0x25, 0x50, 0x44, 0x46] },                   // "%PDF"
+];
+
+/**
+ * Does this file's content match the type it claims? Returns false only when we KNOW it does not.
+ *
+ * This is the boundary doing the one check it can: a provider decodes these formats itself and 400s
+ * on anything it cannot parse, and a 400 arrives mid-turn — after the message is persisted, with the
+ * `file-ref` now in history where it resolves into EVERY subsequent outgoing copy and fails the
+ * session for good. A renamed file, a truncated upload or a placeholder is caught here instead, while
+ * refusing still costs the user nothing but re-picking the file.
+ *
+ * It is not a validity check: a well-formed header on a structurally broken document still passes,
+ * because only the provider can know that.
+ */
+function contentMatchesType(bytes: Uint8Array, mimeType: string): boolean {
+  const base = mimeType.split(';')[0]!.trim().toLowerCase();
+  const rules = MAGIC.filter(m => m.mime === base);
+  if (rules.length === 0) return true;                       // nothing known about this type — don't guess
+  return rules.every(r =>
+    bytes.length >= r.at + r.sig.length && r.sig.every((b, i) => bytes[r.at + i] === b));
+}
+
+function describe(name: string | undefined, mimeType: string): string {
+  return name ?? `attachment.${mimeType.split('/')[1] ?? 'bin'}`;
+}
+
+function humanBytes(n: number): string {
+  if (n < 1024)        return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * The submission boundary, in one place so every frontend inherits it: rewrite each by-value media arm
+ * to a `file-ref` against the `MediaStore`, leave text untouched, and VET each ref a caller supplied
+ * itself.
+ *
+ * A text-only submission never touches the store, so a deployment with no `MediaStore` registered is
+ * completely unaffected — it only hears about one when someone actually attaches something, and then it
+ * is told why rather than silently dropping it.
+ *
+ * Vetting the refs belongs here and nowhere else. A submission crosses a wire boundary, so a `fileId`
+ * is the client's word about which bytes to send, and `resolveSessionMedia` inlines whatever it is
+ * handed — no session, no namespace, no `allowed` consulted — which made "describe this" a read of any
+ * file in the store. This is the only point that knows the session AND has a channel to say no: the
+ * runner could only drop the block silently, mid-turn, for something the user watched itself attach.
+ */
+export async function ingestMedia(
+  content:   readonly UserContent[],
+  sessionId: string,
+  store:     MediaStore | undefined,
+): Promise<MessageContent[]> {
+  // A ref counts: it is the arm that needs CHECKING rather than rewriting, and one cannot be honoured
+  // without a store any more than a by-value arm can be stored without one.
+  if (!content.some(c => INLINE_ARMS.has(c.type) || c.type === 'file-ref')) return content as MessageContent[];
+
+  if (store === undefined) {
+    throw mediaRejectedError('no-store',
+      'This deployment cannot accept attachments: no MediaStore is registered, so there is nowhere to ' +
+      'put the bytes. Send the message as text, or register a media store.');
+  }
+
+  // Derived, not counted — see MAX_MEDIA_BYTES_PER_SESSION. One listing for the whole batch.
+  let sessionBytes = 0;
+  for await (const held of store.list({ sessionId })) sessionBytes += held.size;
+
+  const out: MessageContent[] = [];
+  for (const c of content) {
+    if (c.type === 'file-ref') {
+      // Ownership, not `allowed`: every put below sets `allowed: true`, so the flag the HTTP read route
+      // gates on cannot separate this session's media from another's. `sessionId` + namespace can, and
+      // together they are strictly the stronger check. Reported as unknown rather than forbidden, for
+      // the reason `GET /media/:id` gives: a refusal must not confirm that an id exists.
+      const held = await store.get(c.fileId).catch(() => null);
+      if (held === null || held.sessionId !== sessionId || held.namespace !== MEDIA_NAMESPACE) {
+        throw mediaRejectedError('unknown-ref',
+          `"${c.name}" is not media attached to this session. Attach the file itself, rather than a ` +
+          'reference to one.', c.name);
+      }
+      out.push(c as MessageContent);
+      continue;
+    }
+    if (!INLINE_ARMS.has(c.type)) { out.push(c as MessageContent); continue; }
+    const arm  = c as Extract<UserContent, { data: string }>;
+    const name = describe(arm.name, arm.mimeType);
+
+    // Before the decode, because it needs no bytes and this is the cheapest of the three refusals.
+    if (armFor(arm.mimeType) === null) {
+      throw mediaRejectedError('unsupported-type',
+        `"${name}" is ${arm.mimeType}, which no model endpoint decodes — sending it would fail the ` +
+        'whole conversation, not just this message. Convert it to PNG or JPEG and attach that.', name);
+    }
+
+    let bytes: Uint8Array;
+    try { bytes = decodeBase64(arm.data); }
+    catch { throw mediaRejectedError('unreadable', `"${name}" is not valid base64 and could not be read.`, name); }
+
+    if (!contentMatchesType(bytes, arm.mimeType)) {
+      throw mediaRejectedError('unreadable',
+        `"${name}" does not contain valid ${arm.mimeType} data — the file may be corrupt, truncated, or ` +
+        `misnamed. Sending it would fail the whole conversation, not just this message.`, name);
+    }
+    if (bytes.byteLength > MAX_MEDIA_BYTES_PER_FILE) {
+      throw mediaRejectedError('too-large',
+        `"${name}" is ${humanBytes(bytes.byteLength)}, over the ${humanBytes(MAX_MEDIA_BYTES_PER_FILE)} per-file limit.`, name);
+    }
+    sessionBytes += bytes.byteLength;
+    if (sessionBytes > MAX_MEDIA_BYTES_PER_SESSION) {
+      throw mediaRejectedError('session-quota',
+        `Attaching "${name}" (${humanBytes(bytes.byteLength)}) would take this session over its ` +
+        `${humanBytes(MAX_MEDIA_BYTES_PER_SESSION)} media limit. Start a new session, or attach less.`, name);
+    }
+
+    // Anonymous put: a UUID id, so two uploads of "photo.jpg" in one session are two files rather than
+    // an upsert over each other. The display name rides on the `file-ref` block instead, which every
+    // FileStore therefore preserves without having to.
+    const handle = await store.put(undefined, arm.mimeType, (async function *() { yield bytes; })(),
+      { sessionId, namespace: MEDIA_NAMESPACE, allowed: true });
+    out.push({ type: 'file-ref', fileId: handle.id, name, mimeType: arm.mimeType });
+  }
+  return out;
+}
+
+/**
+ * Turn-side resolution: which `file-ref`s get swapped for inline bytes on the outgoing copy. Returns
+ * message-id → (file-id → the inline arm to stand in for that ref); a message with nothing resolvable
+ * is absent from it, and so is a ref left outside the budget.
+ *
+ * Keyed per REF rather than returning each message's finished content array, because the array is not
+ * final when this runs: a raced `screen` verdict folds durable blocks onto the user message *inside* the
+ * round loop, and a caller splicing a whole array resolved at turn start would drop them from every
+ * later round — persisted and on screen, but never sent. Handing back the substitutions instead leaves
+ * the caller mapping blocks it still owns.
+ *
+ * Computed ONCE per turn rather than per round: the bytes cannot change mid-turn, and re-deciding each
+ * round would let a message drop out of the window between two provider calls — busting the prompt
+ * cache and leaving the model referring to something no longer there.
+ */
+export async function resolveSessionMedia(
+  messages: readonly Message[],
+  store:    MediaStore | undefined,
+  budget    = MEDIA_RESIDENCY_BYTES,
+  signal?:  AbortSignal,
+): Promise<Map<string, Map<string, MessageContent>>> {
+  const resolved = new Map<string, Map<string, MessageContent>>();
+  if (store === undefined) return resolved;
+
+  let spent = 0;
+  // Newest-first: the attachment the user is talking about right now is the one that must survive.
+  for (let i = messages.length - 1; i >= 0 && spent < budget; i--) {
+    const msg = messages[i]!;
+    if (!msg.content.some(c => c.type === 'file-ref')) continue;
+
+    const byFileId = new Map<string, MessageContent>();
+    for (const c of msg.content) {
+      if (c.type !== 'file-ref') continue;
+      // Left out of the map, the ref stays exactly as it is — the converters already render it as
+      // `[Attached file: x]`, which is true and the file is still fetchable by name. Three ways to
+      // land there: a type no endpoint decodes, a ref the store no longer has, and the budget.
+      const arm = armFor(c.mimeType);
+      if (arm === null) continue;
+      // One resolution per id: the same ref twice in a message must not be paid for twice, and both
+      // blocks render from the one entry.
+      if (byFileId.has(c.fileId)) continue;
+      const handle = spent < budget ? await store.get(c.fileId).catch(() => null) : null;
+      if (handle === null || spent + handle.size > budget) continue;
+      spent += handle.size;
+      const data = encodeBase64(await collectBytes(handle.stream(signal)));
+      byFileId.set(c.fileId, arm === 'document'
+        ? { type: 'document', data, mimeType: c.mimeType as MimeType, name: c.name }
+        : { type: arm,        data, mimeType: c.mimeType as MimeType });
+    }
+    if (byFileId.size > 0) resolved.set(msg.id, byFileId);
+  }
+  return resolved;
+}

package/src/registry.ts

@@ -377,6 +377,7 @@ export async function setupPlugin(plugin: MatbotPlugin, services: MatbotMachine,
       },
       removeByPlugin: (name: string) => services.systemContext.removeByPlugin(name),
       build:          (ctx)          => services.systemContext.build(ctx),
+      parts:          (ctx)          => services.systemContext.parts(ctx),
     },
     async register(key, svc) {
       const keys = state.serviceKeys.get(plugin.name) ?? [];

package/src/runner.ts

@@ -1,7 +1,7 @@
 import type {
   Session, Message, MessageContent, ModelContent, Usage, UsageSite, ProviderMeta, TruncatedToolResult,
   TurnEvent, RunConfig, ProviderAdapter, ProviderConfig,
-  Tool, ToolRegistry, ToolContext, Store, FileStore, SystemContextRegistry, Vault, PromptFn, FormField,
+  Tool, ToolRegistry, ToolContext, Store, FileStore, MediaStore, SystemContextRegistry, Vault, PromptFn, FormField,
 } from './types.js';
 import type { MatbotPlugin } from './plugin.js';
 import type { ToolPresenter } from '@matatbread/matbot-plugin-api';
@@ -10,6 +10,7 @@ import { HookRegistry } from './hooks.js';
 import { appendMessage, createMessage } from './session.js';
 import { foldOntoUserTurn, bindPluginOps } from '@matatbread/matbot-plugin-api';
 import { addUsage } from './usage.js';
+import { MEDIA_RESIDENCY_BYTES, resolveSessionMedia } from './media.js';
 
 // Establish a usage call site across an async iteration. Wrapping the *loop* would not work: this
 // runner is itself an async generator, so it suspends at every `yield` and resumes under the consumer's
@@ -79,6 +80,10 @@ export interface RunSessionOpts {
   workdir?:       string;
   configPath?:    string;
   files?:         FileStore;
+  /** Where user-attached session media lives. Resolved once per turn into the outgoing copy, newest-first
+   *  and inside {@link MEDIA_RESIDENCY_BYTES}; absent ⇒ every `file-ref` stays a ref and the converters
+   *  degrade it. Never read for anything else — the runner does not otherwise touch a file. */
+  mediaStore?:    MediaStore;
   /** Supply a prompt implementation to allow tools to ask interactive questions. */
   prompt?:        PromptFn;
   /**
@@ -228,6 +233,14 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
   // Turn-scoped and wire-only: it is spliced into the outgoing copy below and dies with this call.
   const attachments = new Map<string, Message>();
 
+  // User-attached media, keyed by the message whose `file-ref` blocks it replaces. The mirror of
+  // `attachments` — same splice, different source and different placement: tool media is *pinned after*
+  // the tool message it answers, session media is swapped *in place*, so the model reads the image where
+  // the person actually put it. Resolved once here, not per round: the bytes cannot change mid-turn, and
+  // re-deciding each round could drop a message out of the byte budget between two calls — busting the
+  // prompt cache and leaving the model referring to something no longer there.
+  const sessionMedia = await resolveSessionMedia(session.messages, opts.mediaStore, MEDIA_RESIDENCY_BYTES, signal);
+
   for (;;) {
     // Respect an abort that arrived between turns (e.g. during tool execution).
     if (signal.aborted) {
@@ -283,10 +296,18 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
     // message can be a marker (e.g. a retract-redo leaves the retraction marker as the tail) — folding
     // there would drop the ephemeral with it. -1 ⇒ nothing to fold onto (no non-marker history).
     const foldIdx = ephemeral.length > 0 ? session.messages.findLastIndex(m => m.role !== 'marker') : -1;
-    const history = foldIdx >= 0 || attachments.size > 0
+    const history = foldIdx >= 0 || attachments.size > 0 || sessionMedia.size > 0
       ? session.messages.flatMap((m, i) => {
-          const folded = i === foldIdx ? { ...m, content: [...m.content, ...ephemeral] } : m;
-          const media  = attachments.get(m.id);
+          // Per BLOCK, never the whole array: `sessionMedia` was resolved once before this loop, and a
+          // raced verdict's `foldOntoUserTurn` (claimVerdicts, above) extends this same user message
+          // mid-turn. Substituting the array would put back the pre-fold copy on every later round —
+          // dropping durable robo-user blocks from the wire while leaving them persisted and on screen.
+          const refs    = sessionMedia.get(m.id);
+          const inlined = refs
+            ? { ...m, content: m.content.map(c => (c.type === 'file-ref' ? refs.get(c.fileId) ?? c : c)) }
+            : m;
+          const folded  = i === foldIdx ? { ...inlined, content: [...inlined.content, ...ephemeral] } : inlined;
+          const media   = attachments.get(m.id);
           return media ? [folded, media] : [folded];
         })
       : session.messages;

package/src/session-runner.ts

@@ -1,6 +1,6 @@
 import type {
   Session, Message, MessageContent, Principal, PromptFn, PipelineEvent,
-  Store, ToolRegistry, SystemContextRegistry, Vault, FileStore, Tool,
+  Store, ToolRegistry, SystemContextRegistry, Vault, FileStore, MediaStore, UserContent, Tool,
   ProviderAdapter, ProviderConfig, SessionRunner, SessionView, OpenOpts, SubmitOpenOpts,
   SteeringPolicy, SteeringDecision, TurnEntry,
 } from './types.js';
@@ -11,6 +11,7 @@ import { appendMessage, createMessage } from './session.js';
 import { isReadOnlyError, foldOntoUserTurn, lastUserIndex, runAs } from '@matatbread/matbot-plugin-api';
 import { machineBusy, withUsageScope } from '@matatbread/matbot-plugin-api/host';
 import { runSession } from './runner.js';
+import { ingestMedia } from './media.js';
 
 export interface SessionRunnerDeps {
   store:           Store<Session>;
@@ -28,6 +29,10 @@ export interface SessionRunnerDeps {
   // disposed (queue vs interrupt) and supplies an interrupt's continuation nudge. Absent ⇒ the runner's
   // own defaults (DEFAULT_STEERING_POLICY / DEFAULT_STEER_NUDGE).
   steeringPolicy?: () => SteeringPolicy | undefined;
+  // Resolved live (a host registers its boot default, a plugin may replace it): where a submission's
+  // by-value media is written at the boundary, and where the runner reads it back from. Absent ⇒ an
+  // attachment is refused with a reason and a stored `file-ref` degrades to the converters' text note.
+  mediaStore?:     () => MediaStore | undefined;
   hooks?:          HookRegistry;
   systemContext?:  SystemContextRegistry;
   vault?:          Vault;
@@ -306,9 +311,15 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
         // A redo re-runs the existing committed user turn — no title derivation, no new user message.
         if (head.redo === undefined) {
           if (!session.title && !session.messages.some(m => m.role === 'user')) {
+            // Falls back to the attachment names when the turn has no words of its own: an image-only
+            // first turn is a real submission, and got no title at all — which reads in the session
+            // list as a session that failed to start.
             const text = content
               .filter((c): c is Extract<MessageContent, { type: 'text' }> => c.type === 'text')
-              .map(c => c.text).join(' ').trim();
+              .map(c => c.text).join(' ').trim()
+              || content
+                .filter((c): c is Extract<MessageContent, { type: 'file-ref' }> => c.type === 'file-ref')
+                .map(c => c.name).join(', ');
             if (text) {
               const words = text.split(/\s+/).slice(0, 8).join(' ');
               session = { ...session, title: words.length > 60 ? `${words.slice(0, 60)}…` : words };
@@ -351,6 +362,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
         // inputSchema (no contract) are left as-is; absent ToolTypeIndex (browser) ⇒ plain descriptions.
         const wire = await deps.toolTypeIndex?.()?.wireContracts();
         const toolPresenter = deps.toolPresenter?.();
+        const mediaStore    = deps.mediaStore?.();
         const toolMap = deps.tools !== undefined
           ? new Map<string, Tool>(deps.tools.list().map(t => {
               const wc = wire?.[t.name];
@@ -400,6 +412,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
               ...(deps.systemContext !== undefined ? { systemContext: deps.systemContext } : {}),
               ...(deps.workdir       !== undefined ? { workdir:       deps.workdir       } : {}),
               ...(deps.files         !== undefined ? { files:         deps.files         } : {}),
+              ...(mediaStore         !== undefined ? { mediaStore                        } : {}),
               ...(deps.configPath    !== undefined ? { configPath:    deps.configPath    } : {}),
               ...(deps.vault         !== undefined ? { vault:         deps.vault         } : {}),
               ...(head.prompt        !== undefined ? { prompt:        head.prompt        } : {}),
@@ -455,7 +468,11 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
               // event and the persisted user message the pump builds from this item.
               for (const raw of resubmits.reverse()) {
                 const rt = crypto.randomUUID();
-                const content = raw.map(c => (c.type === 'text' ? { ...c, origin: 'robo' as const } : c));
+                // Every block, not just text: `origin` is authorship, orthogonal to what the block
+                // carries, and a resubmission that attached an image was silently presenting it as the
+                // user's own. The arms a stamp would be wrong on don't occur here — a hook returns
+                // content, not a thinking block — so a blanket stamp beats an arm-by-arm list.
+                const content = raw.map(c => ({ ...c, origin: 'robo' as const }));
                 s.queue.unshift({
                   traceId:       rt,
                   rootTraceId:   head.rootTraceId,
@@ -565,9 +582,26 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
         }
         s = stateFor(opts.sessionId);
         traceId = opts.traceId ?? crypto.randomUUID();
-        const { content, provider, principal } = opts;
+        const { provider, principal } = opts;
         const mode = opts.mode ?? 'queue';
 
+        // Which turn a steer is FOR is fixed here, before the first await, and checked again before the
+        // abort. `s.running` alone cannot answer it: it is true across the pump's whole queue, so it
+        // says "something is running", not "still the one you meant". Every await below can outlive a
+        // turn — the classifier and the nudge could already, and media ingestion can hold for seconds
+        // on a large attachment — after which aborting on `s.running` kills whatever is running NOW,
+        // a turn the user never saw, and names the wrong `interruptedTraceId` on the way.
+        const steerTarget = s.runningTraceId;
+
+        // The media boundary, before anything else this submission touches: by-value attachments are
+        // written through the MediaStore and become `file-ref`s here, so nothing downstream — the
+        // steering classifier, the `queued`/`steer` events, the persisted user message — ever sees
+        // bytes. One place, and every frontend inherits it, which is what lets Telegram (where bytes
+        // arrive WITH the message and there is no upload-in-advance leg) work with no code of its own.
+        // Throws MediaRejectedError on a refusal; nothing is enqueued, so the caller has nothing to
+        // undo — it just tells the user which file and why.
+        const content = await ingestMedia(opts.content, opts.sessionId, deps.mediaStore?.());
+
         // Decide interrupt vs queue for a submission arriving mid-turn. Steering is only meaningful
         // while a turn is running; with nothing running it enqueues and runs next regardless of mode.
         // The decision — and, on interrupt, the abort+unshift — happen here synchronously against
@@ -589,8 +623,10 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
               ? (committed ? await policy.classify({ session: committed, steer: content }) : DEFAULT_STEERING_POLICY)
               : DEFAULT_STEERING_POLICY;
 
-          // Any await above may have outlived the running turn; only interrupt one still live.
-          if (decision === 'interrupt' && s.running) {
+          // Any await above may have outlived the turn this steer was for: interrupt only if THAT one
+          // is still the running turn. Otherwise fall through and queue — the turn they were steering
+          // has already committed, which makes this an ordinary follow-up rather than an interruption.
+          if (decision === 'interrupt' && s.running && s.runningTraceId === steerTarget) {
             const nudge = policy?.nudge !== undefined && committed
               ? policy.nudge({ session: committed, steer: content })
               : DEFAULT_STEER_NUDGE;

package/src/single-turn.ts

@@ -1,11 +1,50 @@
-import type { Tool, ToolExecutor, ToolContract, ToolResultOf, ToolContext, MatbotMachine } from '@matatbread/matbot-plugin-api';
+import type {
+  Tool, ToolExecutor, ToolContract, ToolResultOf, ToolContext, MatbotMachine, MimeType, UserContent, FileStore,
+} from '@matatbread/matbot-plugin-api';
+import { collectBytes, encodeBase64 } from '@matatbread/matbot-plugin-api';
+// The arm mapping is the runner's, not a copy of it: it decides which types may be sent at all, and a
+// rule with two copies is one that gets fixed in one of them.
+import { armFor } from './media.js';
 
 declare module '@matatbread/matbot-plugin-api' {
   interface ToolContracts {
-    single_turn: ToolContract<{ text: string }, { provider?: string; prompt: string; system?: string }>;  // the consulted provider's reply text
+    single_turn: ToolContract<{ text: string }, { provider?: string; prompt: string; system?: string; attach?: string[] }>;  // the consulted provider's reply text
   }
 }
 
+/**
+ * Resolve `attach` names/ids to inline media for the one-shot. Looked up by **id first, then name**,
+ * across the MediaStore and then the turn's own file store: an id is unambiguous and a name is what a
+ * model actually has to hand, and both stores are in play because session media and workspace files are
+ * separately owned. A one-shot has no session and so no residency window — whatever is named is sent,
+ * once, and the caller's own provider limits are the only ceiling.
+ */
+async function resolveAttachments(
+  names:  readonly string[],
+  stores: ReadonlyArray<FileStore | undefined>,
+  signal: AbortSignal | undefined,
+): Promise<{ content: UserContent[]; missing: string[]; unsupported: string[] }> {
+  const content: UserContent[] = [];
+  const missing: string[] = [];
+  const unsupported: string[] = [];
+  for (const ref of names) {
+    let handle = null;
+    for (const store of stores) {
+      if (store === undefined) continue;
+      handle = await store.get(ref).catch(() => null) ?? await store.getByName(ref).catch(() => null);
+      if (handle !== null) break;
+    }
+    if (handle === null) { missing.push(ref); continue; }
+    // A type no endpoint decodes is refused, not routed to an arm that will 400 the call. Reported
+    // apart from `missing`: "no such file" would send the model hunting for a file it named correctly.
+    const arm = armFor(handle.mimeType);
+    if (arm === null) { unsupported.push(`${ref} (${handle.mimeType})`); continue; }
+    const bytes = await collectBytes(handle.stream(signal));
+    content.push({ type: arm, data: encodeBase64(bytes), mimeType: handle.mimeType as MimeType, name: handle.name });
+  }
+  return { content, missing, unsupported };
+}
+
 /**
  * Exposes {@link MatbotMachine.singleTurn} to the model: a one-shot completion against a configured
  * provider, returning its reply. The intended use is consulting another model (e.g. a different-lineage
@@ -21,7 +60,7 @@ declare module '@matatbread/matbot-plugin-api' {
 export function createSingleTurnTool(services: MatbotMachine): Tool<ToolResultOf<'single_turn'>> {
   const executor: ToolExecutor<ToolResultOf<'single_turn'>> = {
     async *execute(input: unknown, ctx: ToolContext) {
-      const args = input as { provider?: string; prompt?: string; system?: string };
+      const args = input as { provider?: string; prompt?: string; system?: string; attach?: unknown };
       if (typeof args.prompt !== 'string') { yield { type: 'error', message: 'single_turn requires a string "prompt".' }; return; }
       const provider = args.provider ?? ctx.provider;
       if (!provider) {
@@ -33,9 +72,29 @@ export function createSingleTurnTool(services: MatbotMachine): Tool<ToolResultOf
         yield { type: 'error', message: `Unknown provider "${provider}". Configured providers: ${known}.` };
         return;
       }
+      // Attachments make the prompt a UserContent[] rather than a string. Media the store doesn't have
+      // is REPORTED, not silently dropped: a consulted model answering about a file it never saw is the
+      // failure that looks like a bad answer rather than a bad call.
+      const attach = Array.isArray(args.attach) ? args.attach.filter((a): a is string => typeof a === 'string') : [];
+      let prompt: string | UserContent[] = args.prompt;
+      if (attach.length > 0) {
+        const { content, missing, unsupported } = await resolveAttachments(attach, [services.MediaStore, ctx.files], ctx.signal);
+        if (missing.length > 0) {
+          yield { type: 'error', message: `single_turn: no such file(s): ${missing.join(', ')}. Attachments are looked up by store id or by name.` };
+          return;
+        }
+        if (unsupported.length > 0) {
+          yield { type: 'error', message:
+            `single_turn: no model endpoint decodes ${unsupported.join(', ')}, so sending it would fail ` +
+            'the call. Convert it to PNG or JPEG, or read the file as text and put that in the prompt.' };
+          return;
+        }
+        prompt = [...content, { type: 'text', text: args.prompt }];
+      }
+
       const res = await services.singleTurn({
         provider,
-        prompt: args.prompt,
+        prompt,
         signal: ctx.signal,
         ...(typeof args.system === 'string' ? { system: args.system } : {}),
       });
@@ -53,7 +112,13 @@ export function createSingleTurnTool(services: MatbotMachine): Tool<ToolResultOf
       'back its text. Use it to consult a different model — e.g. a second, ' +
       'different-lineage model critiquing your draft, or any generation that should run on a specific ' +
       'provider. `provider` is OPTIONAL: omit it to run on the current conversation\'s model, or name ' +
-      'a configured provider to switch models (list or add providers with the provider tool).',
+      'a configured provider to switch models (list or add providers with the provider tool). ' +
+      '`attach` is an ARRAY OF STORED FILE NAMES OR IDS (e.g. ["chart.png"]) to send alongside the ' +
+      'prompt, for the consulted model to look at. It is not a content type and not a way to forward ' +
+      'media from THIS conversation — you can already see that; only name a file that exists in the ' +
+      'workspace or media store. Whether the consulted provider can read a given file is its business; ' +
+      'one it cannot take degrades to a text note. An image in a format no endpoint decodes (HEIC, ' +
+      'SVG, BMP, TIFF) is refused outright rather than sent — convert it first, or read it as text.',
     inputSchema: {
       type:       'object',
       required:   ['prompt'],
@@ -61,6 +126,7 @@ export function createSingleTurnTool(services: MatbotMachine): Tool<ToolResultOf
         provider: { type: 'string', description: 'Name of a configured provider to run the completion against. Optional — defaults to the current turn\'s provider.' },
         prompt:   { type: 'string', description: 'The user message to send to that provider.' },
         system:   { type: 'string', description: 'Optional system prompt for the call.' },
+        attach:   { type: 'array', items: { type: 'string' }, description: 'Optional array of stored FILE NAMES or store ids, e.g. ["diagram.png"]. Each is loaded and sent as inline media (image/document/audio) ahead of the prompt text. Not a content type — naming a file that does not exist is an error, not a request for one.' },
       },
     },
     executor,

package/src/system-context.ts

@@ -1,4 +1,4 @@
-import type { Session, SystemContextContributor, SystemContextRegistry } from './types.js';
+import type { Session, SystemContextContributor, SystemContextPart, SystemContextRegistry } from './types.js';
 
 interface TaggedContributor {
   fn:          SystemContextContributor;
@@ -18,9 +18,23 @@ export class SystemContextRegistryImpl implements SystemContextRegistry {
     }
   }
 
+  async parts(ctx: { session: Session; signal: AbortSignal }): Promise<SystemContextPart[]> {
+    // Zipped, not indexed twice. Re-reading `_contributors` after the await pairs each text with
+    // whatever now sits at that index: a plugin unloading mid-await (`removeByPlugin` splices) shifts
+    // every survivor onto its predecessor's text and drops the last one, and since `build()` derives
+    // from this, that corrupts the prompt actually sent — not merely the breakdown reported.
+    const settled = await Promise.all(
+      this._contributors.map(async c => ({ c, text: await c.fn(ctx) })));
+    return settled.flatMap(({ c, text }) =>
+      typeof text === 'string' && text.length > 0
+        ? [{ text, ...(c.pluginName !== undefined ? { plugin: c.pluginName } : {}) }]
+        : []);
+  }
+
+  // The joined form is derived from the attributed one, so the prompt the model receives and the
+  // breakdown `about_matbot` reports cannot drift: there is one traversal and one filter.
   async build(ctx: { session: Session; signal: AbortSignal }): Promise<string | null> {
-    const parts = (await Promise.all(this._contributors.map(c => c.fn(ctx))))
-      .filter((s): s is string => typeof s === 'string' && s.length > 0);
-    return parts.length > 0 ? parts.join('\n\n') : null;
+    const parts = await this.parts(ctx);
+    return parts.length > 0 ? parts.map(p => p.text).join('\n\n') : null;
   }
 }