@matatbread/matbot-plugin-api 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Mat Woolf
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,20 @@
+# @matatbread/matbot-plugin-api
+
+The plugin API for [matbot](https://github.com/MatAtBread/matbot) — a thin, composable
+TypeScript AI harness.
+
+This is the **singleton contract** every matbot plugin builds against: the `MatbotPlugin`
+type, the `MatbotServices`/`MatbotRuntime`/`MatbotMachine` registry, the hook channels, the
+ambient principal carrier, the `Vault`/`Store` interfaces, and the shared error types.
+
+Plugins should declare it as a **peer dependency** (the host provides the single shared copy
+— two copies would break `instanceof` checks, the principal carrier, and module
+augmentation). It ships as raw TypeScript and requires **Node 24+** (native type stripping)
+or a bundler.
+
+See the [main repository](https://github.com/MatAtBread/matbot) for the full design guide and
+plugin-authoring docs.
+
+## License
+
+Apache-2.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@matatbread/matbot-plugin-api",
+  "matbotRuntime": [
+    "node",
+    "browser"
+  ],
+  "version": "0.1.0",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "files": [
+    "src"
+  ],
+  "description": "matbot plugin API: the singleton contract every matbot plugin builds against — MatbotPlugin, the service registry, hooks, principal carrier, and shared types.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MatAtBread/matbot.git",
+    "directory": "plugin-api"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/broadcast.ts

@@ -0,0 +1,73 @@
+// A minimal multi-subscriber fan-out for AsyncIterable observation streams (tool/plugin/skill watch,
+// and any future plugin-owned CRUD stream). Each subscriber gets its own unbounded queue, so a slow
+// consumer never blocks emit() or its peers. Acceptable because these events are rare and small
+// (registry/document CRUD); this is not a high-throughput data path. emit() is synchronous and never throws.
+
+interface Subscriber<T> {
+  queue: T[];
+  wake:  (() => void) | undefined;
+  done:  boolean;
+}
+
+// The consumer facet — what a stream hands out. `emit` is the producer's, kept off this so a
+// surface that only exposes observation (e.g. services.mounted) cannot forge events.
+export interface Subscribable<T> {
+  subscribe(signal?: AbortSignal): AsyncIterable<T>;
+  // Detached observation loop: awaits each handler before pulling the next (no overlapping runs),
+  // isolates a throwing handler (logged, never propagated — a bad observer must not kill the stream),
+  // and ends when the source ends or `signal` aborts. The fire-and-forget form of the for-await loop
+  // every watch call site otherwise hand-writes.
+  consume(handler: (value: T) => void | Promise<void>, signal?: AbortSignal): void;
+}
+
+export interface Broadcaster<T> extends Subscribable<T> {
+  emit(value: T): void;
+}
+
+/**
+ * Wrap a bare subscribe generator into a full {@link Subscribable}, supplying the standard detached
+ * `consume` loop. Use for a *derived* stream — e.g. a per-plugin scoped view of a shared broadcaster —
+ * that owns its own subscribe generator but wants the same consume ergonomics as a real broadcaster.
+ */
+export function subscribable<T>(subscribe: (signal?: AbortSignal) => AsyncIterable<T>): Subscribable<T> {
+  const consume = (handler: (value: T) => void | Promise<void>, signal?: AbortSignal): void => {
+    void (async () => {
+      for await (const v of subscribe(signal)) {
+        try { await handler(v); }
+        catch (e) { console.error('[matbot] consume handler threw:', e instanceof Error ? e.message : e); }
+      }
+    })();
+  };
+  return { subscribe, consume };
+}
+
+export function createBroadcaster<T>(): Broadcaster<T> {
+  const subs = new Set<Subscriber<T>>();
+
+  const emit = (value: T): void => {
+    for (const sub of subs) {
+      sub.queue.push(value);
+      sub.wake?.();
+    }
+  };
+
+  async function* subscribe(signal?: AbortSignal): AsyncIterable<T> {
+    const sub: Subscriber<T> = { queue: [], wake: undefined, done: false };
+    subs.add(sub);
+    const onAbort = () => { sub.done = true; sub.wake?.(); };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+      while (true) {
+        while (sub.queue.length > 0) yield sub.queue.shift()!;
+        if (sub.done || signal?.aborted) return;
+        await new Promise<void>(resolve => { sub.wake = resolve; });
+        sub.wake = undefined;
+      }
+    } finally {
+      subs.delete(sub);
+      signal?.removeEventListener('abort', onAbort);
+    }
+  }
+
+  return { emit, ...subscribable(subscribe) };
+}

package/src/context-switch.ts

@@ -0,0 +1,73 @@
+import type { Principal } from './types.js';
+import { runAs } from './principal-context.js';
+
+/**
+ * A context switch is the machine analogue of an OS one: it pages in any pending machine state and
+ * sets the owner. {@link runAs} is the bare "set the owner" instruction (the principal carrier);
+ * {@link contextSwitch} is the scheduler operation layered on top — it also lands any machine
+ * mutation that was deferred while the machine was busy.
+ *
+ * Why deferral exists: a service like the `StorageBackend` is the system of record, and swapping it
+ * under a running operation would split a compare-and-swap (or a turn) across two backends. So a
+ * swap is queued and applied only at the *quiescent edge* — the instant no context is active — which
+ * is exactly a context-switch boundary. The principal carrier stays a pure identity primitive; this
+ * module owns the machine-update half, so the two concerns share call sites without sharing code.
+ *
+ * The host registers what to flush ({@link onContextQuiesce}); the three entry points (a web
+ * request, a telegram message, a turn) switch context through {@link contextSwitch} instead of
+ * calling {@link runAs} directly. The boot principal (an `enter`, not a `run`) is the depth-0
+ * baseline and is never counted.
+ */
+
+const quiescers = new Set<() => void>();
+let depth = 0;
+let flushing = false;
+
+/**
+ * Register a machine-update flush, run at every quiescent edge (no context active). Flushers MUST be
+ * idempotent: a no-op when nothing is pending, since the edge is reached after every operation.
+ * Returns an unregister fn. A throwing flusher is isolated — one must not block the others or escape
+ * into the operation that triggered the edge.
+ */
+export function onContextQuiesce(flush: () => void): () => void {
+  quiescers.add(flush);
+  return () => { quiescers.delete(flush); };
+}
+
+/**
+ * Run the registered flushers iff no context is currently active — the quiescent edge. Called by
+ * {@link contextSwitch} at both edges, and by the host right after it *queues* a deferred mutation:
+ * queued while busy (depth > 0) this no-ops and the exit edge lands it; queued while idle (depth 0)
+ * it applies immediately, so an idle-time swap doesn't wait for the next request to take effect.
+ */
+export function flushIfQuiescent(): void {
+  if (depth !== 0 || flushing) return;
+  flushing = true;
+  try {
+    for (const q of quiescers) {
+      try { q(); }
+      catch (e) { console.error('[matbot] context-quiesce flush threw:', e instanceof Error ? e.message : e); }
+    }
+  } finally {
+    flushing = false;
+  }
+}
+
+/**
+ * Switch into the machine as `principal`: land any pending machine mutation (only safe while idle),
+ * then run `fn` under the principal. Mirrors {@link runAs}'s sync/async return — when `fn` is async,
+ * the context stays open until its promise settles, so the depth count tracks the real operation.
+ */
+export function contextSwitch<T>(principal: Principal, fn: () => T): T {
+  flushIfQuiescent();
+  depth++;
+  const settle = (): void => { depth--; flushIfQuiescent(); };
+  let result: T;
+  try {
+    result = runAs(principal, fn);
+  } catch (e) {
+    settle();
+    throw e;
+  }
+  return result instanceof Promise ? (result.finally(settle) as T) : (settle(), result);
+}

package/src/errors.ts

@@ -0,0 +1,69 @@
+/**
+ * Thrown by Vault.resolve() when one or more ${NAME} placeholders cannot be resolved.
+ * `missingKeys` carries the unresolved key names (e.g. `ANTHROPIC_API_KEY`) so callers
+ * can prompt for and store them.
+ */
+export class MissingSecretError extends Error {
+  readonly missingKeys: readonly string[];
+
+  constructor(missingKeys: readonly string[]) {
+    super(`Vault: secret(s) not found: ${missingKeys.join(', ')}`);
+    this.name        = 'MissingSecretError';
+    this.missingKeys = missingKeys;
+  }
+}
+
+/**
+ * Thrown by the loader when an explicit, single, user-initiated load (the `plugin`/`provider`
+ * tools via `services.loadPlugin`) targets a plugin whose `matbotRuntime` excludes this host.
+ * Unlike a setup() failure — which may be transient (a missing secret) and is left in config to
+ * fix — this is permanent for the host, so the `add` flow catches it specifically and rolls the
+ * specifier back out of matbot.yaml rather than persisting a plugin that can never activate here.
+ */
+export class IncompatibleRuntimeError extends Error {
+  readonly specifier:    string;
+  readonly declared:     readonly string[];
+  readonly hostRuntime:  string;
+
+  constructor(specifier: string, declared: readonly string[], hostRuntime: string) {
+    super(`Cannot load plugin "${specifier}": declares matbotRuntime [${declared.join(', ')}], host runtime is "${hostRuntime}".`);
+    this.name        = 'IncompatibleRuntimeError';
+    this.specifier   = specifier;
+    this.declared    = declared;
+    this.hostRuntime = hostRuntime;
+  }
+}
+
+/**
+ * Thrown by the loader when an explicit, single, user-initiated load targets a module that imports
+ * cleanly but is not plugin-shaped — no `plugin` export, a `plugin` without `apiVersion`, or a
+ * non-function lifecycle member. Like {@link IncompatibleRuntimeError} this is *permanent* for the
+ * specifier (the code is a library, not a plugin), so the `add` flow catches it specifically and
+ * rolls the specifier back out of matbot.yaml — distinct from a transient setup() failure (a missing
+ * secret), which is left in config to fix. `reason` is the precise shape defect for logs; callers
+ * surfacing this to an LLM should prefer a terminal "not a plugin" message over echoing `reason`,
+ * which is phrased as a code-fix instruction the model may try to act on.
+ */
+export class NotAPluginError extends Error {
+  readonly specifier: string;
+  readonly reason:    string;
+
+  constructor(specifier: string, reason: string) {
+    super(reason);
+    this.name      = 'NotAPluginError';
+    this.specifier = specifier;
+    this.reason    = reason;
+  }
+}
+
+/**
+ * Thrown by a `PromptFn` implementation when the user cancels — the "give up" path, not a graceful
+ * decline. Callers awaiting `ctx.prompt()` need not branch on it: the surrounding try/catch turns
+ * it into a tool error that closes the tool call, while the host separately abandons the turn.
+ */
+export class PromptCancelledError extends Error {
+  constructor(message = 'User cancelled — cannot proceed.') {
+    super(message);
+    this.name = 'PromptCancelledError';
+  }
+}

package/src/hooks.ts

@@ -0,0 +1,185 @@
+import type {
+  Hook, HookPoint, Message, MessageContent, Session,
+  ScreenContext, ContributeContext, ToolCallContext, ToolCallResult, ToolResultContext, FollowupContext,
+} from './types.js';
+
+const HOOK_ERROR_CREATOR = 'matbot-hooks';
+
+export class HookRegistry {
+  private readonly hooks = new Map<HookPoint, Hook[]>();
+
+  // A hook handler that *throws* is a failure, not an intentional stop (which is a return value:
+  // `abort` / `rejectTool`). A throw must never propagate out of a run* method — that is what bricked
+  // the turn loop: one misconfigured screen hook (e.g. a provider with an unresolved secret) threw at
+  // the top of every turn, so the model never ran and the user couldn't even invoke a tool to fix it.
+  // So every handler call goes through `invoke`, which catches, logs, and treats the throw as "the
+  // hook returned nothing" (skipped). The failure is recorded once per hook (`markedFailures`) and
+  // drained into a marker by the next `runScreen`, so it degrades *visibly* rather than silently.
+  private readonly markedFailures = new Set<Hook>();
+  private pendingFailureMarkers: { channel: HookPoint; pluginName?: string; message: string }[] = [];
+
+  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);
+  }
+
+  removeByPlugin(pluginName: string): void {
+    for (const [point, list] of this.hooks) {
+      this.hooks.set(point, list.filter(h => h.pluginName !== pluginName));
+    }
+  }
+
+  // Backing for the per-call `ctx.removeHook()`: drop one hook by identity. Filtering into a fresh
+  // array (rather than splicing) leaves any in-flight run loop — which iterates the array reference
+  // it captured before the mutation — to finish over the old list; the next run sees the new one.
+  // Idempotent: removing an already-absent hook is a no-op, so calling removeHook() twice is safe.
+  private removeOne(point: HookPoint, hook: Hook): void {
+    const list = this.hooks.get(point);
+    if (list) this.hooks.set(point, list.filter(h => h !== hook));
+  }
+
+  // Run one handler, isolating a throw: log it, record it for a one-time marker, and return undefined
+  // — which every run* method already treats as "no contribution from this hook".
+  private async invoke<R>(hook: Hook, run: () => R | Promise<R>): Promise<R | undefined> {
+    try {
+      return await run();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const owner = hook.pluginName !== undefined ? ` from "${hook.pluginName}"` : '';
+      console.error(`[matbot] ${hook.on} hook${owner} threw; skipping it for this turn:`, message);
+      if (!this.markedFailures.has(hook)) {
+        this.markedFailures.add(hook);
+        this.pendingFailureMarkers.push({
+          channel: hook.on,
+          ...(hook.pluginName !== undefined ? { pluginName: hook.pluginName } : {}),
+          message,
+        });
+      }
+      return undefined;
+    }
+  }
+
+  // Append a `marker` message for each not-yet-marked hook failure (from any channel) to the session,
+  // then clear the queue. Called from runScreen — the once-per-turn, session-owning channel whose
+  // returned session the runner persists — so failures surface durably and exactly once. Returns the
+  // appended marker content blocks too, so the runner can carry them live (a session reload is the
+  // 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:   [{
+        type:    'marker',
+        creator: HOOK_ERROR_CREATOR,
+        data:    { channel: f.channel, ...(f.pluginName !== undefined ? { pluginName: f.pluginName } : {}), message: f.message },
+      }],
+    }));
+    this.pendingFailureMarkers = [];
+    return {
+      session: { ...session, messages: [...session.messages, ...messages] },
+      markers: messages.flatMap(m => m.content),
+    };
+  }
+
+  // screen folds across hooks: each sees the session as shaped so far, accumulates ephemeral, and
+  // the first `abort` short-circuits (the partial session is returned so the caller can persist it).
+  async runScreen(ctx: Omit<ScreenContext, 'removeHook'>): Promise<{ session: Session; ephemeral: MessageContent[]; durable: MessageContent[]; markers: MessageContent[]; abort?: string }> {
+    let session = ctx.session;
+    const ephemeral: MessageContent[] = [];
+    // Handler-returned markers: appended to the session here (so they persist) and accumulated so the
+    // runner can also emit them live — keeping a live draw and a reload identical.
+    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,
+      }] };
+    };
+    // 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
+    // persisted twin of `ephemeral`. Accumulated too, so the runner emits it live as a `robo-user`
+    // event (keeping live draw and reload identical). No user message ⇒ nothing to fold onto, so the
+    // blocks are dropped rather than orphaned (a screen hook only runs when a turn is being submitted,
+    // so a user message is present in practice; this is defensive).
+    const durable: MessageContent[] = [];
+    const foldDurable = (blocks: MessageContent[]): void => {
+      const idx = session.messages.findLastIndex(m => m.role === 'user');
+      if (idx < 0) return;
+      durable.push(...blocks);
+      session = { ...session, messages: session.messages.map((m, i) =>
+        i === idx ? { ...m, content: [...m.content, ...blocks] } : m) };
+    };
+    for (const hook of this.hooks.get('screen') ?? []) {
+      if (hook.on !== 'screen') continue;
+      const r = await this.invoke(hook, () => hook.handler({ ...ctx, session, removeHook: () => this.removeOne('screen', hook) }));
+      if (!r) continue;
+      if (r.session)                     session = r.session;
+      if (r.ephemeral)                   ephemeral.push(...r.ephemeral);
+      if (r.durable && r.durable.length) foldDurable(r.durable);
+      if (r.markers && r.markers.length) appendMarkers(r.markers);
+      if (r.abort) {
+        const drained = this.drainFailureMarkers(session);
+        return { session: drained.session, ephemeral, durable, markers: [...handlerMarkers, ...drained.markers], abort: r.abort };
+      }
+    }
+    const drained = this.drainFailureMarkers(session);
+    return { session: drained.session, ephemeral, durable, markers: [...handlerMarkers, ...drained.markers] };
+  }
+
+  // contribute folds the outgoing array through each hook — a pure transform pipeline; the stored
+  // 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;
+      const r = await this.invoke(hook, () => hook.handler({ ...ctx, outgoing, removeHook: () => this.removeOne('contribute', hook) }));
+      if (r) outgoing = r;
+    }
+    return outgoing;
+  }
+
+  // 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;
+      const r = await this.invoke(hook, () => hook.handler({ ...ctx, removeHook: () => this.removeOne('toolcall', hook) }));
+      if (r && (r.rejectTool || r.abort)) return r;
+    }
+    return {};
+  }
+
+  // toolresult folds the tool result through each hook — a transform pipeline (redaction, truncation);
+  // 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;
+      const r = await this.invoke(hook, () => hook.handler({ ...ctx, result, removeHook: () => this.removeOne('toolresult', hook) }));
+      if (r) result = r.result;
+    }
+    return result;
+  }
+
+  // followup runs every hook and collects their resubmissions (each becomes its own head-enqueued
+  // turn), any durable markers (appended to the committed session by the pump), and any
+  // retract-and-rerun requests. A turn can be popped only once, so multiple hooks' retraction
+  // contexts merge into a single redo (in practice only one fires); `retract` is omitted when none did.
+  async runFollowup(ctx: Omit<FollowupContext, 'removeHook'>): Promise<{ resubmits: MessageContent[][]; markers: MessageContent[]; retract?: { context: MessageContent[] } }> {
+    const resubmits: MessageContent[][] = [];
+    const markers:   MessageContent[]   = [];
+    const retract:   MessageContent[]   = [];
+    for (const hook of this.hooks.get('followup') ?? []) {
+      if (hook.on !== 'followup') continue;
+      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) retract.push(...r.retractAndRerun.context);
+      if (r?.markers)         markers.push(...r.markers);
+    }
+    return { resubmits, markers, ...(retract.length > 0 ? { retract: { context: retract } } : {}) };
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export type * from './types.js';
+export { CONFIRM_YES, CONFIRM_NO } from './types.js';
+export * from './store-query.js';
+export * from './vault.js';
+export * from './errors.js';
+export * from './principal-context.js';
+export * from './context-switch.js';
+export * from './hooks.js';
+export * from './plugin.js';
+export * from './broadcast.js';