pi-process

A Pi extension that overrides bash and adds a process tool with OpenClaw-style background execution.

Features

• bash auto-backgrounds long commands after yieldMs (default 10000ms)
• bash background=true starts immediately in background
• In-memory job tracking (per Pi session)
• process actions: list, poll, log, write, kill, clear, remove
• Simple KISS/YAGNI implementation (in-memory state, optional PTY via node-pty)

Install

cd ~/code/pi-process
npm install

Then load in Pi:

pi -e ~/code/pi-process/src/index.ts

Or add it to ~/.pi/agent/extensions/ (or .pi/extensions/) and use /reload.

Tool contracts

bash

Parameters:

• command (required)
• timeout (seconds, optional)
• yieldMs (milliseconds, default 10000)
• background (boolean, optional)
• pty (boolean, optional; requires @lydell/node-pty)

Behavior:

• If command completes before yieldMs, returns foreground output.
• Otherwise returns status=running and sessionId.

process

Parameters:

• action: list | poll | log | write | kill | clear | remove
• sessionId: required for all actions except list
• offset, limit: optional paging for log (line-based)
• data, eof: optional stdin input for write

Acceptance smoke tests (agent-driven)

Use these in a fresh Pi session after loading the extension. These are end-to-end prompts where the agent should decide when to use bash vs process.

1) Long command that should auto-background and complete

Prompt to agent:

Run `ping -c 20 google.com`. If it backgrounds, keep polling until it completes, then summarize packet loss and avg latency.

What success looks like:

• First bash call runs ~10s and backgrounds with a session id.
• Agent then calls process poll repeatedly.
• Final response includes completed ping stats.

2) Regular short command should stay foreground

Prompt to agent:

Run `uname -a` and show me the result.

What success looks like:

• Agent uses bash only.
• No process follow-up needed.

3) Start long job, write to stdin, then cancel it

Prompt to agent:

Start `cat` in background. Write `hello\n` to stdin, poll to verify output, then stop it.

What success looks like:

• Agent gets a running session id from bash.
• Agent uses process write with data (and optional eof) to send stdin.
• Agent confirms echoed output via process poll.
• Agent stops it with process kill (or remove).

4) Fire-and-forget behavior

Prompt to agent:

Start `sleep 15 && echo done` in background and do not wait for completion. Just tell me the session id.

What success looks like:

• Agent starts background work and returns session id.
• Agent does not keep polling.

5) Timeout behavior

Prompt to agent:

Run `sleep 30` with timeout 3 seconds and report what happened.

What success looks like:

• Command is terminated by timeout.
• Agent reports timeout outcome (foreground or via process state).

6) PTY/TTY behavior

Prompt to agent:

Run `python3` with pty=true, send `print(2+2)\n` via process write, then send eof=true and report output.

What success looks like:

• bash session starts with PTY and backgrounds/foregrounds as needed
• process write sends input into REPL
• output includes 4

Notes

• Jobs are scoped to the current Pi session.
• Jobs are in-memory only and cleaned up after a TTL.
• user_bash (!cmd) is intentionally not modified in v1.