pi-oneterm

pi-oneterm is a pi extension for OneTerm Agent Mode. It emits OSC 9;7 status events from pi to the terminal host, following docs/spec-osc-agent-status.md.

What it emits

Wire format:

ESC ] 9 ; 7 ; <base64-json> BEL

Implemented event types:

• session on session_start, including project_dir: ctx.cwd
• state for working, idle, done, error, and manual blocked
• heartbeat while the session is alive
• model on startup/model changes/turn end
• tool_call on tool start/update/end
• file for pi built-in file/search tools
• approval for manual blocked state via /agent-status blocked ...

Tool calls are separated in code and payload metadata:

• Pi built-ins: bash, read, write, edit, grep, find, ls → tool_kind: "pi_builtin"
• pi-srcwalk tools: semantic_query, semantic_grep, semantic_inspect, semantic_show, semantic_review → tool_kind: "pi_srcwalk"
• Other/custom/extension tools → tool_kind: "other"

Project layout

src/
├── commands/          # slash commands
├── events/            # pi event registration
├── protocol/          # OSC 9;7 wire protocol, envelope, sequence, types
├── runtime/           # state machine, heartbeat, lifecycle handling
├── tools/             # pi built-in, pi-srcwalk, and other tool classification/summaries
├── utils/             # text/object/redaction helpers
└── index.ts           # extension entrypoint

Project-local auto-discovery entrypoint:

.pi/extensions/pi-oneterm.ts

Package entrypoint:

{
  "pi": {
    "extensions": ["./src/index.ts"]
  }
}

Development usage

Run directly:

pi -e ./src/index.ts

Or trust this project and let pi auto-discover .pi/extensions/pi-oneterm.ts.

Commands

Inside pi:

/agent-status
/agent-status working [message]
/agent-status blocked [message]
/agent-status idle [message]
/agent-status done [message]
/agent-status error [message]

/agent-status with no args shows current status and emits a heartbeat.

Validation

npm install
npm run typecheck