@matatbread/matbot-plugin-api 0.3.8 → 0.4.1

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.3.8",
+  "version": "0.4.1",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -22,7 +22,8 @@
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./host": "./src/host.ts"
   },
   "repository": {
     "type": "git",

package/src/hooks.ts

@@ -1,11 +1,12 @@
 import type {
-  Hook, HookPoint, Message, MessageContent, Session, DeferredScreen,
+  Hook, HookPoint, HookRegistrar, Message, MessageContent, Session, DeferredScreen,
   ScreenContext, ContributeContext, ToolCallContext, ToolCallResult, ToolResultContext, FollowupContext,
 } from './types.js';
+import { foldOntoUserTurn } from './session.js';
 
 const HOOK_ERROR_CREATOR = 'matbot-hooks';
 
-export class HookRegistry {
+export class HookRegistry implements HookRegistrar {
   private readonly hooks = new Map<HookPoint, Hook[]>();
 
   // A hook handler that *throws* is a failure, not an intentional stop (which is a return value:
@@ -111,11 +112,10 @@ export class HookRegistry {
     // 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;
+      const folded = foldOntoUserTurn(session, blocks);
+      if (folded === session) return;      // no user message to attach to — dropped, not orphaned
       durable.push(...blocks);
-      session = { ...session, messages: session.messages.map((m, i) =>
-        i === idx ? { ...m, content: [...m.content, ...blocks] } : m) };
+      session = folded;
     };
     for (const hook of this.hooks.get('screen') ?? []) {
       if (hook.on !== 'screen') continue;

package/src/host-machine.ts

@@ -0,0 +1,192 @@
+import type {
+  CompletionRequest, MatbotMachine, MatbotServices, Mounted, MountConsumeOptions, SingleTurnRequest,
+} from './plugin.js';
+
+/*
+ * Host-side machine assembly — the wiring an *embedder* does once at boot, not API a plugin author
+ * writes against. It lives behind `@matatbread/matbot-plugin-api/host` so the package root can answer
+ * exactly one question: what does a plugin need in order to be a plugin? Publishing these at the root
+ * made boot mechanics look like stable author-facing surface, and no plugin in this repo imports one.
+ *
+ * Split out of plugin.ts as a *file* boundary rather than an export list, so the distinction cannot
+ * quietly erode the next time something is added. The plugin-facing halves of the same subsystems stay
+ * where they are: `Mounted`/`MountConsumeOptions` (the contract of `services.mounted`) in plugin.ts,
+ * `runAs`/`currentPrincipal` in principal-context.ts.
+ */
+
+/**
+ * Wrap a services object so every registered service is reachable as a member (`services.InterfaceName`),
+ * not only via `services.get('InterfaceName')` — one access surface for base members and plugin-registered
+ * services alike. A member read of a key the object doesn't carry falls back to its own `get()` (the
+ * registry), so the augmentation that declares `InterfaceName?: InterfaceName` is also the access path;
+ * the optional `?` is the single call-site signal of "may be absent, null-check it". Assignment throws,
+ * directing callers to `register()` (the swap-aware write path). Applied to both the host services object
+ * and the per-plugin scoped object, so plugins see the same surface the host does.
+ *
+ * Only `get` and `set` are trapped. `has` used to fall through to the registry too, which made the plain
+ * language construct `'Foo' in services` perform a registry lookup — no side effect, but a surprise, and
+ * inconsistent with `ownKeys`, which never listed registered services. `in` is therefore structural, and
+ * the presence check remains the documented one: `services.Foo !== undefined`, or `?.`.
+ */
+export function unifyServices(services: MatbotMachine): MatbotMachine {
+  return new Proxy(services, {
+    get(target, key, receiver) {
+      if (Reflect.has(target, key)) return Reflect.get(target, key, receiver);
+      return typeof key === 'string' ? target.get(key as keyof MatbotServices) : undefined;
+    },
+    set(_target, key) {
+      throw new Error(
+        `Cannot assign services.${String(key)} directly — use services.register('${String(key)}', impl) to register or replace a service.`,
+      );
+    },
+  });
+}
+// ── Capture-safe swap proxies ───────────────────────────────────────────────────
+
+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.
+ */
+export function forwardingProxy<T extends object>(getCurrent: () => T | undefined): T {
+  return new Proxy({} as T, {
+    get(_t, prop) {
+      const cur = getCurrent();
+      if (cur === undefined) return undefined;
+      const val = Reflect.get(cur, prop, cur);
+      return typeof val === 'function' ? (val as (...a: unknown[]) => unknown).bind(cur) : val;
+    },
+    has(_t, prop)    { const cur = getCurrent(); return cur !== undefined && Reflect.has(cur, prop); },
+    getPrototypeOf() { const cur = getCurrent(); return cur === undefined ? null : Reflect.getPrototypeOf(cur); },
+    ownKeys()        { const cur = getCurrent(); return cur === undefined ? [] : Reflect.ownKeys(cur); },
+    getOwnPropertyDescriptor(_t, prop) {
+      const cur = getCurrent();
+      if (cur === undefined) return undefined;
+      const d = Reflect.getOwnPropertyDescriptor(cur, prop);
+      if (d !== undefined) d.configurable = true; // Proxy invariant: props absent from the {} target must be configurable.
+      return d;
+    },
+  });
+}
+
+/**
+ * Returns [proxy, swap]: the Store/FileStore handle plugins capture, plus the fn register() calls to
+ * repoint it at a new backend's store. Built on forwardingProxy so capture-safety is uniform.
+ */
+export function makeSwappable<T extends object>(initial: T): [T, SwapFn<T>] {
+  let current = initial;
+  return [forwardingProxy<T>(() => current), (next: T) => { current = next; }];
+}
+
+// ── Mount table (host half) ──────────────────────────────────
+
+/** The host-side mount table: {@link Mounted} for plugins, plus the producer half the host drives from
+ *  its register/unregister and quiescent-edge flush. */
+export interface MountTable {
+  readonly mounted: Mounted;
+  /** Record that a key's presence may have changed since the last edge (called by register/unregister). */
+  markDirty(key: keyof MatbotServices): void;
+  /** At a quiescent edge, compute each dirty key's net presence transition and multicast it. */
+  flush(): void;
+}
+
+interface MountInterest {
+  readonly handler:   (machine: MatbotMachine) => void | Promise<void>;
+  readonly onUnmount: ((machine: MatbotMachine) => void | Promise<void>) | undefined;
+  readonly signal:    AbortSignal | undefined;
+}
+
+function reportMountHandlerError(e: unknown): void {
+  console.error('[matbot] mounted handler threw:', e instanceof Error ? e.message : e);
+}
+
+/**
+ * Build a {@link MountTable} over a lazily-read machine. Notifications batch to the quiescent edge
+ * ({@link flush}), where each dirty key's net presence (absent→present = mount, present→present =
+ * remount, present→absent = committed unload) is multicast to that key's subscribers. The clock holds
+ * the last-committed presence per key, so a reload collapses to one remount and a committed unload is
+ * well-defined. Presence is read by member access on the unified machine, which resolves both the core
+ * getters (StorageBackend/Vault/KnowledgeIndex) and the registry-backed augmented keys.
+ */
+export function createMountTable(getMachine: () => MatbotMachine): MountTable {
+  const interests = new Map<string, Set<MountInterest>>();
+  const committed = new Map<string, boolean>();   // last-committed presence per key (the clock)
+  const dirty     = new Set<string>();
+
+  const present = (key: string): boolean => (getMachine() as unknown as Record<string, unknown>)[key] !== undefined;
+
+  const run = (fn: (machine: MatbotMachine) => void | Promise<void>, machine: MatbotMachine): void => {
+    try {
+      const r = fn(machine);
+      if (r instanceof Promise) r.catch(reportMountHandlerError);
+    } catch (e) { reportMountHandlerError(e); }
+  };
+
+  const mounted: Mounted = {
+    observe(options, handler) {
+      const { key, replay, signal, onUnmount } = options;
+      if (signal?.aborted === true) return;
+      const interest: MountInterest = {
+        handler:   handler as MountInterest['handler'],
+        onUnmount: onUnmount as MountInterest['onUnmount'],
+        signal,
+      };
+      let set = interests.get(key);
+      if (set === undefined) { set = new Set(); interests.set(key, set); }
+      const subs = set;
+      subs.add(interest);
+      signal?.addEventListener('abort', () => { subs.delete(interest); }, { once: true });
+      // Replay on the next microtask (async-iterator parity — never inline in the consume() frame).
+      // Reads the live machine, not `committed`: replay is "current state", separate from the clock.
+      if (replay === true) queueMicrotask(() => {
+        if (signal?.aborted === true) return;
+        if (present(key as string)) run(interest.handler, getMachine());
+      });
+    },
+  };
+
+  return {
+    mounted,
+    markDirty(key) { dirty.add(key as string); },
+    flush() {
+      if (dirty.size === 0) return;
+      const keys = [...dirty];
+      dirty.clear();
+      const machine = getMachine();
+      for (const key of keys) {
+        const before = committed.get(key) ?? false;
+        const after  = present(key);
+        committed.set(key, after);
+        const subs = interests.get(key);
+        if (subs === undefined) continue;
+        if (after) {
+          for (const i of subs) run(i.handler, machine);                                  // mount / remount
+        } else if (before) {
+          for (const i of subs) if (i.onUnmount !== undefined) run(i.onUnmount, machine);  // committed unload
+        }
+      }
+    },
+  };
+}
+
+/**
+ * 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.
+ */
+export function singleTurnRequest(req: SingleTurnRequest): CompletionRequest {
+  return {
+    provider: req.provider,
+    messages: [{
+      id: '', traceId: '', createdAt: new Date().toISOString(), role: 'user',
+      content: [{ type: 'text', text: req.prompt }],
+    }],
+    ...(req.system     !== undefined ? { system: req.system } : {}),
+    ...(req.parameters !== undefined ? { parameters: req.parameters } : {}),
+    ...(req.signal     !== undefined ? { signal: req.signal } : {}),
+  };
+}

package/src/host.ts

@@ -0,0 +1,43 @@
+/*
+ * `@matatbread/matbot-plugin-api/host` — the boot-time wiring an *embedder* performs to stand a machine
+ * up, as opposed to what a *plugin* is written against.
+ *
+ * The package root used to export both, which made carrier installers, swap proxies, the mount table and
+ * the hook registry implementation look like stable author-facing API. They are not: no plugin in this
+ * repo imports one, and only `apps/*` and `core` ever did. Splitting them here lets the root answer one
+ * question — what does a plugin need in order to be a plugin? — and lets these change without it being a
+ * plugin-API break.
+ *
+ * Three of these subsystems are deliberately *split* rather than moved whole, because each has a genuine
+ * author-facing half that stays at the root:
+ *   - principal: `runAs` / `currentPrincipal` / `tryCurrentPrincipal` are read and established by plugins
+ *     (a frontend scopes each inbound message); only *installing the carrier* is the host's job.
+ *   - notifications: every plugin publishes and consumes; only *minting* the process notifier is the host's.
+ *   - mount table: `services.mounted` (`Mounted`, `MountConsumeOptions`) is the plugin contract; the
+ *     producer half (`MountTable`, `markDirty`/`flush`) is driven by the host's register/quiescent edge.
+ *
+ * `core` re-exports everything here, so a host that already depends on `@matatbread/matbot-core` needs no
+ * direct import of this subpath.
+ */
+
+// Machine assembly: member-access unification, capture-safe swap proxies, the mount table's producer
+// half, and the one-shot CompletionRequest builder behind MatbotRuntime.singleTurn.
+export * from './host-machine.js';
+
+// Ambient scope carriers. The host installs a platform impl once at boot (node: AsyncLocalStorage;
+// browser/single-principal: a constant carrier) and never touches them again.
+export { installPrincipalCarrier, enterPrincipal, createConstantPrincipalCarrier } from './principal-context.js';
+export type { PrincipalCarrier } from './principal-context.js';
+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';
+
+// Hook dispatch implementation. Plugins register hooks through `services.hooks`; only the host constructs
+// the registry that backs it.
+export { HookRegistry } from './hooks.js';
+
+// The multi-subscriber fan-out primitive under `Notifier`. A plugin that wants to publish an event uses
+// the Notifier — that is the sanctioned path, and the reason this stays host-side.
+export * from './broadcast.js';
+export { createNotifier, scopedNotifier } from './notify.js';

package/src/index.ts

@@ -1,14 +1,32 @@
+/*
+ * `@matatbread/matbot-plugin-api` — everything a plugin author needs, and nothing a host needs to *build*
+ * a machine. Boot wiring (carrier installers, swap proxies, the mount table's producer half, the hook
+ * registry impl, the broadcaster) lives behind the `/host` subpath; see host.ts for the reasoning.
+ *
+ * Star-exported where a file is wholly plugin-facing; enumerated where a file is deliberately split. The
+ * two enumerated cases use `export type *` for the shapes plus a named list of runtime values, so a new
+ * *type* flows out automatically and a new *value* is a decision someone has to make here.
+ */
+
 export type * from './types.js';
-export { CONFIRM_YES, CONFIRM_NO } from './types.js';
+export { CONFIRM_YES, CONFIRM_NO, isTruncatedToolResult } from './types.js';
+
 export * from './store-query.js';
-export * from './vault.js';
 export * from './errors.js';
-export * from './principal-context.js';
-export * from './usage-context.js';
+export * from './vault.js';
 export * from './session.js';
-export * from './context-switch.js';
-export * from './hooks.js';
-export * from './plugin.js';
-export * from './broadcast.js';
-export * from './notify.js';
 export * from './invoke-tool.js';
+
+// The plugin half of the machine: MatbotPlugin/MatbotServices/MatbotRuntime, the mount-table *consumer*
+// contract, and the API version a plugin declares. Host assembly is in ./host-machine.ts.
+export type * from './plugin.js';
+export { PLUGIN_API_VERSION } from './plugin.js';
+
+// Ambient principal: read it, or establish one for an inbound request/message. Installing the carrier is
+// the host's job (`/host`).
+export { currentPrincipal, tryCurrentPrincipal, runAs } from './principal-context.js';
+
+// Notifications: publish, consume, and the two kinds plugin-api itself defines. Minting the process
+// notifier is the host's job (`/host`).
+export type * from './notify.js';
+export { ItemChangeKind, RegistryChangeKind, notifyingStore } from './notify.js';

package/src/invoke-tool.ts

@@ -1,6 +1,29 @@
-import type { MatbotMachine } from './plugin.js';
+import type { MatbotMachine, MatbotPlugin } from './plugin.js';
 import type { ToolContext, ToolEvent, ToolResultFor, ToolProxy, PromptFn, FormField } from './types.js';
 
+/** The host's plugin hot-load ops, as both the runner and {@link invokeTool} hold them. */
+export interface PluginOps {
+  loadPlugin(specifier: string, prompt?: PromptFn, refresh?: boolean): Promise<MatbotPlugin>;
+  unloadPlugin(specifier: string): Promise<boolean>;
+}
+
+/**
+ * Bind the plugin hot-load ops for a {@link ToolContext}, closing over the turn's `prompt`.
+ *
+ * That closure is the whole point of `ToolContext.loadPlugin` existing alongside
+ * `MatbotRuntime.loadPlugin`: a tool cannot forget to pass the prompt, so an interactive load cannot
+ * silently become non-interactive at one call site out of six — the same reasoning that makes the
+ * principal ambient rather than threaded. What it should not be is written out twice, once in the runner
+ * and once here, since the injected middle argument is exactly the shape a signature change breaks
+ * quietly.
+ */
+export function bindPluginOps(host: PluginOps, prompt: PromptFn): Pick<ToolContext, 'loadPlugin' | 'unloadPlugin'> {
+  return {
+    loadPlugin:   (specifier, refresh) => host.loadPlugin(specifier, prompt, refresh),
+    unloadPlugin: (specifier)          => host.unloadPlugin(specifier),
+  };
+}
+
 /**
  * Inputs to {@link invokeTool} that a one-shot caller can't derive from the machine. A tool
  * forwarding a call to another tool should pass its own {@link ToolContext} straight through as
@@ -41,8 +64,7 @@ export function invokeTool<K extends string, const P>(
     signal:       opts.signal,
     vault:        machine.Vault,
     prompt,
-    loadPlugin:   (specifier, refresh) => machine.loadPlugin(specifier, prompt, refresh),
-    unloadPlugin: (specifier) => machine.unloadPlugin(specifier),
+    ...bindPluginOps(machine, prompt),
     ...(opts.provider      !== undefined ? { provider:   opts.provider      } : {}),
     ...(machine.workdir    !== undefined ? { workdir:    machine.workdir    } : {}),
     ...(machine.configPath !== undefined ? { configPath: machine.configPath } : {}),

package/src/notify.ts

@@ -98,6 +98,9 @@ export const RegistryChangeKind = '@matatbread/matbot-plugin-api#RegistryChange'
  * exhaustiveness checking is unsound here (unlike a closed discriminated union). A bridge that wants a
  * foreign kind typed augments this itself; otherwise it validates at its own boundary, like any other
  * system edge.
+ *
+ * One of matbot's five open-registry augmentation points — same technique at each; see
+ * docs/DEVELOPING.md *Open-registry augmentation* for the shared shape and the rules that follow from it.
  */
 export interface Notifications {
   '@matatbread/matbot-plugin-api#ItemChange':    ItemChange;