@gkoreli/ghx 2.4.1 → 2.5.0

package/README.md

@@ -68,8 +68,16 @@ you can `ls` and `jq`:
     logs.jsonl                # GenAI-convention message-content records
     metrics.jsonl             # duration, token, report-size metrics
     tier-decisions.jsonl      # escalation policy evaluation per turn (which tier, why)
+    live.jsonl                # realtime turn activity, appended as it happens
 ```
 
+The OTLP artifacts are written when a question completes; `live.jsonl` streams
+turn activity in realtime — turn start/end, text and thought chunks, every tool
+call and update as the agent works — so
+`tail -f ~/.ghx/sessions/<name>/live.jsonl` watches a running question instead
+of waiting minutes for the final report
+(see [ADR-0022.1](docs/adr/0022.1-live-turn-log.md)).
+
 Sessions persist, so follow-up questions on the same repo are cheaper and
 context-aware. The traces are **official OpenTelemetry** (OTLP/JSON, GenAI
 semantic conventions) — any industry tool consumes them in seconds, and
@@ -146,26 +154,78 @@ go install github.com/gkoreli/ghx/v2/cmd/ghx@latest
 The sidecar drives an ACP-capable agent under the hood, and it reads GitHub
 through the authenticated [gh CLI](https://cli.github.com/) (`gh auth login`).
 
-### 2. Configure the agent
+### 2. Configure the agent (optional — zero-config works)
 
 The sidecar speaks [Agent Client Protocol (ACP)](https://agentclientprotocol.com)
-to its underlying model. One command writes a working config using the
+to its underlying model. **With no config at all, the pinned
 [claude-agent-acp](https://www.npmjs.com/package/@agentclientprotocol/claude-agent-acp)
-adapter:
+adapter is the default** — if you have Node/npx and are logged into Claude Code,
+`ghx sidecar ask` works out of the box. Write an explicit config only to pin a
+different agent or model:
 
 ```bash
 ghx sidecar config init --claude-acp    # writes ~/.ghx/config.json with the ACP adapter
 ```
 
-> Setup is the hardest step, so this is designed to be one command. Without
-> `--claude-acp`, `config init` auto-detects any ACP-capable agent already on
-> your PATH; a bare `claude` binary does **not** speak ACP on stdio and is
-> rejected on purpose (it would hang every turn — see
+> Without `--claude-acp`, `config init` auto-detects any ACP-capable agent
+> already on your PATH; a bare `claude` binary does **not** speak ACP on stdio
+> and is rejected on purpose (it would hang every turn — see
 > [ADR-0019](docs/adr/0019-sidecar-adoption-zero-cli-surface.md) D4).
 
 Re-running `config init --claude-acp` against an existing config shows a field
 diff and refuses to overwrite without `--force`.
 
+**Using your installed Claude Code (toolbox / wrapper builds).** The adapter's
+SDK ships its own bundled Claude Code binary and its own credential store — by
+default your `claude` on PATH (and its `~/.claude/settings.json`, credential
+hooks, model aliases) is **not** what runs. If your organization installs a
+wrapped `claude` that carries work credentials, point the adapter at it with
+`CLAUDE_CODE_EXECUTABLE` (honored by `claude-agent-acp` ≥ 0.55):
+
+```json
+{
+  "agent": "env CLAUDE_CODE_EXECUTABLE=/path/to/your/claude npx -y @agentclientprotocol/claude-agent-acp@0.55.0"
+}
+```
+
+`ghx sidecar config init --claude-exe /path/to/your/claude` writes exactly this
+config for you (`--claude-exe auto` resolves `claude` from your PATH; the same
+diff-and-`--force` rules apply).
+
+> **Known upstream issue (enterprise wrapper builds):** when
+> `CLAUDE_CODE_EXECUTABLE` points at a *wrapper* script/binary (e.g. a
+> corporate toolbox `claude` that resolves credentials itself), the adapter
+> can hang indefinitely at prompt time: ghx legitimately sends ACP
+> `settingSources: []` for session isolation, and some wrappers stall instead
+> of erroring when settings loading is suppressed (isolated 2026-07-06:
+> `settingSources: []` alone reproduces the hang; `strictMcpConfig` and
+> `tools` do not; mechanism: the native binary resolves Bedrock
+> `modelOverrides` from `~/.claude/settings.json` and stalls instead of
+> erroring when that read is suppressed). The fix is one config line:
+>
+> ```json
+> {
+>   "agent": "env CLAUDE_CODE_EXECUTABLE=/path/to/your/claude npx -y @agentclientprotocol/claude-agent-acp@0.55.0",
+>   "agentSettingSources": ["user"]
+> }
+> ```
+>
+> `agentSettingSources` opts the spawned agent into loading your user
+> settings (`~/.claude/settings.json`) so the wrapper's model aliases and
+> credential hooks work. It deliberately weakens session isolation — host
+> user settings apply to sidecar sessions — which is why it is opt-in and
+> off by default (ADR-0033.2). Wrapping the *adapter* in a script that
+> exports auth env itself remains a valid alternative.
+
+Embedding `env VAR=...` in the agent command makes the setting travel with the
+command itself, so it works no matter which process (CLI or resident daemon)
+spawns the agent. Exporting `CLAUDE_CODE_EXECUTABLE` in your shell also works:
+every ask forwards auth-relevant env to the agent
+([ADR-0033.1](docs/adr/0033.1-client-auth-env-passthrough.md)), and the same
+applies to Bedrock/Vertex/gateway env (`CLAUDE_CODE_USE_BEDROCK`, `AWS_*`,
+`ANTHROPIC_BASE_URL`, ...). `ghx sidecar doctor` shows exactly which names your
+shell would forward.
+
 ### 3. Verify
 
 ```bash
@@ -267,7 +327,7 @@ A main agent talks to the sidecar through a single MCP tool — one tool it cann
 be tempted into step-driving:
 
 ```bash
-ghx serve --recon     # exposes exactly one MCP tool: recon(question, repo, session?)
+ghx serve --recon     # exposes exactly one MCP tool: recon(question, repo?, session?)
 ```
 
 The recommended skill for agents is the concise recon skill (`ghx skill --recon`,
@@ -319,7 +379,7 @@ matching files. Same command, always useful output.
 ### Commands
 
 ```bash
-ghx --version                               # Health check / installed version
+ghx --version                               # Health check / installed version (also: ghx version)
 ghx explore <owner/repo>                    # Compact branch + tree + README orientation
 ghx explore <owner/repo> --full             # Complete legacy explore output
 ghx explore <owner/repo> <path>             # Compact subdirectory listing
@@ -338,11 +398,36 @@ ghx search <owner/repo> "func main"         # Repo-first code search, auto-quote
 ghx search <owner/repo> "router" --lang go  # Narrow by language
 ghx search <owner/repo> "router" --glob "**/*.go" # Narrow by path glob
 ghx search "repo:gkoreli/ghx cobra.Command" # Advanced raw GitHub code-search query
+ghx inspect <owner/repo> "routing middleware" # Concern-driven search + ranked files, maps, snippets
 ghx grep <owner/repo> "func main"           # Grep-like repo search
 ghx grep <owner/repo> "RunE" --path internal/cli --limit 10
 ghx repos "<query>"                         # Repo search with README preview
 ghx tree <owner/repo> [path]                # Full recursive tree
 ghx tree <owner/repo> [path] --depth N      # Tree limited to N levels
+ghx code "<js>"                             # Execute JS with access to all ghx tools
+ghx code --list                             # List available tools with type stubs
+ghx serve                                   # Start the direct-tools MCP server (stdio)
+ghx serve --http :8080                      # Serve MCP over streamable HTTP
+ghx serve --recon                           # Start the single-tool recon MCP service
+ghx skill                                   # Print the classic CLI skill
+ghx skill --mcp                             # Print the classic MCP skill
+ghx skill --recon                           # Print the concise recon skill
+ghx sidecar config init --claude-acp        # Write ~/.ghx/config.json for Claude ACP
+ghx sidecar config show                     # Show resolved sidecar config
+ghx sidecar doctor                          # Verify token, network, ghx binary, ACP, report sink
+ghx sidecar doctor --live                   # Run a real one-prompt ACP turn for diagnosis
+ghx sidecar ask --repo <owner/repo> "<q>"   # Delegate one repo question to the sidecar
+ghx sidecar ask "<q>"                       # Discovery question across GitHub
+ghx sidecar ask --repo <o/r> --local "<q>"  # Also allow tier-2 local analysis (codemap/ast-grep/repomap)
+ghx sidecar daemon --status                 # Inspect the warm sidecar daemon
+ghx sidecar daemon --stop                   # Stop the warm sidecar daemon
+ghx sidecar sessions list                   # List persisted sidecar sessions
+ghx sidecar sessions show <session>         # Metadata + report history
+ghx sidecar sessions ledger <session>       # Accumulated evidence ledger JSON
+ghx sidecar sessions reroute <s> <turn> <dest> # Move a mis-routed turn and rebuild ledgers
+ghx sidecar view [session]                  # Local OTel viewer over session artifacts
+ghx sidecar evals export --format sft --run <dir> --out <file> # Export committed eval episodes
+ghx sidecar report-sink --out <path>        # Internal report-sink MCP server used by ACP turns
 ghx tier2 codemap <owner/repo>              # Tier-2 cross-file structure as JSON (local snapshot)
 ghx tier2 codemap <owner/repo> --context    # Agent-ready JSON context envelope (--compact to shrink)
 ghx tier2 codemap <owner/repo> --importers <file>  # Who imports a file (fan-in; needs ast-grep)
@@ -379,9 +464,12 @@ the binary codemap needs for `--importers`/`--deps`), and `local:repomap`
 stolen with attribution from
 [aider's repo map](https://github.com/Aider-AI/aider), Apache-2.0 — an
 algorithm, not a dependency; deterministic given the same snapshot and
-query). If a tool binary is missing, ghx prints the install hint and exits
-before any clone; answers fall back to remote Tier-1 evidence — never a
-silent or faked Tier-2 result. `astgrep` follows grep parity: exit `1` with
+query). Only `local:repomap` works with zero extra installs; codemap and
+ast-grep are optional external binaries, and `ghx sidecar doctor` reports
+which tier-2 backends resolve on your machine with install hints for the
+missing ones. If a tool binary is missing, ghx prints the install hint and
+exits before any clone; answers fall back to remote Tier-1 evidence — never
+a silent or faked Tier-2 result. `astgrep` follows grep parity: exit `1` with
 `[]` means the search ran and found nothing.
 
 When the sidecar answers a question, escalation is never vibes: every turn

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gkoreli/ghx",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "description": "Agent-first GitHub code exploration. GraphQL batching, code maps, codemode TypeScript sandbox, MCP server.",
   "bin": {
     "ghx": "npm/bin/ghx"
@@ -28,11 +28,11 @@
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@gkoreli/ghx-darwin-arm64": "2.4.1",
-    "@gkoreli/ghx-darwin-x64": "2.4.1",
-    "@gkoreli/ghx-linux-arm64": "2.4.1",
-    "@gkoreli/ghx-linux-x64": "2.4.1",
-    "@gkoreli/ghx-win32-arm64": "2.4.1",
-    "@gkoreli/ghx-win32-x64": "2.4.1"
+    "@gkoreli/ghx-darwin-arm64": "2.5.0",
+    "@gkoreli/ghx-darwin-x64": "2.5.0",
+    "@gkoreli/ghx-linux-arm64": "2.5.0",
+    "@gkoreli/ghx-linux-x64": "2.5.0",
+    "@gkoreli/ghx-win32-arm64": "2.5.0",
+    "@gkoreli/ghx-win32-x64": "2.5.0"
   }
 }