@matatbread/matbot-core 0.4.17 → 0.4.19

package/package.json

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

package/src/assemble.ts

@@ -1,6 +1,6 @@
 import type {
   MatbotMachine, MatbotServices, MatbotPlugin, Store, Session, FileStore, StorageBackend, Vault, Notifier,
-  KnowledgeIndex, PermissionGate, PluginSettings, ProviderConfig, ProviderAdapter, SessionRunner, Tool, Usage,
+  KnowledgeIndex, PermissionGate, PluginSettings, ProviderConfig, ProviderAdapter, SessionRunner, SessionAppender, Tool, Usage,
 } from '@matatbread/matbot-plugin-api';
 import {
   forwardingProxy, makeSwappable, createMountTable, scheduleAtEdge, createNotifier, recordUsage, singleTurnRequest,
@@ -9,6 +9,7 @@ import {
 import type { SwapFn } from '@matatbread/matbot-plugin-api/host';
 import { notifyingStore, createMessage } from '@matatbread/matbot-plugin-api';
 import { mediumGuard } from './storage-base/medium-guard.js';
+import { MemoryStore } from './storage-base/memory-store.js';
 import { unifyServices } from './plugin.js';
 import { instantiateProvider, recordServiceKey, getPluginNameForSpecifier, getRegisteredPlugins } from './registry.js';
 import { installSettingsDefaults, installSettingsNotifier, makePluginSettings, settingsDefaultNamespaces } from './settings.js';
@@ -19,6 +20,7 @@ import type { ProviderRegistryImpl } from './provider-registry.js';
 import { SystemContextRegistryImpl } from './system-context.js';
 import { LookupKnowledgeIndex } from './knowledge/index.js';
 import { createSessionRunner } from './session-runner.js';
+import { createSessionAppender } from './session-append.js';
 import { createSingleTurnTool } from './single-turn.js';
 import { createAboutMatbotTool } from './about.js';
 import { addUsage } from './usage.js';
@@ -81,7 +83,7 @@ export interface AssembleOptions {
 export interface AssembledMachine {
   services: MatbotMachine;
   /** A session runner over any store — the shared one is `services.run`. */
-  makeRunner(store: Store<Session>): SessionRunner;
+  makeRunner(store: Store<Session>, opts?: { appender?: SessionAppender }): SessionRunner;
   /** Call once the configured plugins have loaded. */
   loaded(): void;
 }
@@ -176,7 +178,21 @@ export function assembleMachine(opts: AssembleOptions): AssembledMachine {
   // The host's file area doubles as the media store, so attachments work with no plugin. Seeded into the
   // registry rather than spelled on the base object, because `unifyServices` resolves an own property
   // first — a member spelled there is one `register()` could never reach.
-  const seed: Partial<MatbotServices> = { MediaStore: fileStore, ...opts.seed };
+  //
+  // The session appender is seeded the same way, in every process: it refuses in a background job, which
+  // 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`.
+  const seed: Partial<MatbotServices> = {
+    MediaStore:      fileStore,
+    SessionAppender: createSessionAppender({
+      sessions:   () => services.sessions,
+      run:        () => services.run,
+      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
   // builtins are seeded, and may be unloaded again. It wraps the executor, so every door — the runner,
@@ -306,6 +322,10 @@ export function assembleMachine(opts: AssembleOptions): AssembledMachine {
     sessions,
     files:    fileStore,
     get run() { return runner; },
+    ephemeral(opts) {
+      const store = new MemoryStore<Session>();
+      return { sessions: store, run: makeRunner(store, opts) };
+    },
     hooks,
     tools,
     systemContext,
@@ -328,8 +348,9 @@ export function assembleMachine(opts: AssembleOptions): AssembledMachine {
   };
 
   // Services a plugin registers after boot are resolved live, per turn.
-  const makeRunner = (store: Store<Session>): SessionRunner => createSessionRunner({
+  const makeRunner = (store: Store<Session>, extra?: { appender?: SessionAppender }): SessionRunner => createSessionRunner({
     store,
+    ...(extra?.appender !== undefined ? { appender: extra.appender } : {}),
     resolveProvider,
     tools,
     hooks,

package/src/ephemeral-turn.ts

@@ -0,0 +1,67 @@
+import type { EphemeralRun, PipelineEvent, Principal, PromptFn, Session, UserContent } from '@matatbread/matbot-plugin-api';
+
+/**
+ * One turn on an ephemeral run, from a fresh session to its committed transcript: what a background job
+ * and a skill demonstration each do, and each did for itself.
+ *
+ * Yields the turn's own events, up to and including its terminal, and returns the transcript.
+ *
+ * Three details are why this is shared rather than rewritten:
+ * - `signal` is wired to the run's `abort`. On `open` it only ends this view of the session, while the
+ *   turn runs on the runner's own controller. Without the wiring, a cancelled job or compile left its
+ *   turn calling tools after its caller had gone.
+ * - A caller that stops reading before the terminal aborts the turn for the same reason.
+ * - So does reaching the terminal, which is NOT the end of the run: `followup` is post-commit, so a hook
+ *   that resubmits or retracts enqueues a further turn on this runner AFTER the terminal this returns on.
+ *   Left armed, it ran on unobserved — calling tools, and appending through the run's appender — past the
+ *   transcript its caller was handed and past a cancel that no longer reached it. One turn means one.
+ * - An `error` terminal carries no session, so the transcript is then recovered from the run's store.
+ *
+ * `sessionId` is for a caller that names the session before the turn starts, to log or check it.
+ */
+export async function* runEphemeralTurn(
+  ephemeral: EphemeralRun,
+  opts: {
+    content:    UserContent[];
+    provider:   string;
+    principal:  Principal;
+    signal:     AbortSignal;
+    prompt?:    PromptFn;
+    sessionId?: string;
+  },
+): AsyncGenerator<PipelineEvent, Session | undefined> {
+  const now = new Date().toISOString();
+  const id  = opts.sessionId ?? crypto.randomUUID();
+  await ephemeral.sessions.set(id, { id, version: crypto.randomUUID(), status: 'active', messages: [], createdAt: now, updatedAt: now });
+
+  const view = await ephemeral.run.open({
+    sessionId: id, signal: opts.signal, provider: opts.provider, principal: opts.principal, content: opts.content,
+    ...(opts.prompt !== undefined ? { prompt: opts.prompt } : {}),
+  });
+  const stop = (): void => { ephemeral.run.abort(id); };
+  opts.signal.addEventListener('abort', stop, { once: true });
+  if (opts.signal.aborted) stop();
+
+  let final: Session | undefined;
+  try {
+    for await (const ev of view.events) {
+      // To `idle` — the run quiescing — not to this turn's terminal. `followup` is post-commit, so a hook
+      // that resubmits or retracts enqueues a FURTHER turn on this runner after the terminal, and stopping
+      // at the terminal left it running with nobody watching: appending through the run's appender, calling
+      // tools, past the transcript the caller was handed and past a cancel that no longer reached it.
+      // Aborting at the terminal does not close that either — the pop happens before the hook enqueues, so
+      // the resubmission is queued after the drain and runs anyway. Waiting is what makes the run's work
+      // the caller's: bounded by MAX_RESUBMIT_DEPTH, cancellable throughout, and counted.
+      if (ev.type === 'idle') break;
+      if (!('traceId' in ev) || ev.traceId !== view.traceId) continue;
+      if (ev.type === 'done' || ev.type === 'aborted') final = ev.session;
+      yield ev;
+    }
+  } finally {
+    opts.signal.removeEventListener('abort', stop);
+    stop();
+  }
+  // The store, not the terminal's session: a followup turn commits after it, and the transcript is meant to
+  // be everything the run did. `final` covers a store that has gone from under it.
+  return (await ephemeral.sessions.get(id)) ?? final;
+}

package/src/index.ts

@@ -23,7 +23,7 @@ export { applyCreateSecret, assertStorableKey, unreferenceableKey, REFERENCEABLE
 // 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, FUNCTION_TIMEOUT } from '@matatbread/matbot-plugin-api';
+export { isTruncatedToolResult, notifyingStore, ItemChangeKind, RegistryChangeKind, SessionAppendKind, FUNCTION_TIMEOUT } 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';
@@ -57,6 +57,8 @@ export * from './usage.js';
 export * from './hooks.js';
 export * from './runner.js';
 export * from './session-runner.js';
+export * from './session-append.js';
+export * from './ephemeral-turn.js';
 export * from './plugin.js';
 export * from './registry.js';
 export * from './settings.js';

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/runner.ts

@@ -5,7 +5,7 @@ import type {
   PermissionGate,
 } from './types.js';
 import type { MatbotPlugin } from './plugin.js';
-import type { ToolPresenter } 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;
@@ -115,6 +147,9 @@ export interface RunSessionOpts {
   workdir?:       string;
   configPath?:    string;
   files?:         FileStore;
+  /** Handed to tools as `ToolContext.appender`: set only by a runner whose sessions the machine's own
+   *  appender cannot reach (an ephemeral one). */
+  appender?:      SessionAppender;
   /** 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. */
@@ -133,6 +168,13 @@ export interface RunSessionOpts {
    * re-run of the originating user turn. Empty/absent for an ordinary turn.
    */
   injectedEphemeral?: MessageContent[];
+  /**
+   * Consulted at the top of every round — the one point in a turn where the history is protocol-whole:
+   * every `tool_use` so far is answered, and no provider call is in flight. Returns the session with
+   * messages from outside the turn placed into it (the pump's parallel replies), and the traceIds to
+   * announce as `merged`; `undefined` ⇒ nothing arrived. Where they go is the caller's decision.
+   */
+  interject?:     (session: Session) => { session: Session; merged: string[] } | undefined;
   loadPlugin:     (specifier: string, prompt?: PromptFn, refresh?: boolean) => Promise<MatbotPlugin>;
   unloadPlugin:   (specifier: string) => Promise<boolean>;
 }
@@ -165,7 +207,15 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
   // Nothing is written mid-turn, so "commit" here means the whole turn or none of it.
   // Closes over the reassigned `session` deliberately, so no exit can commit a stale copy.
   async function* end(terminal: TurnEvent): AsyncIterable<TurnEvent> {
+    // One last pull, because this is the funnel every exit passes through. A parallel reply that settled
+    // since the previous round boundary may already be in the store (the session runner places one as it
+    // settles, so a turn parked in a long tool call does not hide it) — and the write below is the whole
+    // document, so a reply this turn never took would be erased by it. Reachable: a turn aborted or
+    // thrown during that same tool call never reaches another round top.
+    const late = opts.interject?.(session);
+    if (late !== undefined) session = late.session;
     await store.set(session.id, session);
+    if (late !== undefined) for (const from of late.merged) yield { type: 'merged', traceId: from, into: traceId };
     yield terminal;
   }
 
@@ -220,6 +270,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[] = [];
@@ -296,11 +351,22 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
     }
     round += 1;
 
+    const interjected = opts.interject?.(session);
+    if (interjected !== undefined) {
+      session = interjected.session;
+      for (const from of interjected.merged) yield { type: 'merged', traceId: from, into: traceId };
+    }
+
     // A raced screen verdict that already fired (settled during setup, or while a previous tool round
     // ran): fold its correction in before generating, so this call is informed directly rather than
     // 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[] = [];
@@ -357,10 +423,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();
@@ -501,7 +570,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 });
@@ -602,6 +672,8 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
         ...(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/session-append.ts

@@ -0,0 +1,77 @@
+import type { AppendMessage, AppendResult, Notifier, Session, SessionAppender, SessionRunner, Store } from './types.js';
+import { tryCurrentPrincipal, isReadOnlyError, SessionAppendKind } from '@matatbread/matbot-plugin-api';
+import { appendMessage, createMessage } from './session.js';
+
+/**
+ * The host's {@link SessionAppender}: an append is checked now, and written by the session's runner once no
+ * turn holds the session (`SessionRunner.write`).
+ *
+ * Checked now so that a session that does not exist is reported to a caller who can still act on it. When
+ * no turn holds the session the write runs at once and the append settles once it has, so a write that
+ * cannot land (the session went, or it is shared in read-only) is reported too. When a turn holds it, the
+ * append settles on acceptance: the caller may be that very turn, which the write is waiting for.
+ *
+ * Seeded in every process, and refuses in a background job — whose store is the parent's medium with none
+ * of the parent's turns behind it — until the job registers one that forwards to its parent.
+ */
+export function createSessionAppender(deps: {
+  sessions:   () => Store<Session> | undefined;
+  run:        () => SessionRunner | undefined;
+  notifier:   () => Notifier;
+  isSubAgent: () => boolean;
+}): SessionAppender {
+  return {
+    async append(sessionId, messages): Promise<AppendResult> {
+      if (deps.isSubAgent()) {
+        throw new Error('This background job has no way to reach its parent\'s sessions, so it cannot append to one.');
+      }
+      if (sessionId === undefined) throw new Error('No session was named to append to.');
+      if (messages.length === 0) throw new Error('Nothing to append.');
+      const store = deps.sessions();
+      if (store === undefined) throw new Error('No session store is available.');
+      const run = deps.run();
+      if (run === undefined) throw new Error('No session runner is available to write the session.');
+      if (await store.get(sessionId) === null) throw new Error(`Session "${sessionId}" not found.`);
+
+      const principal = tryCurrentPrincipal();
+      const traceId   = crypto.randomUUID();
+      const built     = messages.map((m: AppendMessage) => createMessage({
+        role: m.role, content: m.content, traceId,
+        ...(m.metadata !== undefined ? { metadata: m.metadata } : {}),
+      }));
+      const messageIds = built.map(m => m.id);
+
+      let landed = false;
+      let dropped: string | undefined;
+      const write = run.write(sessionId, async () => {
+        const current = await store.get(sessionId);
+        if (current === null) {
+          dropped = `Session "${sessionId}" no longer exists.`;
+          console.error(`[matbot] append to session "${sessionId}" dropped: the session no longer exists.`);
+          return true;
+        }
+        try {
+          if (!(await store.cas(sessionId, current.version, built.reduce(appendMessage, current))).ok) return false;
+        } catch (e) {
+          // Readable, so accepted; not writable — a session shared in read-only.
+          if (!isReadOnlyError(e)) throw e;
+          dropped = e.message;
+          console.error(`[matbot] append to session "${sessionId}" dropped: ${e.message}`);
+          return true;
+        }
+        deps.notifier().notify({
+          kind: SessionAppendKind, source: 'append', sessionId, messageIds,
+          ...(principal !== undefined ? { principal } : {}),
+        });
+        landed = true;
+        return true;
+      }, `[matbot] append to session "${sessionId}" lost to repeated concurrent writes.`);
+
+      if (!write.deferred) {
+        await write.done;
+        if (!landed) throw new Error(`The append was not written: ${dropped ?? 'it failed, or lost to repeated concurrent writes (see the log).'}`);
+      }
+      return { sessionId, messageIds, ...(write.deferred ? { deferred: true as const } : {}) };
+    },
+  };
+}