@matatbread/matbot-plugin-api 0.4.18 → 0.4.19

package/package.json

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

package/src/hooks.ts

@@ -1,5 +1,5 @@
 import type {
-  Hook, HookPoint, HookRegistrar, Message, MessageContent, Session, DeferredScreen,
+  Hook, HookPoint, HookRegistrar, Message, MessageContent, Session, DeferredScreen, TurnToolSource,
   ScreenContext, ContributeContext, ToolCallContext, ToolCallResult, ToolResultContext, FollowupContext,
 } from './types.js';
 import { foldOntoUserTurn, createMessage } from './session.js';
@@ -120,12 +120,13 @@ export class HookRegistry implements HookRegistrar {
 
   // screen folds across hooks: each sees the session as shaped so far, accumulates ephemeral, and
   // the first `abort` short-circuits (the partial session is returned so the caller can persist it).
-  async runScreen(ctx: Omit<ScreenContext, 'removeHook'>): Promise<{ session: Session; ephemeral: MessageContent[]; durable: MessageContent[]; markers: MessageContent[]; deferred: DeferredScreen[]; abort?: string }> {
+  async runScreen(ctx: Omit<ScreenContext, 'removeHook'>): Promise<{ session: Session; ephemeral: MessageContent[]; durable: MessageContent[]; markers: MessageContent[]; deferred: DeferredScreen[]; tools: TurnToolSource[]; abort?: string }> {
     let session = ctx.session;
     const ephemeral: MessageContent[] = [];
     // Raced verdicts handed back by hooks: the runner polls each without gating the turn (see
     // DeferredScreen). Usually zero or one; an array so several racing hooks compose.
     const deferred: DeferredScreen[] = [];
+    const tools: TurnToolSource[] = [];
     // Handler-returned markers: appended to the session here (so they persist) and accumulated so the
     // runner can also emit them live — keeping a live draw and a reload identical.
     const handlerMarkers: MessageContent[] = [];
@@ -155,13 +156,14 @@ export class HookRegistry implements HookRegistrar {
       if (r.durable && r.durable.length) foldDurable(r.durable);
       if (r.markers && r.markers.length) appendMarkers(r.markers);
       if (r.deferred)                    deferred.push(r.deferred);
+      if (r.tools)                       tools.push(r.tools);
       if (r.abort) {
         const drained = this.drainFailureMarkers(session);
-        return { session: drained.session, ephemeral, durable, markers: [...handlerMarkers, ...drained.markers], deferred, abort: r.abort };
+        return { session: drained.session, ephemeral, durable, markers: [...handlerMarkers, ...drained.markers], deferred, tools, abort: r.abort };
       }
     }
     const drained = this.drainFailureMarkers(session);
-    return { session: drained.session, ephemeral, durable, markers: [...handlerMarkers, ...drained.markers], deferred };
+    return { session: drained.session, ephemeral, durable, markers: [...handlerMarkers, ...drained.markers], deferred, tools };
   }
 
   // contribute folds the outgoing array through each hook — a pure transform pipeline; the stored

package/src/invoke-tool.ts

@@ -58,11 +58,11 @@ export function bindGate(
  */
 export type InvokeToolOptions =
   Pick<ToolContext, 'session' | 'signal'>
-  & Partial<Pick<ToolContext, 'prompt' | 'provider' | 'callId'>>;
+  & Partial<Pick<ToolContext, 'prompt' | 'provider' | 'callId' | 'turnTools'>>;
 
 /**
  * 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.
+ * machine's tool registry (else the turn's own tools, when `opts` carries them), 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,
@@ -79,7 +79,8 @@ export function invokeTool<K extends string, const P>(
   params:  P,
   opts:    InvokeToolOptions,
 ): AsyncIterable<ToolEvent<ToolResultFor<K, P>>> {
-  const tool = machine.tools.resolve(name);
+  // The registry first, as the runner does: a turn tool never shadows a registered one.
+  const tool = machine.tools.resolve(name) ?? opts.turnTools?.get(name) ?? null;
   if (tool === null) throw new Error(`Tool "${name}" is not registered`);
   // A call whose turn was cancelled never starts. Otherwise a composed body looping over `await tool.x()`
   // goes on calling tools after the abort, each callee deciding for itself whether to honour the signal.
@@ -98,6 +99,7 @@ export function invokeTool<K extends string, const P>(
     // non-interactive case the request's `fallback` exists to answer.
     ...bindGate(machine.PermissionGate, name, opts.prompt),
     ...(opts.provider      !== undefined ? { provider:   opts.provider      } : {}),
+    ...(opts.turnTools     !== undefined ? { turnTools:  opts.turnTools     } : {}),
     ...(machine.workdir    !== undefined ? { workdir:    machine.workdir    } : {}),
     ...(machine.configPath !== undefined ? { configPath: machine.configPath } : {}),
     ...(machine.files      !== undefined ? { files:      machine.files      } : {}),

package/src/types/hooks.ts

@@ -24,6 +24,7 @@ export interface RunConfig {
  *               doesn't bust the cached prefix), `durable` context (the persisted, visible twin of
  *               `ephemeral`: folded onto this turn's user message as `origin: 'robo'` blocks and
  *               carried live as a `robo-user` event, so it survives into the next turn's history),
+ *               turn-scoped `tools` (a source the runner asks each round — see {@link TurnToolSource}),
  *               or `abort`. Mix freely. This is where the durable-vs-ephemeral choice for incoming
  *               user input lives.
  *   contribute  runner, before *every* provider call. Ephemeral by construction (it re-fires, so a
@@ -123,9 +124,28 @@ export interface ScreenResult {
    * you just want to annotate (e.g. a fired trigger's silent tool recording what it did).
    */
   markers?:   MessageContent[];
+  /** Tools for this turn only — see {@link TurnToolSource}. */
+  tools?:     TurnToolSource;
   abort?:     string;
 }
 
+/**
+ * Tools that exist for one turn of one session and nowhere else: advertised to the model, runnable by
+ * it, and runnable by any tool in the turn that forwards its context ({@link ToolContext.turnTools}) —
+ * but never registered, so no other session, no sessionless door (`POST /tools/:name`), the type index
+ * and the tool presenter never see them. The shape a session-scoped `tool_function` needs.
+ *
+ * A SOURCE rather than a list because the runner asks it at the top of EVERY round, with the session as
+ * it then stands: a turn's own tool calls change the session (a marker recording a definition lands at
+ * the end of its round), and a tool defined in round 2 must be callable in round 3, not next turn. So a
+ * source is called often and should cache whatever is costly to build.
+ *
+ * A turn tool may not shadow a registered one: a name the registry holds is dropped, with a warning, and
+ * the registered tool keeps it. Shadowing a tool by registration is a gated decision (`tools.overwrite`),
+ * and a hook must not be a way round it. A source wanting the model to hear about a clash says so itself.
+ */
+export type TurnToolSource = (session: Session) => readonly Tool[] | Promise<readonly Tool[]>;
+
 export interface ContributeContext {
   readonly outgoing: readonly Message[];
   readonly session:  Session;

package/src/types/tools.ts

@@ -219,6 +219,13 @@ export interface ToolContext {
    * reach. Prefer it over `services.SessionAppender`; absent ⇒ the machine's is the right one.
    */
   appender?:   SessionAppender;
+  /**
+   * The tools that exist for this turn only ({@link TurnToolSource}), as the runner resolved them for
+   * this round. Never in the registry, so a tool calling another by name finds them only through here —
+   * which {@link invokeTool} does when handed this context, the way a forwarding tool already should.
+   * Absent ⇒ none, or a door that runs no turn (`POST /tools/:name`).
+   */
+  turnTools?:  ReadonlyMap<string, Tool>;
   /** Prompt the user for input. The host provides a readline or form implementation. */
   prompt:      PromptFn;
   /**