# pi-agent-shell

A high-performance, general-purpose interactive shell extension for [pi](https://github.com/nicobailon/pi).

Gives AI agents a single `turn()` primitive to interact with any CLI program — no polling, no timing heuristics, no program-specific adapters. Uses OS-level read-block detection to know exactly when a program is waiting for input.

## Install

```bash
pi install ~/Projects/pi-agent-shell
```

## How it works

The agent interacts with shell programs through one atomic operation:

```
turn(sessionId, input?) → { newOutput, prompt, waitingForInput, exited }
```

Internally, `turn()` writes input to a PTY, drains output, and waits for an OS-level signal that the process is blocked on a read syscall. The agent never polls or guesses timing — every round-trip is a decision, not a timing check.

### OS read-block detection

- **macOS**: process state probing via `ps` on the leaf foreground process
- **Linux**: `/proc/{pid}/syscall` — syscall number 0 (read) or select/epoll variants
- **Fallback**: quiet-window timeout when OS probing is unavailable (CI, containers)

## Tool: `agent_shell`

### Start a session

```json
{ "command": "python3 game.py" }
→ { "sessionId": "abc-123" }
```

### Take a turn

```json
{ "sessionId": "abc-123", "input": "north" }
→ { "newOutput": "You enter a dark cave.\n> ", "prompt": "> ", "waitingForInput": true }
```

### Peek (non-blocking)

```json
{ "sessionId": "abc-123", "peek": true }
→ { "newOutput": "...", "waitingForInput": false }
```

### Kill a session

```json
{ "sessionId": "abc-123", "kill": true }
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `command` | string | — | Shell command to start a new session |
| `sessionId` | string | — | Session to interact with |
| `input` | string | — | Text to send (appends `\n` if missing) |
| `peek` | boolean | false | Non-blocking snapshot, no input |
| `kill` | boolean | false | Terminate the session |
| `cwd` | string | pi cwd | Working directory |
| `env` | object | — | Additional environment variables |
| `timeoutMs` | number | 30000 | Max wait time for `turn()` |
| `quietMs` | number | 200 | Quiet-window fallback threshold |

## User commands

| Command | Description |
|---------|-------------|
| `/sessions` | List all active sessions |
| `/attach [id]` | Reattach the session overlay to watch/interact |

## Session overlay

When a session is running, an overlay shows real-time output. Controls:

- **Ctrl+B** — background the session (overlay hides, session keeps running)
- **Ctrl+C** — kill the session
- **↑/↓** — scroll through output

## Architecture

See [ARCHITECTURE.md](ARCHITECTURE.md) for design details.

## Development

```bash
npm test        # run tests
```

## Limitations

- **Line-oriented programs only** — full-screen TUI programs (vim, nano, htop) are not supported. The agent has better tools for file editing (`read`/`edit`/`write`), and most interactive CLI programs have non-interactive equivalents.
- **Unix only** — requires PTY support (macOS, Linux). No Windows/ConPTY support.
- **Local processes only** — no remote PTY or SSH session management.