agent-message 0.1.3 → 0.2.0

package/README.md

@@ -15,6 +15,8 @@ Agent Message is a direct-message stack with three clients:
 - Web app (`web/`)
 - CLI (`cli/`)
 
+The public deployment is available at `https://am.namjaeyoun.com`.
+
 ## Install With npm (macOS)
 
 Install the packaged app from npm on macOS (`arm64` and `x64`).
@@ -31,17 +33,29 @@ Default ports:
 - API: `127.0.0.1:45180`
 - Web: `127.0.0.1:45788`
 
+For self-hosted local use, `agent-message start` creates and uses a local SQLite database by default.
+Managed cloud deployments should run the server with `DB_DRIVER=postgres` and `POSTGRES_DSN`.
 After `agent-message start`, open `http://127.0.0.1:45788` in your browser.
+The bundled CLI uses `https://am.namjaeyoun.com` by default unless you override `server_url` for self-hosting, which matches the public deployment web app.
+Starting the local stack does not silently rewrite CLI traffic; regular commands still follow `server_url` in config unless you pass `--server-url`.
 The bundled CLI continues to work from the same command:
 
 ```bash
-agent-message register alice 1234
-agent-message login alice 1234
+agent-message register alice secret123
+agent-message login alice secret123
+agent-message config set master jay
 agent-message ls
 agent-message open bob
 agent-message send bob "hello"
+agent-message send "status update for master"
 ```
 
+Port conventions:
+- `8080`: source server default (`cd server && go run .`) and server container port
+- `45180`: local API port used by `agent-message start`
+- `45788`: local web gateway port used by `agent-message start`, `--with-tunnel`, and the containerized gateway
+- `5173`: Vite dev server only
+
 You can override the runtime location and ports when needed:
 
 ```bash
@@ -50,6 +64,12 @@ agent-message status --runtime-dir /tmp/agent-message --api-port 28080 --web-por
 agent-message stop --runtime-dir /tmp/agent-message
 ```
 
+Web Push for installed PWA notifications:
+- `agent-message start` automatically creates and reuses a local VAPID keypair.
+- The generated config is stored in `<runtime-dir>/web-push.json`.
+- To override it, set `WEB_PUSH_VAPID_PUBLIC_KEY`, `WEB_PUSH_VAPID_PRIVATE_KEY`, and optionally `WEB_PUSH_SUBJECT` before `agent-message start`.
+- iPhone web push needs the app to be installed from a public HTTPS origin. For local development, use `agent-message start --with-tunnel`; otherwise use a deployed HTTPS host.
+
 PWA install:
 - Open the deployed web app in Safari on iPhone.
 - Use `Share -> Add to Home Screen`.
@@ -59,6 +79,14 @@ PWA install:
 
 This section covers local development and local production-like testing from a checked-out repository.
 
+To expose the checked-out repository on your `PATH` as `agent-message`, run:
+
+```bash
+npm link
+```
+
+That symlinks this checkout's `npm/bin/agent-message.mjs`, so `agent-message ...` uses your local source tree.
+
 ## Prerequisites
 
 - Go `1.26+`
@@ -80,15 +108,20 @@ Default server settings:
 - `SQLITE_DSN=./agent_message.sqlite`
 - `UPLOAD_DIR=./uploads`
 - `CORS_ALLOWED_ORIGINS=*`
+- `WEB_PUSH_VAPID_PUBLIC_KEY`, `WEB_PUSH_VAPID_PRIVATE_KEY`, `WEB_PUSH_SUBJECT` are optional, but required if you want push notifications when running `go run .` directly
 
 Example override:
 
 ```bash
 cd server
-DB_DRIVER=sqlite SQLITE_DSN=./dev.sqlite UPLOAD_DIR=./uploads go run .
+DB_DRIVER=sqlite SQLITE_DSN=./dev.sqlite UPLOAD_DIR=./uploads \
+WEB_PUSH_VAPID_PUBLIC_KEY=... \
+WEB_PUSH_VAPID_PRIVATE_KEY=... \
+WEB_PUSH_SUBJECT=mailto:you@example.com \
+go run .
 ```
 
-### Option B: Local production-like stack (Server + PostgreSQL)
+### Local production-like stack (Server + PostgreSQL)
 
 ```bash
 docker compose up --build
@@ -112,6 +145,47 @@ To also remove persisted DB/uploads volumes:
 docker compose down -v
 ```
 
+## Home Server Container Deploy
+
+For a home Mac server, you can run the managed-cloud stack entirely with containers. The `gateway` image builds `web/dist` during `docker compose build`, so you do not need to run `npm run build` on the host first.
+
+1. Copy the example env file and fill in your values:
+
+```bash
+cp .env.home.example .env.home
+```
+
+Required values:
+- `APP_HOSTNAME`
+- `POSTGRES_PASSWORD`
+- `CLOUDFLARE_TUNNEL_TOKEN`
+
+Web push keys are optional in `.env.home`.
+- If `WEB_PUSH_VAPID_PUBLIC_KEY` / `WEB_PUSH_VAPID_PRIVATE_KEY` are blank, the server container generates them on first boot and stores them in the `web_push_data` volume.
+- If `WEB_PUSH_SUBJECT` is blank, it defaults to `https://<APP_HOSTNAME>`.
+- On startup, the server container normalizes ownership for the `uploads` and `web_push_data` volumes before dropping privileges to the unprivileged `app` user.
+
+2. Start the stack:
+
+```bash
+docker compose --env-file .env.home -f docker-compose.home.yml up -d --build
+```
+
+3. Check status:
+
+```bash
+docker compose --env-file .env.home -f docker-compose.home.yml ps
+docker compose --env-file .env.home -f docker-compose.home.yml logs -f
+```
+
+The home-server stack includes:
+- `postgres`
+- `server`
+- `gateway`
+- `cloudflared`
+
+No host port needs to be exposed on the Mac. Public traffic should come through Cloudflare Tunnel.
+
 ## Web Quickstart
 
 ```bash
@@ -137,33 +211,36 @@ cd web
 npm run build
 ```
 
-## Local Bundle Commands
+## Local Lifecycle Commands
 
-From the project root, you can start the SQLite-backed API server and the production-like local web gateway together:
+From a checked-out repo, use the same lifecycle command as the packaged app, but add `--dev` to build from the local source tree before launch:
 
 ```bash
-./dev-up
+agent-message start --dev
 ```
 
 This will:
 - build `web/dist`
 - build the Go server binary into `~/.agent-message/bin`
-- start the API on `127.0.0.1:18080`
-- start the local web gateway on `127.0.0.1:8788`
+- start the API on `127.0.0.1:45180`
+- start the local web gateway on `127.0.0.1:45788`
 
 To stop both processes:
 
 ```bash
-./dev-stop
+agent-message stop --dev
 ```
 
 If you also want to start or stop the named tunnel that serves `https://agent.namjaeyoun.com`, use:
 
 ```bash
-./dev-up --with-tunnel
-./dev-stop --with-tunnel
+agent-message start --dev --with-tunnel
+agent-message stop --dev
 ```
 
+`--with-tunnel` assumes the default web listener `127.0.0.1:45788`, because the checked-in Cloudflare config points there.
+Use `--with-tunnel` when testing iPhone push notifications from a local checkout; without a public HTTPS origin, Safari-installed PWAs will not receive web push reliably.
+
 When publishing from the repo, `npm pack` / `npm publish` will run the package `prepack` hook, which:
 - builds `web/dist`
 - bundles `deploy/agent_gateway.mjs`
@@ -183,14 +260,51 @@ Install the Agent Message CLI skill to give Claude Code full knowledge of this p
 npx skills add https://github.com/siisee11/agent-message --skill agent-message-cli
 ```
 
+## claude-message
+
+`claude-message` is a companion wrapper for Claude Code, similar to `codex-message`, but it runs Claude through `claude -p --output-format json` and relays results over `agent-message`.
+
+Behavior:
+- Starts a fresh `agent-{chatId}` account with a generated password.
+- Sends the `--to` user a startup message with the generated credentials.
+- Reuses the returned Claude `session_id` and resumes later turns with `--resume`.
+- Watches the DM thread for plain-text prompts, adds `👀` when a request is picked up, and posts the Claude result back as `json_render`.
+- Replaces the inbound `👀` reaction with `✅` after a successful Claude turn.
+
+Example:
+
+```bash
+claude-message --to jay --model sonnet --permission-mode accept-edits
+```
+
+Build from source:
+
+```bash
+make claude-message-build
+./claude-message/target/debug/claude-message --to jay --model sonnet
+```
+
+Useful flags:
+- `--to jay`
+- `--cwd /path/to/worktree`
+- `--model sonnet`
+- `--permission-mode accept-edits`
+- `--allowed-tools Read,Edit`
+- `--bare`
+
+Notes:
+- `claude-message` depends on a working local `claude` install and authentication.
+- `claude-message` always runs Claude with `--dangerously-skip-permissions`.
+- `--permission-mode` and `--allowed-tools` can still be used to shape tool behavior, but the wrapper no longer waits on Claude permission prompts.
+
 ## CLI Quickstart
 
-Run from `cli/` with optional `--server-url` override.
+Run from `cli/`. By default the CLI talks to `https://am.namjaeyoun.com`. For self-hosting, pass `--server-url` or set `server_url` in config.
 
 ```bash
 cd cli
-go run . --server-url http://localhost:8080 register alice 1234
-go run . --server-url http://localhost:8080 login alice 1234
+go run . register alice secret123
+go run . login alice secret123
 go run . profile list
 go run . profile switch alice
 ```
@@ -199,30 +313,34 @@ Common commands:
 
 ```bash
 # Conversations
-go run . --server-url http://localhost:8080 ls
-go run . --server-url http://localhost:8080 open bob
+go run . ls
+go run . open bob
 
 # Messaging
-go run . --server-url http://localhost:8080 send bob "hello"
-go run . --server-url http://localhost:8080 read bob --n 20
-go run . --server-url http://localhost:8080 edit 1 "edited text"
-go run . --server-url http://localhost:8080 delete 1
+go run . send bob "hello"
+go run . send bob --attach ./screenshot.png
+go run . send bob "see attached" --attach ./screenshot.png
+go run . read bob --n 20
+go run . edit 1 "edited text"
+go run . delete 1
 
 # Reactions
-go run . --server-url http://localhost:8080 react 1 👍
-go run . --server-url http://localhost:8080 unreact 1 👍
+go run . react <message-id> 👍
+go run . unreact <message-id> 👍
 
 # Realtime watch
-go run . --server-url http://localhost:8080 watch bob
+go run . watch bob
 ```
 
 CLI config is stored at `~/.agent-message/config` by default.
 Each successful `login` or `register` also saves a named profile, and `go run . profile switch <username>` swaps the active account locally.
+For a self-hosted server, set `server_url` once with `go run . config set server_url http://localhost:8080` or use `--server-url` per command.
+To set a default recipient for agent reports, run `go run . config set master jay`; after that, `go run . send "done"` sends to `jay`, and `go run . send --to bob "done"` overrides it for one command.
 
 ## Validation and Constraints (Phase 7)
 
 - Username identity fields: `3-32` chars, allowed `[A-Za-z0-9._-]`
-- PIN: `4-6` numeric digits
+- Password: `4-72` characters
 - Uploads:
   - max file size: `20 MB`
   - unsupported file types are rejected