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

package/src/assemble.ts

@@ -1,6 +1,6 @@
 import type {
   MatbotMachine, MatbotServices, MatbotPlugin, Store, Session, FileStore, StorageBackend, Vault, Notifier,
-  KnowledgeIndex, PermissionGate, PluginSettings, ProviderConfig, ProviderAdapter, SessionRunner, Tool, Usage,
+  KnowledgeIndex, PermissionGate, PluginSettings, ProviderConfig, ProviderAdapter, SessionRunner, SessionAppender, Tool, Usage,
 } from '@matatbread/matbot-plugin-api';
 import {
   forwardingProxy, makeSwappable, createMountTable, scheduleAtEdge, createNotifier, recordUsage, singleTurnRequest,
@@ -9,6 +9,7 @@ import {
 import type { SwapFn } from '@matatbread/matbot-plugin-api/host';
 import { notifyingStore, createMessage } from '@matatbread/matbot-plugin-api';
 import { mediumGuard } from './storage-base/medium-guard.js';
+import { MemoryStore } from './storage-base/memory-store.js';
 import { unifyServices } from './plugin.js';
 import { instantiateProvider, recordServiceKey, getPluginNameForSpecifier, getRegisteredPlugins } from './registry.js';
 import { installSettingsDefaults, installSettingsNotifier, makePluginSettings, settingsDefaultNamespaces } from './settings.js';
@@ -19,6 +20,7 @@ import type { ProviderRegistryImpl } from './provider-registry.js';
 import { SystemContextRegistryImpl } from './system-context.js';
 import { LookupKnowledgeIndex } from './knowledge/index.js';
 import { createSessionRunner } from './session-runner.js';
+import { createSessionAppender } from './session-append.js';
 import { createSingleTurnTool } from './single-turn.js';
 import { createAboutMatbotTool } from './about.js';
 import { addUsage } from './usage.js';
@@ -81,7 +83,7 @@ export interface AssembleOptions {
 export interface AssembledMachine {
   services: MatbotMachine;
   /** A session runner over any store — the shared one is `services.run`. */
-  makeRunner(store: Store<Session>): SessionRunner;
+  makeRunner(store: Store<Session>, opts?: { appender?: SessionAppender }): SessionRunner;
   /** Call once the configured plugins have loaded. */
   loaded(): void;
 }
@@ -176,7 +178,21 @@ export function assembleMachine(opts: AssembleOptions): AssembledMachine {
   // The host's file area doubles as the media store, so attachments work with no plugin. Seeded into the
   // registry rather than spelled on the base object, because `unifyServices` resolves an own property
   // first — a member spelled there is one `register()` could never reach.
-  const seed: Partial<MatbotServices> = { MediaStore: fileStore, ...opts.seed };
+  //
+  // The session appender is seeded the same way, in every process: it refuses in a background job, which
+  // registers its own (forwarding to its parent) over it — and unloading that reverts to refusing, which
+  // is the honest answer for a job with no channel. Late-bound, as `services` is built below. It writes
+  // through the shared runner, the one writer of the sessions in `services.sessions`.
+  const seed: Partial<MatbotServices> = {
+    MediaStore:      fileStore,
+    SessionAppender: createSessionAppender({
+      sessions:   () => services.sessions,
+      run:        () => services.run,
+      notifier:   () => services.Notifier,
+      isSubAgent: () => services.isSubAgent(),
+    }),
+    ...opts.seed,
+  };
   const serviceRegistry = new Map<string, unknown>(Object.entries(seed));
   // The validator lookup is late-bound and read per call: one is registered by a plugin long after the
   // builtins are seeded, and may be unloaded again. It wraps the executor, so every door — the runner,
@@ -306,6 +322,10 @@ export function assembleMachine(opts: AssembleOptions): AssembledMachine {
     sessions,
     files:    fileStore,
     get run() { return runner; },
+    ephemeral(opts) {
+      const store = new MemoryStore<Session>();
+      return { sessions: store, run: makeRunner(store, opts) };
+    },
     hooks,
     tools,
     systemContext,
@@ -328,8 +348,9 @@ export function assembleMachine(opts: AssembleOptions): AssembledMachine {
   };
 
   // Services a plugin registers after boot are resolved live, per turn.
-  const makeRunner = (store: Store<Session>): SessionRunner => createSessionRunner({
+  const makeRunner = (store: Store<Session>, extra?: { appender?: SessionAppender }): SessionRunner => createSessionRunner({
     store,
+    ...(extra?.appender !== undefined ? { appender: extra.appender } : {}),
     resolveProvider,
     tools,
     hooks,

package/src/ephemeral-turn.ts

@@ -0,0 +1,67 @@
+import type { EphemeralRun, PipelineEvent, Principal, PromptFn, Session, UserContent } from '@matatbread/matbot-plugin-api';
+
+/**
+ * One turn on an ephemeral run, from a fresh session to its committed transcript: what a background job
+ * and a skill demonstration each do, and each did for itself.
+ *
+ * Yields the turn's own events, up to and including its terminal, and returns the transcript.
+ *
+ * Three details are why this is shared rather than rewritten:
+ * - `signal` is wired to the run's `abort`. On `open` it only ends this view of the session, while the
+ *   turn runs on the runner's own controller. Without the wiring, a cancelled job or compile left its
+ *   turn calling tools after its caller had gone.
+ * - A caller that stops reading before the terminal aborts the turn for the same reason.
+ * - So does reaching the terminal, which is NOT the end of the run: `followup` is post-commit, so a hook
+ *   that resubmits or retracts enqueues a further turn on this runner AFTER the terminal this returns on.
+ *   Left armed, it ran on unobserved — calling tools, and appending through the run's appender — past the
+ *   transcript its caller was handed and past a cancel that no longer reached it. One turn means one.
+ * - An `error` terminal carries no session, so the transcript is then recovered from the run's store.
+ *
+ * `sessionId` is for a caller that names the session before the turn starts, to log or check it.
+ */
+export async function* runEphemeralTurn(
+  ephemeral: EphemeralRun,
+  opts: {
+    content:    UserContent[];
+    provider:   string;
+    principal:  Principal;
+    signal:     AbortSignal;
+    prompt?:    PromptFn;
+    sessionId?: string;
+  },
+): AsyncGenerator<PipelineEvent, Session | undefined> {
+  const now = new Date().toISOString();
+  const id  = opts.sessionId ?? crypto.randomUUID();
+  await ephemeral.sessions.set(id, { id, version: crypto.randomUUID(), status: 'active', messages: [], createdAt: now, updatedAt: now });
+
+  const view = await ephemeral.run.open({
+    sessionId: id, signal: opts.signal, provider: opts.provider, principal: opts.principal, content: opts.content,
+    ...(opts.prompt !== undefined ? { prompt: opts.prompt } : {}),
+  });
+  const stop = (): void => { ephemeral.run.abort(id); };
+  opts.signal.addEventListener('abort', stop, { once: true });
+  if (opts.signal.aborted) stop();
+
+  let final: Session | undefined;
+  try {
+    for await (const ev of view.events) {
+      // To `idle` — the run quiescing — not to this turn's terminal. `followup` is post-commit, so a hook
+      // that resubmits or retracts enqueues a FURTHER turn on this runner after the terminal, and stopping
+      // at the terminal left it running with nobody watching: appending through the run's appender, calling
+      // tools, past the transcript the caller was handed and past a cancel that no longer reached it.
+      // Aborting at the terminal does not close that either — the pop happens before the hook enqueues, so
+      // the resubmission is queued after the drain and runs anyway. Waiting is what makes the run's work
+      // the caller's: bounded by MAX_RESUBMIT_DEPTH, cancellable throughout, and counted.
+      if (ev.type === 'idle') break;
+      if (!('traceId' in ev) || ev.traceId !== view.traceId) continue;
+      if (ev.type === 'done' || ev.type === 'aborted') final = ev.session;
+      yield ev;
+    }
+  } finally {
+    opts.signal.removeEventListener('abort', stop);
+    stop();
+  }
+  // The store, not the terminal's session: a followup turn commits after it, and the transcript is meant to
+  // be everything the run did. `final` covers a store that has gone from under it.
+  return (await ephemeral.sessions.get(id)) ?? final;
+}

package/src/index.ts

@@ -23,7 +23,7 @@ export { applyCreateSecret, assertStorableKey, unreferenceableKey, REFERENCEABLE
 // that apply one cannot differ on what a patch MEANS, and re-exported here so an app needs no direct
 // plugin-api dependency to get it.
 export { applyProviderPatch, patchedFields } from '@matatbread/matbot-plugin-api';
-export { isTruncatedToolResult, notifyingStore, ItemChangeKind, RegistryChangeKind, FUNCTION_TIMEOUT } from '@matatbread/matbot-plugin-api';
+export { isTruncatedToolResult, notifyingStore, ItemChangeKind, RegistryChangeKind, SessionAppendKind, FUNCTION_TIMEOUT } from '@matatbread/matbot-plugin-api';
 // The canonical `type: 'confirm'` answers. Same reason as the patch policy above: an app implementing a
 // PromptFn (or a test standing one in) has to speak them, and must not hard-code the rendered label.
 export { CONFIRM_YES, CONFIRM_NO } from '@matatbread/matbot-plugin-api';
@@ -57,6 +57,8 @@ export * from './usage.js';
 export * from './hooks.js';
 export * from './runner.js';
 export * from './session-runner.js';
+export * from './session-append.js';
+export * from './ephemeral-turn.js';
 export * from './plugin.js';
 export * from './registry.js';
 export * from './settings.js';

package/src/runner.ts

@@ -5,7 +5,7 @@ import type {
   PermissionGate,
 } from './types.js';
 import type { MatbotPlugin } from './plugin.js';
-import type { ToolPresenter } from '@matatbread/matbot-plugin-api';
+import type { ToolPresenter, SessionAppender } from '@matatbread/matbot-plugin-api';
 import { recordSpan, recordUsage, withUsageSite, scopeIterable } from '@matatbread/matbot-plugin-api/host';
 import { HookRegistry } from './hooks.js';
 import { appendMessage, createMessage } from './session.js';
@@ -115,6 +115,9 @@ export interface RunSessionOpts {
   workdir?:       string;
   configPath?:    string;
   files?:         FileStore;
+  /** Handed to tools as `ToolContext.appender`: set only by a runner whose sessions the machine's own
+   *  appender cannot reach (an ephemeral one). */
+  appender?:      SessionAppender;
   /** Where user-attached session media lives. Resolved once per turn into the outgoing copy, newest-first
    *  and inside {@link MEDIA_RESIDENCY_BYTES}; absent ⇒ every `file-ref` stays a ref and the converters
    *  degrade it. Never read for anything else — the runner does not otherwise touch a file. */
@@ -133,6 +136,13 @@ export interface RunSessionOpts {
    * re-run of the originating user turn. Empty/absent for an ordinary turn.
    */
   injectedEphemeral?: MessageContent[];
+  /**
+   * Consulted at the top of every round — the one point in a turn where the history is protocol-whole:
+   * every `tool_use` so far is answered, and no provider call is in flight. Returns the session with
+   * messages from outside the turn placed into it (the pump's parallel replies), and the traceIds to
+   * announce as `merged`; `undefined` ⇒ nothing arrived. Where they go is the caller's decision.
+   */
+  interject?:     (session: Session) => { session: Session; merged: string[] } | undefined;
   loadPlugin:     (specifier: string, prompt?: PromptFn, refresh?: boolean) => Promise<MatbotPlugin>;
   unloadPlugin:   (specifier: string) => Promise<boolean>;
 }
@@ -165,7 +175,15 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
   // Nothing is written mid-turn, so "commit" here means the whole turn or none of it.
   // Closes over the reassigned `session` deliberately, so no exit can commit a stale copy.
   async function* end(terminal: TurnEvent): AsyncIterable<TurnEvent> {
+    // One last pull, because this is the funnel every exit passes through. A parallel reply that settled
+    // since the previous round boundary may already be in the store (the session runner places one as it
+    // settles, so a turn parked in a long tool call does not hide it) — and the write below is the whole
+    // document, so a reply this turn never took would be erased by it. Reachable: a turn aborted or
+    // thrown during that same tool call never reaches another round top.
+    const late = opts.interject?.(session);
+    if (late !== undefined) session = late.session;
     await store.set(session.id, session);
+    if (late !== undefined) for (const from of late.merged) yield { type: 'merged', traceId: from, into: traceId };
     yield terminal;
   }
 
@@ -296,6 +314,12 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
     }
     round += 1;
 
+    const interjected = opts.interject?.(session);
+    if (interjected !== undefined) {
+      session = interjected.session;
+      for (const from of interjected.merged) yield { type: 'merged', traceId: from, into: traceId };
+    }
+
     // 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.
@@ -602,6 +626,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
         ...(opts.workdir     !== undefined ? { workdir:     opts.workdir     } : {}),
         ...(opts.configPath  !== undefined ? { configPath:  opts.configPath  } : {}),
         ...(opts.files       !== undefined ? { files:       opts.files       } : {}),
+        ...(opts.appender    !== undefined ? { appender:    opts.appender    } : {}),
       };
 
       // Iterated by hand rather than with `for await`, so the read can be bounded once the turn is

package/src/session-append.ts

@@ -0,0 +1,77 @@
+import type { AppendMessage, AppendResult, Notifier, Session, SessionAppender, SessionRunner, Store } from './types.js';
+import { tryCurrentPrincipal, isReadOnlyError, SessionAppendKind } from '@matatbread/matbot-plugin-api';
+import { appendMessage, createMessage } from './session.js';
+
+/**
+ * The host's {@link SessionAppender}: an append is checked now, and written by the session's runner once no
+ * turn holds the session (`SessionRunner.write`).
+ *
+ * Checked now so that a session that does not exist is reported to a caller who can still act on it. When
+ * no turn holds the session the write runs at once and the append settles once it has, so a write that
+ * cannot land (the session went, or it is shared in read-only) is reported too. When a turn holds it, the
+ * append settles on acceptance: the caller may be that very turn, which the write is waiting for.
+ *
+ * Seeded in every process, and refuses in a background job — whose store is the parent's medium with none
+ * of the parent's turns behind it — until the job registers one that forwards to its parent.
+ */
+export function createSessionAppender(deps: {
+  sessions:   () => Store<Session> | undefined;
+  run:        () => SessionRunner | undefined;
+  notifier:   () => Notifier;
+  isSubAgent: () => boolean;
+}): SessionAppender {
+  return {
+    async append(sessionId, messages): Promise<AppendResult> {
+      if (deps.isSubAgent()) {
+        throw new Error('This background job has no way to reach its parent\'s sessions, so it cannot append to one.');
+      }
+      if (sessionId === undefined) throw new Error('No session was named to append to.');
+      if (messages.length === 0) throw new Error('Nothing to append.');
+      const store = deps.sessions();
+      if (store === undefined) throw new Error('No session store is available.');
+      const run = deps.run();
+      if (run === undefined) throw new Error('No session runner is available to write the session.');
+      if (await store.get(sessionId) === null) throw new Error(`Session "${sessionId}" not found.`);
+
+      const principal = tryCurrentPrincipal();
+      const traceId   = crypto.randomUUID();
+      const built     = messages.map((m: AppendMessage) => createMessage({
+        role: m.role, content: m.content, traceId,
+        ...(m.metadata !== undefined ? { metadata: m.metadata } : {}),
+      }));
+      const messageIds = built.map(m => m.id);
+
+      let landed = false;
+      let dropped: string | undefined;
+      const write = run.write(sessionId, async () => {
+        const current = await store.get(sessionId);
+        if (current === null) {
+          dropped = `Session "${sessionId}" no longer exists.`;
+          console.error(`[matbot] append to session "${sessionId}" dropped: the session no longer exists.`);
+          return true;
+        }
+        try {
+          if (!(await store.cas(sessionId, current.version, built.reduce(appendMessage, current))).ok) return false;
+        } catch (e) {
+          // Readable, so accepted; not writable — a session shared in read-only.
+          if (!isReadOnlyError(e)) throw e;
+          dropped = e.message;
+          console.error(`[matbot] append to session "${sessionId}" dropped: ${e.message}`);
+          return true;
+        }
+        deps.notifier().notify({
+          kind: SessionAppendKind, source: 'append', sessionId, messageIds,
+          ...(principal !== undefined ? { principal } : {}),
+        });
+        landed = true;
+        return true;
+      }, `[matbot] append to session "${sessionId}" lost to repeated concurrent writes.`);
+
+      if (!write.deferred) {
+        await write.done;
+        if (!landed) throw new Error(`The append was not written: ${dropped ?? 'it failed, or lost to repeated concurrent writes (see the log).'}`);
+      }
+      return { sessionId, messageIds, ...(write.deferred ? { deferred: true as const } : {}) };
+    },
+  };
+}