Kai
53ffa2fd7f
One Gitea repo (kai/pi-agent-config, SSH key auth as user git on :222) holds the runtime config, all scenario agent configs, and the curator backend; no per-agent repos. Each scenario now carries a root README pointing at the shared repo and push flow so a directory's provenance and push method are unambiguous.
107 lines
5.0 KiB
Markdown
107 lines
5.0 KiB
Markdown
# memo-inbox — Pi agent scenario
|
|
|
|
This directory is the **memo-inbox** Pi agent. It is tracked as part of the
|
|
`pi-agent-config` repository — it is **not** a standalone repository.
|
|
|
|
- Gitea repo: `kai/pi-agent-config` on `192.168.50.45` (web `:3000`, SSH `:222`).
|
|
- Remote: `origin -> gitea-45:kai/pi-agent-config.git`, branch `main`.
|
|
- Auth: SSH key only (`~/.ssh/id_ed25519_gitea`, Git user `git`); no HTTP token.
|
|
- Push and pull from the repository root, not from here:
|
|
|
|
```bash
|
|
git pull --rebase origin main
|
|
git push origin main
|
|
```
|
|
|
|
See the repository [`README.md`](../../README.md), section “Gitea repository and
|
|
push authentication”, for the full SSH config and caveats.
|
|
|
|
## Layout
|
|
|
|
- `profile.toml` — the launch contract; `deploy = "mirror"` records what the live service does.
|
|
- `workspace/` — the mirrored live agent configuration.
|
|
- `docs/` — scenario-specific documentation.
|
|
|
|
# Scenario: memo-inbox
|
|
|
|
Routes Kai's Telegram and WeChat messages into Google Calendar, today's Obsidian
|
|
todo list, or a journal memo — without requiring slash commands or confirmation.
|
|
|
|
Live service: `pi-memo-telegram.service` (user unit, active).
|
|
Live workspace: `/home/claw/pi-workspaces/memo-inbox`.
|
|
|
|
## Migration status
|
|
|
|
**Mirrored, not yet managed.** Migrated 2026-08-27 by copying; the live
|
|
directory was not moved or modified and the service was not restarted. All four
|
|
tracked files match production byte for byte.
|
|
|
|
| Tracked | Live target |
|
|
|---|---|
|
|
| `workspace/AGENTS.md` | `<workspace>/AGENTS.md` |
|
|
| `workspace/.pi/extensions/memo-guard.ts` | `<workspace>/.pi/extensions/memo-guard.ts` |
|
|
| `workspace/.agents/skills/pi-memo-inbox/SKILL.md` | `<workspace>/.agents/skills/pi-memo-inbox/SKILL.md` |
|
|
| `workspace/bin/journal-sync.sh` | `<workspace>/bin/journal-sync.sh` |
|
|
|
|
Verify at any time:
|
|
|
|
```bash
|
|
scripts/pi-diff.sh memo-inbox
|
|
```
|
|
|
|
## Deliberately not tracked
|
|
|
|
| Path | Why |
|
|
|---|---|
|
|
| `telegram-gateway/` | Application code (622 + 343 lines), not configuration. It also sits inside the agent's own cwd, which is a separate design problem — an agent's readable workspace should not contain the program that drives it. Relocating it is a follow-up. |
|
|
| `.ccgram-uploads/` | Runtime data: inbound Telegram voice notes, photos and documents. |
|
|
| `download.html` | Generated artefact. |
|
|
| `telegram-gateway/.venv/` | Toolchain. |
|
|
| `gateway.py.bak-20260818-wechat` | Stale backup. |
|
|
|
|
## Why this scenario matters to the others
|
|
|
|
memo-inbox is the **reference implementation** for three patterns that the
|
|
curator scenario lacks. See `docs/gateway-patterns.md` for the full comparison.
|
|
|
|
1. **Long-lived RPC process.** `gateway.py` starts `pi --mode rpc` once and
|
|
drives it turn by turn, with protocol-correct `\n`-only JSONL framing.
|
|
2. **Session rotation.** Rotates after 24 prompts, plus a `messageCount >= 60`
|
|
guard. pi has no session TTL and auto-compaction does not fire on a
|
|
1.05 M-token context window, so a gateway must do this itself.
|
|
3. **Deterministic write receipts.** The reply a user sees for a state change is
|
|
harvested from `tool_execution_end` on the mutation tools, not generated by
|
|
the model. This is the single most valuable pattern in the repository.
|
|
|
|
Its `memo-guard.ts` is also the origin of `shared/extensions/pi-guard-base.ts`:
|
|
path containment, the restricted `read` override, `setActiveTools`, and the
|
|
`tool_call` block.
|
|
|
|
## Known gaps
|
|
|
|
Recorded here rather than fixed, because this service is in daily use and the
|
|
migration was scoped to zero behaviour change. Tracked as plan phase 5.
|
|
|
|
| Gap | Effect |
|
|
|---|---|
|
|
| No `--no-extensions` / `--no-skills` / `--no-prompt-templates` / `--no-themes` | `~/.pi/agent/extensions/{herdr-agent-state,pi-memo-trust}.ts` and `~/.agents/skills/{find-skills,modsearch,summarize}` load into this agent. `find-skills` instructs the agent to discover and install further skills. |
|
|
| No `.pi/SYSTEM.md` | Runs on pi's default coding-assistant prompt, including the block of absolute paths to pi's own docs with an instruction to read them and follow cross-references. `AGENTS.md` corrects course from on top of that rather than replacing it. |
|
|
| Full environment inherited | `ASR_API_KEY` and anything else in the unit reaches the node process and every extension it loads. |
|
|
| No `--no-builtin-tools` | Built-ins are active at startup and are narrowed only once `session_start` fires and `setActiveTools` runs. The `tool_call` hook still blocks them, so this is a defence-in-depth gap rather than an open hole. |
|
|
| `--continue` instead of `--session-id` | Continuity depends on "most recent session for this cwd". A stray interactive `pi` run in the same directory could be continued by the service. |
|
|
| `allowed-tools:` in SKILL.md | Not consumed by pi 0.84.3. Harmless, but do not treat it as enforcement. |
|
|
|
|
## Applying changes
|
|
|
|
```bash
|
|
scripts/deploy-scenario.sh memo-inbox # dry run, shows the diff
|
|
scripts/deploy-scenario.sh memo-inbox --apply # then restart the unit yourself
|
|
```
|
|
|
|
The deploy script never restarts a service. For this scenario:
|
|
|
|
```bash
|
|
systemctl --user restart pi-memo-telegram.service
|
|
systemctl --user status pi-memo-telegram.service
|
|
```
|