@matatbread/matbot-plugin-api 0.4.15 → 0.4.17

package/package.json

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

package/src/context-switch.ts

@@ -104,15 +104,13 @@ export type Quiescer = (unregister: () => void) => void | Promise<void>;
  * onContextQuiesce(() => { if (nothingToDo) return; … });
  * ```
  *
- * **This or {@link scheduleAtEdge}?** They answer different questions, and the difference is what happens
- * when you ask twice.
+ * **This or {@link scheduleAtEdge}?** The difference is what happens when you ask twice.
  *
  * This is a *subscription*: each call adds a callback, and every callback added runs. Ask twice and the work
  * happens twice — correct when each call carries its own work (two deferred session edits are two edits, and
- * both must land). `scheduleAtEdge` is a *dirty flag*: you create one scheduler up front, and however many
- * times you poke it before an edge, the work runs once. Correct when the calls describe a **slot** rather
- * than a queue — three `register('StorageBackend')` calls mean one backend to install, not three to install
- * in turn, and the work reads the slot at fire time so the last writer wins.
+ * both must land). `scheduleAtEdge` is a *dirty flag*: one scheduler, poked any number of times before an
+ * edge, runs once and reads a slot at fire time. Correct when the calls describe a **slot** rather than a
+ * queue — three `register('StorageBackend')` calls mean one backend to install, not three in turn.
  *
  * Picking wrongly is not subtle in either direction: a subscription where you wanted a flag re-applies stale
  * intermediate values, and a flag where you wanted a subscription silently drops work.
@@ -125,36 +123,24 @@ export type Quiescer = (unregister: () => void) => void | Promise<void>;
  *
  * - Flushers are **invoked in registration order**, in one synchronous sweep; one that goes async is
  *   started in that order and then left to settle alongside the rest.
- * - **The synchronous prefix lands within the call.** As long as flushers are synchronous nothing
- *   yields at all, which is what lets the host stage a mutation and land it with a bare
- *   `flushIfQuiescent()` — in effect before the call returns.
+ * - **The synchronous prefix lands within the call.** As long as flushers are synchronous nothing yields at
+ *   all, so a host can stage a mutation and have it in effect before the staging call returns.
  * - **No second sweep begins until the current one has completely settled**, and a mutation staged
  *   meanwhile is turned away rather than applied.
  * - A throwing flusher is isolated, and so is a rejecting one — neither may deny the others their
  *   completion, nor escape into the operation whose release happened to reach the edge.
+ * - **Exclusivity, for a flusher's whole extent**, because {@link machineBusy} bars entry while a flush is
+ *   settling. Flushers still overlap *each other*, deliberately: sequencing them would remove one source of
+ *   concurrent mutation while leaving every other in place, at the price of every flusher waiting on the
+ *   slowest. Keeping a flusher synchronous is still worth it where the work allows.
  *
- * - **Exclusivity, for a flusher's whole extent.** A synchronous flusher has always had it for free —
- *   the runtime is single-threaded — and that remains the argument for keeping one synchronous whenever
- *   the work allows. An asynchronous one now has it too, because {@link machineBusy} bars entry while a
- *   flush is settling. Flushers still overlap *each other*, deliberately: sequencing them would remove
- *   one source of concurrent mutation while leaving every other in place, at the price of every flusher
- *   waiting on the slowest.
- *
- * Exclusivity is a recent acquisition and the reasoning that preceded it is worth keeping, because it
- * says what the barrier is really for. This edge used to be a counter, not a gate: `depth` was 0 while
- * a flush settled, so an HTTP endpoint could accept a request and run a whole tool call inside a single
- * `await`, and the conclusion drawn was that contention over a service is the *service's* to resolve —
- * a `Store` answers it with compare-and-swap — and that the sweep's job was only to make contention
- * rare rather than to pretend the machine stops.
- *
- * That is still true, and `mediumGuard` is the shipped form of it: a write whose read came from another
- * `StorageBackend` fails on the version stamp, so coherence does not depend on this module at all.
- * Which is precisely what makes the barrier safe to add. It is not the correctness mechanism; it is the
- * **liveness** one. A counter cannot force `depth` to reach 0, so under continuously overlapping holds —
- * several sessions on a busy server, each pump holding across its own queue — the edge simply never
- * arrives and staged work waits for an idle moment that never comes. A deferred session edit that never
- * lands, and a staged backend swap that never applies, are both failures with no symptom. Barring entry
- * is the only way to make the drain reachable, and exclusivity falls out of it for free.
+ * **The barrier is for liveness, not coherence.** Coherence does not depend on this module at all:
+ * `mediumGuard` fails a write whose read came from another `StorageBackend` on the version stamp, and
+ * contention over a service is that service's to resolve (a `Store` answers it with compare-and-swap). What
+ * a counter *cannot* do is force `depth` to reach 0 — under continuously overlapping holds (several sessions
+ * on a busy server, each pump holding across its own queue) the edge never arrives, and a deferred session
+ * edit that never lands and a staged swap that never applies are both failures with no symptom. Barring
+ * entry is the only way to make the drain reachable.
  *
  * The keys that repoint *immediately* — `Vault`, `KnowledgeIndex`, `Notifier`, anything a plugin
  * registers — carry no protection here or anywhere: they change under a running turn too, by the
@@ -165,16 +151,13 @@ export function onContextQuiesce(flush: Quiescer): () => void {
   const unregister = (): void => { cs.quiescers.delete(flush); };
   cs.quiescers.add(flush);
 
-  // **Registering IS announcing.** A stager should not have to also remember to ask for an edge: the one
-  // plugin doing this in-tree registered a one-shot and never called `flushIfQuiescent`, so the barrier
-  // never engaged on its behalf and its work depended on someone else happening to release. Two calls that
-  // must be paired, where omitting the second is silent, is the shape this module exists to avoid.
+  // **Registering IS announcing**, because two calls that must be paired, where omitting the second is
+  // silent, is the shape this module exists to avoid: a stager that registered and forgot to ask for an
+  // edge left the barrier disengaged, and its work then depended on someone else happening to release.
   //
   // The barrier is raised synchronously (it invokes nothing) so it engages at once, while the edge ATTEMPT
   // waits for a microtask — a callback must not run before the statement registering it has finished, or a
   // one-shot reading anything initialised on that same line, `unregister` included, would see it missing.
-  // Nothing depends on registration landing synchronously; the host's inline-landing guarantee is attached
-  // to an explicit `flushIfQuiescent()`, which still has it.
   if (cs.depth !== 0 || cs.flushing) cs.wanted = true;
   void Promise.resolve().then(() => { if (cs.quiescers.has(flush)) flushIfQuiescent(); });
 
@@ -183,13 +166,8 @@ export function onContextQuiesce(flush: Quiescer): () => void {
 
 /**
  * Announce registered work and land it if the edge is already here — **private**, and the second half of
- * {@link onContextQuiesce}.
- *
- * It was public, and announcing was then a call a stager had to remember to pair with its registration. The
- * one plugin registering a one-shot never made it, so the barrier never engaged for the very work whose
- * starvation motivated it. Registering announces now, which is the same guarantee with nothing to forget —
- * and once that was true, nothing outside this module had any reason to call this. Exposing "force an edge"
- * only offered a way to reason about firing that a caller should not have to have.
+ * {@link onContextQuiesce}. Private because registering announces, so nothing outside this module has any
+ * reason to force an edge; offering one only invites reasoning about firing that a caller should not need.
  *
  * It stays separate from the opportunistic sweep {@link machineBusy} performs at its own edges: only a
  * registration knows work exists, and a sweep that raised `wanted` merely because it found the machine busy
@@ -277,10 +255,9 @@ function sweep(): Promise<void> | undefined {
  * caller through here — which is all the mount contract has ever promised: eventual and ordered,
  * never timed.
  *
- * **Largely redundant since the barrier.** {@link machineBusy} now waits for staged work before it takes
- * the hold, which is this guarantee delivered where it cannot be forgotten — so the pump, the caller this
- * was written for, no longer calls it. It remains for an operation that needs deferred work complete and
- * does *not* want to hold the machine.
+ * **Largely redundant since the barrier**, which delivers this guarantee inside {@link machineBusy} where
+ * it cannot be forgotten. It remains for an operation that needs deferred work complete and does *not*
+ * want to hold the machine.
  */
 export async function quiesced(): Promise<void> {
   await sweep();
@@ -369,23 +346,21 @@ async function admit(): Promise<void> {
  * off-limits to further ones until `fn` is done. When `fn` is async the hold stays up until its promise
  * settles, so the count tracks the real operation rather than the synchronous call.
  *
- * **Always a promise, because entry can wait** ({@link admit}) — that is the barrier, and it is in here
- * rather than at the call site on purpose. An explicit "wait, then hold" pair reads better and puts the
- * cost in view, but it makes the waiting *optional*, and a second caller who omits it gets no error and
- * no symptom: staged work simply stops landing. That is the failure this whole module exists to prevent,
- * so it is not one to leave to a caller's memory — the same reasoning that makes the principal ambient
- * rather than threaded, and binds a mount interest to its plugin's load extent.
+ * **Always a promise, because entry can wait** ({@link admit}) — the barrier is in here rather than at the
+ * call site on purpose. An explicit "wait, then hold" pair reads better and puts the cost in view, but it
+ * makes the waiting *optional*, and a caller who omits it gets no error and no symptom: staged work simply
+ * stops landing. Same reasoning that makes the principal ambient rather than threaded, and binds a mount
+ * interest to its plugin's load extent.
  *
  * When nothing is staged, `fn` still runs **synchronously** within the call, before the returned promise
  * is handed back: the barrier adds a hold, never a scheduling gap, so nothing can slip between the check
  * and the hold. A synchronous throw becomes a rejection, so the two paths report failure identically.
  *
  * The hold is released on **every** exit — a throw, a rejected promise, a bare `return` from anywhere
- * inside — because the release is bound to the call, not written at the exits. That is the whole reason
- * this is a wrapper and not a `begin()`/`end()` pair: a caller with a dozen early returns (the pump has
- * several per queue item) cannot leave the counter stuck, and a stuck counter is unrecoverable — every
- * later flush would silently no-op forever, and the symptom would be a deferred mutation that simply
- * never happens.
+ * inside — because the release is bound to the call, not written at the exits. That is why this is a
+ * wrapper and not a `begin()`/`end()` pair: a caller with a dozen early returns (the pump has several per
+ * queue item) cannot leave the counter stuck, and a stuck counter is unrecoverable — every later flush
+ * would silently no-op forever, with no symptom but a deferred mutation that never happens.
  */
 export function machineBusy<T>(fn: () => T | Promise<T>): Promise<T> {
   if (!clear()) return admit().then(() => held(fn));

package/src/hooks.ts

@@ -2,7 +2,7 @@ import type {
   Hook, HookPoint, HookRegistrar, Message, MessageContent, Session, DeferredScreen,
   ScreenContext, ContributeContext, ToolCallContext, ToolCallResult, ToolResultContext, FollowupContext,
 } from './types.js';
-import { foldOntoUserTurn } from './session.js';
+import { foldOntoUserTurn, createMessage } from './session.js';
 import { withUsageSite } from './usage-context.js';
 
 const HOOK_ERROR_CREATOR = 'matbot-hooks';
@@ -20,11 +20,20 @@ export class HookRegistry implements HookRegistrar {
   private readonly markedFailures = new Set<Hook>();
   private pendingFailureMarkers: { channel: HookPoint; pluginName?: string; message: string }[] = [];
 
+  // A fresh array, never an in-place push + sort, for the reason given at `removeOne`: a run loop
+  // iterating the old list across its awaits would otherwise visit a hook registered mid-run, or visit
+  // one twice after the sort moved it behind the cursor.
   register(hook: Hook): void {
-    const list = this.hooks.get(hook.on) ?? [];
-    list.push(hook);
-    list.sort((a, b) => (a.priority ?? 50) - (b.priority ?? 50));
-    this.hooks.set(hook.on, list);
+    const list = [...(this.hooks.get(hook.on) ?? []), hook];
+    this.hooks.set(hook.on, list.sort((a, b) => (a.priority ?? 50) - (b.priority ?? 50)));
+  }
+
+  // The hooks registered on one channel, narrowed to that channel's arm. The map is keyed BY `on`, so
+  // its members are already the right arm; each run* method used to re-test `if (hook.on !== 'screen')
+  // continue` purely to tell TypeScript so — five guards that could never fire. Narrowing at the lookup
+  // says it once, where it is true by construction.
+  private on<P extends HookPoint>(point: P): Extract<Hook, { on: P }>[] {
+    return (this.hooks.get(point) ?? []) as Extract<Hook, { on: P }>[];
   }
 
   removeByPlugin(pluginName: string): void {
@@ -79,12 +88,10 @@ export class HookRegistry implements HookRegistrar {
   // fallback path, not the only one).
   private drainFailureMarkers(session: Session): { session: Session; markers: MessageContent[] } {
     if (this.pendingFailureMarkers.length === 0) return { session, markers: [] };
-    const messages: Message[] = this.pendingFailureMarkers.map(f => ({
-      id:        crypto.randomUUID(),
-      role:      'marker',
-      createdAt: new Date().toISOString(),
-      traceId:   '',
-      content:   [{
+    const messages: Message[] = this.pendingFailureMarkers.map(f => createMessage({
+      role:    'marker',
+      traceId: '',
+      content: [{
         type:    'marker',
         creator: HOOK_ERROR_CREATOR,
         data:    { channel: f.channel, ...(f.pluginName !== undefined ? { pluginName: f.pluginName } : {}), message: f.message },
@@ -110,9 +117,8 @@ export class HookRegistry implements HookRegistrar {
     const handlerMarkers: MessageContent[] = [];
     const appendMarkers = (blocks: MessageContent[]): void => {
       handlerMarkers.push(...blocks);
-      session = { ...session, messages: [...session.messages, {
-        id: crypto.randomUUID(), role: 'marker', createdAt: new Date().toISOString(), traceId: '', content: blocks,
-      }] };
+      session = { ...session, messages: [...session.messages,
+        createMessage({ role: 'marker', traceId: '', content: blocks })] };
     };
     // Handler-returned durable context: folded onto the running turn's user message (the last one
     // with role 'user'), so it persists into history AND rides every subsequent provider call — the
@@ -127,8 +133,7 @@ export class HookRegistry implements HookRegistrar {
       durable.push(...blocks);
       session = folded;
     };
-    for (const hook of this.hooks.get('screen') ?? []) {
-      if (hook.on !== 'screen') continue;
+    for (const hook of this.on('screen')) {
       const r = await this.invoke(hook, () => hook.handler({ ...ctx, session, removeHook: () => this.removeOne('screen', hook) }));
       if (!r) continue;
       if (r.session)                     session = r.session;
@@ -149,8 +154,7 @@ export class HookRegistry implements HookRegistrar {
   // session is never touched.
   async runContribute(ctx: Omit<ContributeContext, 'removeHook'>): Promise<Message[]> {
     let outgoing = ctx.outgoing as Message[];
-    for (const hook of this.hooks.get('contribute') ?? []) {
-      if (hook.on !== 'contribute') continue;
+    for (const hook of this.on('contribute')) {
       const r = await this.invoke(hook, () => hook.handler({ ...ctx, outgoing, removeHook: () => this.removeOne('contribute', hook) }));
       if (r) outgoing = r;
     }
@@ -159,8 +163,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.hooks.get('toolcall') ?? []) {
-      if (hook.on !== 'toolcall') continue;
+    for (const hook of this.on('toolcall')) {
       const r = await this.invoke(hook, () => hook.handler({ ...ctx, removeHook: () => this.removeOne('toolcall', hook) }));
       if (r && (r.rejectTool || r.abort)) return r;
     }
@@ -171,8 +174,7 @@ export class HookRegistry implements HookRegistrar {
   // a hook that returns nothing just observes (auditing). Returns the final result.
   async runToolResult(ctx: Omit<ToolResultContext, 'removeHook'>): Promise<unknown> {
     let result = ctx.result;
-    for (const hook of this.hooks.get('toolresult') ?? []) {
-      if (hook.on !== 'toolresult') continue;
+    for (const hook of this.on('toolresult')) {
       const r = await this.invoke(hook, () => hook.handler({ ...ctx, result, removeHook: () => this.removeOne('toolresult', hook) }));
       if (r) result = r.result;
     }
@@ -188,17 +190,20 @@ export class HookRegistry implements HookRegistrar {
     const markers:      MessageContent[]   = [];
     const retractCtx:   MessageContent[]   = [];
     const retractDur:   MessageContent[]   = [];
-    for (const hook of this.hooks.get('followup') ?? []) {
-      if (hook.on !== 'followup') continue;
+    // Whether a hook ASKED to retract, not how much it sent with the request. Deriving it from the
+    // payload size dropped a `retractAndRerun: {}` — type-legal, both fields being optional — so a hook
+    // 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) }));
       if (r?.resubmit)        resubmits.push(r.resubmit.content);
       if (r?.retractAndRerun) {
+        retracting = true;
         if (r.retractAndRerun.context) retractCtx.push(...r.retractAndRerun.context);
         if (r.retractAndRerun.durable) retractDur.push(...r.retractAndRerun.durable);
       }
       if (r?.markers)         markers.push(...r.markers);
     }
-    const retracting = retractCtx.length > 0 || retractDur.length > 0;
     return { resubmits, markers, ...(retracting ? { retract: { context: retractCtx, durable: retractDur } } : {}) };
   }
 }

package/src/host-machine.ts

@@ -2,6 +2,7 @@ import type {
   CompletionRequest, MatbotMachine, MatbotServices, Mounted, MountConsumeOptions, SingleTurnRequest,
 } from './plugin.js';
 import { RegistryChangeKind } from './notify.js';
+import { createMessage } from './session.js';
 
 /*
  * Host-side machine assembly — the wiring an *embedder* does once at boot, not API a plugin author
@@ -50,8 +51,15 @@ export type SwapFn<T extends object> = (next: T) => void;
  * A capture-safe forwarding proxy: every trap routes to whatever `getCurrent()` returns *now*, so a
  * reference captured before a register()-driven swap keeps resolving to the live impl. getPrototypeOf
  * is forwarded so `instanceof` sees the real impl (the StorageBackend identity checks depend on it);
- * ownKeys + getOwnPropertyDescriptor keep object spread faithful. Methods bind to the current impl,
- * not the proxy. A nullish current (an optional service with nothing registered yet) reads as empty.
+ * ownKeys + getOwnPropertyDescriptor keep object spread faithful. A nullish current (an optional service
+ * with nothing registered yet) reads as empty.
+ *
+ * **Method identity is not stable**, and callers do need to know: a `get` binds to the impl current at
+ * that moment, so each read produces a NEW function and `store.get !== store.get`. That is what makes a
+ * captured method follow a swap instead of calling into the displaced impl — the point of the whole
+ * proxy — but it means anything keyed on a method's identity silently never matches: a `Set` of
+ * callbacks it is asked to remove one from, a memo keyed by function, an `===` comparison against a
+ * previously-read method. Capture the SERVICE and call through it; do not capture its methods.
  */
 export function forwardingProxy<T extends object>(getCurrent: () => T | undefined): T {
   return new Proxy({} as T, {
@@ -198,16 +206,17 @@ export function createMountTable(getMachine: () => MatbotMachine): MountTable {
 
 /**
  * Build the one-message CompletionRequest for a {@link MatbotRuntime.singleTurn} call, hiding the
- * otherwise-mandatory and meaningless Message fields (id/traceId/createdAt) an out-of-band one-shot
- * has no use for. Pure; the host invokes its own complete() with the result.
+ * otherwise-mandatory Message fields an out-of-band one-shot has no use for. The host invokes its own
+ * complete() with the result.
  */
 export function singleTurnRequest(req: SingleTurnRequest): CompletionRequest {
   return {
     provider: req.provider,
-    messages: [{
-      id: '', traceId: '', createdAt: new Date().toISOString(), role: 'user',
+    messages: [createMessage({
+      role:    'user',
+      traceId: '',
       content: typeof req.prompt === 'string' ? [{ type: 'text', text: req.prompt }] : req.prompt,
-    }],
+    })],
     ...(req.system     !== undefined ? { system: req.system } : {}),
     ...(req.parameters !== undefined ? { parameters: req.parameters } : {}),
     ...(req.signal     !== undefined ? { signal: req.signal } : {}),

package/src/host.ts

@@ -33,6 +33,10 @@ export * from './usage-context.js';
 // The machine half of a context switch: quiescent-edge flushers and the deferred-swap application point.
 export * from './context-switch.js';
 
+// Re-entering an ambient scope on every pull of an async iterator — what both carriers need to cover a
+// tool executor's deferred body. Host-side: a plugin gets this behaviour for free from `runAs`.
+export * from './scoped-iterator.js';
+
 // The boot `PermissionGate` a host installs as the base of the swap-member: ask through whatever
 // channel is in scope, else answer the request's own `fallback`. A plugin supplying a *policy* is the
 // author-facing half and needs only the `PermissionGate` type, which the root exports.

package/src/invoke-tool.ts

@@ -108,6 +108,21 @@ export function invokeTool<K extends string, const P>(
   return tool.executor.execute(params, ctx) as AsyncIterable<ToolEvent<ToolResultFor<K, P>>>;
 }
 
+/**
+ * The one drain: consume a tool event stream, keeping the last `result` and throwing on the first
+ * `error`. Whether a stream that yielded NO result is a failure is the caller's question, and the only
+ * thing the three public drains ever disagreed on — so it is the only thing they pass in.
+ */
+async function drain<R>(events: AsyncIterable<ToolEvent<R>>): Promise<{ value: R | undefined; hadResult: boolean }> {
+  let value: R | undefined;
+  let hadResult = false;
+  for await (const ev of events) {
+    if      (ev.type === 'result') { value = ev.value; hadResult = true; }
+    else if (ev.type === 'error')  { throw new Error(ev.message); }
+  }
+  return { value, hadResult };
+}
+
 /**
  * Drain a tool event stream (e.g. {@link invokeTool}'s return) to its raw `result` *value*, typed:
  * paired with `invokeTool(machine, name, …)` it returns whatever `ToolContracts[name]` declares (or
@@ -116,14 +131,9 @@ export function invokeTool<K extends string, const P>(
  * Stops and throws on the first `error` event, or if the tool finished without yielding a `result`.
  */
 export async function toolResult<R>(events: AsyncIterable<ToolEvent<R>>): Promise<R> {
-  let value!: R;
-  let hadResult = false;
-  for await (const ev of events) {
-    if      (ev.type === 'result') { value = ev.value; hadResult = true; }
-    else if (ev.type === 'error')  { throw new Error(ev.message); }
-  }
+  const { value, hadResult } = await drain(events);
   if (!hadResult) throw new Error('Tool produced no result');
-  return value;
+  return value as R;
 }
 
 /**
@@ -133,13 +143,7 @@ export async function toolResult<R>(events: AsyncIterable<ToolEvent<R>>): Promis
  * (the shape `skill_action` and other prose tools return) by its `content`, anything else as JSON.
  */
 export async function toolText(events: AsyncIterable<ToolEvent>): Promise<string> {
-  let result: unknown;
-  let hadResult = false;
-  for await (const ev of events) {
-    if      (ev.type === 'result') { result = ev.value; hadResult = true; }
-    else if (ev.type === 'error')  { throw new Error(ev.message); }
-  }
-  if (!hadResult) throw new Error('Tool produced no result');
+  const result = await toolResult(events);
 
   if (typeof result === 'string') return result;
   if (result !== null && typeof result === 'object' && typeof (result as { content?: unknown }).content === 'string') {
@@ -148,9 +152,28 @@ export async function toolText(events: AsyncIterable<ToolEvent>): Promise<string
   return JSON.stringify(result, null, 2);
 }
 
-const rejectingPrompt: PromptFn = (((p: string | FormField): Promise<string> => {
-  const label = typeof p === 'string' ? p : p.label;
-  return Promise.reject(new Error(`Non-interactive context: cannot prompt for "${label}"`));
+const cannotPrompt = (p: string | FormField): Promise<string> =>
+  Promise.reject(new Error(`Non-interactive context: cannot prompt for "${typeof p === 'string' ? p : p.label}"`));
+
+/**
+ * The stand-in for "there is nobody to ask": every request rejects, naming the field, which a tool's
+ * surrounding try/catch turns into an ordinary error event.
+ *
+ * Deliberately NOT what a gate is handed — see {@link bindGate}. A gate must be able to tell "nobody is
+ * here" (`ask === undefined`) from "a human answered", and a stand-in that answers makes that
+ * undecidable.
+ */
+export const rejectingPrompt: PromptFn = cannotPrompt as PromptFn;
+
+/**
+ * The stand-in that answers with a field's OWN default where it has one, and rejects like
+ * {@link rejectingPrompt} where it does not — what `ToolContext.prompt` is when the host supplied no
+ * channel. The two stand-ins shared one message written out twice, in two packages; what actually
+ * separates them is this one line, so it is the only thing that differs now.
+ */
+export const defaultingPrompt: PromptFn = (((p: string | FormField, def?: string): Promise<string> => {
+  const fallback = typeof p === 'string' ? def : p.default;
+  return fallback !== undefined ? Promise.resolve(fallback) : cannotPrompt(p);
 }) as PromptFn);
 
 /** Compact a value to one trace line. */
@@ -161,6 +184,25 @@ function compactTrace(v: unknown): string {
   return s.length > 240 ? `${s.slice(0, 240)}…` : s;
 }
 
+/**
+ * The {@link ToolProxy}'s drain. Unlike {@link toolResult}, a stream that ends with no `result` resolves
+ * to `undefined` instead of throwing — a tool whose work is a side effect yields nothing BY DESIGN
+ * (`function-tools` omits the event when a body returns nothing, and the triggers dispatcher fires only
+ * on a yielded result), and this proxy is the surface such a tool is called through. Throwing here made
+ * the one surface meant to be silent the one that shouted.
+ *
+ * A tool that declares a DATA result and yields nothing is still an error — but it is caught where the
+ * types are, not re-derived from a contract string on every call: the checker compiles a body against its
+ * declared return type, and `strict` rejects one that can fall through (TS2355 with no return at all,
+ * TS2366 when only some paths do). A body declaring `T | undefined` is deliberately NOT rejected —
+ * `undefined` IS its contract, and is exactly what this drain hands back. Two paths reach here unchecked
+ * and resolve to `undefined` rather than throwing: an explicit `noTypeCheck`, and the browser, where there
+ * is no `ToolTypeIndex`. Both are opted into.
+ */
+async function drainProxyResult<R>(events: AsyncIterable<ToolEvent<R>>): Promise<R | undefined> {
+  return (await drain(events)).value;
+}
+
 /**
  * A factory for a context-overridden {@link ToolProxy}: `toolInContext({ provider }).some_tool(params)`
  * runs `some_tool` with the given fields merged over the box's bound context (omitted fields inherited).
@@ -195,7 +237,7 @@ export function makeToolBox(
         if (typeof prop !== 'string' || prop === 'then') return undefined;
         return async (params?: unknown): Promise<unknown> => {
           opts?.onEvent?.({ type: 'stdout', chunk: `→ ${prop}(${compactTrace(params)})\n` });
-          const value = await toolResult(invokeTool(machine, prop, params ?? {}, call));
+          const value = await drainProxyResult(invokeTool(machine, prop, params ?? {}, call));
           opts?.onEvent?.({ type: 'stdout', chunk: `← ${prop}: ${compactTrace(value)}\n` });
           return value;
         };

package/src/notify.ts

@@ -193,6 +193,7 @@ export interface Notifier {
  */
 export function createNotifier(defaultPlugin: string): Notifier {
   const events = createBroadcaster<Notification>();
+  const warned = new Set<string>();
   return {
     notify(notification) {
       const plugin = notification.plugin ?? defaultPlugin;
@@ -200,9 +201,12 @@ export function createNotifier(defaultPlugin: string): Notifier {
       // matter most here: a plain-JS plugin, or a bridge injecting another instance's traffic. Warn, don't
       // throw — `notify` is contractually non-throwing, and a badly-named kind is a hygiene fault, not a
       // delivery failure. Only the shape is checkable; that the prefix names the *definer* is not, since
-      // the emitter legitimately differs from it.
-      if (!notification.kind.includes('#')) {
-        console.warn(`[matbot] ${plugin} published unqualified notification kind "${notification.kind}" — expected <package-name>#<InterfaceName>`);
+      // the emitter legitimately differs from it. Once per emitter and kind: the fault is in the source,
+      // so repeating it on every publish only buries the log.
+      const warning = `${plugin} published unqualified notification kind "${notification.kind}"`;
+      if (!notification.kind.includes('#') && !warned.has(warning)) {
+        warned.add(warning);
+        console.warn(`[matbot] ${warning} — expected <package-name>#<InterfaceName>`);
       }
       events.emit({ ...notification, plugin } as Notification);
     },

package/src/plugin.ts

@@ -7,18 +7,16 @@ import type {
 import type { Notifications, Notifier } from './notify.js';
 
 /**
- * The plugin API contract version: this package's `major.minor`, and nothing else. It sat at `'0.1'`
- * while the package shipped 0.3.x, so it conveyed no information and could not be reasoned about at a
- * version boundary — the point at which it is the only thing every third-party plugin hardcodes.
+ * The plugin API contract version: this package's `major.minor`, and nothing else — it must track the
+ * package, being the only thing every third-party plugin hardcodes.
  *
  * The gate (`checkApiVersion`, in core's registry) reads it as: **major must match exactly** — a
  * mismatch is a hard load failure — and a plugin declaring a *newer minor* than the runtime warns and
  * loads, since it may reach for something absent. Declare it as `apiVersion: PLUGIN_API_VERSION` and it
  * stays right for free; that is what every plugin in this repo does.
  *
- * Bumping 0.1 → 0.4 breaks nothing: at 0.x the major is `'0'` either way, and an older declared minor
- * does not warn. It matters at 1.0.0, where a plugin still declaring `'0.x'` will fail the major check
- * loudly instead of loading against a contract it was never built for.
+ * It matters at 1.0.0, where a plugin still declaring `'0.x'` fails the major check loudly instead of
+ * loading against a contract it was never built for.
  */
 export const PLUGIN_API_VERSION = '0.4';
 
@@ -247,26 +245,8 @@ export interface MatbotRuntime {
    */
   createStore<T extends { id: string; version: string }>(namespace: string): Store<T>;
 
-  /**
-   * Mount-table notifications: react to a registry service (re)mounting or being unloaded. A plugin
-   * needs this iff its setup() reads another service's *current state* to build cached/derived state —
-   * skills/triggers cache the StorageBackend's documents; cognition seeds from the SkillManager. A pure
-   * map (no setup data; data arrives later as a tool call or hook) needs nothing — resolve the service
-   * per-invocation through its proxy/member instead.
-   *
-   *   // cache the backend's documents; rebuild on every swap (own initial load was in setup())
-   *   services.mounted.observe({ key: 'StorageBackend', signal }, () => this.load());
-   *
-   *   // depend on a peer service that may not be present yet; seed now if it is, and on each (re)mount
-   *   services.mounted.observe({ key: 'SkillManager', replay: true, signal }, m => seed(m));
-   *
-   * Contract guarantees only *eventual, ordered* delivery of each key's net presence transition — it
-   * says nothing about timing: a mount may fire synchronously-ish or batch to a later quiescent edge, so
-   * never assume a register() is observed inline or at a turn boundary. A reload (unregister+register
-   * before the edge) collapses to a single remount; an unregister not replaced by the edge is a
-   * committed unload, delivered to `onUnmount` (drop your captured ref there to let the gone plugin's
-   * working set be collected). Handlers may re-fire on later remounts, so they must be idempotent.
-   */
+  /** Mount-table notifications: react to a registry service (re)mounting or being unloaded. See
+   *  {@link Mounted} for when a plugin needs this, the two idioms, and what the contract guarantees. */
   readonly mounted: Mounted;
 
   /**
@@ -358,9 +338,29 @@ export interface MountConsumeOptions<K extends keyof MatbotServices> {
   readonly onUnmount?: (machine: MatbotMachine) => void | Promise<void>;
 }
 
-/** The mount-table consumer facet exposed on {@link MatbotRuntime.mounted}. `observe` (not `consume`)
- *  so the verb `consume` means exactly one thing repo-wide — the detached stream drain on
- *  {@link Subscribable}; this keyed, replay/onUnmount, edge-batched delivery is its own paradigm. */
+/**
+ * The mount-table consumer facet exposed on {@link MatbotRuntime.mounted}.
+ *
+ * A plugin needs this iff its `setup()` reads another service's *current state* to build cached/derived
+ * state — skills/triggers cache the StorageBackend's documents; cognition seeds from the SkillManager. A
+ * pure map (no setup data; data arrives later as a tool call or hook) needs nothing, and resolves the
+ * service per-invocation through its proxy/member instead.
+ *
+ *   // cache the backend's documents; rebuild on every swap (own initial load was in setup())
+ *   services.mounted.observe({ key: 'StorageBackend' }, () => this.load());
+ *
+ *   // depend on a peer service that may not be present yet; seed now if it is, and on each (re)mount
+ *   services.mounted.observe({ key: 'SkillManager', replay: true }, m => seed(m));
+ *
+ * The contract guarantees only *eventual, ordered* delivery of each key's net presence transition, and
+ * says nothing about timing — never assume a `register()` is observed inline or at a turn boundary. A
+ * reload (unregister+register before the edge) collapses to a single remount; an unregister not replaced
+ * by the edge is a committed unload, delivered to `onUnmount`. Handlers re-fire on a later remount, so
+ * they must be idempotent.
+ *
+ * `observe`, not `consume`, so the verb `consume` means exactly one thing repo-wide — the detached
+ * stream drain on {@link Subscribable}; this keyed, edge-batched delivery is its own paradigm.
+ */
 export interface Mounted {
   observe<K extends keyof MatbotServices>(
     options: MountConsumeOptions<K>,
@@ -374,11 +374,6 @@ export interface Mounted {
 
 export type ProviderAdapterFactory = (config: ProviderConfig) => ProviderAdapter;
 
-export type StoreFactory = (
-  kind:    string,
-  options: Record<string, unknown>,
-) => Store<{ id: string; version: string }>;
-
 // ── Plugin manifest ───────────────────────────────────────────────────────────
 
 export interface PluginManifest {
@@ -453,12 +448,11 @@ export interface VisibilityQuery {
  * notification is visible to that connection's principal. Absent ⇒ no partitioning, and every connection
  * sees everything.
  *
- * **The predicate is consulted for EVERY kind, and decides for itself which it filters.** It used to be
- * reached only for an `ItemChange` carrying a principal, because the caller gated on that — which left
- * every plugin-defined kind fanned out unfiltered with no hook capable of stopping it, and made `kind` a
- * constant not worth passing. Moving that judgement here is the point: routing a partitioned namespace and
- * addressing a notification to a recipient are two different policies, and only the implementation knows
- * which of its kinds want which. An implementation that has nothing to say about a kind returns `true`.
+ * **The predicate is consulted for EVERY kind, and decides for itself which it filters** — so a
+ * plugin-defined kind cannot be fanned out unfiltered with no hook capable of stopping it. Routing a
+ * partitioned namespace and addressing a notification to a recipient are two different policies, and only
+ * the implementation knows which of its kinds want which. One with nothing to say about a kind returns
+ * `true`.
  */
 export interface WatchVisibility {
   /**
@@ -488,9 +482,8 @@ export interface WatchVisibility {
  * **The token is a partition, never a principal.** The two are not interchangeable: one principal may
  * hold several profiles, and a profile may alias a namespace onto a third profile's partition, so the
  * partition serving a principal's files is not derivable from the principal id. Minting the token from
- * the identity in force — the bug this replaces — attached an addressable partition to files that were
- * in the shared base area, and would have pointed at an empty partition the moment one was created
- * under that name.
+ * the identity in force instead attaches an addressable partition to files that are in the shared base
+ * area, and points at an empty partition the moment one is created under that name.
  *
  * `current` and `enter` are one round trip and must stay each other's inverse: whatever `current`
  * returns, `enter` puts a reader back into the area those bytes were written to. Both live here rather
@@ -518,7 +511,6 @@ export interface MatbotPluginSpec {
   readonly apiVersion:  string;
   readonly manifest?:   PluginManifest;
   readonly provider?:   ProviderAdapterFactory;
-  readonly storage?:    Record<string, StoreFactory>;
   readonly tools?:      readonly Tool[];
   /**
    * When present, the runtime calls open(dotData) before creating the services object and uses the

package/src/principal-context.ts

@@ -1,4 +1,5 @@
 import type { Principal } from './types.js';
+import { scopeIterator } from './scoped-iterator.js';
 
 /**
  * Ambient carrier for the security {@link Principal} — the single mechanism by which any layer
@@ -115,32 +116,13 @@ function isAsyncIterator(value: unknown): value is AsyncIterator<unknown> & Asyn
     && typeof (value as AsyncIterator<unknown>).next === 'function';
 }
 
+// The per-pull re-entry itself is `scopeIterator` (./scoped-iterator.ts), shared with the usage carrier.
 function scopedIterator<T>(
   carrier:   PrincipalCarrier,
   principal: Principal,
   source:    AsyncIterator<T> & AsyncIterable<T>,
 ): AsyncIterableIterator<T> {
-  const inScope = <R>(f: () => R): R => carrier.run(principal, f);
-  // A Proxy rather than a fresh object literal: the value crossing back out must still BE what it was —
-  // a custom iterator's own methods, its prototype, `instanceof` — so only the pull points are replaced.
-  // Anything else is forwarded bound to the target, which a class-based iterator holding internal state
-  // (or an object with internal slots) requires.
-  const pulls: Record<PropertyKey, unknown> = {
-    [Symbol.asyncIterator]: () => proxy,
-    next:   (...args: [] | [undefined]) => inScope(() => source.next(...args)),
-    ...(source.return !== undefined ? { return: (value?: unknown) => inScope(() => source.return!(value)) } : {}),
-    ...(source.throw  !== undefined ? { throw:  (error?: unknown) => inScope(() => source.throw!(error))  } : {}),
-  };
-  const proxy = new Proxy(source, {
-    // `hasOwn`, not `in`: the latter reaches Object.prototype, which would serve `toString`/`constructor`
-    // off the lookup object instead of the iterator being wrapped.
-    get(target, prop) {
-      if (Object.hasOwn(pulls, prop)) return pulls[prop];
-      const value = Reflect.get(target, prop, target);
-      return typeof value === 'function' ? value.bind(target) : value;
-    },
-  }) as AsyncIterableIterator<T>;
-  return proxy;
+  return scopeIterator(source, f => carrier.run(principal, f));
 }
 
 /** Imperatively establish `principal` for the current flow (entry points only). */

package/src/scoped-iterator.ts

@@ -0,0 +1,50 @@
+/**
+ * Re-enter an ambient scope on every pull of an async iterator.
+ *
+ * The problem is the same wherever it appears: an async generator's body does not begin until the first
+ * pull, so an iterator returned out of a scope carries its whole extent OUT of it — the scope covered
+ * the construction, and the work then runs in whatever flow happens to pull it. The tool ABI
+ * (`executor.execute()`) returns exactly that shape, so both of matbot's ambient carriers need this, and
+ * both had written it out: `runAs` for the principal, and the runner for the usage call site.
+ *
+ * The two copies did not agree. This one is the careful version: a **Proxy**, so the value crossing back
+ * out still IS what it was — a class-based iterator keeps its own members, its prototype and
+ * `instanceof` — with only the pull points replaced. The object-literal copy silently dropped all of
+ * that, which held only for as long as every tool was a plain async generator.
+ *
+ * Whether re-entering per pull is *sound* is the caller's question, not this helper's, and the answer
+ * differs: an identity is a re-entrant label, so `runAs` re-establishes it freely, while a hold or a
+ * roll-up settles when its `fn` does and must not be re-acquired per pull. See `machineBusy` and
+ * `withUsageScope`, which deliberately do not use this.
+ */
+
+/** Run `f` inside the caller's ambient scope. The shape both `carrier.run(p, f)` and `withUsageSite(s, f)` take. */
+export type ScopeFn = <R>(f: () => R) => R;
+
+export function scopeIterator<T>(source: AsyncIterator<T>, inScope: ScopeFn): AsyncIterableIterator<T> {
+  const pulls: Record<PropertyKey, unknown> = {
+    [Symbol.asyncIterator]: () => proxy,
+    next:   (...args: [] | [undefined]) => inScope(() => source.next(...args)),
+    ...(source.return !== undefined ? { return: (value?: unknown) => inScope(() => source.return!(value)) } : {}),
+    ...(source.throw  !== undefined ? { throw:  (error?: unknown) => inScope(() => source.throw!(error))  } : {}),
+  };
+  const proxy: AsyncIterableIterator<T> = new Proxy(source, {
+    // `hasOwn`, not `in`: the latter reaches Object.prototype, which would serve `toString`/`constructor`
+    // off the lookup object instead of the iterator being wrapped.
+    get(target, prop) {
+      if (Object.hasOwn(pulls, prop)) return pulls[prop];
+      const value = Reflect.get(target, prop, target);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+  }) as AsyncIterableIterator<T>;
+  return proxy;
+}
+
+/**
+ * The iterable form: every iterator this hands out is scoped per pull. For a caller holding an
+ * `AsyncIterable` that is not itself iterator-shaped — legal, and what a tool returning a bare
+ * `{ [Symbol.asyncIterator]() {…} }` gives the runner.
+ */
+export function scopeIterable<T>(source: AsyncIterable<T>, inScope: ScopeFn): AsyncIterable<T> {
+  return { [Symbol.asyncIterator]: () => scopeIterator(source[Symbol.asyncIterator](), inScope) };
+}

package/src/session.ts

@@ -1,4 +1,31 @@
-import type { MessageContent, Session } from './types.js';
+import type { Message, MessageContent, MessageRole, Session } from './types.js';
+
+/**
+ * A `Message` with the fields every one carries minted for it — a fresh id, `createdAt` now — and the
+ * optional ones spread conditionally.
+ *
+ * Lives here rather than in core because a message is not core's to define: the hook registry builds
+ * marker messages in *this* package, and had its own copy of these five lines because core is
+ * downstream of it. There were five such copies in two packages, and every one of them is a place a
+ * message could quietly acquire a different shape.
+ */
+export function createMessage(opts: {
+  role:           MessageRole;
+  content:        MessageContent[];
+  traceId:        string;
+  providerName?:  string;
+  metadata?:      Record<string, unknown>;
+}): Message {
+  return {
+    id:        crypto.randomUUID(),
+    role:      opts.role,
+    content:   opts.content,
+    createdAt: new Date().toISOString(),
+    traceId:   opts.traceId,
+    ...(opts.providerName !== undefined ? { providerName: opts.providerName } : {}),
+    ...(opts.metadata     !== undefined ? { metadata:     opts.metadata     } : {}),
+  };
+}
 
 /**
  * A session's `updatedAt` invariant: the timestamp of its last message, or its own `createdAt` when it

package/src/types/hooks.ts

@@ -195,7 +195,8 @@ export interface FollowupResult {
    * `context` is folded EPHEMERALLY onto the redo (for-this-answer-only). `durable` is instead folded
    * onto the re-run's user message — persisted, visible (mark it `origin: 'robo'`), carried live as a
    * `robo-user` event — so a `contextual`-kind correction updates the conversation durably even when it
-   * lands post-commit. At least one of the two is present.
+   * lands post-commit. Normally at least one is supplied; the RETRACT is driven by the presence of this
+   * object, so `{}` means "pop and re-run with nothing added" rather than being quietly ignored.
    */
   retractAndRerun?: { context?: MessageContent[]; durable?: MessageContent[] };
   /**

package/src/types/knowledge.ts

@@ -21,6 +21,7 @@ export interface KnowledgeIndex {
    *  index never inspects an entry's opaque `source`. The party that indexed an entry owns retracting
    *  it — e.g. a skill manager retracts a hidden/deleted skill rather than the index policing tenants. */
   remove(id: string): Promise<void>;
+  /** Rejects with the signal's reason if it is already aborted; an abort during the search may reject too. */
   search(terms: Array<{ term: string; context?: string }>, signal: AbortSignal): Promise<KnowledgeEntry[]>;
   /** Enumerate all indexed entries. When present, register('KnowledgeIndex', …) drains these into the incoming backend. */
   entries?(): Iterable<KnowledgeEntry>;