@matatbread/matbot-plugin-api 0.2.4 → 0.2.5

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.2.4",
+  "version": "0.2.5",
   "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, ToolResultOf, 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>(
+  machine: MatbotMachine,
+  name:    K,
+  params:  unknown,
+  opts:    InvokeToolOptions,
+): AsyncIterable<ToolEvent<ToolResultOf<K>>> {
+  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<ToolResultOf<K>>>;
+}
+
+/**
+ * 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.

package/src/types.ts

@@ -438,11 +438,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 +451,26 @@ 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.
+ */
+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;
+
 /**
  * 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 +508,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
@@ -649,6 +671,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)