@matatbread/matbot-plugin-api 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"
   },

package/src/broadcast.ts

@@ -1,27 +1,47 @@
 // A minimal multi-subscriber fan-out for AsyncIterable observation streams (tool/plugin/skill watch,
-// and any future plugin-owned CRUD stream). Each subscriber gets its own unbounded queue, so a slow
-// consumer never blocks emit() or its peers. Acceptable because these events are rare and small
+// file changes, and any future plugin-owned CRUD stream). Each subscriber gets its own unbounded queue,
+// so a slow consumer never blocks emit() or its peers. Acceptable because these events are rare and small
 // (registry/document CRUD); this is not a high-throughput data path. emit() is synchronous and never throws.
+//
+// Every event flows as a {@link Routed} envelope carrying an optional `origin` principal — the partition
+// or actor that produced it. This is the one attribution channel shared by every stream (files, skills,
+// future partitioned stores); a global stream (tool/plugin registry) simply never sets it. Per-subscriber
+// filtering (`subscribe(signal, filter)`) is applied at emit time, so a subscriber that only wants events
+// visible to one principal never even queues the rest — the single, common place per-principal visibility
+// lives, whatever the terminal (SSE→frontend, an internal consumer, or a cache).
+
+import type { Principal } from './types.js';
+
+/** A broadcast event plus its optional origin. `origin` undefined ⇒ global/base — visible to all. */
+export interface Routed<T> {
+  readonly value:   T;
+  readonly origin?: Principal;
+}
+
+/** Per-subscriber predicate: keep only the envelopes it returns true for. */
+export type RoutedFilter<T> = (event: Routed<T>) => boolean;
 
 interface Subscriber<T> {
-  queue: T[];
-  wake:  (() => void) | undefined;
-  done:  boolean;
+  queue:  Routed<T>[];
+  wake:   (() => void) | undefined;
+  done:   boolean;
+  filter: RoutedFilter<T> | undefined;
 }
 
 // The consumer facet — what a stream hands out. `emit` is the producer's, kept off this so a
 // surface that only exposes observation (e.g. services.mounted) cannot forge events.
 export interface Subscribable<T> {
-  subscribe(signal?: AbortSignal): AsyncIterable<T>;
+  subscribe(signal?: AbortSignal, filter?: RoutedFilter<T>): AsyncIterable<Routed<T>>;
   // Detached observation loop: awaits each handler before pulling the next (no overlapping runs),
   // isolates a throwing handler (logged, never propagated — a bad observer must not kill the stream),
   // and ends when the source ends or `signal` aborts. The fire-and-forget form of the for-await loop
-  // every watch call site otherwise hand-writes.
-  consume(handler: (value: T) => void | Promise<void>, signal?: AbortSignal): void;
+  // every watch call site otherwise hand-writes. An internal cache is exactly this: a `consume` that
+  // folds each `Routed<T>` into per-origin state.
+  consume(handler: (event: Routed<T>) => void | Promise<void>, signal?: AbortSignal, filter?: RoutedFilter<T>): void;
 }
 
 export interface Broadcaster<T> extends Subscribable<T> {
-  emit(value: T): void;
+  emit(value: T, origin?: Principal): void;
 }
 
 /**
@@ -29,11 +49,13 @@ export interface Broadcaster<T> extends Subscribable<T> {
  * `consume` loop. Use for a *derived* stream — e.g. a per-plugin scoped view of a shared broadcaster —
  * that owns its own subscribe generator but wants the same consume ergonomics as a real broadcaster.
  */
-export function subscribable<T>(subscribe: (signal?: AbortSignal) => AsyncIterable<T>): Subscribable<T> {
-  const consume = (handler: (value: T) => void | Promise<void>, signal?: AbortSignal): void => {
+export function subscribable<T>(
+  subscribe: (signal?: AbortSignal, filter?: RoutedFilter<T>) => AsyncIterable<Routed<T>>,
+): Subscribable<T> {
+  const consume = (handler: (event: Routed<T>) => void | Promise<void>, signal?: AbortSignal, filter?: RoutedFilter<T>): void => {
     void (async () => {
-      for await (const v of subscribe(signal)) {
-        try { await handler(v); }
+      for await (const event of subscribe(signal, filter)) {
+        try { await handler(event); }
         catch (e) { console.error('[matbot] consume handler threw:', e instanceof Error ? e.message : e); }
       }
     })();
@@ -44,15 +66,17 @@ export function subscribable<T>(subscribe: (signal?: AbortSignal) => AsyncIterab
 export function createBroadcaster<T>(): Broadcaster<T> {
   const subs = new Set<Subscriber<T>>();
 
-  const emit = (value: T): void => {
+  const emit = (value: T, origin?: Principal): void => {
+    const event: Routed<T> = origin !== undefined ? { value, origin } : { value };
     for (const sub of subs) {
-      sub.queue.push(value);
+      if (sub.filter !== undefined && !sub.filter(event)) continue;
+      sub.queue.push(event);
       sub.wake?.();
     }
   };
 
-  async function* subscribe(signal?: AbortSignal): AsyncIterable<T> {
-    const sub: Subscriber<T> = { queue: [], wake: undefined, done: false };
+  async function* subscribe(signal?: AbortSignal, filter?: RoutedFilter<T>): AsyncIterable<Routed<T>> {
+    const sub: Subscriber<T> = { queue: [], wake: undefined, done: false, filter };
     subs.add(sub);
     const onAbort = () => { sub.done = true; sub.wake?.(); };
     signal?.addEventListener('abort', onAbort, { once: true });

package/src/errors.ts

@@ -16,7 +16,7 @@
 
 const BRAND = 'matbot';
 
-export type MatbotErrorKind = 'MissingSecret' | 'IncompatibleRuntime' | 'NotAPlugin' | 'PromptCancelled';
+export type MatbotErrorKind = 'MissingSecret' | 'IncompatibleRuntime' | 'NotAPlugin' | 'PromptCancelled' | 'ReadOnly';
 
 function isKind(e: unknown, kind: MatbotErrorKind): boolean {
   return typeof e === 'object' && e !== null && (e as Record<string, unknown>)[BRAND] === kind;
@@ -102,3 +102,26 @@ export function promptCancelledError(message = 'User cancelled — cannot procee
 export function isPromptCancelledError(e: unknown): e is PromptCancelledError {
   return isKind(e, 'PromptCancelled');
 }
+
+/**
+ * Thrown by a `Store` write when the target item is not owned by the current principal — e.g. a session
+ * shared read-only into another profile's partition (see `@matatbread/matbot-storage-profiles`). This is
+ * a per-operation condition, **not** a process fault: the turn pump catches it (via {@link isReadOnlyError},
+ * never `instanceof`) and surfaces it as a turn error rather than letting it escape the detached pump and
+ * crash the host. `namespace`/`id` name the item; `owner` is the owning principal id (`''` for the shared
+ * base/global partition).
+ */
+export interface ReadOnlyError extends Error {
+  matbot: 'ReadOnly';
+  readonly namespace: string;
+  readonly id:        string;
+  readonly owner:     string;
+}
+export function readOnlyError(namespace: string, id: string, owner: string): ReadOnlyError {
+  const e = new Error(`${namespace} "${id}" was shared by "${owner || 'global'}" and is read-only.`);
+  e.name = 'ReadOnlyError';
+  return Object.assign(e, { matbot: 'ReadOnly' as const, namespace, id, owner });
+}
+export function isReadOnlyError(e: unknown): e is ReadOnlyError {
+  return isKind(e, 'ReadOnly');
+}

package/src/hooks.ts

@@ -1,5 +1,5 @@
 import type {
-  Hook, HookPoint, Message, MessageContent, Session,
+  Hook, HookPoint, Message, MessageContent, Session, DeferredScreen,
   ScreenContext, ContributeContext, ToolCallContext, ToolCallResult, ToolResultContext, FollowupContext,
 } from './types.js';
 
@@ -88,9 +88,12 @@ export class HookRegistry {
 
   // screen folds across hooks: each sees the session as shaped so far, accumulates ephemeral, and
   // the first `abort` short-circuits (the partial session is returned so the caller can persist it).
-  async runScreen(ctx: Omit<ScreenContext, 'removeHook'>): Promise<{ session: Session; ephemeral: MessageContent[]; durable: MessageContent[]; markers: MessageContent[]; abort?: string }> {
+  async runScreen(ctx: Omit<ScreenContext, 'removeHook'>): Promise<{ session: Session; ephemeral: MessageContent[]; durable: MessageContent[]; markers: MessageContent[]; deferred: DeferredScreen[]; abort?: string }> {
     let session = ctx.session;
     const ephemeral: MessageContent[] = [];
+    // Raced verdicts handed back by hooks: the runner polls each without gating the turn (see
+    // DeferredScreen). Usually zero or one; an array so several racing hooks compose.
+    const deferred: DeferredScreen[] = [];
     // Handler-returned markers: appended to the session here (so they persist) and accumulated so the
     // runner can also emit them live — keeping a live draw and a reload identical.
     const handlerMarkers: MessageContent[] = [];
@@ -122,13 +125,14 @@ export class HookRegistry {
       if (r.ephemeral)                   ephemeral.push(...r.ephemeral);
       if (r.durable && r.durable.length) foldDurable(r.durable);
       if (r.markers && r.markers.length) appendMarkers(r.markers);
+      if (r.deferred)                    deferred.push(r.deferred);
       if (r.abort) {
         const drained = this.drainFailureMarkers(session);
-        return { session: drained.session, ephemeral, durable, markers: [...handlerMarkers, ...drained.markers], abort: r.abort };
+        return { session: drained.session, ephemeral, durable, markers: [...handlerMarkers, ...drained.markers], deferred, abort: r.abort };
       }
     }
     const drained = this.drainFailureMarkers(session);
-    return { session: drained.session, ephemeral, durable, markers: [...handlerMarkers, ...drained.markers] };
+    return { session: drained.session, ephemeral, durable, markers: [...handlerMarkers, ...drained.markers], deferred };
   }
 
   // contribute folds the outgoing array through each hook — a pure transform pipeline; the stored
@@ -169,17 +173,22 @@ export class HookRegistry {
   // turn), any durable markers (appended to the committed session by the pump), and any
   // retract-and-rerun requests. A turn can be popped only once, so multiple hooks' retraction
   // contexts merge into a single redo (in practice only one fires); `retract` is omitted when none did.
-  async runFollowup(ctx: Omit<FollowupContext, 'removeHook'>): Promise<{ resubmits: MessageContent[][]; markers: MessageContent[]; retract?: { context: MessageContent[] } }> {
-    const resubmits: MessageContent[][] = [];
-    const markers:   MessageContent[]   = [];
-    const retract:   MessageContent[]   = [];
+  async runFollowup(ctx: Omit<FollowupContext, 'removeHook'>): Promise<{ resubmits: MessageContent[][]; markers: MessageContent[]; retract?: { context: MessageContent[]; durable: MessageContent[] } }> {
+    const resubmits:    MessageContent[][] = [];
+    const markers:      MessageContent[]   = [];
+    const retractCtx:   MessageContent[]   = [];
+    const retractDur:   MessageContent[]   = [];
     for (const hook of this.hooks.get('followup') ?? []) {
       if (hook.on !== 'followup') continue;
       const r = await this.invoke(hook, () => hook.handler({ ...ctx, removeHook: () => this.removeOne('followup', hook) }));
       if (r?.resubmit)        resubmits.push(r.resubmit.content);
-      if (r?.retractAndRerun) retract.push(...r.retractAndRerun.context);
+      if (r?.retractAndRerun) {
+        if (r.retractAndRerun.context) retractCtx.push(...r.retractAndRerun.context);
+        if (r.retractAndRerun.durable) retractDur.push(...r.retractAndRerun.durable);
+      }
       if (r?.markers)         markers.push(...r.markers);
     }
-    return { resubmits, markers, ...(retract.length > 0 ? { retract: { context: retract } } : {}) };
+    const retracting = retractCtx.length > 0 || retractDur.length > 0;
+    return { resubmits, markers, ...(retracting ? { retract: { context: retractCtx, durable: retractDur } } : {}) };
   }
 }

package/src/plugin.ts

@@ -1,9 +1,10 @@
 import type {
-  FileStore, Vault, Message, ModelParameters,
+  FileStore, StoreChange, Principal, Vault, Message, ModelParameters,
   ProviderAdapter, ProviderConfig, ProviderRegistry, Tool, ToolRegistry, FrontendInfo,
   Store, Session, SystemContextRegistry, KnowledgeIndex, PromptFn, SessionRunner, Usage,
-  TypeScriptStripper, ToolTypeIndex, ToolPresenter,
+  TypeScriptStripper, ToolTypeIndex, ToolPresenter, SteeringPolicy,
 } from './types.js';
+import type { Routed } from './broadcast.js';
 import type { HookRegistry } from './hooks.js';
 
 export const PLUGIN_API_VERSION = '0.1';
@@ -14,6 +15,15 @@ export interface CompletionRequest {
   provider:    string;
   messages:    Message[];
   system?:     string;
+  /**
+   * @deprecated Per-call parameter overrides, shallow-merged over the provider config (request wins).
+   * It DOES work — both hosts (CLI + web-bundle) honour it — but it is a speculative affordance whose
+   * obvious use is an anti-pattern: a caller clamping tokens / disabling thinking for one call takes
+   * control away from the provider config, where parameters belong and stay user-editable. Prefer a
+   * dedicated provider profile (e.g. a `-classify` provider) instead of reaching for this. Kept, not
+   * removed, only because the surface is tiny and a genuine per-call need may yet appear. If you found
+   * this because you set it and it worked — reconsider whether a provider profile is the right home.
+   */
   parameters?: Partial<ModelParameters>;
   signal?:     AbortSignal;
 }
@@ -27,6 +37,9 @@ export interface SingleTurnRequest {
   provider: string;
   prompt:   string;
   system?:  string;
+  /** @deprecated Forwarded verbatim to {@link CompletionRequest.parameters}; same speculative
+   *  anti-pattern caveat — prefer a dedicated provider profile over per-call overrides. */
+  parameters?: Partial<ModelParameters>;
   signal?:  AbortSignal;
 }
 
@@ -106,6 +119,15 @@ export interface MatbotServices {
    *  whole turn snapshot. A plain registered service (not a swap-member); consumed as a member. See
    *  {@link ToolPresenter}. */
   readonly ToolPresenter?: ToolPresenter | undefined;
+  /** Optional partition-aware file-watch layer (cross-partition observation + per-connection visibility),
+   *  registered by a partitioning storage backend. Absent ⇒ frontends use the plain `fileStore.watch()`.
+   *  See {@link WatchVisibility}. */
+  readonly WatchVisibility?: WatchVisibility | undefined;
+  /** Optional steering policy: decides how a mid-turn submission under `mode: 'auto'` is disposed
+   *  (queue vs interrupt) and supplies the nudge folded onto an interrupt's continuation. Absent ⇒ the
+   *  runner uses its own defaults. A plain registered service, consumed by the runner as a member.
+   *  See {@link SteeringPolicy}. */
+  readonly SteeringPolicy?: SteeringPolicy | undefined;
 }
 
 /** The assembled machine: registry services wired to the fixed runtime — what `setup()` receives. */
@@ -166,10 +188,10 @@ export interface MatbotRuntime {
    * per-invocation through its proxy/member instead.
    *
    *   // cache the backend's documents; rebuild on every swap (own initial load was in setup())
-   *   services.mounted.consume({ key: 'StorageBackend', signal }, () => this.load());
+   *   services.mounted.observe({ key: 'StorageBackend', signal }, () => this.load());
    *
    *   // depend on a peer service that may not be present yet; seed now if it is, and on each (re)mount
-   *   services.mounted.consume({ key: 'SkillManager', replay: true, signal }, m => seed(m));
+   *   services.mounted.observe({ key: 'SkillManager', replay: true, signal }, m => seed(m));
    *
    * Contract guarantees only *eventual, ordered* delivery of each key's net presence transition — it
    * says nothing about timing: a mount may fire synchronously-ish or batch to a later quiescent edge, so
@@ -334,9 +356,11 @@ export interface MountConsumeOptions<K extends keyof MatbotServices> {
   readonly onUnmount?: (machine: MatbotMachine) => void | Promise<void>;
 }
 
-/** The mount-table consumer facet exposed on {@link MatbotRuntime.mounted}. */
+/** The mount-table consumer facet exposed on {@link MatbotRuntime.mounted}. `observe` (not `consume`)
+ *  so the verb `consume` means exactly one thing repo-wide — the detached stream drain on
+ *  {@link Subscribable}; this keyed, replay/onUnmount, edge-batched delivery is its own paradigm. */
 export interface Mounted {
-  consume<K extends keyof MatbotServices>(
+  observe<K extends keyof MatbotServices>(
     options: MountConsumeOptions<K>,
     handler: (machine: MountedMachine<K>) => void | Promise<void>,
   ): void;
@@ -385,7 +409,7 @@ export function createMountTable(getMachine: () => MatbotMachine): MountTable {
   };
 
   const mounted: Mounted = {
-    consume(options, handler) {
+    observe(options, handler) {
       const { key, replay, signal, onUnmount } = options;
       if (signal?.aborted === true) return;
       const interest: MountInterest = {
@@ -443,8 +467,9 @@ export function singleTurnRequest(req: SingleTurnRequest): CompletionRequest {
       id: '', traceId: '', createdAt: new Date().toISOString(), role: 'user',
       content: [{ type: 'text', text: req.prompt }],
     }],
-    ...(req.system !== undefined ? { system: req.system } : {}),
-    ...(req.signal !== undefined ? { signal: req.signal } : {}),
+    ...(req.system     !== undefined ? { system: req.system } : {}),
+    ...(req.parameters !== undefined ? { parameters: req.parameters } : {}),
+    ...(req.signal     !== undefined ? { signal: req.signal } : {}),
   };
 }
 
@@ -478,6 +503,34 @@ export interface StorageBackend {
   close?(): Promise<void>;
 }
 
+/**
+ * The partition-aware file-watch layer, registered by a storage backend that partitions files per
+ * principal (the profiles backend). Consumed by a frontend firehose so it can (a) observe file events
+ * across *every* partition, each stamped with the {@link Routed} origin that produced it, and (b) decide,
+ * per SSE connection, whether a given event is visible to that connection's principal. Absent ⇒ no
+ * partitioning: the frontend falls back to the plain single-stream `fileStore.watch()` with no filter.
+ * The origin/visibility split is generic (files today; the same shape serves skills/stores later).
+ */
+export interface WatchVisibility {
+  /** Every partition's file events, merged into one stream, each a self-describing {@link StoreChange}
+   *  (routing namespace `'files'`, the file id, and the {@link FileMetaData} in `detail`) tagged with the
+   *  origin partition — so the firehose filters and routes files through the same predicate as any stream. */
+  watchFiles(signal?: AbortSignal): AsyncIterable<Routed<StoreChange>>;
+  /**
+   * The per-connection visibility predicate for ANY partitioned event stream (files, skills, …): would a
+   * connection owned by `viewer` see the change to (`namespace`, `id`) produced by `origin`? True iff the
+   * viewer routes that namespace to the same partition as `origin` — `route(viewer, namespace) ===
+   * route(origin, namespace)` — OR the item is shared INTO the viewer's partition (the owner edits a
+   * shared-in item: origin=owner ≠ the viewer's route, yet the viewer holds a live link to it). This yields
+   * the intended behavior uniformly: global/base events for namespaces the viewer has NOT isolated,
+   * own-partition events for those it has, plus live updates to items shared in from another partition.
+   * `origin` may be a partition principal (files, tagged by the merge) or the acting principal (skills,
+   * stamped at write) — routing both sides makes either correct. `undefined` origin ⇒ base. `id` is the
+   * store id of the changed item; it drives the shared-in check.
+   */
+  visible(viewer: Principal, namespace: string, id: string, origin: Principal | undefined): boolean;
+}
+
 // ── Plugin interface ──────────────────────────────────────────────────────────
 
 /**

package/src/types.ts

@@ -223,9 +223,9 @@ export type SessionStatus = 'active' | 'archived' | 'pinned';
 export interface Session {
   id:                    string;
   version:               string;
-  ownerPrincipalId:      string;
-  actorPrincipalId?:     string;
-  persona?:              string;
+  // Legacy: persisted sessions may still carry `ownerPrincipalId` / `actorPrincipalId` / `persona`.
+  // They were never read — ownership-at-rest is structural (the storage partition), resolved via the
+  // backend, not a field. Left undeclared; old data keeps them harmlessly as excess properties.
   title?:                string;
   status:                SessionStatus;
   contexts:              string[];
@@ -254,7 +254,6 @@ export interface SystemContextRegistry {
 
 export interface RunConfig {
   provider:   string;
-  persona?:   string;
   sessionId?: string;
   traceId?:   string;
 }
@@ -311,8 +310,47 @@ export interface ScreenContext {
   /** Unregister the hook currently running. For one-shot hooks that should fire at most once. */
   removeHook(): void;
 }
+/**
+ * A raced screen verdict the runner folds in WITHOUT gating the turn on it. A `screen` hook that starts
+ * expensive work concurrently (e.g. a triggers classifier judging the user message) returns immediately
+ * and hands back one of these instead of blocking on it. The runner polls `claim()` — synchronously,
+ * never awaiting — at each turn-loop edge (before a provider call, on every stream event, and just
+ * before committing). The first time `claim()` returns blocks (the work has settled WITH a correction),
+ * the runner DISCARDS the uncommitted in-progress response and re-runs the loop with those blocks
+ * tail-folded as ephemeral context — an in-situ redo: no store pop, no retraction marker, cleaner than a
+ * post-commit retract. Because the mid-stream poll runs before each event is emitted, a verdict faster
+ * than time-to-first-token is caught before any token reaches the frontend (the clean path); a slower
+ * one aborts the in-flight provider request, saving the unstreamed remainder. If it never fires before
+ * the turn commits, the turn commits normally and any correction is left to a post-commit `followup`.
+ *
+ * `claim()` MUST be exactly-once: return the correction on the first successful poll and `undefined`
+ * forever after (not settled, no correction, or already claimed). The hook uses that single delivery to
+ * coordinate with its own post-commit path — a claimed verdict is never also delivered by `followup`.
+ */
+export interface DeferredScreen {
+  claim(): DeferredCorrection | undefined;
+}
+/**
+ * A claimed raced-verdict correction. `ephemeral` is tail-folded onto the re-run's outgoing messages
+ * and never persisted (the transient "for this answer only" twin); `durable` is folded onto the turn's
+ * user message — persisted, visible (the hook marks it `origin: 'robo'`), and carried live as a
+ * `robo-user` event — so it updates the conversation rather than informing one answer (a `contextual`
+ * trigger's semantics, preserved even though the verdict now lands mid-turn instead of before it). At
+ * least one is non-empty when returned.
+ */
+export interface DeferredCorrection {
+  ephemeral?: MessageContent[];
+  durable?:   MessageContent[];
+}
 export interface ScreenResult {
   session?:   Session;
+  /**
+   * A raced verdict the runner folds in without gating on it (see {@link DeferredScreen}). Lets a
+   * screen hook race expensive work — a classifier — against generation: return immediately, hand this
+   * back, and the runner restarts the turn in-situ if the verdict fires before commit. A hook that
+   * would rather gate the turn (block until the verdict) just returns `ephemeral` as usual instead.
+   */
+  deferred?:  DeferredScreen;
   /** Turn-scoped context appended onto the tail of this turn's outgoing messages (the freshest
    *  input the model reads), never persisted. At the tail, not a system prefix, so a directive
    *  keeps its salience and the cached system/history prefix stays stable across turns. */
@@ -402,8 +440,13 @@ export interface FollowupResult {
    * defect that the injected context dissolves on the redo, so it won't re-fire; `resubmitDepth` (a
    * redo carries parent+1) caps an ill-formed one. `resubmit` and `retractAndRerun` are independent
    * capabilities — a single turn returning both is not expected, but both head-enqueue if it does.
+   *
+   * `context` is folded EPHEMERALLY onto the redo (for-this-answer-only). `durable` is instead folded
+   * onto the re-run's user message — persisted, visible (mark it `origin: 'robo'`), carried live as a
+   * `robo-user` event — so a `contextual`-kind correction updates the conversation durably even when it
+   * lands post-commit. At least one of the two is present.
    */
-  retractAndRerun?: { context: MessageContent[] };
+  retractAndRerun?: { context?: MessageContent[]; durable?: MessageContent[] };
   /**
    * Durable `marker` blocks to append to the just-committed session (LLM-invisible; for tracing /
    * cross-references). The second durable-write capability after `screen` — safe here for the same
@@ -739,6 +782,26 @@ export interface FileHandle extends FileMetaData {
 
 export type FileEvent = FileMetaData & { changed: Array<keyof FileMetaData> };
 
+/**
+ * The generic, self-describing change envelope every partitioned CRUD stream emits (files, skills, and
+ * future partitioned stores) — the payload half of a {@link Routed} event, whose `origin` carries the
+ * acting principal/partition. It supersedes the per-stream bespoke shapes (the old `SkillEvent`, the raw
+ * `FileEvent` on the wire) so a frontend firehose can filter and route every stream through ONE predicate.
+ *
+ * `namespace` is the ROUTING namespace the change lives under — `'files'`, `'skills'`, or a document
+ * namespace — NOT a content sub-namespace (a file's own `metadata.namespace`, e.g. `'workspace'`, rides in
+ * `detail`). Pairing `namespace` + `id` is exactly what `WatchVisibility.visible` needs to decide, per
+ * connection, whether the viewer routes that item to the same partition (or has it shared in). `detail`
+ * carries an optional rich payload for in-place UI updates — a file change ships its {@link FileMetaData}
+ * so a sidebar row can update its size without a re-fetch; a skill change needs none (a refresh ping).
+ */
+export interface StoreChange {
+  readonly operation: 'saved' | 'deleted';
+  readonly namespace: string;
+  readonly id:        string;
+  readonly detail?:   unknown;
+}
+
 export interface FileFilter {
   sessionId?:     string;
   mimeType?:      string;
@@ -931,6 +994,13 @@ export type PipelineEvent =
   // threw), carried live so a frontend renders them without waiting for a session reload. The blocks
   // are already persisted in the session; this event is purely the live-delivery channel.
   | { type: 'marker';         content: MessageContent[]; traceId: string }
+  // A mid-turn steer that INTERRUPTED the running turn (see `SteeringPolicy`). Emitted synchronously
+  // when the steer is accepted, so the new user bubble lands in correct stream order and a frontend
+  // knows the imminent `aborted` (reason 'steer') on `interruptedTraceId` is a yield, not a dead-end:
+  // keep that turn's partial work rendered and expect a continuation. `traceId`/`rootTraceId` identify
+  // the steer submission itself (the continuation turn). Late subscribers reconstruct the bubble from
+  // the pump's per-turn `queued` replay seed / committed store order — this is purely live delivery.
+  | { type: 'steer';          content: MessageContent[]; interruptedTraceId: string; traceId: string; rootTraceId: string }
   | { type: 'error';          error: string;          traceId: string }
   | { type: 'system-context'; text: string;           traceId: string };
 
@@ -969,6 +1039,11 @@ export interface SubmitOpenOpts extends OpenOpts {
   /** When true, this submission may be merged with others drained in the same batch. Default false
    *  (queue mode: one turn per submission). */
   concatQueue?: boolean;
+  /** Disposition for a submission arriving while a turn is running (see {@link SteeringPolicy}):
+   *  'queue' waits for the turn boundary (default), 'interrupt' stops the running turn — keeping its
+   *  committed partial work — and runs this next, 'auto' defers to the registered SteeringPolicy (else
+   *  the host default). Meaningless when nothing is running (degrades to a plain enqueue). */
+  mode?:        SteeringMode;
   /** Interactive prompt implementation for this submission's turn. The frontend owns delivery —
    *  it must target the frontend's per-session client connections, not a single request. */
   prompt?:      PromptFn;
@@ -992,3 +1067,35 @@ export interface SessionRunner {
    *  behind it. `busy` is `running || queued > 0`. */
   status(sessionId: string): { busy: boolean; running: boolean; queued: number };
 }
+
+// ── Steering ────────────────────────────────────────────────────────────────────
+
+/** Disposition of a submission that arrives while a turn is running. `interrupt` stops the running
+ *  turn (its committed partial work is preserved) and runs the new message next; `queue` waits for the
+ *  turn boundary. */
+export type SteeringDecision = 'queue' | 'interrupt';
+/** The wire-level request (see `SubmitOpenOpts.mode`). `auto` defers the decision to the registered
+ *  {@link SteeringPolicy} (else the host default). */
+export type SteeringMode = SteeringDecision | 'auto';
+
+/**
+ * How the runner disposes of a mid-turn submission under `mode: 'auto'`, and how an interrupt's
+ * continuation is nudged. An optional, registerable service ({@link MatbotServices}); absent ⇒ the
+ * runner uses its own defaults. Both members are optional so a plugin may override one, the other, or
+ * both. `classify` is deliberately NOT assumed to be an LLM — a regex or a semantic classifier is a
+ * first-class implementation (return synchronously); an LLM `singleTurn` returns a promise.
+ */
+export interface SteeringPolicy {
+  /**
+   * Consulted only for `mode: 'auto'` while a turn is running. `session` is the COMMITTED session
+   * (history up to the running turn's start — the in-flight partial is not reachable at submit time);
+   * `steer` is the incoming submission. Return synchronously (regex) or async (semantic / singleTurn).
+   * Absent ⇒ the host default disposition.
+   */
+  classify?(ctx: { session: Session; steer: MessageContent[] }): SteeringDecision | Promise<SteeringDecision>;
+  /**
+   * The ephemeral "keep going, noting the above" context folded onto an interrupt's continuation turn
+   * (never persisted). Absent ⇒ the host default nudge.
+   */
+  nudge?(ctx: { session: Session; steer: MessageContent[] }): MessageContent[];
+}