Skip to content

Document AGENTD_WEBUI_PORT + print webui URL in paths#327

Merged
edwin-zvs merged 1 commit into
mainfrom
docs-webui-port-headless
Jun 2, 2026
Merged

Document AGENTD_WEBUI_PORT + print webui URL in paths#327
edwin-zvs merged 1 commit into
mainfrom
docs-webui-port-headless

Conversation

@edwin-zvs

Copy link
Copy Markdown
Contributor

Closes #318.

What

Two discoverability gaps from an isolated dogfood run:

  1. AGENTD_WEBUI_PORT was undocumented and the resolved localhost web-UI URL only appeared in the daemon log.

    • Documented the port (default 5746, override AGENTD_WEBUI_PORT) and the resolved URL in docs/configuration.md.
    • agent paths and agentd paths now print a webui: line, e.g. webui: http://127.0.0.1:5746/.
    • The port/URL resolution moved into a shared agentd_protocol::paths::local_webui_port() / local_webui_url() helper so the daemon and CLI can't drift (the daemon's inline literal is gone).
  2. The "prompt ⇒ headless" coupling was undocumented. While documenting it I verified the actual mechanism against the code and an isolated daemon, and it's slightly different from the issue's framing:

    • The mode is decided by --mode if given, otherwise by whether the creating client supplied a PTY size. agent new never supplies one, so every CLI session is headless regardless of the prompt (agent new shell "" and agent new shell "echo hi" both resolve to mode=headless; only --mode interactive flips it).
    • The prompt is orthogonal to the mode — it only decides what the harness runs on start (e.g. shell empty → $SHELL -il interactive program; non-empty → $SHELL -lc "<prompt>" one-shot).
    • docs/harnesses.md now states these rules precisely and how --mode interacts.

Verification

Built the workspace (debug) and ran an isolated daemon with AGENTD_WEBUI_PORT=5799:

$ agent paths
...
webui:   http://127.0.0.1:5799/

shell empty-prompt        mode=headless
shell with-prompt         mode=headless
shell --mode interactive  mode=interactive

Daemon log confirmed the override is honored end-to-end (local webui ready ... url=http://127.0.0.1:5799/).

Binaries

Docs-only behavior except for the webui: line in paths, which lives in agent (CLI) and agentd (daemon). Both built clean from the worktree.

Closes #318.

- Resolve the localhost web-UI port via a shared
  `agentd_protocol::paths::local_webui_port()` / `local_webui_url()` helper
  (default 5746, `AGENTD_WEBUI_PORT` override) instead of inlining the literal
  in the daemon.
- Print a `webui:` line in both `agent paths` and `agentd paths` so the URL no
  longer only appears in the daemon log.
- Document the web-UI port (and the resolved URL) in docs/configuration.md.
- Clarify the session-mode rules in docs/harnesses.md: mode is chosen by
  `--mode`, else by whether the client supplied a PTY size — so every CLI
  `agent new` session is headless regardless of the prompt; the prompt only
  decides what the session runs on start.
@edwin-zvs
edwin-zvs merged commit 8effd43 into main Jun 2, 2026
1 check passed
@edwin-zvs
edwin-zvs deleted the docs-webui-port-headless branch June 2, 2026 02:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: document AGENTD_WEBUI_PORT and the prompt-implies-headless coupling

1 participant