NAME
Langertha::Raider::CLI::Runner - Internal runner of one raider CLI prompt, for a human or a machine
VERSION
version 0.503
SYNOPSIS
# Internal to Langertha-Raider -- no API promise.
my $runner = Langertha::Raider::CLI::Runner->new(app => $app, output => $out);
my $ok = $runner->run_prompt('Summarize README.md');
$ok = $runner->run_prompt('Summarize README.md', machine => $machine);DESCRIPTION
Internal module. Its interface may change without notice.
Runs one prompt through "run_prompt" in Langertha::Raider::Application, which records the run in the session journal, and renders the outcome: the agent's answer plus a status line (elapsed seconds, history size against the context budget, token usage when tracing), or with a machine (Langertha::Raider::CLI::Machine) the run's document -- and, when that machine streams, the run.started, run.state, message and tool events the application hands it. It also owns the signals of a run.
app
The Langertha::Raider::CLI to run on. Required.
output
The Langertha::Raider::CLI::Output to print to. Required.
err
Filehandle for warnings that must not end up in machine output (a session journal that cannot be written). Defaults to STDERR.
run_prompt
my $ok = $runner->run_prompt($text, machine => $machine, session => $session, catch_signals => 1);Returns true when the run finished, false when it failed (the error is printed, or with machine is the failed document). An empty prompt runs nothing and counts as finished.
With a session (Langertha::Raider::Session) the application records the run in its journal ("run_prompt" in Langertha::Raider::Application), also when it failed or was interrupted; a machine document then names the session in session (id, path). A journal write that fails is a warning ("journal_error"); the run goes on.
With catch_signals, a SIGINT during the run cancels it ("cancel_run"): it ends as cancelled at its next safe point, its outcome is printed or written as always, and then the process dies of SIGINT ("die_of_signal"). A second SIGINT while it is being cancelled, one before the application started the run, and a SIGTERM end it as interrupted: see "interrupt".
interrupt
$runner->interrupt(TERM => $machine, $elapsed);Ends a run interrupted by the signal: ends the tool subprocesses still running ("terminate_children"), ends the application's run as interrupted (with the signal), prints a note, or with a machine writes the interrupted document, then dies of that same signal through "die_of_signal".
With a machine it also works as a class method, which Langertha::Raider::CLI::Main uses for a signal during startup, before there is an app to run: the stream then has no run.started, only the interrupted state change and run.finished.
cancel_run
my $cancelling = $runner->cancel_run;Cancels the run in progress without leaving the process -- the REPL's first Ctrl-C, and the first SIGINT of a one-shot run: asks the application to cancel it ("cancel_run" in Langertha::Raider::Application), then ends the tool subprocesses still running ("terminate_children"). The run ends as cancelled at its next safe point and "run_prompt" returns false, after turn cancelled (or with a machine, the cancelled document). Only records and signals, so the signal handler calls it. Returns false when no run is in progress.
abandon
$runner->abandon('TERM');Ends the run in progress, if there is one, as interrupted by the signal -- its run.finished in the session journal, and with a machine its document -- without leaving the process. The REPL calls it when it is left during a run.
event
$runner->event('tool.call', call => 'c1', name => 'bash', arguments => { ... });One event of the run in progress, as the application hands it on: into the machine stream ("event" in Langertha::Raider::CLI::Machine), except the user's own input -- a stream message is the agent's (ADR 0013). Outside a run it does nothing.
record
$runner->record($session, 'history.cleared');Appends one event outside a run to the session journal ("record" in Langertha::Raider::Application). A write that fails is a warning ("journal_error") and returns false.
journal_error
$runner->journal_error($session, $error);Reports a session journal that cannot be written on "err", warning: session ID not fully saved: ...: the application's "on_journal_error" in Langertha::Raider::Application, which reports only the first failure of a run.
die_of_signal
$runner->die_of_signal('TERM');Ends the process by the signal, restored to its default action: the parent sees a process killed by that signal (a shell reports 130 for INT, 143 for TERM; the Hall records the raider as signaled). Should the process survive it, it exits with 128 plus the signal number.
terminate_children
$runner->terminate_children;Ends the processes this raider started that still run -- a bash command (MCP::Run::Bash puts it into a process group of its own, so a signal aimed at raider alone never reaches it), a perl_eval or perl_cpanm child: SIGTERM to each child's process group, or to the child when it leads none, and SIGKILL to what is left after terminate_grace seconds.
child_pids
The process IDs of this process's children, from /proc, or from ps where there is none.
elapsed_since
my $elapsed = $runner->elapsed_since($t0);Seconds since the Time::HiRes time $t0, to the millisecond: the elapsed of a document.
SEE ALSO
SUPPORT
Issues
Please report bugs and feature requests on GitHub at https://github.com/Getty/langertha-raider/issues.
IRC
Join #langertha on irc.perl.org or message Getty directly.
CONTRIBUTING
Contributions are welcome! Please fork the repository and submit a pull request.
AUTHOR
Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/
COPYRIGHT AND LICENSE
This software is copyright (c) 2026 by Torsten Raudssus.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.