@agimon-ai/po-runner
Supervised shell execution, background process control, and run logs for Pi coding agents.
Package details
Install @agimon-ai/po-runner from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@agimon-ai/po-runner- Package
@agimon-ai/po-runner- Version
0.0.0-alpha.183- Published
- Nov 22, 2026
- Downloads
- 31.6K/mo · 5,329/wk
- Author
- agiflow-ai
- License
- BUSL-1.1
- Types
- package
- Size
- 2.5 MB
- Dependencies
- 10 dependencies · 4 peers
Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
@agimon-ai/po-runner
Supervised shell execution for Po: sequential checks, interactive input, background processes, and complete command logs.
po init includes Runner in default.packages in .po/presets.yaml. Move it to a named layer to select it only in particular presets.
Requirements
- Node.js 24 or newer and
/bin/bash. - macOS or Linux on arm64 or x64 for bundled RMUX and RTK. Linux binaries require compatible glibc and a system loader; a matching CPU is not enough for musl hosts such as Alpine.
Panes use bundled RMUX, then rmux on PATH, then tmux. Without a pane backend, non-interactive commands fall back to a supervised subprocess; interactive commands require a pane backend. Install Runner rather than its optional platform packages directly.
Run commands
Always pass command as an array:
{
"command": ["pnpm build", "pnpm typecheck", "pnpm lint", "pnpm test"],
"name": "verification",
"timeout": 120
}
Entries run sequentially in fresh shells and stop at the first failure. Each has its own timeout and full log. cd and export do not carry between entries. The response lists attempted log paths and only the last executed command's bounded output.
Commands still running after the default 60-second threshold become supervised runners. Use background: true to detach immediately, for example for a dev server. Use interactive: true only when terminal input is needed; it applies to the last command only. For an interactive sequence, use the returned stage runner ID for input, not the sequence ID.
An agent-watched native runner retains background-work ownership until its completion notification is admitted. Receiving a runner ID is not evidence that the command succeeded or its enclosing workflow finished.
Inspect and stop work
With code mode, discover the runner namespace and use its list, status, logs, input, and stop methods. stopAll stops this session's active work. Reads are snapshots, not live streams. Check status before retrying, and distinguish requested cancellation from confirmed termination.
Without code mode, use the standalone CLI:
po-runner list
po-runner status <runner-id>
po-runner logs <runner-id>
po-runner input <runner-id> --text "y" --enter
po-runner stop <runner-id>
Input requires a running interactive RMUX or tmux process. Stop servers and watchers when no longer needed.
Logs, output limits, and configuration
Runner files live below the session's host-admitted temporary directory. Compaction does not remove that evidence; session removal, restart, or termination does. An external observer handles owner hard-kill cleanup. Save important deliverables to session artifacts, not Runner's temporary logs.
Do not redirect output to a file or pipe it through head or tail: Runner already saves the raw log. Long tool responses show opening and closing excerpts with a dropped-span marker. Byte, line, and estimated-token ceilings all apply; whichever binds first wins. Successful commands receive smaller excerpts than failures. Some error lines are rescued from the omitted span, but the excerpt is not complete diagnostic coverage. Inspect the saved log before rerunning a failed command.
Configuration precedence is per-command pragma, environment, trusted-project settings, then defaults. A command can request a wider excerpt on its first line:
# @po: {"maxResultBytes": 32768, "maxResultTokens": 8192, "maxResultLines": 300}
pnpm build
Trusted projects may use .pi/po-runner.json for result ceilings, excerpt ratios, and additional error patterns. Unknown keys and invalid values are reported; numeric ceilings prevent a project file flooding the model context. PO_RUNNER_RESULT_MAX_BYTES, PO_RUNNER_RESULT_MAX_TOKENS, and their PO_RUNNER_SUCCESS_* counterparts override project defaults. Changing only the byte ceiling will not help when another ceiling binds.
Commands use the admitted session environment and the operating system user's privileges. Logs can contain prompts, source, credentials, and other secrets. Protect access and retention accordingly. Supervision is not an OS sandbox.
Optional processing and shared admission
RTK filters conservatively recognized single commands after the raw log is saved. Compound commands, pipelines, redirects, unsupported formats, or logs above its 10 MiB input limit return bounded raw output. A missing, incompatible, or failed RTK binary also falls back to raw output without changing the command's exit status. Unrunnable spawn failures disable further attempts for that processor instance; missing-path resolution and ordinary processing failures do not.
The server shares a bounded heavy-job queue across sessions for recognized non-interactive build, test, lint, and typecheck commands. Background promotion retains the slot until exit; cancellation removes queued work without launching it. PO_RUNNER_MAX_HEAVY_JOBS controls the host limit. This is command admission, not an OS CPU quota. Explicit child environment settings override Runner's conservative non-interactive defaults.
Package-owned launches
readPoRunnerLaunch(context) from @agimon-ai/po-runner/launch reads the calling session's po/runner-launch service. Its operations stay session-local. Optional forOwner() takes no owner argument: it routes the same operations to the workflow's trusted owner session, or the current session otherwise. Check that method exists when supporting older builds.
Owner-routed starts suppress agent wake-up and join the owner's supervision. They survive the workflow child, but stop with their owner. Missing, closed, or incompatible owners refuse the launch before spawning; there is no fallback to the child. Releasing the child cancels its own starts before handoff and subscriptions, not handed-off owner work.
Native artifacts and development
RMUX is dual-licensed under MIT or Apache-2.0. RTK v0.45.0 is Apache-2.0. Platform packages contain executables and export package metadata only; their READMEs retain upstream provenance.
Run this package's build, typecheck, test, and lint scripts from its directory. Public factories and host integration subpaths are declared in package.json.
License
Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See LICENSE and https://agimon.ai/licensing.