@matatbread/matbot-plugin-api 0.4.17 → 0.4.18

package/package.json

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

package/src/hooks.ts

@@ -59,16 +59,30 @@ export class HookRegistry implements HookRegistrar {
   // than per-channel because it is the one place every handler invocation passes through — and because
   // the site must be in force when the handler *starts*, so work it kicks off detached stays attributed
   // to it however late it settles.
-  private async invoke<R>(hook: Hook, run: () => R | Promise<R>): Promise<R | undefined> {
+  private async invoke<R>(hook: Hook, signal: AbortSignal, run: () => R | Promise<R>): Promise<R | undefined> {
     try {
       return await withUsageSite(
         { kind: 'hook', channel: hook.on, ...(hook.pluginName !== undefined ? { plugin: hook.pluginName } : {}) },
         run,
       );
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
       const owner = hook.pluginName !== undefined ? ` from "${hook.pluginName}"` : '';
-      console.error(`[matbot] ${hook.on} hook${owner} threw; skipping it for this turn:`, message);
+      // An aborted turn (a steer, a cancel) rejects whatever was awaiting its signal with the abort REASON —
+      // often a bare token like 'steer', not an Error — which logged as a failure whose whole message was
+      // "steer". The hook was cut off, not broken, so it is said as such and leaves no failure marker.
+      //
+      // Which is asked of the THROWN value, not of the signal alone. `aborted` stays true for the rest of
+      // the turn, so testing it alone reported every later throw as a cut-off — masking a genuine hook bug,
+      // marker and stack included, from the first steer onwards. Interrupt is the default disposition for a
+      // mid-turn message, so that window is the common case, not a corner of one. A cut-off throw is either
+      // the reason itself (what a signal rejects with) or the standard AbortError.
+      if (signal.aborted && (err === signal.reason || (err as { name?: unknown } | null)?.name === 'AbortError')) {
+        console.warn(`[matbot] ${hook.on} hook${owner} was cut off: its turn was aborted (reason: ${describeThrown(signal.reason)}).`);
+        return undefined;
+      }
+      const message = err instanceof Error ? err.message : `threw a non-Error value: ${describeThrown(err)}`;
+      // The Error itself, not its message, so the log carries the stack — the message alone rarely says where.
+      console.error(`[matbot] ${hook.on} hook${owner} threw; skipping it for this turn:`, err instanceof Error ? err : message);
       if (!this.markedFailures.has(hook)) {
         this.markedFailures.add(hook);
         this.pendingFailureMarkers.push({
@@ -134,7 +148,7 @@ export class HookRegistry implements HookRegistrar {
       session = folded;
     };
     for (const hook of this.on('screen')) {
-      const r = await this.invoke(hook, () => hook.handler({ ...ctx, session, removeHook: () => this.removeOne('screen', hook) }));
+      const r = await this.invoke(hook, ctx.signal, () => hook.handler({ ...ctx, session, removeHook: () => this.removeOne('screen', hook) }));
       if (!r) continue;
       if (r.session)                     session = r.session;
       if (r.ephemeral)                   ephemeral.push(...r.ephemeral);
@@ -155,7 +169,7 @@ export class HookRegistry implements HookRegistrar {
   async runContribute(ctx: Omit<ContributeContext, 'removeHook'>): Promise<Message[]> {
     let outgoing = ctx.outgoing as Message[];
     for (const hook of this.on('contribute')) {
-      const r = await this.invoke(hook, () => hook.handler({ ...ctx, outgoing, removeHook: () => this.removeOne('contribute', hook) }));
+      const r = await this.invoke(hook, ctx.signal, () => hook.handler({ ...ctx, outgoing, removeHook: () => this.removeOne('contribute', hook) }));
       if (r) outgoing = r;
     }
     return outgoing;
@@ -164,7 +178,7 @@ export class HookRegistry implements HookRegistrar {
   // toolcall stops at the first hook that rejects or aborts; the rest don't run.
   async runToolCall(ctx: Omit<ToolCallContext, 'removeHook'>): Promise<ToolCallResult> {
     for (const hook of this.on('toolcall')) {
-      const r = await this.invoke(hook, () => hook.handler({ ...ctx, removeHook: () => this.removeOne('toolcall', hook) }));
+      const r = await this.invoke(hook, ctx.signal, () => hook.handler({ ...ctx, removeHook: () => this.removeOne('toolcall', hook) }));
       if (r && (r.rejectTool || r.abort)) return r;
     }
     return {};
@@ -175,7 +189,7 @@ export class HookRegistry implements HookRegistrar {
   async runToolResult(ctx: Omit<ToolResultContext, 'removeHook'>): Promise<unknown> {
     let result = ctx.result;
     for (const hook of this.on('toolresult')) {
-      const r = await this.invoke(hook, () => hook.handler({ ...ctx, result, removeHook: () => this.removeOne('toolresult', hook) }));
+      const r = await this.invoke(hook, ctx.signal, () => hook.handler({ ...ctx, result, removeHook: () => this.removeOne('toolresult', hook) }));
       if (r) result = r.result;
     }
     return result;
@@ -195,7 +209,7 @@ export class HookRegistry implements HookRegistrar {
     // asking to pop and re-run with nothing added was answered by doing nothing at all, silently.
     let retracting = false;
     for (const hook of this.on('followup')) {
-      const r = await this.invoke(hook, () => hook.handler({ ...ctx, removeHook: () => this.removeOne('followup', hook) }));
+      const r = await this.invoke(hook, ctx.signal, () => hook.handler({ ...ctx, removeHook: () => this.removeOne('followup', hook) }));
       if (r?.resubmit)        resubmits.push(r.resubmit.content);
       if (r?.retractAndRerun) {
         retracting = true;
@@ -207,3 +221,9 @@ export class HookRegistry implements HookRegistrar {
     return { resubmits, markers, ...(retracting ? { retract: { context: retractCtx, durable: retractDur } } : {}) };
   }
 }
+
+function describeThrown(value: unknown): string {
+  if (value instanceof Error) return `${value.name}: ${value.message}`;
+  if (typeof value === 'string') return JSON.stringify(value);
+  try { return JSON.stringify(value) ?? String(value); } catch { return String(value); }
+}

package/src/index.ts

@@ -29,10 +29,10 @@ export { PLUGIN_API_VERSION } from './plugin.js';
 // the host's job (`/host`).
 export { currentPrincipal, tryCurrentPrincipal, runAs } from './principal-context.js';
 
-// Notifications: publish, consume, and the two kinds plugin-api itself defines. Minting the process
+// Notifications: publish, consume, and the three kinds plugin-api itself defines. Minting the process
 // notifier is the host's job (`/host`).
 export type * from './notify.js';
-export { ItemChangeKind, RegistryChangeKind, notifyingStore } from './notify.js';
+export { ItemChangeKind, RegistryChangeKind, SessionAppendKind, notifyingStore } from './notify.js';
 
 // The quiescent edge: defer work to the next moment it is safe to touch machine state. A plugin that has
 // something to do after the current operation — a store edit the running turn would otherwise write over —

package/src/notify.ts

@@ -89,7 +89,22 @@ export interface RegistryChange extends NotificationBase {
 }
 
 /**
- * The wire tags for the two kinds defined here. A `kind` is a globally-scoped token — unlike a type
+ * Messages were appended to a session outside any turn (see `SessionAppender`) — not by the session's
+ * own pump, so nothing on that session's turn stream says so.
+ *
+ * The same write raises an {@link ItemChange} for the session; this exists beside it because it carries
+ * the one thing a re-read cannot recover: WHICH messages arrived this way. A turn adds messages too, so a
+ * consumer diffing the document would have to keep a copy of it to tell them apart. A frontend draws
+ * these into the open conversation; a chat bridge forwards them to the chat the session belongs to.
+ * Identity only, as ever — a consumer re-reads the session for the content.
+ */
+export interface SessionAppend extends NotificationBase {
+  readonly sessionId:  string;
+  readonly messageIds: readonly string[];
+}
+
+/**
+ * The wire tags for the kinds defined here. A `kind` is a globally-scoped token — unlike a type
  * name, which an importer can rename out of a clash — so these exist to give one back: import the const
  * under whatever local name suits (`import { ItemChangeKind as Changed }`) and use it as a `case` label
  * or in a filter. `satisfies` ties each to a real key, so a typo fails the build here instead of
@@ -97,6 +112,7 @@ export interface RegistryChange extends NotificationBase {
  */
 export const ItemChangeKind     = '@matatbread/matbot-plugin-api#ItemChange'     satisfies keyof Notifications;
 export const RegistryChangeKind = '@matatbread/matbot-plugin-api#RegistryChange' satisfies keyof Notifications;
+export const SessionAppendKind  = '@matatbread/matbot-plugin-api#SessionAppend'  satisfies keyof Notifications;
 
 /**
  * The registry of notification shapes, keyed by `kind` — augment it exactly like `MatbotServices` /
@@ -128,6 +144,7 @@ export const RegistryChangeKind = '@matatbread/matbot-plugin-api#RegistryChange'
 export interface Notifications {
   '@matatbread/matbot-plugin-api#ItemChange':    ItemChange;
   '@matatbread/matbot-plugin-api#RegistryChange': RegistryChange;
+  '@matatbread/matbot-plugin-api#SessionAppend':  SessionAppend;
 }
 
 /** A notification as a consumer sees it: the arm, plus the `kind` its registry key supplies. Grafting

package/src/plugin.ts

@@ -3,6 +3,7 @@ import type {
   ProviderAdapter, ProviderConfig, ProviderRegistry, Tool, ToolRegistry, FrontendInfo,
   Store, Session, SystemContextRegistry, KnowledgeIndex, PromptFn, SessionRunner, Usage, HookRegistrar,
   TypeScriptStripper, FunctionRunner, ToolTypeIndex, ToolPresenter, SteeringPolicy, UserContent, PermissionGate,
+  SessionAppender, EphemeralRun,
 } from './types.js';
 import type { Notifications, Notifier } from './notify.js';
 
@@ -193,6 +194,11 @@ export interface MatbotServices {
    *  one; absent ⇒ such code runs unbounded, as it must where synchronous code cannot be interrupted.
    *  See {@link FunctionRunner}. */
   readonly FunctionRunner?: FunctionRunner | undefined;
+  /** Appends messages to a session without running a turn, once no turn holds it. The host seeds
+   *  one wherever it holds the session store; a background job registers one that forwards to its parent.
+   *  Absent ⇒ this process has no safe way to append (a job spawned without that channel), and a caller
+   *  refuses rather than writing the store itself. See {@link SessionAppender}. */
+  readonly SessionAppender?: SessionAppender | undefined;
 }
 
 /** The assembled machine: registry services wired to the fixed runtime — what `setup()` receives. */
@@ -294,6 +300,22 @@ export interface MatbotRuntime {
   /** Per-session turn serialiser. Frontends submit and observe through this rather than calling
    *  runSession directly, so concurrent submits queue instead of clobbering the session. */
   readonly run?:            SessionRunner | undefined;
+  /**
+   * A private runner over its own in-memory session store, for a turn that should leave no trace: a
+   * background job's run, a demonstration whose transcript is analysed and thrown away. Nothing it holds
+   * is persisted or announced, and nothing outlives the returned object — so create the session in
+   * `sessions` before `run.open`, and drop both when done.
+   *
+   * Tools on this runner still reach the machine's real stores through what they captured at setup:
+   * `session_action list` sees the user's conversations, and `session_edit` of the ephemeral session
+   * refuses, finding nothing. `appender` is how such a turn reports somewhere real — it arrives as
+   * `ToolContext.appender`, and its `defaultSessionId` is where an append naming no session goes.
+   *
+   * Its turns hold the machine as any turn does. Its tools use the live machine, so a storage swap or an
+   * unload waits until the run ends. Its appends, and its edits of other sessions, do not: each waits only
+   * for a turn of the session it writes (`SessionRunner.write`).
+   */
+  ephemeral?(opts?: { appender?: SessionAppender }): EphemeralRun;
   readonly files?:          FileStore;
   readonly hooks:           HookRegistrar;
   readonly tools:           ToolRegistry;

package/src/types/events.ts

@@ -55,6 +55,18 @@ export type TurnEvent =
   // 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 }
 
+  // A mid-turn submission answered IN PARALLEL with the running turn (`mode: 'parallel'`), which is left
+  // untouched. It runs on a private copy of the session's completed turns — everything before
+  // `runningTraceId`'s user message — so its events (this one first, then its own turn's, under
+  // `traceId`) are live delivery only: its tool calls stay in that copy and are never persisted, and its
+  // terminal's `session` is the COPY, not this session. What survives is the submission and its final
+  // reply, written back as a user/assistant pair and announced by `merged`.
+  | { type: 'parallel';       content: MessageContent[]; runningTraceId: string; traceId: string; rootTraceId: string }
+  // A parallel turn's pair has been written into the session. `into` is the turn that was running when
+  // it landed: the pair went into that turn's history, ahead of its user message (where the copy it ran
+  // on ended), at a round boundary. Absent ⇒ nothing was running and it was appended.
+  | { type: 'merged';         traceId: string; into?: string }
+
   // ── terminals: exactly one per turn ──
   | { type: 'done';           session: Session;       traceId: string }
   | { type: 'aborted';        reason: string; session: Session; traceId: string }

package/src/types/messages.ts

@@ -181,13 +181,13 @@ export interface Session {
   // Legacy: persisted sessions may still carry `ownerPrincipalId` / `actorPrincipalId` / `persona`, and
   // `contexts` (a required-but-never-read `string[]`, dropped at 0.4.0 — system context is contributed by
   // SystemContextContributor, not carried on the session). 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;
-  messages:              Message[];
-  parentSessionId?:      string;
-  branchPointMessageId?: string;
-  createdAt:             ISODate;
-  updatedAt:             ISODate;
+  // (the storage partition), resolved via the backend, not a field. Likewise `parentSessionId` /
+  // `branchPointMessageId` (dropped at 0.4.18): a fork or split records its relation as a marker in the
+  // session (`peerSessionId` + `targetMsg`), which is what a frontend reads. Left undeclared; old data
+  // keeps them harmlessly as excess properties.
+  title?:    string;
+  status:    SessionStatus;
+  messages:  Message[];
+  createdAt: ISODate;
+  updatedAt: ISODate;
 }

package/src/types/session-append.ts

@@ -0,0 +1,47 @@
+// ── Session appends ─────────────────────────────────────────────────────────────
+
+/**
+ * A message added to a session outside any turn — a background job's report, an answer merged back
+ * from elsewhere.
+ *
+ * Deliberately narrow: plain text, user or assistant. An append arrives unasked into a history that is
+ * replayed to a provider on every later turn, so the arms that carry protocol state are excluded by
+ * construction — a `tool-use` without its result, or a `thinking` block whose signature it did not
+ * earn, would fail every turn after it rather than this one.
+ */
+export interface AppendMessage {
+  role:      'user' | 'assistant';
+  content:   Array<{ type: 'text'; text: string; origin?: 'robo' }>;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AppendResult {
+  sessionId:  string;
+  /** The ids the appended messages will carry — minted at acceptance, so a caller can name them before
+   *  the write has landed. */
+  messageIds: string[];
+  /** The write waits for a turn holding the session, so it has not landed yet. Absent ⇒ it has. */
+  deferred?:  true;
+}
+
+/**
+ * Adds messages to the end of a session without running a turn.
+ *
+ * A running turn owns its session: the runner works on an in-memory copy and writes it back whole when
+ * the turn ends, which is what keeps the stored session a set of completed turns. So an append is written
+ * by the session's runner once no turn holds that session (`SessionRunner.write`), and announced then as a
+ * `SessionAppend` notification. When no turn holds it, that is at once, and the append settles once
+ * written, reporting a write that could not land. When one does, it settles once **accepted**: the caller
+ * may be that very turn, and awaiting the write from inside it would deadlock.
+ *
+ * The host seeds one in every process that holds the session store. A background job does not get
+ * one: it shares the store's medium with its parent but none of the parent's pumps, so a write it made
+ * would race them unseen. A job registers one that forwards to its parent instead; with neither, a
+ * caller refuses rather than writing.
+ */
+export interface SessionAppender {
+  /** Where an append naming no session goes, when this process has a destination of its own — a
+   *  background job's: the conversation it reports to. Absent ⇒ the caller supplies its own session. */
+  readonly defaultSessionId?: string;
+  append(sessionId: string | undefined, messages: readonly AppendMessage[]): Promise<AppendResult>;
+}

package/src/types/session-runner.ts

@@ -4,15 +4,16 @@ import type { MimeType } from './primitives.js';
 import type { Principal } from './principal.js';
 import type { SteeringMode } from './steering.js';
 import type { PromptFn } from './tools.js';
+import type { Store } from './storage.js';
 
 // ── Session runner ──────────────────────────────────────────────────────────────
 
 /**
  * A view onto a session returned by `SessionRunner.open`. `session` is the authoritative
- * server-side state — committed messages plus an overlay of any queued-but-not-yet-run
- * submissions (each carrying `metadata.pending: true`). `events` is a lazy, per-session live
- * tap: accessing it subscribes to the turn event stream from now (replaying the in-flight
- * turn, if any); never touching it costs nothing.
+ * server-side state — committed messages only, ending at the running turn's user message. The
+ * in-flight turn and any queued submissions are the delta, delivered over `events`, never overlaid
+ * here. `events` is a lazy, per-session live tap: accessing it subscribes to the turn event stream
+ * from now (replaying the in-flight turn, then the queue); never touching it costs nothing.
  */
 export interface SessionView {
   session:        Session;
@@ -73,8 +74,9 @@ export interface SubmitOpenOpts extends OpenOpts {
   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). */
+   *  committed partial work — and runs this next, 'parallel' answers it now beside the running turn
+   *  (see the `parallel` event), '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. */
@@ -89,13 +91,54 @@ export interface SubmitOpenOpts extends OpenOpts {
  */
 export interface SessionRunner {
   open(opts: OpenOpts | SubmitOpenOpts): Promise<SessionView>;
-  /** Abort the running turn (if any) and drop all queued submissions, emitting `cancelled` for each. */
+  /** Abort the running turn (if any), any `parallel` turns beside it, and drop all queued submissions,
+   *  emitting `cancelled` for each. */
   abort(sessionId: string): void;
+  /** Stop ONE `parallel` turn, leaving the running turn, the queue and any other parallel turns alone.
+   *  A parallel turn is the only kind that can be stopped individually: it runs on a nested runner with
+   *  a stop of its own, where a queued submission has not started and the running turn is what `abort`
+   *  and `cancelTurn` already address. It still settles and writes back its pair, carrying a note in
+   *  place of the reply — the submission was made, and dropping it would lose that. A no-op if no
+   *  parallel turn of the session carries this traceId. Deliberately its own method rather than an
+   *  optional argument to `abort`: an implementation that ignored the argument would silently stop
+   *  everything, which is the opposite of what the caller asked. */
+  abortParallel(sessionId: string, traceId: string): void;
   /** Abandon the running turn (if any) WITHOUT touching the queue — `pump` advances to the next
    *  queued submission, or idles. The "give up on this turn" path (a prompt cancel); contrast
    *  `abort`, which also clears the queue. A no-op if nothing is running. */
   cancelTurn(sessionId: string): void;
-  /** Snapshot of a session's live state: whether a turn is running and how many submissions wait
-   *  behind it. `busy` is `running || queued > 0`. */
-  status(sessionId: string): { busy: boolean; running: boolean; queued: number };
+  /** Snapshot of a session's live state: whether a turn is running, how many submissions wait behind
+   *  it, and how many `parallel` turns are in flight beside it. `busy` is any of the three. */
+  status(sessionId: string): { busy: boolean; running: boolean; queued: number; parallel: number };
+  /**
+   * Write session `sessionId` from outside its turns — an append, a rename, an edit of its history.
+   *
+   * A turn works on an in-memory copy of its session and writes it back whole when it ends, so a write
+   * landing during a turn is undone by that write-back. The runner is therefore the session's one writer:
+   * it runs `attempt` between that session's turns, in the order writes arrive, and no turn of the session
+   * starts until it has finished. Other sessions' turns do not delay it.
+   *
+   * `attempt` reads the session itself and writes it with compare-and-swap, which still answers any writer
+   * outside this runner (another process sharing the store). It resolves `false` only when that CAS lost,
+   * to be read and tried again, and `true` once finished, whether or not it wrote; it reports its own
+   * failures. `lost` is logged if every attempt loses. It runs as the principal in force at this call.
+   *
+   * It never runs before this call returns. See {@link SessionWrite} for when awaiting it is safe.
+   */
+  write(sessionId: string, attempt: () => Promise<boolean>, lost: string): SessionWrite;
+}
+
+/** A write handed to {@link SessionRunner.write}. */
+export interface SessionWrite {
+  /** A turn of the session was in progress, so the write waits for it to end. Then never await `done`
+   *  from that turn: its end is what the write is waiting for. */
+  deferred: boolean;
+  /** Settles once the write has run, however it ended (each failure is logged). Never rejects. */
+  done:     Promise<void>;
+}
+
+/** A runner and the store it alone reads and writes — see {@link MatbotRuntime.ephemeral}. */
+export interface EphemeralRun {
+  sessions: Store<Session>;
+  run:      SessionRunner;
 }

package/src/types/steering.ts

@@ -4,8 +4,9 @@ import type { MessageContent, Session } from './messages.js';
 
 /** 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';
+ *  turn boundary; `parallel` leaves the running turn alone and answers the new message at once on a
+ *  private copy of the session's completed turns, writing back only the message and its final reply. */
+export type SteeringDecision = 'queue' | 'interrupt' | 'parallel';
 /** 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';

package/src/types/tools.ts

@@ -4,6 +4,7 @@ import type { MatbotPlugin } from '../plugin.js';
 import type { JSONSchema } from './primitives.js';
 import type { PermissionRequest } from './permission.js';
 import type { Vault } from './vault.js';
+import type { SessionAppender } from './session-append.js';
 
 // ── Tools ─────────────────────────────────────────────────────────────────────
 
@@ -212,6 +213,12 @@ export interface ToolContext {
   workdir?:    string;
   configPath?: string;
   files?:      FileStore;
+  /**
+   * The appender belonging to the runner this turn is on, when it is not the machine's — an ephemeral
+   * run's ({@link MatbotRuntime.ephemeral}), whose session exists nowhere the machine's appender can
+   * reach. Prefer it over `services.SessionAppender`; absent ⇒ the machine's is the right one.
+   */
+  appender?:   SessionAppender;
   /** Prompt the user for input. The host provides a readline or form implementation. */
   prompt:      PromptFn;
   /**

package/src/types.ts

@@ -26,4 +26,5 @@ export * from './types/health.js';
 export * from './types/registries.js';
 export * from './types/events.js';
 export * from './types/session-runner.js';
+export * from './types/session-append.js';
 export * from './types/steering.js';