@matatbread/matbot-core 0.3.3 → 0.3.5

package/package.json

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

package/src/registry.ts

@@ -39,8 +39,9 @@ const state = {
 // not in `state` — it owns subscribers across the registry's lifetime, not per-plugin data.
 const pluginEvents = createBroadcaster<PluginRegistryEvent>();
 
-export function watchPlugins(signal?: AbortSignal): AsyncIterable<PluginRegistryEvent> {
-  return pluginEvents.subscribe(signal);
+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;
 }
 
 // Settings namespace + key under which the user's "overwrite all colliding tools" choice
@@ -306,13 +307,13 @@ export async function setupPlugin(plugin: MatbotPlugin, services: MatbotMachine,
   // fires. Forward-referenced via `scoped`, assigned below; consume() only runs after setup.
   let scoped: MatbotMachine;
   const scopedMounted: Mounted = {
-    consume(options, handler) {
+    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;
-      services.mounted.consume(forwarded, () => handler(scoped as never));
+      services.mounted.observe(forwarded, () => handler(scoped as never));
     },
   };
 

package/src/runner.ts

@@ -1,5 +1,5 @@
 import type {
-  Session, MessageContent, Usage, ProviderMeta,
+  Session, MessageContent, Usage, ProviderMeta, DeferredCorrection,
   PipelineEvent, RunConfig, ProviderAdapter, ProviderConfig,
   Tool, ToolRegistry, ToolContext, Store, FileStore, SystemContextRegistry, Vault, PromptFn, FormField,
 } from './types.js';
@@ -10,6 +10,15 @@ import { HookRegistry } from './hooks.js';
 import { appendMessage, createMessage } from './session.js';
 import { addUsage } from './usage.js';
 
+// Substituted for an errored tool result when the turn was aborted (e.g. a mid-turn steer interrupt):
+// the tool was cut off, not genuinely faulty, and the raw abort reason ("Error: steer") is a leaked
+// 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.
+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;
+
 export interface RunSessionOpts {
   session:        Session;
   config:         RunConfig;
@@ -111,8 +120,42 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
   // drops non-result content from tool-role messages — a separate trailing message would break on
   // one or the other).
   // injectedEphemeral (a pump-supplied retract-redo's context) leads, then screen's own — both share
-  // the identical tail-fold path below.
-  const ephemeral = [...(opts.injectedEphemeral ?? []), ...screen.ephemeral];
+  // the identical tail-fold path below. Mutable: a raced screen verdict (below) folds its correction
+  // 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.
+  const deferred = screen.deferred;
+  const pollDeferred = (): DeferredCorrection | undefined => {
+    if (deferred.length === 0) return undefined;
+    const ephemeralC: MessageContent[] = [];
+    const durableC:   MessageContent[] = [];
+    for (const d of deferred) {
+      const c = d.claim();
+      if (!c) continue;
+      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;
+      }
+    }
+    return [];
+  };
 
   // ── 2. System context (built once per submit, never persisted) ─────────────
 
@@ -138,10 +181,18 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
       return;
     }
 
+    // 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 }; }
+
     const pendingCalls: Array<{ id: string; name: string; input: unknown; meta?: ProviderMeta }> = [];
     const assistantParts: MessageContent[] = [];
     let textAcc = '';
     let turnUsage: Usage | undefined;
+    // Set if a raced verdict fires mid-generation: discard this response and re-run the loop (below).
+    let restart = false;
 
     // One provider call. The outgoing array (system context + history, with screen's ephemeral
     // blocks appended onto the tail message) is assembled here and handed to `contribute` hooks for
@@ -164,8 +215,21 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
     const advertised = opts.toolPresenter
       ? await opts.toolPresenter.present([...tools.values()], { session, provider: config.provider })
       : [...tools.values()];
+    // 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();
+    const callSignal = AbortSignal.any([signal, callAc.signal]);
     try {
-      for await (const ev of provider.complete(outgoing, providerConfig, advertised, signal)) {
+      for await (const ev of provider.complete(outgoing, providerConfig, advertised, callSignal)) {
+        // 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;
+        }
         switch (ev.type) {
           case 'text-delta':
             textAcc += ev.delta;
@@ -202,7 +266,11 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
         }
       }
     } catch (e: any) {
-      if (signal.aborted) {
+      // A provider call cancelled by an in-situ restart (callAc, not the turn signal) is expected — fall
+      // through to the restart below rather than surfacing it as a turn abort or an error.
+      if (restart || (callAc.signal.aborted && !signal.aborted)) {
+        restart = true;
+      } else if (signal.aborted) {
         // Save whatever the LLM streamed before the abort hit.
         if (textAcc) assistantParts.push({ type: 'text', text: textAcc });
         if (assistantParts.length > 0) {
@@ -214,11 +282,22 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
         await store.set(session.id, session);
         yield { type: 'aborted', reason: typeof signal.reason === 'string' ? signal.reason : 'user-abort', session, traceId };
         return;
+      } else {
+        yield { type: 'error', error: String(e) + (('cause' in e && e.cause) ? ' ('+String(e.cause)+')' : '' ), traceId };
+        return;
       }
-      yield { type: 'error', error: String(e) + (('cause' in e && e.cause) ? ' ('+String(e.cause)+')' : '' ), traceId };
-      return;
     }
 
+    // In-situ restart: discard this iteration's (uncommitted) response and re-run the loop with the
+    // raced correction now folded into `ephemeral`. No store write, no retraction marker — the clean
+    // counterpart to a post-commit `followup` retract.
+    if (restart) continue;
+
+    // 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; }
+
     // Build and store assistant message
     if (textAcc)           assistantParts.push({ type: 'text', text: textAcc });
     for (const tc of pendingCalls) {
@@ -318,6 +397,14 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
         isError = true;
       }
 
+      // A tool that errored under an aborted signal did so because it was cut off (a steer interrupt,
+      // a user cancel), not a genuine fault — reframe it before it is recorded, so the raw abort reason
+      // never reaches the model or the transcript. Covers both the throw and the yielded-`error` paths;
+      // a successful result is left untouched.
+      if (signal.aborted && isError) {
+        result = INTERRUPTED_TOOL_RESULT;
+      }
+
       // toolresult — last chance to transform the result before it's recorded/yielded (hard redaction),
       // or to observe it (auditing: args + result + timing). Owns the LLM-facing + persisted surfaces.
       result = await hookReg.runToolResult({

package/src/session-runner.ts

@@ -2,12 +2,13 @@ import type {
   Session, Message, MessageContent, Principal, PromptFn, PipelineEvent,
   Store, ToolRegistry, SystemContextRegistry, Vault, FileStore, Tool,
   ProviderAdapter, ProviderConfig, SessionRunner, SessionView, OpenOpts, SubmitOpenOpts,
+  SteeringPolicy, SteeringDecision,
 } from './types.js';
 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 } from '@matatbread/matbot-plugin-api';
+import { contextSwitch, withUsageScope, isReadOnlyError } from '@matatbread/matbot-plugin-api';
 import { runSession } from './runner.js';
 
 export interface SessionRunnerDeps {
@@ -22,6 +23,10 @@ export interface SessionRunnerDeps {
   // Resolved live (registers after boot): picks which tools are advertised to the model per provider
   // call. Absent ⇒ the whole turn snapshot is advertised. Threaded into runSession per turn.
   toolPresenter?:  () => ToolPresenter | undefined;
+  // Resolved live (registers after boot): decides how a mid-turn submission under `mode: 'auto'` is
+  // disposed (queue vs interrupt) and supplies an interrupt's continuation nudge. Absent ⇒ the runner's
+  // own defaults (DEFAULT_STEERING_POLICY / DEFAULT_STEER_NUDGE).
+  steeringPolicy?: () => SteeringPolicy | undefined;
   hooks?:          HookRegistry;
   systemContext?:  SystemContextRegistry;
   vault?:          Vault;
@@ -50,11 +55,30 @@ interface QueuedItem {
   // message already exists) and hands `ephemeral` (the trigger tool's output) to runSession, which
   // tail-folds it for this run only. `content` is empty for such an item — there is no new bubble.
   redo?: { ephemeral: MessageContent[] };
+  // Turn-scoped ephemeral context to fold onto this item's turn (tail-folded, never persisted) — used
+  // to carry an interrupt's "keep going, noting the above" nudge. Feeds runSession's injectedEphemeral,
+  // the same path `redo` uses; the two are mutually exclusive in practice (redo re-runs an existing
+  // turn with no new message, a steer introduces a new user message).
+  injectEphemeral?: MessageContent[];
   prompt?:     PromptFn;
 }
 
 const MAX_RESUBMIT_DEPTH = 8;
 
+// Disposition for a `mode: 'auto'` mid-turn submission when no SteeringPolicy is registered (or it
+// declares no `classify`). Interrupt-by-default: a message sent while the agent works stops the
+// running turn (its committed partial work is preserved) and runs next. Flip to 'queue' to make the
+// conservative "wait for the turn boundary" the default — this const is the single knob.
+const DEFAULT_STEERING_POLICY: SteeringDecision = 'interrupt';
+
+// The ephemeral nudge folded onto an interrupt's continuation when no SteeringPolicy supplies one. It
+// biases the model to continue the interrupted task while accounting for the steer, rather than pivot
+// wholesale — the dial between "I'll get to that in a minute" and a full reprioritisation.
+const DEFAULT_STEER_NUDGE: MessageContent[] = [{
+  type: 'text',
+  text: 'The user sent the message above while you were working. Take it into account and keep going — continue the task you were on, incorporating this new input rather than discarding your progress.',
+}];
+
 // Marker creator for a retract-and-rerun: its `data.retracted` carries the popped (superseded) turn
 // messages so a frontend can render them struck-through and a post-mortem can audit them. Core-owned
 // because the pop is a pump operation, not a plugin's.
@@ -69,6 +93,10 @@ interface SessionState {
   // submissions interleaved among them (see the batch-building loop in pump). Concat and queued mix freely.
   queue:       QueuedItem[];
   running:     boolean;
+  // traceId of the turn currently running (set at pump loop top, cleared when the turn ends). Lets an
+  // interrupt name the turn it is yielding, so a frontend correlates the `steer` event's
+  // `interruptedTraceId` with the `aborted` (reason 'steer') it is about to see.
+  runningTraceId: string | undefined;
   ac:          AbortController | undefined;
   subscribers: Set<Sink>;
   // Events of the *current* turn, replayed to a subscriber that joins mid-turn. Cleared at each
@@ -134,7 +162,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
   const stateFor = (id: string): SessionState => {
     let s = states.get(id);
     if (s === undefined) {
-      s = { queue: [], running: false, ac: undefined, subscribers: new Set(), replay: [] };
+      s = { queue: [], running: false, runningTraceId: undefined, ac: undefined, subscribers: new Set(), replay: [] };
       states.set(id, s);
     }
     return s;
@@ -176,6 +204,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
           while (s.queue.length > 0 && s.queue[0]!.concatQueue) batch.push(s.queue.shift()!);
         }
         const content = batch.flatMap(i => i.content);
+        s.runningTraceId = head.traceId;
         s.replay = [];
         // Seed replay with the running turn's user message as a single merged `queued`, mirroring the
         // message persisted just below. notify() (in open()) reaches only subscribers that are live at
@@ -211,7 +240,17 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
           // while queued. That is what stops a mid-turn submit from clobbering session state. A robo
           // resubmission's blocks already carry `origin: 'robo'` (stamped where it was enqueued).
           session = appendMessage(session, createMessage({ role: 'user', content, traceId: head.traceId, providerName: head.provider }));
-          await deps.store.set(session.id, session);
+          try {
+            await deps.store.set(session.id, session);
+          } catch (e) {
+            // A read-only store rejects the persist-at-turn-start write (e.g. a session shared read-only
+            // from another profile's partition). That is a per-turn condition, not a host fault: surface
+            // it as a turn error and drop this submission rather than let it escape the detached pump and
+            // crash the process. Any other write failure stays fatal.
+            if (!isReadOnlyError(e)) throw e;
+            emit(s, { type: 'error', error: e.message, traceId: head.traceId });
+            continue;
+          }
         }
 
         const resolved = await deps.resolveProvider(head.provider);
@@ -220,6 +259,10 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
           continue;
         }
 
+        // A redo re-runs an existing turn with its ephemeral; a steer carries an interrupt's nudge. The
+        // two never coincide on one item, so either supplies runSession's injectedEphemeral.
+        const inject = head.redo?.ephemeral ?? head.injectEphemeral;
+
         const ac = new AbortController();
         s.ac = ac;
         // Fold each tool's wire contract — the `params`/`result` text flattened from its single contract
@@ -266,7 +309,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
               ...(deps.configPath    !== undefined ? { configPath:    deps.configPath    } : {}),
               ...(deps.vault         !== undefined ? { vault:         deps.vault         } : {}),
               ...(head.prompt        !== undefined ? { prompt:        head.prompt        } : {}),
-              ...(head.redo          !== undefined ? { injectedEphemeral: head.redo.ephemeral } : {}),
+              ...(inject             !== undefined ? { injectedEphemeral: inject } : {}),
             })) {
               emit(s, ev);
             }
@@ -279,7 +322,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
           if (!ac.signal.aborted && hooks) {
             const committed = await deps.store.get(id);
             if (committed && head.resubmitDepth < MAX_RESUBMIT_DEPTH) {
-              let followup: { resubmits: MessageContent[][]; markers: MessageContent[]; retract?: { context: MessageContent[] } } = { resubmits: [], markers: [] };
+              let followup: { resubmits: MessageContent[][]; markers: MessageContent[]; retract?: { context: MessageContent[]; durable: MessageContent[] } } = { resubmits: [], markers: [] };
               await contextSwitch(head.principal, async () => {
                 followup = await hooks.runFollowup({
                   session:       committed,
@@ -338,7 +381,12 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
               if (followup.retract) {
                 const lastUserIdx = committed.messages.findLastIndex(m => m.role === 'user');
                 const popped = lastUserIdx >= 0 ? committed.messages.slice(lastUserIdx + 1) : [];
-                const kept   = lastUserIdx >= 0 ? committed.messages.slice(0, lastUserIdx + 1) : committed.messages;
+                // `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).
+                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 retractionMsg: Message = {
                   id:        crypto.randomUUID(),
                   role:      'marker',
@@ -347,7 +395,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
                   // `retracted` is what was popped (the superseded answer); `injected` is the ephemeral
                   // context fed to the redo — neither is otherwise persisted, so the pair fully traces
                   // the swap for a post-mortem (and a frontend can render the strike-through + the cause).
-                  content:   [{ type: 'marker', creator: RETRACTION_CREATOR, data: { retracted: popped, injected: followup.retract.context, traceId: head.traceId } }],
+                  content:   [{ type: 'marker', creator: RETRACTION_CREATOR, data: { retracted: popped, injected: followup.retract.context ?? [], traceId: head.traceId } }],
                 };
                 // Any followup markers ride along as a trailing marker message (not folded into the
                 // retraction marker) so each creator's trace stays its own block.
@@ -355,6 +403,9 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
                   ? [{ id: crypto.randomUUID(), role: 'marker', createdAt: new Date().toISOString(), traceId: head.traceId, content: followup.markers }]
                   : [];
                 await deps.store.set(id, { ...committed, messages: [...kept, retractionMsg, ...trailing] });
+                // Emit the durable fold live (as a robo-user on the kept user turn) before the retraction
+                // marker, mirroring the screen-time durable path's ordering.
+                if (durable.length > 0) notify(s, { type: 'robo-user', content: durable, traceId: head.traceId });
                 notify(s, { type: 'marker', content: retractionMsg.content, traceId: head.traceId });
                 if (trailing.length > 0) notify(s, { type: 'marker', content: followup.markers, traceId: head.traceId });
 
@@ -367,7 +418,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
                   principal:     head.principal,
                   concatQueue:   false,
                   resubmitDepth: head.resubmitDepth + 1,
-                  redo:          { ephemeral: followup.retract.context },
+                  redo:          { ephemeral: followup.retract.context ?? [] },
                   ...(head.prompt !== undefined ? { prompt: head.prompt } : {}),
                 });
               }
@@ -381,6 +432,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
       }
     } finally {
       s.running = false;
+      s.runningTraceId = undefined;
       s.replay  = [];
       // Deterministic busy→idle signal: running is now false, so any subscriber draining the stream
       // (a frontend's status tracker) reads an authoritative idle the moment it sees this — no racing
@@ -406,22 +458,75 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
         }
         s = stateFor(opts.sessionId);
         traceId = opts.traceId ?? crypto.randomUUID();
-        const concatQueue = opts.concatQueue ?? false;
-        s.queue.push({
-          traceId,
-          rootTraceId:   traceId,
-          content:       opts.content,
-          provider:      opts.provider,
-          principal:     opts.principal,
-          concatQueue,
-          resubmitDepth: 0,
-          ...(opts.prompt !== undefined ? { prompt: opts.prompt } : {}),
-        });
-        // Announce the submission on the stream as part of the live delta, before its turn's events.
-        // If it runs immediately `queued` is 0 (no wait); otherwise it's how many are ahead. concatQueue
-        // tells a frontend whether this submission will merge into the running batch (so it can fold the
-        // bubble) or run as its own turn.
-        notify(s, { type: 'queued', content: opts.content, queued: aheadOf(s, s.queue.length - 1), concatQueue, traceId, rootTraceId: traceId });
+        const { content, provider, principal } = opts;
+        const mode = opts.mode ?? 'queue';
+
+        // Decide interrupt vs queue for a submission arriving mid-turn. Steering is only meaningful
+        // while a turn is running; with nothing running it enqueues and runs next regardless of mode.
+        // The decision — and, on interrupt, the abort+unshift — happen here synchronously against
+        // s.running (re-checked after any classify/nudge await) so an interrupt can never land on the
+        // wrong (a later) turn: the fatal race of deciding across a wire is closed by deciding in-runner.
+        let interrupt = false;
+        if (mode !== 'queue' && s.running) {
+          const policy = deps.steeringPolicy?.();
+          // Fetch the committed session once (history up to the running turn's start) only when a policy
+          // member actually needs it: classify under `auto`, and nudge on any interrupt. The common
+          // no-policy interrupt path (e.g. the web default) does no extra read.
+          const wantClassify = mode === 'auto' && policy?.classify !== undefined;
+          const wantNudge    = policy?.nudge !== undefined;
+          const committed = (wantClassify || wantNudge) ? await deps.store.get(opts.sessionId) : null;
+
+          const decision: SteeringDecision = mode === 'interrupt'
+            ? 'interrupt'
+            : policy?.classify !== undefined
+              ? (committed ? await policy.classify({ session: committed, steer: content }) : DEFAULT_STEERING_POLICY)
+              : DEFAULT_STEERING_POLICY;
+
+          // Any await above may have outlived the running turn; only interrupt one still live.
+          if (decision === 'interrupt' && s.running) {
+            const nudge = policy?.nudge !== undefined && committed
+              ? policy.nudge({ session: committed, steer: content })
+              : DEFAULT_STEER_NUDGE;
+            const interruptedTraceId = s.runningTraceId ?? '';
+            // Head of the queue (ahead of anything else already queued): the steer runs immediately
+            // after the interrupted turn commits its partial work. Own turn (never concat).
+            s.queue.unshift({
+              traceId,
+              rootTraceId:     traceId,
+              content,
+              provider,
+              principal,
+              concatQueue:     false,
+              resubmitDepth:   0,
+              injectEphemeral: nudge,
+              ...(opts.prompt !== undefined ? { prompt: opts.prompt } : {}),
+            });
+            // Announce the steer before aborting so a subscriber places the new bubble and reads the
+            // imminent `aborted` (reason 'steer') as a yield, not a dead-end.
+            notify(s, { type: 'steer', content, interruptedTraceId, traceId, rootTraceId: traceId });
+            s.ac?.abort('steer');
+            interrupt = true;
+          }
+        }
+
+        if (!interrupt) {
+          const concatQueue = opts.concatQueue ?? false;
+          s.queue.push({
+            traceId,
+            rootTraceId:   traceId,
+            content,
+            provider,
+            principal,
+            concatQueue,
+            resubmitDepth: 0,
+            ...(opts.prompt !== undefined ? { prompt: opts.prompt } : {}),
+          });
+          // Announce the submission on the stream as part of the live delta, before its turn's events.
+          // If it runs immediately `queued` is 0 (no wait); otherwise it's how many are ahead. concatQueue
+          // tells a frontend whether this submission will merge into the running batch (so it can fold the
+          // bubble) or run as its own turn.
+          notify(s, { type: 'queued', content, queued: aheadOf(s, s.queue.length - 1), concatQueue, traceId, rootTraceId: traceId });
+        }
         void pump(opts.sessionId, s);
       }
 

package/src/session.ts

@@ -1,25 +1,17 @@
-import type { Session, Message, MessageContent, MessageRole, Principal, Usage } from './types.js';
+import type { Session, Message, MessageContent, MessageRole, Usage } from './types.js';
 
 export interface CreateSessionOpts {
-  ownerPrincipal:        Principal;
-  actorPrincipal?:       Principal;
-  persona?:              string;
   title?:                string;
   contexts?:             string[];
   parentSessionId?:      string;
   branchPointMessageId?: string;
 }
 
-export function createSession(opts: CreateSessionOpts): Session {
+export function createSession(opts: CreateSessionOpts = {}): Session {
   const now = new Date().toISOString();
   return {
     id:               crypto.randomUUID(),
     version:          crypto.randomUUID(),
-    ownerPrincipalId: opts.ownerPrincipal.id,
-    ...(opts.actorPrincipal && opts.actorPrincipal.id !== opts.ownerPrincipal.id
-      ? { actorPrincipalId: opts.actorPrincipal.id }
-      : {}),
-    ...(opts.persona              !== undefined ? { persona:              opts.persona              } : {}),
     ...(opts.title                !== undefined ? { title:                opts.title                } : {}),
     ...(opts.parentSessionId      !== undefined ? { parentSessionId:      opts.parentSessionId      } : {}),
     ...(opts.branchPointMessageId !== undefined ? { branchPointMessageId: opts.branchPointMessageId } : {}),

package/src/storage-base/caching-backend.ts

@@ -0,0 +1,166 @@
+import type {
+  Store, StorageBackend, FileStore, StoreQuery, QueryResult, CASResult,
+} from '@matatbread/matbot-plugin-api';
+import { executeQuery } from './query/execute.js';
+
+export interface CachingOptions {
+  /**
+   * Bounded-staleness ceiling for FOREIGN writes — another process/tab/host mutating the same backing
+   * store behind our back. When set, a namespace's in-memory image is treated as stale this many ms
+   * after it was warmed and re-loaded on the next read. Own writes are always coherent regardless
+   * (write-through keeps the image in step), so a strictly single-writer deployment can leave this
+   * unset. Undefined ⇒ warm once and never expire on time.
+   *
+   * TTL is the *portable* invalidation tier — every backing store supports it. A backing store that
+   * also exposes a change feed (Node `fs.watch`, the Drive Changes API, Postgres `LISTEN/NOTIFY`)
+   * could drive sharper foreign-write invalidation by evicting `image` on a remote change event; that
+   * is a later, opt-in refinement layered on top of this and deliberately NOT required here.
+   */
+  ttlMs?: number;
+}
+
+/** Per-namespace cache counters, for answering "is the cache actually saving reads?" — see
+ *  {@link CachingStorageBackend.stats}. `reads` is get()+query() calls; `hits` is the subset served
+ *  from the warm image without touching the backing store; `loads` is full-namespace warms/refreshes
+ *  (the expensive round-trips); `lastLoadMs` times the most recent one; `docs` is the current image
+ *  size. A healthy cache shows `hits` climbing while `loads` stays flat (typically 1). */
+export interface CacheNamespaceStats {
+  docs:       number;
+  reads:      number;
+  hits:       number;
+  loads:      number;
+  lastLoadMs: number;
+}
+
+/**
+ * Cache-aside, write-through caching Store. Reads serve from a full in-memory image of the namespace
+ * (`Map<id, T>`), warmed lazily by a single `backing.query({})`; every write goes to the backing store
+ * first (the system of record — CAS and durability stay there) and then updates the image on success.
+ *
+ * Coherence is honest: always coherent with THIS store's own writes; foreign writes only as sharp as
+ * the {@link CachingOptions.ttlMs} tier (never, if unset). That is the single-writer assumption made
+ * explicit at one layer — a backend that cannot assume it simply isn't wrapped, or wraps with a short
+ * TTL.
+ */
+class CachingStore<T extends { id: string; version: string }> implements Store<T> {
+  private image: Map<string, T> | undefined;
+  private warmedAt = 0;
+  private warming: Promise<Map<string, T>> | undefined;
+
+  private readonly backing: Store<T>;
+  private readonly ttlMs:   number | undefined;
+
+  private reads = 0;
+  private hits  = 0;
+  private loads = 0;
+  private lastLoadMs = 0;
+
+  constructor(backing: Store<T>, ttlMs: number | undefined) {
+    this.backing = backing;
+    this.ttlMs   = ttlMs;
+  }
+
+  get stats(): CacheNamespaceStats {
+    return { docs: this.image?.size ?? 0, reads: this.reads, hits: this.hits, loads: this.loads, lastLoadMs: this.lastLoadMs };
+  }
+
+  private fresh(): boolean {
+    if (this.image === undefined) return false;
+    if (this.ttlMs === undefined) return true;
+    return Date.now() - this.warmedAt < this.ttlMs;
+  }
+
+  // Serve the whole-namespace image, (re)loading it when cold or TTL-stale. Concurrent callers share
+  // one in-flight load rather than each firing their own `query({})`.
+  private warm(): Promise<Map<string, T>> {
+    if (this.image !== undefined && this.fresh()) { this.hits++; return Promise.resolve(this.image); }
+    return (this.warming ??= this.load());
+  }
+
+  private async load(): Promise<Map<string, T>> {
+    const started = Date.now();
+    try {
+      const { items } = await this.backing.query({});
+      const map = new Map<string, T>(items.map(d => [d.id, d]));
+      this.image      = map;
+      this.warmedAt   = Date.now();
+      this.loads++;
+      this.lastLoadMs = Date.now() - started;
+      return map;
+    } finally {
+      this.warming = undefined;
+    }
+  }
+
+  async get(id: string): Promise<T | null> {
+    this.reads++;
+    return (await this.warm()).get(id) ?? null;
+  }
+
+  async query(q: StoreQuery): Promise<QueryResult<T>> {
+    this.reads++;
+    return executeQuery([...(await this.warm()).values()], q);
+  }
+
+  async set(id: string, value: T): Promise<void> {
+    await this.backing.set(id, value);
+    this.image?.set(id, value);
+  }
+
+  async cas(id: string, expected: string, next: T): Promise<CASResult<T>> {
+    const result = await this.backing.cas(id, expected, next);
+    if (this.image !== undefined) {
+      if (result.ok) this.image.set(id, next);
+      // Conflict: the backing store hands back the authoritative current doc — reconcile the image so a
+      // retry (and the caller inspecting `current`) sees truth, not our stale copy.
+      else if (result.current !== null) this.image.set(id, result.current);
+      else this.image.delete(id);
+    }
+    return result;
+  }
+
+  async delete(id: string, expectedVersion?: string): Promise<boolean> {
+    const ok = await this.backing.delete(id, expectedVersion);
+    if (ok) this.image?.delete(id);
+    return ok;
+  }
+}
+
+/**
+ * Wraps any {@link StorageBackend} in a per-namespace read-through cache — see {@link CachingStore}.
+ * Compose it BELOW any principal-partitioning router (e.g. the profiles backend) so each partition
+ * gets its own cache and the cache never sees a blended, principal-blind view; a slow backend
+ * (browser Google Drive) wraps its own backend before registering. File blobs pass straight through
+ * uncached (large, and read far less often than documents).
+ */
+export class CachingStorageBackend implements StorageBackend {
+  readonly inner: StorageBackend;
+  private readonly ttlMs:  number | undefined;
+  private readonly stores = new Map<string, CachingStore<{ id: string; version: string }>>();
+
+  constructor(inner: StorageBackend, options: CachingOptions = {}) {
+    this.inner = inner;
+    this.ttlMs = options.ttlMs;
+  }
+
+  createStore<T extends { id: string; version: string }>(namespace: string): Store<T> {
+    let store = this.stores.get(namespace);
+    if (store === undefined) {
+      store = new CachingStore(this.inner.createStore(namespace), this.ttlMs);
+      this.stores.set(namespace, store);
+    }
+    return store as unknown as Store<T>;
+  }
+
+  /** Per-namespace cache counters (only namespaces touched so far). A diagnostic surface — read it to
+   *  confirm the cache is serving reads (`hits` up, `loads` ~1) rather than re-reading the backend. */
+  stats(): Record<string, CacheNamespaceStats> {
+    const out: Record<string, CacheNamespaceStats> = {};
+    for (const [ns, store] of this.stores) out[ns] = store.stats;
+    return out;
+  }
+
+  get fileStore(): FileStore { return this.inner.fileStore; }
+
+  close(): Promise<void> { return this.inner.close?.() ?? Promise.resolve(); }
+}

package/src/storage-base/index.ts

@@ -1 +1,2 @@
 export * from './query/index.js';
+export { CachingStorageBackend, type CachingOptions, type CacheNamespaceStats } from './caching-backend.js';

package/src/tool-registry.ts

@@ -32,7 +32,8 @@ export class ToolRegistryImpl implements ToolRegistry {
     return [...this.tools.values()];
   }
 
-  watch(signal?: AbortSignal): AsyncIterable<ToolRegistryEvent> {
-    return this.events.subscribe(signal);
+  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;
   }
 }