Skip to content

smelt.tools

Tier: Host — Available in every runtime, including headless mode.

Register, unregister, and resolve plugin tools for the engine.

smelt.tools.call

fun(name: string, args: table?, parent_call_id: string?): { content: string, is_error: boolean?, metadata: table? }

Call another tool from within execute. Pass parent_call_id so streamed output groups under the parent invocation. Returns { content, is_error, metadata? }.

smelt.tools.default_summary

fun(args: table?): string

Best-effort one-liner summary of a tool call's arguments. Picks a sensible field from args in priority order: questions (returns "N question(s)"), pattern (optionally suffixed with in <display path>), then the first non-empty command | file_path | notebook_path | path | url | query | name | id. Returns "" if nothing matches. Used as the default summary field on tools registered via smelt.tools.register.

smelt.tools.list

fun(): table

Return the names of every registered plugin tool, sorted.

smelt.tools.middleware

fun(name: string, mw: table): smelt.Reg

Types: smelt.Reg

Register middleware for tool name. Pass "" (empty string) as name to match every tool. mw is a table of { before = fn?, after = fn? }:

  • before(args, ctx) runs synchronously before the tool executes. Return a table to replace args; return { deny = true, reason = "..." } to short-circuit with an error result. Any other return is no-op.
  • after(args, ctx, result) runs after the tool completes and may return { content, is_error } to replace the result. NOTE: after currently only fires for tools that complete synchronously; yielding tools (most builtins) skip it until the task-runtime path is wired.

Hooks fire in registration order; an earlier hook's replacement is visible to later hooks. Returns a Reg whose :remove() drops this middleware.

smelt.tools.register

fun(def: smelt.tools.ToolDef): smelt.Reg

Types: smelt.tools.ToolDef, smelt.Reg

Register a plugin tool. See smelt.tools.ToolDef for every supported field; only name and execute are required. Returns a Reg whose :remove() unregisters the tool.

smelt.tools.resolve

fun(request_id: integer, call_id: string, result: table): nil

Resolve the pending tool call call_id from request request_id with { content, is_error }. Sends a ToolResult back to the engine.

smelt.tools.unregister

fun(name: string): boolean

Unregister a previously-registered tool by name. Returns true if a tool was removed, false otherwise.