@av-pi-studio/server 0.0.10 → 0.0.11

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 |
@@ -301,17 +320,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 +406,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 +445,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.
-```