@matatbread/matbot-plugin-api 0.3.2 → 0.3.4

package/package.json

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

package/src/broadcast.ts

@@ -1,27 +1,47 @@
 // 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
+// file changes, 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.
+//
+// Every event flows as a {@link Routed} envelope carrying an optional `origin` principal — the partition
+// or actor that produced it. This is the one attribution channel shared by every stream (files, skills,
+// future partitioned stores); a global stream (tool/plugin registry) simply never sets it. Per-subscriber
+// filtering (`subscribe(signal, filter)`) is applied at emit time, so a subscriber that only wants events
+// visible to one principal never even queues the rest — the single, common place per-principal visibility
+// lives, whatever the terminal (SSE→frontend, an internal consumer, or a cache).
+
+import type { Principal } from './types.js';
+
+/** A broadcast event plus its optional origin. `origin` undefined ⇒ global/base — visible to all. */
+export interface Routed<T> {
+  readonly value:   T;
+  readonly origin?: Principal;
+}
+
+/** Per-subscriber predicate: keep only the envelopes it returns true for. */
+export type RoutedFilter<T> = (event: Routed<T>) => boolean;
 
 interface Subscriber<T> {
-  queue: T[];
-  wake:  (() => void) | undefined;
-  done:  boolean;
+  queue:  Routed<T>[];
+  wake:   (() => void) | undefined;
+  done:   boolean;
+  filter: RoutedFilter<T> | undefined;
 }
 
 // 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>;
+  subscribe(signal?: AbortSignal, filter?: RoutedFilter<T>): AsyncIterable<Routed<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;
+  // every watch call site otherwise hand-writes. An internal cache is exactly this: a `consume` that
+  // folds each `Routed<T>` into per-origin state.
+  consume(handler: (event: Routed<T>) => void | Promise<void>, signal?: AbortSignal, filter?: RoutedFilter<T>): void;
 }
 
 export interface Broadcaster<T> extends Subscribable<T> {
-  emit(value: T): void;
+  emit(value: T, origin?: Principal): void;
 }
 
 /**
@@ -29,11 +49,13 @@ export interface Broadcaster<T> extends Subscribable<T> {
  * `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 => {
+export function subscribable<T>(
+  subscribe: (signal?: AbortSignal, filter?: RoutedFilter<T>) => AsyncIterable<Routed<T>>,
+): Subscribable<T> {
+  const consume = (handler: (event: Routed<T>) => void | Promise<void>, signal?: AbortSignal, filter?: RoutedFilter<T>): void => {
     void (async () => {
-      for await (const v of subscribe(signal)) {
-        try { await handler(v); }
+      for await (const event of subscribe(signal, filter)) {
+        try { await handler(event); }
         catch (e) { console.error('[matbot] consume handler threw:', e instanceof Error ? e.message : e); }
       }
     })();
@@ -44,15 +66,17 @@ export function subscribable<T>(subscribe: (signal?: AbortSignal) => AsyncIterab
 export function createBroadcaster<T>(): Broadcaster<T> {
   const subs = new Set<Subscriber<T>>();
 
-  const emit = (value: T): void => {
+  const emit = (value: T, origin?: Principal): void => {
+    const event: Routed<T> = origin !== undefined ? { value, origin } : { value };
     for (const sub of subs) {
-      sub.queue.push(value);
+      if (sub.filter !== undefined && !sub.filter(event)) continue;
+      sub.queue.push(event);
       sub.wake?.();
     }
   };
 
-  async function* subscribe(signal?: AbortSignal): AsyncIterable<T> {
-    const sub: Subscriber<T> = { queue: [], wake: undefined, done: false };
+  async function* subscribe(signal?: AbortSignal, filter?: RoutedFilter<T>): AsyncIterable<Routed<T>> {
+    const sub: Subscriber<T> = { queue: [], wake: undefined, done: false, filter };
     subs.add(sub);
     const onAbort = () => { sub.done = true; sub.wake?.(); };
     signal?.addEventListener('abort', onAbort, { once: true });

package/src/errors.ts

@@ -16,7 +16,7 @@
 
 const BRAND = 'matbot';
 
-export type MatbotErrorKind = 'MissingSecret' | 'IncompatibleRuntime' | 'NotAPlugin' | 'PromptCancelled';
+export type MatbotErrorKind = 'MissingSecret' | 'IncompatibleRuntime' | 'NotAPlugin' | 'PromptCancelled' | 'ReadOnly';
 
 function isKind(e: unknown, kind: MatbotErrorKind): boolean {
   return typeof e === 'object' && e !== null && (e as Record<string, unknown>)[BRAND] === kind;
@@ -102,3 +102,26 @@ export function promptCancelledError(message = 'User cancelled — cannot procee
 export function isPromptCancelledError(e: unknown): e is PromptCancelledError {
   return isKind(e, 'PromptCancelled');
 }
+
+/**
+ * Thrown by a `Store` write when the target item is not owned by the current principal — e.g. a session
+ * shared read-only into another profile's partition (see `@matatbread/matbot-storage-profiles`). This is
+ * a per-operation condition, **not** a process fault: the turn pump catches it (via {@link isReadOnlyError},
+ * never `instanceof`) and surfaces it as a turn error rather than letting it escape the detached pump and
+ * crash the host. `namespace`/`id` name the item; `owner` is the owning principal id (`''` for the shared
+ * base/global partition).
+ */
+export interface ReadOnlyError extends Error {
+  matbot: 'ReadOnly';
+  readonly namespace: string;
+  readonly id:        string;
+  readonly owner:     string;
+}
+export function readOnlyError(namespace: string, id: string, owner: string): ReadOnlyError {
+  const e = new Error(`${namespace} "${id}" was shared by "${owner || 'global'}" and is read-only.`);
+  e.name = 'ReadOnlyError';
+  return Object.assign(e, { matbot: 'ReadOnly' as const, namespace, id, owner });
+}
+export function isReadOnlyError(e: unknown): e is ReadOnlyError {
+  return isKind(e, 'ReadOnly');
+}

package/src/plugin.ts

@@ -1,9 +1,10 @@
 import type {
-  FileStore, Vault, Message, ModelParameters,
+  FileStore, FileEvent, Principal, Vault, Message, ModelParameters,
   ProviderAdapter, ProviderConfig, ProviderRegistry, Tool, ToolRegistry, FrontendInfo,
   Store, Session, SystemContextRegistry, KnowledgeIndex, PromptFn, SessionRunner, Usage,
   TypeScriptStripper, ToolTypeIndex, ToolPresenter,
 } from './types.js';
+import type { Routed } from './broadcast.js';
 import type { HookRegistry } from './hooks.js';
 
 export const PLUGIN_API_VERSION = '0.1';
@@ -106,6 +107,10 @@ export interface MatbotServices {
    *  whole turn snapshot. A plain registered service (not a swap-member); consumed as a member. See
    *  {@link ToolPresenter}. */
   readonly ToolPresenter?: ToolPresenter | undefined;
+  /** Optional partition-aware file-watch layer (cross-partition observation + per-connection visibility),
+   *  registered by a partitioning storage backend. Absent ⇒ frontends use the plain `fileStore.watch()`.
+   *  See {@link WatchVisibility}. */
+  readonly WatchVisibility?: WatchVisibility | undefined;
 }
 
 /** The assembled machine: registry services wired to the fixed runtime — what `setup()` receives. */
@@ -166,10 +171,10 @@ export interface MatbotRuntime {
    * per-invocation through its proxy/member instead.
    *
    *   // cache the backend's documents; rebuild on every swap (own initial load was in setup())
-   *   services.mounted.consume({ key: 'StorageBackend', signal }, () => this.load());
+   *   services.mounted.observe({ key: 'StorageBackend', signal }, () => this.load());
    *
    *   // depend on a peer service that may not be present yet; seed now if it is, and on each (re)mount
-   *   services.mounted.consume({ key: 'SkillManager', replay: true, signal }, m => seed(m));
+   *   services.mounted.observe({ key: 'SkillManager', replay: true, signal }, m => seed(m));
    *
    * Contract guarantees only *eventual, ordered* delivery of each key's net presence transition — it
    * says nothing about timing: a mount may fire synchronously-ish or batch to a later quiescent edge, so
@@ -334,9 +339,11 @@ export interface MountConsumeOptions<K extends keyof MatbotServices> {
   readonly onUnmount?: (machine: MatbotMachine) => void | Promise<void>;
 }
 
-/** The mount-table consumer facet exposed on {@link MatbotRuntime.mounted}. */
+/** The mount-table consumer facet exposed on {@link MatbotRuntime.mounted}. `observe` (not `consume`)
+ *  so the verb `consume` means exactly one thing repo-wide — the detached stream drain on
+ *  {@link Subscribable}; this keyed, replay/onUnmount, edge-batched delivery is its own paradigm. */
 export interface Mounted {
-  consume<K extends keyof MatbotServices>(
+  observe<K extends keyof MatbotServices>(
     options: MountConsumeOptions<K>,
     handler: (machine: MountedMachine<K>) => void | Promise<void>,
   ): void;
@@ -385,7 +392,7 @@ export function createMountTable(getMachine: () => MatbotMachine): MountTable {
   };
 
   const mounted: Mounted = {
-    consume(options, handler) {
+    observe(options, handler) {
       const { key, replay, signal, onUnmount } = options;
       if (signal?.aborted === true) return;
       const interest: MountInterest = {
@@ -478,6 +485,29 @@ export interface StorageBackend {
   close?(): Promise<void>;
 }
 
+/**
+ * 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).
+ */
+export interface WatchVisibility {
+  /** Every partition's file events, merged into one stream, each tagged with its origin partition. */
+  watchFiles(signal?: AbortSignal): AsyncIterable<Routed<FileEvent>>;
+  /**
+   * The per-connection visibility predicate for ANY partitioned event stream (files, skills, …): would a
+   * connection owned by `viewer` see an event in `namespace` produced by `origin`? Defined as
+   * `route(viewer, namespace) === route(origin, namespace)` — the two see it iff they route that namespace
+   * to the same partition. This yields the intended behavior uniformly: a viewer sees global/base events
+   * for namespaces it does NOT isolate, and only its own partition's events for namespaces it does.
+   * `origin` may be a partition principal (files, tagged by the merge) or the acting principal (skills,
+   * stamped at write) — routing both sides makes either correct. `undefined` origin ⇒ base.
+   */
+  visible(viewer: Principal, namespace: string, origin: Principal | undefined): boolean;
+}
+
 // ── Plugin interface ──────────────────────────────────────────────────────────
 
 /**

package/src/types.ts

@@ -62,9 +62,30 @@ export interface UsageRecord {
   usage:    Usage;
 }
 
+/**
+ * Opaque, provider-specific round-trip metadata attached to a tool-call — captured from a completion,
+ * persisted, and re-sent verbatim when the call is replayed in history (e.g. a Gemini 3 "thought
+ * signature", which every historical `functionCall` must carry or the request 400s). The harness never
+ * interprets it: it stores, renders, or elides it. Empty by default — a provider package augments its
+ * OWN slice from its own module (namespaced by provider family, so slices from different providers in a
+ * mixed-provider session never collide), so adding a provider that needs round-trip state touches NO
+ * core code:
+ *
+ *   declare module '@matatbread/matbot-plugin-api' {
+ *     interface ProviderMeta { google?: { thoughtSignature?: string } }
+ *   }
+ *
+ * A single session interleaves tool-calls from many providers, so this must be an open, additive union
+ * (interface augmentation) — a generic type parameter can bind only one provider per instantiation and
+ * so could not type a heterogeneous transcript.
+ */
+export interface ProviderMeta {}
+
 export type CompletionEvent =
   | { type: 'text-delta';          delta: string }
-  | { type: 'tool-call';           id: string; name: string; input: unknown }
+  | { type: 'tool-call';           id: string; name: string; input: unknown;
+      /** Provider-specific round-trip metadata for this call, opaque to the harness — see `ProviderMeta`. */
+      meta?: ProviderMeta }
   | { type: 'tool-result';         id: string; result: unknown }
   | { type: 'thinking';            delta: string }
   | { type: 'thinking-block';      thinking: string; signature: string }
@@ -99,7 +120,10 @@ export type MessageContent = (
   | { type: 'image-url';         url: string; detail?: 'low' | 'high' | 'auto' }
   | { type: 'document';          data: string; mimeType: MimeType; name?: string }
   | { type: 'audio';             data: string; mimeType: MimeType }
-  | { type: 'tool-call';         id: string; name: string; input: unknown }
+  | { type: 'tool-call';         id: string; name: string; input: unknown;
+      /** Provider-specific round-trip metadata, persisted and re-sent verbatim on replay — see
+       *  `ProviderMeta` and the `tool-call` `CompletionEvent`. */
+      meta?: ProviderMeta }
   | { type: 'tool-result';       id: string; result: unknown; isError?: boolean;
       /**
        * Accounting addendum: completions the tool itself ran (e.g. `single_turn`, `dream_time`'s ranker/
@@ -199,9 +223,9 @@ export type SessionStatus = 'active' | 'archived' | 'pinned';
 export interface Session {
   id:                    string;
   version:               string;
-  ownerPrincipalId:      string;
-  actorPrincipalId?:     string;
-  persona?:              string;
+  // Legacy: persisted sessions may still carry `ownerPrincipalId` / `actorPrincipalId` / `persona`.
+  // They were never read — ownership-at-rest is structural (the storage partition), resolved via the
+  // backend, not a field. Left undeclared; old data keeps them harmlessly as excess properties.
   title?:                string;
   status:                SessionStatus;
   contexts:              string[];
@@ -230,7 +254,6 @@ export interface SystemContextRegistry {
 
 export interface RunConfig {
   provider:   string;
-  persona?:   string;
   sessionId?: string;
   traceId?:   string;
 }