Process
A Process is an opaque handle, with no constructor, fields, equality or JSON encoding; IO.inspect prints <Process>. A program can start other programs unless it runs with --deny-run (or --sandbox, or agentica run --deny-run). Then every start returns an error that begins with denied: --deny-run, in every task, and extern blocks are refused as with --deny-native. The flag goes before the source file; later arguments reach System.args. Under agentica test, a step program cannot start a program under test:
agentica --deny-run tool.agc- Timeouts are positive milliseconds and include the wait for the handle’s lock. A timeout during stream I/O kills and closes the program; a timeout while waiting for the lock keeps it; a timed-out wait for exit does not terminate it.
- Arguments go to the program as they are. No shell is involved. Every waiting function takes a timeout in milliseconds; the spawn functions take theirs in Process.Options, 30000 by default.
- A program you start belongs to the task that started it and stops when that task ends, however it ends. Programs still running stop when yours ends. Task.spawn_owning gives one to a new task.
Process.Options #
Process.Options(timeout_ms: Int = 30000, chdir: String = ".", env: Map[String, String] = {}, out: String = "", err: String = "", pgroup: Bool = false, pty: Bool = false)The options of Process.spawn, Process.spawn_captured and Process.spawn_channel, their last argument, which defaults to Process.Options(). Give only the fields you need: Process.Options(chdir: "build", err: "err.txt"). The fields are Ruby’s spawn options (chdir:, out:, err:, pgroup:), plus timeout_ms, env (Ruby passes the environment as the first argument) and pty. A timeout or a folder in the place of the options is CHECK-TYPE-MISMATCH.
Process.spawn #
Process.spawn(command: String, args: List[String], options: Process.Options = Process.Options()) -> Result[Process]Starts a program with your program’s environment, plus the variables of env.
- The program starts in the folder
chdir(".", the default, is the current one). An emptychdiror one with a NUL byte giveserror("process: chdir must be nonempty and cannot contain NUL"), and one that is not a foldererror("process: directory is unavailable"). The command is found from the current folder, not fromchdir. - A name with no
/("echo") is looked up in eachPATHfolder, in order. The current folder is never added and empty entries are skipped; a relative entry such asbinis looked up under the current folder, as in the shell. - A command with
/is a path (on Windows\and a drive such asC:too), relative to the current folder: run a local program as"./tool". envsets variables for that program only, on top of a copy of your environment: a pair replaces the variable of the same name (Windows ignores case, also of letters likeÄ, and a map with two names that differ only in case is anerror), and an empty value is a value. Your own environment does not change, and aPATHinenvdoes not change how the command is found: yourPATHresolves it, and only the program sees the new one. An empty name, a name with=, or a NUL byte in a name or value is anerror, and so areAGENTICA_CHANNEL,AGENTICA_VM_METRICS,AGENTICA_VM_METRICS_FILEandUV_USE_IO_URING, which the VM owns.- A name not found, or one that names a directory, gives
error("process: executable is unavailable"). A file that cannot run (no execute permission) is an error fromspawn. - An empty command, or a NUL byte in the command or an argument, gives
error("process: command must be nonempty and arguments cannot contain NUL"). outanderr, when not empty, are files that get the program’s standard output and error, with no shell and without the 1 MiB limit of a read or a captured stream (Ruby’sspawn(cmd, out: path)). Each is created or truncated, on Unix with mode 0666 less where the umask clears bits, asFile.write_textand a shell’s>make it; a file that exists keeps its mode. A relative path starts at the current folder.outanderrnaming one file share it, as> file 2>&1does. A stream sent to a file is not readable:read_linegives the end of output at once, and nothing is forwarded to your standard error. A folder, the descriptor behind your standard output or error (/proc/self/fd/5), one of the program’s own internal pipes, or on Windows a path starting\\.\or\\?\giveserror("process: out does not refer to a regular file")(orerr), as theFilecalls refuse them. A file that cannot be opened (a missing parent folder, no permission) gives an error that starts withprocess: cannot open the out file(orerr) and names the system error. Either way no program starts. A NUL byte giveserror("process: out and err cannot contain NUL"), and--deny-fsturns them off. The files are opened just before the start, so a start that then fails (a file that cannot run) may leave them created or truncated, as a shell’s>does. OnlyProcess.spawntakes them:spawn_capturedandspawn_channelgiveerror("process: out and err need Process.spawn").pgroup: true(also forspawn_capturedandspawn_channel) starts the program in its own process group, as a new session on Linux and macOS. Unlike Ruby’spgroup: true, the new session leaves the program with no controlling terminal, so a prompt on/dev/ttyfails. As for any group of its own, a Ctrl-C or hangup of the terminal reaches it only through your program’s stop of its children, and aSIGKILLof your program leaves the group running. A stop of the program while it runs (close, a stream timeout, the end of the run, a signal to your program) signals the whole group, so the programs it started end with it: a compiler driver and itscc1, orshand itssleep. After aSIGTERMthe group getsSIGKILLwhen the grace ends, even if the program itself has already exited. A descendant left behind by a program that exited on its own, before any stop, is not stopped. A program started withoutpgroupis stopped alone, and its own children can outlive it. On Windowspgroupchanges nothing: the program is stopped alone.pty: trueruns the program on a pseudo-terminal, as Ruby’sPTY.spawndoes, so interactive programs work: a password prompt (ssh,sudo), a REPL, an editor or a full-screen program. See Process on a pty.- Windows: only
.exeand.comrun (PATHEXTis not read; a suffixless name tries.exefirst; usecmd.exeby name for a shell). These fail: a name ending in a dot, a space,.cmdor.bat; one starting with\\?\or\\.\; a:that is not a drive.
def main() -> Void
p = Process.spawn("echo", ["hello"]).unwrap!
puts(Process.read_line(p, 1000))
puts(Process.wait(p, 1000))
endok("hello")
ok(0)def main() -> Void
p = Process.spawn("sh", ["-c", "echo $GREETING"], Process.Options(env: {"GREETING": "hello"})).unwrap!
puts(Process.read_line(p, 1000))
endok("hello")def main() -> Void
options = Process.Options(out: "out.txt", err: "err.txt")
p = Process.spawn("sh", ["-c", "echo report; echo warning >&2"], options).unwrap!
puts(Process.wait(p, 1000))
puts(File.read_text("out.txt"))
endok(0)
ok("report\n")Process.send and Process.send_bytes #
Process.send(process: Process, text: String, timeout_ms: Int) -> Result[Void]
Process.send_bytes(process: Process, bytes: Bytes, timeout_ms: Int) -> Result[Void]Write to the program’s standard input, and flush. A send takes at most 1048576 bytes, UTF-8 text or a Bytes; invalid data consumes nothing.
def main() -> Void
p = Process.spawn("cat", []).unwrap!
_ = Process.send(p, "ping\n", 1000)
puts(Process.read_line(p, 1000))
Process.close(p)
endok("ping")Process.read_line and Process.read_bytes #
Process.read_line(process: Process, timeout_ms: Int) -> Result[String]
Process.read_bytes(process: Process, count: Int, timeout_ms: Int) -> Result[Bytes]Read from the program’s standard output.
read_lineremoves the line ending (LF or CRLF), takes at most 1 MiB and decodes strictly. At the end of output it gives an error, and a line over 1 MiB closes the program.read_bytestakescountfrom 0 to 1048576, waits for that many bytes or the end of output, and gives them asBytes. At the end of output they are empty.
Process.poll_line #
Process.poll_line(process: Process, timeout_ms: Int) -> Result[String]Reads a line as read_line does, but a timeout keeps the program and what it has written of the next line: the error has the kind process.timeout, and a later read gets the whole line. At the end of output the kind is process.eof. So a loop can do other work between polls.
def main() -> Void
p = Process.spawn("sh", ["-c", "printf 'wor'; sleep 1; echo king"]).unwrap!
case Process.poll_line(p, 100)
ok(line) -> puts(line)
error(e) -> puts(e.kind)
end
puts(Process.poll_line(p, 5000))
endprocess.timeout
ok("working")Process.close_stdin #
Process.close_stdin(process: Process, timeout_ms: Int) -> Result[Void]Closes the program’s input, so it sees the end of input. It flushes first, and closing twice is fine.
def main() -> Void
p = Process.spawn("wc", ["-l"]).unwrap!
_ = Process.send(p, "a\nb\n", 1000)
_ = Process.close_stdin(p, 1000)
puts(Process.read_line(p, 1000).unwrap!.strip)
end2Process.wait #
Process.wait(process: Process, timeout_ms: Int) -> Result[Int]Gives the exit code, nonzero codes included (false gives ok(1)), and can be repeated. A timeout leaves the program running. Unread output stays readable after wait. A program blocks when its standard output pipe is full, so read it in a task while you send or wait.
Process.close #
Process.close(process: Process) -> VoidStops the program if it still runs and frees it. Closing twice is fine. A running program is killed, the call waits for it to exit (other tasks run meanwhile) and closes the ports it owns; a timeout closes the program too, but does not wait for it. A failed explicit cleanup is RUNTIME-PROCESS-CLOSE at the call.
Return from main, System.exit, a diagnostic, a task failure, step exhaustion and an external interruption clean up the programs started directly; their descendants are covered only with pgroup or Process.spawn_group, while the program runs. On Windows a stop is always immediate (no SIGTERM grace). Where libuv can assign its job object, the direct children of the VM die when the VM ends, and a child that is itself an Agentica program stops its own children the same way.
For a Process.spawn program, the closing task waits up to one second for it to end; other tasks keep running.
Its standard error goes to yours, unless started with Process.spawn_captured or an err file. It goes through your program’s stderr buffer: while nobody reads your stderr, the child and Process.wait on it wait, and other tasks keep running.
Process on a pty #
With pty: true the program starts in a new session whose controlling terminal is a new pseudo-terminal of 24 rows and 80 columns, which is also its standard input, output and error, so standard error comes mixed into the output. send and send_bytes type into the terminal, and read_line, read_bytes, poll_line and read_available read what it shows. As for spawn_captured, the output is read all the time into a buffer of 1 MiB, so the program never blocks on a full terminal; past 1 MiB of unread output the rest is dropped and every read gives error("process: output exceeds 1048576 bytes"), close sends SIGTERM and then SIGKILL, and as with pgroup: true a stop signals the whole group. The output ends when the program and every program it started with the terminal have exited.
- A terminal echoes what you send, unless the program turned echo off (a password prompt does), and ends lines with
\r\n;read_linestrips the\r. A prompt has no newline yet: read it withread_bytesorread_available. Ctrl-C is"\x03"and Ctrl-D (the end of input at the start of a line) is"\x04";close_stdindoes not end the program’s input. - The program gets the variables of your environment, so give it
TERMinenvwhen it needs one. spawn_capturedandspawn_channelwithpty, orptywithoutorerr, giveerror("process: pty needs Process.spawn without out and err"). There is no terminal mode API. Linux and macOS only: elsewhereptygiveserror("process: pty is not supported on this system")with kindprocess.failed.
def main() -> Void
p = Process.spawn(
"sh",
["-c", "stty -echo; printf 'name: '; read name; echo hi $name"],
Process.Options(pty: true),
).unwrap!
puts(Process.read_bytes(p, 6, 1000).unwrap!.size)
Process.send(p, "Ada\n", 1000).unwrap!
puts(Process.read_line(p, 1000))
end6
ok("hi Ada")Process.resize #
Process.resize(process: Process, rows: Int, cols: Int) -> Result[Void]Sets the size of a pty: true program’s terminal, as a terminal window does when it is resized: the program gets SIGWINCH, and stty size shows the new size. Rows and columns are 1 to 65535, else error("process: rows and cols must be 1..65535"). A program without a pty gives error("process: the child has no pty") with kind process.failed, and a closed one error("process: process is closed").
Process.signal and Process.signal_group #
Process.signal(process: Process, signal: System.Signal) -> Result[Void]
Process.signal_group(process: Process, signal: System.Signal) -> Result[Void]Process.signal sends a signal (System.Signal, see System.subscribe) to the program; signal_group sends it to the process group the program leads, so the programs it started get it too. A signal the program does not handle ends it, and Process.wait then gives 128 + the signal’s number (143 for Term). Neither call waits for the program to end: follow it with Process.wait and a deadline, and Process.close when the program is late.
- A closed program returns
error("process: process is closed"). A program that has exited returnserror("process: the child has exited")with kindprocess.failed: its pid may already belong to another process. signal_groupneeds a program that leads its own group, started withProcess.spawn_grouporpgroup: true; any other returnserror("process: the child does not lead a process group")with kindprocess.failed.- On Windows both return
error("signal: not supported on this system")with kindsystem.signal.
Process.spawn_group #
Process.spawn_group(command: String, args: List[String], dir: String = ".", timeout_ms: Int = 30000) -> Result[Process]Starts a program in a new session, so it leads its own process group, as Python’s Popen(start_new_session=True). It shares your program’s standard input, output and error: its output goes where yours goes (a terminal, a container’s log), nothing can fill up, and read_line, read_bytes, read_available, output, send, send_bytes and close_stdin return error("process: the child uses the program's stdin, stdout and stderr") with kind process.failed. dir is where it starts; the command is found from your program’s folder, so give an absolute path when dir is not ".". --deny-run turns it off, and on Windows it returns error("process: process groups are not supported on this system") with kind system.signal.
The new session leaves the child without a controlling terminal: it has descriptors 0 to 2, but opening /dev/tty fails (ENXIO), so a program that needs one (an ssh password prompt, less, sudo, an editor) cannot use it, and there is no terminal job control. Ctrl-C reaches it only through the VM’s stop path, which sends SIGKILL to the group. The child reads the same standard input as your program, so a pending IO.gets splits the input with it, and your buffered output may appear after the child’s: flush before spawning.
Process.close, the end of the task that owns it and the end of the run send SIGKILL to the whole group while the program runs. This is the start of a container entrypoint: it stops the program with signal_group, waits with a deadline, and kills the group when it is late.
def main() -> Void
signals = System.subscribe([System.Signal.Term, System.Signal.Int]).unwrap!
child = Process.spawn_group("/usr/bin/runner", ["--once"]).unwrap!
case signals.recv(3600000)
ok(signal) ->
_ = Process.signal_group(child, signal)
if !Process.wait(child, 30000).ok?
Process.close(child)
end
System.exit(128 + System.signal_number(signal))
error(_) -> nil
end
endProcess.spawn_captured #
Process.spawn_captured(command: String, args: List[String], options: Process.Options = Process.Options()) -> Result[Process]Starts a program as Process.spawn does, in the folder chdir, and keeps its output.
- Standard output and error are read all the time into buffers of 1 MiB each, so the program never blocks on a full pipe and its standard error is never printed.
read_lineandread_bytesread standard output as usual. - Past 1 MiB of waiting standard output, or of standard error, the rest is dropped and every read of standard output gives
error("process: output exceeds 1048576 bytes").Process.read_bytes(p, 0, timeout)gives it at once, to check without waiting. closesendsSIGTERMand kills the program one second later if it still runs, so an Agentica program can stop its own children.closeand a timeout never wait, and at the end of a run a captured program gets about one second, while aProcess.spawnprogram is killed at once. Windows has noSIGTERM: the program ends at once, and where libuv can assign its job object, programs the VM started die when the VM ends (other descendants are not covered).
Process.output #
Process.output(process: Process, timeout_ms: Int) -> Result[Process.Output]Waits until a captured program has closed its standard output and error, then gives Process.Output(stdout: String, stderr: String, truncated: Bool): stdout is what you have not read yet, stderr all of it, truncated says whether output was dropped (invalid UTF-8 in stderr becomes U+FFFD). It consumes nothing, so call it again if needed. A timeout is error("process: operation timed out") and keeps the program. A Process.spawn program gives error("process: output is not captured").
def main() -> Void
p = Process.spawn_captured("sh", ["-c", "echo one; echo two; echo oops >&2"]).unwrap!
puts(Process.read_line(p, 1000))
out = Process.output(p, 1000).unwrap!
puts(out.stdout)
puts(out.stderr)
puts(out.truncated)
Process.close(p)
endok("one")
two
oops
falseProcess.spawn_channel #
Process.spawn_channel(command: String, args: List[String], options: Process.Options = Process.Options()) -> Result[Process]Like Process.spawn_captured, and also opens a private channel to the program, apart from its standard input, output and error. It carries lines of text both ways, on Linux, macOS and Windows: a pipe each way, so the program reads descriptor 3, writes descriptor 4 and sees AGENTICA_CHANNEL=3,4.
Process.spawn and Process.spawn_captured remove that variable from what they pass on, so a program sees only a channel its own parent opened. Its standard input and output stay free.
Process.channel_read_line, Process.channel_send and Process.channel_close #
Process.channel_read_line(process: Process, timeout_ms: Int) -> Result[String]
Process.channel_send(process: Process, text: String, timeout_ms: Int) -> Result[Void]
Process.channel_close(process: Process, timeout_ms: Int) -> Result[Void]channel_read_linereads one line (at most 1 MiB, ending removed), asProcess.read_linedoes. At the end it giveserror("process: end of input"); a last line that the program’s exit cut off, with no line ending, is not returned as a line: it giveserror("process: line cut off"). If standard output or error was cut (seeProcess.read_available) and no complete line is there, it giveserror("process: output exceeds 1048576 bytes")at once, so a program that prints forever is noticed without the timeout.channel_sendsends at most 1048576 bytes exactly as given: add your own"\n".channel_closecloses only the sending side: the program reads end of input, and you can still read what it sends. Closing twice, or after exit, is fine.- A timeout in
channel_read_lineorchannel_sendcloses the channel, not the program. Later calls giveerror("process: channel is closed"). - Without a channel all three give
error("process: the child has no channel").
def main() -> Void
script = "read line <&3; echo \"got $line\" >&4"
p = Process.spawn_channel("sh", ["-c", script]).unwrap!
_ = Process.channel_send(p, "hello\n", 1000)
puts(Process.channel_read_line(p, 1000))
Process.close(p)
endok("got hello")Process.read_available #
Process.read_available(process: Process, timeout_ms: Int) -> Result[String]Gives, and removes, the standard output of a captured program that has arrived since the last call.
- It never waits for more output; the timeout only bounds the wait for the read lock. One call takes at most about 2 MiB.
- Bytes that end mid-character wait for the next call, so a character is never split (unless the output has ended).
- Output written before a channel line is in the text once you have read that line, so flushing before sending a record ties the output to the record.
- After truncation it gives
error("process: output exceeds 1048576 bytes"). On aProcess.spawnprogram,error("process: output is not captured").
def main() -> Void
script = "echo working; echo done >&4"
p = Process.spawn_channel("sh", ["-c", script]).unwrap!
puts(Process.channel_read_line(p, 1000))
puts(Process.read_available(p, 1000))
Process.close(p)
endok("done")
ok("working\n")Process.parent_read_line and Process.parent_send #
Process.parent_read_line(timeout_ms: Int) -> Result[String]
Process.parent_send(text: String, timeout_ms: Int) -> Result[Void]The program’s side of the channel its parent opened with Process.spawn_channel, with the rules of channel_read_line and channel_send. The timeout must be positive, and a timeout closes the channel for good. Without a channel: error("process: no parent channel").
- The VM takes the channel at start-up only when
AGENTICA_CHANNELis3,4and descriptor 3 is open for reading and 4 for writing, each a pipe, a FIFO or a socket (on Windows a pipe). On Linux and macOS it also takes3with one socket or FIFO open both ways on descriptor 3. Anything else (a regular file, a device, a pipe the wrong way round) is left alone: no channel. - The program’s own children do not inherit the descriptors or the variable.
These calls are for runner code such as agentica test. A test that calls them can break the protocol between the runner and its file, and nothing stops it.
def main() -> Void
line = Process.parent_read_line(5000)
if line.ok?
_ = Process.parent_send("echo " + line.unwrap! + "\n", 5000)
end
end