user-dialog ยท diff
git:20260905.4e8ba32 to git:20260914.1c3399b
29 added, 22 removed. Audit A to A.
---
name: user-dialog
description: Create a purpose-built popup interface to communicate with the user and return their response to the conversation.
---
# User Dialog
- Codex determines the content and interaction. The helper displays an agent-authored GTK/libadwaita view, preserves its bound values, and returns the response. Compose the interface for the actual communication purpose; do not constrain it to a catalog of forms.
-
- Use the compact blue libadwaita shell. Group related requests in one window, preserving entered values across navigation. Fit the content without clipping text, controls, or card shadows; adapt the composition before introducing unnecessary scrolling. Keep implementation commentary out of the interface.
-
- Make the interaction usable without a mouse. Use the host's focus and default-action bridge, and keep keyboard order consistent with the authored layout.
-
- ## Compose and Open
-
- Set `SKILL_DIR` to this skill's absolute directory. Resolve view and run paths from the session project.
+ Compose a compact blue libadwaita dialog from a version 1 JSON request. The
+ renderer owns GTK, persistence, keyboard behavior, validation, and response
+ formatting; request-specific Python modules are not used.
- Read [references/view-contract.md](references/view-contract.md) before authoring the view when its API is absent from context. Write a Python module exposing `build(ui)` using the provided GTK objects and response bridge. Place request-specific files outside the installed skill directory.
+ Set `SKILL_DIR` to this skill's absolute directory. Request files and relative
+ custom template paths resolve from the project working directory.
```bash
- uv run --script "$SKILL_DIR/scripts/user_dialog.py" show <view.py> \
- --title "<user-facing title>" --run-dir <run-dir>
+ uv run --script "$SKILL_DIR/scripts/user_dialog.py" show <request.json|-> \
+ [--run-dir <path>] [--python <absolute-python>]
```
- The default run location is `dialog-runs/<unique-id>/`. The helper prints its path to stderr and returns one JSON response on stdout when the window finishes. If runtime discovery fails, read [references/runtime-setup.md](references/runtime-setup.md) and resolve the reported dependency or interpreter issue.
-
- ## Receive and Continue
-
- Retain and poll a yielded execution handle while awaiting the response. Do not open another copy of the same request or give a final waiting handoff while a response is still expected.
-
- Interpret `submitted` together with its action ID and values. `dismissed` and `deferred` contain no submitted answer. Do not treat closure or an untouched field as consent. Popup responses do not replace tool-required approvals.
+ `show` compiles the request, starts the renderer detached, and returns
+ operational status. A normal run captures the originating Codex task and
+ delivers the submitted result there as internal tool input through the desktop
+ app bridge. Add `--preview` to open without origin or delivery and save
+ `message.md`; preview is explicit and never a silent fallback.
- For a requested reopening or interrupted run:
+ Top-level keys are `version`, `title`, `subtitle`, `body`, `actions`,
+ `message`, and `width`; `title` is required and `version` is `1`.
+ Read [the view contract](references/view-contract.md) before composing when its schema is absent from context.
+ Use bundled templates as editable building blocks, or supply a custom JSON template;
+ compose content and behavior for the actual communication purpose. Localize visible
+ labels so each answer remains understandable on its own; use `response_label`
+ when a long prompt needs a shorter answer label. The runtime owns response
+ formatting, and typed text remains verbatim.
+ For interpreter or connection errors, read [runtime setup](references/runtime-setup.md).
```bash
+ uv run --script "$SKILL_DIR/scripts/user_dialog.py" validate <request.json|->
+ uv run --script "$SKILL_DIR/scripts/user_dialog.py" templates
uv run --script "$SKILL_DIR/scripts/user_dialog.py" status <run-dir>
uv run --script "$SKILL_DIR/scripts/user_dialog.py" resume <run-dir>
+ uv run --script "$SKILL_DIR/scripts/user_dialog.py" deliver <run-dir>
```
- Resume restores bound values; an already submitted run returns its saved response without reopening. Keep the original view and supporting files available. Fix view errors in those files and resume instead of changing the shared helper for a particular request.
+ `validate` reports structural validity. `resume` reuses the compiled spec
+ and absolute asset paths, restores the draft, and never reopens submitted state.
+ `deliver` retries only safe pre-send failures; `sending`, `unknown`, and
+ accepted states cannot be retried. Keep the run and referenced assets available.
- Report the actual response or delivery failure. Preserve the run when further interaction or recovery is needed.
+ After a successful normal launch, continue independent work or finish the current turn when waiting on the user. The detached renderer delivers the answer to the pinned task. Do not keep polling for the answer or repost `message.md` yourself. Dismissal, deferral, and navigation send nothing. A delivery error is not a submitted message; preserve the run and report its actual status.