Add terminal explorer tooling for headless configuration

[Hamedghz]

Summary

• add a reusable Control API client and command processor for headless explorers
• ship a Textual-based terminal explorer app plus a FastAPI text-browser bridge and launcher script
• document three terminal-first options for running the explorer alongside the headless deployment guide

Testing

• not run (tooling and documentation only)

---

https://chatgpt.com/codex/tasks/task_e_6906565536688328a4a285dfe9cc4934

[chatgpt-codex-connector]

💡 Codex Review

https://github.com/ghasemzadeh-hamed/OMERTAOS/blob/3e1d57840410116eb9397cbb8d7f9d69eb62bf03/console/tui/api.py#L195-L198
Default provider type ignores key= alias

The provider command defaults kind to "api" only when a "api_key" parameter is present, but the CLI help and examples use the shorter key= alias. In the common call add provider openai key=sk-…, params contains "key" and this branch sets kind to "local", registering a local provider with an API key that the control plane will never use. Users must manually add kind=api to get the expected behaviour. Consider treating either key or api_key as a signal to default to the api kind.

---

https://github.com/ghasemzadeh-hamed/OMERTAOS/blob/3e1d57840410116eb9397cbb8d7f9d69eb62bf03/console/tui/api.py#L157-L159
Unhandled request failures crash the terminal explorer

The command processor only traps ControlAPIError, but every API operation uses requests and will raise requests.RequestException on connection failures, TLS errors, etc. When the control service is offline or misconfigured, those exceptions bubble out of execute and tear down the Textual app or the FastAPI bridge instead of returning a friendly error. Catch RequestException (or a broader exception) alongside ControlAPIError and surface a message so the UI does not exit unexpectedly.

---

https://github.com/ghasemzadeh-hamed/OMERTAOS/blob/3e1d57840410116eb9397cbb8d7f9d69eb62bf03/console/tui/web_server.py#L68-L75
History output allows HTML/script injection

User commands and Control API responses are interpolated directly into the INDEX_TEMPLATE without HTML escaping. An attacker can craft a command such as <script>alert(1)</script> or a provider name that includes markup, and the / handler will render it verbatim in the history div. When the explorer is exposed on 0.0.0.0 or accessed through a graphical browser, this becomes an XSS vector. Escape user input and API output before inserting into the template or render through a templating engine that handles escaping by default.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".