@matatbread/matbot-plugin-api 0.3.0 → 0.3.1

package/package.json

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

package/src/plugin.ts

@@ -2,7 +2,7 @@ import type {
   FileStore, Vault, Message, ModelParameters,
   ProviderAdapter, ProviderConfig, ProviderRegistry, Tool, ToolRegistry, FrontendInfo,
   Store, Session, SystemContextRegistry, KnowledgeIndex, PromptFn, SessionRunner, Usage,
-  TypeScriptStripper, ToolTypeIndex,
+  TypeScriptStripper, ToolTypeIndex, ToolPresenter,
 } from './types.js';
 import type { HookRegistry } from './hooks.js';
 
@@ -101,6 +101,11 @@ export interface MatbotServices {
    *  reference held across a swap keeps resolving to the live backend. Always present (boot default). */
   readonly Vault: Vault;
   readonly KnowledgeIndex: KnowledgeIndex;
+  /** 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
+   *  {@link ToolPresenter}. */
+  readonly ToolPresenter?: ToolPresenter | undefined;
 }
 
 /** The assembled machine: registry services wired to the fixed runtime — what `setup()` receives. */

package/src/types.ts

@@ -802,6 +802,32 @@ export interface ToolRegistry {
   watch(signal?: AbortSignal): AsyncIterable<ToolRegistryEvent>;
 }
 
+/** What the runner tells a {@link ToolPresenter} about the call it's about to make. */
+export interface PresentContext {
+  /** The session as of this provider call — the persisted user turn plus any assistant/tool turns
+   *  taken so far this turn. A presenter ranks the tool set against this. */
+  session:  Session;
+  /** The provider profile name this turn runs under, so a presenter can tailor to provider
+   *  capabilities (e.g. Anthropic's in-context tool_reference expansion). */
+  provider: string;
+}
+
+/**
+ * Chooses which tools are advertised to the model for a single provider call — a read-only *view* over
+ * the turn's tool snapshot, NOT tool management. Presentation is orthogonal to the {@link ToolRegistry},
+ * which stays the single source of registration, resolution, and type-contracts (its fragile, load-bearing
+ * machinery is never a swap surface). The runner consults the presenter before *every* provider call, so
+ * an impl may present a subset (deferring a large library behind a search tool) and grow it mid-turn as the
+ * model discovers tools. Executor resolution is unaffected — a tool withheld here stays callable by name
+ * through the live registry — so presentation only ever changes what the model is *told about*.
+ *
+ * Optional {@link MatbotServices} member (offer-loosely): absent ⇒ the runner advertises the whole
+ * snapshot, byte-identical to today. `present` may return synchronously or async (a reranker).
+ */
+export interface ToolPresenter {
+  present(tools: readonly Tool[], ctx: PresentContext): readonly Tool[] | Promise<readonly Tool[]>;
+}
+
 /**
  * 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