tau-tui 0.2.0__tar.gz

tau_tui-0.2.0/.gitignore

@@ -0,0 +1,25 @@
+.DS_Store
+.env
+.env.*
+!.env.example
+*.local.env
+__pycache__/
+*.py[cod]
+
+# Python / uv
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+
+# Personal facts about the user stay local (persona/user.example.md is the tracked template)
+persona/user.md
+
+# Tools tau wrote itself, waiting for approval
+tools/_pending/*
+!tools/_pending/.gitkeep
+
+# MkDocs build output
+site/

tau_tui-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fport
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tau_tui-0.2.0/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.5
+Name: tau-tui
+Version: 0.2.0
+Summary: Textual terminal UI for tau: streamed markdown replies, tool cards, live events and in-TUI approvals.
+Project-URL: Homepage, https://github.com/fport/tau
+Project-URL: Documentation, https://docs.tau.getporti.com
+Project-URL: Issues, https://github.com/fport/tau/issues
+Project-URL: Changelog, https://github.com/fport/tau/releases
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,assistant,cli,tau,terminal,textual,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13
+Requires-Dist: tau-core>=0.1.0
+Requires-Dist: textual<9,>=8.2
+Description-Content-Type: text/markdown
+
+# tau-tui
+
+The [Textual](https://textual.textualize.io/) terminal interface for tau: replies stream in as
+markdown, tool calls are cards with their tier, approval and result, agent events show in a live
+pane, tier-2 calls ask in a modal dialog, and the brand's τ mark opens every new session. One row
+of chrome at the top, at most four at the bottom, so 80x24 over mosh on a phone stays usable.
+
+It is its own distribution (`tau-tui`, import `tau_tui`), uses only the public API of `tau-core`
+and plugs into the `tau` command through the `tau.commands` entry point (`tui`):
+
+```sh
+pip install tau-tui          # or, in this repo: uv sync --all-packages --group dev
+tau tui                      # new session
+tau tui --resume             # continue the most recent earlier session
+tau tui --resume ID          # continue a given session
+tau --home /path/to/tau --lang tr tui --profile travel
+```
+
+Configuration comes from `tau.toml` and `.env` like every other channel (`TAU_HOME`,
+`TAU_DATA_DIR`, `TAU_PROFILE`, `TAU_LANG`). Missing credentials, a broken config or an unknown
+session end the command with a plain English message and exit code 2 before the interface opens.
+The chrome (hints, labels, notices, the approval dialog) follows `[ui] language` (`en` or `tr`);
+`/lang` switches it for one run.
+
+## Layout
+
+Four bands by width (`-phone` < 60 cols, `-narrow` 60–99, `-wide` 100–139, `-ultra` ≥ 140) and
+three by height (`-short` < 20 rows, `-mid`, `-tall` ≥ 30). The header is one row, the composer a
+rounded box of one to five text rows, the hint bar one row.
+
+80x24 (`-narrow`), idle after a two-tool turn:
+
+```text
+ τ tau  home · 20260929-120000-abcd                                  brain · en
+ › Salon lambası açık mı? Açıksa kapat.
+ ● get_light_state(room="salon")                                  tier 0 · 38ms
+   ⎿  {"on": true, "brightness": 80}
+ ● set_light(room="salon", on=false)                  tier 2 · approved · 412ms
+   ⎿  Light turned off
+ τ Salon lambası kapatıldı.
+   • Önceki durum: açık, %80 parlaklık
+ ✓ Worked for 4s · 2 tool calls · ctrl+o expand
+╭──────────────────────────────────────────────────────────────────────────────╮
+│ ❯ Type a message…                                                            │
+╰──────────────────────────────────────────────────────────────────────────────╯
+ ? shortcuts · / commands · ctrl+j newline                          ctrl+q quit
+```
+
+100x30 (`-wide`): the events pane docks on the right (34 cols; 40 at `-ultra`), `ctrl+e` hides
+it. 160x45 (`-ultra`): a read-only session sidebar (28 cols) on the left; clicking a row resumes.
+
+```text
+ τ tau  home · 20260929-120000-abcd                          brain · 7 tools · en
+ › Salon lambası açık mı? Açıksa kapat.          │ Events · 5
+ ● get_light_state(room="salon")   tier 0 · 38ms │ 12:00:01 ● get_light_state
+   ⎿  {"on": true, "brightness": 80}             │          tier 0 · ok · 38ms
+ τ Salon lambası kapatıldı.                      │ 12:00:02 ◆ approval set_light
+                                                 │          tier 2 → approved (tui)
+```
+
+80x30 (`-narrow -tall`): an 8-row events strip under the transcript. Below 100 cols `ctrl+e` /
+F4 swaps the transcript for the events log in the same body; the composer stays live and Esc
+returns to the chat.
+
+50x24 (`-phone`, Termius over mosh): the header drops the session id (`/session` shows it),
+tool badges move to the result line, the composer has no border, hints say `^j`, the welcome
+card shows the 16-column mark, replies stream as plain text and settle into markdown when the
+segment ends, and the approval dialog is full width with stacked buttons.
+
+```text
+ τ tau · home                                  en
+ › Salon lambası açık mı? Açıksa kapat.
+ ○ set_light(room="salon", on=false)
+   ⎿  tier 2 · running
+ ✻ Running set_light…
+ ❯
+ esc cancel · ^j newline                     busy
+```
+
+`-short` (< 20 rows): no hint row, the welcome mark is hidden, the composer grows to two rows.
+
+## Vocabulary
+
+Every glyph is one cell wide and none is an emoji-presentation code point, so phone terminals
+draw them at the right width: `›` you · `τ` tau · `●` finished tool call · `○` running or waiting
+for approval · `⎿` result line · `✻` busy verb / reasoning · `✓ ◆ ✗` turn footer (finished /
+limit, cancelled, interrupted / error) · `◆` needs you · `▸` notice · `❯` prompt.
+
+State colours (deliberate; no green and no red in the palette, shapes double the colours):
+**ok / success = Flare**, **error = Signal**, **rejected = Ember**, **running / pending = Core at
+55 %**, **attention = Flare**, notice = Ember. Rich renderables (the events pane) cannot take a TCSS
+alpha, so they use the literal blends `theme.TEXT_MUTED` (Core over Void at 60 %, the live clock and
+the running dot) and `theme.TEXT_DISABLED` (38 %, replayed clocks). The header `τ` breathes while the welcome card is
+on screen, runs the comet while a turn is busy and is static Ember otherwise; nothing else in
+the UI moves. The composer border is Ember, Signal while busy and Flare while an approval waits.
+
+## Keys and commands
+
+| Key | Effect |
+|---|---|
+| Enter | send (or accept the highlighted menu row); while tau answers the text stays and a toast says so |
+| ctrl+j | newline (shift+enter too where the terminal delivers it) |
+| Esc | close the menu · cancel the running turn · leave the events view · scroll back to the bottom |
+| ctrl+e / F4 | events: toggle the column (≥ 100 cols) or the view (< 100 cols) |
+| ctrl+r / F2 | session picker (Enter resumes, `n` new, Esc closes) |
+| ctrl+n | new session |
+| ctrl+t / F3 | `/tools` |
+| ctrl+o / F6 | expand or collapse the cards of the last turn: the arguments as JSON and the full result (a click toggles any card) |
+| PageUp / PageDown, F7 / F8 | scroll the transcript; PageUp at the top of a folded history loads 20 older turns |
+| F9 | back to the bottom |
+| ↑ / ↓ | recall sent prompts (single-line composer); navigate the menu while it is open |
+| `?` or F1 | help (only in an empty composer; `?x` is sent as a message) |
+| ctrl+q | quit (ctrl+c copies a selection in the composer; without one it only says how to quit) |
+
+Typing `/` into an empty composer opens a fuzzy menu of the slash commands (`↑↓` pick, Tab
+complete, Enter run, Esc close). An exact name ranks first, and a command typed in full runs as
+typed even when the menu has not caught up with a burst of keys (a paste, mosh), so `/session`
+never runs `/sessions`. The commands are the shared spec of `tau_core.commands`, with
+the same wording as `tau chat`:
+
+| command | effect |
+|---|---|
+| `/help`, `/tools`, `/sessions`, `/session`, `/lang en\|tr` | as in `tau chat` |
+| `/resume [n\|id]`, `/new` | switch sessions (see below) |
+| `/compact [focus]` | summarize this session with its own model and continue in a new session seeded with the summary; the old session is kept |
+| `/clear` | empty the transcript (turns, welcome card, info cards, the fold); the session and the agent go on, `/resume` or `--resume` show the history again |
+| `/status` | an info card: profile, session, model, context, tools, language, versions, hub |
+| `/model [role]` | list the roles of `tau.toml`, or switch this session to one; the header follows |
+| `/quit` (alias `/exit`) | leave |
+
+The Turkish aliases (`/devam`, `/çık`, `/özet`, `/temizle`, `/durum`, `/rol`, …) keep working
+but are never listed; the menu shows the twelve canonical names and every row is on screen at
+80x24 (in the `-short` band it scrolls). `/new`, `/resume`, `/compact`, `/clear` and
+`/model <role>` wait for the current turn (a toast says so); `/status` and `/model` without an
+argument run any time.
+
+## Approvals
+
+`TuiApprover` (`name = "tui"`) is the channel's `Approver`. A tier-2 call opens `ApprovalScreen`:
+tool, effect, the arguments as pretty JSON and the buttons **Approve** / **Reject**.
+
+- `y` or `e` approves, `n`, `h` or Esc rejects; focus starts on **Reject**, so Enter rejects, and
+  Tab only moves between the two buttons (PageUp/PageDown scroll the arguments). The keys work in
+  both languages whatever the UI setting.
+- `y`/`e` and **Approve** only work 0.5 s after the dialog opens (the hint reads `(arming…)`
+  meanwhile), so keys typed for the chat cannot approve by accident.
+- Anything other than an explicit approval rejects: a dialog closed another way, an approver
+  with no running app, or a cancelled wait (the dialog is taken down so it cannot approve later).
+- Rejecting does not cancel the turn: the model reads the refusal and answers.
+
+The dialog is translucent: the chat stays visible behind it. Behind it the tool card reads
+`○ set_light(…)` + `⎿ ◆ waiting for your approval`, the composer and the header `τ` turn Flare
+and the hint bar says what to press. Nothing in this package approves on its own.
+
+## Sessions and events
+
+`/sessions` lists the ten most recent earlier sessions with messages (numbered for `/resume n`,
+same order as `tau chat`); `/resume` alone resumes the most recent one. Resuming rebuilds the
+agent on the stored session (the previous one is closed), renders the history from the stored
+messages (user rows, markdown replies, tool cards with the recorded duration, approval and
+result), replays the stored agent events into the events pane before live ones, and keeps the
+current agent when the rebuild fails. The last 40 turns stay live; older ones fold into one
+line and PageUp at the top pages them in. One `EventBus` serves the app for its lifetime; events
+stamped with another session id are ignored.
+
+`/compact [focus]` asks the agent's own model for a continuation summary, opens a new session
+whose history starts with that summary, links the two sessions in their metadata
+(`compacted_from` / `compacted_to`) and keeps the old one untouched; the transcript is reset
+like `/new`, then shows the summary as an info card and the notice `Compacted N messages into a
+summary. New session <id>; the previous session <old id> is kept.`, the header shows the new id
+and the events pane starts empty. The summary is written in a worker, so the app stays
+responsive: the chrome is busy (`✻ Summarizing…`, `esc cancel` in the hint bar), read-only
+commands such as `/status` still answer, turns and session switches are refused, and Esc
+cancels the summarizer (`Compaction cancelled; the session continues.`). A failure (nothing to
+summarize, a model error, missing credentials) is a notice and the current session goes on.
+The details are in tau-core's README under "Compaction".
+
+`/model fast` rebuilds the agent on the same session with that role (the transcript stays,
+the header and the welcome card follow) and remembers the role in the session's metadata, so
+`/resume` and `tau tui --resume` come back on it; `build_app(role=...)` pins a role for the
+whole run instead. An unknown role, missing credentials or an unavailable provider leave the
+current agent working and say why.
+
+## Knobs
+
+| Setting | Effect |
+|---|---|
+| `TAU_TUI_ASCII=1` | ASCII vocabulary (`> t * o L * + x ! - >`), `ascii` box borders on every screen (the screens carry an `-ascii` class that `theme.ASCII_CSS` keys on), an Ember-only mark |
+| `TAU_TUI_PLAIN_STREAM=1` | stream every reply as plain text and parse the markdown once per segment |
+| `TEXTUAL_ANIMATIONS=none` | no header motion at all (also the default under `motion=False`) |
+| `TEXTUAL_COLOR_SYSTEM` / `--ansi` | the `tau-ansi` theme for 16-colour terminals |
+
+Live markdown streaming needs ≥ 60 cols; two consecutive slow appends (a long open code fence)
+switch the segment to plain text until it ends. Replies are coalesced to at most one update every
+80 ms.
+
+## Logs
+
+While the interface runs the terminal belongs to Textual: details go to
+`<TAU_DATA_DIR>/logs/tau.log` (for example `~/.local/share/tau/logs/tau.log`), the stderr
+handler of the `tau` command is detached for the duration, and the chat shows a short notice
+instead of a traceback.
+
+## Python API
+
+```python
+from tau_tui import TauApp, build_app, resolve_resume, SessionNotFound
+from tau_tui import TuiApprover, ApprovalScreen, Transcript, EventLog, rasterise
+
+app = build_app(config, session_store=store, session_id=None)  # builds the agent (channel "tui")
+app.run()
+```
+
+`build_app` creates one `EventBus` and one `TuiApprover`, builds the first agent with
+`tau_core.build_agent(..., channel="tui")` and gives `TauApp` a factory
+`agent_factory(session_id, *, role=None, seed_messages=None)` that builds every later agent
+(`/new`, `/resume`, `/compact`, `/model`) on the same bus, store and approver. `role=None`
+means `brain`, or the role a resumed `session_id` remembers from `/model`; an explicit `role`
+is pinned for the run. Tests pass `model=FakeModel([...])`, `tools=[...]`, a fixed `clock`,
+`tz=UTC`, `motion=False` and `show_durations=False`.
+`resolve_resume(store, resume, language=...)` turns `--resume [ID]` into a session id and an
+optional notice (`SessionNotFound` for an unknown id). `rasterise(cols)` is the τ mark as
+half-block cells (`docs/brand/README.md`, "Terminal").
+
+## Development
+
+```sh
+uv run pytest packages/tau-tui -q                      # pilot + snapshot tests, offline
+uv run pytest packages/tau-tui --snapshot-update       # after an intended visual change
+```
+
+Snapshots live under `tests/__snapshots__/test_snapshots/` as `.raw` files: pytest-textual-snapshot
+1.0 with syrupy 6 writes SVG under that extension, and the extension is pinned in
+`test_snapshots.py` (exactly one file per snapshot test, no glob). There are twelve: welcome at
+80x24, 50x24 and in Turkish, chat (a markdown list, a one-line fence and a rejected tier-2 card),
+busy, approval, menu (all twelve rows) and picker at 80x24, wide 100x30 (busy chrome), ultra
+160x45 (a fence and the last turn's cards expanded), the events view at 50x24 and short 80x18. Every snapshot uses the fixed session id
+`20260929-120000-abcd` (checked in every file), a fixed clock, UTC event times, no motion and no
+durations, and is taken after the streams stopped; review a regenerated file before committing it
+(it must never contain a local path, which the test also checks). The pilot tests read the widgets
+through text oracles (`Transcript.text`, `EventLog.text`, `HintBar.text`, `HeaderBar.text`,
+`ToolCard.text`) so behaviour changes do not churn the snapshots. The mark fixtures under
+`tests/fixtures/` are the text previews of `rasterise(24)` and `rasterise(16)`; regenerate them
+together with the pinned SHA-256 in `test_brand.py` when the geometry in `docs/brand/render.py`
+changes.
+
+License: MIT.

tau_tui-0.2.0/README.md

@@ -0,0 +1,247 @@
+# tau-tui
+
+The [Textual](https://textual.textualize.io/) terminal interface for tau: replies stream in as
+markdown, tool calls are cards with their tier, approval and result, agent events show in a live
+pane, tier-2 calls ask in a modal dialog, and the brand's τ mark opens every new session. One row
+of chrome at the top, at most four at the bottom, so 80x24 over mosh on a phone stays usable.
+
+It is its own distribution (`tau-tui`, import `tau_tui`), uses only the public API of `tau-core`
+and plugs into the `tau` command through the `tau.commands` entry point (`tui`):
+
+```sh
+pip install tau-tui          # or, in this repo: uv sync --all-packages --group dev
+tau tui                      # new session
+tau tui --resume             # continue the most recent earlier session
+tau tui --resume ID          # continue a given session
+tau --home /path/to/tau --lang tr tui --profile travel
+```
+
+Configuration comes from `tau.toml` and `.env` like every other channel (`TAU_HOME`,
+`TAU_DATA_DIR`, `TAU_PROFILE`, `TAU_LANG`). Missing credentials, a broken config or an unknown
+session end the command with a plain English message and exit code 2 before the interface opens.
+The chrome (hints, labels, notices, the approval dialog) follows `[ui] language` (`en` or `tr`);
+`/lang` switches it for one run.
+
+## Layout
+
+Four bands by width (`-phone` < 60 cols, `-narrow` 60–99, `-wide` 100–139, `-ultra` ≥ 140) and
+three by height (`-short` < 20 rows, `-mid`, `-tall` ≥ 30). The header is one row, the composer a
+rounded box of one to five text rows, the hint bar one row.
+
+80x24 (`-narrow`), idle after a two-tool turn:
+
+```text
+ τ tau  home · 20260929-120000-abcd                                  brain · en
+ › Salon lambası açık mı? Açıksa kapat.
+ ● get_light_state(room="salon")                                  tier 0 · 38ms
+   ⎿  {"on": true, "brightness": 80}
+ ● set_light(room="salon", on=false)                  tier 2 · approved · 412ms
+   ⎿  Light turned off
+ τ Salon lambası kapatıldı.
+   • Önceki durum: açık, %80 parlaklık
+ ✓ Worked for 4s · 2 tool calls · ctrl+o expand
+╭──────────────────────────────────────────────────────────────────────────────╮
+│ ❯ Type a message…                                                            │
+╰──────────────────────────────────────────────────────────────────────────────╯
+ ? shortcuts · / commands · ctrl+j newline                          ctrl+q quit
+```
+
+100x30 (`-wide`): the events pane docks on the right (34 cols; 40 at `-ultra`), `ctrl+e` hides
+it. 160x45 (`-ultra`): a read-only session sidebar (28 cols) on the left; clicking a row resumes.
+
+```text
+ τ tau  home · 20260929-120000-abcd                          brain · 7 tools · en
+ › Salon lambası açık mı? Açıksa kapat.          │ Events · 5
+ ● get_light_state(room="salon")   tier 0 · 38ms │ 12:00:01 ● get_light_state
+   ⎿  {"on": true, "brightness": 80}             │          tier 0 · ok · 38ms
+ τ Salon lambası kapatıldı.                      │ 12:00:02 ◆ approval set_light
+                                                 │          tier 2 → approved (tui)
+```
+
+80x30 (`-narrow -tall`): an 8-row events strip under the transcript. Below 100 cols `ctrl+e` /
+F4 swaps the transcript for the events log in the same body; the composer stays live and Esc
+returns to the chat.
+
+50x24 (`-phone`, Termius over mosh): the header drops the session id (`/session` shows it),
+tool badges move to the result line, the composer has no border, hints say `^j`, the welcome
+card shows the 16-column mark, replies stream as plain text and settle into markdown when the
+segment ends, and the approval dialog is full width with stacked buttons.
+
+```text
+ τ tau · home                                  en
+ › Salon lambası açık mı? Açıksa kapat.
+ ○ set_light(room="salon", on=false)
+   ⎿  tier 2 · running
+ ✻ Running set_light…
+ ❯
+ esc cancel · ^j newline                     busy
+```
+
+`-short` (< 20 rows): no hint row, the welcome mark is hidden, the composer grows to two rows.
+
+## Vocabulary
+
+Every glyph is one cell wide and none is an emoji-presentation code point, so phone terminals
+draw them at the right width: `›` you · `τ` tau · `●` finished tool call · `○` running or waiting
+for approval · `⎿` result line · `✻` busy verb / reasoning · `✓ ◆ ✗` turn footer (finished /
+limit, cancelled, interrupted / error) · `◆` needs you · `▸` notice · `❯` prompt.
+
+State colours (deliberate; no green and no red in the palette, shapes double the colours):
+**ok / success = Flare**, **error = Signal**, **rejected = Ember**, **running / pending = Core at
+55 %**, **attention = Flare**, notice = Ember. Rich renderables (the events pane) cannot take a TCSS
+alpha, so they use the literal blends `theme.TEXT_MUTED` (Core over Void at 60 %, the live clock and
+the running dot) and `theme.TEXT_DISABLED` (38 %, replayed clocks). The header `τ` breathes while the welcome card is
+on screen, runs the comet while a turn is busy and is static Ember otherwise; nothing else in
+the UI moves. The composer border is Ember, Signal while busy and Flare while an approval waits.
+
+## Keys and commands
+
+| Key | Effect |
+|---|---|
+| Enter | send (or accept the highlighted menu row); while tau answers the text stays and a toast says so |
+| ctrl+j | newline (shift+enter too where the terminal delivers it) |
+| Esc | close the menu · cancel the running turn · leave the events view · scroll back to the bottom |
+| ctrl+e / F4 | events: toggle the column (≥ 100 cols) or the view (< 100 cols) |
+| ctrl+r / F2 | session picker (Enter resumes, `n` new, Esc closes) |
+| ctrl+n | new session |
+| ctrl+t / F3 | `/tools` |
+| ctrl+o / F6 | expand or collapse the cards of the last turn: the arguments as JSON and the full result (a click toggles any card) |
+| PageUp / PageDown, F7 / F8 | scroll the transcript; PageUp at the top of a folded history loads 20 older turns |
+| F9 | back to the bottom |
+| ↑ / ↓ | recall sent prompts (single-line composer); navigate the menu while it is open |
+| `?` or F1 | help (only in an empty composer; `?x` is sent as a message) |
+| ctrl+q | quit (ctrl+c copies a selection in the composer; without one it only says how to quit) |
+
+Typing `/` into an empty composer opens a fuzzy menu of the slash commands (`↑↓` pick, Tab
+complete, Enter run, Esc close). An exact name ranks first, and a command typed in full runs as
+typed even when the menu has not caught up with a burst of keys (a paste, mosh), so `/session`
+never runs `/sessions`. The commands are the shared spec of `tau_core.commands`, with
+the same wording as `tau chat`:
+
+| command | effect |
+|---|---|
+| `/help`, `/tools`, `/sessions`, `/session`, `/lang en\|tr` | as in `tau chat` |
+| `/resume [n\|id]`, `/new` | switch sessions (see below) |
+| `/compact [focus]` | summarize this session with its own model and continue in a new session seeded with the summary; the old session is kept |
+| `/clear` | empty the transcript (turns, welcome card, info cards, the fold); the session and the agent go on, `/resume` or `--resume` show the history again |
+| `/status` | an info card: profile, session, model, context, tools, language, versions, hub |
+| `/model [role]` | list the roles of `tau.toml`, or switch this session to one; the header follows |
+| `/quit` (alias `/exit`) | leave |
+
+The Turkish aliases (`/devam`, `/çık`, `/özet`, `/temizle`, `/durum`, `/rol`, …) keep working
+but are never listed; the menu shows the twelve canonical names and every row is on screen at
+80x24 (in the `-short` band it scrolls). `/new`, `/resume`, `/compact`, `/clear` and
+`/model <role>` wait for the current turn (a toast says so); `/status` and `/model` without an
+argument run any time.
+
+## Approvals
+
+`TuiApprover` (`name = "tui"`) is the channel's `Approver`. A tier-2 call opens `ApprovalScreen`:
+tool, effect, the arguments as pretty JSON and the buttons **Approve** / **Reject**.
+
+- `y` or `e` approves, `n`, `h` or Esc rejects; focus starts on **Reject**, so Enter rejects, and
+  Tab only moves between the two buttons (PageUp/PageDown scroll the arguments). The keys work in
+  both languages whatever the UI setting.
+- `y`/`e` and **Approve** only work 0.5 s after the dialog opens (the hint reads `(arming…)`
+  meanwhile), so keys typed for the chat cannot approve by accident.
+- Anything other than an explicit approval rejects: a dialog closed another way, an approver
+  with no running app, or a cancelled wait (the dialog is taken down so it cannot approve later).
+- Rejecting does not cancel the turn: the model reads the refusal and answers.
+
+The dialog is translucent: the chat stays visible behind it. Behind it the tool card reads
+`○ set_light(…)` + `⎿ ◆ waiting for your approval`, the composer and the header `τ` turn Flare
+and the hint bar says what to press. Nothing in this package approves on its own.
+
+## Sessions and events
+
+`/sessions` lists the ten most recent earlier sessions with messages (numbered for `/resume n`,
+same order as `tau chat`); `/resume` alone resumes the most recent one. Resuming rebuilds the
+agent on the stored session (the previous one is closed), renders the history from the stored
+messages (user rows, markdown replies, tool cards with the recorded duration, approval and
+result), replays the stored agent events into the events pane before live ones, and keeps the
+current agent when the rebuild fails. The last 40 turns stay live; older ones fold into one
+line and PageUp at the top pages them in. One `EventBus` serves the app for its lifetime; events
+stamped with another session id are ignored.
+
+`/compact [focus]` asks the agent's own model for a continuation summary, opens a new session
+whose history starts with that summary, links the two sessions in their metadata
+(`compacted_from` / `compacted_to`) and keeps the old one untouched; the transcript is reset
+like `/new`, then shows the summary as an info card and the notice `Compacted N messages into a
+summary. New session <id>; the previous session <old id> is kept.`, the header shows the new id
+and the events pane starts empty. The summary is written in a worker, so the app stays
+responsive: the chrome is busy (`✻ Summarizing…`, `esc cancel` in the hint bar), read-only
+commands such as `/status` still answer, turns and session switches are refused, and Esc
+cancels the summarizer (`Compaction cancelled; the session continues.`). A failure (nothing to
+summarize, a model error, missing credentials) is a notice and the current session goes on.
+The details are in tau-core's README under "Compaction".
+
+`/model fast` rebuilds the agent on the same session with that role (the transcript stays,
+the header and the welcome card follow) and remembers the role in the session's metadata, so
+`/resume` and `tau tui --resume` come back on it; `build_app(role=...)` pins a role for the
+whole run instead. An unknown role, missing credentials or an unavailable provider leave the
+current agent working and say why.
+
+## Knobs
+
+| Setting | Effect |
+|---|---|
+| `TAU_TUI_ASCII=1` | ASCII vocabulary (`> t * o L * + x ! - >`), `ascii` box borders on every screen (the screens carry an `-ascii` class that `theme.ASCII_CSS` keys on), an Ember-only mark |
+| `TAU_TUI_PLAIN_STREAM=1` | stream every reply as plain text and parse the markdown once per segment |
+| `TEXTUAL_ANIMATIONS=none` | no header motion at all (also the default under `motion=False`) |
+| `TEXTUAL_COLOR_SYSTEM` / `--ansi` | the `tau-ansi` theme for 16-colour terminals |
+
+Live markdown streaming needs ≥ 60 cols; two consecutive slow appends (a long open code fence)
+switch the segment to plain text until it ends. Replies are coalesced to at most one update every
+80 ms.
+
+## Logs
+
+While the interface runs the terminal belongs to Textual: details go to
+`<TAU_DATA_DIR>/logs/tau.log` (for example `~/.local/share/tau/logs/tau.log`), the stderr
+handler of the `tau` command is detached for the duration, and the chat shows a short notice
+instead of a traceback.
+
+## Python API
+
+```python
+from tau_tui import TauApp, build_app, resolve_resume, SessionNotFound
+from tau_tui import TuiApprover, ApprovalScreen, Transcript, EventLog, rasterise
+
+app = build_app(config, session_store=store, session_id=None)  # builds the agent (channel "tui")
+app.run()
+```
+
+`build_app` creates one `EventBus` and one `TuiApprover`, builds the first agent with
+`tau_core.build_agent(..., channel="tui")` and gives `TauApp` a factory
+`agent_factory(session_id, *, role=None, seed_messages=None)` that builds every later agent
+(`/new`, `/resume`, `/compact`, `/model`) on the same bus, store and approver. `role=None`
+means `brain`, or the role a resumed `session_id` remembers from `/model`; an explicit `role`
+is pinned for the run. Tests pass `model=FakeModel([...])`, `tools=[...]`, a fixed `clock`,
+`tz=UTC`, `motion=False` and `show_durations=False`.
+`resolve_resume(store, resume, language=...)` turns `--resume [ID]` into a session id and an
+optional notice (`SessionNotFound` for an unknown id). `rasterise(cols)` is the τ mark as
+half-block cells (`docs/brand/README.md`, "Terminal").
+
+## Development
+
+```sh
+uv run pytest packages/tau-tui -q                      # pilot + snapshot tests, offline
+uv run pytest packages/tau-tui --snapshot-update       # after an intended visual change
+```
+
+Snapshots live under `tests/__snapshots__/test_snapshots/` as `.raw` files: pytest-textual-snapshot
+1.0 with syrupy 6 writes SVG under that extension, and the extension is pinned in
+`test_snapshots.py` (exactly one file per snapshot test, no glob). There are twelve: welcome at
+80x24, 50x24 and in Turkish, chat (a markdown list, a one-line fence and a rejected tier-2 card),
+busy, approval, menu (all twelve rows) and picker at 80x24, wide 100x30 (busy chrome), ultra
+160x45 (a fence and the last turn's cards expanded), the events view at 50x24 and short 80x18. Every snapshot uses the fixed session id
+`20260929-120000-abcd` (checked in every file), a fixed clock, UTC event times, no motion and no
+durations, and is taken after the streams stopped; review a regenerated file before committing it
+(it must never contain a local path, which the test also checks). The pilot tests read the widgets
+through text oracles (`Transcript.text`, `EventLog.text`, `HintBar.text`, `HeaderBar.text`,
+`ToolCard.text`) so behaviour changes do not churn the snapshots. The mark fixtures under
+`tests/fixtures/` are the text previews of `rasterise(24)` and `rasterise(16)`; regenerate them
+together with the pinned SHA-256 in `test_brand.py` when the geometry in `docs/brand/render.py`
+changes.
+
+License: MIT.

tau_tui-0.2.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "tau-tui"
+version = "0.2.0"
+description = "Textual terminal UI for tau: streamed markdown replies, tool cards, live events and in-TUI approvals."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+dependencies = ["click>=8.1", "rich>=13", "tau-core>=0.1.0", "textual>=8.2,<9"]
+keywords = ["tau", "agent", "assistant", "tui", "textual", "terminal", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Home Automation",
+]
+
+[project.urls]
+Homepage = "https://github.com/fport/tau"
+Documentation = "https://docs.tau.getporti.com"
+Issues = "https://github.com/fport/tau/issues"
+Changelog = "https://github.com/fport/tau/releases"
+
+[project.entry-points."tau.commands"]
+tui = "tau_tui.cli:tui"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tau_tui"]

tau_tui-0.2.0/src/tau_tui/__init__.py

@@ -0,0 +1,35 @@
+"""tau-tui: the Textual terminal interface for tau.
+
+Public API::
+
+    TauApp, build_app, resolve_resume, SessionNotFound
+    TuiApprover, ApprovalScreen
+    Transcript, EventLog, rasterise
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+import tau_tui.strings  # noqa: F401  (registers the tui.* message keys)
+from tau_tui.app import SessionNotFound, TauApp, build_app, resolve_resume
+from tau_tui.approval import ApprovalScreen, TuiApprover
+from tau_tui.brand import rasterise
+from tau_tui.events import EventLog
+from tau_tui.transcript import Transcript
+
+try:
+    __version__ = version("tau-tui")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "ApprovalScreen",
+    "EventLog",
+    "SessionNotFound",
+    "TauApp",
+    "Transcript",
+    "TuiApprover",
+    "__version__",
+    "build_app",
+    "rasterise",
+    "resolve_resume",
+]