@matatbread/matbot-core 0.4.16 → 0.4.18

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';
@@ -18,9 +18,8 @@ import { MEDIA_RESIDENCY_BYTES, resolveSessionMedia } from './media.js';
 // context, losing any scope entered around the loop body. Scoping each `next()` instead means the
 // tool's body — and anything it kicks off while running — always resumes under its own site.
 //
-// `scopeIterable` is the shared per-pull wrap, as used by `runAs` for the principal: this had its own
-// object-literal copy, which replaced the iterator wholesale and so dropped a class-based tool
-// iterator's own members, prototype and `instanceof`.
+// `scopeIterable` is the per-pull wrap `runAs` also uses for the principal. It wraps the iterator rather
+// than replacing it, so a class-based tool iterator keeps its own members, prototype and `instanceof`.
 const siteScoped = <T>(site: UsageSite, src: AsyncIterable<T>): AsyncIterable<T> =>
   scopeIterable(src, f => withUsageSite(site, f));
 
@@ -116,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. */
@@ -134,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>;
 }
@@ -166,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;
   }
 
@@ -297,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.
@@ -603,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 } : {}) };
+    },
+  };
+}