@matatbread/matbot-core 0.4.18 → 0.4.20

package/package.json

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

package/src/assemble.ts

@@ -69,8 +69,6 @@ export interface AssembleOptions {
   providers:        ProviderRegistryImpl;
   gate:             HostGate;
   defaultSettings?: ReadonlyMap<string, Readonly<Record<string, unknown>>> | undefined;
-  /** Registry values present from boot, which an unregister reverts to rather than deleting. */
-  seed?:            Partial<MatbotServices>;
   builtinTools?:    Tool[];
   /** Resolve one `${NAME}` reference; the browser prompts for a missing secret. Defaults to the vault. */
   resolveSecret?(ref: string, vault: Vault): Promise<string>;
@@ -183,6 +181,9 @@ export function assembleMachine(opts: AssembleOptions): AssembledMachine {
   // registers its own (forwarding to its parent) over it — and unloading that reverts to refusing, which
   // is the honest answer for a job with no channel. Late-bound, as `services` is built below. It writes
   // through the shared runner, the one writer of the sessions in `services.sessions`.
+  // Not a host-supplied set: an embedder with a service of its own registers it on the returned
+  // `services` before `loaded()`, which is the same moment and one mechanism rather than two. A `seed`
+  // option existed for the node `FunctionRunner`, and went with it when that became a plugin.
   const seed: Partial<MatbotServices> = {
     MediaStore:      fileStore,
     SessionAppender: createSessionAppender({
@@ -191,7 +192,6 @@ export function assembleMachine(opts: AssembleOptions): AssembledMachine {
       notifier:   () => services.Notifier,
       isSubAgent: () => services.isSubAgent(),
     }),
-    ...opts.seed,
   };
   const serviceRegistry = new Map<string, unknown>(Object.entries(seed));
   // The validator lookup is late-bound and read per call: one is registered by a plugin long after the

package/src/config/loader.ts

@@ -21,12 +21,6 @@ export interface MatbotConfig {
    * config rather than data. A stored value always wins; `delete` reverts to the default here.
    */
   defaultSettings?:  ReadonlyMap<string, Readonly<Record<string, unknown>>>;
-  /**
-   * Longest a `tool_function` body may run synchronously — without awaiting — before it is stopped
-   * (`function_timeout_ms`). Absent ⇒ the host's default. `0` ⇒ no limit at all, for testing: bodies run
-   * directly, and a loop that never awaits freezes the process.
-   */
-  functionTimeoutMs?: number;
 }
 
 function asString(v: YamlValue | undefined, label: string): string {
@@ -144,17 +138,6 @@ export function parseConfig(
     }
   }
 
-  const functionTimeoutRaw = doc['function_timeout_ms'];
-  let functionTimeoutMs: number | undefined;
-  if (functionTimeoutRaw !== undefined && functionTimeoutRaw !== null) {
-    functionTimeoutMs = asNumber(functionTimeoutRaw, 'function_timeout_ms');
-    // Refused rather than clamped, like maxRounds: a negative or fractional limit is a typo, and `0` already
-    // means something of its own.
-    if (!Number.isInteger(functionTimeoutMs) || functionTimeoutMs < 0) {
-      throw new Error(`Config: "function_timeout_ms" must be a non-negative integer (milliseconds; 0 removes the limit), got ${functionTimeoutMs}`);
-    }
-  }
-
   const prompt           = typeof doc['prompt']            === 'string' ? doc['prompt']            : undefined;
   const ephemeral        = doc['ephemeral'] === true ? true : undefined;
   const defaultProvider  = typeof doc['default_provider'] === 'string' ? doc['default_provider']  : undefined;
@@ -168,7 +151,6 @@ export function parseConfig(
     ...(defaultProvider  !== undefined ? { defaultProvider  } : {}),
     ...(principal        !== undefined ? { principal        } : {}),
     ...(defaultSettings.size > 0       ? { defaultSettings  } : {}),
-    ...(functionTimeoutMs !== undefined ? { functionTimeoutMs } : {}),
   };
 }
 

package/src/index.ts

@@ -18,12 +18,12 @@ export type {
   MissingSecretError, IncompatibleRuntimeError, NotAPluginError, PromptCancelledError, ReadOnlyError,
   MediaRejectedError, InvalidSecretNameError, MatbotErrorKind,
 } from '@matatbread/matbot-plugin-api';
-export { applyCreateSecret, assertStorableKey, unreferenceableKey, REFERENCEABLE_KEY_RULE } from '@matatbread/matbot-plugin-api';
+export { applyResolve, applyCreateSecret, assertStorableKey, unreferenceableKey, REFERENCEABLE_KEY_RULE } from '@matatbread/matbot-plugin-api';
 // The `provider update` patch policy, alongside the vault's: written once in plugin-api so the hosts
 // that apply one cannot differ on what a patch MEANS, and re-exported here so an app needs no direct
 // plugin-api dependency to get it.
 export { applyProviderPatch, patchedFields } from '@matatbread/matbot-plugin-api';
-export { isTruncatedToolResult, notifyingStore, ItemChangeKind, RegistryChangeKind, SessionAppendKind, FUNCTION_TIMEOUT } from '@matatbread/matbot-plugin-api';
+export { isTruncatedToolResult, notifyingStore, ItemChangeKind, RegistryChangeKind, SessionAppendKind, FUNCTION_TIMEOUT, permitted, refused, refusalMessage } from '@matatbread/matbot-plugin-api';
 // The canonical `type: 'confirm'` answers. Same reason as the patch policy above: an app implementing a
 // PromptFn (or a test standing one in) has to speak them, and must not hard-code the rendered label.
 export { CONFIRM_YES, CONFIRM_NO } from '@matatbread/matbot-plugin-api';

package/src/providers-base/index.ts

@@ -1 +1,2 @@
 export { parseSSE } from './sse.js';
+export { textDocument } from './text-document.js';

package/src/providers-base/text-document.ts

@@ -0,0 +1,55 @@
+/**
+ * A text-typed `document` arm, rendered as a plain text block.
+ *
+ * Every adapter needs this and none should use its protocol's document block for it. A document block
+ * buys a title and citation support on the one endpoint that natively implements it, and is DISCARDED
+ * by the Anthropic- and OpenAI-compatible shims most vendors front their models with: DeepSeek
+ * substitutes the literal "[Unsupported Document]" server-side, so the model is told a file is attached
+ * and shown nothing — strictly worse than either sending the bytes or refusing them at the boundary.
+ * A text block is the one content shape every endpoint implements, and for text it is lossless: the
+ * model reads the same characters either way.
+ *
+ * The name is folded into the framing because the alternative is a bare CSV dump with nothing saying
+ * it is a file, which is the other half of what went wrong — a model that cannot tell content from
+ * attachment goes looking for the attachment.
+ */
+
+/**
+ * Structured-text types that are text without saying `text/`. A `+json`/`+xml` suffix (RFC 6839) is
+ * matched too, so `application/vnd.api+json` needs no entry.
+ *
+ * An unlisted type is NOT guessed at, `application/octet-stream` above all: the browser hands that over
+ * for any extension the OS could not place (`.yaml` on some installs), and sniffing it would mean
+ * deciding that binary is text on the strength of it happening to decode.
+ */
+const TEXTUAL: ReadonlySet<string> = new Set([
+  'application/json', 'application/ld+json', 'application/x-ndjson',
+  'application/xml', 'application/yaml', 'application/x-yaml',
+  'application/toml', 'application/csv', 'application/sql',
+  'application/javascript', 'application/x-javascript', 'application/ecmascript',
+  'application/x-sh', 'application/x-httpd-php', 'application/graphql',
+]);
+
+function isTextual(mimeType: string): boolean {
+  const base = mimeType.split(';')[0]!.trim().toLowerCase();
+  return base.startsWith('text/') || base.endsWith('+json') || base.endsWith('+xml') || TEXTUAL.has(base);
+}
+
+/**
+ * The text of a document arm that should be inlined as text, or null to leave the adapter's own
+ * degradation in place (a PDF, an unrecognised type, or bytes that are not valid UTF-8 — a mislabelled
+ * binary must not reach a prompt as mojibake, so the decode is `fatal`).
+ *
+ * `atob` yields one byte per char, so re-widen through TextDecoder rather than trusting it for anything
+ * outside ASCII.
+ */
+export function textDocument(doc: { mimeType: string; data: string; name?: string | undefined }): string | null {
+  if (!isTextual(doc.mimeType)) return null;
+  let text: string;
+  try {
+    text = new TextDecoder('utf-8', { fatal: true })
+      .decode(Uint8Array.from(atob(doc.data), ch => ch.charCodeAt(0)));
+  } catch { return null; }
+  const label = doc.name ?? doc.mimeType;
+  return `--- ${label} ---\n${text}\n--- end of ${label} ---`;
+}

package/src/registry.ts

@@ -60,7 +60,7 @@ async function resolveToolCollision(
 ): Promise<boolean> {
   const owner = existingOwner !== undefined ? `"${existingOwner}"` : 'a built-in';
   const label = `Tool \`"${toolName}"\` is already registered by **${owner}**. Overwrite it with the one from **"${incomingOwner}"**?`;
-  const allowed = await (services.PermissionGate ?? askPermissionGate).decide({
+  const decision = await (services.PermissionGate ?? askPermissionGate).decide({
     gate:     'tools.overwrite',
     subject:  toolName,
     // The incoming OWNER rides in the label rather than in a field of its own: a single `subject`
@@ -73,9 +73,10 @@ async function resolveToolCollision(
   // changed hands" is exactly the report this line answers. A policy that overwrites after ASKING
   // needs no warning — the user just saw the question.
   if (prompt === undefined) {
-    console.warn(`[matbot] ${label} — non-interactive, ${allowed ? 'overwriting' : 'keeping the existing tool'}.`);
+    console.warn(`[matbot] ${label} — non-interactive (${decision.source}), `
+      + `${decision.allowed ? 'overwriting' : 'keeping the existing tool'}.`);
   }
-  return allowed;
+  return decision.allowed;
 }
 
 // ── Version check ─────────────────────────────────────────────────────────────

package/src/runner.ts

@@ -5,7 +5,7 @@ import type {
   PermissionGate,
 } from './types.js';
 import type { MatbotPlugin } from './plugin.js';
-import type { ToolPresenter, SessionAppender } from '@matatbread/matbot-plugin-api';
+import type { ToolPresenter, SessionAppender, TurnToolSource } from '@matatbread/matbot-plugin-api';
 import { recordSpan, recordUsage, withUsageSite, scopeIterable } from '@matatbread/matbot-plugin-api/host';
 import { HookRegistry } from './hooks.js';
 import { appendMessage, createMessage } from './session.js';
@@ -83,6 +83,38 @@ const INTERRUPTED_TOOL_RESULT = {
   error: 'Tool call interrupted before completion — the turn was interrupted while it was running. It may not have run to completion, and any side effect may or may not have occurred. Re-run it only if you still need its result.',
 } as const;
 
+/**
+ * The turn tools `screen` offered (see {@link TurnToolSource}), as they stand for this round. Asked every
+ * round because the turn itself changes the session they are derived from. A name the registry (or the
+ * turn-start snapshot) already holds is dropped: the registered tool keeps it, since shadowing one is a
+ * gated decision and a hook must not be a way round it. `warned` keeps that to one line per name a turn.
+ * A source that throws is skipped, like a throwing hook — it must not take the turn down with it.
+ */
+async function resolveTurnTools(
+  sources:  readonly TurnToolSource[],
+  session:  Session,
+  taken:    (name: string) => boolean,
+  warned:   Set<string>,
+): Promise<Map<string, Tool>> {
+  const out = new Map<string, Tool>();
+  for (const source of sources) {
+    let offered: readonly Tool[];
+    try { offered = await source(session); }
+    catch (e) { console.warn(`[runner] a turn tool source failed: ${e instanceof Error ? e.message : String(e)}`); continue; }
+    for (const tool of offered) {
+      if (taken(tool.name)) {
+        if (!warned.has(tool.name)) {
+          warned.add(tool.name);
+          console.warn(`[runner] turn tool "${tool.name}" dropped: a registered tool has that name.`);
+        }
+        continue;
+      }
+      if (!out.has(tool.name)) out.set(tool.name, tool);
+    }
+  }
+  return out;
+}
+
 export interface RunSessionOpts {
   session:        Session;
   config:         RunConfig;
@@ -160,6 +192,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
     async createSecret() { throw new Error('No vault configured'); },
     async writeSecret()  { throw new Error('No vault configured'); },
     hasKey() { return false; },
+    async readSecret() { return undefined; },
     async resolve(ref: string) { return ref; },
     scrub(text: string) { return text; },
   };
@@ -238,6 +271,11 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
   // Returns whether anything was claimed. What the caller does with that is the part that legitimately
   // differs — proceed, abort the in-flight provider call, or re-run the loop — so it stays at the site.
   const deferred = screen.deferred;
+
+  // Re-resolved at the top of every round (below), so a tool defined in one round is callable in the next.
+  const turnToolSources = screen.tools;
+  const turnToolWarned  = new Set<string>();
+  let turnTools = new Map<string, Tool>();
   async function* claimVerdicts(): AsyncGenerator<TurnEvent, boolean, undefined> {
     if (deferred.length === 0) return false;
     const ephemeralC: MessageContent[] = [];
@@ -325,6 +363,11 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
     // discarded. This is the no-waste path — the verdict landed before we spent any tokens.
     yield* claimVerdicts();
 
+    if (turnToolSources.length > 0) {
+      turnTools = await resolveTurnTools(turnToolSources, session,
+        name => tools.has(name) || (opts.toolRegistry?.resolve(name) ?? null) !== null, turnToolWarned);
+    }
+
     const pendingCalls: Array<{ id: string; name: string; input: unknown; meta?: ProviderMeta;
       truncated?: { bytes: number; stopReason?: string } }> = [];
     const assistantParts: MessageContent[] = [];
@@ -381,10 +424,13 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
     // tools stay callable — execution resolves against the live registry (opts.toolRegistry), not this.
     // Scoped to the round: a presenter may itself run completions (deriving a tool's search terms), and
     // that spend belongs to the round that asked for it — it is neither a tool call nor a hook.
-    const advertised = opts.toolPresenter
+    // Turn tools go AFTER the presenter, never through it: they are few, made for this session, and
+    // absent from the registry a presenter's own search reads — one it windowed out could not come back.
+    const presented = opts.toolPresenter
       ? await withUsageSite({ kind: 'round', round },
           () => opts.toolPresenter!.present([...tools.values()], { session, provider: config.provider }))
       : [...tools.values()];
+    const advertised = turnTools.size > 0 ? [...presented, ...turnTools.values()] : presented;
     // Per-call signal linked to the turn signal: an in-situ restart aborts THIS provider call (callAc)
     // to cancel the in-flight request and stop backend generation, without aborting the whole turn.
     const callAc = new AbortController();
@@ -404,6 +450,9 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
           case 'thinking':
             yield { type: 'thinking', delta: ev.delta, traceId };
             break;
+          case 'progress':
+            yield { type: 'progress', pct: ev.pct, ...(ev.message !== undefined ? { message: ev.message } : {}), traceId };
+            break;
           case 'thinking-block':
             assistantParts.push({ type: 'thinking', thinking: ev.thinking, signature: ev.signature });
             break;
@@ -525,7 +574,8 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
     for (const [callIdx, tc] of pendingCalls.entries()) {
       yield { type: 'tool:start', callId: tc.id, name: tc.name, input: tc.input, traceId };
 
-      const tool = opts.toolRegistry !== undefined ? opts.toolRegistry.resolve(tc.name) : tools.get(tc.name);
+      const tool = (opts.toolRegistry !== undefined ? opts.toolRegistry.resolve(tc.name) : tools.get(tc.name))
+        ?? turnTools.get(tc.name);
       if (!tool) {
         const err = { error: `Unknown tool: ${tc.name}` };
         toolResults.push({ type: 'tool-result', id: tc.id, result: err, isError: true });
@@ -622,11 +672,12 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
         // default, so a gate handed it could never tell "no human is reachable" from "a human answered
         // with the default" — and would get the fallback back one layer too late to reason about.
         // `ToolContext.prompt` keeps the stand-in exactly as before; only the gate sees the truth.
-        ...bindGate(opts.permissionGate, tc.name, opts.prompt),
+        ...bindGate(opts.permissionGate, tool, opts.prompt, opts.toolRegistry ?? { resolve: n => tools.get(n) ?? null }),
         ...(opts.workdir     !== undefined ? { workdir:     opts.workdir     } : {}),
         ...(opts.configPath  !== undefined ? { configPath:  opts.configPath  } : {}),
         ...(opts.files       !== undefined ? { files:       opts.files       } : {}),
         ...(opts.appender    !== undefined ? { appender:    opts.appender    } : {}),
+        ...(turnTools.size   > 0         ? { turnTools                      } : {}),
       };
 
       // Iterated by hand rather than with `for await`, so the read can be bounded once the turn is

package/src/security/vault.ts

@@ -1,7 +1,6 @@
 import type { Vault } from '@matatbread/matbot-plugin-api';
-import { missingSecretError, applyCreateSecret, assertStorableKey, unreferenceableKey } from '@matatbread/matbot-plugin-api';
+import { applyResolve, applyCreateSecret, assertStorableKey, unreferenceableKey } from '@matatbread/matbot-plugin-api';
 
-const REF_RE = /\$\{([^}]+)\}/g;
 
 /**
  * Default vault implementation: a single flat namespace of secrets keyed by name.
@@ -58,19 +57,12 @@ export class VaultImpl implements Vault {
     return undefined;
   }
 
-  async resolve(ref: string): Promise<string> {
-    const errors: string[] = [];
-
-    const result = ref.replace(REF_RE, (_, name: string) => {
-      const value = this.store.get(name);
-      if (value === undefined) { errors.push(name); return ''; }
-      return value;
-    });
+  async readSecret(name: string): Promise<string | undefined> {
+    return this.store.get(name);
+  }
 
-    if (errors.length > 0) {
-      throw missingSecretError(errors);
-    }
-    return result;
+  resolve(ref: string): Promise<string> {
+    return applyResolve(this, ref);
   }
 
   scrub(text: string): string {

package/src/session-runner.ts

@@ -108,7 +108,7 @@ const DEFAULT_STEER_NUDGE: MessageContent[] = [{
 // "how's it going?" mid-task sees a history that ends a turn early and answers as though nothing were
 // running. Names the running request so the reply can be about it, and says what happens to the reply.
 const PARALLEL_FRAMING_CAP = 2_000;
-const parallelFraming = (running: string): UserContent => ({
+const parallelFraming = (running: string): Extract<UserContent, { type: 'text' }> => ({
   type: 'text',
   origin: 'robo',
   text: 'A separate turn of this conversation is still working on the request below, and you cannot see its '
@@ -118,11 +118,32 @@ const parallelFraming = (running: string): UserContent => ({
     + '\n</running-request>',
 });
 
-// A parallel turn's write-back: its submission and final reply, ready to place. Built once, when the
-// parallel turn settles; placed by whoever holds the session at that moment (see `merges`).
+// A parallel turn's span as it can be placed into shared history: trimmed back to the last point at
+// which every tool-call in it has its result. An abort (or a failure mid-round) leaves a trailing
+// tool-call with nothing answering it, and an unpaired call is not valid wire for any provider — it
+// would break not just this placement but every later turn of the session.
+const closedSpan = (msgs: Message[]): Message[] => {
+  const open = new Set<string>();
+  let closed = 0;
+  for (const [i, m] of msgs.entries()) {
+    for (const c of m.content) {
+      if (c.type === 'tool-call')        open.add(c.id);
+      else if (c.type === 'tool-result') open.delete(c.id);
+    }
+    if (open.size === 0) closed = i + 1;
+  }
+  return msgs.slice(0, closed);
+};
+
+// A parallel turn's write-back: its submission and everything the turn produced, ready to place. Built
+// once, when the parallel turn settles; placed by whoever holds the session at that moment (see
+// `merges`).
 interface ParallelReply {
   traceId:  string;
-  messages: [Message, Message];
+  /** The turn's head first, then its whole span — thinking, tool calls, their results, its markers and
+   *  its final reply. Non-empty by construction, which is what keeps `messages[0]` the head: every
+   *  placement path dedupes on that id. */
+  messages: [Message, ...Message[]];
   /** The id of the message this reply's copy was cut AT — the running turn's head when it was submitted,
    *  captured then. The pair belongs immediately ahead of it, because that is where the history the reply
    *  was generated against ended. Absent ⇒ the copy was cut at the end of the session (nothing was
@@ -881,12 +902,12 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
 
   /**
    * A parallel turn: the submission runs at once on a nested runner over a private copy of the session's
-   * completed turns, and only it and its final reply come back (`ParallelReply`). The copy ends where the
+   * completed turns, and its submission plus everything it produced come back (`ParallelReply`). The copy ends where the
    * running turn's own messages begin (`head`), plus any replies already placed into that turn but not
    * yet committed (`interjected`) — both captured at submit, before any await could outlive the turn.
    *
-   * Its events are forwarded under its own traceId as progress, never persisted: its tool calls belong to
-   * the copy, which is dropped here. A nested runner rather than `runSession` so the turn is an ordinary
+   * Its events are forwarded under its own traceId as progress; what persists is the span the write-back
+   * carries, read from the copy once the turn has settled. A nested runner rather than `runSession` so the turn is an ordinary
    * one — screen, followup, accounting, media — with nothing re-implemented.
    */
   const runParallel = async (
@@ -910,6 +931,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
       const have     = new Set(prefix.map(m => m.id));
       const copy     = { ...stored, messages: [...prefix, ...p.interjected.filter(m => !have.has(m.id))] };
       const running  = p.head?.request ?? '';
+      const framing  = running ? parallelFraming(running) : undefined;
 
       const store = new MemoryStore<Session>();
       await store.set(id, copy);
@@ -941,10 +963,21 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
       const msgs   = final?.messages ?? [];
       const hIdx   = msgs.findIndex(m => m.role === 'user' && m.traceId === p.traceId);
       const qHead  = msgs[hIdx];
-      // Only the reply's text crosses back: its tool calls stay in the copy (an unpaired one would break
-      // every later turn), and its thinking was signed against a history that included those tool rounds.
-      const last   = hIdx >= 0 ? msgs.slice(hIdx + 1).findLast(m => m.role === 'assistant') : undefined;
-      const answer = (last?.content ?? []).filter(c => c.type === 'text');
+      // The turn's WHOLE span crosses back, not just its final text: thinking, tool calls, their results
+      // and any markers. A history holding only the answer makes everything a parallel turn actually did
+      // unrecoverable the moment the live stream is gone — `determine_provenance` reads a real tool result
+      // as fabricated, and so does a person scrolling back. The span is placed exactly where the copy was
+      // cut, so it sits in the history it was generated against, and `closedSpan` is what keeps it valid
+      // wire. Thinking rides along persisted but unsubmitted (every adapter elides a historical block),
+      // and a foreign round-trip token is the adapters' to drop by `providerName`, which these messages
+      // carry — so nothing here depends on which provider ran the turn.
+      const span   = hIdx >= 0 ? closedSpan(msgs.slice(hIdx + 1)) : [];
+      // Answered iff the span ENDS with assistant text. Not "contains some": a turn aborted after
+      // "let me check that" has said nothing, and a span ending on a tool result needs the note after it
+      // to close the turn on an assistant message.
+      const tail   = span[span.length - 1];
+      const answer = tail?.role === 'assistant'
+        ? tail.content.filter(c => c.type === 'text' && c.text.trim() !== '') : [];
       const ended  = rec.replay.findLast(e => e.type === 'done' || e.type === 'aborted' || e.type === 'error' || e.type === 'cancelled');
       const reason = ended?.type === 'aborted' ? `was stopped (${ended.reason})`
                    : ended?.type === 'cancelled' ? 'was stopped before it started'
@@ -954,14 +987,19 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
         traceId:  p.traceId,
         ...(p.head !== undefined ? { head: p.head.id } : {}),
         messages: [
-          // The copy's own head, carrying its accounting, but with the content as the person submitted it.
+          // The copy's own head, carrying its accounting, with the framing block taken back OFF — that
+          // block is this turn's own context and not something the person wrote. Subtracted rather than
+          // replaced with `p.content` wholesale: a `contextual` trigger folds its correction DURABLY onto
+          // the head, and overwriting the content dropped exactly that, so the correction informed the
+          // answer and then vanished from the history the answer sits in.
           qHead !== undefined
-            ? { ...qHead, content: p.content }
+            ? { ...qHead, content: qHead.content.filter(c => !(framing !== undefined && c.type === 'text'
+                && c.origin === framing.origin && c.text === framing.text)) }
             : createMessage({ role: 'user', content: p.content, traceId: p.traceId, providerName: p.provider }),
-          last !== undefined && answer.length > 0
-            ? { ...last, content: answer }
-            : createMessage({ role: 'assistant', content: [{ type: 'text', text: `(No reply — this message's parallel turn ${reason}.)` }],
-                traceId: p.traceId, providerName: p.provider }),
+          ...span,
+          ...(answer.length > 0 ? [] : [createMessage({
+            role: 'assistant', content: [{ type: 'text', text: `(No reply — this message's parallel turn ${reason}.)` }],
+            traceId: p.traceId, providerName: p.provider })]),
         ],
       };
     } catch (e) {