skalpel 3.2.10 → 3.2.12

package/INSTALL.md

@@ -54,9 +54,13 @@ If the user runs `skalpel` without first running `skalpel login`, the walkthroug
 The primary, guided path is the website signup wizard, which mints a one-time, version-pinned-to-`latest` command:
 
 ```bash
-npx --yes skalpel@<latest> login --activation <token>
+npx --yes skalpel@<latest> login --activation <token> && npm install -g skalpel@<latest>
 ```
 
+The `&& npm install -g` step puts `skalpel` on your PATH so shell wrappers from setup work in new terminals; it only runs if activation succeeds.
+
+The shell wrappers — and the `skalpel active` / `skalpel inactive` indicator each new `claude` / `codex` session prints — **require a persistent global install** (`npm install -g skalpel`). The wrapper block is gated on `command -v skalpel`, so a block written while only an ephemeral `npx` binary is on PATH never activates. If you run only the `npx … login --activation` step (without the global install), harness setup detects that no persistent `skalpel` is on PATH and **tells you to run `npm install -g skalpel@latest`** instead of silently writing an inert block. Run the global install, then `skalpel setup` (or restart your shell), and the indicator appears.
+
 `login --activation` is **auth-only with respect to the TUI**: it claims the token, writes `auth.json`, and never launches the TUI (the magic flow is a deliberate terminal handoff). Before exiting it chains directly into harness setup so the single pasted command also walks the user through wrapping their coding agents: in an interactive terminal it runs the same detection + checkbox prompt as `skalpel setup`; in a non-interactive shell (CI, piped) it only prints what it detected and points at `skalpel setup`, never editing shell startup files unattended. Browser-loopback `skalpel login` is unchanged and still lands the user on the dashboard.
 
 A user who independently runs `npm install -g skalpel` is still supported: `postinstall` prints a best-effort pointer to `https://launch.skalpel.ai/signup`, and the first `skalpel` run repeats that pointer where output is guaranteed.
@@ -68,7 +72,15 @@ Harness setup runs automatically at the tail of `login --activation` (see above)
 - **Claude Code** and **Codex CLI** — detected and wrappable.
 - **Cursor** — detected for display only (no Skalpel wrapper today).
 
-The user opts into which detected agents to wrap. `setup` resolves the correct shell startup file for the current OS + shell (zsh/bash/fish rc files, or the PowerShell `$PROFILE` on Windows), writes a managed fenced block (identical fences to the install-time block, so `skalpel uninstall` removes either), and prints exactly which file changed plus undo instructions (`skalpel uninstall`, or `SKALPEL_NO_AGENT_WRAP=1` to disable wrapping). It never launches the TUI. On an unknown OS/shell it prints manual instructions instead of writing.
+In an **interactive** terminal, `setup` shows a checkbox list (nothing pre-selected), matching Claude Code’s multi-select pattern: **↑/↓** to move, **enter** (or **space**) on an agent row toggles a green **[✓]**, then move to **Confirm and wrap selected** and press **enter** to apply. **esc** skips without changes. It does not use a free-text `>` prompt and does not wrap all detected agents unless you pass `--yes` / `-y` or run in a non-interactive shell (which wraps all detected agents for explicit `skalpel setup` only — the chained `login --activation` path never writes shell files unattended).
+
+Harness detection uses the same `internal/harness` probes as the published npm binary (`claude` / `codex` on PATH, or `~/.claude` / `~/.codex` config dirs). If nothing is found, the CLI prints what it looked for — that is not a dev-only stub.
+
+After wrapping, `setup` prints per-agent success lines and reminds you that new `claude` / `codex` sessions show **`skalpel active`** or **`skalpel inactive`** on stderr before the agent loads (via the shell wrapper calling `skalpel status`). Toggle interception without editing shell files: **`skalpel off`** / **`skalpel on`**.
+
+The wrapper block only fires when `skalpel` is **permanently on your PATH** (a global `npm install -g skalpel`, not an ephemeral `npx` run). If you invoke `setup` from a non-persistent `skalpel` (e.g. via `npx`), it will not write the rc block — it instead prints the exact `npm install -g skalpel@latest` command to run first, because the wrappers cannot activate without it.
+
+`setup` resolves the correct shell startup file for the current OS + shell (zsh/bash/fish rc files, or the PowerShell `$PROFILE` on Windows), writes a managed fenced block (identical fences to the install-time block, so `skalpel uninstall` removes either), and prints exactly which file changed plus undo instructions (`skalpel uninstall`, or `SKALPEL_NO_AGENT_WRAP=1` to disable wrapping). It never launches the TUI. On an unknown OS/shell it prints manual instructions instead of writing.
 
 Historical note: prior versions of skalpel supported pasting a `sk-skalpel-*` API key copied from the web dashboard as an alternative to `skalpel login`. The W4 OAuth-port grep-delete removed both the api_key-paste wizard and the daemon-side api_key sending path. Users on stale auth.json files (api_key-only, no Cognito bundle) need to run `skalpel login` once to refresh.
 
@@ -141,6 +153,47 @@ When the TUI connects to the daemon at launch, the handshake includes a version
 
 The handshake is also where the TUI reads the daemon's engine list and the daemon's per-agent detection results (per `SPEC.md` §6 and §9). A version-coupled handshake is also a guarantee that the TUI is reading those results from a daemon whose schema it understands. When the bundle promises versions match, the TUI does not need a defensive parse-and-recover path for the daemon's responses; the schema is whatever the bundle's joint version says it is.
 
+## Advanced: chaining `skalpeld` through a local interception proxy
+
+By default `skalpeld` is the host's HTTP proxy for coding agents. If you
+also run a separate local interception proxy (e.g. an mitmproxy that
+records traffic for research), you can have the daemon **chain** its
+outbound provider traffic through it without either rig fighting over the
+proxy role. This is opt-in and controlled by two environment variables on
+the **daemon** process:
+
+| Variable | Values | Default | Effect |
+|---|---|---|---|
+| `SKALPEL_VIA_MITM` | `true` \| `false` \| `bypass` | `true` | `true`: the daemon routes its **provider** calls (Anthropic / OpenAI / …) through the proxy at `MITM_PROXY_URL`, while its own **control-plane** calls to `api.skalpel.ai` and the **Cognito** auth hop bypass the proxy (so your recordings never contain Skalpel control-plane chatter). `false` / `bypass`: the daemon talks direct to providers, no chaining; `bypass` is the explicit "turn everything off" debugging value. An unset or unrecognised value behaves as `true`. |
+| `MITM_PROXY_URL` | a proxy URL | `http://127.0.0.1:8888` | The interception-proxy address to chain through when `SKALPEL_VIA_MITM=true`. The daemon's own live proxy address-file and `SKALPEL_PROXY_URL` take precedence over this if set. |
+
+The bypass list is fixed and suffix-based — it covers the Skalpel control
+plane (`api.skalpel.ai`, `.skalpel.ai`), Cognito and AWS
+(`amazoncognito.com`, `amazonaws.com`), object stores
+(`r2.cloudflarestorage.com`), the package registries the install path
+reaches (`pypi.org`, `crates.io`, `*.github.com`), and loopback. Provider
+hosts are NOT on the list, so they route through the proxy.
+
+Because the daemon is service-managed, set these via a systemd drop-in
+rather than an interactive shell:
+
+```ini
+# ~/.config/systemd/user/skalpeld.service.d/proxy-chain.conf
+[Service]
+Environment=SKALPEL_VIA_MITM=true
+Environment=MITM_PROXY_URL=http://127.0.0.1:8888
+```
+
+```bash
+systemctl --user daemon-reload
+systemctl --user restart skalpeld
+```
+
+To disable chaining, set `SKALPEL_VIA_MITM=bypass` (or `false`) and
+restart the daemon. The interception proxy must trust nothing extra for
+this to work; the chain is purely a network-layer redirect of the
+daemon's outbound sockets.
+
 ## Open questions
 
 A small set of bundling questions are recorded here for the build phase. Each will be resolved before v1 ships; none affect the design commitments above.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skalpel",
-  "version": "3.2.10",
+  "version": "3.2.12",
   "description": "Skalpel — local proxy and TUI for coding agents (skalpel + skalpeld bundle).",
   "license": "Apache-2.0",
   "homepage": "https://skalpel.ai",
@@ -58,10 +58,10 @@
     "x64"
   ],
   "optionalDependencies": {
-    "@skalpelai/skalpel-darwin-arm64": "3.2.10",
-    "@skalpelai/skalpel-darwin-x64": "3.2.10",
-    "@skalpelai/skalpel-linux-arm64": "3.2.10",
-    "@skalpelai/skalpel-linux-x64": "3.2.10",
-    "@skalpelai/skalpel-win32-x64": "3.2.10"
+    "@skalpelai/skalpel-darwin-arm64": "3.2.11",
+    "@skalpelai/skalpel-darwin-x64": "3.2.11",
+    "@skalpelai/skalpel-linux-arm64": "3.2.11",
+    "@skalpelai/skalpel-linux-x64": "3.2.11",
+    "@skalpelai/skalpel-win32-x64": "3.2.11"
   }
 }