widgets

ChatGPT OAuth sign-in screen, reachable via /auth -> openai_codex.

Mirrors the MCP loopback flow in mcp_auth from the user's POV: a modal shows progress, surfaces the authorize URL inline (so headless / SSH users can copy it when the browser launch fails), and dismisses once the OAuth callback completes. The OAuth primitives themselves (PKCE, callback HTTP server, token exchange, refresh, atomic file write) are delegated to langchain_openai.chatgpt_oauth via the deepagents_code.integrations.openai_codex adapter.

Security notes:

• The authorize URL displayed inline does not contain secrets — it carries only the PKCE challenge (the verifier never leaves this process).
• The success / error messages reported back via notify never include the access token, refresh token, or ID token.

Confirmation modal shown after a successful MCP login.

Restarting the LangGraph server is required for newly minted MCP tokens to take effect, but auto-restarting interrupts users who want to authenticate against several MCP servers back-to-back. This modal lets the user choose between restarting now and deferring until later.

Live panel showing subagents fanned out from within js_eval calls.

When the agent writes code that calls the top-level task() global, each dispatch runs as a subagent inside a single js_eval tool call which is invisible to the normal message stream. The QuickJS task bridge emits lifecycle events on the custom stream. This widget consumes them and renders a docked, live-updating fan-out panel.

Trust note: description/subagent_type and error strings originate from LLM-authored JavaScript executed in the sandbox, so they are untrusted. We route every rendered string through sanitize_control_chars which strips control/escape/bidi characters and only ever render via Content.styled / markup=False Static updates, so embedded Textual markup and terminal escapes cannot influence rendering or panel state.

Loading widget with animated spinner for agent activity.

Message widgets.

Confirmation modals for /update dependency-refresh flows in the TUI.

When deepagents-code itself is already on the latest release, /update can still re-resolve its dependencies to the newest versions allowed by the pinned ranges (e.g. a new langchain-openai). The already-current path dry-runs the resolution first, then asks for explicit confirmation only when dependencies can move. /update --deps skips that prompt, but asks before taking an available app update ahead of the dependency refresh for the current app version.

Interactive agent selector screen for /agents command.

Tool renderers for approval widgets - registry pattern.

Notification settings screen for /notifications command.

Autocomplete system for @ mentions and / commands.

This is a custom implementation that handles trigger-based completion for slash commands (/) and file mentions (@).

Command history manager for input persistence.

Progress modal for app self-update installs.

Dedicated modal for the update-available notification.

Shown automatically at startup when a newer version of deepagents-code is available on PyPI. Surfaces the same actions the notification center would offer for the update entry but with a focused, single-purpose presentation instead of the generic notification list.

Chat input widget for deepagents-code with autocomplete and history support.

Prompt for switching cwd when resuming threads.

Ask user widget for interactive questions during agent execution.

Interactive theme selector screen for /theme command.

TUI screens for managing stored model-provider credentials.

AuthPromptScreen accepts an API key for a single provider, persists it via auth_store, and is the sole place that deletes existing credentials (after a DeleteCredentialConfirmScreen confirmation). AuthManagerScreen lists known providers and routes the user into the prompt; it does not delete directly. Both are reachable via the /auth slash command.

Security notes:

• Inputs are rendered with password=True so the key is never echoed to the terminal.
• This module never logs the key value, never includes it in notify() payloads, and never round-trips it through Rich markup. Callers that introduce new logging here must do the same.

Approval widget for HITL - using standard Textual patterns.

Goal acceptance-criteria review widget.

Read-only MCP server and tool viewer modal.

Onboarding screens for the interactive TUI.

Interactive thread selector screen for /threads command.

Status bar widget.

Interactive reasoning effort selector for /effort.

Generic detail modal for a single pending notification.

Used by NotificationCenterScreen when the user drills into an entry whose payload does not have a dedicated modal (e.g. missing-dependency notices). Update-available notifications continue to use UpdateAvailableScreen, which adds a changelog row on top of the action list.

Dismisses with the selected ActionId, or None on Esc.

Confirmation modal offered after a restart-capable /install.

Provider and sandbox extras (and --package installs) are imported by the app-owned LangGraph server subprocess, so a /restart loads them without exiting the TUI. Rather than make the user type /restart by hand, this modal offers to run that restart immediately while leaving deferral one keypress away.

Message store for virtualized chat history.

This module provides data structures and management for message virtualization, allowing the TUI to handle large message histories efficiently by keeping only a sliding window of widgets in the DOM while storing all message data as lightweight dataclasses.

The approach is inspired by Textual's Log widget, which only keeps N lines in the DOM and recreates older ones on demand.

Notification center modal for pending actionable notices.

Surfaces a list of PendingNotification entries as single-line rows. Selecting a row drills into a dedicated detail modal (UpdateAvailableScreen for update entries, NotificationDetailScreen otherwise) stacked on top of the center. When the detail modal dismisses with any non-SUPPRESS action the center dismisses with a NotificationActionResult so the app layer can dispatch; SUPPRESS is handled in place via NotificationSuppressRequested so the remaining notifications stay reachable. When the detail cancels, the center stays open on the list.

Trust prompt for skills that resolve outside trusted skill directories.

When a /skill:<name> invocation reads a SKILL.md whose resolved path (via symlink) falls outside every trusted skill root, load_skill_content refuses the read. Rather than forcing the user to quit, edit env/config, and relaunch, this non-blocking modal asks for an in-the-moment decision. Allowing persists the resolved target directory to the skill trust store.

Confirmation modal for /install <package> --package in the TUI.

Arbitrary packages have no curated allowlist to vet against, so installing one pulls in third-party code. Rather than forcing the user to re-run with --force, this non-blocking modal asks for explicit confirmation before the install runs. --force (or --yes) still bypasses the prompt.

Tool-specific approval widgets for HITL display.

Welcome banner widget.

Enhanced diff widget for displaying unified diffs.

In-TUI MCP OAuth login modal.

MCPLoginScreen is both a Textual ModalScreen and an implementation of OAuthInteraction. The login worker awaits its interaction methods while the user sees and acts on the modal's widgets — authorize URLs become clickable links, paste-back callback URLs go through an inline input row, device-code instructions render inline, and the modal closes itself on success.

The screen runs on the Textual event loop (same loop as the worker), so methods called from the worker can await modal-bound futures directly without app.call_from_thread.

Interactive model selector screen for /model command.