@matatbread/matbot-core 0.1.0

package/src/registry.ts

@@ -0,0 +1,348 @@
+import type { Tool, ToolRegistry, Hook, PromptFn, FormField, FrontendInfo, PluginRegistryEvent } from './types.js';
+import { createBroadcaster } from '@matatbread/matbot-plugin-api';
+import type {
+  MatbotPlugin, MatbotMachine, Mounted,
+  ProviderAdapterFactory, StoreFactory,
+} from './plugin.js';
+import { PLUGIN_API_VERSION, unifyServices } from './plugin.js';
+import { HookRegistry } from './hooks.js';
+import { makePluginSettings } from './settings.js';
+import type { SettingsDoc } from './settings.js';
+
+// ── Internal state ────────────────────────────────────────────────────────────
+
+// Mutable arrays/maps held in a single object to make _resetRegistry() simple.
+const state = {
+  plugins:         [] as MatbotPlugin[],
+  providers:       new Map<string, ProviderAdapterFactory>(),
+  storage:         new Map<string, StoreFactory>(),
+  toolRegistry:    undefined as ToolRegistry | undefined,
+  frontendPlugins:  new Map<string, FrontendInfo>(),  // pluginName → info, written by services.registerFrontend()
+  serviceKeys:     new Map<string, string[]>(),  // pluginName → MatbotMachine keys it registered
+  hookPlugins:        new Set<string>(),         // plugins that registered at least one hook
+  systemContextPlugins: new Set<string>(),       // plugins that registered a system-context contributor
+  overwriteAllTools: undefined as boolean | undefined,  // persisted "overwrite on collision, this install" choice, loaded lazily
+};
+
+// Read-only observation of plugin load/unload, for consumers that key off plugin presence (e.g. the
+// web plugins panel refreshing live when a backend restores a plugin set out of band). Module-level,
+// not in `state` — it owns subscribers across the registry's lifetime, not per-plugin data.
+const pluginEvents = createBroadcaster<PluginRegistryEvent>();
+
+export function watchPlugins(signal?: AbortSignal): AsyncIterable<PluginRegistryEvent> {
+  return pluginEvents.subscribe(signal);
+}
+
+// Settings namespace + key under which the user's "overwrite all colliding tools" choice
+// is persisted for the installation. The namespace doubles as a Store document id, so it must
+// satisfy the storage id charset (/^[\w-]+$/) — hence underscores, not '@matbot/core'. The
+// dunder marks it reserved (internal), so it won't collide with a real plugin's settings.
+const CORE_SETTINGS_NS    = '__matbot_core__';
+const OVERWRITE_TOOLS_KEY = 'overwriteToolsOnCollision';
+
+/**
+ * Decide whether an incoming tool registration may overwrite an existing tool of the
+ * same name owned by a different plugin. Returns true to overwrite, false to keep the
+ * existing one and drop the incoming registration.
+ *
+ * Resolution order: a persisted "overwrite all (this install)" choice short-circuits to
+ * true; otherwise the user is prompted [n / Y / all] with Y (overwrite) as the default.
+ * 'all' persists the choice. With no prompt available (non-interactive host) we overwrite —
+ * the default — preserving matbot's historical last-registration-wins behaviour.
+ */
+async function resolveToolCollision(
+  services:      MatbotMachine,
+  toolName:      string,
+  existingOwner: string | undefined,
+  incomingOwner: string,
+  prompt:        PromptFn | undefined,
+): Promise<boolean> {
+  const coreSettings = makePluginSettings(services.createStore<SettingsDoc>('settings'), CORE_SETTINGS_NS);
+  if (state.overwriteAllTools === undefined) {
+    state.overwriteAllTools = (await coreSettings.get<boolean>(OVERWRITE_TOOLS_KEY)) ?? false;
+  }
+  if (state.overwriteAllTools) return true;
+
+  const owner = existingOwner !== undefined ? `"${existingOwner}"` : 'a built-in';
+  const label = `Tool \`"${toolName}"\` is already registered by **${owner}**. Overwrite it with the one from **"${incomingOwner}"**?`;
+
+  if (prompt === undefined) {
+    console.warn(`[matbot] ${label} — non-interactive, overwriting (default).`);
+    return true;
+  }
+
+  const field: FormField = {
+    name:    'overwrite',
+    label,
+    type:    'select',
+    options: ['Keep existing', 'Overwrite', 'Always overwrite'],
+    default: 'Overwrite',
+  };
+  const answer = (await prompt(field)).trim().toLowerCase();
+  if (answer.startsWith('a')) {  // "Always overwrite" — persist for the installation
+    state.overwriteAllTools = true;
+    await coreSettings.set(OVERWRITE_TOOLS_KEY, true);
+    return true;
+  }
+  return !answer.startsWith('k');  // "Keep existing" → false; "Overwrite"/default → true
+}
+
+// ── Version check ─────────────────────────────────────────────────────────────
+
+function checkApiVersion(plugin: MatbotPlugin): void {
+  const [rMajor = '0', rMinor = '0'] = PLUGIN_API_VERSION.split('.');
+  const [pMajor = '0', pMinor = '0'] = plugin.apiVersion.split('.');
+
+  if (pMajor !== rMajor) {
+    throw new Error(
+      `Plugin "${plugin.name}" requires API ${plugin.apiVersion} (major ${pMajor}) ` +
+      `but runtime provides ${PLUGIN_API_VERSION}. ` +
+      `Update the plugin or the runtime.`,
+    );
+  }
+  if (Number(pMinor) > Number(rMinor)) {
+    console.warn(
+      `[matbot] Plugin "${plugin.name}" targets API ${plugin.apiVersion} ` +
+      `but runtime is ${PLUGIN_API_VERSION}. Some features may not be available.`,
+    );
+  }
+}
+
+// ── Registration ──────────────────────────────────────────────────────────────
+
+export function registerPlugin(plugin: MatbotPlugin): void {
+  checkApiVersion(plugin);
+
+  if (state.plugins.some(p => p.name === plugin.name)) {
+    throw new Error(`Plugin "${plugin.name}" is already registered.`);
+  }
+
+  if (plugin.provider !== undefined && state.providers.has(plugin.name)) {
+    throw new Error(`Provider "${plugin.name}" is already registered.`);
+  }
+
+  for (const type of Object.keys(plugin.storage ?? {})) {
+    if (state.storage.has(type)) {
+      const owner = state.plugins.find(p => p.storage?.[type] !== undefined)?.name ?? '?';
+      throw new Error(
+        `Storage type "${type}" is already registered by "${owner}". ` +
+        `"${plugin.name}" cannot register it again.`,
+      );
+    }
+  }
+
+  state.plugins.push(plugin);
+
+  if (plugin.provider !== undefined) {
+    state.providers.set(plugin.name, plugin.provider);
+  }
+  for (const [type, factory] of Object.entries(plugin.storage ?? {})) {
+    state.storage.set(type, factory);
+  }
+
+  pluginEvents.emit({ type: 'loaded', name: plugin.name });
+}
+
+// ── Resolution ────────────────────────────────────────────────────────────────
+
+export function resolveProviderFactory(module: string): ProviderAdapterFactory {
+  const factory = state.providers.get(module);
+  if (factory === undefined) {
+    const available = [...state.providers.keys()].join(', ') || 'none';
+    throw new Error(
+      `No provider registered for module "${module}". ` +
+      `Available: ${available}. ` +
+      `Install and load the provider plugin.`,
+    );
+  }
+  return factory;
+}
+
+export function getRegisteredTools(): readonly Tool[] {
+  return state.toolRegistry?.list() ?? [];
+}
+
+export function getRegisteredPlugins(): readonly MatbotPlugin[] {
+  return state.plugins;
+}
+
+export function getRegisteredFrontendPlugins(): ReadonlyMap<string, FrontendInfo> {
+  return state.frontendPlugins;
+}
+
+/** MatbotMachine keys a plugin registered at runtime via services.register() (e.g. 'KnowledgeIndex'). */
+export function getRegisteredServiceKeys(pluginName: string): readonly string[] {
+  return state.serviceKeys.get(pluginName) ?? [];
+}
+
+/**
+ * Attribute a service key to a plugin out of band. The host uses this for a backend it opened at boot
+ * *before* the registry knew the plugin's name — a storageBackend manifest pre-scan bypasses the scoped
+ * register() that would normally record the key. Recording it makes the boot-opened backend unload-equal
+ * to a runtime register(): unloadPlugin() then calls unregister() for it, reverting to the host base.
+ */
+export function recordServiceKey(pluginName: string, key: string): void {
+  const keys = state.serviceKeys.get(pluginName) ?? [];
+  if (!keys.includes(key)) keys.push(key);
+  state.serviceKeys.set(pluginName, keys);
+}
+
+/** Plugins that registered at least one hook in setup(). */
+export function getHookPlugins(): ReadonlySet<string> {
+  return state.hookPlugins;
+}
+
+/** Plugins that registered a system-context contributor in setup(). */
+export function getSystemContextPlugins(): ReadonlySet<string> {
+  return state.systemContextPlugins;
+}
+
+/** Resolve a loaded plugin's name from the specifier used to load it. Each plugin carries its own
+ *  specifier, so this is a scan of the plugin list — no side-map to keep in sync. */
+export function getPluginNameForSpecifier(specifier: string): string | undefined {
+  return state.plugins.find(p => p.specifier === specifier)?.name;
+}
+
+/** Reverse of getPluginNameForSpecifier — finds the specifier used to load the named plugin. */
+export function getSpecifierForPlugin(pluginName: string): string | undefined {
+  return state.plugins.find(p => p.name === pluginName)?.specifier;
+}
+
+// ── Lifecycle ─────────────────────────────────────────────────────────────────
+
+/**
+ * Run setup() for a single plugin. Called by loadPlugins immediately after registration.
+ *
+ * `prompt`, when supplied by the host, makes tool-name collisions interactive: registering a
+ * tool whose name a *different* plugin already owns asks the user whether to overwrite. Absent
+ * (non-interactive host), collisions overwrite silently — the historical default.
+ */
+export async function setupPlugin(plugin: MatbotPlugin, services: MatbotMachine, prompt?: PromptFn): Promise<void> {
+  state.toolRegistry ??= services.tools;
+
+  // Single choke point for every plugin tool registration (static `plugin.tools` and in-setup
+  // `services.tools.register`). Stamps ownership and resolves name collisions. The no-collision
+  // path runs synchronously (an async fn yields nothing before its first await), so fire-and-forget
+  // callers that don't await still get the tool registered in the same tick.
+  const registerTool = async (tool: Tool): Promise<void> => {
+    const stamped: Tool = { ...tool, pluginName: plugin.name };
+    const existing = services.tools.resolve(stamped.name);
+    if (existing !== null && existing.pluginName !== plugin.name) {
+      const overwrite = await resolveToolCollision(services, stamped.name, existing.pluginName, plugin.name, prompt);
+      if (!overwrite) return;
+    }
+    services.tools.register(stamped);
+  };
+
+  // Plugin-scoped settings: bound to this plugin's identity, built once. A plugin reaches only its
+  // own settings — there is no way to name another's.
+  const ownSettings = makePluginSettings(services.createStore<SettingsDoc>('settings'), plugin.name);
+
+  // Per-plugin `mounted`: a thin adapter over the host mount table that delivers *this plugin's* scoped
+  // machine (and scoped onUnmount) to handlers. The stable `scoped` object reads through the host's
+  // re-pointing proxies/registry, so `scoped[key]` is the host's live service by the time a transition
+  // fires. Forward-referenced via `scoped`, assigned below; consume() only runs after setup.
+  let scoped: MatbotMachine;
+  const scopedMounted: Mounted = {
+    consume(options, handler) {
+      // Forward to the host mount table but deliver *this plugin's* scoped machine — it reads through
+      // the same proxies/registry, so scoped[key] is the host's live service. onUnmount is scoped too.
+      const forwarded = options.onUnmount !== undefined
+        ? { ...options, onUnmount: () => options.onUnmount!(scoped) }
+        : options;
+      services.mounted.consume(forwarded, () => handler(scoped as never));
+    },
+  };
+
+  scoped = unifyServices({
+    ...services,
+    mounted: scopedMounted,
+    settings: () => ownSettings,
+    self: {
+      name:      plugin.name,
+      specifier: plugin.specifier,
+      ...(plugin.source !== undefined ? { source: plugin.source } : {}),
+    },
+    tools: {
+      register:      registerTool,
+      remove:        (name: string) => services.tools.remove(name),
+      resolve:       (name: string) => services.tools.resolve(name),
+      list:          ()             => services.tools.list(),
+      removeByPlugin:(name: string) => services.tools.removeByPlugin(name),
+      watch:         (signal?: AbortSignal) => services.tools.watch(signal),
+    },
+    hooks: {
+      register(hook: Hook) {
+        state.hookPlugins.add(plugin.name);
+        services.hooks.register({ ...hook, pluginName: plugin.name } as Hook);
+      },
+      removeByPlugin: (name: string) => services.hooks.removeByPlugin(name),
+    } as unknown as HookRegistry,
+    systemContext: {
+      register(contributor) {
+        state.systemContextPlugins.add(plugin.name);
+        services.systemContext.register(contributor, plugin.name);
+      },
+      removeByPlugin: (name: string) => services.systemContext.removeByPlugin(name),
+      build:          (ctx)          => services.systemContext.build(ctx),
+    },
+    async register(key, svc) {
+      const keys = state.serviceKeys.get(plugin.name) ?? [];
+      keys.push(key as string);
+      state.serviceKeys.set(plugin.name, keys);
+      await services.register(key, svc);
+    },
+    registerFrontend(info) {
+      state.frontendPlugins.set(plugin.name, info);
+    },
+  });
+  for (const tool of plugin.tools ?? []) {
+    await registerTool(tool);
+  }
+  await plugin.setup?.(scoped);
+}
+
+/** Tear down and fully unload a single plugin, removing all its registered contributions. */
+export async function unloadPlugin(pluginName: string, services: MatbotMachine): Promise<boolean> {
+  console.warn(`[matbot] Unloading plugin "${pluginName}"`);
+  const idx = state.plugins.findIndex(p => p.name === pluginName);
+  if (idx === -1) return false;
+
+  // Note: all synchronous cleanup (removing tools, hooks, services) is done before any asynchronous teardown() calls, to ensure a consistent state even if teardown() fails or hangs.
+  const plugin = state.plugins[idx]!;
+
+  services.tools.removeByPlugin(pluginName);
+  services.hooks.removeByPlugin(pluginName);
+  services.systemContext.removeByPlugin(pluginName);
+
+  for (const key of state.serviceKeys.get(pluginName) ?? []) {
+    services.unregister(key);
+  }
+  state.serviceKeys.delete(pluginName);
+  state.hookPlugins.delete(pluginName);
+  state.systemContextPlugins.delete(pluginName);
+
+  if (plugin.provider !== undefined) state.providers.delete(plugin.name);
+  for (const type of Object.keys(plugin.storage   ?? {})) state.storage.delete(type);
+
+  state.frontendPlugins.delete(pluginName);
+
+  state.plugins.splice(idx, 1);
+  pluginEvents.emit({ type: 'unloaded', name: pluginName });
+  await Promise.race([
+    plugin.teardown?.(),
+    new Promise<void>((_, reject) => setTimeout(() => reject(new Error(`Teardown timeout for plugin ${pluginName}`)), 10000))
+  ]);
+  return true;
+}
+
+/** Run each plugin's teardown() in reverse-registration order. Errors are logged, not thrown. */
+export async function teardownPlugins(): Promise<void> {
+  const results = await Promise.allSettled([...state.plugins].reverse().map(plugin => plugin.teardown?.()));
+  results.forEach((result, i) => {
+    if (result.status === 'rejected') {
+      console.error(`[matbot] teardown error in plugin "${state.plugins[i]?.name}":`, result.reason);
+    }
+  });
+}
+

package/src/runner.ts

@@ -0,0 +1,324 @@
+import type {
+  Session, MessageContent,
+  PipelineEvent, RunConfig, ProviderAdapter, ProviderConfig,
+  Tool, ToolRegistry, ToolContext, Store, FileStore, SystemContextRegistry, Vault, PromptFn, FormField,
+} from './types.js';
+import type { MatbotPlugin } from './plugin.js';
+import { HookRegistry } from './hooks.js';
+import { appendMessage, createMessage } from './session.js';
+
+export interface RunSessionOpts {
+  session:        Session;
+  config:         RunConfig;
+  provider:       ProviderAdapter;
+  providerConfig: ProviderConfig;
+  tools?:         ReadonlyMap<string, Tool>;
+  /**
+   * Live registry consulted to *resolve the executor* at call time. The `tools` map above is a
+   * turn-start snapshot — the stable menu advertised to the model for the whole turn — but a tool
+   * that mutates the registry mid-turn (`plugin reload`/`add`/`remove`) must take effect for any
+   * call later in the *same* turn, so execution resolves against this live registry rather than the
+   * snapshot. Present ⇒ authoritative (a tool removed mid-turn resolves to null ⇒ "Unknown tool",
+   * which is correct); absent ⇒ falls back to the snapshot (direct callers / tests that pass only
+   * `tools`).
+   */
+  toolRegistry?:  ToolRegistry;
+  store:          Store<Session>;
+  hooks?:         HookRegistry;
+  systemContext?: SystemContextRegistry;
+  signal:         AbortSignal;
+  vault?:         Vault;
+  workdir?:       string;
+  configPath?:    string;
+  files?:         FileStore;
+  /** Supply a prompt implementation to allow tools to ask interactive questions. */
+  prompt?:        PromptFn;
+  /**
+   * Turn-scoped context to inject ephemerally, exactly like a `screen` hook's `ephemeral` (tail-folded
+   * onto the freshest non-marker message, never persisted) — merged ahead of whatever `screen` adds.
+   * The pump supplies this for an agent-phase retract-redo: the trigger tool's output rides into the
+   * re-run of the originating user turn. Empty/absent for an ordinary turn.
+   */
+  injectedEphemeral?: MessageContent[];
+  loadPlugin:     (specifier: string, prompt?: PromptFn) => Promise<MatbotPlugin>;
+  unloadPlugin:   (specifier: string) => Promise<boolean>;
+}
+
+export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineEvent> {
+  const { config, provider, providerConfig, store, signal } = opts;
+  const tools   = opts.tools   ?? new Map<string, Tool>();
+  const hookReg = opts.hooks   ?? new HookRegistry();
+  const promptFn: PromptFn = opts.prompt ?? (((p: string | FormField, def?: string): Promise<string> => {
+    const fallback = typeof p === 'string' ? def : p.default;
+    if (fallback !== undefined) return Promise.resolve(fallback);
+    const label = typeof p === 'string' ? p : p.label;
+    return Promise.reject(new Error(`Non-interactive context: cannot prompt for "${label}"`));
+  }) as PromptFn);
+  const vault: Vault = opts.vault ?? {
+    async createSecret() { throw new Error('No vault configured'); },
+    async writeSecret()  { throw new Error('No vault configured'); },
+    hasKey() { return false; },
+    async resolve(ref: string) { return ref; },
+    scrub(text: string) { return text; },
+  };
+  const traceId = config.traceId ?? crypto.randomUUID();
+
+  // ── 1. screen — once per turn: shape/abort the incoming submission ──────────
+
+  const screen = await hookReg.runScreen({ session: opts.session, config, signal, prompt: promptFn });
+  if (screen.abort) {
+    // Hook-failure (and any other screen-injected) markers carried live, even on abort, so a
+    // misconfigured hook surfaces this turn rather than only on a later reload.
+    if (screen.markers.length > 0) yield { type: 'marker', content: screen.markers, traceId };
+    await store.set(screen.session.id, screen.session);
+    yield { type: 'aborted', reason: screen.abort, session: screen.session, traceId };
+    return;
+  }
+  // Durable context a screen hook folded onto the user message (e.g. a fired `contextual` trigger),
+  // carried live so a frontend draws it now rather than only on a later reload. It is already part of
+  // screen.session (origin: 'robo' blocks on the user turn) — this event is purely live delivery.
+  // Emitted BEFORE the markers so the live order matches a reload: the durable blocks belong to the
+  // user message (rendered with the turn), while screen markers were appended to the session AFTER it.
+  if (screen.durable.length > 0) {
+    yield { type: 'robo-user', content: screen.durable, traceId };
+  }
+  // Hook-failure (and any other screen-injected) markers, carried live so the UI shows them this turn
+  // rather than only on a later session reload. They are already persisted in screen.session.
+  if (screen.markers.length > 0) {
+    yield { type: 'marker', content: screen.markers, traceId };
+  }
+  let session = screen.session;
+
+  // Turn-scoped ephemeral context from screen — appended to the TAIL of the outgoing messages
+  // (onto the content of the freshest history message, preserving its role), never persisted.
+  // At the tail, not as a system prefix, because (a) a "do X now" directive needs the salience of
+  // being the last thing the model reads — a system-block prefix sits above the whole history and
+  // reads as stale once the turn has any momentum — and (b) per-turn content in the prefix would
+  // bust the cached system/history prefix every turn; appended at the tail it leaves the prefix
+  // byte-stable. Folding into the last message (rather than adding a trailing message) avoids
+  // role-alternation hazards and survives both adapters (Anthropic folds system→system=; OpenAI
+  // drops non-result content from tool-role messages — a separate trailing message would break on
+  // one or the other).
+  // injectedEphemeral (a pump-supplied retract-redo's context) leads, then screen's own — both share
+  // the identical tail-fold path below.
+  const ephemeral = [...(opts.injectedEphemeral ?? []), ...screen.ephemeral];
+
+  // ── 2. System context (built once per submit, never persisted) ─────────────
+
+  const systemText = opts.systemContext
+    ? await opts.systemContext.build({ session, signal })
+    : null;
+
+  const systemMsg = systemText !== null
+    ? [createMessage({ role: 'system', content: [{ type: 'text', text: systemText }], traceId: '' })]
+    : [];
+
+  if (systemText !== null) {
+    yield { type: 'system-context', text: systemText, traceId };
+  }
+
+  // ── 3. Agentic loop ────────────────────────────────────────────────────────
+
+  for (;;) {
+    // Respect an abort that arrived between turns (e.g. during tool execution).
+    if (signal.aborted) {
+      await store.set(session.id, session);
+      yield { type: 'aborted', reason: typeof signal.reason === 'string' ? signal.reason : 'user-abort', session, traceId };
+      return;
+    }
+
+    const pendingCalls: Array<{ id: string; name: string; input: unknown }> = [];
+    const assistantParts: MessageContent[] = [];
+    let textAcc = '';
+
+    // One provider call. The outgoing array (system context + history, with screen's ephemeral
+    // blocks appended onto the tail message) is assembled here and handed to `contribute` hooks for
+    // a final ephemeral transform — none of this is written back to the session.
+    // Fold onto the last NON-marker message: markers are elided from the wire, so the literal last
+    // message can be a marker (e.g. a retract-redo leaves the retraction marker as the tail) — folding
+    // there would drop the ephemeral with it. -1 ⇒ nothing to fold onto (no non-marker history).
+    const foldIdx = ephemeral.length > 0 ? session.messages.findLastIndex(m => m.role !== 'marker') : -1;
+    const history = foldIdx >= 0
+      ? session.messages.map((m, i) =>
+          i === foldIdx ? { ...m, content: [...m.content, ...ephemeral] } : m)
+      : session.messages;
+    const outgoing = await hookReg.runContribute({
+      outgoing: [...systemMsg, ...history],
+      session, config, signal,
+    });
+    try {
+      for await (const ev of provider.complete(outgoing, providerConfig, [...tools.values()], signal)) {
+        switch (ev.type) {
+          case 'text-delta':
+            textAcc += ev.delta;
+            yield { type: 'text-delta', delta: ev.delta, traceId };
+            break;
+          case 'thinking':
+            yield { type: 'thinking', delta: ev.delta, traceId };
+            break;
+          case 'thinking-block':
+            assistantParts.push({ type: 'thinking', thinking: ev.thinking, signature: ev.signature });
+            break;
+          case 'redacted-thinking':
+            assistantParts.push({ type: 'redacted-thinking', data: ev.data });
+            break;
+          case 'unknown-block':
+            assistantParts.push({ type: 'unknown-content', blockType: ev.blockType, raw: ev.raw });
+            break;
+          case 'reasoning-block':
+            assistantParts.push({ type: 'reasoning', reasoning: ev.reasoning });
+            break;
+          case 'tool-call':
+            pendingCalls.push({ id: ev.id, name: ev.name, input: ev.input });
+            break;
+          case 'usage':
+            yield { type: 'usage', inputTokens: ev.inputTokens, outputTokens: ev.outputTokens, traceId,
+              ...(ev.costUsd              !== undefined ? { costUsd:              ev.costUsd              } : {}),
+              ...(ev.cacheReadTokens     !== undefined ? { cacheReadTokens:     ev.cacheReadTokens     } : {}),
+              ...(ev.cacheCreationTokens !== undefined ? { cacheCreationTokens: ev.cacheCreationTokens } : {}) };
+            break;
+          case 'done':
+            break;
+        }
+      }
+    } catch (e: any) {
+      if (signal.aborted) {
+        // Save whatever the LLM streamed before the abort hit.
+        if (textAcc) assistantParts.push({ type: 'text', text: textAcc });
+        if (assistantParts.length > 0) {
+          session = appendMessage(session, createMessage({
+            role: 'assistant', content: assistantParts, traceId, providerName: config.provider,
+          }));
+        }
+        await store.set(session.id, session);
+        yield { type: 'aborted', reason: typeof signal.reason === 'string' ? signal.reason : 'user-abort', session, traceId };
+        return;
+      }
+      yield { type: 'error', error: String(e) + (('cause' in e && e.cause) ? ' ('+String(e.cause)+')' : '' ), traceId };
+      return;
+    }
+
+    // Build and store assistant message
+    if (textAcc)           assistantParts.push({ type: 'text', text: textAcc });
+    for (const tc of pendingCalls) {
+      assistantParts.push({ type: 'tool-call', id: tc.id, name: tc.name, input: tc.input });
+    }
+
+    if (assistantParts.length > 0) {
+      const assistantMsg = createMessage({
+        role:         'assistant',
+        content:      assistantParts,
+        traceId,
+        providerName: config.provider,
+      });
+      session = appendMessage(session, assistantMsg);
+    } else {
+      // Diagnostic: the provider returned no text, no tool calls, no thinking — a genuinely empty
+      // completion. The turn will end with no assistant message, which reads as "the agent never
+      // replied". Logged here so a silent no-reply turn is traceable. (textAcc length is shown to
+      // tell a truly empty stream apart from one that was only whitespace.)
+      console.warn(`[runner] empty completion (no assistant content) on traceId ${traceId}; textAcc=${textAcc.length} chars, provider=${config.provider}`);
+    }
+
+    // No tool calls → done
+    if (pendingCalls.length === 0) break;
+
+    // ── 3. Execute tool calls ────────────────────────────────────────────────
+
+    const toolResults: MessageContent[] = [];
+    const toolMarkers: MessageContent[] = [];
+
+    for (const tc of pendingCalls) {
+      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);
+      if (!tool) {
+        const err = { error: `Unknown tool: ${tc.name}` };
+        toolResults.push({ type: 'tool-result', id: tc.id, result: err, isError: true });
+        yield { type: 'tool:end', callId: tc.id, result: err, isError: true, traceId };
+        continue;
+      }
+
+      const decision = await hookReg.runToolCall({
+        session, config, signal,
+        toolCall: { id: tc.id, name: tc.name, input: tc.input },
+        tool,
+      });
+      if (decision.abort) {
+        yield { type: 'aborted', reason: decision.abort, session, traceId };
+        return;
+      }
+      if (decision.rejectTool) {
+        const err = { error: decision.rejectTool.message };
+        toolResults.push({ type: 'tool-result', id: tc.id, result: err, isError: true });
+        yield { type: 'tool:end', callId: tc.id, result: err, isError: true, traceId };
+        continue;
+      }
+
+      let result: unknown;
+      let isError = false;
+      const startedAt = Date.now();
+
+      const toolCtx: ToolContext = {
+        callId: tc.id, session, signal, vault,
+        provider:     config.provider,
+        prompt:       promptFn,
+        loadPlugin:   (specifier: string) => opts.loadPlugin(specifier, promptFn),
+        unloadPlugin: opts.unloadPlugin,
+        ...(opts.workdir     !== undefined ? { workdir:     opts.workdir     } : {}),
+        ...(opts.configPath  !== undefined ? { configPath:  opts.configPath  } : {}),
+        ...(opts.files       !== undefined ? { files:       opts.files       } : {}),
+      };
+
+      try {
+        for await (const toolEv of tool.executor.execute(tc.input, toolCtx)) {
+          switch (toolEv.type) {
+            case 'stdout':   yield { type: 'tool:stdout', callId: tc.id, chunk: toolEv.chunk, traceId }; break;
+            case 'stderr':   yield { type: 'tool:stderr', callId: tc.id, chunk: toolEv.chunk, traceId }; break;
+            case 'file':     yield { type: 'file', handle: toolEv.handle, traceId }; break;
+            case 'result':   result = toolEv.value; break;
+            case 'marker':   toolMarkers.push({ type: 'marker', creator: toolEv.creator, data: toolEv.data }); break;
+            case 'progress': break;
+            case 'error':    result = {
+              error: toolEv.message,
+              ...(toolEv.stdout !== undefined ? { stdout: toolEv.stdout } : {}),
+              ...(toolEv.stderr !== undefined ? { stderr: toolEv.stderr } : {}),
+            }; isError = true; break;
+          }
+        }
+      } catch (e) {
+        result  = { error: String(e) };
+        isError = true;
+      }
+
+      // toolresult — last chance to transform the result before it's recorded/yielded (hard redaction),
+      // or to observe it (auditing: args + result + timing). Owns the LLM-facing + persisted surfaces.
+      result = await hookReg.runToolResult({
+        session, config, signal,
+        toolCall: { id: tc.id, name: tc.name, input: tc.input },
+        tool, result, isError, durationMs: Date.now() - startedAt,
+      });
+
+      toolResults.push({ type: 'tool-result', id: tc.id, result, isError });
+      yield { type: 'tool:end', callId: tc.id, result, isError, traceId };
+    }
+
+    // Add tool results message, then loop for the next provider call.
+    const toolMsg = createMessage({ role: 'tool', content: toolResults, traceId });
+    session = appendMessage(session, toolMsg);
+
+    // Markers a tool emitted while running: persist as their own marker-role message (elided from
+    // provider submission) and carry live so a frontend can render them without a reload.
+    if (toolMarkers.length > 0) {
+      session = appendMessage(session, createMessage({ role: 'marker', content: toolMarkers, traceId }));
+      yield { type: 'marker', content: toolMarkers, traceId };
+    }
+  }
+
+  // ── 4. Persist and finish ──────────────────────────────────────────────────
+  // `react` fires post-commit, in pump (the queue owner) — not here.
+
+  await store.set(session.id, session);
+
+  yield { type: 'done', session, traceId };
+}

package/src/security/grants.ts

@@ -0,0 +1,6 @@
+import type { Principal } from '@matatbread/matbot-plugin-api';
+
+/** Convenience: the system principal — the origin for operations not driven by an external user. */
+export function systemPrincipal(id = 'system'): Principal {
+  return { id, type: 'system' };
+}