hx-cli 0.2.3__tar.gz → 0.2.5__tar.gz

hx_cli-0.2.5/.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.3 → hx_cli-0.2.5}/CHANGELOG.md

@@ -28,6 +28,117 @@ the project follows [semantic versioning](https://semver.org/).
 
 ---
 
+## [0.2.5] - 2026-09-23
+
+### Added
+
+- Images as input. `ctrl+v` attaches the image on the clipboard, dragging an
+  image file into the terminal attaches it, and `hx -p "..." --image PATH`
+  attaches one to a headless prompt. Each shows in the prompt as
+  `[Image #N]`.
+- `Read` returns image files as images, so the model can look at a screenshot
+  or mockup it is pointed at with `@path`.
+- Images returned by MCP tools reach the model instead of being dropped.
+- Every route carries images: OpenRouter, the Codex subscription and the Devin
+  subscription. Large images are scaled and re-encoded to fit each route's
+  limits.
+- A model that does not accept images is warned about when one is attached,
+  and is told the image was left out rather than sent a request that fails.
+  The `/model` picker marks the models that can see images.
+
+### Fixed
+
+- Background jobs are waited for, not only signalled, when a session closes.
+  An unwaited subprocess transport was collected after the event loop had
+  gone, which raised `Event loop is closed` as an unraisable warning on CI
+  runs that otherwise passed.
+
+---
+
+## [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
@@ -481,7 +592,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.3...HEAD
+[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.5...HEAD
+[0.2.5]: https://github.com/aletisunil/hx/compare/v0.2.4...v0.2.5
+[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

hx_cli-0.2.3/README.md → hx_cli-0.2.5/PKG-INFO

@@ -1,3 +1,43 @@
+Metadata-Version: 2.5
+Name: hx-cli
+Version: 0.2.5
+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: pillow>=10.4
+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,
@@ -257,9 +297,13 @@ available through OpenRouter.
 ```sh
 hx                          # interactive TUI in the current directory
 hx -p "explain this repo"   # headless: streams to stdout, tool activity to stderr
+hx -p "why?" --image s.png  # attach an image to a headless prompt; repeatable
 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
@@ -333,6 +377,7 @@ be rebound (see [Keybindings](#keybindings)).
 | `pgdn` | scroll the transcript down (fullscreen; otherwise your terminal scrolls) |
 | `ctrl+home` | jump to the start: the viewport in fullscreen, the first message otherwise |
 | `ctrl+end` | jump back to the newest output |
+| `ctrl+v` | attach the image on the clipboard (see [Images](#images)) |
 | `@path` | complete a file path |
 | `!command` | run a shell command directly, no model turn |
 
@@ -364,6 +409,44 @@ text](#selecting-and-copying-text) for the terminal's own selection.
 HX does not emit OSC 133 prompt markers yet, so shell-integration features that
 jump between prompts will not see HX's messages.
 
+#### Images
+
+Give the model a picture three ways, and each lands in the prompt as a token
+such as `[Image #1]`:
+
+- **`ctrl+v`** attaches whatever image is on the clipboard: a screenshot copied
+  with `cmd+ctrl+shift+4`, an image copied in a browser, or an image file
+  copied in Finder or a file manager. Terminals whose own paste sends nothing
+  when the clipboard holds a picture are caught too - an empty paste is read as
+  a request for the image.
+- **Drag an image file** into the terminal. The terminal pastes its path, and a
+  paste that is nothing but paths to image files attaches them instead of
+  inserting the text. Quoted, backslash-escaped and `file://` paths all work.
+- **Mention it.** `look at @docs/mockup.png` sends the path as text, and the
+  model opens it with `Read`, which returns images as images.
+
+The token is the attachment: move it and the text refers to the picture in a
+different place, delete it (one `backspace` takes the whole token) and the
+image is not sent. Sent messages list their images underneath, with size and
+weight. Numbers run for the whole session, so a message recalled from history
+or restored by a rewind still carries its pictures.
+
+PNG, JPEG, GIF, WebP, BMP and TIFF are accepted. An image within every route's
+limits goes byte for byte; a larger one is scaled to 2000 px on its long side
+and re-encoded to stay under 5 MB, which is what a retina screenshot usually
+needs. Images an MCP tool returns - a browser screenshot, say - are handled the
+same way rather than dropped.
+
+Whether a model can see images comes from the catalogue: OpenRouter's input
+modalities, the Codex catalogue, and Devin's model config. The `/model` picker
+marks the ones that can with `images`. A model that cannot
+is warned about when you attach, and is sent a line saying an image was left
+out, rather than a request that fails. The transcript keeps the image either
+way, so `/model` to one that can see it and ask again.
+
+Over SSH the clipboard you copied into is on your own machine, so `ctrl+v`
+says so; copy the file over and drag or paste its path instead.
+
 #### Keybindings
 
 Any key can be rebound in `~/.hx/keybindings.json`, keyed by the action ids in
@@ -407,6 +490,7 @@ than being silently resolved.
 | `/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 |
@@ -652,6 +736,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 |
@@ -735,6 +820,79 @@ 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:
@@ -760,6 +918,10 @@ 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`.
 
+**Images.** `Read` on a PNG, JPEG, GIF, WebP, BMP or TIFF - or on a file with
+no extension whose bytes are one - returns the image itself for the model to
+look at, normalised the way a pasted one is (see [Images](#images)).
+
 **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:

hx_cli-0.2.3/PKG-INFO → hx_cli-0.2.5/README.md

@@ -1,40 +1,3 @@
-Metadata-Version: 2.5
-Name: hx-cli
-Version: 0.2.3
-Summary: HX - an agent harness for the terminal
-Project-URL: Homepage, 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,
@@ -294,9 +257,13 @@ available through OpenRouter.
 ```sh
 hx                          # interactive TUI in the current directory
 hx -p "explain this repo"   # headless: streams to stdout, tool activity to stderr
+hx -p "why?" --image s.png  # attach an image to a headless prompt; repeatable
 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
@@ -370,6 +337,7 @@ be rebound (see [Keybindings](#keybindings)).
 | `pgdn` | scroll the transcript down (fullscreen; otherwise your terminal scrolls) |
 | `ctrl+home` | jump to the start: the viewport in fullscreen, the first message otherwise |
 | `ctrl+end` | jump back to the newest output |
+| `ctrl+v` | attach the image on the clipboard (see [Images](#images)) |
 | `@path` | complete a file path |
 | `!command` | run a shell command directly, no model turn |
 
@@ -401,6 +369,44 @@ text](#selecting-and-copying-text) for the terminal's own selection.
 HX does not emit OSC 133 prompt markers yet, so shell-integration features that
 jump between prompts will not see HX's messages.
 
+#### Images
+
+Give the model a picture three ways, and each lands in the prompt as a token
+such as `[Image #1]`:
+
+- **`ctrl+v`** attaches whatever image is on the clipboard: a screenshot copied
+  with `cmd+ctrl+shift+4`, an image copied in a browser, or an image file
+  copied in Finder or a file manager. Terminals whose own paste sends nothing
+  when the clipboard holds a picture are caught too - an empty paste is read as
+  a request for the image.
+- **Drag an image file** into the terminal. The terminal pastes its path, and a
+  paste that is nothing but paths to image files attaches them instead of
+  inserting the text. Quoted, backslash-escaped and `file://` paths all work.
+- **Mention it.** `look at @docs/mockup.png` sends the path as text, and the
+  model opens it with `Read`, which returns images as images.
+
+The token is the attachment: move it and the text refers to the picture in a
+different place, delete it (one `backspace` takes the whole token) and the
+image is not sent. Sent messages list their images underneath, with size and
+weight. Numbers run for the whole session, so a message recalled from history
+or restored by a rewind still carries its pictures.
+
+PNG, JPEG, GIF, WebP, BMP and TIFF are accepted. An image within every route's
+limits goes byte for byte; a larger one is scaled to 2000 px on its long side
+and re-encoded to stay under 5 MB, which is what a retina screenshot usually
+needs. Images an MCP tool returns - a browser screenshot, say - are handled the
+same way rather than dropped.
+
+Whether a model can see images comes from the catalogue: OpenRouter's input
+modalities, the Codex catalogue, and Devin's model config. The `/model` picker
+marks the ones that can with `images`. A model that cannot
+is warned about when you attach, and is sent a line saying an image was left
+out, rather than a request that fails. The transcript keeps the image either
+way, so `/model` to one that can see it and ask again.
+
+Over SSH the clipboard you copied into is on your own machine, so `ctrl+v`
+says so; copy the file over and drag or paste its path instead.
+
 #### Keybindings
 
 Any key can be rebound in `~/.hx/keybindings.json`, keyed by the action ids in
@@ -444,6 +450,7 @@ than being silently resolved.
 | `/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 |
@@ -689,6 +696,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 |
@@ -772,6 +780,79 @@ 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:
@@ -797,6 +878,10 @@ 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`.
 
+**Images.** `Read` on a PNG, JPEG, GIF, WebP, BMP or TIFF - or on a file with
+no extension whose bytes are one - returns the image itself for the model to
+look at, normalised the way a pasted one is (see [Images](#images)).
+
 **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:

{hx_cli-0.2.3 → hx_cli-0.2.5}/pyproject.toml

@@ -33,6 +33,7 @@ dependencies = [
   "pygments>=2.17",
   # CommonMark parsing. The renderer is ours; the parser is not worth writing.
   "markdown-it-py>=3.0",
+  "pillow>=10.4",
 ]
 
 [project.optional-dependencies]
@@ -60,7 +61,9 @@ dev = [
 hx = "hx.cli:main"
 
 [project.urls]
-Homepage = "https://github.com/aletisunil/hx"
+Homepage = "https://hx.sunilaleti.dev"
+Documentation = "https://hx.sunilaleti.dev"
+Source = "https://github.com/aletisunil/hx"
 Issues = "https://github.com/aletisunil/hx/issues"
 
 # The version lives in the package, not here - three hand-maintained copies

{hx_cli-0.2.3 → hx_cli-0.2.5}/src/hx/__init__.py

@@ -1,5 +1,5 @@
 """HX - an agent harness for the terminal."""
 
-__version__ = "0.2.3"
+__version__ = "0.2.5"
 
 __all__ = ["__version__"]

{hx_cli-0.2.3 → hx_cli-0.2.5}/src/hx/auth/oauth/callback.py

@@ -12,6 +12,7 @@ where the browser reaches the host by another address.
 from __future__ import annotations
 
 import asyncio
+import html
 import os
 import threading
 from dataclasses import dataclass
@@ -49,7 +50,18 @@ p{{margin:0;color:#9aa4b2}}
 
 
 def _page(title: str, body: str, *, ok: bool) -> bytes:
-    return _PAGE.format(title=title, body=body, colour="#7ee787" if ok else "#ff7b72").encode()
+    """Render the one page this server serves.
+
+    Both fields are escaped: ``body`` carries the provider's ``error``
+    parameter, which arrives from the network and is under nobody's control
+    here. Interpolated raw, ``?error=<img src=x onerror=...>`` executed on an
+    origin that is otherwise this machine's own.
+    """
+    return _PAGE.format(
+        title=html.escape(title),
+        body=html.escape(body),
+        colour="#7ee787" if ok else "#ff7b72",
+    ).encode()
 
 
 class _Handler(BaseHTTPRequestHandler):

{hx_cli-0.2.3 → hx_cli-0.2.5}/src/hx/auth/store.py

@@ -21,6 +21,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import os
 import time
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field, replace
@@ -172,9 +173,22 @@ class AuthStore:
         path.parent.mkdir(parents=True, exist_ok=True)
         payload = {pid: cred.to_json() for pid, cred in sorted(data.items())}
 
+        # Created 0600, not chmod'd to it afterwards. The file is opened at
+        # whatever the umask allows and only narrowed once the tokens are
+        # already in it, which leaves a window - at a path anyone can predict -
+        # where the credential is world-readable. Passing the mode to `open`
+        # closes it: there is no instant at which the descriptor exists and the
+        # permissions are wrong.
         tmp = path.with_suffix(".json.tmp")
-        tmp.write_text(json.dumps(payload, indent=2))
-        # Restrict before the rename so the token is never briefly world-readable.
+        descriptor = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        try:
+            with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+                handle.write(json.dumps(payload, indent=2))
+        except BaseException:
+            tmp.unlink(missing_ok=True)
+            raise
+        # O_CREAT leaves an existing file's mode alone, so a store written by
+        # an older HX is narrowed here rather than keeping its old permissions.
         tmp.chmod(0o600)
         tmp.replace(path)