skills/skills/session-inbox-monitor/SKILL.md

name, author, version, description

name	author	version	description
session-inbox-monitor	ours	1.0.0	Raises a persistent Monitor on the project's Mappa inbox (poll `mcp__mappa__inbox_monitor` / HTTP `GET /inbox?project=<cwd>`), so inter-session messages page the session in real time; the monitor dies on session end on its own. Pi (pi-coding-agent) sessions: a global extension polls the same HTTP endpoint, session-scoped (own project only). Triggers: AGENTS.md line `inbox monitor: raise on start`, or «подними монитор почты», «настрой авто-монитор инбокса», «raise inbox monitor», «auto-arm inbox watcher». Headless (`claude -p` / `pi -p`): does NOT raise — rely on the Stop-hook / agent_settled pull pickup. File channel `.agents/inbox/` is gone (flip, решение 15) — letters live in Mappa as entities `i:N`, delivery is a carve-out (no lease, решение 19). NOT for how to handle a received message (→ inter-session-messaging).

session-inbox-monitor

Auto-raises a session-length Monitor on the project's Mappa inbox at interactive-session start, so inter-session messages page the session in real time. Tears down for free on session end. Headless sessions skip it and rely on the pull-model (Stop-hook / agent_settled pickup).

Канал — Mappa, НЕ файлы: письма — сущности inbox (i:N) в сервисе, читаются через mcp__mappa__inbox_monitor(project, limit) (или HTTP GET /inbox?project=<имя-папки>&limit=N). Доставка/чтение — карв-аут (решение 19): не блокируются лизом, работают всегда. Файловые .agents/inbox/ и .read/ выпилены.

When to use

• Automatic (the common path). A paired SessionStart hook injects an instruction at the start of every interactive session of an opted-in project. You act on that injection — raise the monitor as your first action — without a user phrase.
• On request. AGENTS.md line inbox monitor: raise on start, or «подними монитор почты», «настрой авто-монитор инбокса», «raise inbox monitor», «auto-arm inbox watcher».
• NOT for handling the content of a received message (→ inter-session-messaging). This skill is only the monitor's lifecycle.

Inputs

• <project> — своё имя папки (cwd basename), адрес в Mappa.
• Письма: mcp__mappa__inbox_monitor(project=<своя папка>, limit) → {rows: [{id, slug, body}]} (последние N). from/subject — в meta, через entity_get(id) при ответе.
• Мопitor-команда при CC — HTTP-опрос GET /inbox?project=... (без токена на текущем проде; если MAPPA_API_TOKEN задан — x-api-token header).

Steps

1. Mode check. Headless / non-interactive (claude -p, pi -p, ctx.hasUI === false): STOP — do not raise a monitor. The pull pickup (CC Stop-hook / pi agent_settled) plus Notify: cover delivery there; a Monitor can't idle-watch in headless.
2. Raise exactly one persistent Monitor on the Mappa inbox: mcp__mappa__inbox_monitor(project=<cwd-имя-папки>, limit=50), poll interval ~15s, description: "inbox watcher". Dedup by письменному id: новое письмо — это id, которого ещё не было в предыдущих ответах.
3. Do not sweep yourself. Killing orphans is the hook's job (it runs before you, at SessionStart).
4. On an event (новый id в ответе inbox_monitor), прочитай письмо (body) и обработай per inter-session-messaging. Для ответа — entity_get(id) → meta.from. Письма не перемещаются (нет .read/) — обработанные остаются в списке; дедуп по id в памяти монитора.
5. Teardown is automatic. The Monitor dies at session end. Do not add a SessionEnd teardown.

Pi (pi-coding-agent) support — session-scoped global extension

Same contract, pi-native, session-scoped: the extension polls ONLY the current session's project inbox (GET /inbox?project=<basename cwd>); it never reads other projects' inboxes (vitya's rule: an agent may only read its own project's inbox). Installed globally so every pi session has the capability, but each session only ever touches its own project.

• Source of truth: ~/projects/pi-extensions/extensions/inbox-monitor.ts (репо OpeItcLoc03/pi-extensions, Gitea — дом pi-расширений). Deploy: just install в клоне репо — копирует с затираанием в ~/.pi/agent/extensions/inbox-monitor.ts (global → every pi, every directory), hot-reload with /reload.
• Opt-in per project: AGENTS.md / CLAUDE.md line inbox monitor: raise on start. (Файловой директории .agents/inbox/ больше нет — триггер только строка.)
• PUSH: ~15s poll of the session's own Mappa inbox (interactive only). PULL: agent_settled sweep — same poll, backstop. Both share one dedup set per process (by letter id).
• Headless (pi -p, ctx.hasUI === false): NO delivery — no watcher, no sweep. Messages sit in Mappa until an interactive session picks them up.
• Delivery: pi.sendUserMessage(body, { deliverAs: "followUp", triggerTurn: true }) — paged into the transcript as a user message; the agent handles it per inter-session-messaging.

Failure modes

• Нет opt-in строки → монитор не поднимается; ожидаемо.
• Сервис mappa недоступен → poll-запрос падает; монитор ретраит следующий тик. Письма в сервисе не теряются (они — сущности), доставятся когда сервис вернётся. НЕ дублируй в файлы — фолбэк-канал выпилен.
• Two live interactive sessions on the same project → оба поллят один инбокс; дедуп по id делает доставку first-wins (кто первый прочитал id — тот и доставил; второй пропускает). Real-time paging теряет только тот, кто опоздал; письма не теряются (pull-свип в конце хода).
• Monitor auto-stopped → harness останавливает мониторы с переизбытком событий; дедуп по id держит частоту пейджинга под баром.
• Обработанное письмо вернулось в списке — не баг: в Mappa нет .read/, письма не перемещаются. Сверяйся с уже виденными id, не перечитывай.

What NOT to do

• Don't watch the file inbox (.agents/inbox/) — канал выпилен; пиши и читай через Mappa.
• Don't watch the inbox with a background Bash (run_in_background) — it leaks across /clear and accumulates zombies. Use the Monitor tool.
• Don't add a SessionEnd teardown hook — the Monitor self-terminates.
• Don't raise more than one monitor. The hook guarantees a clean slate before you raise.
• Don't handle message content here — that's inter-session-messaging.
• Don't rely on this in headless — use the pull model (Stop-hook + Notify).