@matatbread/matbot-plugin-api 0.3.8 → 0.4.1

package/src/plugin.ts

@@ -1,14 +1,26 @@
 import type {
   FileStore, Principal, Vault, Message, ModelParameters,
   ProviderAdapter, ProviderConfig, ProviderRegistry, Tool, ToolRegistry, FrontendInfo,
-  Store, Session, SystemContextRegistry, KnowledgeIndex, PromptFn, SessionRunner, Usage,
+  Store, Session, SystemContextRegistry, KnowledgeIndex, PromptFn, SessionRunner, Usage, HookRegistrar,
   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';
+/**
+ * The plugin API contract version: this package's `major.minor`, and nothing else. It sat at `'0.1'`
+ * while the package shipped 0.3.x, so it conveyed no information and could not be reasoned about at a
+ * version boundary — the point at which it is the only thing every third-party plugin hardcodes.
+ *
+ * The gate (`checkApiVersion`, in core's registry) reads it as: **major must match exactly** — a
+ * mismatch is a hard load failure — and a plugin declaring a *newer minor* than the runtime warns and
+ * loads, since it may reach for something absent. Declare it as `apiVersion: PLUGIN_API_VERSION` and it
+ * stays right for free; that is what every plugin in this repo does.
+ *
+ * Bumping 0.1 → 0.4 breaks nothing: at 0.x the major is `'0'` either way, and an older declared minor
+ * does not warn. It matters at 1.0.0, where a plugin still declaring `'0.x'` will fail the major check
+ * loudly instead of loading against a contract it was never built for.
+ */
+export const PLUGIN_API_VERSION = '0.4';
 
 // ── Sub-runner types ──────────────────────────────────────────────────────────
 
@@ -17,13 +29,18 @@ export interface CompletionRequest {
   messages:    Message[];
   system?:     string;
   /**
-   * @deprecated Per-call parameter overrides, shallow-merged over the provider config (request wins).
-   * It DOES work — both hosts (CLI + web-bundle) honour it — but it is a speculative affordance whose
-   * obvious use is an anti-pattern: a caller clamping tokens / disabling thinking for one call takes
-   * control away from the provider config, where parameters belong and stay user-editable. Prefer a
-   * dedicated provider profile (e.g. a `-classify` provider) instead of reaching for this. Kept, not
-   * removed, only because the surface is tiny and a genuine per-call need may yet appear. If you found
-   * this because you set it and it worked — reconsider whether a provider profile is the right home.
+   * Per-call parameter overrides, shallow-merged over the named provider's own `parameters` (request
+   * wins). For *transient* model behaviour — a lower `temperature` to classify, `thinking` off for a
+   * cheap sub-call, a tighter `maxTokens` on a call whose output is parsed rather than shown.
+   *
+   * The alternative is a near-duplicate provider profile per behaviour, identical to its sibling but
+   * for one field, which pushes a caller's transient concern into global, user-editable config and
+   * multiplies the profiles a user has to understand. So: **durable properties of a model belong in
+   * the provider profile; a single call's behaviour belongs here.** If the same override appears at
+   * every call site of a provider, that is the signal it was a profile all along.
+   *
+   * Honoured by both hosts (CLI + web-bundle), which resolve the merge before handing the config to
+   * the adapter; an unrecognised key is the adapter's business, exactly as in a profile.
    */
   parameters?: Partial<ModelParameters>;
   signal?:     AbortSignal;
@@ -38,8 +55,7 @@ export interface SingleTurnRequest {
   provider: string;
   prompt:   string;
   system?:  string;
-  /** @deprecated Forwarded verbatim to {@link CompletionRequest.parameters}; same speculative
-   *  anti-pattern caveat — prefer a dedicated provider profile over per-call overrides. */
+  /** Forwarded verbatim to {@link CompletionRequest.parameters} — same merge, same guidance. */
   parameters?: Partial<ModelParameters>;
   signal?:  AbortSignal;
 }
@@ -99,11 +115,15 @@ export interface PluginSelf {
 // ── Services container ────────────────────────────────────────────────────────
 
 /**
+ * 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.
+ *
  * The registry bucket: the swappable, registerable services, keyed by interface name. This is the
  * `keyof` domain of {@link MatbotRuntime.register}/`get`, and the surface third-party plugins augment
  * (`declare module '@matatbread/matbot-plugin-api' { interface MatbotServices { Foo?: Foo } }`). The
- * core three carry a host boot default and revert to it when unregistered; an augmented service is
- * optional and simply drops. Read each as a member (`services.KnowledgeIndex`); swap with register().
+ * four swap-members (`StorageBackend`, `KnowledgeIndex`, `Vault`, `Notifier`) carry a host boot default
+ * and revert to it when unregistered; an augmented service is optional and simply drops. Read each as
+ * a member (`services.KnowledgeIndex`); swap with register().
  */
 export interface MatbotServices {
   readonly StorageBackend?: StorageBackend | undefined;
@@ -255,7 +275,7 @@ export interface MatbotRuntime {
    *  runSession directly, so concurrent submits queue instead of clobbering the session. */
   readonly run?:            SessionRunner | undefined;
   readonly files?:          FileStore;
-  readonly hooks:           HookRegistry;
+  readonly hooks:           HookRegistrar;
   readonly tools:           ToolRegistry;
   readonly systemContext:   SystemContextRegistry;
   /** Default working directory for tool execution. Plugins that create servers should forward this to tool contexts. */
@@ -274,74 +294,6 @@ export interface MatbotRuntime {
   isSubAgent(): boolean;
 }
 
-/**
- * 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.
- */
-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;
-    },
-    has(target, key) {
-      if (Reflect.has(target, key)) return true;
-      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 ─────────────────────────────────────────────────────────────────
 
 /** The machine with one registry key narrowed to present — what a keyed mount handler receives. */
@@ -355,7 +307,10 @@ export interface MountConsumeOptions<K extends keyof MatbotServices> {
    *  (then on each later remount). Off by default — a cacher that did its initial load in setup() wants
    *  only future transitions; a deferred dependency wants the latch. */
   readonly replay?:    boolean;
-  /** Ends the subscription (the consumer's own teardown). */
+  /** Ends the subscription *earlier* than the observing plugin's unload. Optional because it is a
+   *  narrowing convenience, not the cleanup path: the host binds every plugin-scoped observe() to that
+   *  plugin's load extent, so an interest can never outlive its owner. Pass one only when the
+   *  subscription's life is shorter than the plugin's (a per-session cache, a one-shot latch). */
   readonly signal?:    AbortSignal;
   /** The *dependency's* teardown: fired when `key` is committed-unloaded (removed and not replaced by
    *  the quiescent edge) while this consumer lives on. The stream continues — a later remount re-fires
@@ -373,112 +328,7 @@ export interface Mounted {
   ): void;
 }
 
-/** 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 } : {}),
-  };
-}
 
 // ── Factory types ─────────────────────────────────────────────────────────────
 

package/src/session.ts

@@ -1,4 +1,4 @@
-import type { Session } from './types.js';
+import type { MessageContent, Session } from './types.js';
 
 /**
  * A session's `updatedAt` invariant: the timestamp of its last message, or its own `createdAt` when it
@@ -15,3 +15,32 @@ export function lastActivityAt(session: Session): string {
   const last = session.messages[session.messages.length - 1];
   return last ? last.createdAt : session.createdAt;
 }
+
+/**
+ * Index of the turn's user message — the message a durable fold attaches to, and the point a retraction
+ * pops back to. `-1` when the session has none.
+ */
+export function lastUserIndex(session: Session): number {
+  return session.messages.findLastIndex(m => m.role === 'user');
+}
+
+/**
+ * Append `blocks` to the turn's user message, returning a new session. This is what "durable" means
+ * everywhere it appears: unlike `ephemeral` (tail-folded into the outgoing copy and discarded), the blocks
+ * become part of the user turn — persisted, visible to a reader, and carried by every subsequent provider
+ * call in the turn and after it.
+ *
+ * With no user message the blocks are **dropped rather than orphaned**: there is nothing they could belong
+ * to, and appending a message of their own would change the role sequence the adapters depend on.
+ *
+ * Shared because the three callers must agree: the `screen` hook fold, the runner's raced-verdict
+ * correction, and the pump's retract-and-rerun rebase. They were three independent copies of one
+ * `findLastIndex` + splice, in two different packages.
+ */
+export function foldOntoUserTurn(session: Session, blocks: readonly MessageContent[]): Session {
+  if (blocks.length === 0) return session;
+  const idx = lastUserIndex(session);
+  if (idx < 0) return session;
+  return { ...session, messages: session.messages.map((m, i) =>
+    i === idx ? { ...m, content: [...m.content, ...blocks] } : m) };
+}

package/src/types/events.ts

@@ -0,0 +1,81 @@
+import type { FileHandle } from './files.js';
+import type { MessageContent, Session } from './messages.js';
+import type { Usage } from './provider.js';
+
+// ── Pipeline events ─────────────────────────────────────────────────────────────
+
+/**
+ * A turn's own events. `traceId` — the turn that produced it — is the correlation key a frontend routes
+ * on (see `SessionRunner`), and every arm here carries it. Grouped by what a consumer does with them:
+ * streamed model output, tool progress, live delivery of something already persisted, and the terminals.
+ *
+ * A turn ends with **exactly one** terminal: `done`, `aborted` (interrupted mid-flight), or `error`.
+ */
+export type TurnEvent =
+  // ── streamed model output ──
+  | { type: 'text-delta';     delta: string;          traceId: string }
+  | { type: 'thinking';       delta: string;          traceId: string }
+  | { type: 'system-context'; text: string;           traceId: string }
+  | ({ type: 'usage';         traceId: string } & Usage)
+
+  // ── tool execution ──
+  | { type: 'tool:start';     callId: string; name: string; input: unknown; traceId: string }
+  | { type: 'tool:stdout';    callId: string; chunk: string;  traceId: string }
+  | { type: 'tool:stderr';    callId: string; chunk: string;  traceId: string }
+  | { type: 'tool:progress';  callId: string; pct: number; message?: string; traceId: string }
+  | { type: 'tool:end';       callId: string; result: unknown; isError: boolean; traceId: string }
+
+  // ── live delivery of state that is ALREADY persisted; never the source of truth ──
+  | { type: 'file';           handle: FileHandle;     traceId: string }
+  // Machine-authored content folded onto the running turn's user message (a `screen` hook's
+  // `durable` result — e.g. a fired `contextual` trigger), carried live so a frontend draws it
+  // immediately. The blocks are already persisted in that user message (origin: 'robo'); this is
+  // purely the live-delivery channel, so a live draw matches the reload (which splits the user
+  // turn's robo blocks into their own agent-side bubble).
+  | { type: 'robo-user';      content: MessageContent[]; traceId: string }
+  // Marker blocks appended to the session this turn (e.g. the dispatcher's record of a hook that
+  // threw), carried live so a frontend renders them without waiting for a session reload. The blocks
+  // are already persisted in the session; this event is purely the live-delivery channel.
+  | { type: 'marker';         content: MessageContent[]; traceId: string }
+
+  // ── queue disposition ──
+  // A queued (not-yet-running) submission, carried on the stream so a frontend renders it as part
+  // of the live "delta" (everything after the last committed message), never from stored state.
+  // `queued` is the number of submissions ahead of it (0 ⇒ about to run). Emitted live on enqueue
+  // and replayed (in queue order) to anyone subscribing mid-flight.
+  | { type: 'queued';         content: MessageContent[]; queued: number; concatQueue: boolean; traceId: string; rootTraceId: string }
+  // A mid-turn steer that INTERRUPTED the running turn (see `SteeringPolicy`). Emitted synchronously
+  // when the steer is accepted, so the new user bubble lands in correct stream order and a frontend
+  // knows the imminent `aborted` (reason 'steer') on `interruptedTraceId` is a yield, not a dead-end:
+  // keep that turn's partial work rendered and expect a continuation. `traceId`/`rootTraceId` identify
+  // the steer submission itself (the continuation turn). Late subscribers reconstruct the bubble from
+  // the pump's per-turn `queued` replay seed / committed store order — this is purely live delivery.
+  | { type: 'steer';          content: MessageContent[]; interruptedTraceId: string; traceId: string; rootTraceId: string }
+
+  // ── terminals: exactly one per turn ──
+  | { type: 'done';           session: Session;       traceId: string }
+  | { type: 'aborted';        reason: string; session: Session; traceId: string }
+  | { type: 'error';          error: string;          traceId: string }
+  // A queued submission dropped before it ever ran (e.g. by `SessionRunner.abort`). It carries no
+  // session because nothing ran and so nothing was persisted — but it does have a traceId: the
+  // submission it cancels was assigned one at enqueue, and a frontend needs it to retire that bubble.
+  | { type: 'cancelled';      sessionId: string;      traceId: string };
+
+/**
+ * Events about the *session*, not any one turn — hence keyed on `sessionId` with no `traceId`. Split from
+ * {@link TurnEvent} so that absence is type-checkable rather than a comment: `idle` was the single arm of
+ * a 20-arm union without a `traceId`, which every consumer had to know by having read the note saying so.
+ */
+export type SessionEvent =
+  // The runner has fully drained its queue. Emitted once per busy period, *after* `running` flips false,
+  // so a consumer can map it to an authoritative busy→idle transition without racing the internal flip.
+  | { type: 'idle';           sessionId: string };
+
+/**
+ * The streaming output of a session: its turns' events, plus the session-level ones.
+ *
+ * Consumers that only ever see one turn (a tool reporting progress, a per-turn frontend) should narrow to
+ * {@link TurnEvent} and get `traceId` unconditionally; a subscriber to a whole session takes this union
+ * and must handle `idle`. Switching on `type` works the same either way.
+ */
+export type PipelineEvent = TurnEvent | SessionEvent;

package/src/types/files.ts

@@ -0,0 +1,46 @@
+import type { ISODate, MimeType } from './primitives.js';
+
+// ── Files ─────────────────────────────────────────────────────────────────────
+
+export interface FileMetaData {
+  id:          string;
+  version:     string;
+  name:        string;
+  mimeType:    MimeType;
+  size:        number;
+  createdAt:   ISODate;
+  sessionId?:  string;
+  messageId?:  string;
+  namespace?:  string;
+  /** Whether this file may be served at a public URL. Default-deny: absent ⇒ not servable. The
+   *  flag rides in the file's own persisted metadata (no separate allow-list), so the same read that
+   *  resolves a request also gates it. Producers opt in per put (the workspace tool sets it true). */
+  allowed?:    boolean;
+}
+
+export interface FileHandle extends FileMetaData {
+  stream(signal?: AbortSignal): AsyncIterable<Uint8Array>;
+}
+
+export interface FileFilter {
+  sessionId?:     string;
+  mimeType?:      string;
+  namespace?:     string;
+  createdAfter?:  ISODate;
+  createdBefore?: ISODate;
+}
+
+export interface FileStore {
+  /** Store a file. When `name` is provided, upserts by (name + namespace); otherwise always creates a new entry. */
+  put(
+    name:     string | undefined,
+    mimeType: MimeType,
+    data:     AsyncIterable<Uint8Array>,
+    meta?:    { sessionId?: string; messageId?: string; namespace?: string; allowed?: boolean }
+  ): Promise<FileHandle>;
+  get(id: string): Promise<FileHandle | null>;
+  getByName(name: string, namespace?: string): Promise<FileHandle | null>;
+  delete(id: string): Promise<void>;
+  list(filter?: FileFilter): AsyncIterable<FileHandle>;
+  putTemp(name: string, mimeType: MimeType, data: AsyncIterable<Uint8Array>): Promise<FileHandle>;
+}

package/src/types/frontend.ts

@@ -0,0 +1,11 @@
+// ── Frontend ──────────────────────────────────────────────────────────────────
+
+/**
+ * Passed to `services.registerFrontend()` by a plugin declaring itself a frontend. A frontend
+ * owns its own I/O (an HTTP server, a bot connection, a REPL); matbot only needs to know it
+ * exists. This object is the growth point for frontend-level capability advertisement
+ * (accepted/produced MIME types, size limits, …) as media support lands.
+ */
+export interface FrontendInfo {
+  name: string;
+}

package/src/types/health.ts

@@ -0,0 +1,6 @@
+// ── Health ────────────────────────────────────────────────────────────────────
+
+export type HealthStatus =
+  | { status: 'ok';       latencyMs?: number }
+  | { status: 'degraded'; reason: string; latencyMs?: number }
+  | { status: 'down';     reason: string };