@matatbread/matbot-core 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"
   },
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@matatbread/matbot-plugin-api": "^0.3.4"
+    "@matatbread/matbot-plugin-api": "^0.3.5"
   },
   "devDependencies": {
     "typescript": "^6.0.3"

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,6 +2,7 @@ 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';
@@ -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
@@ -230,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
@@ -276,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);
             }
@@ -289,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,
@@ -348,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',
@@ -357,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.
@@ -365,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 });
 
@@ -377,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 } : {}),
                 });
               }
@@ -391,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
@@ -416,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);
       }