@matatbread/matbot-plugin-api 0.4.14 → 0.4.15

package/package.json

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

package/src/index.ts

@@ -9,7 +9,7 @@
  */
 
 export type * from './types.js';
-export { CONFIRM_YES, CONFIRM_NO, optionValue, optionLabel, isTruncatedToolResult, renderToolCheck, renderToolCheckOmitted } from './types.js';
+export { CONFIRM_YES, CONFIRM_NO, optionValue, optionLabel, isTruncatedToolResult, renderToolCheck, renderToolCheckOmitted, FUNCTION_TIMEOUT } from './types.js';
 
 export * from './base64.js';
 export * from './bytes.js';

package/src/invoke-tool.ts

@@ -68,7 +68,8 @@ export type InvokeToolOptions =
  * 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
+ * Throws synchronously if no tool is registered under `name`, or if `opts.signal` has already aborted.
+ * 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.
  */
@@ -80,6 +81,9 @@ export function invokeTool<K extends string, const P>(
 ): AsyncIterable<ToolEvent<ToolResultFor<K, P>>> {
   const tool = machine.tools.resolve(name);
   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.
+  if (opts.signal.aborted) throw new Error(`Tool "${name}" was not started: the call was cancelled.`);
 
   const prompt = opts.prompt ?? rejectingPrompt;
   const ctx: ToolContext = {

package/src/plugin.ts

@@ -2,7 +2,7 @@ import type {
   FileStore, MediaStore, Principal, Vault, Message, ModelParameters,
   ProviderAdapter, ProviderConfig, ProviderRegistry, Tool, ToolRegistry, FrontendInfo,
   Store, Session, SystemContextRegistry, KnowledgeIndex, PromptFn, SessionRunner, Usage, HookRegistrar,
-  TypeScriptStripper, ToolTypeIndex, ToolPresenter, SteeringPolicy, UserContent, PermissionGate,
+  TypeScriptStripper, FunctionRunner, ToolTypeIndex, ToolPresenter, SteeringPolicy, UserContent, PermissionGate,
 } from './types.js';
 import type { Notifications, Notifier } from './notify.js';
 
@@ -191,6 +191,10 @@ export interface MatbotServices {
    *  `file-ref` degrades to the converters' `[Attached file: x]` note. A text-only deployment is
    *  unaffected either way. See {@link MediaStore}. */
   readonly MediaStore?: MediaStore | undefined;
+  /** Optional bound on how long model-authored code may run without awaiting. The node host registers
+   *  one; absent ⇒ such code runs unbounded, as it must where synchronous code cannot be interrupted.
+   *  See {@link FunctionRunner}. */
+  readonly FunctionRunner?: FunctionRunner | undefined;
 }
 
 /** The assembled machine: registry services wired to the fixed runtime — what `setup()` receives. */

package/src/types/typescript.ts

@@ -17,6 +17,26 @@ export interface TypeScriptStripper {
   strip(source: string): string | Promise<string>;
 }
 
+/**
+ * Optional, host-supplied: compiles already-stripped JavaScript into an async function whose SYNCHRONOUS
+ * execution is bounded. Model-authored code (a `tool_function` body) runs on the one event loop every
+ * session, frontend and schedule shares, so a loop that never awaits freezes all of them — and nothing
+ * in-process can stop it, an abort signal included, since stopping needs the loop to yield. Only the
+ * stretches between awaits are bounded: a body waiting on a slow tool call is not doing work.
+ *
+ * Absent ⇒ a consumer compiles with `new AsyncFunction` and runs unbounded, which is all a platform with
+ * no way to interrupt synchronous code (the browser) can do. An embedder may register its own.
+ */
+export interface FunctionRunner {
+  /** Compile `body` as the body of an async function taking `params`. Throws on a syntax error. A call
+   *  stopped at the limit rejects with an error whose `code` is {@link FUNCTION_TIMEOUT}. */
+  compile(params: readonly string[], body: string): (...args: unknown[]) => Promise<unknown>;
+}
+
+/** The `code` on the error a {@link FunctionRunner} rejects with when it stops a run at its limit, so a
+ *  consumer can tell a stopped runaway from an ordinary failure without matching message text. */
+export const FUNCTION_TIMEOUT = 'FUNCTION_TIMEOUT';
+
 /**
  * One finding from {@link ToolTypeIndex.check} — the record, not a rendering of it.
  *