pi-agent-runtime

A Pi extension that exposes one tool, agent_runtime_run, for running a local command through @esauflores/agent-runtime. The runtime owns process cleanup and durable job recording; the tool returns its result, job directory, and bounded output.

Install

pi install npm:@esauflores/pi-agent-runtime

Requires Node.js 24+ or Bun 1.4+ for the runtime CLI; its published package runs compiled JavaScript on Node rather than relying on type stripping inside node_modules. The tool accepts literal argv, with optional workspace and timeoutSecs:

{
  "argv": ["printf", "%s\\n", "hello world"],
  "workspace": "/path/to/project",
  "timeoutSecs": 60
}

The command and arguments are passed without a shell. Omit workspace to use Pi's current working directory; omit timeoutSecs for no timeout. The result includes the runtime result record, job directory, and up to 16 KiB each of stdout and stderr. The complete recorded result and logs are stored in that job directory.

Cancellation and safety

When Pi cancels a tool call, the extension sends SIGTERM to the runtime CLI and waits for it to finish. The runtime then terminates its workload process group, persists the cancelled result, and exits. If the runtime cannot be started or does not return a result, the tool reports an error.

Local execution is not a sandbox. Commands retain the runtime user's filesystem, network, and environment access. A workspace only sets the command's working directory. Do not expose untrusted commands or inherited credentials; runtime process-group cleanup is not an isolation guarantee.

Development

From this directory:

bun install --frozen-lockfile
bun run check
bun run test