smelt.process¶

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

Run, spawn, list, and kill processes against the ProcessRegistry. spawned processes are non-blocking; run processes wait for completion.

smelt.process.get_default_shell¶

fun(): any

Return the current default shell as { program, args }, or nil when the built-in sh -c default is in effect.

smelt.process.kill¶

fun(id: string): nil

Stop the registered process with id. Schedules the kill asynchronously; no-op when no host is installed.

smelt.process.list¶

fun(): table

Return the registry of running processes as rows of { id, command, elapsed_secs }.

smelt.process.read_output¶

fun(id: string): table

Drain buffered output from the registered process id. Returns { text, running, exit_code? }, or an empty table when no such process exists.

smelt.process.run¶

fun(cmd: string, args: string[]?, opts: table?): table?, string?

Run cmd with args synchronously. opts accepts cwd, env, timeout_secs, and stdin. Returns ({ stdout, stderr, exit_code, timed_out }, nil) or (nil, err_string) on failure.

smelt.process.run_async¶

fun(cmd: string, args: string[]?, opts: table?): { stdout: string, stderr: string, exit_code: integer, timed_out: boolean }?, string?

Run cmd with args off the main thread. Must be called from inside smelt.spawn(fn) or a tool.execute. opts accepts cwd, env, timeout_secs, stdin. Returns ({ stdout, stderr, exit_code, timed_out }, nil) on success or (nil, err) on spawn failure. If the calling coroutine is cancelled (e.g. by smelt.task.timeout or by :remove() on the parent spawn), the child process is killed (SIGTERM to its process group) and smelt.task.external raises cancelled — same shape as every other yielding API.

smelt.process.run_streaming¶

fun(task_id: integer, call_id: string, command: string, timeout_ms: integer): nil

Run command with a timeout_ms deadline, streaming each output line into the live tool call call_id and resolving task task_id with { content, is_error, timed_out } (or { __cancelled = true } if cancelled).

smelt.process.set_default_shell¶

fun(opts: table?): nil

Override the wrapping shell used by spawn_bg and run_streaming for string-form commands. opts.program is the executable (e.g. "/bin/zsh"); opts.args is the leading argv (e.g. { "-fc" }) — the command string is appended after these. Pass nil (no args) to revert to the default sh -c.

smelt.process.spawn_bg¶

fun(command: string): string

Spawn command as a background child registered with the process registry. The wrapping shell defaults to sh -c and can be overridden process-wide via smelt.process.set_default_shell. Returns the process id; raises if no host is installed or the spawn fails.