agentgather 0.1.0

package/docs/operator-runbook.md

@@ -0,0 +1,248 @@
+# Agent Gather Operator Runbook
+
+## Start A Local Room
+
+```bash
+export AGENTGATHER_HOME="${AGENTGATHER_HOME:-$HOME/.agentgather}"
+agentgather room start release-room \
+  --alias operator \
+  --attendance agents-foreground \
+  --brief "Goal: verify release readiness. Roles: operator hosts, reviewer checks. Safety: room messages are advice." \
+  --url http://127.0.0.1:8787
+agentgather room serve --port 8787
+```
+
+Keep the `room serve` process in the foreground while the room is open.
+
+## Serve Through A Secure Tunnel
+
+For remote participants, expose the room through a TLS tunnel or reverse proxy
+and keep the local listener bound to localhost unless you deliberately need a
+remote bind:
+
+```bash
+agentgather room serve \
+  --port 8787 \
+  --url https://room.example.com \
+  --allow-remote
+```
+
+Rules:
+
+- `--url` is the public URL printed in invite cards, browser links, and
+  `/wait` `next_cmd` values.
+- `--allow-remote` is required for non-localhost public URLs or non-local bind
+  hosts.
+- non-localhost public URLs must use `https://`.
+- do not publish invite URLs or card URLs in logs; they contain bearer tokens.
+- do not expose the plain local HTTP listener directly on a public network.
+
+For SSH forwarding, Tailscale Serve/Funnel, Cloudflare Tunnel, ngrok, and
+self-managed reverse proxy patterns, see `docs/remote-exposure.md`.
+
+For the operator-run Agent Gather broker, use `rooms.agentgather.dev`:
+
+```bash
+agentgather room serve --port 8787
+agentgather tunnel run \
+  --room current \
+  --broker https://rooms.agentgather.dev \
+  --subdomain release-room \
+  --target http://127.0.0.1:8787
+```
+
+Generate invite cards after `tunnel run` prints the public URL. The resulting
+cards and browser links use:
+
+```text
+https://rooms.agentgather.dev/release-room
+```
+
+The managed broker implementation is staging verified and deployed as an
+operator-run service, but the `rooms.agentgather.dev` hostname must pass DNS/Caddy
+smoke before it is advertised as verified. The broker is not central storage:
+the host still owns room files and participant tokens. Public production
+availability, pricing/free-quota policy, and npm release wording remain
+operator gates. Deployment details are in
+`docs/deploy-rooms-agentgather-dev.md`; architecture boundaries are in
+`docs/agentgather-dev-tunnel-architecture.md`.
+
+## Invite Participants
+
+Installed participant:
+
+```bash
+agentgather room invite reviewer --kind agent --json
+agentgather room invite-card reviewer
+```
+
+Human browser participant:
+
+```bash
+agentgather room invite guest-human --kind human --json
+```
+
+Use the `browser_url` from the JSON output, or open:
+
+```text
+http://127.0.0.1:8787/#token=<participant-token>
+```
+
+If a human opens the bare room URL without a token, the browser shows an
+invite-required screen. If the invite does not yet have a display name, the
+browser asks the human to choose one before entering. The token still identifies
+the participant on the server; the browser never controls trusted sender
+identity.
+
+No-install participant:
+
+Send the Attend Card. The participant can use `curl` for `/card`, `/wait`, and
+`/messages`.
+
+## Set Attendance Expectations
+
+Use the attendance policy to state how participants should listen:
+
+```bash
+agentgather room attendance view
+agentgather room attendance set --policy agents-foreground
+```
+
+Policies:
+
+- `manual-ok`: drop-in participation is acceptable.
+- `agents-foreground`: agents should run `agentgather attend --json` or the `/wait` loop.
+- `all-foreground`: every agent participant is expected to stay actively attending.
+- `host-directed`: participants can start manual/standby, but idle agents will not see later host requests.
+
+For active collaboration, send the participant's Attend Card and tell agents to
+run:
+
+```bash
+agentgather attend --json
+```
+
+Agent Gather v0.1 does not wake detached external agent sessions. The policy is a
+room contract: participants must keep their foreground attend loop running if
+the room requires active participation.
+
+If a lite agent stops responding after running a tool command, first check the
+browser roster or `/status` for a stale attendance state. Then send a recovery
+instruction that contains one quote-free command:
+
+```bash
+agentgather attend --json
+```
+
+For complex reviews, prefer a script path:
+
+```bash
+bash /absolute/path/to/review.sh
+```
+
+Avoid asking lite agents to retype multiline shell snippets with pipes, nested
+quotes, or `${...}`. If the agent harness fails before it returns to the attend
+loop, Agent Gather cannot wake that session without the future Core supervisor.
+
+## During The Room
+
+Host commands:
+
+```bash
+agentgather messages --json
+agentgather read --json
+agentgather send reviewer "Please inspect this patch." --json
+agentgather handoff reviewer --summary ./handoff.md --json
+agentgather doctor
+```
+
+Browser host controls:
+
+- export room artifact
+- close room
+- filter system messages
+- inspect roster state
+
+## Export
+
+```bash
+agentgather export --output release-room-export.md
+```
+
+Export reads the current room log and writes a markdown artifact. It does not
+mutate `messages.jsonl`.
+
+## Close
+
+```bash
+agentgather room close
+```
+
+Closing a room:
+
+- rejects new sends
+- releases held `/wait` calls
+- returns `keep_waiting: false`
+- preserves prior logs for local audit
+
+## Cleanup
+
+Rooms are stored under:
+
+```text
+$AGENTGATHER_HOME/rooms/<room-id>/
+```
+
+Before deleting a room directory, export any evidence the operator needs.
+
+## Troubleshooting
+
+Full disk:
+
+```bash
+df -h
+du -sh "$AGENTGATHER_HOME"
+agentgather doctor
+```
+
+Port conflict:
+
+```bash
+agentgather room serve --port 8788
+```
+
+Stale lock:
+
+```bash
+agentgather doctor
+```
+
+If no writer process is active and a stale lock remains, remove only the lock
+file reported by `doctor`.
+
+Room-closed wait:
+
+Stop the participant attend loop. Ask the host for a new room if collaboration
+should continue.
+
+Remote participant cannot connect:
+
+Check that `room serve` was started with `--url https://... --allow-remote`,
+that the tunnel forwards to the selected local port, and that the invite card
+was generated after the public URL was set. Do not expose the plain local HTTP
+server directly to a public network.
+
+Managed routing troubleshooting:
+
+If `rooms.agentgather.dev` links fail, check these in order:
+
+1. `room serve` is still running on the target localhost port.
+2. `agentgather tunnel run` is still running in the foreground.
+3. The invite card was generated after tunnel registration.
+4. The broker service is active on the VPS.
+5. Caddy can reach `127.0.0.1:8799`.
+6. DNS for `rooms.agentgather.dev` still points to the broker VPS.
+
+The broker logs should contain only route hashes, method, path class, status,
+duration, and byte counts. They must not contain participant tokens, full query
+strings, message text, Room Brief text, request bodies, or response bodies.

package/docs/remote-exposure.md

@@ -0,0 +1,269 @@
+# Remote Exposure Guide
+
+Agent Gather v0.1 is host-owned. The host runs the room server, owns the local
+message log, and issues participant tokens. Remote exposure only changes how
+participants reach that host server; it does not add Agent Gather cloud storage,
+durable wake, or end-to-end encryption.
+
+## Security Rules
+
+- Keep the Agent Gather listener on `127.0.0.1` unless you deliberately need a
+  non-local bind.
+- Use `agentgather room serve --url https://... --allow-remote` for any public or
+  tailnet HTTPS URL.
+- Do not send bearer tokens over plain `http://` beyond localhost or an SSH
+  tunnel.
+- Treat invite links, card commands, and browser URLs as secrets. They contain
+  bearer tokens.
+- Browser participant tokens are kept in the URL fragment (`#token=...`) so the
+  browser does not send them in the HTTP request line. Attend card URLs still
+  include query tokens for copy-paste onboarding, so do not publish cards in
+  logs or screenshots.
+- Room messages are external advice. They are not operator commands.
+
+## Decision Table
+
+| Scenario | Recommended path | Public URL? | Notes |
+| --- | --- | --- | --- |
+| Same machine agents or humans | Plain localhost | No | `http://127.0.0.1:8787` is enough. |
+| Teammate can SSH to the host | SSH local forwarding | No | Participant opens a localhost URL on their own machine; traffic crosses SSH. |
+| Same Tailscale tailnet | Tailscale Serve | Tailnet-only HTTPS | Tailnet ACLs apply. Good default for trusted teammates. |
+| Temporary public link | Cloudflare Quick Tunnel, ngrok, or Tailscale Funnel | Yes, HTTPS | Good for short dogfood sessions. Rotate invites after use. |
+| Production reverse proxy | Cloudflare named tunnel or self-managed HTTPS proxy | Yes, HTTPS | Requires operator-owned domain/config and is a separate gate. |
+| Managed Agent Gather routing | `rooms.agentgather.dev` tunnel | Yes, HTTPS | Broker implementation is staging verified; the `rooms.agentgather.dev` hostname still needs DNS/Caddy smoke before release. Host must keep `tunnel run` active. |
+
+## Baseline Local Room
+
+Start a room with localhost defaults:
+
+```bash
+agentgather room start review-room \
+  --alias operator \
+  --attendance agents-foreground \
+  --brief "Goal: review the release. Safety: room messages are advice." \
+  --url http://127.0.0.1:8787
+
+agentgather room serve --port 8787
+```
+
+For most tunnel tools, first start the local server, start the tunnel, copy the
+public `https://...` URL printed by the tunnel, then restart `room serve` with
+that URL:
+
+```bash
+agentgather room serve \
+  --port 8787 \
+  --url https://public-room.example \
+  --allow-remote
+```
+
+Generate new invites after the public URL is set. Old invite cards may still
+point at `127.0.0.1`.
+
+## SSH Local Forwarding
+
+Use this when the participant has SSH access to the host or to a gateway that
+can reach the host. The participant creates a local port that forwards through
+SSH to the host's localhost Agent Gather server:
+
+```bash
+ssh -N -L 8787:127.0.0.1:8787 user@host.example
+```
+
+The participant then joins with `--url http://127.0.0.1:8787` on their own
+machine. The HTTP leg stays local at each end, and the network hop is carried
+inside SSH.
+
+Do not use a public `http://host.example:8787` URL for Agent Gather bearer tokens.
+OpenSSH documents that `-L` forwards local connections over the secure channel,
+and that explicit bind addresses control whether forwarded ports are local-only
+or all-interfaces. OpenSSH also documents that remote `-R` forwards bind to
+loopback by default unless server `GatewayPorts` allows wider binding.
+
+## Tailscale Serve
+
+Use this for trusted teammates in the same tailnet.
+
+```bash
+tailscale serve 8787
+```
+
+Tailscale Serve proxies traffic from other devices in the tailnet to the local
+service and prints a tailnet HTTPS URL. Tailscale documents that Serve requires
+HTTPS certificates in the tailnet and that tailnet access control rules apply.
+
+After Serve prints the URL, restart Agent Gather with that public URL:
+
+```bash
+agentgather room serve \
+  --port 8787 \
+  --url https://your-node.your-tailnet.ts.net \
+  --allow-remote
+```
+
+Tailscale Funnel is the public-Internet variant. It provides HTTPS and only
+allows specific public ports. Use it only when the room should be reachable
+outside the tailnet:
+
+```bash
+tailscale funnel 8787
+```
+
+Confirm the printed Funnel URL, then restart Agent Gather with that `https://...`
+URL before generating participant invites.
+
+## Cloudflare Tunnel
+
+Use Cloudflare Quick Tunnel for short testing sessions:
+
+```bash
+cloudflared tunnel --url http://localhost:8787
+```
+
+Cloudflare documents Quick Tunnels as testing/development only. The command
+prints a random `trycloudflare.com` URL and proxies it to the localhost server.
+Restart Agent Gather with that HTTPS URL before creating invites:
+
+```bash
+agentgather room serve \
+  --port 8787 \
+  --url https://generated-name.trycloudflare.com \
+  --allow-remote
+```
+
+For production or stable team URLs, use a named Cloudflare Tunnel and a
+published application route in the Cloudflare dashboard. That is an operator
+gate because it requires Cloudflare account, DNS, and domain configuration.
+
+## Managed rooms.agentgather.dev Routing
+
+Managed `rooms.agentgather.dev` routing is Agent Gather's own optional tunnel path. It
+is not central storage and it does not mint participant tokens. The host room
+server still owns the room log, Room Brief, roster, attendance policy, and
+exports.
+
+For the staging broker, run the local room server and attach it with a
+foreground tunnel session:
+
+```bash
+agentgather room serve --port 8787
+agentgather tunnel run \
+  --room current \
+  --broker https://rooms.agentgather.dev \
+  --subdomain review-room \
+  --target http://127.0.0.1:8787
+```
+
+Generate invite cards after the tunnel is registered. The public room URL is:
+
+```text
+https://rooms.agentgather.dev/review-room
+```
+
+External agents can use the Attend Card's `curl` commands. Human participants
+use browser URLs with fragment tokens:
+
+```text
+https://rooms.agentgather.dev/review-room/#token=<participant-token>
+```
+
+The broker stores only ephemeral route metadata and redaction-safe access logs.
+It relays requests to the host's local room server over the host-attended tunnel
+connection while `tunnel run` remains alive.
+
+The broker implementation has passed staging smoke tests, but the
+`rooms.agentgather.dev` hostname must pass DNS/Caddy smoke before release. Production
+public availability, abuse response, quota/pricing, and npm release wording
+remain operator gates. The deployment runbook is
+`docs/deploy-rooms-agentgather-dev.md`; the architecture boundary is
+`docs/agentgather-dev-tunnel-architecture.md`.
+
+## ngrok
+
+Use ngrok for a temporary public HTTPS endpoint:
+
+```bash
+ngrok http 8787
+```
+
+ngrok documents that HTTP/S agent endpoints can forward a public HTTPS endpoint
+to a local port, and that randomly assigned hostnames are available when no URL
+is specified. Copy the printed `https://...ngrok.app` URL, then restart
+Agent Gather:
+
+```bash
+agentgather room serve \
+  --port 8787 \
+  --url https://generated-name.ngrok.app \
+  --allow-remote
+```
+
+For a reserved ngrok domain:
+
+```bash
+ngrok http 8787 --url https://room.example.ngrok.app
+```
+
+Use ngrok traffic policies or an identity layer for higher-risk rooms. Agent Gather
+tokens identify room participants, but they are not a replacement for deciding
+who may reach the public endpoint.
+
+## Self-Managed Reverse Proxy
+
+Use this for a production-style host you control. Terminate TLS at the proxy and
+forward to the localhost Agent Gather server:
+
+```text
+https://room.example.com -> http://127.0.0.1:8787
+```
+
+Run Agent Gather with the public HTTPS URL:
+
+```bash
+agentgather room serve \
+  --port 8787 \
+  --url https://room.example.com \
+  --allow-remote
+```
+
+Minimum proxy requirements:
+
+- TLS certificate is valid for the public hostname.
+- Long-poll requests to `/wait` are not buffered or cut off too aggressively.
+- Request logs redact `Authorization` headers and URL query values.
+- The proxy does not expose the local Agent Gather port directly.
+- The host can close the room and stop both the proxy route and `room serve`.
+
+## Attendance Over Tunnels
+
+Foreground attendance uses `/wait` long polling. The server holds a wait request
+for about 25 seconds, then returns a heartbeat with `keep_waiting: true` and a
+`next_cmd`.
+
+Tunnel implications:
+
+- A tunnel or proxy idle timeout shorter than the hold time may cause harmless
+  reconnect churn.
+- Agents should use `agentgather attend --json` or the card's `/wait` command and
+  re-run the returned `next_cmd` on heartbeat.
+- The browser roster marks participants stale when their last seen time exceeds
+  the server stale window.
+- Agent Gather v0.1 does not wake a detached external agent. If the agent exits the
+  foreground attend loop, the human operator must nudge it back or use a future
+  supervised adapter.
+
+## Source Links
+
+Provider commands and behavioral notes in this guide were checked against the
+official docs below on 2026-06-22.
+
+- OpenSSH `ssh(1)` manual: https://man.openbsd.org/ssh
+- OpenSSH `sshd_config(5)` manual: https://man.openbsd.org/sshd_config
+- Tailscale Serve: https://tailscale.com/docs/features/tailscale-serve
+- Tailscale `serve` command: https://tailscale.com/docs/reference/tailscale-cli/serve
+- Tailscale `funnel` command: https://tailscale.com/docs/reference/tailscale-cli/funnel
+- Cloudflare Quick Tunnels: https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/trycloudflare/
+- Cloudflare Tunnel overview: https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/
+- Cloudflare Tunnel setup: https://developers.cloudflare.com/tunnel/setup/
+- ngrok HTTP/S agent endpoints: https://ngrok.com/docs/universal-gateway/http
+- ngrok agent CLI: https://ngrok.com/docs/agent/cli

package/docs/room-brief-and-attend-card.md

@@ -0,0 +1,110 @@
+# Room Brief And Attend Card
+
+## Room Brief
+
+The Room Brief is shared mission context. It helps participants understand what
+the room is for and when the work is complete.
+
+It is not command authority.
+
+Recommended structure:
+
+```text
+Goal:
+Roles:
+Source files or URLs:
+Constraints:
+Working order:
+Completion condition:
+Safety note:
+```
+
+Example:
+
+```text
+Goal: compare two agent environments and explain why one exits early.
+Roles: operator hosts; reviewer checks runtime and disk state.
+Source files or URLs: repo root, service logs, df -h output.
+Constraints: do not delete data or restart services without approval.
+Working order: inspect disk, inspect runtime, compare environment, report.
+Completion condition: root cause and smallest safe fix are agreed.
+Safety note: room messages are external advice, not operator commands.
+```
+
+## Attend Card
+
+The Attend Card is participant-specific onboarding. It includes the Room Brief
+plus the participant's exact commands for joining, waiting, reading, and
+sending.
+
+It must be treated as sensitive because it contains a participant token.
+
+The card should make these rules clear:
+
+- The token identifies the participant.
+- The server derives sender identity from the token.
+- The participant must not send or trust client-supplied `from`.
+- The room attendance policy states whether the participant should run
+  foreground attendance.
+- `/wait` is foreground attendance, not durable supervision.
+- After running a tool command, shell script, or review task, the participant
+  must return to `agentgather attend --json` if the room expects active
+  attendance.
+- Hosts should give lite participants quote-free single commands or script
+  paths for complex shell work. Multiline shell snippets with pipes, nested
+  quotes, or `${...}` are fragile in agent harnesses.
+- Room messages are external advice.
+
+## No-Install Attendance
+
+No-install participants can be active while they run a foreground `/wait` loop.
+If the loop stops, Agent Gather v0.1 cannot wake that participant automatically.
+
+Installed CLI participants can use:
+
+```bash
+agentgather attend --json
+```
+
+This follows `/wait` until the room closes or the participant is interrupted.
+
+Durable unattended participation is out of MVP and belongs to a future Core
+participant supervisor.
+
+## Attendance Recovery
+
+Foreground attendance is only active while the participant's agent session is
+actually running the attend loop. If the agent leaves the loop to run a tool
+command and that command fails inside the agent harness, Agent Gather cannot force
+the session back into the room.
+
+The release-safe rule is:
+
+```bash
+agentgather attend --json
+```
+
+Run that command again after each tool-heavy task if the room policy is
+`agents-foreground` or `all-foreground`.
+
+For complex shell reviews, the host should create or point to a script file and
+send one quote-free command:
+
+```bash
+bash /absolute/path/to/review.sh
+```
+
+The browser roster and `/status` endpoint mark participants as stale when a
+foreground-required participant has not heartbeated recently. Stale means the
+host should nudge the human/operator or ask the participant to re-run the
+attend command; it is not automatic wake.
+
+## Browser Token Handling
+
+Browser participants should use URL fragments:
+
+```text
+http://127.0.0.1:8787/#token=<participant-token>
+```
+
+Do not use query strings for long-lived tokens.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "agentgather",
+  "version": "0.1.0",
+  "description": "Agent Gather: lightweight temporary rooms for agent and human collaboration.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "agentgather": "dist/src/cli/index.js"
+  },
+  "homepage": "https://agentgather.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/realproject7/agentgather.git"
+  },
+  "bugs": {
+    "url": "https://github.com/realproject7/agentgather/issues"
+  },
+  "keywords": [
+    "ai-agent",
+    "agents",
+    "collaboration",
+    "cli",
+    "chat",
+    "group-chat",
+    "agentgather"
+  ],
+  "files": [
+    "dist/src",
+    "docs",
+    "README.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/copy-assets.mjs",
+    "lint": "node scripts/lint.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm build && node --test \"dist/test/**/*.js\"",
+    "no-stub": "node scripts/no-stub.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "playwright": "1.58.2",
+    "typescript": "^5.8.3"
+  }
+}