@matatbread/matbot-plugin-api 0.2.7 → 0.2.9

package/package.json

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

package/src/plugin.ts

@@ -1,6 +1,6 @@
 import type {
   FileStore, Vault, Message, ModelParameters,
-  ProviderAdapter, ProviderConfig, Tool, ToolRegistry, FrontendInfo,
+  ProviderAdapter, ProviderConfig, ProviderRegistry, Tool, ToolRegistry, FrontendInfo,
   Store, Session, SystemContextRegistry, KnowledgeIndex, PromptFn, SessionRunner, Usage,
 } from './types.js';
 import type { HookRegistry } from './hooks.js';
@@ -56,6 +56,13 @@ export type Runtime = 'node' | 'browser';
  */
 export interface PluginResolver {
   identify(specifier: string): Promise<string>;
+  /**
+   * The plugin's package.json `version`, or `undefined` when it can't be read (no package.json, or a
+   * remote specifier whose version isn't baked). Read from the same nearest-named-package.json boundary
+   * as {@link identify}, so it lives here (host-specific: fs walk on node, baked manifest in the browser)
+   * rather than in the platform-neutral loader. Stamped onto {@link MatbotPlugin.version} at load.
+   */
+  version?(specifier: string): Promise<string | undefined>;
   /**
    * The runtimes a plugin declares support for via its package.json `matbotRuntime`
    * (e.g. `["node"]`, `["browser"]`, `["node","browser"]`), or `undefined` when the field is
@@ -97,7 +104,7 @@ export type MatbotMachine = MatbotServices & MatbotRuntime;
 /**
  * The fixed runtime — microcode, not a service: the agentic loop's primitives (`complete`,
  * `createStore`), the registries you mutate but never swap wholesale (`hooks`, `tools`,
- * `systemContext`), plugin lifecycle, and the registry API itself. Not augmentable, not registerable.
+ * `systemContext`, `providers`), plugin lifecycle, and the registry API itself. Not augmentable, not registerable.
  */
 export interface MatbotRuntime {
   complete(req: CompletionRequest): Promise<CompletionResponse>;
@@ -198,7 +205,7 @@ export interface MatbotRuntime {
   /** The calling plugin's own loader-established identity. Bound per-plugin inside setup(). */
   readonly self?:           PluginSelf;
 
-  readonly providers:       ReadonlyMap<string, ProviderConfig>;
+  readonly providers:       ProviderRegistry;
   readonly sessions?:       Store<Session>;
   /** Per-session turn serialiser. Frontends submit and observe through this rather than calling
    *  runSession directly, so concurrent submits queue instead of clobbering the session. */
@@ -504,4 +511,8 @@ export interface MatbotPlugin extends MatbotPluginSpec {
   // than re-derived so `list` can report it offline and for remote plugins, whose config-entry
   // specifier (a github:/https URL) can't be resolved back to a package.json after the fact.
   readonly matbotRuntime?: readonly Runtime[];
+  // The plugin's package.json `version`, read by the resolver at load (fs walk on node; baked manifest
+  // in the browser). Absent ⇒ couldn't be read (no package.json, or a remote whose version isn't baked).
+  // Loader-established provenance, like `name`/`matbotRuntime` — not the author's to declare.
+  readonly version?: string;
 }

package/src/types.ts

@@ -718,6 +718,27 @@ export interface ToolRegistry {
   watch(signal?: AbortSignal): AsyncIterable<ToolRegistryEvent>;
 }
 
+/**
+ * The named provider profiles the runtime resolves by name. A `ReadonlyMap` for the many read-only
+ * consumers (`services.providers.get`/`has`/`keys`/…), plus a sanctioned write path so a plugin can
+ * *contribute* profiles live — a storage backend replaying provider definitions it captured in its own
+ * medium, or the built-in `provider` tool — exactly as a plugin contributes tools via {@link ToolRegistry}.
+ * Keyed by `config.name`; `register` upserts.
+ */
+export interface ProviderRegistry extends ReadonlyMap<string, ProviderConfig> {
+  register(config: ProviderConfig): void;
+  /** Explicit delete (the `provider` tool's `remove`) — removes the profile outright. */
+  remove(name: string): boolean;
+  /**
+   * Undo a contribution: restore the boot-baseline profile for `name` if one existed (a plugin-supplied
+   * profile that shadowed a configured one), otherwise delete it. A plugin that registers providers
+   * (e.g. a storage backend replaying them from its medium) calls this for each in its `teardown()`, so
+   * unloading it reverts the provider set to the host's boot condition — the multi-valued analogue of a
+   * swap-member reverting to its captured boot default.
+   */
+  revert(name: string): void;
+}
+
 export type PluginRegistryEvent =
   | { type: 'loaded';   name: string }
   | { type: 'unloaded'; name: string };