# pi-inbox

Allow multiple Pi sessions to talk to each other while still staying coherent, with a small agent-facing surface and policy-driven behavior inside the extension.

## Install

Install from npm through Pi:

```bash
pi install npm:@nqbao/pi-inbox
```

Or load it locally during development:

```bash
pi -e ./index.ts
```

## Package

This is a Pi package and exposes its extension through `package.json`:

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

`pi-inbox` is designed around a simple rule: keep protocol complexity inside Pi, and keep the agent interface as small as possible. The extension focuses on policy between Pi sessions so they can talk to each other without creating too much confusion for the agent, while the agent itself ideally only needs to understand:

- a message was delivered
- reply with `inbox_post(channel, message)` if a reply is needed

## Current Shape

- Pure file-system transport
- Channel-oriented messaging
- Auto-polling and notification injection
- One agent-facing tool: `inbox_post`
- User-facing commands for subscribe, unsubscribe, post, clear, and status

Current implementation files:

- [index.ts](./index.ts)
- [tools.ts](./tools.ts)
- [transport.ts](./transport.ts)
- [channels.ts](./channels.ts)
- [config.ts](./config.ts)

## Product Position

`pi-inbox` is a messaging primitive, not an orchestration runtime.

It is meant to let independent Pi sessions talk to each other while keeping the model loop simple. Coordination complexity such as delivery behavior, claiming, retries, batching, or response shaping should live inside the extension rather than in additional agent tools.

This means `pi-inbox` focuses on policy among agents:

- who should receive a message
- whether a reply is expected
- whether a message is informational or claimable
- how broadly a message should be delivered
- whether responses should be constrained
- whether urgent items should be broken out from normal batches

The goal is operational sophistication with cognitive simplicity.

## Design Principles

- Hide protocol, expose intent
- Keep the agent-facing communication API minimal
- Push messages to the agent instead of making the agent poll
- Keep discovery primarily user-facing
- Use one transport model for both broadcast and peer-to-peer messaging
- Prefer delivery policy over extra coordination tools

## Communication Model

Channels are the core primitive.

Examples:

- shared channel: `code-review`
- shared channel: `orchestrator`
- peer-specific channel: `_dm.worker-abc`

Both broadcast-style and peer-to-peer communication should fit within the same channel model.

Current channel names may only contain lowercase letters, `.`, `_`, and `-`.

## Policy Direction

The longer-term direction is to let Pi manage communication policy internally while preserving the same small external interface.

Examples of policy dimensions:

- audience: broadcast, selective, direct
- reply expectation: read-only, reply-allowed, single-claimer
- constraints: free-form, yes/no, fixed choices, short structured reply
- priority: high, normal, low

These policies are intended to shape delivery and notification behavior without growing the tool surface.

## Current Tool

### `inbox_post(channel, message)`

Posts a message to a subscribed channel.

Current behavior:

- rejects unsubscribed channels
- writes to the channel log
- advances cursor to avoid self-notification

See [tools.ts](./tools.ts).

## Commands

Current user-facing commands:

- `/inbox-subscribe <channel>`
- `/inbox-unsubscribe <channel>`
- `/inbox-status`
- `/inbox-post <channel> <message>`
- `/inbox-clear <channel>`

Commands are for user control and inspection. Discovery and richer session awareness should be added here before becoming agent-visible capabilities.

## Transport

`pi-inbox` uses append-only `messages.jsonl` files under a local inbox directory.

Default shape:

```text
~/.pi/inbox/
  default/
    channels/
      code-review/
        messages.jsonl
```

This keeps the system:

- local
- durable
- inspectable
- offline-tolerant
- free of broker/daemon requirements

## Roadmap

Planned work is documented in [PLAN.md](./PLAN.md).

The main roadmap direction is not “more tools.” It is richer internal policy with a stable, simple agent-facing model.