feat: dynamic numtide catalog (88+ agents), CI smoke tests, catalog defensive fixes

.github/workflows/ci.yml

@@ -0,0 +1,228 @@
+name: CI
+
+on:
+  push:
+    branches: [master, pi-sandbox-refactor]
+  pull_request:
+    branches: [master]
+
+jobs:
+  rust-tests:
+    name: Rust tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            crates/nixosandbox/target
+          key: cargo-${{ runner.os }}-${{ hashFiles('crates/nixosandbox/Cargo.lock') }}
+          restore-keys: cargo-${{ runner.os }}-
+
+      - name: Build
+        working-directory: crates/nixosandbox
+        run: cargo build
+
+      - name: Test
+        working-directory: crates/nixosandbox
+        run: cargo test
+
+  typescript-check:
+    name: TypeScript typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+
+      - name: Install dependencies
+        working-directory: packages/pi-sandbox-extension
+        run: npm install
+
+      - name: Typecheck
+        working-directory: packages/pi-sandbox-extension
+        run: npx tsc --noEmit
+
+  nix-eval:
+    name: Nix evaluation & catalog
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: cachix/install-nix-action@v30
+        with:
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+            extra-substituters = https://cache.numtide.com
+            extra-trusted-public-keys = niks3.numtide.com-1:DTx8wZduET09hRmMtKdQDxNNthLQETkc/yaX7M4qK0g=
+
+      - name: Flake check
+        run: nix flake check --accept-flake-config
+
+      - name: Evaluate catalog agents
+        run: |
+          nix eval --accept-flake-config .#catalog.agents --apply 'x: builtins.attrNames x'
+
+      - name: Evaluate catalog tools
+        run: |
+          nix eval --accept-flake-config .#catalog.tools --apply 'x: builtins.attrNames x'
+
+      - name: Verify existing profiles
+        run: |
+          nix eval --accept-flake-config .#packages.x86_64-linux.sandbox-strict.name
+
+  nix-build:
+    name: Nix build & smoke test
+    runs-on: ubuntu-latest
+    needs: [rust-tests, nix-eval]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: cachix/install-nix-action@v30
+        with:
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+            extra-substituters = https://cache.numtide.com
+            extra-trusted-public-keys = niks3.numtide.com-1:DTx8wZduET09hRmMtKdQDxNNthLQETkc/yaX7M4qK0g=
+
+      - name: Build nixosandbox CLI
+        run: nix build --accept-flake-config .#nixosandbox
+
+      - name: Test catalog subcommand
+        run: |
+          NIXOSANDBOX_FLAKE_ROOT=$PWD ./result/bin/nixosandbox catalog --json | python3 -m json.tool > /dev/null
+          echo "Catalog JSON is valid"
+
+      - name: Verify catalog agent count and new packages
+        run: |
+          catalog_json=$(NIXOSANDBOX_FLAKE_ROOT=$PWD ./result/bin/nixosandbox catalog --json)
+          agent_count=$(echo "$catalog_json" | python3 -c "import sys, json; d=json.load(sys.stdin); print(len(d['agents']))")
+          echo "Catalog agent count: $agent_count"
+          # Threshold is conservative — guards against empty catalog, not exact upstream count.
+          # llm-agents.nix is a third-party input that may fluctuate; 50 is well above any realistic minimum.
+          [ "$agent_count" -gt 50 ] || { echo "ERROR: expected >50 agents, got $agent_count"; exit 1; }
+          echo "$catalog_json" | python3 -c '
+          import sys, json
+          d = json.load(sys.stdin)
+          agents = d["agents"]
+          missing = [n for n in ["openclaw", "hermes-agent", "jules"] if n not in agents]
+          if missing:
+              print(f"ERROR: missing agents: {missing}", file=sys.stderr)
+              sys.exit(1)
+          print(f"All expected agents present in {len(agents)} total")
+          '
+
+      - name: Test catalog filter
+        run: |
+          output=$(NIXOSANDBOX_FLAKE_ROOT=$PWD ./result/bin/nixosandbox catalog --filter claude)
+          echo "$output"
+          echo "$output" | grep -q "claude-code"
+
+      - name: Test --with rootfs creation
+        run: |
+          output=$(NIXOSANDBOX_FLAKE_ROOT=$PWD ./result/bin/nixosandbox create \
+            --with bash,coreutils --network off --name ci-smoke --json)
+          echo "$output"
+          session_id=$(echo "$output" | python3 -c "import sys,json; print(json.load(sys.stdin)['sessionId'])")
+          echo "Session created: $session_id"
+          NIXOSANDBOX_FLAKE_ROOT=$PWD ./result/bin/nixosandbox destroy "$session_id"
+          echo "Session destroyed"
+
+      - name: Test mutual exclusivity
+        run: |
+          if NIXOSANDBOX_FLAKE_ROOT=$PWD ./result/bin/nixosandbox create --profile strict --with bash 2>&1; then
+            echo "ERROR: should have failed" && exit 1
+          else
+            echo "Mutual exclusivity check passed"
+          fi
+
+  agent-smoke-tests:
+    name: Agent sandbox smoke tests
+    runs-on: ubuntu-latest
+    needs: [nix-build]
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - agent: claude-code
+            binary: claude
+            check: "--version"
+          - agent: codex
+            binary: codex
+            check: "--help"
+          - agent: opencode
+            binary: opencode
+            check: "--version"
+          - agent: amp
+            binary: amp
+            check: "--help"
+          - agent: droid
+            binary: droid
+            check: "--version"
+          - agent: pi
+            binary: pi
+            check: "--help"
+          - agent: openclaw
+            binary: openclaw
+            check: "--help"
+          - agent: hermes-agent
+            binary: hermes
+            check: "--version"
+          - agent: jules
+            binary: jules
+            check: "--help"
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: cachix/install-nix-action@v30
+        with:
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+            extra-substituters = https://cache.numtide.com
+            extra-trusted-public-keys = niks3.numtide.com-1:DTx8wZduET09hRmMtKdQDxNNthLQETkc/yaX7M4qK0g=
+
+      - name: Install and verify bubblewrap
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq bubblewrap
+          echo "bwrap path: $(which bwrap)"
+          bwrap --version
+          # Verify bwrap can actually create sandboxes.
+          # Ubuntu 24.04 may restrict user namespaces via AppArmor (containers/bubblewrap#632).
+          if ! bwrap --ro-bind / / --dev /dev --proc /proc -- echo "bwrap sandbox works"; then
+            echo "bwrap failed — relaxing AppArmor unprivileged userns restriction"
+            sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+            bwrap --ro-bind / / --dev /dev --proc /proc -- echo "bwrap sandbox works after sysctl fix"
+          fi
+
+      - name: Build nixosandbox CLI
+        run: nix build --accept-flake-config .#nixosandbox
+
+      - name: Create sandbox with ${{ matrix.agent }}
+        run: |
+          echo "Creating sandbox with ${{ matrix.agent }} + bash..."
+          output=$(NIXOSANDBOX_FLAKE_ROOT=$PWD ./result/bin/nixosandbox create \
+            --with ${{ matrix.agent }},bash --network off --name ci-${{ matrix.agent }} --json)
+          echo "$output"
+          echo "$output" | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Session: {d[\"sessionId\"]}, Profile: {d[\"profile\"]}')"
+          session_id=$(echo "$output" | python3 -c "import sys,json; print(json.load(sys.stdin)['sessionId'])")
+          echo "SESSION_ID=$session_id" >> "$GITHUB_ENV"
+
+      - name: Verify ${{ matrix.agent }} binary launches
+        run: |
+          echo "Running: ${{ matrix.binary }} ${{ matrix.check }}"
+          NIXOSANDBOX_FLAKE_ROOT=$PWD ./result/bin/nixosandbox exec "$SESSION_ID" --json \
+            -- ${{ matrix.binary }} ${{ matrix.check }}
+          echo "${{ matrix.agent }} smoke test passed"
+
+      - name: Cleanup session
+        if: always()
+        run: |
+          if [ -n "$SESSION_ID" ]; then
+            NIXOSANDBOX_FLAKE_ROOT=$PWD ./result/bin/nixosandbox destroy "$SESSION_ID" 2>/dev/null || true
+          fi

.gitignore

@@ -108,3 +108,14 @@ tests/__pycache__/
 *.key
 credentials.json
 secrets.json
+
+# Pi Sandbox Extension
+packages/pi-sandbox-extension/node_modules/
+packages/pi-sandbox-extension/dist/
+
+# Rust / Cargo
+crates/nixosandbox/target/
+
+# Protocol tests
+tests/protocol/node_modules/
+.pi/

CLAUDE.md

@@ -0,0 +1,96 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build and test commands
+
+### Rust CLI
+```bash
+cd crates/nixosandbox
+cargo build                          # build
+cargo test                           # run all 20 tests
+cargo test session::tests            # run tests in one module
+cargo test metadata_roundtrip        # run a single test by name
+```
+
+### TypeScript extension
+```bash
+cd packages/pi-sandbox-extension
+npm install
+npx tsc --noEmit                     # typecheck only
+npm run build                        # compile to dist/
+```
+
+### Nix
+```bash
+nix flake check --accept-flake-config
+nix build --accept-flake-config .#nixosandbox          # build CLI as Nix package
+nix eval --accept-flake-config .#catalog.agents --apply 'x: builtins.attrNames x'
+nix eval --accept-flake-config .#catalog.tools --apply 'x: builtins.attrNames x'
+```
+
+### CLI smoke test (Linux only, requires bwrap)
+```bash
+NIXOSANDBOX_FLAKE_ROOT=$PWD ./result/bin/nixosandbox catalog --json
+NIXOSANDBOX_FLAKE_ROOT=$PWD ./result/bin/nixosandbox create --with bash,coreutils --network off --json
+NIXOSANDBOX_FLAKE_ROOT=$PWD ./result/bin/nixosandbox exec <session-id> -- echo hello
+NIXOSANDBOX_FLAKE_ROOT=$PWD ./result/bin/nixosandbox destroy <session-id>
+```
+
+## Architecture
+
+### Core data flow
+
+1. **User runs** `nixosandbox create --with claude-code,bash --network off`
+2. **nix.rs** resolves package names via `build_with_catalog()` which generates a Nix expression calling `mkAgentSandbox`
+3. **mkAgentSandbox.nix** resolves names from the catalog (agents first, then tools) and delegates to `mkSandboxRootfs`
+4. **mkSandboxRootfs.nix** uses `pkgs.buildEnv` to merge packages, then creates a rootfs directory with symlinks into `/nix/store`
+5. **session.rs** creates a session directory under `~/.local/share/nixosandbox/sessions/<id>/` with metadata, workspace, home, and cache dirs
+6. **User runs** `nixosandbox exec <id> -- command`
+7. **plan_builder.rs** constructs bwrap argv: `--ro-bind <rootfs> /`, `--ro-bind /nix/store /nix/store`, writable bind mounts for workspace/home/cache, namespace flags, env vars
+8. **main.rs** spawns bwrap (detected path from `bubblewrap::detect()`) with the constructed argv
+
+### Key design decisions
+
+- **Profile field is overloaded**: `session.profile` stores either a built-in profile name (e.g., `"strict"`) which maps to `nix/profiles/<name>.json`, or `"custom:<pkg1>,<pkg2>"` for `--with` sessions. Code must check `meta.profile.starts_with("custom:")` before calling `load_profile()`.
+- **Rootfs symlinks require Nix store**: The rootfs contains absolute symlinks into `/nix/store`. bwrap must bind-mount `/nix/store` read-only, and the rootfs must have `/nix/store` as an empty mount point directory.
+- **macOS support via Docker sidecar**: On non-Linux, `bubblewrap::detect()` tries a Docker sidecar container (`nixosandbox-sidecar`) with bwrap inside. Session paths are rewritten from host to container paths via `docker::rewrite_path()`.
+- **Package name validation**: `nix::validate_package_name()` rejects names not matching `[a-zA-Z0-9_.-]+` to prevent Nix expression injection via `--with`.
+- **Network mode storage**: For `--with` sessions, the network mode is stored in `session.network` (not derivable from a profile file). For built-in profiles, it's in the profile JSON.
+
+### Rust module responsibilities
+
+| Module | Owns |
+|--------|------|
+| `cli.rs` | clap argument parsing |
+| `main.rs` | command dispatch, `cmd_create`, `cmd_exec`, `cmd_catalog`, etc. |
+| `session.rs` | session CRUD, metadata serialization, directory layout |
+| `nix.rs` | `find_flake_root()`, `build_profile()`, `build_with_catalog()`, `query_catalog()` (filters non-derivation attrs via `filterDrvs` before reading `.meta.description`) |
+| `plan_builder.rs` | bwrap argv construction (`--ro-bind`, `--bind`, `--unshare-*`, `--setenv`) |
+| `bubblewrap.rs` | bwrap detection: `NIXOSANDBOX_BWRAP_PATH` env var, then `which bwrap`, Docker fallback on macOS |
+| `docker.rs` | Docker sidecar lifecycle (find, start, create, image build) |
+| `spec.rs` | profile/spec loading from JSON, validation |
+
+### Nix module responsibilities
+
+| File | Owns |
+|------|------|
+| `nix/catalog.nix` | Unified `{ agents, tools }` attrset — agents is a full dynamic passthrough of `llm-agents-pkgs` (no whitelist), tools from nixpkgs |
+| `nix/mkSandboxRootfs.nix` | Builds rootfs directory tree from package list (symlinks, /etc, certs) |
+| `nix/mkAgentSandbox.nix` | Resolves catalog names to packages, delegates to mkSandboxRootfs |
+| `nix/profiles/*.json` | Built-in profile specs (strict, build-install, offline-review, debug-network) |
+
+### TypeScript extension (packages/pi-sandbox-extension)
+
+Provides Pi coding agent integration. Key files:
+- `cli-client.ts` — spawns the nixosandbox CLI as a subprocess, provides `createSession()`, `execCommand()`, `catalogPackages()`
+- `extension.ts` — registers Pi tools: `sandboxRun`, `sandboxReadFile`, `sandboxWriteFile`, `sandboxListFiles`, `sandboxSessionInfo`, `sandboxBrowser`, `sandboxCatalog`
+- `contract.ts` — TypeScript type definitions for the NDJSON protocol
+
+## Session tests use env var serialization
+
+Tests in `session.rs` mutate `NIXOSANDBOX_DATA_DIR` to use temp directories. They serialize via `static ENV_LOCK: Mutex<()>` acquired in `with_temp_data_dir()`. If adding session tests, always use this helper.
+
+## CI runs on nixos-25.11
+
+The flake pins `nixpkgs` to `nixos-25.11`. CI uses `cachix/install-nix-action@v30` with the numtide binary cache. Agent smoke tests use system apt bwrap (setuid) because Nix-built bwrap lacks setuid and fails on Ubuntu 24.04's AppArmor user namespace restrictions.