Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
ccb1469
qt sidebar and tabs: an observation redraws only what changed
trissim Nov 18, 2026
415b0dc
burst stack: a burst ends when the reader leaves the end, not when th…
trissim Nov 18, 2026
fdeb5b5
qt history: a rising row fades as one picture, not its rich text draw…
trissim Nov 18, 2026
cc9ba18
qt pin: a burst's stacked headers keep their layout as the stack shifts
trissim Nov 18, 2026
263874d
history rows: an arrival is an insert, not a reset; the composer read…
trissim Nov 18, 2026
a318ef9
qt tabs: marking the selected tab presents the panes on every paint a…
trissim Nov 18, 2026
e909e4e
toad serve: add --public-url for tailnet-served browser workspaces
claude Nov 18, 2026
735f4c9
fix: burst stack must not cover a visible header
claude Nov 18, 2026
e3c914f
history rows: a status change and a link change tell the kept row hei…
trissim Nov 18, 2026
6d0d42e
toad + qt: --open NAME opens a thread or #channel at launch; search l…
trissim Nov 18, 2026
f461d75
history: a burst leaves the top row's own message out of its stack by…
trissim Nov 18, 2026
06f0a92
qt_drive: a drive always keeps its settings under OUTDIR
trissim Nov 18, 2026
1ab4a39
Merge remote-tracking branch 'origin/arrival-insert' into qt-ui-batch-6
trissim Nov 18, 2026
49ffa45
Merge remote-tracking branch 'origin/open-thread-launch' into qt-ui-b…
trissim Nov 18, 2026
a60cd66
toad serve-tailnet: port the owner-only tailnet serving from feat/toa…
claude Nov 18, 2026
a1b6924
Merge branch 'claude/toad-serve-tailnet-port-dw4byw' of https://githu…
claude Nov 18, 2026
15153b8
fix: burst stack covers visible header as the overlay's last line
claude Nov 18, 2026
388b69f
history: a burst's stack leaves the top row's message out by identity…
trissim Nov 18, 2026
fcd6a4f
serve-tailnet: use TailnetSelf from agent-comms instead of hand-parsi…
claude Nov 18, 2026
828294f
history: a header drawn at the top edge is the stack's last line; the…
trissim Nov 18, 2026
ca1b2f1
Merge remote-tracking branch 'origin/claude/toad-serve-tailnet-port-d…
trissim Nov 18, 2026
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
34 changes: 23 additions & 11 deletions docs/browser-serving.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,26 +37,38 @@ each local port. Missing credentials, mismatched or null Origin, a DNS-rebinding
Host and an external bind fail closed. The server API is pinned to
`textual-serve==1.1.3`.

## Tailnet browser serving

`toad serve-tailnet PORT` serves to this machine's tailnet owner only. It listens
on an owner-only unix socket (`0600` in the user's runtime directory) and checks
the `Tailscale-User-Login` header that `tailscale serve` attaches to each request.
The owner login and DNS name are read from `tailscale status --json --self` at
startup.

```shell
toad serve-tailnet 8443 acp agent-comms-acp
```

No TCP listener exists: the only peer that reaches the routes is the tailscale
proxy. The unix socket is claimed with a lockfile so a second instance fails
rather than racing the first.

## Desktop tailnet service

The desktop user service is `tools/systemd/toad-serve.service`. It starts the
existing `textual-serve` package using the Python under
`~/.local/share/agent-comms/current`, not a copied runtime. Each browser tab runs
`/home/ts/bin/toad-comms`, which selects the installed Toad through its normal
launcher. Restart the service after a runtime switch to move the server process
as well as newly opened Toad children onto the new runtime.
The desktop user service is `tools/systemd/toad-serve.service`. It runs `toad
serve-tailnet` with the installed runtime's toad. Each browser tab runs `toad acp
agent-comms-acp` as its own process. Restart the service after a runtime switch.

Install the unit under `~/.config/systemd/user/toad-serve.service`, then run:

```shell
systemctl --user daemon-reload
systemctl --user enable --now toad-serve.service
tailscale serve --bg --https=8443 http://127.0.0.1:8040
tailscale serve --bg --https=8443 unix:/run/user/$(id -u)/toad-serve-8443.sock
```

Open `https://desktop.tail553874.ts.net:8443` from a tailnet device. The backend
binds only `127.0.0.1:8040`. This service uses tailnet access control rather than
the local `toad serve` cookie gate. A connected browser has full agent control;
never enable Funnel for port 8443. The connector's existing HTTPS/Funnel route
Open `https://desktop.tail553874.ts.net:8443` from a tailnet device. Only the
machine's tailnet owner is admitted. A connected browser has full agent control;
never enable Funnel for this port. The connector's existing HTTPS/Funnel route
on port 443 is separate and must remain unchanged. `tailscale funnel status`
is a read-only check, not permission to enable another public route.
4 changes: 3 additions & 1 deletion src/toad/app.py
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@
from toad.core import input_events
from toad.widgets.file_viewer import ImageViewer
from toad.launch_binding import AgentBinding
from toad.launch_opening import LaunchOpening, NoLaunchOpening
from toad.native_style import TransparentBackground
from toad.neovim_editing import HostsNeovim
from formbridge.forms.declared_fields import DeclaredField
Expand Down Expand Up @@ -136,6 +137,7 @@ def __init__(
project_dir: Checkout,
connection: CoreConnection,
agent_session_id: AcpSessionId | NoAcpSessionId = NoAcpSessionId(),
opening: LaunchOpening = NoLaunchOpening(),
) -> None:
"""Toad app.

Expand All @@ -148,7 +150,7 @@ def __init__(
self.render_processes: Renderer = TextualPreparedRenderer(self.preparation)
self.background_render_slots = asyncio.Semaphore(1)
self._background_render_tasks: set[asyncio.Task[object]] = set()
self.initialize_client(agent_binding, connection, agent_session_id)
self.initialize_client(agent_binding, connection, agent_session_id, opening)
self.clipboard_transport = Clipboard.for_platform()
self.input_attention = TerminalAttention(self)
self._mode_switch_lock = asyncio.Lock()
Expand Down
12 changes: 9 additions & 3 deletions src/toad/application_lifetime.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
from toad.version import VersionMonitor
from toad.client.tab_identity.kinds import MailboxTab
from toad.client.tab_identity import TabNotDrawnHere, TabTargetGone
from toad.launch_opening import LaunchOpening, NoLaunchOpening

if TYPE_CHECKING:
from ssl import SSLContext
Expand Down Expand Up @@ -132,10 +133,13 @@ def observe_next_start(cls, observer: Callable[[ApplicationLifetime], None]) ->
"""Install the sole one-shot observer for the next owned startup."""
ApplicationLifetime._startup_hook = ApplicationLifetime._startup_hook.install(observer)

def __init__(self, app: ClientApplication, resumed_session: AcpSessionId | NoAcpSessionId) -> None:
def __init__(self, app: ClientApplication, resumed_session: AcpSessionId | NoAcpSessionId,
opening: LaunchOpening = NoLaunchOpening()) -> None:
self.app = app
# The agent session the launch asked to resume, if it named one.
self.resumed_session = resumed_session
# The conversation the launch asked to open (`--open`), if it named one.
self.opening = opening

def begin(self) -> None:
"""Run start as its own task: it awaits drawn frames, so neither Mount
Expand All @@ -146,6 +150,7 @@ def begin(self) -> None:
async def start(self) -> None:
ApplicationLifetime._startup_hook = ApplicationLifetime._startup_hook.notify(self)
await self.restore_workspace()
await self.opening.open(self.app)
self.started()
self.prepare_view_settings()
self.settle_heap()
Expand Down Expand Up @@ -260,8 +265,9 @@ def set_process_title(title: str) -> None:

setproctitle.setproctitle(title)

def __init__(self, app: ToadApp, resumed_session: AcpSessionId | NoAcpSessionId) -> None:
super().__init__(app, resumed_session)
def __init__(self, app: ToadApp, resumed_session: AcpSessionId | NoAcpSessionId,
opening: LaunchOpening = NoLaunchOpening()) -> None:
super().__init__(app, resumed_session, opening)
self.quit_warning_deadline = 0.0
self.usage = UsageReports(app)
self.version = VersionMonitor()
Expand Down
53 changes: 36 additions & 17 deletions src/toad/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
from toad.app import ToadApp
from toad.application_lifetime import TerminalApplicationLifetime
from toad.client.connection import CoreConnection
from toad.client.local_connection import select_connection
from toad.client.local_connection import ClientLaunch
from toad.launch_binding import AgentAttached, AgentBinding, LaunchAgentRefused
from toad.preferences import SavedSettings
from toad.web_server import ToadWebServer
Expand Down Expand Up @@ -67,8 +67,8 @@ def parse_args(self, ctx, args):
if "--version" in args or "-v" in args:
return super().parse_args(ctx, args)

# The launch's connection; apps receive this captured value.
ctx.obj = select_connection(args)
# The launch's connection and the conversation it opens; apps receive this captured value.
ctx.obj = ClientLaunch.startup(args)
# Check if first arg is a known subcommand
if not args or args[0] not in self.commands:
# If not a subcommand, prepend the default command name
Expand Down Expand Up @@ -119,18 +119,20 @@ def main(ctx, version):
@click.argument("project_dir", metavar="PATH", required=True)
@click.option("-a", "--agent", metavar="AGENT", default="")
@click.pass_obj
def run(connection: CoreConnection, project_dir: str, agent: str = "1"):
"""Run an installed agent."""
def run(launch: ClientLaunch, project_dir: str, agent: str = "1"):
"""Run an installed agent. `--open NAME` (a thread, or #channel) opens that conversation
once the saved tabs are back."""

project = FieldCodec.decode(Checkout, project_dir).resolved(strict=True)



binding = asyncio.run(get_agent_binding(connection, agent))
binding = asyncio.run(get_agent_binding(launch.connection, agent))
app = ToadApp(
agent_binding=binding,
project_dir=project,
connection=connection,
connection=launch.connection,
opening=launch.opening,
)
run_terminal(app)

Expand All @@ -157,7 +159,7 @@ def run(connection: CoreConnection, project_dir: str, agent: str = "1"):
@click.option("-d", "--project-dir", "project_option", metavar="PATH", default=None)
@click.pass_obj
def acp(
connection: CoreConnection,
launch: ClientLaunch,
command: str,
title: str | None,
project_dir: str | None,
Expand Down Expand Up @@ -191,8 +193,9 @@ def acp(
app = ToadApp(
agent_binding=AgentAttached(agent_data),
project_dir=FieldCodec.decode(Checkout, project_dir).resolved(strict=True),
connection=connection,
connection=launch.connection,
agent_session_id=session_id,
opening=launch.opening,
)
run_terminal(app)

Expand Down Expand Up @@ -237,7 +240,7 @@ def replay(path: str) -> None:
"serve",
context_settings={"allow_interspersed_args": False},
)
@click.option("-p", "--port", metavar="PORT", default=8000, type=int)
@click.option("-p", "--port", metavar="PORT", default=8000, type=click.IntRange(1, 65535))
@click.option(
"-H",
"--host",
Expand All @@ -247,26 +250,42 @@ def replay(path: str) -> None:
)
@click.argument("toad_args", metavar="[TOAD ARGS]...", nargs=-1, type=click.UNPROCESSED)
def serve(port: int, host: str, toad_args: tuple[str, ...]) -> None:
"""Serve a Toad command line in a web browser.
"""Serve a Toad command line in a web browser on this machine.

Each browser tab runs `toad TOAD ARGS` as its own process, for example
`toad serve acp agent-comms-acp`.
"""
from toad.web_server import LocalBrowserAuthentication, LocalBrowserEndpoint

ToadWebServer.run_toad(
LocalBrowserAuthentication(LocalBrowserEndpoint(host, port)), toad_args
)


@main.command(
"serve-tailnet",
context_settings={"allow_interspersed_args": False},
)
@click.argument("https_port", metavar="PORT", type=click.IntRange(1, 65535))
@click.argument("toad_args", metavar="[TOAD ARGS]...", nargs=-1, type=click.UNPROCESSED)
def serve_tailnet(https_port: int, toad_args: tuple[str, ...]) -> None:
"""Serve a Toad command line to this machine's tailnet owner only.

Listens on an owner-only unix socket for `tailscale serve --https=PORT`, which
supplies each caller's tailnet login.
"""
from toad.web_server import TailnetBrowserAuthentication

command = shlex.join([sys.executable, "-m", "toad", *toad_args])
server = ToadWebServer(command, host=host, port=port, title="Toad")
TerminalApplicationLifetime.set_process_title("toad serve")
server.serve()
ToadWebServer.run_toad(TailnetBrowserAuthentication.from_status(https_port), toad_args)


@main.command("about")
@click.pass_obj
def show_about(connection: CoreConnection) -> None:
def show_about(launch: ClientLaunch) -> None:
"""Show about information."""


print(about.render(connection.location))
print(about.render(launch.connection.location))


if __name__ == "__main__":
Expand Down
4 changes: 3 additions & 1 deletion src/toad/client/application.py
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@
from toad.core import events as core_events
from toad.core import session_requests
from toad.launch_binding import AgentBinding
from toad.launch_opening import LaunchOpening, NoLaunchOpening
from toad.navigation_preparation import NavigationReader
from toad.session_host import NavigationHost
from toad.session_navigation import SessionNavigation
Expand Down Expand Up @@ -200,6 +201,7 @@ def initialize_client(
agent_binding: AgentBinding,
connection: CoreConnection,
agent_session_id: AcpSessionId | NoAcpSessionId = NoAcpSessionId(),
opening: LaunchOpening = NoLaunchOpening(),
) -> None:
"""The launch's client owners, built once from the native constructor.

Expand All @@ -211,7 +213,7 @@ def initialize_client(
self.events = core_events.CoreEventStream(self)
self.navigation_reader = NavigationReader()
self.agent_binding = agent_binding
self.application = self.lifetime_kind(self, agent_session_id)
self.application = self.lifetime_kind(self, agent_session_id, opening)
self.session_navigation = SessionNavigation(self)
self.thread_navigation = ThreadNavigator(self)
self.thread_actions = ThreadActions(self)
Expand Down
43 changes: 35 additions & 8 deletions src/toad/client/history_changes.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,8 @@
from toad.client.line_blocks import Divider, MutedRole

if TYPE_CHECKING:
from toad.client.fragments import FragmentKey, HistoryFragment
from agent_comms.nominal.field_codec import ToolCallId
from toad.client.fragments import EventSourceKey, FragmentKey, HistoryFragment
from toad.client.transcript_fragments import TranscriptFragment
from toad.widgets.history_anchor import HistoryWindow
from toad.widgets.transcript_history import FragmentSpan, TranscriptPageView
Expand Down Expand Up @@ -82,7 +83,8 @@ class FragmentRowUnderTop:
width: int

def pinned_header(self) -> PinnedHeader:
return PinnedHeader(self.fragment.sticky_header(self.block, self.row), self.x, self.width)
return PinnedHeader(self.fragment.sticky_header(self.block, self.row), self.x, self.width,
self.fragment.key.source)


@dataclass(frozen=True)
Expand All @@ -94,6 +96,9 @@ class PinnedHeader:
headers: tuple[Divider, ...]
x: int
width: int
source: EventSourceKey | ToolCallId | None = None
"""The message the top row draws (its fragment key's `source`), by which a burst leaves the
top row's own message out of its stack; none where no drawn fragment is on the top row."""


@dataclass(frozen=True)
Expand Down Expand Up @@ -157,18 +162,36 @@ def stack(self, window: PinsMessageHeader, pinned: PinnedHeader) -> StackedHeade
"""The earlier messages whose head is scrolled above the top row, the most recent
`shown` of them, under a count line; none for a burst of one, or once the reader is
above the burst (no head is above the top row then). The top row's own message pins
its header as before and is not stacked twice."""
its header as before and is not stacked twice.

When the top row IS a header (pinned.headers empty), the burst message at that row
becomes the overlay's last line, so the overlay covers the flow's header with its
own copy and earlier messages stack above it — never A drawn over visible B."""
if len(self.messages) < 2 or not pinned.width:
return NO_STACK
own = pinned.headers[-1:]
# The top row's own message by identity: messages from one sender to one destination in
# the same second draw equal headers, and comparing headers left such a message out.
# Nothing pinned means a header is drawn at the top edge (the top row is a message's head,
# or the gap just before it, which the layout counts with the message above): the overlay
# would cover that header, so it becomes the overlay's last line, drawn once, and no
# earlier header is drawn over it. It is the first burst message starting at or below
# the top edge.
top_line: tuple[Divider, ...] = ()
if not pinned.headers:
covered = next((message for message in self.messages
if (top := window.message_top(message.key)) is not None
and top >= window.scroll_y), None)
if covered is None:
return NO_STACK
top_line = (covered.header,)
above = [message for message in self.messages[:-1]
if message.header not in own
if message.key.source != pinned.source
and (top := window.message_top(message.key)) is not None and top < window.scroll_y]
if not above:
return NO_STACK
stacked = above[-self.shown:]
count = Divider.titled(f"{len(self.messages)} new", MutedRole)
return StackedHeaders((count, *(message.header for message in stacked)),
return StackedHeaders((count, *(message.header for message in stacked), *top_line),
(above[0].key, *(message.key for message in stacked)))


Expand Down Expand Up @@ -233,9 +256,13 @@ def repin_header(self) -> None:
"""Pin from where the reader is now. The window calls this on every scroll offset and
every committed geometry change: a reflow, a filter, replaced rows or a restored tab can
change the top row's message at an unchanged offset. Only the reader scrolls a window up:
following, gliding and placing an arrival move it down or keep it (`layout_scroll`)."""
following, gliding and placing an arrival move it down or keep it (`layout_scroll`).
The burst ends when the reader leaves the end, not when the window's offset falls: rows
above that shrink (a receipt, the queue rows closing) clamp the offset up while the reader
still follows, and ending the burst there emptied it before it could stack."""
burst = self.arrival_burst
if burst.messages and self.scroll_y < self.pinned_scroll_y and not self._restoring:
if (burst.messages and not self.follows_tail and self.scroll_y < self.pinned_scroll_y
and not self._restoring):
burst = self.arrival_burst = NO_BURST
self.pinned_scroll_y = self.scroll_y
pinned = self.top_message_header()
Expand Down
16 changes: 16 additions & 0 deletions src/toad/client/local_connection.py
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@
from agent_comms.ui_model.sidebar import SidebarModel

from toad.client.agent_processes import AgentProcesses, SpawnsAgentProcesses
from toad.launch_opening import LaunchOpening
from toad.client.db import UNSCOPED_TABS, TabScope
from toad.client.connection import (
AnsweringReads,
Expand Down Expand Up @@ -59,6 +60,21 @@ def select_connection(arguments: list[str]) -> CoreConnection:
arguments, lambda: LaunchRoot.from_path(CommsRoute.current().root)))


@dataclass(frozen=True)
class ClientLaunch:
"""What a desktop launch's own arguments select, read once for Toad's terminal launch and
Qt's desktop launch alike: the Core it opens (`select_connection`) and the conversation
it opens there (`LaunchOpening`, `--open NAME`). Each is removed from ``arguments``, so
the frontend's own parser sees only the project and its agent."""

connection: CoreConnection
opening: LaunchOpening

@classmethod
def startup(cls, arguments: list[str]) -> ClientLaunch:
return cls(select_connection(arguments), LaunchOpening.startup(arguments))


class LocalCoreConnection(LaunchRoot, CoreConnection):
"""A local connection inherits the selected root and its launch behavior."""

Expand Down
Loading
Loading