@matatbread/matbot-plugin-api 0.3.7 → 0.3.8

package/package.json

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

package/src/index.ts

@@ -10,4 +10,5 @@ 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';

package/src/notify.ts

@@ -0,0 +1,239 @@
+import type { Principal, Store } from './types.js';
+import { createBroadcaster } from './broadcast.js';
+import { tryCurrentPrincipal } from './principal-context.js';
+
+/**
+ * What every notification carries, whoever produced it and however it arrived.
+ *
+ * Two independent axes ride here, and conflating them is the mistake this shape exists to prevent:
+ *
+ *   - **attribution** — `instance`/`plugin`/`source`: who *produced* the fact. Drives per-producer
+ *     filtering, and lets a bridge suppress its own echo.
+ *   - **ownership** — `principal`: whose *data* the fact is about. This is the visibility axis, the
+ *     input to `WatchVisibility.visible`. A notification with no principal is a global fact.
+ *
+ * A producer never sets `instance`: undefined means "this matbot". A bridge stamps it on ingress, so a
+ * forwarded event stays attributable to the server that produced it and never loops back out.
+ *
+ * `kind` is deliberately absent here: it is not something an arm declares but something its
+ * {@link Notifications} key *is*, grafted on by {@link Notification}. Declaring it on the arm as well
+ * would be the same string written twice with nothing keeping the two honest.
+ */
+export interface NotificationBase {
+  /** Producing plugin's name; `core` is reserved for the host and core itself. Defaulted from the
+   *  emitting plugin's scope, so an ordinary producer never sets it. It stays overridable rather than
+   *  enforced because relaying another producer's event is a legitimate act — that is exactly what a
+   *  bridge does with a notification it received from another instance. */
+  readonly plugin:     string;
+  /** Producer-defined sub-channel within that plugin (`tools`, `save`, `job-output`, …). Opaque to core. */
+  readonly source:     string;
+  /** Originating matbot instance. Undefined ⇒ produced locally. Set only by a bridge, on ingress. */
+  readonly instance?:  string;
+  /** Whose data this is about — the visibility axis, NOT attribution. Undefined ⇒ a global fact. */
+  readonly principal?: Principal;
+}
+
+/**
+ * The thing addressed by `(namespace, id)` is no longer what you last read — re-read it.
+ *
+ * Deliberately named for that contract and not for a medium: this is published by `Store` writes
+ * (via {@link notifyingStore}), by `FileStore` writes, and by a share/unshare that passes through
+ * neither. **Use it whenever the change is an invalidation of an addressable item**, wherever the item
+ * lives — including a plugin watching something matbot doesn't own. Define a `kind` of your own only
+ * when you carry information a consumer *cannot* get by re-reading (progress, a measurement, an
+ * external event); squeezing that in here as `detail` is the mistake this note exists to prevent.
+ *
+ * Carries identity, never the value: an event is queued per subscriber and is stale the moment a
+ * concurrent writer lands, so a consumer that acts on a payload races the source it is mirroring.
+ *
+ * `namespace` is the ROUTING namespace (`files`, `skills`, `sessions`, a document namespace) — the axis
+ * a profile isolates and `visible` routes on — not a content sub-namespace. `detail` is advisory only:
+ * a cheap payload for an in-place UI update (a file's size) that a consumer may render but must never
+ * treat as authoritative.
+ */
+export interface ItemChange extends NotificationBase {
+  readonly namespace: string;
+  readonly id:        string;
+  readonly operation: 'saved' | 'deleted';
+  readonly detail?:   unknown;
+}
+
+/** A process-global registry gained or lost a member (tools, plugins). No owner, no item identity. */
+export interface RegistryChange extends NotificationBase {
+  readonly registry:  string;
+  readonly name:      string;
+  readonly operation: 'added' | 'removed';
+}
+
+/**
+ * The wire tags for the two kinds defined here. A `kind` is a globally-scoped token — unlike a type
+ * name, which an importer can rename out of a clash — so these exist to give one back: import the const
+ * under whatever local name suits (`import { ItemChangeKind as Changed }`) and use it as a `case` label
+ * or in a filter. `satisfies` ties each to a real key, so a typo fails the build here instead of
+ * becoming a predicate that silently never matches.
+ */
+export const ItemChangeKind     = '@matatbread/matbot-plugin-api#ItemChange'     satisfies keyof Notifications;
+export const RegistryChangeKind = '@matatbread/matbot-plugin-api#RegistryChange' satisfies keyof Notifications;
+
+/**
+ * The registry of notification shapes, keyed by `kind` — augment it exactly like `MatbotServices` /
+ * `MarkerData` / `ToolContracts` to add your own:
+ *
+ *   export interface JobProgress extends NotificationBase { done: number; total: number }
+ *
+ *   declare module '@matatbread/matbot-plugin-api' {
+ *     interface Notifications { '@fnarr/jobs#JobProgress': JobProgress }
+ *   }
+ *
+ * **The key is `<package-name>#<InterfaceName>` — no translation, no invention.** As with the service
+ * registry, the string is the erasure-time stand-in for a type identity; unlike a type name, it is
+ * globally scoped and an importer cannot rename it out of a collision, so the package name (already
+ * unique, npm guarantees it) qualifies it. The prefix names the package that *defines* the shape, never
+ * the one emitting it — `plugin` is the emitter, and four different plugins emit `ItemChange`. The rule
+ * is enforced by {@link Qualified} at the `notify` call; export the key as a const beside the interface
+ * (see {@link ItemChangeKind}) so consumers get a renameable handle back.
+ *
+ * **The set is open at runtime.** A kind can arrive from a plugin that isn't in this build, or bridged
+ * from another server — so a `switch (n.kind)` over notifications must always have a `default`, and
+ * 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.
+ */
+export interface Notifications {
+  '@matatbread/matbot-plugin-api#ItemChange':    ItemChange;
+  '@matatbread/matbot-plugin-api#RegistryChange': RegistryChange;
+}
+
+/** A notification as a consumer sees it: the arm, plus the `kind` its registry key supplies. Grafting
+ *  `kind` on here rather than declaring it per-arm is what makes "the tag equals the key" unrepresentable
+ *  rather than a convention to police. */
+export type Notification = {
+  [K in keyof Notifications]: Notifications[K] & { readonly kind: K };
+}[keyof Notifications];
+
+/** One arm as a standalone type, for the rare annotation that wants a single kind rather than the union. */
+export type Notified<K extends keyof Notifications> = Notifications[K] & { readonly kind: K };
+
+/** Fails an arm whose key isn't `<package>#<Name>`. Intersected into {@link NotifyInput}, so a malformed
+ *  key surfaces at the `notify` call — in the compilation that declared the augmentation, since the
+ *  mapped type is resolved at the use site. Nothing at runtime; see `createNotifier` for the producers
+ *  TypeScript can't see. */
+type Qualified<K> = K extends `${string}#${string}` ? unknown
+  : { 'ERROR — notification kind must be `<package-name>#<InterfaceName>`': K };
+
+/** What a producer passes to {@link Notifier.notify}: any registered arm, plus its key as `kind`, minus
+ *  the `plugin` the runtime stamps. Mapped over the registry (not `Omit<Notification, …>`) so it
+ *  distributes across arms and picks up augmentations. `plugin` stays settable for the one caller that
+ *  legitimately relays another's event — a bridge replaying a remote notification. */
+export type NotifyInput = {
+  [K in keyof Notifications]: Qualified<K> & Omit<Notifications[K], 'plugin'> & { readonly kind: K; plugin?: string };
+}[keyof Notifications];
+
+/** Per-subscriber predicate. Applied at emit time, so a subscriber never queues what it didn't ask for. */
+export type NotificationFilter = (notification: Notification) => boolean;
+
+/**
+ * The notification bus: one fan-out for every "something changed" fact a frontend, cache, or bridge
+ * needs, replacing the per-kind bespoke streams each producer used to hand out.
+ *
+ * A swappable {@link MatbotServices} member, not fixed runtime plumbing. The host boots an in-process
+ * broadcaster; `register('Notifier', …)` swaps in a distributed one (Redis, NATS, a matbot-to-matbot
+ * bridge) behind the usual capture-safe proxy, and unloading that plugin reverts to the host's default.
+ * Matbot owns the envelope and the registration surface; it does not own delivery.
+ *
+ * **What matbot guarantees, and an alternative implementation must preserve:**
+ *   - `notify` never throws and never blocks — enqueue and return; a slow subscriber blocks nobody.
+ *   - Ordered per producer to each subscriber. No ordering across producers.
+ *   - Local delivery is at-most-once, in-memory. **No persistence, no replay, no delivery guarantee.**
+ *     A sink attaching mid-flight has missed whatever preceded it — so a sink re-queries on attach and
+ *     treats notifications purely as invalidation. Never put current state in the bus.
+ *   - Filters are applied before queueing.
+ *   - An implementation that forwards off-box MUST stamp `instance` on ingress and MUST NOT forward a
+ *     notification that already carries a foreign `instance` — that is the loop break.
+ */
+export interface Notifier {
+  /** Publish. `plugin` is stamped from the calling plugin's scope unless explicitly relayed. */
+  notify(notification: NotifyInput): void;
+  subscribe(signal?: AbortSignal, filter?: NotificationFilter): AsyncIterable<Notification>;
+  /** Detached observation loop: awaits each handler before pulling the next, isolates a throwing
+   *  handler, ends when `signal` aborts. The fire-and-forget form of the for-await every sink writes. */
+  consume(handler: (notification: Notification) => void | Promise<void>, signal?: AbortSignal, filter?: NotificationFilter): void;
+}
+
+/**
+ * The host's boot default: in-process fan-out over the shared broadcaster, one queue per subscriber.
+ * `defaultPlugin` is stamped on anything published without one — the host passes `core`, and the
+ * per-plugin scope built in setupPlugin passes the plugin's own name.
+ */
+export function createNotifier(defaultPlugin: string): Notifier {
+  const events = createBroadcaster<Notification>();
+  return {
+    notify(notification) {
+      const plugin = notification.plugin ?? defaultPlugin;
+      // The type-level rule is erased by the time this runs, and TypeScript never saw the producers that
+      // 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>`);
+      }
+      events.emit({ ...notification, plugin } as Notification);
+    },
+    async *subscribe(signal?: AbortSignal, filter?: NotificationFilter) {
+      for await (const event of events.subscribe(signal, filter ? e => filter(e.value) : undefined)) yield event.value;
+    },
+    consume(handler, signal?, filter?) {
+      events.consume(e => handler(e.value), signal, filter ? e => filter(e.value) : undefined);
+    },
+  };
+}
+
+/** Re-scope a notifier so everything published through it is attributed to `plugin`. */
+export function scopedNotifier(notifier: Notifier, plugin: string): Notifier {
+  return {
+    notify(notification) { notifier.notify({ ...notification, plugin: notification.plugin ?? plugin } as NotifyInput); },
+    subscribe: (signal, filter) => notifier.subscribe(signal, filter),
+    consume:   (handler, signal, filter) => notifier.consume(handler, signal, filter),
+  };
+}
+
+/**
+ * Wrap a store so every successful write announces itself. For a namespace with ONE writer, an explicit
+ * `notify` at that writer is clearer; use this where a namespace has many — `sessions` is written by the
+ * turn pump (title derivation, persist-at-turn-start, the assistant commit), the `session_action` tool
+ * (rename/hide/unhide), `session_edit` (fork/split), and the frontend (a session minted over HTTP). One
+ * wrapper covers them all and cannot be forgotten by the next writer to arrive.
+ *
+ * It sits ABOVE the backend, so it is storage-independent (no backend implements anything) and profile-
+ * independent (the principal is read ambiently at write time, which is also what makes it the correct
+ * partition for visibility filtering). It observes writes made THROUGH it — a second process, or a
+ * writer that bypassed this store, is not seen; that is what a backend's own watch, where one exists,
+ * is for.
+ */
+export function notifyingStore<T extends { id: string; version: string }>(
+  store: Store<T>, notifier: Notifier, namespace: string, source: string,
+): Store<T> {
+  const announce = (operation: 'saved' | 'deleted', id: string): void => {
+    const principal = tryCurrentPrincipal();
+    notifier.notify({
+      kind: ItemChangeKind, source, operation, namespace, id,
+      ...(principal !== undefined ? { principal } : {}),
+    });
+  };
+  return {
+    get:   id => store.get(id),
+    query: q  => store.query(q),
+    async set(id, value)          { await store.set(id, value); announce('saved', id); },
+    async cas(id, expected, next) {
+      const res = await store.cas(id, expected, next);
+      if (res.ok) announce('saved', id);
+      return res;
+    },
+    async delete(id, expectedVersion) {
+      const deleted = await store.delete(id, expectedVersion);
+      if (deleted) announce('deleted', id);
+      return deleted;
+    },
+  };
+}

package/src/plugin.ts

@@ -1,10 +1,11 @@
 import type {
-  FileStore, StoreChange, Principal, Vault, Message, ModelParameters,
+  FileStore, Principal, Vault, Message, ModelParameters,
   ProviderAdapter, ProviderConfig, ProviderRegistry, Tool, ToolRegistry, FrontendInfo,
   Store, Session, SystemContextRegistry, KnowledgeIndex, PromptFn, SessionRunner, Usage,
   TypeScriptStripper, ToolTypeIndex, ToolPresenter, SteeringPolicy,
 } from './types.js';
 import type { Routed } from './broadcast.js';
+import type { Notifier } from './notify.js';
 import type { HookRegistry } from './hooks.js';
 
 export const PLUGIN_API_VERSION = '0.1';
@@ -114,6 +115,12 @@ export interface MatbotServices {
    *  reference held across a swap keeps resolving to the live backend. Always present (boot default). */
   readonly Vault: Vault;
   readonly KnowledgeIndex: KnowledgeIndex;
+  /** The notification bus — every "something changed" fact, one fan-out. Also the `register('Notifier',
+   *  impl)` swap key: the host boots an in-process broadcaster, a plugin may swap in a distributed one
+   *  (and unloading it reverts to the boot default). Capture-safe behind a proxy. Always present.
+   *  Within a plugin's `setup()` this is scoped, so published notifications carry that plugin's name.
+   *  See {@link Notifier}. */
+  readonly Notifier: Notifier;
   /** Optional tool-presentation policy: chooses which tools are advertised to the model per provider
    *  call (a large-library search/deferral plugin registers one). Absent ⇒ the runner advertises the
    *  whole turn snapshot. A plain registered service (not a swap-member); consumed as a member. See
@@ -504,18 +511,13 @@ export interface StorageBackend {
 }
 
 /**
- * The partition-aware file-watch layer, registered by a storage backend that partitions files per
- * principal (the profiles backend). Consumed by a frontend firehose so it can (a) observe file events
- * across *every* partition, each stamped with the {@link Routed} origin that produced it, and (b) decide,
- * per SSE connection, whether a given event is visible to that connection's principal. Absent ⇒ no
- * partitioning: the frontend falls back to the plain single-stream `fileStore.watch()` with no filter.
- * The origin/visibility split is generic (files today; the same shape serves skills/stores later).
+ * The per-connection visibility layer, registered by a storage backend that partitions per principal (the
+ * profiles backend). Consumed by a frontend firehose to decide, per SSE connection, whether a given
+ * notification is visible to that connection's principal. Absent ⇒ no partitioning, and every connection
+ * sees everything. Generic across kinds: it answers on (`namespace`, `id`, `origin`), so files, skills and
+ * stores all route through the one predicate.
  */
 export interface WatchVisibility {
-  /** Every partition's file events, merged into one stream, each a self-describing {@link StoreChange}
-   *  (routing namespace `'files'`, the file id, and the {@link FileMetaData} in `detail`) tagged with the
-   *  origin partition — so the firehose filters and routes files through the same predicate as any stream. */
-  watchFiles(signal?: AbortSignal): AsyncIterable<Routed<StoreChange>>;
   /**
    * The per-connection visibility predicate for ANY partitioned event stream (files, skills, …): would a
    * connection owned by `viewer` see the change to (`namespace`, `id`) produced by `origin`? True iff the

package/src/store-query.ts

@@ -39,6 +39,18 @@ export interface StoreQuery {
   sort?:   SortSpec[];
   limit?:  number;
   cursor?: string | undefined;
+  /**
+   * The caller's promise not to mutate the returned documents, freeing a backend to hand back shared
+   * instances instead of freshly-materialised ones. A pure optimisation hint: a backend may ignore it
+   * and nothing changes, so it is never load-bearing for correctness — but a backend that honours it
+   * can skip re-materialising documents that have not changed since the last query, which for a
+   * summary listing (read every document, use four fields) is the entire cost of the call.
+   *
+   * Set it only where the promise is actually kept. A read-modify-write path — pull a page, edit a
+   * document, `cas` it back — must NOT set it: the instance it edits may be one another caller is
+   * still reading, and a backend caching it would then be caching an edit that never reached disk.
+   */
+  immutable?: boolean;
 }
 
 export interface QueryResult<T> {

package/src/types.ts

@@ -730,6 +730,25 @@ export interface ToolContext {
   unloadPlugin(specifier: string): Promise<boolean>;
 }
 
+/**
+ * The read-only facts about the call a composed function is running under, injected into a
+ * `tool_function` body as the ambient `context` binding beside `tool`/`toolInContext`. Deliberately
+ * narrower than {@link ToolContext}: the identity of the call, not its capabilities — `vault`,
+ * `files`, `prompt` and plugin (un)loading stay off a surface authored by a model and reachable only
+ * through the tool contracts. A tool with real source takes `ToolContext` and needs none of this.
+ *
+ * Not `ToolCallContext` — that name belongs to the `toolcall` hook's context; this is the composed
+ * caller's own view, not a hook's view of a call about to run.
+ */
+export interface ComposedCallContext {
+  readonly callId:    string;
+  readonly sessionId: string;
+  /** The provider key driving the turn — the same one nested `tool.x(…)` calls inherit. */
+  readonly provider?: string;
+  readonly workdir?:  string;
+  readonly signal:    AbortSignal;
+}
+
 /**
  * A tool's runtime. `R` is the type of the `value` carried by its `result` event — declared once,
  * at the source, so the executor's yields and the tool's {@link ToolContracts} registry entry can't
@@ -780,28 +799,6 @@ export interface FileHandle extends FileMetaData {
   stream(signal?: AbortSignal): AsyncIterable<Uint8Array>;
 }
 
-export type FileEvent = FileMetaData & { changed: Array<keyof FileMetaData> };
-
-/**
- * The generic, self-describing change envelope every partitioned CRUD stream emits (files, skills, and
- * future partitioned stores) — the payload half of a {@link Routed} event, whose `origin` carries the
- * acting principal/partition. It supersedes the per-stream bespoke shapes (the old `SkillEvent`, the raw
- * `FileEvent` on the wire) so a frontend firehose can filter and route every stream through ONE predicate.
- *
- * `namespace` is the ROUTING namespace the change lives under — `'files'`, `'skills'`, or a document
- * namespace — NOT a content sub-namespace (a file's own `metadata.namespace`, e.g. `'workspace'`, rides in
- * `detail`). Pairing `namespace` + `id` is exactly what `WatchVisibility.visible` needs to decide, per
- * connection, whether the viewer routes that item to the same partition (or has it shared in). `detail`
- * carries an optional rich payload for in-place UI updates — a file change ships its {@link FileMetaData}
- * so a sidebar row can update its size without a re-fetch; a skill change needs none (a refresh ping).
- */
-export interface StoreChange {
-  readonly operation: 'saved' | 'deleted';
-  readonly namespace: string;
-  readonly id:        string;
-  readonly detail?:   unknown;
-}
-
 export interface FileFilter {
   sessionId?:     string;
   mimeType?:      string;
@@ -823,8 +820,6 @@ export interface FileStore {
   delete(id: string): Promise<void>;
   list(filter?: FileFilter): AsyncIterable<FileHandle>;
   putTemp(name: string, mimeType: MimeType, data: AsyncIterable<Uint8Array>): Promise<FileHandle>;
-  /** Observe file changes. Implementations that cannot watch their backing store omit this. */
-  watch(signal?: AbortSignal): AsyncIterable<FileEvent>;
 }
 
 // ── Frontend ──────────────────────────────────────────────────────────────────
@@ -886,19 +881,16 @@ export type HealthStatus =
 
 // ── Registries ────────────────────────────────────────────────────────────────
 
-export type ToolRegistryEvent =
-  | { type: 'registered'; name: string; pluginName?: string }
-  | { type: 'removed';    name: string };
-
+/** Tool CRUD is observed on the {@link Notifier}, as a `RegistryChange` with `registry: 'tools'` — this
+ *  registry had its own broadcaster over the same primitive, which is duplication, not layering. One
+ *  notification per tool (removeByPlugin announces a `removed` per matched tool); the registering
+ *  plugin's name rides in `detail`, advisory as ever — resolve the name for anything authoritative. */
 export interface ToolRegistry {
   register(tool: Tool): void;
   remove(name: string): void;
   resolve(name: string): Tool | null;
   list(): readonly Tool[];
   removeByPlugin(pluginName: string): void;
-  /** Observe tool CRUD as it happens. Read-only — observers cannot veto a registration. One event
-   *  per tool (removeByPlugin emits a `removed` per matched tool). The stream ends when `signal` aborts. */
-  watch(signal?: AbortSignal): AsyncIterable<ToolRegistryEvent>;
 }
 
 /** What the runner tells a {@link ToolPresenter} about the call it's about to make. */
@@ -948,10 +940,6 @@ export interface ProviderRegistry extends ReadonlyMap<string, ProviderConfig> {
   revert(name: string): void;
 }
 
-export type PluginRegistryEvent =
-  | { type: 'loaded';   name: string }
-  | { type: 'unloaded'; name: string };
-
 // ── Pipeline events ─────────────────────────────────────────────────────────────
 
 /**