菜单
Modify or extend the PilotSwarm terminal UI. Covers the shared-first architecture across ui-core, ui-react, and packages/app/tui, the current layout and visual conventions, prompt/question behavior, and the requirement to keep maintainer docs updated as the TUI evolves.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
| name | pilotswarm-tui |
| description | Modify or extend the PilotSwarm terminal UI. Covers the shared-first architecture across ui-core, ui-react, and packages/app/tui, the current layout and visual conventions, prompt/question behavior, and the requirement to keep maintainer docs updated as the TUI evolves. |
Use this skill when changing any of:
packages/app/ui/core/packages/app/ui/react/packages/app/tui/run.shThe terminal UI is not a monolith.
ui-core owns state, controller logic, selectors, formatting, and transport-facing behavior.ui-react owns shared React composition and stays host-neutral.packages/app/tui is the thin terminal host: keyboard wiring, terminal rendering, process lifecycle, clipboard, downloads, and OS integration.Do not move host rendering details into ui-core.
Do not move controller or selector semantics into packages/app/tui.
Do not bypass shared selectors/components with host-only UI logic unless the behavior is truly terminal-specific.
M61 Conductor · R2D Train Watcher · Mad-Eye Moody; do not render agent-name prefixes before the useful title in session rows or chat pane headers.⚙ in yellow. Leave one text space after the marker in title-bearing rows/headers; the terminal renderer already gives this symbol enough visual width.model:effort display convention, falling back to the active session row's reasoningEffort when the metric summary was produced without that field.turnCount alongside token totals so model switches can be audited per turn bucket. Keep effort variants distinct in the model label.set_model command path; explicit restart actions remain separate.set_session_model calls are also terminal and schedule an automatic bootstrap correction continuation on the unchanged model. Failed control-plane switches are rejected before command acceptance and should not create chat continuations.session.turn_completed dividers. Keep the collapsed row compact (Mod, input/output tokens, duration) with provider/reasoning omitted from the model label; expanded details can show full model, effort, cache, tool, worker, and result data. The native TUI sequence view remains line-oriented unless a terminal-specific design is added deliberately.contextWindowSizes is available; keep generic smaller/larger labels as the fallback for catalogs without size metadata.none, minimal, low, medium, high, xhigh, and max; individual models expose subsets (for example Opus 4.8 exposes low through max).[cron <duration>] and wall-clock cron as [cron <next client-local time>] from shared selector state; status clearing must remove stale wall-clock cron fields when cronActive becomes false. Do not expose the internal cron_at tool name in row badges.~ icon or cron badge unless a newer session update, running state, or terminal state actually clears the wait.cron_at lifecycle events with the same visible cron label and magenta styling as interval cron, including a visible wake-up indicator when session.cron_at_fired arrives.[SESSION_MESSAGE ...] and [SESSION_MESSAGE_RESPONSE ...] protocol prompts are product-visible transcript items and must render as dedicated session request/reply cards, not collapsed activity-only system notices.f opens the session owner filter; keep terminal help text and docs aligned with that binding.Ctrl+G opens the move-to-group picker for the selected top-level non-system sessions, or for the active top-level non-system session when multi-select is off. The picker includes [New Group], existing groups, and [No Group]; keep status hints and keybinding docs aligned with that binding.P pins or unpins the active top-level session. Pinned rows render with a 📌 marker. System sessions, child (sub-agent) sessions, and sessions contained in a group cannot be pinned; moving a pinned session into a group drops the pin automatically. Pin state persists across portal devices through users.profile_settings.pinnedSessionIds; the portal does not use browser localStorage/cookies as a preference cache. The native TUI uses the user config file (pinnedSessionIds). Pins for sessions that no longer exist or that are no longer top-level are pruned automatically on the next session refresh.v cycles an owned non-system session tree through private, shared_read, and shared_write; uppercase S opens targeted sharing. Uppercase V remains multi-select. The portal exposes the same visibility/share actions through the selected-session controls, and both hosts enforce owner/admin capability flags from the transport.🗂 rows, can be pinned independently, and do not open a transcript. Session ordering bands are: system sessions first, pinned groups, pinned single sessions, unpinned groups, then unpinned sessions. On fresh page/app load, seed row order within each band and group by last-updated time, newest first; during live refreshes preserve stable row order so timestamp changes do not churn the visible list. Sessions inside a group are not pinnable; child rows follow the stable unpinned order. Leave two text spaces after the marker so terminal renderers do not crowd the title. Selecting a group opens a plain markdown group details view with metric and member tables in the chat pane; inspector and activity panes show a generic prompt to select a session instead of sequence/log/activity details. Groups are private per-user organization: each group belongs to the signed-in user, only that user sees it, and any readable session (owned or shared) can be placed in it — placement never changes access. Group rows show the group owner's owner-initials prefix. Groups do not support cancel/complete bulk actions; deleting a group clears only the owner's placements and never touches sessions. In the portal, the Sessions pane header exposes a Group / Group (n) button that opens the shared move-to-group picker.Complete & Restart, Cancel prompts for Terminate & Restart, and Delete prompts for Hard Delete & Restart. They all route through restartSystemSession, not ordinary completeSession / cancelSession / deleteSession. In the portal Sessions pane, the ordinary Terminate button becomes Restart for system sessions and opens a disposition picker with those three restart choices.s toggles between the transcript and the current session summary view; keep the portal top-toolbar Summary / Chat toggle and TUI keybinding help in sync. Do not add a second Chat/Summary control inside the chat pane header. Summary and group details are read-only views: the portal hides/disables the prompt composer and suppresses transient live-progress labels there.New/Model/Switch/Filter on row 1, and Theme/Chat-or-Summary/Focus/Admin on row 2. Portal connection/status text lives in the app header under the version pill, not in the toolbar.Apply Theme commits the previewed theme; Cancel, Close, backdrop click, or Esc restores the theme that was active when the picker opened.\\n) in otherwise tabular markdown, normalize and render the table structure instead of showing raw pipe-delimited text.V toggles multi-select mode (seeded with the active session). Space toggles selection on the active row, Ctrl+G moves every selected top-level non-system session through the move-to-group picker, c cancels every selected session in one confirmation (system sessions and groups are skipped), d completes selected sessions, D hard-deletes selected sessions, and Esc exits select mode. The portal mirrors selection with Cmd/Ctrl-click and Shift-click on session rows; the panel header reveals Clear, Group (n), and Terminate (n). Terminate (n) opens the same three-disposition picker for Complete, Cancel, and Hard Delete.f cycles between the session, fleet, and users views; keep terminal and portal behavior aligned.n fast-starts a generic session with the default model when generic sessions are allowed; if generic sessions are disabled, it falls back to the model-first creation flow when models are available, or the agent picker. Shift+N opens the model picker, then reasoning effort when applicable, then the generic/named-agent picker.transport.listCreatableAgents(), not by worker logs. In remote mode, packages/app/tui/src/node-sdk-transport.js builds that metadata from PLUGIN_DIRS; if session-policy.json.creation.bundledAgents opts into SDK-bundled agents such as generic-crawler, the transport must expand those names from packages/sdk/plugins/default-agents/ into creatableAgents so both native remote TUI and portal bootstrap show them.Fact Tombstones card when facts tombstone
backlog is nonzero. The card is fed by getFactsTombstoneStats through the shared
transport/controller/reducer path and renders pending, unreconciled, TTL-blocked,
oldest, and reconciled counts in packages/app/ui/core/src/selectors.js.x deletes the selected artifact after confirmation; keep terminal and portal behavior aligned.users.profile_settings so browser/mobile sessions share the same preferences. The portal must not read or write browser localStorage/cookies for these preferences; it may only clear old legacy keys/cookies at startup. The native TUI persists the same pinnedSessionIds, collapsedSessionIds, activeSessionId, theme/filter/view mode, and pane adjustments in its user config file. If no stored activeSessionId/collapsedSessionIds exist yet, the shared default is the main PilotSwarm system session selected with every group/parent session collapsed.Enter on an empty draft flushes the queued batch, Up/Down at the prompt boundary navigate queued items, and Esc cancels the selected queued item. Keep portal, TUI, status hints, and docs aligned with that behavior.sendAnswer is in flight and after it is accepted, then let the durable user.message transcript replace it once history sync catches up; stale session refreshes must not restore the old question card or hide the submitted exchange.Connection is closed / Live Copilot connection lost) should remain stable in the chat pane while the session is still running a retry; running detail refreshes must not clear and re-add the same warning card.Working card is governed by the session's running state, not by whether an assistant message has already appeared in the transcript. Assistant output can land before a turn is fully complete; keep the card visible until the session stops running.Working card and queued outbox are bottom-sticky flex siblings that reduce the transcript viewport height. useScrollSync must observe real viewport size changes and reapply the existing bottom/top anchor even when transcript lines did not change; otherwise the last transcript rows sit under the bottom fade and appear to slide behind Working. Preserve paused user scroll and touch momentum when re-anchoring.completed is not the same as a terminal child session: non-system children remain alive for follow-up, so graceful shutdown must use authoritative CMS lifecycle status and still close an idle child.Shift+A in the native TUI; toolbar Admin button in the portal) is a workspace-replacing surface for per-user settings. It must never display the raw GitHub Copilot key text — selectAdminConsole and selectAdminGhcpKeyEditorModal only carry the githubCopilotKeySet boolean and a masked editor value. The TUI and portal share the state.admin slice in ui-core and route every mutation through the controller (beginAdminEditGhcpKey, setAdminGhcpKeyDraft, cancelAdminEditGhcpKey, saveAdminGhcpKey, clearAdminGhcpKey, refreshAdminProfile); keep both hosts in sync if you add a new admin setting. Do not globally block New/New+Model when the per-user GitHub key is unset: GitHub models should fail only at create time when neither env GITHUB_TOKEN nor the per-user key is available, and non-GitHub providers must remain usable.○ pending (client only), ✓ queued (durably enqueued), ✓✓ sent (persisted as a transcript user.message). Synchronous sends coalesce into a single durable enqueue; merge boundaries are not user-visible. Keep the glyph mapping in packages/app/ui/core/src/selectors.js consistent across portal and TUI.When a keybinding changes, update all user-facing surfaces together:
packages/app/tui/src/app.jspackages/app/ui/core/src/selectors.js.github/copilot-instructions.mdThe native TUI and browser portal share ui-core state and ui-react components but diverge in these areas:
| Aspect | Native TUI (packages/app/tui) | Portal (packages/app/web) |
|---|---|---|
| Border radius | N/A (terminal box-drawing) | Slight rounding (6px / 8px) — subtle corners, not pills |
| Scrollbars | Native terminal scrolling | Custom dark scrollbars — slim, theme-matched thumbs/tracks instead of browser-default white scrollbars |
| Structured chat blocks | Box-drawing cards/tables rendered as terminal text | Web-native cards/tables — the portal converts shared box-drawing system notices and markdown tables into wrapped HTML blocks for layout fidelity |
| Status bar / keybinding hints | Rendered in a status strip below the workspace | Removed — the portal has no keybinding hints strip; status/error text is shown in the toolbar next to New/Refresh/Theme buttons |
| Footer | Status strip + prompt | No page-wide footer — the prompt composer lives inside the chat pane so it stays scoped to Chat instead of spanning inspector/activity columns |
| Session collapse default | Starts collapsed — sessions that become parents are auto-collapsed on initial bulk load, but manual expand stays respected across refreshes | Starts collapsed — same shared reducer behavior |
| Session collapse toggle | Keyboard shortcut in app.js | Click — clicking a session with children toggles collapse/expand in SessionPane |
| Nesting depth | Box-drawing prefix — the └ run (role:"depth") is rendered as text | Guide rails — the depth run is dropped and replaced by one hairline per ancestor level, painted as per-row background images so the list stays a flat row sequence |
| Row status mark | Glyph — the status run (role:"status") is rendered as text+colour | Disc at top level, RING when nested — the ring is centred on the row's deepest rail, so a run of siblings reads as one thread with a node each rather than a stack of glyphs. Status is still carried by colour; only the fill changes |
| Creating a session | Two keys — n fast-starts a generic session on the default model, Shift+N opens model → reasoning effort → agent | One ＋ button, and it opens the chooser (equivalent to Shift+N). The plain-＋ fast path was dropped: two buttons for one intent cost a toolbar slot the phone cannot spare. Deliberate divergence — the TUI keeps both keys |
| Admin console | Shift+A toggles it | Desktop only — the button is omitted on mobile. Its settings tree, package detail and file preview need width the phone layout cannot give them |
Both the depth and status runs are tagged by the shared selector precisely so a host can re-render them. The TUI ignores the tags by design — glyphs are correct in a terminal — so the rails and the nested ring are deliberately portal-only.
The auto-collapse-on-load logic lives in ui-core/src/reducer.js (shared). It collapses sessions when they first become parents, including nested parents, but must not re-collapse a row the user already expanded during later sessions/loaded refreshes. Initial active selection should be the first visible flat-tree row after collapse, not the first raw session object.
Both were broken once and cost a visible flicker each. Do not "simplify" either.
sessions/groupsLoaded must dispatch BEFORE sessions/loaded. sessions/loaded
seeds default collapse state and the default selection from the rows it can
see. With no folder rows in state it collapses nothing and auto-selects a
folder MEMBER, which then holds the folder open forever to keep that
selection visible.state.sessions.byId. Because of (1) the store still holds the previous
membership, so a folder whose last member just moved out looked claimed by
its own stale members and survived its deletion. The refresh passes the fresh
rows on the action ({ type: "sessions/groupsLoaded", groups, sessions }).refreshSessions() also stamps each run (sessionRefreshSeq) and drops its
writes if a newer run started while it was awaiting. Refreshes genuinely
overlap — a 4s catalog tick against a run that awaits several sequential
round-trips — and groupsLoaded is authoritative, so a stale snapshot landing
late deleted folders that a newer run had just found.
.github/copilot-instructions.md if contributor maintenance expectations changed.Prefer fast local checks for TUI work:
node --input-type=module -e "await import('./packages/app/ui/react/src/components.js'); await import('./packages/app/tui/src/platform.js')"
./run.sh local --db
Use targeted selector/controller smokes for shared UI logic. Boot the live TUI when changing layout, keybindings, prompt flow, modal behavior, or terminal rendering.
The order of operations for changing a live agent safely — diagnose, patch, publish, converge, verify, roll back. Use whenever you are about to modify an agent package that something is already running on.
Deploy PilotSwarm to AKS using the repo's canonical scripts and checks. Use when refreshing secrets, building/pushing the worker image, rolling out to AKS, or verifying provider/model changes in the live cluster.
Reset remote PilotSwarm state for AKS safely. Use when wiping the PilotSwarm database/blob state, clearing stale orchestration history, or recovering from namespace drift and replay/nondeterminism issues.
Use when bringing up a fresh, isolated PilotSwarm environment (`mysandbox`, `myenv2`, etc.) via the npm Bicep/GitOps orchestrator at `deploy/scripts/deploy.mjs`. Covers `new-env` scaffolding, EDGE_MODE × TLS_SOURCE selection, the `all` aggregate, per-service redeploys with `--steps`, force-redeploy semantics, verification, and teardown. Strictly separate from the legacy bash path operated by `scripts/deploy-aks.sh`.
Use after deploying a PilotSwarm stamp with VPN_GATEWAY_ENABLED=true when an operator needs the Azure VPN client profile (azurevpnconfig.xml). Wraps deploy/scripts/auth/Get-VpnClientProfile.ps1 — downloads the gateway-issued profile zip via 'az network vnet-gateway vpn-client generate' and extracts it under the gitignored deploy/envs/local/<env>/vpn-client/ folder. The XML is the same for every user (no per-user credentials), and end users still authenticate with their own Entra ID at connect time.
How to compute model latency and estimated $ cost from PilotSwarm observability data. Read this before reporting that a model is "slow" or "expensive" — most apparent slowness is orchestration overhead, not model inference, and most cost numbers are guesses unless they reference a real published price card.