# Service Manifest

Canonical sidecar and host-integration inventory for `pi-config`.

Goal:
- make services explicit
- record install path and health check
- separate repo-controlled code from durable data

## Fields
For each service/tool:
- purpose
- code source
- install path
- runtime/data path
- health check
- backup class
- current status notes

---

## agents-database
- purpose: canonical shared memory store and memory pipeline
- code source: external sibling project under `/home/sebas/agents-database`
- install path: systemd user services `agents-database-http.service`, `agents-database-maintenance.service`
- runtime/data path: `/home/sebas/agents-database/data/`
- health check: `http://100.116.176.16:8091/api/status`
- backup class: must back up durable data
- notes:
  - this should stay a sidecar, not a Pi extension
  - `pi-config` should integrate with it, not absorb it

## session-memory dispatcher
- purpose: receive queued session analysis payloads from Pi extension hook
- code source: `pi-config/scripts/session-memory-dispatcher.py`
- install path: `scripts/install-session-memory-dispatcher.service`
- runtime/data path: loop/session job data under `pi-config/sessions/` and local dispatcher runtime
- health check: local dispatcher should accept queue POSTs on `127.0.0.1:17882`
- backup class: repo-controlled logic; session jobs optional backup depending on value
- notes:
  - sidecar is correct shape

## session-memory sweeper
- purpose: catch up missed session analysis, especially Telegram-heavy periods
- code source: `pi-config/scripts/session-memory-sweeper.py`
- install path: `scripts/session-memory-sweeper.service`, `scripts/session-memory-sweeper.timer`
- runtime/data path: `/home/sebas/pi-config/runtime/session-memory-sweeper-state.json`
- health check: timer enabled; jobs processed; no growing backlog
- backup class: disposable state, repo-controlled logic

## pi-telegram
- purpose: Telegram bridge/session integration
- code source:
  - `bin/pi-telegram-service`
  - `scripts/pi-telegram.service`
  - `scripts/install-pi-telegram-service.sh`
- install path: `pi-telegram.service` user service via repo installer
- runtime/data path: Telegram env vars and session runtime
- health check: bridge receives/sends messages; `/new` rotation works
- backup class: repo logic + secret/env restore required
- notes:
  - installer path is now captured in repo

## task-phase tooling
- purpose: deterministic task execution harness
- code source:
  - `bin/task-phase-init`
  - `bin/task-phase-run`
  - `bin/task-phase-loop`
  - `scripts/task-phase-lib.ts`
- install path: repo-local CLI tools; no service required
- runtime/data path: task folders under `/home/sebas/work/tasks/`
- health check:
  - `bun run typecheck`
  - tool `--help`
  - smoke task creation/run
- backup class: repo logic + task data backup

## tool-usage telemetry
- purpose: append-only local usage/success telemetry for key tools
- code source:
  - `bin/tool-usage-log`
  - `bin/tool-usage-report`
  - `extensions/_shared/tool-usage.ts`
- install path: repo-local CLI/tools/extensions
- runtime/data path: `/home/sebas/runtime/tool-usage/events.jsonl`
- health check: `bin/tool-usage-report`
- backup class: optional durable ops history

## codex usage alerts
- purpose: send Telegram alerts for Codex 5h high-usage and 7d underused capacity near weekly reset
- code source:
  - `bin/codex-usage-alert`
  - `scripts/codex-usage-alert.service`
  - `scripts/codex-usage-alert.timer`
  - `scripts/install-codex-usage-alert.sh`
- install path: repo-local CLI + user systemd timer
- runtime/data path: `/home/sebas/runtime/codex-usage-alert/state.json`
- health check:
  - `bin/codex-usage-alert --status`
  - `systemctl --user status codex-usage-alert.timer`
- backup class: disposable runtime, useful ops state

## pi-job detached runner
- purpose: one detached inspectable non-interactive Pi job
- code source:
  - `bin/pi-job-start`
  - `bin/pi-job-runner`
  - `bin/pi-job-check`
  - `bin/pi-job-wait`
  - `bin/pi-job-stop`
- install path: repo-local CLI tools
- runtime/data path: `/home/sebas/runtime/pi-jobs`
- health check: start/check/wait flow works
- backup class: disposable runtime, optional archival value

## pi-loop generic loop
- purpose: repeated generic multi-session prompt loop
- code source: `bin/pi-loop`
- install path: repo-local CLI tool
- runtime/data path: `/home/sebas/runtime/pi-loop-runs`
- health check: smoke loop runs and artifacts appear
- backup class: disposable runtime, optional archival value
- notes:
  - for serious deterministic work, prefer task-phase loop now

## ralph-loop-run
- purpose: blocking file-handoff loop for multi-pass repo work
- code source: `bin/ralph-loop-run`
- install path: repo-local CLI tool
- runtime/data path: `/home/sebas/runtime/ralph-loops`
- health check: run dir + state/task files + runner log
- backup class: disposable runtime unless preserving historical audit matters

## laptop helpers
- purpose: remote laptop file/command access over tailnet ssh-over-tcp
- code source: `bin/laptop-*`
- install path: repo-local CLI tools
- runtime/data path: remote host + local mountpoints
- health check: `bin/laptop-run 'uname -a'`
- backup class: repo logic; keys/config must be restorable securely

## wifi tracker API
- purpose: local wifi presence/tracker service
- code source:
  - `bin/wifi-tracker-api.py`
  - `scripts/wifi-tracker-api.service`
  - `scripts/install-wifi-tracker-api-service.sh`
- install path: `wifi-tracker-api.service` via repo installer
- runtime/data path: service-owned runtime/logs
- health check: API responds locally / service active
- backup class: repo logic, runtime disposable unless logs matter

## nginx portal / files exposure
- purpose: expose local apps, files, and portal routes
- code source:
  - `scripts/nginx-kiosk.conf`
  - `scripts/install-nginx-kiosk.sh`
  - repo docs
- install path: `/etc/nginx/sites-available/kiosk` via root installer
- runtime/data path: `/var/www/portal`, proxied local services, `/files/` mapping
- health check: local routes work on `:80`
- backup class: host config must be reconstructable; served content varies by path
- notes:
  - this is host integration, not a Pi concern
  - installer still requires sudo/root

## tmux persistence layer
- purpose: durable PTY for interactive Pi use
- code source:
  - `scripts/tmux.conf`
  - `scripts/pi-shell-helpers.sh`
  - `scripts/install-shell-tmux-helpers.sh`
  - repo docs
- install path: `~/.tmux.conf` and shell rc source block via repo installer
- runtime/data path: tmux sessions
- health check: `pitmux` / `piresume` behavior matches docs
- backup class: must restore config, runtime disposable

---

## Removed legacy personal-agent HTTP service
- former health check: `http://100.116.176.16:8082/api/status`
- status: removed from expected control-plane surface
- former feature surface:
  - status API on `:8082`
  - older runtime readiness/status endpoint shape
- replacement/current reality:
  - `agents-database` is the active shared-memory service
  - Pi extensions, task-phase tooling, and `pi-telegram.service` remain active

## Main gaps
Current biggest portability gaps:
- no single bootstrap script flow yet
- durable backup policy not previously explicit