@agimon-ai/po-runner

Supervised shell execution, background process control, and run logs for Pi coding agents.

Packages

Package details

package

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.