@matatbread/matbot-plugin-api 0.2.5 → 0.2.7

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.2.5",
+  "version": "0.2.7",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "typescript": "^5.8.0"
+    "typescript": "^6.0.3"
   },
   "scripts": {
     "typecheck": "tsc --noEmit"

package/src/invoke-tool.ts

@@ -1,5 +1,5 @@
 import type { MatbotMachine } from './plugin.js';
-import type { ToolContext, ToolEvent, ToolResultOf, PromptFn, FormField } from './types.js';
+import type { ToolContext, ToolEvent, ToolResultFor, PromptFn, FormField } from './types.js';
 
 /**
  * Inputs to {@link invokeTool} that a one-shot caller can't derive from the machine. A tool
@@ -25,12 +25,12 @@ export type InvokeToolOptions =
  * runs non-interactively: any attempt to prompt rejects, which a tool surfaces as a normal error
  * event. Pair with {@link toolText} to collapse the stream to its result string.
  */
-export function invokeTool<K extends string>(
+export function invokeTool<K extends string, const P>(
   machine: MatbotMachine,
   name:    K,
-  params:  unknown,
+  params:  P,
   opts:    InvokeToolOptions,
-): AsyncIterable<ToolEvent<ToolResultOf<K>>> {
+): AsyncIterable<ToolEvent<ToolResultFor<K, P>>> {
   const tool = machine.tools.resolve(name);
   if (tool === null) throw new Error(`Tool "${name}" is not registered`);
 
@@ -51,7 +51,7 @@ export function invokeTool<K extends string>(
 
   // The registry is name-keyed and untyped (`ToolExecutor.execute` yields `ToolEvent<unknown>`); the
   // `ToolResults` mapping is the call-site contract, asserted here so callers read a typed result.
-  return tool.executor.execute(params, ctx) as AsyncIterable<ToolEvent<ToolResultOf<K>>>;
+  return tool.executor.execute(params, ctx) as AsyncIterable<ToolEvent<ToolResultFor<K, P>>>;
 }
 
 /**

package/src/plugin.ts

@@ -491,7 +491,13 @@ export interface MatbotPluginSpec {
  */
 export interface MatbotPlugin extends MatbotPluginSpec {
   readonly name:      string;   // resolver.identify(specifier)
-  readonly specifier: string;   // how it was loaded
+  readonly specifier: string;   // how it was loaded (config entry / pre-resolved)
+  /** The stable URL the loader actually imported, minus any reload cache-bust stamp — a `file:` URL
+   *  for local/remote-cached plugins, the bare specifier when nothing was pre-resolved. Lets a consumer
+   *  map a loaded plugin back to its on-disk source without re-running specifier resolution (e.g.
+   *  skills_compiler builds a types program over the live plugin set). Set by the loader; absent only
+   *  on hosts that construct MatbotPlugin by hand. */
+  readonly resolvedUrl?: string;
   readonly source?:   PluginSource;
   // The package.json `matbotRuntime`, captured at load from the same value used for the pre-import
   // gate (the host reads it once; downstream just reads this). Absent ⇒ undeclared. Stored rather

package/src/types.ts

@@ -431,6 +431,11 @@ export interface KnowledgeEntry {
 
 export interface KnowledgeIndex {
   index(entry: KnowledgeEntry): Promise<void>;
+  /** Remove the entry with this id, if present (idempotent — removing an absent id is a no-op). The
+   *  id is the index's sole primary key (`index` replaces by it), so retraction is by id alone; the
+   *  index never inspects an entry's opaque `source`. The party that indexed an entry owns retracting
+   *  it — e.g. a skill manager retracts a hidden/deleted skill rather than the index policing tenants. */
+  remove(id: string): Promise<void>;
   search(terms: Array<{ term: string; context?: string }>, signal: AbortSignal): Promise<KnowledgeEntry[]>;
   /** Enumerate all indexed entries. When present, register('KnowledgeIndex', …) drains these into the incoming backend. */
   entries?(): Iterable<KnowledgeEntry>;
@@ -465,11 +470,61 @@ export type ToolEvent<Result = unknown> =
  * name with no registered entry resolves to `unknown` (the caller must narrow). This is a pure
  * type-level construct — no runtime validation; it pins, at the call site, the contract a tool's
  * executor already produces. Keep the entry in sync with what the executor actually yields.
+ *
+ * **Multi-action tools** are a weird form of overloaded function: the same tool returns different
+ * shapes depending on its params. Register such a tool as a union of {@link ToolResult} *arms*, each
+ * pairing a result with the discriminating params *pattern* that selects it — `invokeTool` matches the
+ * call's literal params against the patterns and narrows the result to the matching arm:
+ *
+ *   declare module '@matatbread/matbot-plugin-api' {
+ *     interface ToolResults {
+ *       session_action:
+ *         | ToolResult<Session,                       { action: 'get' }>
+ *         | ToolResult<{ id: string; title: string }, { action: 'rename' }>;
+ *     }
+ *   }
+ *   // invokeTool(machine, 'session_action', { action: 'get', sessionId }) → result is Session
+ *
+ * The pattern is *any* discriminating field(s), not just `action` (a tool keying on `interval`'s
+ * presence registers `ToolResult<…, { interval: string }>`). It is a *pattern*, not the full input:
+ * key only on the discriminant so a call carrying just that field still matches. When no arm's pattern
+ * matches (a non-literal discriminant, or an absence-discriminant the positive patterns can't express),
+ * the result falls back to the union of every arm — always sound, just less narrow.
  */
 export interface ToolResults {}
 
-/** The `result` value a tool named `K` yields, or `unknown` when `K` isn't registered in {@link ToolResults}. */
-export type ToolResultOf<K extends string> = K extends keyof ToolResults ? ToolResults[K] : unknown;
+/**
+ * One overload arm of a multi-action tool registered in {@link ToolResults}: the `Result` it yields
+ * for a call whose params match the discriminating pattern `Args`. `Args` defaults to `unknown` (an
+ * arm that matches any params). Purely type-level — the `__` fields are phantom and never constructed.
+ */
+export interface ToolResult<Result, Args = unknown> {
+  readonly __result: Result;
+  readonly __args:   Args;
+}
+
+type ToolResultArmed<E>           = E extends ToolResult<unknown, unknown> ? true : false;
+type ToolResultUnion<E>           = E extends ToolResult<infer R, unknown> ? R : never;
+type ToolResultMatched<E, P>      = E extends ToolResult<infer R, infer A> ? (P extends A ? R : never) : never;
+
+/** The full set of `result` values a tool named `K` may yield — the union over all its arms (for an
+ *  arm-based entry), the entry itself (for a plain entry), or `unknown` when `K` is unregistered. This
+ *  is what an executor binds against (`ToolExecutor<ToolResultOf<'my_tool'>>`): it must cover every arm. */
+export type ToolResultOf<K extends string> =
+  K extends keyof ToolResults
+    ? ToolResultArmed<ToolResults[K]> extends true ? ToolResultUnion<ToolResults[K]> : ToolResults[K]
+    : unknown;
+
+/** The `result` a call to tool `K` with params `P` yields: for an arm-based entry, the arm whose
+ *  pattern `P` matches (or the full union when none match — always sound); otherwise {@link ToolResultOf}. */
+export type ToolResultFor<K extends string, P> =
+  K extends keyof ToolResults
+    ? ToolResultArmed<ToolResults[K]> extends true
+      ? ([ToolResultMatched<ToolResults[K], P>] extends [never]
+          ? ToolResultUnion<ToolResults[K]>
+          : ToolResultMatched<ToolResults[K], P>)
+      : ToolResults[K]
+    : unknown;
 
 /**
  * Ask the user a question and resolve with their answer. The host supplies the
@@ -520,15 +575,23 @@ export interface ToolContext {
   unloadPlugin(specifier: string): Promise<boolean>;
 }
 
-export interface ToolExecutor {
-  execute(input: unknown, ctx: ToolContext): AsyncIterable<ToolEvent>;
+/**
+ * A tool's runtime. `R` is the type of the `value` carried by its `result` event — declared once,
+ * at the source, so the executor's yields and the tool's {@link ToolResults} registry entry can't
+ * silently drift. The `unknown` default keeps untyped executors compiling untouched, and covariance
+ * means a narrower `ToolExecutor<X>` still satisfies `ToolExecutor` (i.e. `ToolExecutor<unknown>`),
+ * so the heterogeneous registry boundary (`Tool[]`) accepts any executor. Bind `R` to the registry
+ * entry with `ToolExecutor<ToolResultOf<'my_tool'>>` so the single augmentation is the source of truth.
+ */
+export interface ToolExecutor<R = unknown> {
+  execute(input: unknown, ctx: ToolContext): AsyncIterable<ToolEvent<R>>;
 }
 
-export interface Tool {
+export interface Tool<R = unknown> {
   name:         string;
   description:  string;
   inputSchema:  JSONSchema;
-  executor:     ToolExecutor;
+  executor:     ToolExecutor<R>;
   pluginName?:  string;
 }
 
@@ -604,7 +667,11 @@ export interface VaultSpec {
   /** Resolve ${NAME} placeholders by looking up the named value; throws MissingSecretError for any miss. */
   resolve(ref: string): Promise<string>;
   scrub(text: string): string;
-  /** Store `value` under exactly `name`, overwriting. The literal write; no reference/dedup logic. */
+  /**
+   * Store `value` under exactly `name`, overwriting. The literal write; no reference/dedup logic.
+   * An empty `value` removes the key instead — there is no such thing as an empty secret, so the
+   * empty string is the removal signal (idempotent: removing an absent name is a no-op).
+   */
   writeSecret(name: string, value: string): Promise<void>;
   /** Whether a secret is stored under this exact name. */
   hasKey(name: string): boolean;