@matatbread/matbot-plugin-api 0.2.4 → 0.2.6

package/package.json

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

package/src/index.ts

@@ -10,3 +10,4 @@ export * from './context-switch.js';
 export * from './hooks.js';
 export * from './plugin.js';
 export * from './broadcast.js';
+export * from './invoke-tool.js';

package/src/invoke-tool.ts

@@ -0,0 +1,100 @@
+import type { MatbotMachine } from './plugin.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
+ * forwarding a call to another tool should pass its own {@link ToolContext} straight through as
+ * `opts` — `session`, `signal`, `prompt` and crucially **`provider`** all propagate, so a callee
+ * that needs an LLM (e.g. `find_fact`, or anything using `singleTurn`) inherits the same model
+ * rather than finding no provider. Only spell out individual fields when starting a call from
+ * scratch or deliberately overriding one; never hand-pick a subset of `ctx` and drop the rest.
+ */
+export type InvokeToolOptions =
+  Pick<ToolContext, 'session' | 'signal'>
+  & Partial<Pick<ToolContext, 'prompt' | 'provider' | 'callId'>>;
+
+/**
+ * Programmatically invoke a tool by name, the same way the harness does — resolve it off the
+ * machine's tool registry, build a `ToolContext` from the machine, and return its event stream.
+ * The host-only bits a one-shot caller can't derive (the session under which the call runs, its
+ * abort signal, and an optional interactive `prompt`/`provider`) come in via `opts` — pass the
+ * calling tool's `ctx` to forward them all (see {@link InvokeToolOptions}); everything else (vault,
+ * plugin (un)loading, workdir/configPath/files) is filled from `machine`.
+ *
+ * Throws synchronously if no tool is registered under `name`. When no `prompt` is supplied the tool
+ * 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, const P>(
+  machine: MatbotMachine,
+  name:    K,
+  params:  P,
+  opts:    InvokeToolOptions,
+): AsyncIterable<ToolEvent<ToolResultFor<K, P>>> {
+  const tool = machine.tools.resolve(name);
+  if (tool === null) throw new Error(`Tool "${name}" is not registered`);
+
+  const prompt = opts.prompt ?? rejectingPrompt;
+  const ctx: ToolContext = {
+    callId:       opts.callId ?? crypto.randomUUID(),
+    session:      opts.session,
+    signal:       opts.signal,
+    vault:        machine.Vault,
+    prompt,
+    loadPlugin:   (specifier, refresh) => machine.loadPlugin(specifier, prompt, refresh),
+    unloadPlugin: (specifier) => machine.unloadPlugin(specifier),
+    ...(opts.provider      !== undefined ? { provider:   opts.provider      } : {}),
+    ...(machine.workdir    !== undefined ? { workdir:    machine.workdir    } : {}),
+    ...(machine.configPath !== undefined ? { configPath: machine.configPath } : {}),
+    ...(machine.files      !== undefined ? { files:      machine.files      } : {}),
+  };
+
+  // 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<ToolResultFor<K, P>>>;
+}
+
+/**
+ * Drain a tool event stream (e.g. {@link invokeTool}'s return) to its raw `result` *value*, typed:
+ * paired with `invokeTool(machine, name, …)` it returns whatever `ToolResults[name]` declares (or
+ * `unknown` for an unregistered tool). This is the structured counterpart to {@link toolText} — use it
+ * for any tool that returns data; use `toolText` when you want the result collapsed to a string.
+ * Stops and throws on the first `error` event, or if the tool finished without yielding a `result`.
+ */
+export async function toolResult<R>(events: AsyncIterable<ToolEvent<R>>): Promise<R> {
+  let value!: R;
+  let hadResult = false;
+  for await (const ev of events) {
+    if      (ev.type === 'result') { value = ev.value; hadResult = true; }
+    else if (ev.type === 'error')  { throw new Error(ev.message); }
+  }
+  if (!hadResult) throw new Error('Tool produced no result');
+  return value;
+}
+
+/**
+ * Drain a tool event stream (e.g. {@link invokeTool}'s return) to its result as text. Stops and
+ * throws on the first `error` event, or if the tool finished without yielding a `result`. The result
+ * value is rendered the way the model would see it: a string verbatim, a `{ content: string }`
+ * (the shape `skill_action` and other prose tools return) by its `content`, anything else as JSON.
+ */
+export async function toolText(events: AsyncIterable<ToolEvent>): Promise<string> {
+  let result: unknown;
+  let hadResult = false;
+  for await (const ev of events) {
+    if      (ev.type === 'result') { result = ev.value; hadResult = true; }
+    else if (ev.type === 'error')  { throw new Error(ev.message); }
+  }
+  if (!hadResult) throw new Error('Tool produced no result');
+
+  if (typeof result === 'string') return result;
+  if (result !== null && typeof result === 'object' && typeof (result as { content?: unknown }).content === 'string') {
+    return (result as { content: string }).content;
+  }
+  return JSON.stringify(result, null, 2);
+}
+
+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);

package/src/plugin.ts

@@ -116,8 +116,11 @@ export interface MatbotRuntime {
    * Hot-load a plugin by specifier into the running process. Returns the loaded plugin.
    * `prompt`, when supplied, resolves tool-name collisions interactively during the new
    * plugin's setup(); the runner injects the triggering session's prompt automatically.
+   * `refresh` (default false) forces a remote (github/http) plugin's `.plugins/` cache subtree
+   * to be evicted and re-downloaded — a reload of changed upstream source. Cache-first otherwise:
+   * a programmatic loader gets the cached copy and stays offline-tolerant.
    */
-  loadPlugin(specifier: string, prompt?: PromptFn): Promise<MatbotPlugin>;
+  loadPlugin(specifier: string, prompt?: PromptFn, refresh?: boolean): Promise<MatbotPlugin>;
 
   /**
    * Hot-unload a plugin by specifier, removing its tools, hooks, and system context contributions.
@@ -488,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>;
@@ -438,11 +443,11 @@ export interface KnowledgeIndex {
 
 // ── Tools ─────────────────────────────────────────────────────────────────────
 
-export type ToolEvent =
+export type ToolEvent<Result = unknown> =
   | { type: 'stdout';   chunk: string }
   | { type: 'stderr';   chunk: string }
   | { type: 'progress'; pct: number; message?: string }
-  | { type: 'result';   value: unknown }
+  | { type: 'result';   value: Result }
   | { type: 'file';     handle: FileHandle }
   // A durable, LLM-invisible annotation the tool emits as it runs (a link, a status, a trace of a
   // side-effect). Persisted as a `marker`-role message; elided from provider submission like any
@@ -451,6 +456,76 @@ export type ToolEvent =
   | { type: 'marker';   creator: string; data: unknown }
   | { type: 'error';    message: string; code?: number; stdout?: string; stderr?: string };
 
+/**
+ * Per-tool result-type registry: maps a tool's `name` to the type of the `value` it yields in its
+ * `result` event. Augment it exactly like {@link MarkerData} / `MatbotServices`, so a caller gets the
+ * concrete result type back from {@link invokeTool} + `toolResult` instead of `unknown`:
+ *
+ *   declare module '@matatbread/matbot-plugin-api' {
+ *     interface ToolResults { find_fact: string[] | null }
+ *   }
+ *
+ * The tool name is the discriminator: `invokeTool(machine, 'find_fact', …)` is typed
+ * `AsyncIterable<ToolEvent<string[] | null>>`, so `toolResult(…)` resolves to `string[] | null`. A
+ * 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 {}
+
+/**
+ * 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
  * implementation — readline in the CLI, an SSE round-trip in the web frontend. This is
@@ -488,8 +563,10 @@ export interface ToolContext {
   files?:      FileStore;
   /** Prompt the user for input. The host provides a readline or form implementation. */
   prompt:      PromptFn;
-  /** Hot-load a plugin by specifier without restarting the process. Returns the loaded plugin. */
-  loadPlugin(specifier: string): Promise<MatbotPlugin>;
+  /** Hot-load a plugin by specifier without restarting the process. Returns the loaded plugin.
+   *  `refresh` (default false) forces a remote (github/http) plugin to be re-downloaded rather than
+   *  re-loaded from its `.plugins/` cache — pass true to pick up changed upstream source. */
+  loadPlugin(specifier: string, refresh?: boolean): Promise<MatbotPlugin>;
   /**
    * Hot-unload a plugin by specifier, removing its tools, hooks, and system context contributions.
    * Resolves `true` if a plugin was actually resident and unloaded, `false` if there was nothing
@@ -498,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;
 }
 
@@ -649,6 +734,7 @@ export type PipelineEvent =
   | { type: 'tool:start';     callId: string; name: string; input: unknown; traceId: string }
   | { type: 'tool:stdout';    callId: string; chunk: string;  traceId: string }
   | { type: 'tool:stderr';    callId: string; chunk: string;  traceId: string }
+  | { type: 'tool:progress';  callId: string; pct: number; message?: string; traceId: string }
   | { type: 'tool:end';       callId: string; result: unknown; isError: boolean; traceId: string }
   | { type: 'file';           handle: FileHandle;     traceId: string }
   | ({ type: 'usage';         traceId: string } & Usage)