smelt.process¶

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

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

Run subprocesses and manage contained shell jobs. Background jobs are non-blocking; foreground jobs stream bounded output and wait for completion.

smelt.process.detach_foreground¶

fun(): boolean

Stop following the most recently started detachable foreground job and leave the same supervisor-owned job running in the background. Returns true when a detach request was sent.

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 supervised shell job with id. Schedules containment termination asynchronously; no-op when no host is installed.

smelt.process.list¶

fun(): table

Return running shell jobs as rows of { id, pid?, command, elapsed_secs }. id is an opaque stable job ID; pid is present when the OS exposes the top-level child PID.

smelt.process.output¶

fun(id: string): table

Return the bounded output snapshot for supervised job id without draining it. Returns { text, running, exit_code?, termination?, elapsed_secs, pid? }, or an empty table when the job does not exist or its completed snapshot has been evicted.

smelt.process.read_output¶

fun(id: string): table

Drain bounded output from supervised job id. Returns { text, running, exit_code?, termination?, elapsed_secs, pid? }, or an empty table when the job does not exist or its completed snapshot has been evicted.

smelt.process.run¶

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. Yields the calling coroutine until the child exits; must be called from inside smelt.spawn(fn) or a tool.execute. opts accepts cwd, env, timeout_secs, stdin, and max_output_bytes (default 100 KB, maximum 32 MB). 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, background_on_timeout: boolean): nil

Run command as a contained job with a timeout_ms deadline, streaming bounded output into live tool call call_id and resolving task task_id with { content, is_error, timed_out, background_id?, termination? } (or { __cancelled = true } if cancelled). When background_on_timeout is true, the same supervised job keeps running in the background.

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" }), and 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 contained background shell job. Yields while smelt selects and verifies the containment backend, then returns an opaque job ID. Must be called from inside smelt.spawn(fn) or a tool.execute.

smelt.process.stop¶

fun(id: string): { text: string }?, string?

Stop the supervised shell job id and return its bounded output. Yields until containment termination and removes the completed job. Returns ({ text }, nil) on success or (nil, err) when the job does not exist or cannot stop.