@matatbread/matbot-plugin-api 0.3.0 → 0.3.2

package/package.json

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

package/src/invoke-tool.ts

@@ -1,5 +1,5 @@
 import type { MatbotMachine } from './plugin.js';
-import type { ToolContext, ToolEvent, ToolResultFor, PromptFn, FormField } from './types.js';
+import type { ToolContext, ToolEvent, ToolResultFor, ToolProxy, PromptFn, FormField } from './types.js';
 
 /**
  * Inputs to {@link invokeTool} that a one-shot caller can't derive from the machine. A tool
@@ -98,3 +98,55 @@ const rejectingPrompt: PromptFn = (((p: string | FormField): Promise<string> =>
   const label = typeof p === 'string' ? p : p.label;
   return Promise.reject(new Error(`Non-interactive context: cannot prompt for "${label}"`));
 }) as PromptFn);
+
+/** Compact a value to one trace line. */
+function compactTrace(v: unknown): string {
+  let s: string;
+  if (typeof v === 'string') s = v;
+  else { try { s = JSON.stringify(v) ?? String(v); } catch { s = String(v); } }
+  return s.length > 240 ? `${s.slice(0, 240)}…` : s;
+}
+
+/**
+ * A factory for a context-overridden {@link ToolProxy}: `toolInContext({ provider }).some_tool(params)`
+ * runs `some_tool` with the given fields merged over the box's bound context (omitted fields inherited).
+ * Keyed on `ToolContracts`, so a hallucinated tool name is a **compile error**. This is the explicit
+ * escape hatch beside the default `tool` proxy — reach for it only when a call needs a different provider,
+ * signal, prompt or session.
+ */
+export type ToolBox = (call?: Partial<InvokeToolOptions>) => ToolProxy;
+
+/**
+ * Build the typed calling surface both `function-tools` compositions and compiled skills use:
+ *
+ *   const { tool, toolInContext } = makeToolBox(machine, callContext, { onEvent });
+ *   await tool.some_tool(params);                     // bound context; a bad name is a compile error
+ *   await toolInContext({ provider }).some_tool(...); // override one field for this call
+ *
+ * `tool` is a {@link ToolProxy} bound to `callContext`; `toolInContext(override)` returns a fresh proxy
+ * with `override` merged over it (never mutating `tool`). `onEvent`, when supplied, receives a `stdout`
+ * trace per call (→ name / ← result) so a run is observable; omit it for a silent surface. Built on
+ * {@link invokeTool}/{@link toolResult}, which remain the low-level, dynamic-name seam.
+ */
+export function makeToolBox(
+  machine:     MatbotMachine,
+  defaultCall: InvokeToolOptions,
+  opts?:       { onEvent?: (event: ToolEvent) => void },
+): { tool: ToolProxy; toolInContext: ToolBox } {
+  const build = (call: InvokeToolOptions): ToolProxy =>
+    new Proxy({}, {
+      get(_target, prop) {
+        // A symbol key, or `then`, must not read as a callable tool — otherwise the proxy looks like a
+        // thenable and awaiting/returning it would try to invoke a tool named `then`.
+        if (typeof prop !== 'string' || prop === 'then') return undefined;
+        return async (params?: unknown): Promise<unknown> => {
+          opts?.onEvent?.({ type: 'stdout', chunk: `→ ${prop}(${compactTrace(params)})\n` });
+          const value = await toolResult(invokeTool(machine, prop, params ?? {}, call));
+          opts?.onEvent?.({ type: 'stdout', chunk: `← ${prop}: ${compactTrace(value)}\n` });
+          return value;
+        };
+      },
+    }) as ToolProxy;
+  const toolInContext: ToolBox = (override) => build(override === undefined ? defaultCall : { ...defaultCall, ...override });
+  return { tool: build(defaultCall), toolInContext };
+}

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

@@ -590,6 +590,9 @@ type ArmCallSig<E> =
     ? (unknown extends P ? (params?: unknown) => Promise<R> : (params: P) => Promise<R>)
     : never;
 
+// The union of a tool's arm params — the parameter type of the trailing catch-all signature below.
+type ArmArgsUnion<E> = E extends ToolContract<unknown, infer A> ? A : never;
+
 /**
  * The type of the injected `tool` proxy that `function-tools` and compiled skills call
  * (`await tool.name(params)`). Each key is derived from its {@link ToolContracts} entry: a multi-arm
@@ -599,8 +602,17 @@ type ArmCallSig<E> =
  * generated `dts()` declares `tool` as; it is *derived* — never hand-authored — from the same `ToolContracts`
  * augmentation that types authors' `invokeTool`/`toolResult` calls, so the human editor and the LLM see one
  * source of truth.
+ *
+ * The trailing catch-all signature (params union → result union) exists for soundness at the *meta-type*
+ * level, not for call sites: overload resolution is first-match, so a well-formed call still hits its
+ * specific arm and narrows precisely, and a malformed call matches nothing and still errors. What it
+ * changes: `ReturnType<typeof tool.x>` — which on a bare overload set resolves to an arbitrary (last) arm,
+ * a real-world codegen trap — now degrades to the sound full union; and a params value typed as a union of
+ * arms (dynamic multi-action dispatch) becomes callable, returning the result union.
  */
-export type ToolProxy = { [K in keyof ToolContracts]: UnionToIntersection<ArmCallSig<ToolContracts[K]>> };
+export type ToolProxy = { [K in keyof ToolContracts]:
+    UnionToIntersection<ArmCallSig<ToolContracts[K]>>
+  & ((params: ArmArgsUnion<ToolContracts[K]>) => Promise<ToolResultUnion<ToolContracts[K]>>) };
 
 /**
  * Ask the user a question and resolve with their answer. The host supplies the
@@ -802,6 +814,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