CodeNomad/dev-docs/COMPOSER.md
Pascal André 36a2f17cf2
chore(sync): merge dev diagnostics with backend-owned readers
Compose the approved dev snapshot while retaining both histories and the backend API factory, attachment guards, retained view leases and cache identity fix. Host Settings owns OpenCode logs; the paired remote protocol keeps its closed route allowlist.

Accept removal of project Info, retain environment reconciliation in its store tests, and use the shared non-modal output frame without changing Shell ownership. Update the counted async inventory and preserve the 109 restore paths, runtime pins, workflows and cache blobs.

Validated in an ordinary private export with pinned Node 24.22.2: focused authority units, UI and server types, real log route tests, ten-language help and the six complete Chromium files. Deferred responses, executable changes, Shell ANSI/focus/drag/top-layer Escape and host administration stay covered. Native packaging and global qualification remain separate.
2026-11-11 17:26:14 +01:00

9 KiB

Composer

The prompt composer: context selectors, height, focus after send, alternate delivery, attachments, @ mentions, overlays and /btw.

Agent conventions

  • Prompt history uses a persistence identity separate from the physical directory: PromptInput supplies usePromptState.historyKey as backendScoped(backendId, instanceFolder). Local keys retain the exact directory string, including case, separators and trailing slashes. Drafts and attachments use the global instance key plus session; file operations retain the physical directory.

  • Default model resolution retains configured agent models, saved agent choices and recent choices while the instance's provider catalog is absent. Catalog absence is loading state; native creation and prompt dispatch keep the explicit model identity. Once published, the catalog supplies the existing availability checks. Regression: stores/session-default-model.test.ts.

  • The composer reserves /btw for native session.generate, outside ordinary prompt/command submission. Its ephemeral question/answer window uses DismissibleWindow and styles/components/session-aside.css; cancellation and inactive/session transitions fence late results without interrupting the main session.

  • Keep agent, model and thinking controls in the composer footer via PromptContextControls, on one row with the actions on desktop and touch (truncate selector labels, never wrap the footer); adapt it with the named prompt-composer container rather than viewport-only breakpoints. Dense conversation toolbar/footer controls and the session list header actions use --touch-target-size-compact (the latter must fit four actions plus the panel-toggle reserve in the 220 px minimum sidebar); timeline markers use the compact control height rather than the global touch target. Toolbar touch spacing lives in styles/panels/session-toolbar-touch.css.

  • Composer height limits depend only on the visible conversation height: minimum 8% (44 px floor), maximum 60% (never below that minimum). prompt-input/usePromptViewport.ts observes the conversation and its intersection with visualViewport, including keyboard resize/pan. Store manually chosen heights as proportions so the field itself follows viewport changes; saved pixel heights convert to a proportion on the first valid measurement. Viewport-driven changes never overwrite the saved proportion; pointer and keyboard resize controls share the same limits and long drafts remain scrollable.

  • On desktop a send moves focus to the conversation stream for keyboard reading (arrows, paging, Space); a printable character typed there resumes the composer with that character (prompt-input/type-to-focus.ts), while fields, controls, IME composition and plain-key shortcuts keep their keys. Touch-only devices keep the keyboard closed. Do not add delayed refocus timers or a preference for this.

  • The composer's More actions menu offers the other follow-up delivery than Enter (Queue message when Enter steers, Steer now when Enter queues), enabled only in normal mode while the session runs and a draft can be sent; it reuses the shortcut's delivery resolution and its tooltip shows the prompt-alternate-send shortcuts: Alt+Enter plus Mod+Shift+Enter by default, except on macOS where Option+Return is the native line break and only Cmd+Shift+Return sends. Pickers ignore any modified Enter. Covered by tests/browser/composer-alternate-send.test.ts and composer-picker-enter.test.ts.

  • The same menu offers Previous/Next User Message through requestUserMessageJump, with the configured user-message-prev/-next shortcuts in their tooltips. These transcript-navigation actions retain the draft, are separate from prompt-history recall and require an active, existing session. Menu entries capture their owning instance/session before dispatch. Covered by tests/browser/history-navigation.test.ts.

  • Composer overlays show attachment counts, shell-mode state and transient stop confirmation only; keep the textarea's semantic description and transient status announcement. Do not add a keyboard-shortcut strip or help footer. Keep overlay styling in styles/components/prompt-help.css, without changing field height limits or adding a footer row.

  • Composer attachments use one native-device action and project-scoped @ references. Picker/drop/clipboard bytes share prompt-input/useDeviceAttachments.ts for serialized budgets and epoch-based draft/focus fencing; keep lifecycle and read logic out of prompt-input.tsx. File listing/search validate the session directory through existing workspace ownership before reading a worktree or translated WSL root.

  • In local Linux Tauri windows, a trusted paste with no browser File items requests native clipboard attachments through lib/native/clipboard-attachments.ts when it carries file URIs or lacks plain text. GTK reads clipboard URI/image offers on the main thread and bounded regular-file bytes on a worker; all bytes enter the shared device attachment queue with the paste's original draft epoch and selection. The native command validates the local application webview and origin, and its capability targets only local-* webviews. Windows and macOS keep their browser paste path.

  • An Images conversation (root session marked codenomad.companion: images) whose selected agent is design while its own Location's loaded agent catalog lacks it (a list read for another Location counts as not loaded, agentCatalogLocations) shows DesignAgentNotice above the composer, with "Use the default agent" (the catalog's first selectable primary agent, through the session's agent change), and PromptInput's sendBlocked refuses every send (prompt, command, shell, /btw) while typing stays available. Another selected agent, an unmarked conversation and an unloaded catalog never block. Covered by tests/browser/images-conversation.test.ts.

  • Panel extensions add text to the displayed conversation's draft only through API 4 composer.prefill (components/panel-extensions/composer-prefill.ts, rules): PromptInputApi.setPromptText with the draft composed from getPromptText(), refused in shell mode (getMode()), when the result starts with / or when findMentionStart (exported from prompt-input/usePromptPicker.ts, the picker's own rule) finds an open mention at its end. Never send, attach or resolve mentions from it; Ctrl+Z in the composer leaves the added text in place. Covered by tests/browser/panel-extension-api4.test.ts.

  • Host actions that show a conversation and hand it the keyboard call requestComposerFocus (stores/composer-focus.ts); the active SessionView consumes the request and focuses its composer two frames later, on every layout. Do not focus composers from stores through DOM queries.

  • The @ mention menu lists Location skills with search, names and descriptions; selecting one attaches a removable skill and drops the @query token. Skills use the existing PromptAttachmentsBar alongside files and agents, never a separate composer row. The default prompt placeholder lists skills alongside files and agents in every locale. Keep the composer free of a permanent Skills button or /skills shortcut. Explicit attachments use native skill.list for the session Location and send IDs through prompt.skills; selection lives in prompt-input/usePromptPicker.ts. Sending clears only the composer selection; OpenCode keeps the instructions stored with the message. MessageBlock retains skill labels in sent and historical messages without exposing instruction bodies or inventing tool calls; test through the full transcript, not an isolated badge. Queued edits restore removable attachments, never reinsert removed skills from the original payload.

  • A long paste becomes a pasted #N text attachment and a [pasted #N] placeholder in the draft. Sending resolves each placeholder in place (lib/prompt-display-metadata.ts), so the model receives the pasted text exactly once, wherever the placeholder stood (inside code fences too), and never as a separate part. The local display metadata records only inline/pasted segment lengths; splitPromptDisplaySections renders each pasted segment as a folded "Pasted text" section (line count, copy), and a fenced code block (```/~~~, any info string, closed or running to the end) containing pasted text renders as one such section holding the block's code, counting and copying the code between its fences (without the line break before the closer, LF or CRLF). Lines touching pasted text are never fence lines (a paste ending in a line break ends its line), closers take only spaces or tabs after the fence. The section holds only the code and its opening fence (codeFence): Markdown bounds the code itself and formatFencedCode (its formatText) fences each displayed window with a fence longer than any run of its marker in that window, so fences inside a paste stay literal code and the display bound never cuts a generated fence. Never rewrite the sent text to change its display. Covered by lib/prompt-display-metadata.test.ts and tests/browser/pasted-code-fence.test.ts.