hx-cli 0.2.2__tar.gz → 0.2.4__tar.gz

hx_cli-0.2.4/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store
+.hx/sessions/
+# Not .hx/settings.json: that file is the project's *shared* configuration and
+# is meant to be checked in. What HX writes on your behalf - permission grants
+# and the rest - lives under $HX_HOME/projects/<slug>, outside the checkout
+# entirely, so there is nothing here left to hide.
+snapshot_report.html

{hx_cli-0.2.2 → hx_cli-0.2.4}/CHANGELOG.md

@@ -28,6 +28,131 @@ the project follows [semantic versioning](https://semver.org/).
 
 ---
 
+## [0.2.4] - 2026-09-19
+
+### Added
+
+- `/trace [path]`: write the whole session to one self-contained HTML page and
+  open it. The system prompt, the project context, the skills index, every tool
+  schema, every prompt and reply, every thinking block, every tool call beside
+  the result it produced, the per-call token ledger and the files HX changed.
+  Late-injected reminders and compacted turns are included behind a toggle.
+  A session still running traces as it stands, including the turn that just
+  landed. The page follows your system's dark or light setting and a button
+  overrides it; nothing is fetched and nothing is uploaded.
+- `hx trace [SESSION_ID] [PATH]`: the same page for any transcript on the
+  machine, without starting a session. Defaults to the last session in this
+  directory and prints only the path, so `open "$(hx trace)"` works. Either
+  argument may be given alone - a lone one that looks like a path is one.
+- The system prompt and the tool schemas are now written to the transcript on a
+  session's first provider call, so a trace of a finished session can say what
+  the model was told and not only what it said.
+
+### Security
+
+- Permission rules are matched against the path a specifier resolves to, not
+  the text it was written as. `deny: Read(~/.ssh/**)` was got past by asking
+  for `../../.ssh/id_rsa`, or through a symlink planted in the project. The
+  same resolution stops an allow rule leaking: `allow: Edit(src/**)` used to
+  cover `src/../../etc/passwd`.
+- `WebFetch` is matched against every URL it was given rather than the first,
+  so `deny: WebFetch(https://host/**)` is no longer a question of list order.
+  The approval prompt spells the URLs out too; it said `urls=[2 items]`, which
+  answered the only question that mattered with a number.
+- The generated Seatbelt profile no longer grants write access to all of
+  `/private/var/folders` - every user's and every process's temp and cache.
+  `$TMPDIR` was resolved precisely to avoid that, and the profile handed it
+  back on the next line. This user's own container stays writable.
+- `~/.hx/auth.json` is created with mode 0600 rather than narrowed to it after
+  the tokens are written, closing a window at a predictable path where the
+  credential was readable by any local account.
+- The OAuth callback page escapes what the provider sent. An `error` parameter
+  carrying markup ran as HTML on a loopback origin that is otherwise the
+  user's own.
+
+### Fixed
+
+- Slash commands read the session that is in force rather than the one HX
+  opened with. After `/resume`, `/trace` wrote a page of zeros into the empty
+  startup session's directory and `/cost` reported nobody's usage: the command
+  context had captured the session object at startup, and `/resume` rebinds it.
+- A session whose title was the trace template's own data placeholder had the
+  whole payload spliced into the page's `<title>`.
+- A trace labelled an encrypted reasoning block "thinking (signed)", which read
+  as though the page had dropped the rest of it. It now says the text is the
+  provider's summary and the reasoning came back encrypted, and a block that
+  arrived with no summary at all says that rather than rendering an empty box.
+- MCP servers survive a large response. One JSON-RPC message is one line and
+  asyncio's stream limit is 64 KiB, so a tool returning a file did not truncate
+  - it raised out of the read loop and killed the connection for the rest of
+  the session. The limit is now 16 MiB, and overshooting it says so.
+- A tool call is no longer dropped when a stream ends without a `finish_reason`.
+  The arguments were buffered until that field arrived, so a complete call was
+  discarded and the turn reported `end_turn`: the model appeared to stop for no
+  reason, and the tokens were already paid for.
+- The Linux sandbox starts again for anyone with credential *files*. Denied
+  paths were all shadowed with `--tmpfs`, which mounts a directory and aborts
+  bwrap when aimed at a file - and six of them are files, `~/.hx/auth.json`
+  among them. Files are shadowed with `/dev/null` instead. bwrap also starts in
+  the policy's directory rather than whatever `$PWD` happened to hold.
+- `PersistentShell.cwd` follows the shell. It claimed to track it and was in
+  fact the launch directory forever, which meant a background job always
+  started where the session opened rather than where `cd` had left it.
+- A background job no longer leaks its log file descriptor for the life of the
+  session.
+- A record appended while the transcript was being written is no longer
+  dropped. The queue is taken in one step, and a failed write puts its records
+  back rather than losing them.
+- An automatic compaction with nothing to summarise is no longer announced and
+  rerun every turn for the rest of the session. `/compact` still answers either
+  way.
+- `/trace` takes `--no-open`, and never launches a *terminal* browser: with no
+  display, `webbrowser` falls through to lynx or w3m, which opens in the
+  terminal HX is drawing on and takes the session display with it.
+
+---
+
+## [0.2.3] - 2026-09-18
+
+### Added
+
+- Hooks: shell commands HX runs at `PreToolUse`, `PostToolUse`,
+  `UserPromptSubmit` and `Stop`. A hook can refuse an action (exit 2, or
+  `{"decision": "block"}`), rewrite a tool's arguments before the permission
+  engine sees them (`updatedInput`), or add a note for the model
+  (`additionalContext`). Configure them under `"hooks"` in
+  `~/.hx/settings.json`; `/hooks` lists what is loaded. Hooks declared in a
+  project's checked-in `.hx/settings.json` are ignored and reported, because
+  cloning a repository must not be enough to run commands on your machine.
+- `Symbols`: outline a file, find where a name is defined, or find where it is
+  used, over a tree-sitter parse tree rather than a regex - so a match inside a
+  comment or a string never counts. Python, TypeScript, JavaScript, Go and
+  Rust. Needs the grammars: `uv tool install "hx-cli[symbols]"`. Without them
+  the tool is not registered at all.
+- An example hook, `examples/hooks/check.sh`: after every `Edit`/`Write` it
+  runs the project's own checker (`ruff`, `tsc`, `go vet`, `cargo check`)
+  against just that file and hands the output back to the model, so a typo is
+  caught on the next turn instead of at test time.
+- Line anchors. `Read` now labels each line with a short content hash, and
+  `Edit` accepts those anchors in a `hashline` argument to replace a span
+  without retyping it. An anchor that no longer resolves means the file moved,
+  so the patch is rejected instead of landing at the wrong lines. Set
+  `"tools": {"hashline": false}` to go back to plain `cat -n` reads.
+
+### Removed
+
+- The `telemetry` setting, which was parsed and never read by anything.
+
+### Fixed
+
+- The README's Status section said there were two model routes; Devin made it
+  three in 0.2.2.
+- `MultiEdit` and `NotebookEdit` were listed as mutating tools and as edit
+  tools in the permission engine, but no such tools exist. A rule written
+  against either name silently matched nothing.
+
+---
+
 ## [0.2.2] - 2026-09-17
 
 ### Added
@@ -440,7 +565,9 @@ First release, published to PyPI as [`hx-cli`](https://pypi.org/project/hx-cli/)
 - `/configure` and `hx auth` for the OpenRouter key, `hx upgrade` for
   self-update, and `install.sh` bootstrapping uv with a pinned Python.
 
-[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.4...HEAD
+[0.2.4]: https://github.com/aletisunil/hx/compare/v0.2.3...v0.2.4
+[0.2.3]: https://github.com/aletisunil/hx/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/aletisunil/hx/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/aletisunil/hx/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/aletisunil/hx/compare/v0.1.9...v0.2.0

hx_cli-0.2.2/README.md → hx_cli-0.2.4/PKG-INFO

@@ -1,3 +1,42 @@
+Metadata-Version: 2.5
+Name: hx-cli
+Version: 0.2.4
+Summary: HX - an agent harness for the terminal
+Project-URL: Homepage, https://hx.sunilaleti.dev
+Project-URL: Documentation, https://hx.sunilaleti.dev
+Project-URL: Source, https://github.com/aletisunil/hx
+Project-URL: Issues, https://github.com/aletisunil/hx/issues
+Author: Sunil Aleti
+License: MIT
+Keywords: agent,cli,coding-agent,llm,openrouter,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pygments>=2.17
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: truststore>=0.10
+Requires-Dist: wcwidth>=0.2.13
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pyte>=0.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pygments; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: symbols
+Requires-Dist: tree-sitter-language-pack>=0.7; extra == 'symbols'
+Requires-Dist: tree-sitter>=0.23; extra == 'symbols'
+Description-Content-Type: text/markdown
+
 # HX
 
 An agent harness for the terminal. Python core, its own terminal renderer,
@@ -260,6 +299,9 @@ hx -p "explain this repo"   # headless: streams to stdout, tool activity to stde
 hx resume                   # resume the last session here
 hx resume <session-id>      # resume a specific one
 hx prompt                   # print the system prompt this directory would use
+hx trace                    # write the last session here to an HTML page
+hx trace out.html           # the same, to a path you choose
+hx trace <id> out.html      # a specific session, to a path you choose
 hx --model openai/gpt-5     # override the model for one run
 hx --mode plan              # start read-only
 hx --cwd ../other-project   # run against a different directory
@@ -403,9 +445,11 @@ than being silently resolved.
 | `/skills` | installed skills |
 | `/agents` | subagent types |
 | `/mcp` | server status |
+| `/hooks` | configured hooks, and any that were refused |
 | `/theme [name]` | `dark`, `light`, `ansi`, or any theme in `~/.hx/themes` |
 | `/queue [steer <n>\|clear]` | messages waiting for the turn to end, and what to do with them |
 | `/copy` | copy the last reply to the clipboard |
+| `/trace [path]` | write the whole session to a self-contained HTML page |
 | `/fullscreen [on\|off]` | take the whole window, with the prompt pinned to the bottom |
 | `/mouse [on\|off]` | mouse reporting, and with it your terminal's own text selection |
 | `/init` | generate an `AGENTS.md` for the project |
@@ -520,7 +564,6 @@ along with the `.hx/.gitignore` it added to hide it.
 {
   "theme": "dark",                    // dark | light | ansi, or a file in ~/.hx/themes
   "quiet_startup": false,             // skip the startup header
-  "telemetry": false,
 
   "models": {
     "model": "anthropic/claude-sonnet-4.5",
@@ -563,10 +606,18 @@ along with the `.hx/.gitignore` it added to hide it.
   "tui": {
     "enterWhileBusy": "queue",        // queue | steer - what enter does mid-turn
     "fullscreen": false               // true takes the whole window (see /fullscreen)
+  },
+
+  "tools": {
+    "hashline": true                  // Read labels lines with content anchors Edit accepts
   }
 }
 ```
 
+`hooks` is configured in the same files but is deliberately not part of this
+merge: it is read per layer, and only from your own settings. See
+[Extending it](#extending-it).
+
 Environment overrides: `HX_MODEL`, `HX_SUBAGENT_MODEL`, `HX_MAX_TOKENS`,
 `HX_PERMISSION_MODE`, `HX_SANDBOX`, `HX_COMPACT_AT`, `HX_GIT_NOTICES`,
 `HX_THEME`, `HX_QUIET_STARTUP`. Also `HX_HOME` to relocate user state, `HX_TAVILY_API_KEY`
@@ -644,6 +695,7 @@ files load here unchanged. `src/hx/tui/themes/dark.json` is the reference.
 | `~/.hx/system-prompt.md` | your system prompt, replacing the built-in one |
 | `~/.hx/system-prompt-append.md` | text appended to whichever prompt is in force |
 | `~/.hx/sessions/` | transcripts, spilled tool output, subagent sessions |
+| `~/.hx/sessions/<id>/trace.html` | where `/trace` writes, unless you name a path |
 | `~/.hx/skills/`, `~/.hx/agents/` | your skills and agents |
 | `~/.hx/projects/<project>/settings.local.json` | this machine's settings for one project - where "always allow" lands |
 | `./.hx/settings.json` | project settings, checked in if you like — read by HX, never written |
@@ -727,6 +779,127 @@ rest to the session directory, and hands the model that path to grep.
 
 ---
 
+## Tracing a session
+
+`/trace` writes everything that happened to one self-contained HTML file and
+opens it in a browser:
+
+```
+/trace                      # ~/.hx/sessions/<id>/trace.html
+/trace ~/Desktop/bug.html   # somewhere you choose
+```
+
+Everything means everything. The system prompt, the project context, the skills
+index, every tool schema as the provider received it, every prompt, every
+reply, every thinking block, every tool call next to the result it produced,
+the per-call token ledger, and the files HX changed. Late-injected reminders
+and compacted turns are in there too, behind a toggle that says how many there
+are — a trace that hides the reminders and the superseded turns is not a trace
+of the session that ran.
+
+Nothing is summarised and nothing is prettified. Assistant text is shown as it
+arrived, backticks and all, because a trace exists to answer "what actually
+went through" and a rendered version of that is a different document. Long tool
+results are folded rather than truncated, with the character count on the fold.
+
+**Thinking, where the provider allows it.** How much of a model's reasoning HX
+ever sees is the provider's decision, not HX's. Anthropic's models return the
+thinking itself. The Responses API - the OpenAI and Codex routes - returns a
+one-line summary in plaintext and the reasoning encrypted, to be replayed on
+the next call and read by nobody, HX included. A trace labels which of the two
+it is holding, because a one-line thinking block is otherwise indistinguishable
+from a trace that dropped the rest.
+
+A running session traces as it stands right now, including the turn that just
+landed. The page says so, because a trace of a live session is a snapshot.
+
+**Reading it.** Long tool results are folded and the reference panels - the
+prompt, the schemas, the ledger - start shut, so the transcript is what you
+land on. "Expand all" opens the whole page, panels included, and turns into
+"Collapse all". A session with no turns yet opens its panels on its own, since
+there is nothing else to read.
+
+**Dark or light.** The page follows your system by default and a button in the
+corner overrides it, remembered per browser. No stylesheet is fetched to do it.
+
+**Nothing is uploaded and nothing is fetched.** The payload, the stylesheet and
+the script all live in the file, so it opens offline, renders the same a year
+later, and a trace of a private repository stays as private as the directory
+you wrote it into. The embedded payload is also the machine-readable trace: it
+is JSON, in a `<script id="trace-data">` element, and `/trace` is the only way
+HX will ever put your transcript anywhere but `~/.hx`.
+
+From outside a session, on any transcript on the machine:
+
+```sh
+hx trace                        # the last session in this directory
+hx trace 20260918-214743-b5b8f9 # one by id
+hx trace ~/somewhere.html       # the last session, to a path you choose
+hx trace <id> ~/somewhere.html  # both, to a path or a directory
+open "$(hx trace)"              # the path is all that goes to stdout
+```
+
+`hx trace` reads the transcript and runs nothing, so it works on a session that
+ended months ago and on one another terminal has open right now.
+
+**What a trace can be missing.** The prompt and the tool schemas are written to
+the transcript on the session's first provider call — the first moment the tool
+registry has settled, because MCP servers connect after the loop is built. A
+session traced before that call, or one recorded by a version of HX older than
+this feature, has the transcript but not the prompt, and the page leaves those
+panels out rather than guessing. `/trace` inside a live session fills them in
+from the loop either way.
+
+---
+
+## Reading and editing code
+
+**Line anchors.** `Read` labels every line with a short content hash:
+
+```
+     1 a3f9	def handle(request):
+     2 7c1c	    if request.method == "POST":
+```
+
+The anchor is a hash of the line and its two neighbours, truncated to the
+narrowest width that is unambiguous in that file. `Edit` takes those anchors
+instead of retyped content:
+
+```json
+{ "file_path": "app.py", "hashline": [{ "start": "a3f9", "end": "7c1c", "new_string": "..." }] }
+```
+
+The span is inclusive; omit `end` to replace one line, pass an empty
+`new_string` to delete. Anchors are recomputed from disk when the edit runs, so
+a file that moved under the model fails to resolve and the patch is rejected
+rather than applied at stale coordinates. Exact-match `old_string` still works
+and is unchanged; anchors are a second shape, not a replacement. Turn the whole
+thing off with `"tools": {"hashline": false}` and reads go back to plain
+`cat -n`.
+
+**Symbols** answers structural questions with a parse tree rather than a
+regex — three modes, `outline` for one file's shape, `definition` for where a
+name is defined, `references` for where it is used:
+
+```
+Symbols(mode="references", symbol="handle")
+```
+
+Because it matches identifier nodes, the same word in a comment or a string
+literal never matches. It cannot resolve types, so an unrelated symbol with the
+same name in another file still does; it is tighter than `Grep`, not a language
+server. Python, TypeScript, JavaScript, Go and Rust.
+
+It needs grammars that are not installed by default, and the tool is simply not
+registered without them — its schema never enters the cached prefix advertising
+something that cannot run:
+
+```sh
+uv tool install "hx-cli[symbols]"
+```
+
+---
+
 ## Extending it
 
 **Skills** are directories containing `SKILL.md` with YAML frontmatter:
@@ -783,6 +956,68 @@ Or `hx mcp add local python server.py`. Tools arrive namespaced
 with a per-server timeout; one that is broken or slow logs a warning and is
 dropped rather than taking the session with it.
 
+**Hooks** are shell commands HX runs at named points in a turn. Four events:
+`PreToolUse`, `PostToolUse`, `UserPromptSubmit` and `Stop`.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "~/.hx/guard-bash.sh", "timeout": 10 }]
+      }
+    ],
+    "PostToolUse": [
+      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "ruff check --quiet" }] }
+    ]
+  }
+}
+```
+
+`matcher` is a regex matched against the whole tool name; omit it, or use `*`,
+to match every tool. The hook reads a JSON event on stdin — `session_id`,
+`cwd`, `hook_event_name`, and `tool_name`/`tool_input` where they apply — and
+answers with its exit code:
+
+| Exit | Means |
+|---|---|
+| `0` | allow |
+| `2` | block. stderr becomes the reason the model is given |
+| anything else | the hook is broken. Reported as a notice; the action proceeds |
+
+That last row is deliberate: a typo in a shell command must not be able to
+wedge a session. Only an explicit refusal stops anything.
+
+A hook may also print JSON on stdout: `{"decision": "block", "reason": "..."}`
+refuses, `{"updatedInput": {...}}` rewrites a tool's arguments before the
+permission engine sees them, and `{"additionalContext": "..."}` adds a note for
+the model to read. The format matches Claude Code's, so hooks already written
+against that work here unchanged.
+
+A worked example ships in the repository:
+[`examples/hooks/check.sh`](https://github.com/aletisunil/hx/blob/main/examples/hooks/check.sh)
+runs the checker a project already has — `ruff`, `tsc`, `go vet`, `cargo
+check` — against the one file the model just edited, and returns whatever it
+says as `additionalContext`. The model sees the errors appended to its own edit
+result and fixes them on the next turn, rather than discovering them at test
+time. It exits 0 either way: by `PostToolUse` the write has already landed, so
+refusing it would be an answer to something that already happened.
+
+```sh
+curl -o ~/.hx/check.sh https://raw.githubusercontent.com/aletisunil/hx/main/examples/hooks/check.sh
+chmod +x ~/.hx/check.sh
+```
+
+**Where hooks may be declared is a security boundary.** They are loaded from
+`~/.hx/settings.json` and `~/.hx/projects/<slug>/settings.local.json` only.
+Hooks in a project's checked-in `.hx/settings.json` are ignored and listed by
+`/hooks`, because that file arrives with a clone and cloning a repository must
+never be enough to run commands on the machine that cloned it. To adopt a
+shared hook, copy it into your own settings — a deliberate act by the person
+who will run it. Subagents inherit the parent's hooks, so a guard cannot be
+bypassed by delegating through `Task`.
+
 ---
 
 ## Development
@@ -833,9 +1068,10 @@ src/hx/
   core/         loop, context assembly, compaction, late injection, sessions, usage
   auth/         credential store, OAuth flows, per-route resolution
   providers/    OpenRouter, Codex, Devin, the model catalogue, a scripted provider for tests
-  tools/        Bash, Read, Write, Edit, Glob, Grep, TodoWrite, Task, WebSearch,
-                WebFetch, output capping
+  tools/        Bash, Read, Write, Edit, Glob, Grep, Symbols, TodoWrite, Task,
+                WebSearch, WebFetch, line anchors, output capping
   permissions/  rule engine, shell decomposition, Seatbelt/bubblewrap
+  hooks/        the four events, the trust boundary, subprocess execution
   skills/ agents/ mcp/
   keys.py       keybinding registry: ids, defaults, descriptions, user overrides
   term/         the renderer: raw mode, input decoding, the differ, the screen
@@ -898,12 +1134,13 @@ streaming with prefix caching and accurate cost accounting, session persistence
 and resume, the tool suite, the permission engine and OS sandbox, late
 injection, compaction, output capping, skills, subagents, MCP, and the TUI.
 
-Two routes to a model: an OpenRouter API key, or a ChatGPT Plus/Pro
-subscription over OAuth. The model id decides which.
+Three routes to a model: an OpenRouter API key, a ChatGPT Plus/Pro
+subscription over OAuth, or a Devin subscription over OAuth. The model id
+decides which.
 
 Published to PyPI as [`hx-cli`](https://pypi.org/project/hx-cli/), released
 from CI on a tag.
 
-The one thing still unproven in CI is a live call on either route: the `live`
-tests exist and cover both wire formats, tool use, reasoning replay and a
+The one thing still unproven in CI is a live call on any route: the `live`
+tests exist and cover all three wire formats, tool use, reasoning replay and a
 genuine cache hit, but they need a credential and are deselected by default.