@matatbread/matbot-core 0.3.7 → 0.4.0

package/package.json

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

package/src/config/loader.ts

@@ -26,6 +26,11 @@ function asRecord(v: YamlValue | undefined, label: string): YamlMap {
   throw new Error(`Config: expected mapping for "${label}", got ${v === undefined ? 'undefined' : typeof v}`);
 }
 
+function asNumber(v: YamlValue | undefined, label: string): number {
+  if (typeof v === 'number' && Number.isFinite(v)) return v;
+  throw new Error(`Config: expected number for "${label}", got ${v === undefined ? 'undefined' : typeof v}`);
+}
+
 function toModelParameters(raw: YamlMap): ModelParameters {
   const params: ModelParameters = {};
   for (const [k, v] of Object.entries(raw)) {
@@ -52,8 +57,14 @@ function toProviderConfig(name: string, raw: YamlMap): ProviderConfig {
   if (raw['endpoint'] !== undefined) {
     config.endpoint = asString(raw['endpoint'], `providers.${name}.endpoint`);
   }
-  if (raw['fallback'] !== undefined) {
-    config.fallback = asString(raw['fallback'], `providers.${name}.fallback`);
+  if (raw['maxRounds'] !== undefined) {
+    const rounds = asNumber(raw['maxRounds'], `providers.${name}.maxRounds`);
+    // Rejected at the boundary rather than clamped: 0 or a fraction is a typo, and silently treating it
+    // as "no turn may do anything" would look like the provider was broken.
+    if (!Number.isInteger(rounds) || rounds < 1) {
+      throw new Error(`Config: "providers.${name}.maxRounds" must be a positive integer, got ${rounds}`);
+    }
+    config.maxRounds = rounds;
   }
   if (raw['parameters'] !== undefined) {
     config.parameters = toModelParameters(asRecord(raw['parameters'], `providers.${name}.parameters`));

package/src/hooks.ts

@@ -1 +1 @@
-export { HookRegistry } from '@matatbread/matbot-plugin-api';
+export { HookRegistry } from '@matatbread/matbot-plugin-api/host';

package/src/index.ts

@@ -2,32 +2,38 @@ export type * from './types.js';
 // matbot's typed errors are duck-typed: factory `xError()` builders + `isXError()` brand guards are
 // runtime values (re-exported here, since the `export type *` above would strip their value meaning),
 // while the `XError` shapes are types (re-exported below). StoreQueryError is still a class value.
+// Every branded error, uniformly: a partial list meant a consumer importing from core got some guards and
+// silently missed others (readOnlyError/isReadOnlyError were absent, though the pump depends on the guard).
 export {
   missingSecretError, isMissingSecretError,
   incompatibleRuntimeError, isIncompatibleRuntimeError,
   notAPluginError, isNotAPluginError,
   promptCancelledError, isPromptCancelledError,
+  readOnlyError, isReadOnlyError,
   StoreQueryError,
 } from '@matatbread/matbot-plugin-api';
 export type {
-  MissingSecretError, IncompatibleRuntimeError, NotAPluginError, PromptCancelledError, MatbotErrorKind,
+  MissingSecretError, IncompatibleRuntimeError, NotAPluginError, PromptCancelledError, ReadOnlyError,
+  MatbotErrorKind,
 } from '@matatbread/matbot-plugin-api';
 export { applyCreateSecret }  from '@matatbread/matbot-plugin-api';
-// unifyServices is a runtime fn; the `export type *` above would otherwise strip its value meaning.
-export { unifyServices }      from '@matatbread/matbot-plugin-api';
-// Same: pure runtime helpers that would otherwise be stripped to type-only by `export type *`.
-export { forwardingProxy, makeSwappable, singleTurnRequest, createMountTable } from '@matatbread/matbot-plugin-api';
-// Observation-stream primitives (broadcaster + the bare-subscribe wrapper); the host wires `mounted`.
-export { createBroadcaster, subscribable } from '@matatbread/matbot-plugin-api';
-export type { Subscribable, Broadcaster } from '@matatbread/matbot-plugin-api';
-// Ambient security principal: interface is a type (carried by `export type *`); these are the values.
+export { isTruncatedToolResult, notifyingStore, ItemChangeKind, RegistryChangeKind } from '@matatbread/matbot-plugin-api';
+// Ambient security principal: the interface is a type (carried by `export type *`); these are the values.
+export { currentPrincipal, tryCurrentPrincipal, runAs, lastActivityAt } from '@matatbread/matbot-plugin-api';
+// Host boot assembly, from plugin-api's `/host` subpath. An embedding app gets these through core and
+// needs no direct dependency on plugin-api; a *plugin* has no business with any of them, which is why
+// they are not on the plugin-api root. Re-exported here (not `export type *`ed) so their value meaning
+// survives.
 export {
-  installPrincipalCarrier, currentPrincipal, tryCurrentPrincipal,
-  runAs, enterPrincipal, createConstantPrincipalCarrier,
+  unifyServices, forwardingProxy, makeSwappable, singleTurnRequest, createMountTable,
+  createBroadcaster, subscribable, createNotifier, scopedNotifier,
+  installPrincipalCarrier, enterPrincipal, createConstantPrincipalCarrier,
   contextSwitch, onContextQuiesce, flushIfQuiescent,
   installUsageCarrier, createSerialUsageCarrier, recordUsage, currentUsageSink, withUsageScope,
-  lastActivityAt,
-} from '@matatbread/matbot-plugin-api';
+} from '@matatbread/matbot-plugin-api/host';
+export type {
+  Subscribable, Broadcaster, Routed, RoutedFilter, SwapFn, MountTable, PrincipalCarrier, UsageCarrier,
+} from '@matatbread/matbot-plugin-api/host';
 export * from './session.js';
 export * from './usage.js';
 export * from './hooks.js';

package/src/loader.ts

@@ -1,7 +1,7 @@
 import type { MatbotPlugin, MatbotPluginSpec, MatbotMachine, PluginSource, Runtime } from './plugin.js';
 import type { PromptFn } from './types.js';
 import { incompatibleRuntimeError, notAPluginError } from '@matatbread/matbot-plugin-api';
-import { registerPlugin, setupPlugin, unloadPlugin, recordFailedPlugin, clearFailedPlugin } from './registry.js';
+import { registerPlugin, setupPlugin, unloadPlugin, recordFailedPlugin, clearFailedPlugin, announcePluginLoaded } from './registry.js';
 
 /**
  * The runtime this process is executing in. Detected the same way the rejected-import branch below
@@ -235,6 +235,9 @@ export async function loadPlugins(
     try {
       registerPlugin(plugin);
       registered = true;
+      // Announced at registration, not after setup: a setup throw rolls back through unloadPlugin, which
+      // announces the removal — so an observer sees a matched add/remove pair rather than a bare removal.
+      announcePluginLoaded(services, plugin.name);
       await setupPlugin(plugin, services, prompt);
       loaded.push(plugin);
       // Successful (re)load: a fixed plugin drops off the failed list (reload runs this same path).

package/src/plugin.ts

@@ -1 +1,5 @@
+// Core's view of the plugin API is the whole of it: core *is* a host, so it needs the boot-assembly
+// half (`/host`) as well as the author-facing root. Everything reached through this module is therefore
+// available to core internals and, via core's index, to an embedding app.
 export * from '@matatbread/matbot-plugin-api';
+export * from '@matatbread/matbot-plugin-api/host';

package/src/registry.ts

@@ -1,11 +1,11 @@
-import type { Tool, ToolRegistry, Hook, PromptFn, FormField, FrontendInfo, PluginRegistryEvent, ProviderAdapter, ProviderConfig } from './types.js';
-import { createBroadcaster } from '@matatbread/matbot-plugin-api';
+import type { Tool, ToolRegistry, Hook, PromptFn, FormField, FrontendInfo, ProviderAdapter, ProviderConfig } from './types.js';
+import { RegistryChangeKind } from '@matatbread/matbot-plugin-api';
+import { scopedNotifier } from '@matatbread/matbot-plugin-api/host';
 import type {
   MatbotPlugin, MatbotMachine, MatbotRuntime, Mounted,
   ProviderAdapterFactory, StoreFactory,
 } from './plugin.js';
 import { PLUGIN_API_VERSION, unifyServices } from './plugin.js';
-import { HookRegistry } from './hooks.js';
 import { makePluginSettings } from './settings.js';
 import type { SettingsDoc } from './settings.js';
 
@@ -30,18 +30,18 @@ const state = {
   serviceKeys:     new Map<string, string[]>(),  // pluginName → MatbotMachine keys it registered
   hookPlugins:        new Set<string>(),         // plugins that registered at least one hook
   systemContextPlugins: new Set<string>(),       // plugins that registered a system-context contributor
+  lifecycles:      new Map<string, AbortController>(),  // pluginName → "this plugin is loaded" signal, aborted on unload
   failedPlugins:   [] as FailedPlugin[],         // plugins the loader skipped, keyed by specifier (last failure wins)
   overwriteAllTools: undefined as boolean | undefined,  // persisted "overwrite on collision, this install" choice, loaded lazily
 };
 
-// Read-only observation of plugin load/unload, for consumers that key off plugin presence (e.g. the
-// web plugins panel refreshing live when a backend restores a plugin set out of band). Module-level,
-// not in `state` — it owns subscribers across the registry's lifetime, not per-plugin data.
-const pluginEvents = createBroadcaster<PluginRegistryEvent>();
-
-export async function* watchPlugins(signal?: AbortSignal): AsyncIterable<PluginRegistryEvent> {
-  // Plugin CRUD is global — no origin — so unwrap the envelope to the bare event the panel expects.
-  for await (const { value } of pluginEvents.subscribe(signal)) yield value;
+// Plugin load/unload is announced on the Notifier as a `RegistryChange` with `registry: 'plugins'`, for
+// consumers that key off plugin presence (e.g. the web plugins panel refreshing live when a backend
+// restores a plugin set out of band). It was a module-level broadcaster of its own, which is the same
+// primitive the bus already is. `loaded` is announced by the loader — the only caller of
+// registerPlugin, and the one place holding the machine this registry deliberately doesn't.
+export function announcePluginLoaded(services: MatbotMachine, name: string): void {
+  services.Notifier.notify({ kind: RegistryChangeKind, source: 'plugins', registry: 'plugins', name, operation: 'added' });
 }
 
 // Settings namespace + key under which the user's "overwrite all colliding tools" choice
@@ -150,8 +150,6 @@ export function registerPlugin(plugin: MatbotPlugin): void {
   for (const [type, factory] of Object.entries(plugin.storage ?? {})) {
     state.storage.set(type, factory);
   }
-
-  pluginEvents.emit({ type: 'loaded', name: plugin.name });
 }
 
 // ── Resolution ────────────────────────────────────────────────────────────────
@@ -288,16 +286,43 @@ export function getSpecifierForPlugin(pluginName: string): string | undefined {
 export async function setupPlugin(plugin: MatbotPlugin, services: MatbotMachine, prompt?: PromptFn): Promise<void> {
   state.toolRegistry ??= services.tools;
 
+  // This plugin's load extent. The mount table's only cleanup path is an aborted signal, and the
+  // option is optional — so an author who omits it left an interest that outlives the unload and
+  // keeps firing into a torn-down closure (once per reload generation). Ownership is the host's to
+  // know, not the author's to remember: every scoped observe() is bound to this signal, so `signal`
+  // in the options is a narrowing convenience ("stop earlier than my unload"), never load-bearing.
+  const previous = state.lifecycles.get(plugin.name);
+  previous?.abort();                                  // a reload that skipped unloadPlugin
+  const lifecycle = new AbortController();
+  state.lifecycles.set(plugin.name, lifecycle);
+
   // Single choke point for every plugin tool registration (static `plugin.tools` and in-setup
   // `services.tools.register`). Stamps ownership and resolves name collisions. The no-collision
   // path runs synchronously (an async fn yields nothing before its first await), so fire-and-forget
-  // callers that don't await still get the tool registered in the same tick.
+  // callers that don't await still get the tool registered in the same tick — which is the whole
+  // reason `ToolRegistry.register` returns `void`, and every one of its ~34 call sites relies on it.
+  //
+  // That makes the collision branch the one place with an await and no caller to own its outcome, so
+  // it owns its own: a throw from the settings read/write or the prompt (a non-interactive `PromptFn`
+  // rejects with PromptCancelledError) would otherwise be an unhandled rejection — process exit under
+  // Node's default — reached by the ordinary act of two plugins claiming one tool name. Keep-existing
+  // is the safe resolution, so a failure resolves to it. The abort check closes the other end: setup()
+  // has already returned by the time a slow collision resolves, so an unload (or a setup() throw and
+  // its rollback) can land first, and re-inserting the tool would revive one owned by a gone plugin.
   const registerTool = async (tool: Tool): Promise<void> => {
     const stamped: Tool = { ...tool, pluginName: plugin.name };
     const existing = services.tools.resolve(stamped.name);
     if (existing !== null && existing.pluginName !== plugin.name) {
-      const overwrite = await resolveToolCollision(services, stamped.name, existing.pluginName, plugin.name, prompt);
+      const overwrite = await resolveToolCollision(services, stamped.name, existing.pluginName, plugin.name, prompt)
+        .catch((e: unknown) => {
+          console.error(
+            `[matbot] Could not resolve the "${stamped.name}" tool collision for plugin "${plugin.name}" ` +
+            `— keeping the existing tool:`, e instanceof Error ? e.message : e,
+          );
+          return false;
+        });
       if (!overwrite) return;
+      if (lifecycle.signal.aborted) return;
     }
     services.tools.register(stamped);
   };
@@ -315,9 +340,11 @@ export async function setupPlugin(plugin: MatbotPlugin, services: MatbotMachine,
     observe(options, handler) {
       // Forward to the host mount table but deliver *this plugin's* scoped machine — it reads through
       // the same proxies/registry, so scoped[key] is the host's live service. onUnmount is scoped too.
-      const forwarded = options.onUnmount !== undefined
-        ? { ...options, onUnmount: () => options.onUnmount!(scoped) }
-        : options;
+      const forwarded = {
+        ...options,
+        signal: options.signal !== undefined ? AbortSignal.any([lifecycle.signal, options.signal]) : lifecycle.signal,
+        ...(options.onUnmount !== undefined ? { onUnmount: () => options.onUnmount!(scoped) } : {}),
+      };
       services.mounted.observe(forwarded, () => handler(scoped as never));
     },
   };
@@ -331,13 +358,16 @@ export async function setupPlugin(plugin: MatbotPlugin, services: MatbotMachine,
       specifier: plugin.specifier,
       ...(plugin.source !== undefined ? { source: plugin.source } : {}),
     },
+    // Everything this plugin publishes is attributed to it by default — the notification analogue of
+    // stamping `pluginName` on its tools. Reads through the host's swap proxy, so a registered
+    // distributed Notifier takes effect for a plugin that captured this in setup().
+    get Notifier() { return scopedNotifier(services.Notifier, plugin.name); },
     tools: {
       register:      registerTool,
       remove:        (name: string) => services.tools.remove(name),
       resolve:       (name: string) => services.tools.resolve(name),
       list:          ()             => services.tools.list(),
       removeByPlugin:(name: string) => services.tools.removeByPlugin(name),
-      watch:         (signal?: AbortSignal) => services.tools.watch(signal),
     },
     hooks: {
       register(hook: Hook) {
@@ -345,7 +375,7 @@ export async function setupPlugin(plugin: MatbotPlugin, services: MatbotMachine,
         services.hooks.register({ ...hook, pluginName: plugin.name } as Hook);
       },
       removeByPlugin: (name: string) => services.hooks.removeByPlugin(name),
-    } as unknown as HookRegistry,
+    },
     systemContext: {
       register(contributor) {
         state.systemContextPlugins.add(plugin.name);
@@ -382,6 +412,10 @@ export async function unloadPlugin(pluginName: string, services: MatbotMachine):
   services.tools.removeByPlugin(pluginName);
   services.hooks.removeByPlugin(pluginName);
   services.systemContext.removeByPlugin(pluginName);
+  // Drops this plugin's mount interests. Before teardown(), with the other synchronous removals: a
+  // mount handler firing between here and teardown would run against half-removed state.
+  state.lifecycles.get(pluginName)?.abort();
+  state.lifecycles.delete(pluginName);
 
   for (const key of state.serviceKeys.get(pluginName) ?? []) {
     services.unregister(key);
@@ -396,7 +430,7 @@ export async function unloadPlugin(pluginName: string, services: MatbotMachine):
   state.frontendPlugins.delete(pluginName);
 
   state.plugins.splice(idx, 1);
-  pluginEvents.emit({ type: 'unloaded', name: pluginName });
+  services.Notifier.notify({ kind: RegistryChangeKind, source: 'plugins', registry: 'plugins', name: pluginName, operation: 'removed' });
   await Promise.race([
     plugin.teardown?.(),
     new Promise<void>((_, reject) => setTimeout(() => reject(new Error(`Teardown timeout for plugin ${pluginName}`)), 10000))
@@ -406,10 +440,13 @@ export async function unloadPlugin(pluginName: string, services: MatbotMachine):
 
 /** Run each plugin's teardown() in reverse-registration order. Errors are logged, not thrown. */
 export async function teardownPlugins(): Promise<void> {
-  const results = await Promise.allSettled([...state.plugins].reverse().map(plugin => plugin.teardown?.()));
+  // Reverse once and keep it: indexing the *unreversed* array to name a result reported the wrong
+  // plugin for every failure but the middle one.
+  const ordered = [...state.plugins].reverse();
+  const results = await Promise.allSettled(ordered.map(plugin => plugin.teardown?.()));
   results.forEach((result, i) => {
     if (result.status === 'rejected') {
-      console.error(`[matbot] teardown error in plugin "${state.plugins[i]?.name}":`, result.reason);
+      console.error(`[matbot] teardown error in plugin "${ordered[i]?.name}":`, result.reason);
     }
   });
 }

package/src/runner.ts

@@ -1,13 +1,14 @@
 import type {
-  Session, MessageContent, Usage, ProviderMeta, DeferredCorrection,
-  PipelineEvent, RunConfig, ProviderAdapter, ProviderConfig,
+  Session, Message, MessageContent, ModelContent, Usage, ProviderMeta, TruncatedToolResult,
+  TurnEvent, RunConfig, ProviderAdapter, ProviderConfig,
   Tool, ToolRegistry, ToolContext, Store, FileStore, SystemContextRegistry, Vault, PromptFn, FormField,
 } from './types.js';
 import type { MatbotPlugin } from './plugin.js';
 import type { ToolPresenter } from '@matatbread/matbot-plugin-api';
-import { currentUsageSink } from '@matatbread/matbot-plugin-api';
+import { currentUsageSink } from '@matatbread/matbot-plugin-api/host';
 import { HookRegistry } from './hooks.js';
 import { appendMessage, createMessage } from './session.js';
+import { foldOntoUserTurn, bindPluginOps } from '@matatbread/matbot-plugin-api';
 import { addUsage } from './usage.js';
 
 // Substituted for an errored tool result when the turn was aborted (e.g. a mid-turn steer interrupt):
@@ -15,6 +16,16 @@ import { addUsage } from './usage.js';
 // internal token that reads as a real failure. A steer's continuation turn is the one place a model
 // reads this, so the wording tells it the call was interrupted and leaves re-running to its judgement —
 // deliberately NOT "re-run it", so a side-effecting tool isn't reflexively repeated.
+// Creator of the marker recording that a provider cut a response short. Marker-role, so it is durable
+// and visible to a reader while elided from every submission: the model's own text is already truncated
+// in the transcript, and a block telling it so invites narrating the cut-off rather than continuing.
+const TRUNCATION_CREATOR = 'matbot-truncation';
+
+/** An AbortSignal's reason as a turn-terminal string. `reason` is `any` by spec (a caller may abort with
+ *  anything), so the two abort exits both had to narrow it; they narrowed it identically. */
+const abortReason = (signal: AbortSignal): string =>
+  typeof signal.reason === 'string' ? signal.reason : 'user-abort';
+
 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;
@@ -64,7 +75,9 @@ export interface RunSessionOpts {
   unloadPlugin:   (specifier: string) => Promise<boolean>;
 }
 
-export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineEvent> {
+// Yields TurnEvent, not PipelineEvent: a single turn never produces the session-level `idle` — that is
+// the pump's, emitted once its queue drains. Saying so in the type is the point of the two-union split.
+export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent> {
   const { config, provider, providerConfig, store, signal } = opts;
   const tools   = opts.tools   ?? new Map<string, Tool>();
   const hookReg = opts.hooks   ?? new HookRegistry();
@@ -83,15 +96,29 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
   };
   const traceId = config.traceId ?? crypto.randomUUID();
 
+  let session = opts.session;
+
+  // Every way a turn can end funnels through here: commit the session as it stands, then yield exactly
+  // one terminal event. Each exit has its own legitimately different preamble — screen markers, a
+  // streamed assistant partial, closing an unpaired tool_use — but the terminal itself must not vary,
+  // and twice it had not: both the `toolcall`-abort and failed-provider-call exits returned with no
+  // commit at all, silently discarding every completed round of the turn.
+  // 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> {
+    await store.set(session.id, session);
+    yield terminal;
+  }
+
   // ── 1. screen — once per turn: shape/abort the incoming submission ──────────
 
-  const screen = await hookReg.runScreen({ session: opts.session, config, signal, prompt: promptFn });
+  const screen = await hookReg.runScreen({ session, config, signal, prompt: promptFn });
+  session = screen.session;
   if (screen.abort) {
     // Hook-failure (and any other screen-injected) markers carried live, even on abort, so a
     // misconfigured hook surfaces this turn rather than only on a later reload.
     if (screen.markers.length > 0) yield { type: 'marker', content: screen.markers, traceId };
-    await store.set(screen.session.id, screen.session);
-    yield { type: 'aborted', reason: screen.abort, session: screen.session, traceId };
+    yield* end({ type: 'aborted', reason: screen.abort, session, traceId });
     return;
   }
   // Durable context a screen hook folded onto the user message (e.g. a fired `contextual` trigger),
@@ -107,7 +134,6 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
   if (screen.markers.length > 0) {
     yield { type: 'marker', content: screen.markers, traceId };
   }
-  let session = screen.session;
 
   // Turn-scoped ephemeral context from screen — appended to the TAIL of the outgoing messages
   // (onto the content of the freshest history message, preserving its role), never persisted.
@@ -124,12 +150,19 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
   // in here when it fires, and the loop re-runs with it.
   let ephemeral = [...(opts.injectedEphemeral ?? []), ...screen.ephemeral];
 
-  // Raced screen verdicts (see DeferredScreen): polled — synchronously, never awaited — at each loop
-  // edge. `pollDeferred` claims any that have fired this poll (exactly once each) and merges their
-  // corrections; `applyCorrection` then folds them in and returns any durable blocks to emit live.
+  // Raced screen verdicts (see DeferredScreen): claimed — synchronously, never awaited — at each of the
+  // three loop edges (before generating, mid-stream, and pre-commit). Claiming is one step, so the three
+  // sites cannot disagree about it: take every verdict that has fired since the last claim (exactly once
+  // each), fold `ephemeral` in ahead of what is already queued so the re-run reads it, fold `durable`
+  // onto the user turn (persisted — the re-run and every later turn see it in history), and carry that
+  // durable half live as a `robo-user`, which is what preserves a contextual fire's visible persistence
+  // even though the verdict landed mid-turn.
+  //
+  // 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;
-  const pollDeferred = (): DeferredCorrection | undefined => {
-    if (deferred.length === 0) return undefined;
+  async function* claimVerdicts(): AsyncGenerator<TurnEvent, boolean, undefined> {
+    if (deferred.length === 0) return false;
     const ephemeralC: MessageContent[] = [];
     const durableC:   MessageContent[] = [];
     for (const d of deferred) {
@@ -138,24 +171,20 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
       if (c.ephemeral) ephemeralC.push(...c.ephemeral);
       if (c.durable)   durableC.push(...c.durable);
     }
-    return (ephemeralC.length > 0 || durableC.length > 0) ? { ephemeral: ephemeralC, durable: durableC } : undefined;
-  };
-  // Apply a claimed correction: `ephemeral` leads the tail-fold for the re-run; `durable` is folded onto
-  // the turn's user message (persisted, re-run sees it in history) and RETURNED so the caller emits it
-  // live as a `robo-user` event — the durable twin, preserving a contextual fire's persistence even
-  // though the verdict landed mid-turn. Mutates `ephemeral`/`session` in place.
-  const applyCorrection = (c: DeferredCorrection): MessageContent[] => {
-    if (c.ephemeral && c.ephemeral.length > 0) ephemeral = [...c.ephemeral, ...ephemeral];
-    if (c.durable && c.durable.length > 0) {
-      const idx = session.messages.findLastIndex(m => m.role === 'user');
-      if (idx >= 0) {
-        session = { ...session, messages: session.messages.map((m, i) =>
-          i === idx ? { ...m, content: [...m.content, ...c.durable!] } : m) };
-        return c.durable;
+    if (ephemeralC.length === 0 && durableC.length === 0) return false;
+
+    if (ephemeralC.length > 0) ephemeral = [...ephemeralC, ...ephemeral];
+    if (durableC.length > 0) {
+      const folded = foldOntoUserTurn(session, durableC);
+      // Identity-unchanged ⇒ no user message to attach to, so the blocks were dropped: nothing durable
+      // landed, hence nothing to carry live either.
+      if (folded !== session) {
+        session = folded;
+        yield { type: 'robo-user', content: durableC, traceId };
       }
     }
-    return [];
-  };
+    return true;
+  }
 
   // ── 2. System context (built once per submit, never persisted) ─────────────
 
@@ -173,24 +202,44 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
 
   // ── 3. Agentic loop ────────────────────────────────────────────────────────
 
+  // Rounds already run against this provider, where a round is one provider call plus the tool batch it
+  // asked for. Compared against the provider profile's own `maxRounds` — a spend ceiling denominated in
+  // the unit spend varies by. Absent ⇒ unbounded (`?? Infinity`), the historical behaviour.
+  let round = 0;
+
+  // Tool-supplied media, keyed by the tool message it answers — see the `model-content` ToolEvent.
+  // Turn-scoped and wire-only: it is spliced into the outgoing copy below and dies with this call.
+  const attachments = new Map<string, Message>();
+
   for (;;) {
     // Respect an abort that arrived between turns (e.g. during tool execution).
     if (signal.aborted) {
-      await store.set(session.id, session);
-      yield { type: 'aborted', reason: typeof signal.reason === 'string' ? signal.reason : 'user-abort', session, traceId };
+      yield* end({ type: 'aborted', reason: abortReason(signal), session, traceId });
       return;
     }
 
+    // Checked HERE — before starting a round, not part-way through one — so the previous round's tool
+    // results are already appended and there is nothing to reconcile: the same persist-and-yield as the
+    // abort above. A turn stopped by the ceiling was cut short, not faulty, so it ends `aborted` rather
+    // than `error`, and the reason is machine-readable for a frontend that wants to say why.
+    if (round >= (providerConfig.maxRounds ?? Infinity)) {
+      const reason = `round-limit: provider "${config.provider}" allows ${providerConfig.maxRounds} rounds per turn`;
+      yield* end({ type: 'aborted', reason, session, traceId });
+      return;
+    }
+    round += 1;
+
     // 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.
-    const early = pollDeferred();
-    if (early) { const dur = applyCorrection(early); if (dur.length > 0) yield { type: 'robo-user', content: dur, traceId }; }
+    yield* claimVerdicts();
 
-    const pendingCalls: Array<{ id: string; name: string; input: unknown; meta?: ProviderMeta }> = [];
+    const pendingCalls: Array<{ id: string; name: string; input: unknown; meta?: ProviderMeta;
+      truncated?: { bytes: number; stopReason?: string } }> = [];
     const assistantParts: MessageContent[] = [];
     let textAcc = '';
     let turnUsage: Usage | undefined;
+    let truncation: { reason: 'max-tokens' | 'stream-end'; raw?: string } | undefined;
     // Set if a raced verdict fires mid-generation: discard this response and re-run the loop (below).
     let restart = false;
 
@@ -201,9 +250,12 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
     // 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
-      ? session.messages.map((m, i) =>
-          i === foldIdx ? { ...m, content: [...m.content, ...ephemeral] } : m)
+    const history = foldIdx >= 0 || attachments.size > 0
+      ? session.messages.flatMap((m, i) => {
+          const folded = i === foldIdx ? { ...m, content: [...m.content, ...ephemeral] } : m;
+          const media  = attachments.get(m.id);
+          return media ? [folded, media] : [folded];
+        })
       : session.messages;
     const outgoing = await hookReg.runContribute({
       outgoing: [...systemMsg, ...history],
@@ -224,12 +276,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
         // A raced verdict firing mid-generation changes the premise: discard this doomed response and
         // restart the loop with the correction folded in. Polled BEFORE the event is emitted, so a
         // classifier faster than time-to-first-token is caught before any token reaches the frontend.
-        const hit = pollDeferred();
-        if (hit) {
-          const dur = applyCorrection(hit);
-          if (dur.length > 0) yield { type: 'robo-user', content: dur, traceId };
-          restart = true; callAc.abort('screen-restart'); break;
-        }
+        if (yield* claimVerdicts()) { restart = true; callAc.abort('screen-restart'); break; }
         switch (ev.type) {
           case 'text-delta':
             textAcc += ev.delta;
@@ -252,7 +299,11 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
             break;
           case 'tool-call':
             pendingCalls.push({ id: ev.id, name: ev.name, input: ev.input,
-              ...(ev.meta !== undefined ? { meta: ev.meta } : {}) });
+              ...(ev.meta      !== undefined ? { meta:      ev.meta      } : {}),
+              ...(ev.truncated !== undefined ? { truncated: ev.truncated } : {}) });
+            break;
+          case 'truncated':
+            truncation = { reason: ev.reason, ...(ev.raw !== undefined ? { raw: ev.raw } : {}) };
             break;
           case 'usage':
             turnUsage = addUsage(turnUsage, ev);
@@ -279,11 +330,20 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
             ...(turnUsage !== undefined ? { usage: turnUsage } : {}),
           }));
         }
-        await store.set(session.id, session);
-        yield { type: 'aborted', reason: typeof signal.reason === 'string' ? signal.reason : 'user-abort', session, traceId };
+        yield* end({ type: 'aborted', reason: abortReason(signal), session, traceId });
         return;
       } else {
-        yield { type: 'error', error: String(e) + (('cause' in e && e.cause) ? ' ('+String(e.cause)+')' : '' ), traceId };
+        // A failed provider call still commits the rounds that succeeded. Nothing is written mid-turn, so
+        // returning without one discarded the whole turn — and the multi-round case is exactly the
+        // tool-using one, so a provider 500 or a dropped connection on round 3 threw away two completed
+        // rounds of assistant messages and tool results the frontend had already drawn, and which the
+        // next turn (which re-reads from the store) would then be missing.
+        //
+        // Nothing partial is appended here, unlike the abort branch above: `textAcc` and `assistantParts`
+        // belong to the call that failed, and the model never finished the thought. The `error` event
+        // carries no session (a failure is not a transcript), so this yields the terminal itself rather
+        // than the session — but it commits first, exactly like every other exit.
+        yield* end({ type: 'error', error: String(e) + (('cause' in e && e.cause) ? ' ('+String(e.cause)+')' : '' ), traceId });
         return;
       }
     }
@@ -295,8 +355,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
 
     // Pre-commit poll: the verdict may have settled exactly as the stream ended. Discard and re-run
     // rather than commit-then-retract, keeping the correction on the cheaper in-situ path.
-    const late = pollDeferred();
-    if (late) { const dur = applyCorrection(late); if (dur.length > 0) yield { type: 'robo-user', content: dur, traceId }; continue; }
+    if (yield* claimVerdicts()) continue;
 
     // Build and store assistant message
     if (textAcc)           assistantParts.push({ type: 'text', text: textAcc });
@@ -314,7 +373,19 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
         ...(turnUsage !== undefined ? { usage: turnUsage } : {}),
       });
       session = appendMessage(session, assistantMsg);
-    } else {
+    }
+
+    // The provider cut this response short rather than the model choosing to stop. Recorded whether or
+    // not a tool call was caught in it — the commoner case has none, and prose stopping mid-sentence
+    // previously left no trace anywhere. What to DO about it (continue, re-ask with a bigger budget) is
+    // a `followup` hook's call, not the harness's.
+    if (truncation) {
+      const marker: MessageContent = { type: 'marker', creator: TRUNCATION_CREATOR, data: truncation };
+      session = appendMessage(session, createMessage({ role: 'marker', content: [marker], traceId }));
+      yield { type: 'marker', content: [marker], traceId };
+    }
+
+    if (assistantParts.length === 0) {
       // Diagnostic: the provider returned no text, no tool calls, no thinking — a genuinely empty
       // completion. The turn will end with no assistant message, which reads as "the agent never
       // replied". Logged here so a silent no-reply turn is traceable. (textAcc length is shown to
@@ -329,8 +400,9 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
 
     const toolResults: MessageContent[] = [];
     const toolMarkers: MessageContent[] = [];
+    const toolMedia:   ModelContent[]   = [];
 
-    for (const tc of pendingCalls) {
+    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);
@@ -341,13 +413,68 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
         continue;
       }
 
+      // Arguments severed mid-stream (the provider hit its token limit part-way through the call).
+      // The call cannot run, but it must still be answered: the assistant message above carries a
+      // `tool-call` block for it, and an unpaired `tool_use` is rejected by the next submission. So it
+      // is recorded as a call that failed — no execution, no side effect — and the model reads the
+      // failure in the slot it expects and retries smaller, which is the ordinary self-correction the
+      // loop already does for a rejected or unknown tool. No retry counter: a model that keeps
+      // overflowing burns rounds and meets `maxRounds`, exactly as one repeatedly calling any failing
+      // tool does.
+      //
+      // `toolcall` is skipped — there is nothing to judge, the call cannot proceed whatever a hook
+      // says — but `toolresult` runs, because it owns the LLM-facing text and is where a consumer
+      // folds in advice the harness cannot have: which of THIS tool's parameters offers a cheaper
+      // edit. See `isTruncatedToolResult`.
+      if (tc.truncated) {
+        const truncated: TruncatedToolResult = {
+          error:
+            `Arguments for "${tc.name}" were cut off after ${tc.truncated.bytes} bytes and could not be parsed` +
+            `${tc.truncated.stopReason !== undefined ? ` (stop reason "${tc.truncated.stopReason}")` : ''}. ` +
+            'The call did NOT run and had no effect. Retry it smaller — fewer operations in one call, ' +
+            'or split the work across several calls.',
+          truncated: { tool: tc.name, bytes: tc.truncated.bytes,
+            ...(tc.truncated.stopReason !== undefined ? { stopReason: tc.truncated.stopReason } : {}) },
+        };
+        const shaped = await hookReg.runToolResult({
+          session, config, signal,
+          toolCall: { id: tc.id, name: tc.name, input: tc.input },
+          tool, result: truncated, isError: true, durationMs: 0,
+        });
+        toolResults.push({ type: 'tool-result', id: tc.id, result: shaped, isError: true });
+        yield { type: 'tool:end', callId: tc.id, result: shaped, isError: true, traceId };
+        continue;
+      }
+
       const decision = await hookReg.runToolCall({
         session, config, signal,
         toolCall: { id: tc.id, name: tc.name, input: tc.input },
         tool,
       });
       if (decision.abort) {
-        yield { type: 'aborted', reason: decision.abort, session, traceId };
+        // Commit the turn before leaving (`end`, above — nothing is written mid-turn, so an exit that
+        // skips it discards the whole turn: every earlier round's assistant message and tool results,
+        // plus this round's response, all of which the frontend had already drawn). This path is where
+        // that was first found and fixed.
+        //
+        // Committing requires closing the tool_use/tool_result pairing first: the assistant message
+        // above carries a `tool-call` block per pending call, and a `tool_use` left unpaired is
+        // rejected by the next submission (Anthropic 400s; nothing downstream reconciles them). The
+        // abort is a turn-level stop rather than a verdict on the tools, so the calls that never ran
+        // are recorded as not-run. `tool:end` is carried only for the call the hook actually judged —
+        // the rest never had a `tool:start`, so a frontend has no bubble to close for them.
+        const stopped = { error: `Tool call not executed — the turn was aborted (${decision.abort}).` };
+        toolResults.push({ type: 'tool-result', id: tc.id, result: stopped, isError: true });
+        yield { type: 'tool:end', callId: tc.id, result: stopped, isError: true, traceId };
+        for (const rest of pendingCalls.slice(callIdx + 1)) {
+          toolResults.push({ type: 'tool-result', id: rest.id, result: stopped, isError: true });
+        }
+        session = appendMessage(session, createMessage({ role: 'tool', content: toolResults, traceId }));
+        if (toolMarkers.length > 0) {
+          session = appendMessage(session, createMessage({ role: 'marker', content: toolMarkers, traceId }));
+          yield { type: 'marker', content: toolMarkers, traceId };
+        }
+        yield* end({ type: 'aborted', reason: decision.abort, session, traceId });
         return;
       }
       if (decision.rejectTool) {
@@ -369,8 +496,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
         callId: tc.id, session, signal, vault,
         provider:     config.provider,
         prompt:       promptFn,
-        loadPlugin:   (specifier: string, refresh?: boolean) => opts.loadPlugin(specifier, promptFn, refresh),
-        unloadPlugin: opts.unloadPlugin,
+        ...bindPluginOps(opts, promptFn),
         ...(opts.workdir     !== undefined ? { workdir:     opts.workdir     } : {}),
         ...(opts.configPath  !== undefined ? { configPath:  opts.configPath  } : {}),
         ...(opts.files       !== undefined ? { files:       opts.files       } : {}),
@@ -384,6 +510,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
             case 'file':     yield { type: 'file', handle: toolEv.handle, traceId }; break;
             case 'result':   result = toolEv.value; break;
             case 'marker':   toolMarkers.push({ type: 'marker', creator: toolEv.creator, data: toolEv.data }); break;
+            case 'model-content': toolMedia.push(...toolEv.content); break;
             case 'progress': yield { type: 'tool:progress', callId: tc.id, pct: toolEv.pct, ...(toolEv.message !== undefined ? { message: toolEv.message } : {}), traceId }; break;
             case 'error':    result = {
               error: toolEv.message,
@@ -423,6 +550,15 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
     const toolMsg = createMessage({ role: 'tool', content: toolResults, traceId });
     session = appendMessage(session, toolMsg);
 
+    // Media the tools handed over for the model to look at. Held wire-side only — pinned directly
+    // after the tool message it came from (so it keeps a stable history position, and so the model
+    // reads it as the answer to that call) and spliced into `outgoing` on every remaining round of
+    // this turn. Never appended to `session`: the transcript records what the tool returned, not the
+    // bytes it showed.
+    if (toolMedia.length > 0) {
+      attachments.set(toolMsg.id, createMessage({ role: 'user', content: toolMedia, traceId }));
+    }
+
     // Markers a tool emitted while running: persist as their own marker-role message (elided from
     // provider submission) and carry live so a frontend can render them without a reload.
     if (toolMarkers.length > 0) {
@@ -434,7 +570,5 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
   // ── 4. Persist and finish ──────────────────────────────────────────────────
   // `react` fires post-commit, in pump (the queue owner) — not here.
 
-  await store.set(session.id, session);
-
-  yield { type: 'done', session, traceId };
+  yield* end({ type: 'done', session, traceId });
 }

package/src/session-runner.ts

@@ -8,7 +8,8 @@ import type { MatbotPlugin } from './plugin.js';
 import type { HookRegistry } from './hooks.js';
 import type { ToolTypeIndex, ToolPresenter } from '@matatbread/matbot-plugin-api';
 import { appendMessage, createMessage } from './session.js';
-import { contextSwitch, withUsageScope, isReadOnlyError } from '@matatbread/matbot-plugin-api';
+import { isReadOnlyError, foldOntoUserTurn, lastUserIndex } from '@matatbread/matbot-plugin-api';
+import { contextSwitch, withUsageScope } from '@matatbread/matbot-plugin-api/host';
 import { runSession } from './runner.js';
 
 export interface SessionRunnerDeps {
@@ -289,6 +290,14 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
           // the callback: an async iterator returned out of the scope would lose it before it pulls.
           // contextSwitch (not bare runAs): a turn is the transactional unit, so a StorageBackend swap
           // deferred during it lands at this scope's quiescent edge — never mid-CAS.
+          // The terminal event this turn ended on. `followup` is post-COMMIT, and only `done` is a
+          // commit: an `aborted` turn was cut short (a steer, a user cancel, a screen/toolcall hook
+          // refusing it, a provider round ceiling) and an `error` turn produced no response at all, so
+          // in both cases a followup hook would judge history with no completed answer in it — and a
+          // `resubmit` would undo the very stop that just happened, handing a round ceiling a fresh
+          // budget. Tracked here rather than inferred from `ac.signal`, which only knows about the two
+          // signal-driven aborts and not the policy ones.
+          let terminal: PipelineEvent['type'] | undefined;
           await contextSwitch(head.principal, () => withUsageScope(async () => {
             for await (const ev of runSession({
               session,
@@ -311,15 +320,17 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
               ...(head.prompt        !== undefined ? { prompt:        head.prompt        } : {}),
               ...(inject             !== undefined ? { injectedEphemeral: inject } : {}),
             })) {
+              if (ev.type === 'done' || ev.type === 'aborted' || ev.type === 'error') terminal = ev.type;
               emit(s, ev);
             }
           }));
 
           // followup — post-commit, in the queue owner. A hook reads the just-committed turn and may
-          // head-enqueue a robo follow-up (its own real turn, running next). Skipped on abort; runs
-          // under the submitter's principal because a reactor may itself call complete() (a classifier).
+          // head-enqueue a robo follow-up (its own real turn, running next). Runs only for a turn that
+          // committed (see `terminal`), and under the submitter's principal because a reactor may itself
+          // call complete() (a classifier).
           const hooks = deps.hooks;
-          if (!ac.signal.aborted && hooks) {
+          if (terminal === 'done' && hooks) {
             const committed = await deps.store.get(id);
             if (committed && head.resubmitDepth < MAX_RESUBMIT_DEPTH) {
               let followup: { resubmits: MessageContent[][]; markers: MessageContent[]; retract?: { context: MessageContent[]; durable: MessageContent[] } } = { resubmits: [], markers: [] };
@@ -379,14 +390,18 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
               // head, delivering the trigger tool's output as ephemeral context. Unshifted last so it
               // sits at the very head (runs next) even if a resubmit was also queued above.
               if (followup.retract) {
-                const lastUserIdx = committed.messages.findLastIndex(m => m.role === 'user');
+                const lastUserIdx = lastUserIndex(committed);
                 const popped = lastUserIdx >= 0 ? committed.messages.slice(lastUserIdx + 1) : [];
                 // `durable` correction (a contextual fire that landed post-commit) folds onto the user
                 // message we keep — persisted, so the redo AND every later turn see it in history, the
                 // exact durability the clean in-situ path gives. `context` stays ephemeral (redo only).
+                // The fold runs on the *truncated* session, whose last user message is the one we keep,
+                // so it goes through the same helper as the screen and raced-verdict folds.
                 const durable = followup.retract.durable ?? [];
-                const kept = (lastUserIdx >= 0 ? committed.messages.slice(0, lastUserIdx + 1) : committed.messages)
-                  .map((m, i) => (durable.length > 0 && i === lastUserIdx ? { ...m, content: [...m.content, ...durable] } : m));
+                const truncated = lastUserIdx >= 0
+                  ? { ...committed, messages: committed.messages.slice(0, lastUserIdx + 1) }
+                  : committed;
+                const kept = foldOntoUserTurn(truncated, durable).messages;
                 const retractionMsg: Message = {
                   id:        crypto.randomUUID(),
                   role:      'marker',

package/src/session.ts

@@ -2,7 +2,6 @@ import type { Session, Message, MessageContent, MessageRole, Usage } from './typ
 
 export interface CreateSessionOpts {
   title?:                string;
-  contexts?:             string[];
   parentSessionId?:      string;
   branchPointMessageId?: string;
 }
@@ -16,7 +15,6 @@ export function createSession(opts: CreateSessionOpts = {}): Session {
     ...(opts.parentSessionId      !== undefined ? { parentSessionId:      opts.parentSessionId      } : {}),
     ...(opts.branchPointMessageId !== undefined ? { branchPointMessageId: opts.branchPointMessageId } : {}),
     status:    'active',
-    contexts:  opts.contexts ?? [],
     messages:  [],
     createdAt: now,
     updatedAt: now,

package/src/settings.ts

@@ -22,45 +22,51 @@ export function slugSettingsNamespace(name: string): string {
   return name.replace(/[^\w-]+/g, '_');
 }
 
-/** Build a PluginSettings facade over the shared settings store, scoped to one document id. */
+/**
+ * Build a PluginSettings facade over the shared settings store, scoped to one document id.
+ *
+ * Every read used to also decide whether the document was in the pre-Store flat `{ key: value }` format
+ * and, if so, wrap it under a `version: '0'` sentinel that `set`/`delete` then had to recognise and
+ * upgrade with `set` instead of `cas` — a three-site migration paid for on every `settings.get()` by
+ * every plugin, forever. Dropped at 0.4.0: an unrecognised document is treated as absent, so a flat one
+ * would be re-created on first write rather than read. Nothing in the wild is still flat.
+ */
 export function makePluginSettings(store: Store<SettingsDoc>, namespace: string): PluginSettings {
   const id = slugSettingsNamespace(namespace);
 
-  // Handles migration from the old flat-object format (pre-Store).
   const getDoc = async (): Promise<SettingsDoc | null> => {
     const raw = await store.get(id);
-    if (raw === null) return null;
-    if (isSettingsDoc(raw)) return raw;
-    // Old format: flat { key: value } — wrap it so subsequent writes upgrade the file.
-    return { id, version: '0', data: raw as unknown as Record<string, unknown> };
+    return raw !== null && isSettingsDoc(raw) ? raw : null;
+  };
+
+  // One CAS retry loop for both writers: read, apply `mutate`, write. A document that vanished between
+  // read and write (or never existed) is a plain `set`; otherwise `cas` guards the version we read.
+  const update = async (mutate: (data: Record<string, unknown>) => Record<string, unknown> | undefined): Promise<void> => {
+    for (;;) {
+      const doc  = await getDoc();
+      const data = mutate(doc?.data ?? {});
+      if (data === undefined) return;
+      const next: SettingsDoc = { id, version: Date.now().toString(), data };
+      if (doc === null) { await store.set(id, next); return; }
+      const r = await store.cas(id, doc.version, next);
+      if (r.ok) return;
+    }
   };
 
   return {
     async get<T>(key: string): Promise<T | undefined> {
       return (await getDoc())?.data[key] as T | undefined;
     },
-    async set<T>(key: string, value: T): Promise<void> {
-      for (;;) {
-        const doc  = await getDoc();
-        const data = { ...(doc?.data ?? {}), [key]: value as unknown };
-        const next: SettingsDoc = { id, version: Date.now().toString(), data };
-        // version '0' means migrated-but-not-yet-written — use set to upgrade the file.
-        if (doc === null || doc.version === '0') { await store.set(id, next); return; }
-        const r = await store.cas(id, doc.version, next);
-        if (r.ok) return;
-      }
+    set<T>(key: string, value: T): Promise<void> {
+      return update(data => ({ ...data, [key]: value as unknown }));
     },
-    async delete(key: string): Promise<void> {
-      for (;;) {
-        const doc = await getDoc();
-        if (doc === null) return;
-        const data = { ...doc.data };
-        delete data[key];
-        const next: SettingsDoc = { id, version: Date.now().toString(), data };
-        if (doc.version === '0') { await store.set(id, next); return; }
-        const r = await store.cas(id, doc.version, next);
-        if (r.ok) return;
-      }
+    delete(key: string): Promise<void> {
+      return update(data => {
+        if (!(key in data)) return undefined;
+        const next = { ...data };
+        delete next[key];
+        return next;
+      });
     },
   };
 }

package/src/storage-base/query/validate.ts

@@ -93,11 +93,11 @@ function validateFilter(f: Filter, ptr: string): void {
   }
 }
 
-const QUERY_KEYS = new Set(['where', 'sort', 'limit', 'cursor']);
+const QUERY_KEYS = new Set(['where', 'sort', 'limit', 'cursor', 'immutable']);
 
 export function validateQuery(q: StoreQuery): void {
   if (q === null || typeof q !== 'object' || Array.isArray(q))
-    throw new StoreQueryError('query must be an object with optional keys: where, sort, limit, cursor', '/', 'MALFORMED');
+    throw new StoreQueryError('query must be an object with optional keys: where, sort, limit, cursor, immutable', '/', 'MALFORMED');
 
   // Reject unknown top-level keys. Without this the envelope is silently permissive: a clause placed
   // under a wrong key (e.g. `filter` instead of `where`, an SQL-ism LLMs reach for) is dropped, the

package/src/tool-registry.ts

@@ -1,26 +1,37 @@
-import type { Tool, ToolRegistry, ToolRegistryEvent } from './types.js';
-import { createBroadcaster } from '@matatbread/matbot-plugin-api';
+import { RegistryChangeKind } from '@matatbread/matbot-plugin-api';
+import type { Tool, ToolRegistry, Notifier } from './types.js';
 
 export class ToolRegistryImpl implements ToolRegistry {
   private readonly tools = new Map<string, Tool>();
-  private readonly events = createBroadcaster<ToolRegistryEvent>();
+  // The host's notifier proxy, injected at boot (both hosts build it before this registry). Held as the
+  // proxy, not a resolved impl, so a later register('Notifier', …) takes effect here too. Optional: a
+  // registry built without one (tests) simply announces nothing.
+  private readonly notifier: Notifier | undefined;
 
-  constructor(initial?: Iterable<Tool>) {
+  constructor(initial?: Iterable<Tool>, notifier?: Notifier) {
     if (initial !== undefined) for (const tool of initial) this.tools.set(tool.name, tool);
+    this.notifier = notifier;
+  }
+
+  private announce(name: string, operation: 'added' | 'removed', pluginName?: string): void {
+    this.notifier?.notify({
+      kind: RegistryChangeKind, source: 'tools', registry: 'tools', name, operation,
+      ...(pluginName !== undefined ? { detail: { pluginName } } : {}),
+    });
   }
 
   register(tool: Tool): void {
     this.tools.set(tool.name, tool);
-    this.events.emit({ type: 'registered', name: tool.name, ...(tool.pluginName !== undefined ? { pluginName: tool.pluginName } : {}) });
+    this.announce(tool.name, 'added', tool.pluginName);
   }
 
   remove(name: string): void {
-    if (this.tools.delete(name)) this.events.emit({ type: 'removed', name });
+    if (this.tools.delete(name)) this.announce(name, 'removed');
   }
 
   removeByPlugin(pluginName: string): void {
     for (const [name, tool] of this.tools) {
-      if (tool.pluginName === pluginName && this.tools.delete(name)) this.events.emit({ type: 'removed', name });
+      if (tool.pluginName === pluginName && this.tools.delete(name)) this.announce(name, 'removed');
     }
   }
 
@@ -31,9 +42,4 @@ export class ToolRegistryImpl implements ToolRegistry {
   list(): Tool[] {
     return [...this.tools.values()];
   }
-
-  async *watch(signal?: AbortSignal): AsyncIterable<ToolRegistryEvent> {
-    // Tool CRUD is global — no origin — so unwrap the envelope to the bare event.
-    for await (const { value } of this.events.subscribe(signal)) yield value;
-  }
 }

package/src/types.ts

@@ -1,13 +1 @@
 export type * from '@matatbread/matbot-plugin-api';
-
-// ── Internal types (not part of the plugin API) ───────────────────────────────
-
-import type {
-  ProviderAdapter,
-} from '@matatbread/matbot-plugin-api';
-
-export interface ProviderRegistry {
-  register(adapter: ProviderAdapter): void;
-  resolve(name: string): ProviderAdapter;
-}
-