pi-gateway 0.1.0__tar.gz

pi_gateway-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish Python package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package
+        run: uv publish

pi_gateway-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Runtime state
+*.sqlite3
+*.sqlite3-*
+*.log
+/config.yaml

pi_gateway-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

pi_gateway-0.1.0/AGENTS.md

@@ -0,0 +1,147 @@
+# AGENTS.md
+
+Guidance for AI agents working on this repository.
+
+## Project Overview
+
+Pi Gateway is a Python CLI/daemon that connects Telegram to persistent Pi coding-agent sessions.
+
+Core idea:
+
+```text
+Telegram conversation identity -> SQLite mapping -> Pi JSONL session file -> pi --mode rpc
+```
+
+Pi owns conversation history. The gateway owns Telegram routing, authorization, process management, and session metadata.
+
+## Read These First
+
+Before making changes, read:
+
+1. [`README.md`](README.md) - user-facing install/run instructions
+2. [`docs/README.md`](docs/README.md) - documentation index
+3. [`docs/01-architecture-overview.md`](docs/01-architecture-overview.md) - architecture and design constraints
+4. The specific doc for the area you are modifying:
+   - CLI/startup: [`docs/02-startup-and-cli-flow.md`](docs/02-startup-and-cli-flow.md)
+   - Telegram: [`docs/03-telegram-gateway.md`](docs/03-telegram-gateway.md)
+   - Pi RPC: [`docs/04-pi-rpc-integration.md`](docs/04-pi-rpc-integration.md)
+   - SQLite/session mapping: [`docs/05-session-mapping-and-sqlite.md`](docs/05-session-mapping-and-sqlite.md)
+   - deployment/config: [`docs/06-configuration-and-deployment.md`](docs/06-configuration-and-deployment.md)
+   - debugging: [`docs/07-troubleshooting.md`](docs/07-troubleshooting.md)
+
+## Important Commands
+
+Syntax check:
+
+```bash
+python3 -m compileall pi_gateway main.py
+```
+
+CLI smoke tests:
+
+```bash
+python3 main.py --help
+python3 main.py configure --help
+python3 main.py configure telegram --help
+python3 main.py status
+```
+
+uv development:
+
+```bash
+uv sync
+uv run pi-gateway --help
+```
+
+Install/update as uv tool from checkout:
+
+```bash
+uv tool install --force .
+```
+
+## Runtime Commands
+
+Foreground daemon:
+
+```bash
+pi-gateway run
+```
+
+Background daemon:
+
+```bash
+pi-gateway start
+pi-gateway status
+pi-gateway logs -f
+pi-gateway stop
+```
+
+Interactive Telegram configuration:
+
+```bash
+pi-gateway configure telegram
+```
+
+## Repository Structure
+
+```text
+pi_gateway/
+├── cli.py              # CLI, config wizard, foreground/background process commands
+├── config.py           # YAML/env config loader and dataclasses
+├── db.py               # SQLite schema and gateway persistence
+├── pi_rpc.py           # JSONL RPC subprocess client for `pi --mode rpc`
+├── session_manager.py  # per-conversation Pi client cache/locks
+└── telegram_bot.py     # Telegram adapter, auth, commands, lifecycle notifications
+```
+
+## Design Rules
+
+- Do not duplicate Pi conversation history in SQLite.
+- Store gateway metadata in SQLite: Telegram identity, Pi session file/id/name, audit messages.
+- Prefer `pi_session_file` over only `pi_session_id` when resuming sessions.
+- Keep Telegram user allowlisting secure by default.
+- Group chats should remain disabled by default.
+- Keep `pi-gateway run` as foreground mode; `start/stop/status/logs` are convenience wrappers.
+- For production VPS deployment, continue to recommend systemd.
+- If changing behavior, update `README.md` and relevant files in `docs/`.
+
+## Security Notes
+
+This gateway can expose a coding agent with filesystem and shell tools. Be careful.
+
+- Maintain `telegram.allowedUserIds` checks.
+- Do not add broad unauthenticated webhooks or APIs.
+- Do not log secrets such as Telegram bot tokens.
+- If adding new platforms, implement explicit allowlists.
+- If adding group support, consider session-key and authorization implications.
+
+## Pi Integration Notes
+
+The gateway uses Pi RPC, not the Pi SDK.
+
+Important Pi RPC assumptions:
+
+- Start command is `pi --mode rpc`.
+- Existing sessions can resume with `--session <session-file>`.
+- JSONL records are newline-delimited.
+- Prompt completion is detected by consuming events until `agent_end`.
+
+If Pi RPC protocol changes, update:
+
+- `pi_gateway/pi_rpc.py`
+- [`docs/04-pi-rpc-integration.md`](docs/04-pi-rpc-integration.md)
+
+## Git Hygiene
+
+- Run syntax checks before committing.
+- Keep commits focused and descriptive.
+- Do not commit local `config.yaml`, SQLite DBs, logs, PID files, virtualenvs, or `__pycache__`.
+- `.gitignore` already excludes common runtime state.
+
+## Documentation Requirement
+
+When changing code, update relevant docs:
+
+- User-facing behavior: `README.md`
+- Architecture or internals: `docs/*.md`
+- Agent handoff instructions: this `AGENTS.md`

pi_gateway-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: pi-gateway
+Version: 0.1.0
+Summary: Telegram gateway for controlling persistent Pi coding-agent sessions over RPC
+Requires-Python: >=3.11
+Requires-Dist: python-telegram-bot<23.0,>=21.0
+Requires-Dist: pyyaml<7.0,>=6.0.1
+Description-Content-Type: text/markdown
+
+# pi-gateway
+
+Telegram gateway for persistent [Pi](https://pi.dev) coding-agent sessions.
+
+The gateway is a long-running process. Telegram conversations are mapped to Pi JSONL session files in SQLite, while Pi remains the source of truth for agent history.
+
+## Documentation
+
+See [`docs/`](docs/README.md) for architecture, startup flow, Telegram gateway internals, Pi RPC integration, session mapping, deployment, and troubleshooting notes.
+
+## Install with uv
+
+Directly from GitHub (no clone needed):
+
+```bash
+uv tool install git+https://github.com/YOUR_USERNAME/pi-gateway.git
+```
+
+Install a specific tag or branch:
+
+```bash
+uv tool install git+https://github.com/YOUR_USERNAME/pi-gateway.git@v0.1.0
+```
+
+Upgrade later:
+
+```bash
+uv tool install --force git+https://github.com/YOUR_USERNAME/pi-gateway.git
+# or
+uv tool upgrade pi-gateway
+```
+
+From a local checkout:
+
+```bash
+uv tool install .
+```
+
+Or for development:
+
+```bash
+uv sync
+uv run pi-gateway --help
+```
+
+Pi must already be installed and authenticated on the machine as the same user that runs the gateway.
+
+## Configure Telegram
+
+Create/update the default config at `~/.config/pi-gateway/config.yaml` interactively:
+
+```bash
+pi-gateway configure telegram
+```
+
+It will ask for your BotFather token, your allowed Telegram user id, and the Pi working directory.
+
+You can also configure non-interactively:
+
+```bash
+pi-gateway configure telegram \
+  --allowed-user-id YOUR_TELEGRAM_USER_ID \
+  --pi-cwd /home/agent/pi-workspace
+```
+
+By default the bot token can be read from `TELEGRAM_BOT_TOKEN`. You can also write it into the config:
+
+```bash
+pi-gateway configure telegram \
+  --bot-token '123:abc' \
+  --allowed-user-id YOUR_TELEGRAM_USER_ID \
+  --pi-cwd /home/agent/pi-workspace
+```
+
+Security note: `--allowed-user-id` writes a single allowlisted Telegram user id. Messages from other users are ignored. Group chats are disabled unless you pass `--allow-groups`.
+
+Print the default config path:
+
+```bash
+pi-gateway config-path
+```
+
+You can still maintain config manually; see `examples/config.yaml`.
+
+## Run
+
+Foreground mode, useful for debugging or systemd:
+
+```bash
+export TELEGRAM_BOT_TOKEN=123:abc
+pi-gateway run
+```
+
+Background mode, useful for a simple VPS setup without systemd:
+
+```bash
+pi-gateway start
+pi-gateway status
+pi-gateway logs -f
+pi-gateway stop
+```
+
+`start` writes logs to:
+
+```text
+~/.local/state/pi-gateway/pi-gateway.log
+```
+
+With an explicit config:
+
+```bash
+pi-gateway -c config.yaml start
+pi-gateway -c config.yaml run
+# or
+pi-gateway run -c config.yaml
+```
+
+Development checkout:
+
+```bash
+uv run pi-gateway run
+```
+
+## Telegram commands
+
+- `/status` current Pi session/model/stats
+- `/new` fresh Pi session for this Telegram chat
+- `/name <name>` name current Pi session
+- `/compact [instructions]` compact current Pi context
+- `/stop` abort current Pi operation
+- `/last` resend last assistant response
+- `/export` export current session to HTML
+- `/sessions` list known sessions
+- `/switch <id>` point this chat at another known Pi session
+- `/clone` clone current branch into a new session
+- `/models` list available models
+- `/model <provider/model-id>` switch model
+- `/thinking <level>` set thinking level
+- `/queue <text>` queue follow-up
+- `/steer <text>` steer current/next turn
+- `/pi <text>` send raw text to Pi, including Pi slash commands
+
+Normal Telegram messages are sent to Pi as prompts.
+
+## Session mapping
+
+Gateway key:
+
+```text
+telegram:<chat_id>:<thread_id?>:<user_id?>
+```
+
+SQLite stores that key plus Pi's `sessionId` and `sessionFile`. On restart the gateway resumes with:
+
+```bash
+pi --mode rpc --session <stored-session-file>
+```
+
+## systemd
+
+See `systemd/pi-gateway.service` and adjust paths/user/env.
+
+Example with uv tool install:
+
+```ini
+[Service]
+User=agent
+Environment=TELEGRAM_BOT_TOKEN=123:abc
+ExecStart=/home/agent/.local/bin/pi-gateway run
+Restart=always
+```

pi_gateway-0.1.0/README.md

@@ -0,0 +1,171 @@
+# pi-gateway
+
+Telegram gateway for persistent [Pi](https://pi.dev) coding-agent sessions.
+
+The gateway is a long-running process. Telegram conversations are mapped to Pi JSONL session files in SQLite, while Pi remains the source of truth for agent history.
+
+## Documentation
+
+See [`docs/`](docs/README.md) for architecture, startup flow, Telegram gateway internals, Pi RPC integration, session mapping, deployment, and troubleshooting notes.
+
+## Install with uv
+
+Directly from GitHub (no clone needed):
+
+```bash
+uv tool install git+https://github.com/YOUR_USERNAME/pi-gateway.git
+```
+
+Install a specific tag or branch:
+
+```bash
+uv tool install git+https://github.com/YOUR_USERNAME/pi-gateway.git@v0.1.0
+```
+
+Upgrade later:
+
+```bash
+uv tool install --force git+https://github.com/YOUR_USERNAME/pi-gateway.git
+# or
+uv tool upgrade pi-gateway
+```
+
+From a local checkout:
+
+```bash
+uv tool install .
+```
+
+Or for development:
+
+```bash
+uv sync
+uv run pi-gateway --help
+```
+
+Pi must already be installed and authenticated on the machine as the same user that runs the gateway.
+
+## Configure Telegram
+
+Create/update the default config at `~/.config/pi-gateway/config.yaml` interactively:
+
+```bash
+pi-gateway configure telegram
+```
+
+It will ask for your BotFather token, your allowed Telegram user id, and the Pi working directory.
+
+You can also configure non-interactively:
+
+```bash
+pi-gateway configure telegram \
+  --allowed-user-id YOUR_TELEGRAM_USER_ID \
+  --pi-cwd /home/agent/pi-workspace
+```
+
+By default the bot token can be read from `TELEGRAM_BOT_TOKEN`. You can also write it into the config:
+
+```bash
+pi-gateway configure telegram \
+  --bot-token '123:abc' \
+  --allowed-user-id YOUR_TELEGRAM_USER_ID \
+  --pi-cwd /home/agent/pi-workspace
+```
+
+Security note: `--allowed-user-id` writes a single allowlisted Telegram user id. Messages from other users are ignored. Group chats are disabled unless you pass `--allow-groups`.
+
+Print the default config path:
+
+```bash
+pi-gateway config-path
+```
+
+You can still maintain config manually; see `examples/config.yaml`.
+
+## Run
+
+Foreground mode, useful for debugging or systemd:
+
+```bash
+export TELEGRAM_BOT_TOKEN=123:abc
+pi-gateway run
+```
+
+Background mode, useful for a simple VPS setup without systemd:
+
+```bash
+pi-gateway start
+pi-gateway status
+pi-gateway logs -f
+pi-gateway stop
+```
+
+`start` writes logs to:
+
+```text
+~/.local/state/pi-gateway/pi-gateway.log
+```
+
+With an explicit config:
+
+```bash
+pi-gateway -c config.yaml start
+pi-gateway -c config.yaml run
+# or
+pi-gateway run -c config.yaml
+```
+
+Development checkout:
+
+```bash
+uv run pi-gateway run
+```
+
+## Telegram commands
+
+- `/status` current Pi session/model/stats
+- `/new` fresh Pi session for this Telegram chat
+- `/name <name>` name current Pi session
+- `/compact [instructions]` compact current Pi context
+- `/stop` abort current Pi operation
+- `/last` resend last assistant response
+- `/export` export current session to HTML
+- `/sessions` list known sessions
+- `/switch <id>` point this chat at another known Pi session
+- `/clone` clone current branch into a new session
+- `/models` list available models
+- `/model <provider/model-id>` switch model
+- `/thinking <level>` set thinking level
+- `/queue <text>` queue follow-up
+- `/steer <text>` steer current/next turn
+- `/pi <text>` send raw text to Pi, including Pi slash commands
+
+Normal Telegram messages are sent to Pi as prompts.
+
+## Session mapping
+
+Gateway key:
+
+```text
+telegram:<chat_id>:<thread_id?>:<user_id?>
+```
+
+SQLite stores that key plus Pi's `sessionId` and `sessionFile`. On restart the gateway resumes with:
+
+```bash
+pi --mode rpc --session <stored-session-file>
+```
+
+## systemd
+
+See `systemd/pi-gateway.service` and adjust paths/user/env.
+
+Example with uv tool install:
+
+```ini
+[Service]
+User=agent
+Environment=TELEGRAM_BOT_TOKEN=123:abc
+ExecStart=/home/agent/.local/bin/pi-gateway run
+Restart=always
+```

pi_gateway-0.1.0/docs/01-architecture-overview.md

@@ -0,0 +1,104 @@
+# Architecture Overview
+
+Pi Gateway is a personal gateway daemon that lets a Telegram user communicate with Pi from a VPS or always-on machine.
+
+The central design decision is:
+
+> The gateway owns platform routing and metadata. Pi owns the agent conversation history.
+
+Pi sessions are still normal Pi JSONL sessions. The gateway stores only enough SQLite metadata to reconnect a Telegram conversation to the right Pi session file.
+
+## Main Components
+
+```text
+pi-gateway CLI
+  ├── configure telegram
+  ├── run / start / stop / status / logs
+  │
+  ▼
+Gateway runtime
+  ├── Config loader
+  ├── SQLite GatewayDB
+  ├── TelegramGateway adapter
+  └── PiSessionManager
+         └── PiRpcClient subprocesses
+                └── pi --mode rpc
+```
+
+## Runtime Flow
+
+```text
+Telegram message arrives
+  ↓
+TelegramGateway authorizes sender
+  ↓
+Build gateway session key
+  ↓
+GatewayDB finds/creates conversation row
+  ↓
+Command router handles gateway commands, or forwards normal text
+  ↓
+PiSessionManager gets per-conversation PiRpcClient
+  ↓
+PiRpcClient sends JSONL command to `pi --mode rpc`
+  ↓
+Assistant response is extracted from Pi RPC events
+  ↓
+TelegramGateway sends response back to Telegram
+```
+
+## Directory Structure
+
+```text
+pi-gateway/
+├── pi_gateway/
+│   ├── cli.py              # command-line interface and daemon startup
+│   ├── config.py           # config dataclasses and YAML/env loading
+│   ├── db.py               # SQLite schema and database access
+│   ├── pi_rpc.py           # Pi RPC subprocess client
+│   ├── session_manager.py  # per-conversation Pi client cache and locks
+│   └── telegram_bot.py     # Telegram adapter and command router
+├── examples/config.yaml
+├── systemd/pi-gateway.service
+├── docs/
+└── pyproject.toml
+```
+
+## Why RPC Instead of SDK?
+
+The gateway uses Pi RPC mode instead of importing the Pi SDK directly.
+
+Reasons:
+
+1. **Process isolation**: Pi runs as a child process. Gateway and Pi failures are more isolated.
+2. **Stable boundary**: The gateway talks to the documented JSONL RPC protocol.
+3. **VPS-friendly recovery**: On restart, the gateway can spawn `pi --mode rpc --session <file>`.
+4. **Hermes-like architecture**: Messaging gateway and agent runtime are cleanly separated.
+
+The tradeoff is that we must manage subprocesses, JSONL framing, and stdout/stderr readers.
+
+## State Ownership
+
+| State | Owner | Storage |
+|-------|-------|---------|
+| Pi conversation history | Pi | JSONL session files |
+| Active branch/session tree | Pi | JSONL session files |
+| Telegram to Pi mapping | Gateway | SQLite |
+| Inbound/outbound audit log | Gateway | SQLite |
+| Running child processes | Gateway | In memory + PID file for background daemon |
+
+## Design Constraints
+
+- One Telegram conversation should map to one Pi session file.
+- Normal text goes to Pi as a prompt.
+- Gateway slash commands are handled before Pi sees the message.
+- Pi slash commands can still be sent with `/pi <text>`.
+- Messages from non-allowlisted Telegram users are ignored.
+- Pi runs from a configured working directory so session storage and filesystem tools are predictable.
+
+## Related Documents
+
+- [Startup and CLI Flow](02-startup-and-cli-flow.md)
+- [Telegram Gateway](03-telegram-gateway.md)
+- [Pi RPC Integration](04-pi-rpc-integration.md)
+- [Session Mapping and SQLite](05-session-mapping-and-sqlite.md)