saros-proxy 1.0.0 → 1.1.1

package/README.md

@@ -176,11 +176,11 @@ Saros tracks which keys are currently in use. A key handling a streaming request
 
 ### Prompt Install(for the lazy ones)
 
-Don't feel like reading through everything? Copy this prompt and paste it to your AI assistant. It'll read [`LLM_INSTRUCTIONS.md`](LLM_INSTRUCTIONS.md) and guide you through setup — no keys shared in chat.
+Don't feel like reading through everything? Copy this prompt and paste it to your AI assistant. It'll read [`docs/LLM_INSTRUCTIONS.md`](docs/LLM_INSTRUCTIONS.md) and guide you through setup — no keys shared in chat.
 
 ```
 Install Saros Proxy for my opencode. (https://github.com/vitorvilaca3011/saros-proxy)
-Follow the instructions on LLM_INSTRUCTIONS.md.
+Follow the instructions on docs/LLM_INSTRUCTIONS.md.
 ```
 
 ---
@@ -481,14 +481,21 @@ into the "no passphrase source" boot error — a locked keyring is not reported
 as an empty store.
 
 **systemd-creds recipe** (keeps the passphrase out of the unit file and the
-environment of the shell):
+environment of the shell). This is a **system** unit recipe — run the encryption
+as root, since the host key lives in `/var/lib/systemd/credential.secret`:
 
 ```bash
-# One-time: encrypt stdin into a host+user-bound credential.
-systemd-creds encrypt --name=saros-passphrase --with-key=host+user \
+# One-time, as root: encrypt stdin into a host-bound credential.
+# (--with-key=auto picks tpm2+host when the TPM is available, host otherwise.
+#  "host+user" is not a valid key type, and --user only exists from v256.)
+systemd-creds encrypt --name=saros-passphrase --with-key=auto \
   /dev/stdin /etc/saros/passphrase.cred
 ```
 
+For the `systemd --user` unit created by `saros-proxy autostart install`, use
+`Environment=`/`EnvironmentFile=` instead: user credentials need
+`systemd-creds --user`, which only exists from systemd v256 (this host runs 255).
+
 ```ini
 # /etc/systemd/system/saros-proxy.service
 [Service]
@@ -544,7 +551,6 @@ export CIRCUIT_BREAKER_THRESHOLD=5
 export CIRCUIT_BREAKER_COOLDOWN_MS=120000
 export REQUEST_TIMEOUT_MS=45000
 export LOG_LEVEL=debug
-export NODE_ENV=development
 
 npx tsx src/index.ts
 ```
@@ -591,16 +597,48 @@ saros-proxy probe
 # Show per-key quota usage, token totals and most-used models
 saros-proxy usage
 
-# Install autostart (Windows: VBS script or Registry)
-saros-proxy autostart install [--port <port>] [--method vbs|registry|auto]
+# Install autostart (Linux: systemd --user; Windows: VBS script or Registry)
+saros-proxy autostart install [--port <port>] [--method systemd|vbs|registry|auto]
 
 # Uninstall autostart
-saros-proxy autostart uninstall [--method vbs|registry|auto]
+saros-proxy autostart uninstall [--method systemd|vbs|registry|auto]
 
 # Check autostart status
-saros-proxy autostart status [--method vbs|registry|auto]
+saros-proxy autostart status [--method systemd|vbs|registry|auto]
+```
+
+On Linux the default is a `systemd --user` unit at
+`~/.config/systemd/user/saros-proxy.service` (honouring `$XDG_CONFIG_HOME`), enabled
+with `systemctl --user enable` and restarted with `systemctl --user restart`. On
+Windows the default is AV-aware (`auto`): Registry when third-party antivirus is
+detected, otherwise the Startup-folder VBS.
+
+Manage the unit with systemd, not with the CLI: `saros-proxy stop` exits non-zero
+while the service still answers `/health`, because the CLI does not own the unit's
+process.
+
+```bash
+systemctl --user start|stop|restart|status saros-proxy.service
+journalctl --user -u saros-proxy -f
 ```
 
+The unit runs `serve` in the foreground: without a TTY it cannot prompt for a
+passphrase, and the user manager does not inherit the environment of the shell
+that ran `install`. If `config.yaml` holds `enc:v1:` envelopes, give the unit a
+source through a drop-in (`systemctl --user edit saros-proxy.service`):
+
+```ini
+[Service]
+Environment=SAROS_PASSPHRASE=your-passphrase
+```
+
+`EnvironmentFile=-%h/.config/saros/env` (mode 0600) keeps the value out of the
+unit file. A credential is stronger, but `Environment=` can only carry the
+credential *path* (`%d/<name>`), never its content — see the
+[systemd-creds recipe](#api-key-encryption), which wraps `serve` in
+`sh -c 'SAROS_PASSPHRASE="$(cat "$CREDENTIALS_DIRECTORY/<name>")" exec …'`.
+`systemd-creds` only gained a `--user` mode in v256.
+
 The `start` command automatically syncs model definitions to all enabled harnesses (see [Multi-Harness Integration](#multi-harness-integration-pi-oh-my-pi--dsh)).
 
 ### Model Sync Commands
@@ -752,7 +790,7 @@ Behavior:
 - Sync never creates a harness config: harnesses whose config file is missing are skipped.
 - Only `providers["saros-proxy"].models` is replaced; all other providers, fields, and settings are preserved, and a `<file>.backup` is created before the first write.
 
-The model list written to each harness comes from the live provider catalogs (opencode-go) enriched with models.dev metadata, merged with any CommandCode-only models — falling back to bundled models when offline — so every harness stays current alongside OpenCode.
+The model list written to each harness comes from the live provider catalogs (opencode-go) enriched with models.dev metadata, merged with any CommandCode-only models — falling back to the bundled `assets/models.json` when offline — so every harness stays current alongside OpenCode.
 
 > **Why a static model list?** The harnesses use a static `models` list on purpose. `pi` has no `/v1/models` discovery for custom providers, and `oh-my-pi`'s discovery cannot recover reasoning/context/output metadata for provider model IDs. `dsh` replaces only `providers["saros-proxy"].models` in its patch layer (`cordis.patch.yml`), which dsh rewrites at every boot — a static, explicitly-managed list is the only reliable source. Dynamic discovery would silently break thinking-level (`:max`/`:high`) role configs.
 
@@ -781,14 +819,30 @@ Returns JSON with key counts, active requests, and circuit-breaker state.
 
 ### View logs
 
+CLI commands (`status`, `start`, `usage`, …) and a foreground `serve` render
+each log record as one human line: `·` info on stdout, `⚠` warning and `✗`
+error on stderr. The line is the message plus, when the record carries them, a
+gray tail with the public request fields
+`status · keyLabel · provider · durationMs · requestId`. Nothing else from the
+logger reaches the terminal:
+
 ```bash
-# Dev mode (pretty-printed, colorized)
-NODE_ENV=development npx tsx src/index.ts
+saros-proxy status
+```
 
-# Production (structured JSON)
-NODE_ENV=production npx tsx src/index.ts
+Parsing the output from a script? Set `SAROS_LOG_JSON=1` to force the raw
+NDJSON format in any mode:
+
+```bash
+SAROS_LOG_JSON=1 saros-proxy status
 ```
 
+The daemon child, `daemon.log` and the systemd journal are always NDJSON
+(`SAROS_DAEMON=1`, or `NODE_ENV=production` on `serve` — which is what the
+systemd unit and the Docker service use); those lines are never rendered for a
+terminal. Other commands stay human even when `NODE_ENV=production` is
+inherited.
+
 ### See which key and provider served a request
 
 Responses served by an upstream key carry three debug headers:
@@ -866,6 +920,18 @@ npm run build
 
 Output goes to `dist/`.
 
+### Refresh the bundled model catalog
+
+`assets/models.json` is generated — do not edit it by hand. The generator merges models.dev metadata with the live opencode-go and CommandCode catalogs: a model that left upstream leaves the bundle, a model the upstream serves but models.dev does not list still enters with the live name and context window, and a field already in the file survives when models.dev omits it.
+
+```bash
+npm run models:refresh -- --dry-run      # print the diff, write nothing
+npm run models:refresh                   # rewrite assets/models.json
+npm run models:refresh -- --allow-shrink # accept removing more than half of the models
+```
+
+A failed fetch — or a 2xx with an empty catalog — aborts before the file is read, and a merge that would remove more than half of the current models aborts unless `--allow-shrink` is given. The write goes through a temp file and an atomic rename, so a crash never leaves a truncated catalog.
+
 ### Project structure
 
 ```
@@ -879,7 +945,8 @@ src/
   providers/            — Multi-provider key abstraction (KeyProvider, adapters, identifyKey)
   models-fetcher.ts     — Upstream model list fetching + caching
   models-sync.ts        — Auto-sync models from upstream to opencode config
-  models-catalog.ts     — Single source of truth: loads bundled models.json
+  models-catalog.ts     — Single source of truth: loads assets/models.json
+  models-refresh.ts     — Generates that catalog (npm run models:refresh)
   cli/
     setup.ts            — Interactive setup wizard
     daemon.ts           — Background process management