@av-pi-studio/server 0.0.10 → 0.0.12

package/README.md

@@ -125,16 +125,34 @@ curl http://127.0.0.1:6767/api/health
 
 ### Dev daemon
 
-`src/daemon/dev-main.ts` is a development entry that wires the full feature surface and binds
-`0.0.0.0` with developer-friendly defaults. From the root:
+`src/daemon/dev-main.ts` is a development entry that wires only a **minimal handler subset**
+(`dev-bootstrap.ts`: agent list/archive/delete, workspaces/projects listing, providers, file
+read/diff, schedule listing — no terminals, git ops, worktrees, chat, loops, or relay), the mock
+provider, and in-memory state, and binds `0.0.0.0` with developer-friendly defaults. From the root:
 
 ```bash
 npm run dev:daemon
 ```
 
-> The production `bootstrap.ts` and dev `dev-bootstrap.ts` both register the full RPC surface;
-> `bootstrap.ts` is production-grade (real provider, disk persistence, config loading) while
-> `dev-bootstrap.ts` is for local testing and **must never be imported by `bootstrap.ts`**.
+> `bootstrap.ts` (production) registers the **full** RPC surface — agents, terminals, git/worktrees/
+> GitHub, files, service proxy, schedules/chat/loops, rewind, optional outbound relay — with the
+> real provider and disk persistence. `dev-bootstrap.ts` stays intentionally minimal for fast local
+> iteration and **must never grow to duplicate that surface**; `bootstrap.ts` must never import
+> `dev-bootstrap.ts` (the reverse — `dev-bootstrap.ts` importing one shared helper,
+> `wrapSessionEnvelope`, from `bootstrap.ts` — is fine and is what happens today).
+
+### Docker
+
+A production daemon image (multi-stage, compiles the native `node-pty` addon, ships `git` + the
+bundled `pi` runtime) lives at `docker/daemon.Dockerfile`, with a compose file that also runs the
+relay. From the repo root:
+
+```bash
+cd docker && docker compose up --build   # daemon :6767 + relay :7000
+```
+
+`$PI_STUDIO_HOME` is `/data` (mount a volume); bind-mount your projects at `/workspace`. See
+`docker/README.md` for the full env/volume/auth/security matrix.
 
 ---
 
@@ -156,6 +174,7 @@ All optional.
 | `PI_STUDIO_PASSWORD` | _(unset)_ | Require this password for connections (bcrypt-checked) |
 | `PI_STUDIO_HOSTNAMES` | `localhost,*.localhost` | Allowed `Host` header values (comma-separated, or `true` to allow all) |
 | `PI_STUDIO_SERVER_ID` | _(persisted/generated)_ | Stable server identity |
+| `PI_STUDIO_RELAY_ENABLED` | `false` | Opt into the outbound relay dial (env equivalent of `daemon.relay.enabled`; `1`/`true`/`yes`/`on`) |
 | `PI_STUDIO_RELAY_ENDPOINT` | _(unset)_ | Relay server to dial outbound to when `daemon.relay.enabled` (`host:port`) |
 | `PI_STUDIO_RELAY_USE_TLS` | `false` | Use `wss://` for the outbound relay dial (`1`/`true`/`yes`/`on`) |
 | `PI_STUDIO_RELAY_PUBLIC_ENDPOINT` | _(unset)_ | Client-facing relay address, if different from the daemon's own dial target |
@@ -163,6 +182,7 @@ All optional.
 | `PI_STUDIO_SERVICE_PROXY_LISTEN` | _(unset)_ | Service-proxy listen address |
 | `PI_STUDIO_SERVICE_PROXY_PUBLIC_BASE_URL` | _(unset)_ | Public base URL advertised for proxied services |
 | `PI_STUDIO_SERVICE_PROXY_ENABLED` | _(unset)_ | Enable the service proxy (`1`/`true`/`yes`/`on`) |
+| `PI_STUDIO_APP_BASE_URL` | `https://app.pi-studio.sh` | Pairing link origin (`daemon pair`) — set to your own web-client URL for self-hosted/local pairing |
 
 > Literal IP addresses always pass the Host allowlist, so binding `0.0.0.0` and connecting via the
 > server's IP needs no extra config. To reach the daemon by **hostname**, add it to
@@ -210,11 +230,24 @@ extend the `pi` provider via `"extends": "pi"` (a custom provider must also set
 
 **Relay (opt-in, off by default):** with `daemon.relay.enabled: true`, the daemon dials outbound
 to the `endpoint` (a self-hosted `@av-pi-studio/relay` server or Cloudflare Workers deployment)
-after the WS server is up, so remote clients can reach it without an inbound port. See
+after the WS server is up, so remote clients can reach it without an inbound port. It registers
+under a **deterministic** rendezvous session id derived from its own persistent public key
+(`deriveRelaySessionId`, `@av-pi-studio/relay`) — the same id on every (re)connect, so a pairing
+link printed once (`pi-studio daemon pair`) keeps working across relay drops/restarts. See
 `@av-pi-studio/relay`'s README for running a relay (`pi-studio-relay` bin / `pi-studio relay
 start`). Direct WebSocket connections are completely unaffected either way — the relay only adds
 an additional connection path.
 
+The same pairing link can be opened by any number of clients over the daemon's lifetime — each
+one gets its own fresh E2EE handshake and its own daemon-side `Session` (see `relay-transport.ts`'s
+`onHandshake` → `bootstrap.ts`'s `resetRelaySession()`); connecting a second client after a first
+one disconnected is a normal, supported reconnection, not a re-pairing.
+
+Terminal I/O and file-transfer chunks work over a relay connection too — the daemon and client
+encrypt binary application data as the relay channel's `e2ee_bin` frame (a base64-wrapped JSON
+text frame, not a raw binary WebSocket frame; see `@av-pi-studio/relay`'s README § Wire protocol),
+so no daemon or web-client feature is direct-connection-only.
+
 ---
 
 ## The wire API
@@ -301,17 +334,19 @@ All state lives under `$PI_STUDIO_HOME/`. Every write goes through `AtomicStore`
 (write-to-temp-then-rename) for crash safety.
 
 ```
-config.json                      Daemon config (password hash, provider overrides, service proxy, …)
-server-id                        Stable server identity
+config.json                      Daemon config (password hash, provider overrides, relay, service proxy, …)
+pi-studio.pid                    PID lock (prevents a second daemon owning this home)
+server-id                        Stable server identity (plain UUID via randomUUID())
+daemon-keypair.json              Persistent Curve25519 keypair (pairing / outbound relay E2EE)
 logs/                            Rotating NDJSON log files (pino)
 agents/
   <sanitized-cwd>/
     <agentId>.json               Agent record (status, config, timeline seq, labels, …)
 chat/rooms.json                  Chat rooms + messages
-loops/<loopId>.json              Loop records
+loops/loops.json                 ALL loop records (single queued-write file, NOT one file per loop)
 schedules/<scheduleId>.json      Schedule records
-projects.json                    Project registry
-workspaces.json                  Workspace registry
+projects/projects.json           Project registry
+projects/workspaces.json         Workspace registry
 ```
 
 All entity schemas use `.passthrough()` and optional fields — unknown/future fields from a newer
@@ -385,16 +420,24 @@ For a deeper subsystem reference, see [`AGENTS.md`](AGENTS.md) in this package a
 
 ## Logging
 
-`createLogger(name, opts)` returns a `pino` logger that writes pretty output to stdout in
-development and rotating NDJSON to `$PI_STUDIO_HOME/logs/` in production. The level comes from the
-`log.level` config key (default `info`) or `LOG_LEVEL`.
+The daemon logs its full operational lifecycle through one `pino` logger created in the bootstrap
+(`src/logging/logger.ts`): startup (home, config, serverId), agent recovery, WS client
+connect/disconnect (with close code + duration), upgrade/auth rejections, every RPC (at `debug`,
+with duration; failures at `warn`), agent create/turn lifecycle (prompt *sizes*, never contents),
+terminal open/kill/exit, `pi` provider process spawn/exit, and relay dial events.
+
+Output goes to **stdout always** — pretty on a TTY, NDJSON otherwise (so `docker logs` /
+journald / PM2 work out of the box) — **plus** a rotating NDJSON file under
+`$PI_STUDIO_HOME/logs/` in production (both destinations, never either/or). Level comes from
+`PI_STUDIO_LOG_LEVEL` (`trace`|`debug`|`info`|`warn`|`error`|`fatal`|`silent`, default `info`);
+`debug` adds per-RPC request lines, `trace` is the most verbose.
 
 ---
 
 ## Development
 
 ```bash
-npm test -- --project packages/server   # run this package's Vitest suite
+npx vitest run packages/server           # run this package's Vitest suite
 npm run typecheck                        # tsc -b across all packages
 npm run lint                             # oxlint
 npm run fmt:check                        # oxfmt --check
@@ -416,8 +459,9 @@ real wall-clock timers in tests — await real completion signals instead.
 4. **All entity + wire schemas use `.passthrough()` and optional fields** — newer data must load on
    older daemons.
 5. **The wire protocol is append-only.** Never remove or narrow a field, never change a discriminant.
-6. **`dev-bootstrap.ts` must not be imported by `bootstrap.ts`.**
+6. **`bootstrap.ts` must never import `dev-bootstrap.ts`.** (The reverse — `dev-bootstrap.ts`
+   importing the shared `wrapSessionEnvelope` helper from `bootstrap.ts` — is fine and is what
+   happens today.)
 7. **Binary frame codecs are cross-platform** (`Uint8Array`, no Node `Buffer`).
 8. **`~` in `cwd` is expanded server-side** before it reaches a provider.
-```