@matatbread/matbot-plugin-api 0.3.4 → 0.3.5

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.3.4",
+  "version": "0.3.5",
   "engines": {
     "node": ">=24.0.0"
   },

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,8 +1,8 @@
 import type {
-  FileStore, FileEvent, Principal, 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';
@@ -15,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;
 }
@@ -28,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;
 }
 
@@ -111,6 +123,11 @@ export interface MatbotServices {
    *  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. */
@@ -450,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 } : {}),
   };
 }
 
@@ -494,18 +512,23 @@ export interface StorageBackend {
  * 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 tagged with its origin partition. */
-  watchFiles(signal?: AbortSignal): AsyncIterable<Routed<FileEvent>>;
+  /** 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 an event in `namespace` produced by `origin`? Defined as
-   * `route(viewer, namespace) === route(origin, namespace)` — the two see it iff they route that namespace
-   * to the same partition. This yields the intended behavior uniformly: a viewer sees global/base events
-   * for namespaces it does NOT isolate, and only its own partition's events for namespaces it does.
+   * 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.
+   * 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, origin: Principal | undefined): boolean;
+  visible(viewer: Principal, namespace: string, id: string, origin: Principal | undefined): boolean;
 }
 
 // ── Plugin interface ──────────────────────────────────────────────────────────

package/src/types.ts

@@ -310,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. */
@@ -401,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
@@ -738,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;
@@ -930,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 };
 
@@ -968,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;
@@ -991,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[];
+}