@addai/node 0.29.1 → 0.30.0

package/README.md

@@ -1,96 +1,96 @@
-# entities-runtime
-
-A standalone Node.js daemon. Install it on any machine, pair with your
-+Ai account, and your account can then run Claude Code / Codex sessions
-on that machine on its behalf — from Vault, from Entity Studio, or from
-anywhere else in +Ai.
-
-## Quick start
-
-```bash
-npx entities-runtime
-```
-
-The first run prints a 5-letter pairing code and a URL:
-
-```
-Pair this runtime with your +Ai account.
-
-  https://vault.add.ai/entity/connect/HDXYC
-
-Enter this code: HDXYC
-```
-
-Open the URL while signed into Vault, enter the code, and the runtime
-starts polling for work. Capabilities (claude, codex, git, node) are
-reported every 30 s.
-
-## Commands
-
-```
-entities-runtime                  run the daemon (foreground)
-entities-runtime status           pairing + capabilities + last-seen
-entities-runtime sessions         recent requests handled (--limit N)
-entities-runtime unpair --yes     disconnect from +Ai
-entities-runtime version          print version
-```
-
-`status` and `sessions` work without the daemon running — they hit
-Supabase directly using the daemon token in
-`~/.entities-runtime/state.json`.
-
-## Architecture
-
-See [`docs/architecture.md`](docs/architecture.md) for the full picture:
-Supabase tables, RPC inventory, request lifecycle, and the cancel-watcher
-flow.
-
-## DiskGuard — Codex scratch-dir disk protection
-
-Each Codex run gets a throwaway `CODEX_HOME` under the OS temp dir
-(`entities-codex-<rand>`). Codex writes its `state_*.sqlite`, logs, caches
-and shell snapshots there — typically 50–350 MB per run. codex-spawn now
-deletes that dir on exit, but a `SIGKILL`, a crash, or an orphan left by a
-previous runtime process can skip that path. On a dedicated host doing
-thousands of runs, those leftovers once grew to ~158 GiB and filled the
-disk (`ENOSPC`, repeated crashes).
-
-**DiskGuard** is the safety net. Like a CCTV DVR overwriting the oldest
-footage when the disk fills, it watches free space on the volume holding
-the temp dir and, when usage crosses a high-water mark, deletes the
-**oldest inactive** scratch dirs — oldest first — until usage drops back
-below a low-water mark, leaving a buffer for the OS. It runs at startup, on
-an interval, and opportunistically right before each new Codex run.
-
-Safety guarantees: it only touches directories directly under the temp root
-whose names match the configured prefix (realpath-validated); it never
-deletes a dir owned by a live session (in-process, or one whose
-`session.lock` PID is still alive) or one younger than the min-age guard;
-and it removes symlink *entries* without following them, so the durable
-`~/.codex` targets behind `sessions`/`auth.json` are never harmed.
-
-Note: DiskGuard can only reclaim space by deleting scratch dirs it owns. If
-a disk is full of *other* data it will evict what it can and log that it
-couldn't reach the target rather than touching anything it doesn't own.
-
-Configure via environment variables (defaults shown):
-
-| Variable | Default | Meaning |
-|---|---|---|
-| `DISKGUARD_ENABLED` | `true` | Master switch for the sweeper. Cleanup-on-exit still runs when `false`. |
-| `DISKGUARD_HIGH_WATER_PCT` | `90` | Start evicting when volume usage reaches this %. |
-| `DISKGUARD_LOW_WATER_PCT` | `80` | Stop evicting once usage drops below this %. Clamped below high-water. |
-| `DISKGUARD_MIN_AGE_MINUTES` | `30` | Never evict a scratch dir younger than this. |
-| `DISKGUARD_CHECK_INTERVAL_SECONDS` | `60` | Periodic sweep cadence. |
-| `DISKGUARD_DRY_RUN` | `false` | Log what would be evicted without deleting anything. |
-| `DISKGUARD_PREFIXES` | `entities-codex-` | Comma-separated dir-name prefixes eligible for eviction. |
-| `DISKGUARD_TEMP_ROOT` | `os.tmpdir()` | Override the watched temp root (mainly for testing). |
-
-## Development
-
-```bash
-npm install
-npm run build
-node dist/cli.js
-npm test        # builds, then runs the node:test suite (see test/)
-```
+# entities-runtime
+
+A standalone Node.js daemon. Install it on any machine, pair with your
++Ai account, and your account can then run Claude Code / Codex sessions
+on that machine on its behalf — from Vault, from Entity Studio, or from
+anywhere else in +Ai.
+
+## Quick start
+
+```bash
+npx entities-runtime
+```
+
+The first run prints a 5-letter pairing code and a URL:
+
+```
+Pair this runtime with your +Ai account.
+
+  https://vault.add.ai/entity/connect/HDXYC
+
+Enter this code: HDXYC
+```
+
+Open the URL while signed into Vault, enter the code, and the runtime
+starts polling for work. Capabilities (claude, codex, git, node) are
+reported every 30 s.
+
+## Commands
+
+```
+entities-runtime                  run the daemon (foreground)
+entities-runtime status           pairing + capabilities + last-seen
+entities-runtime sessions         recent requests handled (--limit N)
+entities-runtime unpair --yes     disconnect from +Ai
+entities-runtime version          print version
+```
+
+`status` and `sessions` work without the daemon running — they hit
+Supabase directly using the daemon token in
+`~/.entities-runtime/state.json`.
+
+## Architecture
+
+See [`docs/architecture.md`](docs/architecture.md) for the full picture:
+Supabase tables, RPC inventory, request lifecycle, and the cancel-watcher
+flow.
+
+## DiskGuard — Codex scratch-dir disk protection
+
+Each Codex run gets a throwaway `CODEX_HOME` under the OS temp dir
+(`entities-codex-<rand>`). Codex writes its `state_*.sqlite`, logs, caches
+and shell snapshots there — typically 50–350 MB per run. codex-spawn now
+deletes that dir on exit, but a `SIGKILL`, a crash, or an orphan left by a
+previous runtime process can skip that path. On a dedicated host doing
+thousands of runs, those leftovers once grew to ~158 GiB and filled the
+disk (`ENOSPC`, repeated crashes).
+
+**DiskGuard** is the safety net. Like a CCTV DVR overwriting the oldest
+footage when the disk fills, it watches free space on the volume holding
+the temp dir and, when usage crosses a high-water mark, deletes the
+**oldest inactive** scratch dirs — oldest first — until usage drops back
+below a low-water mark, leaving a buffer for the OS. It runs at startup, on
+an interval, and opportunistically right before each new Codex run.
+
+Safety guarantees: it only touches directories directly under the temp root
+whose names match the configured prefix (realpath-validated); it never
+deletes a dir owned by a live session (in-process, or one whose
+`session.lock` PID is still alive) or one younger than the min-age guard;
+and it removes symlink *entries* without following them, so the durable
+`~/.codex` targets behind `sessions`/`auth.json` are never harmed.
+
+Note: DiskGuard can only reclaim space by deleting scratch dirs it owns. If
+a disk is full of *other* data it will evict what it can and log that it
+couldn't reach the target rather than touching anything it doesn't own.
+
+Configure via environment variables (defaults shown):
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `DISKGUARD_ENABLED` | `true` | Master switch for the sweeper. Cleanup-on-exit still runs when `false`. |
+| `DISKGUARD_HIGH_WATER_PCT` | `90` | Start evicting when volume usage reaches this %. |
+| `DISKGUARD_LOW_WATER_PCT` | `80` | Stop evicting once usage drops below this %. Clamped below high-water. |
+| `DISKGUARD_MIN_AGE_MINUTES` | `30` | Never evict a scratch dir younger than this. |
+| `DISKGUARD_CHECK_INTERVAL_SECONDS` | `60` | Periodic sweep cadence. |
+| `DISKGUARD_DRY_RUN` | `false` | Log what would be evicted without deleting anything. |
+| `DISKGUARD_PREFIXES` | `entities-codex-` | Comma-separated dir-name prefixes eligible for eviction. |
+| `DISKGUARD_TEMP_ROOT` | `os.tmpdir()` | Override the watched temp root (mainly for testing). |
+
+## Development
+
+```bash
+npm install
+npm run build
+node dist/cli.js
+npm test        # builds, then runs the node:test suite (see test/)
+```