agent-pager 0.1.0

package/README.md

@@ -0,0 +1,169 @@
+# Agent Pager
+
+**Because people ignore their messages, but not their agents.**
+
+Agent Pager is a secure friend network for paging trusted friends through their active coding agent sessions. The current repo contains the local prototype plus the hosted V1 foundation: Supabase schema/auth/realtime setup, typed database client helpers, safe Vercel config, MCP tools, Codex/Claude skills, and a retro Authorized Human Contact Service web app.
+
+Production V1 is deployed at:
+
+```text
+https://agent-pager.vercel.app
+```
+
+Current launch status: GitHub, Supabase, Vercel production, and the npm CLI package are live.
+
+## Quickstart
+
+Install the CLI:
+
+```bash
+npm install -g agent-pager
+agent-pager login
+agent-pager start
+```
+
+Local prototype:
+
+Terminal 1:
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+Terminal 2:
+
+```bash
+node dist/src/cli.js login --username bryson --local-dev
+node dist/src/cli.js start
+```
+
+Terminal 3, pretending to be a friend:
+
+```bash
+AGENT_PAGER_HOME=/tmp/agent-pager-sarah node dist/src/cli.js login --username sarah --local-dev
+node dist/src/cli.js friends invite
+AGENT_PAGER_HOME=/tmp/agent-pager-sarah node dist/src/cli.js friends add <bryson-invite-url>
+AGENT_PAGER_HOME=/tmp/agent-pager-sarah node dist/src/cli.js page bryson "Can you check the PR?"
+```
+
+Open the web app:
+
+```text
+http://127.0.0.1:8787
+```
+
+Hosted V1 foundation:
+
+```bash
+npm run db:start
+npm run db:types:local
+npm run check
+npm run test:doctor
+npm run test:config
+npm run build
+npm run test:web
+npm run test:mcp
+npm run test:smoke
+npm run test:package
+npm run test:hosted
+```
+
+The hosted foundation includes Vercel-compatible API handlers under `/api` for public config, profiles, public profile links, friend requests, secure device pairing, devices, invites, friends, pages, deliveries, abuse reports, audit events, presence, and health. The retro web app uses Supabase Auth plus those hosted APIs for profile setup, `Page my agent` request-access links, friend invites, page compose/history, report filing, device approvals, and security logs. The tests are local-only and do not push to Supabase cloud or deploy to Vercel.
+
+`agent-pager doctor` is a local-only readiness check for the hosted V1. It verifies the npm package manifest, Vercel Git deployment guard, required environment variables, server signing keypair, local pairing state, Git remote/status, Docker runtime, and cloud-smoke gate without linking Supabase, pushing Git, publishing npm, or deploying Vercel.
+
+`agent-pager launch-check` is the live hosted preflight. It reads GitHub, Supabase, and Vercel state to confirm repo, schema, project, and env readiness before a manual preview deployment.
+
+`agent-pager login` now uses secure hosted device pairing by default. The old local prototype login is still available with `--username` / `--local-dev`.
+
+`agent-pager start` uses Supabase Realtime as the fast path and a signed HTTP polling fallback while it is running. `agent-pager check-pages` remains available for manual recovery or debugging.
+
+The npm package ships the built CLI plus bundled retro web assets. `npm run test:package` dry-runs `npm pack` and verifies the package contents.
+
+After an approved Vercel/Supabase deployment, `npm run cloud-smoke:run -- <vercel-url>` can verify the real hosted flow. The underlying cloud test skips by default and only touches hosted resources when `AGENT_PAGER_CLOUD_SMOKE=1` plus the smoke user credentials are set.
+
+## Commands
+
+```bash
+agent-pager server
+agent-pager login
+agent-pager login --username bryson --local-dev
+agent-pager start
+agent-pager status
+agent-pager share
+agent-pager doctor
+agent-pager launch-check
+agent-pager settings quiet-hours on --start 22:00 --end 08:00 --timezone America/Denver
+agent-pager settings quiet-hours off
+agent-pager settings rate-limit 8
+agent-pager devices list
+agent-pager devices revoke <device-id>
+agent-pager logout
+agent-pager page sarah "Can you review this?"
+agent-pager mute sarah --for 1h
+agent-pager unmute sarah
+agent-pager mutes list
+agent-pager block sarah
+agent-pager unblock sarah
+agent-pager blocks list
+agent-pager report sarah --reason spam
+agent-pager report --page-id <page-id> --reason spam
+agent-pager reports list
+agent-pager friends invite
+agent-pager friends invites
+agent-pager friends revoke-invite <invite-url-or-code>
+agent-pager friends add <invite-url-or-code>
+agent-pager friends request sarah "Page my agent?"
+agent-pager friends requests
+agent-pager friends approve <request-id>
+agent-pager friends deny <request-id>
+agent-pager friends cancel <request-id>
+agent-pager friends list
+agent-pager friends remove <username>
+agent-pager check-pages
+agent-pager setup codex
+agent-pager setup claude
+agent-pager mcp
+```
+
+## Security Model
+
+- Devices generate local Ed25519 keypairs.
+- The service stores public keys only.
+- Device requests are signed with timestamped canonical request signatures.
+- Devices can be revoked from the web dashboard or CLI; revoked devices cannot sign future requests.
+- Page delivery envelopes are signed by the server and verified locally.
+- Pages deliver only between approved friends.
+- Approved friendships can be removed without blocking; removed friends cannot page unless friendship is approved again.
+- Public profiles do not allow arbitrary pages.
+- Pending friend requests can be approved, denied, or canceled before they grant access.
+- Messages are text-only; Agent Pager never lets a remote friend run commands.
+- Per-friend mutes block delivery before a page reaches a local session and can be listed or removed.
+- Blocks prevent friend requests, invite acceptance, approvals, and pages in either direction.
+- Abuse reports can target a username or a page the reporter participated in.
+- Quiet hours block delivery before page rows are created.
+- Invite links expire and can be revoked before use.
+- Rate limits and message length limits protect against spam.
+- Hosted V1 uses Supabase RLS policies and realtime delivery rows instead of exposing raw session lists.
+
+## Agent Integration
+
+`agent-pager setup codex` installs:
+
+- a Codex skill at `~/.codex/skills/agent-pager/SKILL.md`
+- an MCP config block for `agent-pager mcp`
+
+`agent-pager setup claude` installs:
+
+- a Claude skill at `~/.claude/skills/agent-pager/SKILL.md`
+- setup instructions for `claude mcp add agent-pager -- agent-pager mcp`
+
+The MCP server exposes paging, replies, presence, Page my agent sharing, friend-request review, muting, blocking, removal, and abuse-report tools with explicit human-intent wording for access-changing actions.
+
+Claude Code channels are the best future path for true push into an already-running Claude session. The current local listener already receives signed pages, persists them, and sends desktop notifications.
+
+## Design
+
+The web app is inspired by retro authorized-service computing artwork: warm paper, chunky panels, rainbow service stripe, compact operator-console layout, and original Agent Pager branding. It intentionally avoids Apple logos or trademarks.