smelt.tools¶

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

Classification: Supported - Primary alpha facade for user config and plugins.

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.patch¶

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

Types: smelt.Reg

Patch metadata for an already-registered tool without replacing its handler. Supports description and parameters. Returns a Reg whose :remove() restores the previous metadata.

smelt.tools.path_summary¶

fun(path: string, ctx?: { final: boolean }, opts?: { prefix: string?, suffix: string? }): string

Format a path for a tool summary. During argument streaming, paths that may collapse to the current working directory or home directory return an empty string; once final, all paths use smelt.path.display.

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.unregister¶

fun(name: string): boolean

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