host-console: Instructions file for Codex

Prototype Instructions

Run the local server yourself and open the preview in the browser available to this environment. Do not give the user server-start instructions when you can run it.

Before making substantial visual changes, use the Product Design plugin's get-context skill when the visual source is unclear or no longer matches the current goal. When the user gives durable prototype-specific design feedback, preferences, or decisions, record them in AGENTS.md.

When implementing from a selected generated mock, treat that image as the source of truth for layout, component anatomy, density, spacing, color, typography, visible content, and hierarchy.

Build app UI in src/. Keep .openai/hosting.json, worker/index.js, scripts/prepare-sites-build.mjs, and tests/sites-worker.test.mjs intact so the same local prototype can be handed to Sites. Before a Sites handoff, run npm run build and npm run test:sites; the build must leave dist/client/index.html, dist/server/index.js, and dist/.openai/hosting.json.

Durable product decisions:

• Agent access is a persistent, data-driven registry. Never hard-code supported Agent names into the UI; live MCP clients auto-register and remain visible while offline.
• Keep task/client identity separate from Agent installation identity: each task retains its own control lease, while a stable registry ID groups active tasks under one Agent row. Show the active task/connection count, and allow users to remove only offline, unconfigured discovered records.
• Each SSH host may persistently allow multi-Agent terminal writes. Default stays single-writer lease (others wait or force-takeover only after the user explicitly says so); enabling multi-write lets several Agents hold write rights at once. Turning the switch off immediately clears every writer and temporary sudo grant on that session.
• Each registered Agent has a persistent, independent connection switch. Turning it off must make the Agent appear disabled, reject every MCP bridge operation except registration/heartbeat cleanup, release its SSH leases, cancel pending sudo approvals, and revoke its sudo grants without affecting other Agents or disconnecting SSH.
• Each SSH host may persistently enable sudo auto-approval. It only bypasses the per-command sudo prompt while the session is in full mode and an enabled Agent owns the lease; passwords remain encrypted locally and disabling the switch immediately clears temporary sudo grants.
• Adding an Agent uses a local config-file wizard with preview, same-directory backup, and explicit restart guidance. Configuration paths stay in the desktop renderer and are never exposed through MCP snapshots.
• Native config-wizard formats include Codex TOML, OpenCode JSONC, ZCode ~/.zcode/cli/config.json under mcp.servers, WorkBuddy ~/.codebuddy/.mcp.json under mcpServers, and generic mcpServers; keep each Agent's registry kind and label distinct in the access center.
• Every SSH action is bound to a session ID. When more than one session is authorized, control acquisition also verifies the exact alias; Agents must ask rather than infer an ambiguous target.
• Saved SSH connections can be edited only while disconnected. Replacing authentication never reveals the old secret; the new encrypted credential overwrites it, and changing the endpoint resets pinned host trust.
• On desktop, the Agent access center expands to consume all vertical space between the terminal and permission controls; permission controls stay near the bottom so the session pane has no unused lower void. Compact layouts fall back to natural document flow.
• sudo approval defaults to a user-adjustable 30-minute no-prompt window (0 means one command, maximum 240 minutes). A grant is bound to the current SSH session and controlling Agent task, is visible and manually revocable in the UI, and is cleared by pause, mode downgrade, Agent handoff/disconnect, SSH disconnect, or expiry.