Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -1 +1,11 @@

# Exclude JavaScript from GitHub's language breakdown.
*.js -linguist-detectable
*.jsx -linguist-detectable
*.mjs -linguist-detectable
*.cjs -linguist-detectable

# Committed esbuild output: keep the minified bundle from dominating/hiding
# the real source languages.
ui/terminal_bundle/** linguist-generated -linguist-detectable
ui/terminal/package-lock.json linguist-generated -linguist-detectable
2 changes: 1 addition & 1 deletion .postal/config.toml
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ debug = false
# command='python3 ./scripts/test_tool.py'

[model]
name = "deepseek/deepseek-v4.1-flash-1017"
name = "baidu/ernie-5.5-flash-preview:free"
temperature = 1.0
context_window = 256000

Expand Down
2 changes: 0 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,6 @@ npm run preview # run the UI against a local fake backend

Commit the rebuilt `ui/terminal_bundle/postal.mjs` whenever `ui/terminal/src` changes: the Python package ships the bundle, not the TypeScript sources, so an unbuilt change never reaches users. The `TypeScript terminal` job in CI rebuilds and fails if the committed bundle is stale. `tests/test_ui_bridge.py` exercises the protocol with a real `BridgeSession`, so no API key is required.

`POSTAL_UI=textual` still selects the previous Textual interface (`ui/textual_app.py`, `ui/textual_widgets.py`). Treat it as a maintained fallback: keep it importable and keep `tests/test_textual_ui.py` passing, but new interactive work goes in `ui/terminal/`.

Postal uses a component-based UI system where each visual element is a separate, reusable component. This design makes it easier to:

- **Create new UI elements:** Add new components following the existing patterns in `ui/components/` and `ui/terminal/src/`
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ postal login # opens your browser to authorize with OpenRouter
postal # start the interactive TUI
```

Postal needs Python 3.11+ and Node.js 22+ (the interactive TUI is a bundled TypeScript program that runs on `node`; npm is not required). Set `POSTAL_UI=textual` to use the previous Textual interface instead.
Postal needs Python 3.11+ and Node.js 22+ (the interactive TUI is a bundled TypeScript program that runs on `node`; npm is not required).

## Usage

Expand Down Expand Up @@ -117,7 +117,7 @@ Full [CLI reference](docs/cli.md) | [configuration reference](docs/configuration

Commands autocomplete as you type: `/` opens the list, typing filters it, and `↑`/`↓` select. `Tab` or `Enter` completes a partial command; `Enter` submits a completed command.

The terminal opens into a single conversation column with a multiline composer. `Enter` sends, `Ctrl+J` adds a line, `Ctrl+P` opens commands, and `Ctrl+G` opens the live agent tree. Tool output and reasoning start collapsed; click a heading to expand it, or use `Ctrl+O` for the latest tool. `Esc` interrupts a turn and `Ctrl+Q` exits. See the [keyboard reference](docs/cli.md#interactive-terminal).
The terminal opens into a single conversation column with a multiline composer. `Enter` sends, `Ctrl+J` adds a line, `Ctrl+P` opens commands, and `Ctrl+G` opens the live agent tree. Tool calls show live previews, result summaries, and elapsed times, then compact successful results automatically. Repeated reads and searches form expandable groups. Click a heading or use `Ctrl+O` for the latest result, `Alt+O` for the latest group, `Alt+A` to expand all details, and `Alt+C` to collapse them. `Esc` interrupts a turn and `Ctrl+Q` exits. See the [keyboard reference](docs/cli.md#interactive-terminal).

## Sessions

Expand Down
2 changes: 1 addition & 1 deletion docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ Interactive sessions are a TypeScript Ink/React program in `ui/terminal/`. Pytho

Inside the frontend, `state.ts` is a pure reducer over the protocol messages, so streaming behaviour is testable without a terminal. `App.tsx` owns transport, focus, and menus; `components.tsx` renders the conversation, prompt bar, and overlays; `editor.ts` implements the line editor (grapheme-aware movement, wrapping, history); `mouse.tsx` translates SGR mouse reports into clicks and wheel events. `demo.ts` provides a local fake backend for UI iteration without a model.

`POSTAL_UI=textual` keeps the previous Textual interface (`ui/textual_app.py`, `ui/textual_widgets.py`, `ui/postal.tcss`) available as a fallback, and `ui/textual_app.py` remains the reference implementation for streaming and modal behaviour.
The bundled TypeScript TUI is the only interactive interface. Node.js 22 or later is required.

The single-shot CLI retains the Rich renderer below. Both interfaces use the same agent runtime, approval policy, and session storage.

Expand Down
9 changes: 6 additions & 3 deletions docs/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,6 @@ postal upgrade

Postal needs Python 3.11 or newer and Node.js 22 or newer (the interactive TUI is a bundled TypeScript program that runs on `node`). The npm dependencies are bundled into the package, so you never need to run `npm install` to use Postal. A `Dockerfile` and Compose file live in [`docker/`](../docker/) if you would rather run the agent sandboxed.

Set `POSTAL_UI=textual` to use the previous Textual interface instead of the TypeScript one, for example on a machine without Node.

When a newer release is available, Postal displays a notice when the interactive TUI starts. It never upgrades automatically; run `postal upgrade` yourself to install it.

On macOS (`darwin`), `postal upgrade` detects pipx-managed installations and runs
Expand Down Expand Up @@ -69,7 +67,7 @@ These go before the command, or on their own with the bare `postal`.

## Interactive terminal

`postal` opens a full-screen Ink interface with a centered cloud logo and prompt bar. The bar moves below the conversation after the first message. Its input grows to five visible text rows, then scrolls. Tools and reasoning are collapsed until expanded. Agent activity opens in an overlay.
`postal` opens a full-screen Ink interface with a centered cloud logo and prompt bar. The bar moves below the conversation after the first message. Its input grows to five visible text rows, then scrolls. Tools show compact previews. Reasoning shows the latest four wrapped rows while running; expand it to read the full live text. Agent activity opens in an overlay.

The prompt bar's `+` menu adds workspace text/code file references, requests web search for the next prompt, or opens slash commands. File and web chips can be removed before sending. The model picker accepts a model ID and lists models used during the session; the effort picker uses the supported reasoning levels. The arrow sends the prompt and becomes a stop button while Postal is working. Use `Tab` to reach these controls or click them. Settings changes preserve the current draft.

Expand All @@ -81,6 +79,9 @@ The prompt bar's `+` menu adds workspace text/code file references, requests web
| `/`, `Ctrl+P` | Open slash commands; type to filter, arrows to select, `Tab` or `Enter` to complete |
| `Ctrl+G` | Open or close nested agent activity |
| `Ctrl+O` | Expand or collapse the latest tool or reasoning block |
| `Alt+O` | Expand or collapse the latest group of reads or searches |
| `Alt+A` | Expand all tool results and reasoning traces |
| `Alt+C` | Collapse tool details and reasoning traces; errors remain visible |
| `Ctrl+End` | Scroll to the latest message |
| `PageUp` / `PageDown` | Scroll the conversation |
| `Esc`, `Ctrl+C` | Interrupt a running turn; close a menu; reject an open approval request |
Expand All @@ -90,6 +91,8 @@ In agent activity, arrows select an agent, `Enter` runs its slash-command choice

Scrolling up keeps your place while a response streams. Scroll back to the bottom or press `Ctrl+End` to follow new output again. Tool output and reasoning are collapsible with a click or `Ctrl+O`.

Running tools show a small lattice, a fixed two-line output preview, and an elapsed timer. Successful calls briefly settle into a checkmark, show a result summary or small edit preview, and compact after 1.6 seconds. Consecutive reads and searches form expandable groups. File paths keep their filename visible when shortened; expanding a result reveals the full arguments, output, and diff. Failed calls keep their error visible even when tool groups are collapsed.

## Examples

```bash
Expand Down
1 change: 0 additions & 1 deletion docs/technologies.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@ What Postal is built on, and what each piece is actually doing.
| **[marked](https://github.com/markedjs/marked) + [marked-terminal](https://github.com/mikaelbr/marked-terminal)** | Markdown rendering for assistant replies and tool output. |
| **[wrap-ansi](https://github.com/chalk/wrap-ansi) / [string-width](https://github.com/sindresorhus/string-width)** | Grapheme- and width-aware wrapping so wide characters and emoji do not break the layout. |
| **[Rich](https://github.com/Textualize/rich)** | Slash-command output and the streaming renderer for single-shot runs, plus the shared render components. |
| **[Textual](https://github.com/Textualize/textual)** | The fallback interface, kept available as `POSTAL_UI=textual`. |
| **[prompt-toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit)** | Persistent prompt history shared with the previous interface, and legacy terminal input helpers. |
| **[Pygments](https://pygments.org/)** | Syntax highlighting for code blocks and file previews rendered through Rich. |

Expand Down
3 changes: 1 addition & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,6 @@ dependencies = [
"prompt-toolkit>=3.0",
"pydantic>=2.13",
"rich>=15.0",
"textual>=8.2.8,<9",
"tiktoken>=0.13",
]

Expand Down Expand Up @@ -65,7 +64,7 @@ exclude = ["ui.terminal", "ui.terminal.*", "ui.terminal_bundle", "ui.terminal_bu

[tool.setuptools.package-data]
"*" = [
"*.md", "*.txt", "*.tcss", "*.toml",
"*.md", "*.txt", "*.toml",
"ui/terminal/package.json", "ui/terminal/package-lock.json",
"ui/terminal/tsconfig.json", "ui/terminal/build.mjs",
"ui/terminal/src/*.ts", "ui/terminal/src/*.tsx",
Expand Down
1 change: 0 additions & 1 deletion requirements.txt
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,6 @@ sniffio==1.3.1
socksio==1.0.0
sse-starlette==3.4.6
starlette==1.3.1
textual==8.2.8
tiktoken==0.13.0
tomli==2.4.1
tqdm==4.68.4
Expand Down
12 changes: 12 additions & 0 deletions tests/test_repl.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,18 @@ def test_missing_tty_does_not_require_node(self):
self.assertNotIn("Node.js", str(error))
which.assert_not_called()

def test_node_is_required_even_with_old_interface_setting(self):
with (
patch.dict("os.environ", {"POSTAL_UI": "textual"}),
patch("ui.repl.app.sys.stdin") as stdin,
patch("ui.repl.app.shutil.which", return_value=None) as which,
):
stdin.isatty.return_value = True
with self.assertRaisesRegex(RuntimeError, "requires Node.js 22") as raised:
asyncio.run(Repl(Config()).run())
which.assert_called_once_with("node")
self.assertNotIn("textual", str(raised.exception))


if __name__ == "__main__":
unittest.main()
Loading
Loading