@matatbread/matbot-core 0.4.18 → 0.4.19

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.4.18",
+  "version": "0.4.19",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@matatbread/matbot-plugin-api": "^0.4.18"
+    "@matatbread/matbot-plugin-api": "^0.4.19"
   },
   "devDependencies": {
     "typescript": "^6.0.3"

package/src/providers-base/index.ts

@@ -1 +1,2 @@
 export { parseSSE } from './sse.js';
+export { textDocument } from './text-document.js';

package/src/providers-base/text-document.ts

@@ -0,0 +1,55 @@
+/**
+ * A text-typed `document` arm, rendered as a plain text block.
+ *
+ * Every adapter needs this and none should use its protocol's document block for it. A document block
+ * buys a title and citation support on the one endpoint that natively implements it, and is DISCARDED
+ * by the Anthropic- and OpenAI-compatible shims most vendors front their models with: DeepSeek
+ * substitutes the literal "[Unsupported Document]" server-side, so the model is told a file is attached
+ * and shown nothing — strictly worse than either sending the bytes or refusing them at the boundary.
+ * A text block is the one content shape every endpoint implements, and for text it is lossless: the
+ * model reads the same characters either way.
+ *
+ * The name is folded into the framing because the alternative is a bare CSV dump with nothing saying
+ * it is a file, which is the other half of what went wrong — a model that cannot tell content from
+ * attachment goes looking for the attachment.
+ */
+
+/**
+ * Structured-text types that are text without saying `text/`. A `+json`/`+xml` suffix (RFC 6839) is
+ * matched too, so `application/vnd.api+json` needs no entry.
+ *
+ * An unlisted type is NOT guessed at, `application/octet-stream` above all: the browser hands that over
+ * for any extension the OS could not place (`.yaml` on some installs), and sniffing it would mean
+ * deciding that binary is text on the strength of it happening to decode.
+ */
+const TEXTUAL: ReadonlySet<string> = new Set([
+  'application/json', 'application/ld+json', 'application/x-ndjson',
+  'application/xml', 'application/yaml', 'application/x-yaml',
+  'application/toml', 'application/csv', 'application/sql',
+  'application/javascript', 'application/x-javascript', 'application/ecmascript',
+  'application/x-sh', 'application/x-httpd-php', 'application/graphql',
+]);
+
+function isTextual(mimeType: string): boolean {
+  const base = mimeType.split(';')[0]!.trim().toLowerCase();
+  return base.startsWith('text/') || base.endsWith('+json') || base.endsWith('+xml') || TEXTUAL.has(base);
+}
+
+/**
+ * The text of a document arm that should be inlined as text, or null to leave the adapter's own
+ * degradation in place (a PDF, an unrecognised type, or bytes that are not valid UTF-8 — a mislabelled
+ * binary must not reach a prompt as mojibake, so the decode is `fatal`).
+ *
+ * `atob` yields one byte per char, so re-widen through TextDecoder rather than trusting it for anything
+ * outside ASCII.
+ */
+export function textDocument(doc: { mimeType: string; data: string; name?: string | undefined }): string | null {
+  if (!isTextual(doc.mimeType)) return null;
+  let text: string;
+  try {
+    text = new TextDecoder('utf-8', { fatal: true })
+      .decode(Uint8Array.from(atob(doc.data), ch => ch.charCodeAt(0)));
+  } catch { return null; }
+  const label = doc.name ?? doc.mimeType;
+  return `--- ${label} ---\n${text}\n--- end of ${label} ---`;
+}

package/src/runner.ts

@@ -5,7 +5,7 @@ import type {
   PermissionGate,
 } from './types.js';
 import type { MatbotPlugin } from './plugin.js';
-import type { ToolPresenter, SessionAppender } from '@matatbread/matbot-plugin-api';
+import type { ToolPresenter, SessionAppender, TurnToolSource } 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';
@@ -83,6 +83,38 @@ 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;
 
+/**
+ * The turn tools `screen` offered (see {@link TurnToolSource}), as they stand for this round. Asked every
+ * round because the turn itself changes the session they are derived from. A name the registry (or the
+ * turn-start snapshot) already holds is dropped: the registered tool keeps it, since shadowing one is a
+ * gated decision and a hook must not be a way round it. `warned` keeps that to one line per name a turn.
+ * A source that throws is skipped, like a throwing hook — it must not take the turn down with it.
+ */
+async function resolveTurnTools(
+  sources:  readonly TurnToolSource[],
+  session:  Session,
+  taken:    (name: string) => boolean,
+  warned:   Set<string>,
+): Promise<Map<string, Tool>> {
+  const out = new Map<string, Tool>();
+  for (const source of sources) {
+    let offered: readonly Tool[];
+    try { offered = await source(session); }
+    catch (e) { console.warn(`[runner] a turn tool source failed: ${e instanceof Error ? e.message : String(e)}`); continue; }
+    for (const tool of offered) {
+      if (taken(tool.name)) {
+        if (!warned.has(tool.name)) {
+          warned.add(tool.name);
+          console.warn(`[runner] turn tool "${tool.name}" dropped: a registered tool has that name.`);
+        }
+        continue;
+      }
+      if (!out.has(tool.name)) out.set(tool.name, tool);
+    }
+  }
+  return out;
+}
+
 export interface RunSessionOpts {
   session:        Session;
   config:         RunConfig;
@@ -238,6 +270,11 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
   // Returns whether anything was claimed. What the caller does with that is the part that legitimately
   // differs — proceed, abort the in-flight provider call, or re-run the loop — so it stays at the site.
   const deferred = screen.deferred;
+
+  // Re-resolved at the top of every round (below), so a tool defined in one round is callable in the next.
+  const turnToolSources = screen.tools;
+  const turnToolWarned  = new Set<string>();
+  let turnTools = new Map<string, Tool>();
   async function* claimVerdicts(): AsyncGenerator<TurnEvent, boolean, undefined> {
     if (deferred.length === 0) return false;
     const ephemeralC: MessageContent[] = [];
@@ -325,6 +362,11 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
     // discarded. This is the no-waste path — the verdict landed before we spent any tokens.
     yield* claimVerdicts();
 
+    if (turnToolSources.length > 0) {
+      turnTools = await resolveTurnTools(turnToolSources, session,
+        name => tools.has(name) || (opts.toolRegistry?.resolve(name) ?? null) !== null, turnToolWarned);
+    }
+
     const pendingCalls: Array<{ id: string; name: string; input: unknown; meta?: ProviderMeta;
       truncated?: { bytes: number; stopReason?: string } }> = [];
     const assistantParts: MessageContent[] = [];
@@ -381,10 +423,13 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
     // tools stay callable — execution resolves against the live registry (opts.toolRegistry), not this.
     // Scoped to the round: a presenter may itself run completions (deriving a tool's search terms), and
     // that spend belongs to the round that asked for it — it is neither a tool call nor a hook.
-    const advertised = opts.toolPresenter
+    // Turn tools go AFTER the presenter, never through it: they are few, made for this session, and
+    // absent from the registry a presenter's own search reads — one it windowed out could not come back.
+    const presented = opts.toolPresenter
       ? await withUsageSite({ kind: 'round', round },
           () => opts.toolPresenter!.present([...tools.values()], { session, provider: config.provider }))
       : [...tools.values()];
+    const advertised = turnTools.size > 0 ? [...presented, ...turnTools.values()] : presented;
     // 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();
@@ -525,7 +570,8 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
     for (const [callIdx, tc] of pendingCalls.entries()) {
       yield { type: 'tool:start', callId: tc.id, name: tc.name, input: tc.input, traceId };
 
-      const tool = opts.toolRegistry !== undefined ? opts.toolRegistry.resolve(tc.name) : tools.get(tc.name);
+      const tool = (opts.toolRegistry !== undefined ? opts.toolRegistry.resolve(tc.name) : tools.get(tc.name))
+        ?? turnTools.get(tc.name);
       if (!tool) {
         const err = { error: `Unknown tool: ${tc.name}` };
         toolResults.push({ type: 'tool-result', id: tc.id, result: err, isError: true });
@@ -627,6 +673,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
         ...(opts.configPath  !== undefined ? { configPath:  opts.configPath  } : {}),
         ...(opts.files       !== undefined ? { files:       opts.files       } : {}),
         ...(opts.appender    !== undefined ? { appender:    opts.appender    } : {}),
+        ...(turnTools.size   > 0         ? { turnTools                      } : {}),
       };
 
       // Iterated by hand rather than with `for await`, so the read can be bounded once the turn is

package/src/session-runner.ts

@@ -108,7 +108,7 @@ const DEFAULT_STEER_NUDGE: MessageContent[] = [{
 // "how's it going?" mid-task sees a history that ends a turn early and answers as though nothing were
 // running. Names the running request so the reply can be about it, and says what happens to the reply.
 const PARALLEL_FRAMING_CAP = 2_000;
-const parallelFraming = (running: string): UserContent => ({
+const parallelFraming = (running: string): Extract<UserContent, { type: 'text' }> => ({
   type: 'text',
   origin: 'robo',
   text: 'A separate turn of this conversation is still working on the request below, and you cannot see its '
@@ -118,11 +118,32 @@ const parallelFraming = (running: string): UserContent => ({
     + '\n</running-request>',
 });
 
-// A parallel turn's write-back: its submission and final reply, ready to place. Built once, when the
-// parallel turn settles; placed by whoever holds the session at that moment (see `merges`).
+// A parallel turn's span as it can be placed into shared history: trimmed back to the last point at
+// which every tool-call in it has its result. An abort (or a failure mid-round) leaves a trailing
+// tool-call with nothing answering it, and an unpaired call is not valid wire for any provider — it
+// would break not just this placement but every later turn of the session.
+const closedSpan = (msgs: Message[]): Message[] => {
+  const open = new Set<string>();
+  let closed = 0;
+  for (const [i, m] of msgs.entries()) {
+    for (const c of m.content) {
+      if (c.type === 'tool-call')        open.add(c.id);
+      else if (c.type === 'tool-result') open.delete(c.id);
+    }
+    if (open.size === 0) closed = i + 1;
+  }
+  return msgs.slice(0, closed);
+};
+
+// A parallel turn's write-back: its submission and everything the turn produced, ready to place. Built
+// once, when the parallel turn settles; placed by whoever holds the session at that moment (see
+// `merges`).
 interface ParallelReply {
   traceId:  string;
-  messages: [Message, Message];
+  /** The turn's head first, then its whole span — thinking, tool calls, their results, its markers and
+   *  its final reply. Non-empty by construction, which is what keeps `messages[0]` the head: every
+   *  placement path dedupes on that id. */
+  messages: [Message, ...Message[]];
   /** The id of the message this reply's copy was cut AT — the running turn's head when it was submitted,
    *  captured then. The pair belongs immediately ahead of it, because that is where the history the reply
    *  was generated against ended. Absent ⇒ the copy was cut at the end of the session (nothing was
@@ -881,12 +902,12 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
 
   /**
    * A parallel turn: the submission runs at once on a nested runner over a private copy of the session's
-   * completed turns, and only it and its final reply come back (`ParallelReply`). The copy ends where the
+   * completed turns, and its submission plus everything it produced come back (`ParallelReply`). The copy ends where the
    * running turn's own messages begin (`head`), plus any replies already placed into that turn but not
    * yet committed (`interjected`) — both captured at submit, before any await could outlive the turn.
    *
-   * Its events are forwarded under its own traceId as progress, never persisted: its tool calls belong to
-   * the copy, which is dropped here. A nested runner rather than `runSession` so the turn is an ordinary
+   * Its events are forwarded under its own traceId as progress; what persists is the span the write-back
+   * carries, read from the copy once the turn has settled. A nested runner rather than `runSession` so the turn is an ordinary
    * one — screen, followup, accounting, media — with nothing re-implemented.
    */
   const runParallel = async (
@@ -910,6 +931,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
       const have     = new Set(prefix.map(m => m.id));
       const copy     = { ...stored, messages: [...prefix, ...p.interjected.filter(m => !have.has(m.id))] };
       const running  = p.head?.request ?? '';
+      const framing  = running ? parallelFraming(running) : undefined;
 
       const store = new MemoryStore<Session>();
       await store.set(id, copy);
@@ -941,10 +963,21 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
       const msgs   = final?.messages ?? [];
       const hIdx   = msgs.findIndex(m => m.role === 'user' && m.traceId === p.traceId);
       const qHead  = msgs[hIdx];
-      // Only the reply's text crosses back: its tool calls stay in the copy (an unpaired one would break
-      // every later turn), and its thinking was signed against a history that included those tool rounds.
-      const last   = hIdx >= 0 ? msgs.slice(hIdx + 1).findLast(m => m.role === 'assistant') : undefined;
-      const answer = (last?.content ?? []).filter(c => c.type === 'text');
+      // The turn's WHOLE span crosses back, not just its final text: thinking, tool calls, their results
+      // and any markers. A history holding only the answer makes everything a parallel turn actually did
+      // unrecoverable the moment the live stream is gone — `determine_provenance` reads a real tool result
+      // as fabricated, and so does a person scrolling back. The span is placed exactly where the copy was
+      // cut, so it sits in the history it was generated against, and `closedSpan` is what keeps it valid
+      // wire. Thinking rides along persisted but unsubmitted (every adapter elides a historical block),
+      // and a foreign round-trip token is the adapters' to drop by `providerName`, which these messages
+      // carry — so nothing here depends on which provider ran the turn.
+      const span   = hIdx >= 0 ? closedSpan(msgs.slice(hIdx + 1)) : [];
+      // Answered iff the span ENDS with assistant text. Not "contains some": a turn aborted after
+      // "let me check that" has said nothing, and a span ending on a tool result needs the note after it
+      // to close the turn on an assistant message.
+      const tail   = span[span.length - 1];
+      const answer = tail?.role === 'assistant'
+        ? tail.content.filter(c => c.type === 'text' && c.text.trim() !== '') : [];
       const ended  = rec.replay.findLast(e => e.type === 'done' || e.type === 'aborted' || e.type === 'error' || e.type === 'cancelled');
       const reason = ended?.type === 'aborted' ? `was stopped (${ended.reason})`
                    : ended?.type === 'cancelled' ? 'was stopped before it started'
@@ -954,14 +987,19 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
         traceId:  p.traceId,
         ...(p.head !== undefined ? { head: p.head.id } : {}),
         messages: [
-          // The copy's own head, carrying its accounting, but with the content as the person submitted it.
+          // The copy's own head, carrying its accounting, with the framing block taken back OFF — that
+          // block is this turn's own context and not something the person wrote. Subtracted rather than
+          // replaced with `p.content` wholesale: a `contextual` trigger folds its correction DURABLY onto
+          // the head, and overwriting the content dropped exactly that, so the correction informed the
+          // answer and then vanished from the history the answer sits in.
           qHead !== undefined
-            ? { ...qHead, content: p.content }
+            ? { ...qHead, content: qHead.content.filter(c => !(framing !== undefined && c.type === 'text'
+                && c.origin === framing.origin && c.text === framing.text)) }
             : createMessage({ role: 'user', content: p.content, traceId: p.traceId, providerName: p.provider }),
-          last !== undefined && answer.length > 0
-            ? { ...last, content: answer }
-            : createMessage({ role: 'assistant', content: [{ type: 'text', text: `(No reply — this message's parallel turn ${reason}.)` }],
-                traceId: p.traceId, providerName: p.provider }),
+          ...span,
+          ...(answer.length > 0 ? [] : [createMessage({
+            role: 'assistant', content: [{ type: 'text', text: `(No reply — this message's parallel turn ${reason}.)` }],
+            traceId: p.traceId, providerName: p.provider })]),
         ],
       };
     } catch (e) {