> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_40/prd_phase_40.md). # PRD Phase 40: Claude OS v2.10.1 Semantic Port **Status**: Complete **Sessions**: 18 (initial estimate) **Estimated Duration**: 9-14 days **Progress**: 18/18 sessions (100%) *** ## Overview Phase 40 ports actionable Claude OS 2.9, 2.10, and 2.10.1 Hermes changes into AI OS while preserving the current AI OS split Hermes architecture, naming, privacy, public demo, local control-plane, graph storage, media, and metadata boundaries. This Phase PRD now preserves the global source planning record for the port, and the session stubs in this directory preserve the original session split details. The port translates upstream behavior into existing AI OS owners instead of copying upstream monolithic route or Vite middleware files. *** ## Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | --------------------------------------- | -------- | ---------- | ---------- | | 01 | Baseline And Port Invariants | Complete | \~12-25 | 2026-07-02 | | 02 | Models And Provider Readiness | Complete | \~12-25 | 2026-07-02 | | 03 | Shared Redaction Foundation | Complete | \~12-25 | 2026-07-02 | | 04 | Chat Overrides And Runtime | Complete | \~12-25 | 2026-07-03 | | 05 | Command Endpoint | Complete | \~12-25 | 2026-07-03 | | 06 | MoA Save Endpoint | Complete | \~12-25 | 2026-07-03 | | 07 | Connection Probe Parity | Complete | \~12-25 | 2026-07-03 | | 08 | Catalog And Context Metadata | Complete | \~12-25 | 2026-07-03 | | 09 | Model Intelligence And Pricing | Complete | \~12-25 | 2026-07-03 | | 10 | Assets And Media Compliance | Complete | \~12-25 | 2026-07-03 | | 11 | Chat Model Selector And Context Meter | Complete | \~12-25 | 2026-07-03 | | 12 | Compact And Chat Polish | Complete | \~12-25 | 2026-07-03 | | 13 | Command UX And Slash Actions | Complete | \~12-25 | 2026-07-03 | | 14 | Ministry Builder And Pantheon | Complete | \~12-25 | 2026-07-03 | | 15 | Ministry Config, Analytics, And Save UX | Complete | \~12-25 | 2026-07-03 | | 16 | Voice Parity And Broker Respawn | Complete | \~12-25 | 2026-07-03 | | 17 | Docs, Metadata, And Gitignore Closeout | Complete | \~12-25 | 2026-07-03 | | 18 | Full Validation And Handoff | Complete | \~12-25 | 2026-07-03 | *** ## Completed Sessions * 2026-07-02: Session 01 - Baseline And Port Invariants completed. Created the Phase 40 baseline audit, port invariants, decision list, owner mapping, classification ledger, and validation record while keeping production source, public docs, package behavior, graph data, and user-facing UI unchanged. * 2026-07-02: Session 02 - Models And Provider Readiness completed. Expanded Hermes model parsing and bridge output for upstream-compatible defaults, catalog metadata, MoA mixtures, configured-provider summaries, and provider readiness aliases with no-leak coverage. * 2026-07-02: Session 03 - Shared Redaction Foundation completed. Added the shared bridge-output sanitizer and likely-secret detector, migrated Hermes admin and dev bridge redaction call sites, and validated no-leak behavior with focused sanitizer and bridge tests plus the full repo suite. * 2026-07-03: Session 04 - Chat Overrides And Runtime completed. Added per-request Hermes chat model/provider overrides, MoA preset send support, runtime stream safeguards, sanitized `info` diagnostics, and parser, hook, bridge, and Intelligence coverage. * 2026-07-03: Session 05 - Command Endpoint completed. Added a deterministic token/admin-gated Hermes command endpoint, typed parser and hook contracts, non-shell allowlisted execution, confirmation-gated update behavior, bounded sanitized output, and focused bridge, sanitizer, parser, and hook coverage. * 2026-07-03: Session 06 - MoA Save Endpoint completed. Added the admin-gated `/__hermes_moa_save` endpoint, strict MoA preset payload validation, browser-safe setup and write errors, config backup and atomic replacement behavior, typed parser and hook contracts, and focused bridge, parser, hook, and fixture coverage. * 2026-07-03: Session 07 - Connection Probe Parity completed. Added allowlisted GitHub, Google Workspace, Linear, and Spotify CLI-backed connection probes, a 30 second status-only cache, safe missing/error/timeout mapping, explicit skipped Hermes MCP probe metadata, expanded parser and hook contracts, demo fixture alignment, and UI coverage that keeps raw command details out of product copy. * 2026-07-03: Session 08 - Catalog And Context Metadata completed. Added bundled upstream 2026-06-30 model catalog provenance, provider labels and tints, explicit context fallback metadata, `anthropic/claude-sonnet-5` coverage, alias-aware configured-provider filtering, safe demo fixtures, richer Hermes parser and hook contracts, and Pantheon model option coverage. * 2026-07-03: Session 09 - Model Intelligence And Pricing completed. Added Hermes-scoped Ministry model intelligence rows, bundled snapshot pricing, optional local OpenRouter live-pricing overlay, browser-safe parser and ranking helpers, demo fixture gating, hook exposure, and product-facing pricing provenance coverage without live benchmark claims. * 2026-07-03: Session 10 - Assets And Media Compliance completed. Rehomed the 15 Hermes provider SVGs, added the browser-safe provider asset registry and script-side media audit, verified the optimized Ministry hero, and recorded provenance, safety, duplicate-decision, and validation evidence. * 2026-07-03: Session 11 - Chat Model Selector And Context Meter completed. Added the split Hermes chat model selector, approximate context meter, controlled selected-model state, ordinary and MoA send option wiring, responsive composer toolbar slots, and focused selector, context, and payload coverage. * 2026-07-03: Session 12 - Compact And Chat Polish completed. Added the compact summary flow through the existing admin chat transcript boundary, visible local-chat carryover scoping, assistant reply copy controls, elapsed thinking state, narrowed startup-warning filtering, and focused compact, copy, timer, warning, privacy, and label coverage. * 2026-07-03: Session 13 - Command UX And Slash Actions completed. Added the Hermes command menu and slash actions, allowlisted admin command routing, update confirmation, redacted command output and failure bubbles, compact and new-chat command routing, and focused command helper, chat component, admin hook, admin type, and Intelligence event coverage. * 2026-07-03: Session 14 - Ministry Builder And Pantheon completed. Added the Pantheon Ministry builder with safe provider assets, recommended lineup reset, click and drag seat assignment, duplicate and max-expert enforcement, analytics and save/copy shells, existing persona workflow regression coverage, and desktop/mobile route smoke validation. * 2026-07-03: Session 15 - Ministry Config, Analytics, And Save UX completed. Added strict Hermes v0.17 MoA config generation, safe YAML and prompt copy, admin-gated direct save states, duplicate-save prevention, Ministry analytics with live-versus-bundled provenance, model refresh assertions, and focused/full validation coverage. * 2026-07-03: Session 16 - Voice Parity And Broker Respawn completed. Added voice parity evidence for environment-backed broker respawn, expanded bridge, hook, and portal coverage for empty launches, provider-boundary rejection, distinct recovery states, and queued Session 17 documentation notes without porting browser key persistence. * 2026-07-03: Session 17 - Docs, Metadata, And Gitignore Closeout completed. Updated Local API Notes, README, Agent Pages, Data Contract, Local Voice Setup, Intelligence View, TODO, changelog, and the Phase 40 closeout ledger with shipped Hermes behavior, not-ported upstream rationale, package metadata boundaries, `.gitignore` rationale, graph seed preservation, and privacy-safe validation evidence. * 2026-07-03: Session 18 - Full Validation And Handoff completed. Recorded final Phase 40 focused, broad, build, demo, privacy, browser-smoke, security, and handoff evidence; repaired and documented the public demo aggregate bundle cap at 1,600 KB; and bounded the remaining live-provider proof items without adding new product behavior. *** ## Upcoming Sessions * None - Phase 40 is complete. *** ## Objectives 1. Rebaseline upstream Claude OS 2.9, 2.10, and 2.10.1 deltas and lock AI OS port invariants before implementation. 2. Expand Hermes model, provider, chat, command, MoA save, and connection bridge contracts with parser, redaction, and guard coverage. 3. Refresh catalog, context, Ministry model intelligence, pricing provenance, and visual assets within AI OS media and demo boundaries. 4. Port the chat model selector, context meter, command menu, compact flow, reply copy, thinking state, and narrowed startup-warning handling. 5. Integrate Ministry into the current Pantheon and complete valid MoA config, analytics, copy fallback, and admin-gated save UX. 6. Verify voice no-reprompt parity through AI OS environment-backed broker behavior without browser key persistence. 7. Update documentation and metadata only after matching behavior ships, then complete focused and broad validation. *** ## Prerequisites * Phase 39 completed. * Upstream checkout and diff files named in the folded source record are available during implementation sessions. * AI OS Hermes remains split across route shell, components, hooks, schemas, public bridge, and admin bridge. *** ## Planning Assumptions And Resolutions ### Working Assumptions * The folded source planning record is the intended Phase 40 source: state marks Phase 39 complete, the master PRD previously ended at Phase 39, and the dated record clearly defines the next Claude OS upstream port. Phasebuild can proceed by updating both state tracking and the master PRD to include Phase 40. * The authoritative session count is 18: the top-level session split includes Session 18, and the plan's later "Suggested Implementation Sessions" section states that the top-level session split is authoritative. The older appendix phase headings are lower-level planning material, not spec-system sessions. ### Conflict Resolutions * Master PRD versus folded source record: the master PRD did not yet list Phase 40, while the source record defines clear unfinished work after a complete Phase 39. The chosen interpretation is to create Phase 40 from the folded record and reconcile the master PRD and state.json in this phasebuild run. *** ## Technical Considerations ### Architecture Translate upstream behavior into the existing AI OS split Hermes architecture: `src/routes/agents.hermes.tsx` remains a thin shell; feature work belongs in Hermes components, hooks, schemas, `scripts/lib/hermes-dev-bridge.ts`, and `scripts/lib/hermes-admin-bridge.ts`. ### Technologies * Bun, Vite 8, TanStack Start, React 19, and TypeScript. * Existing Hermes public and admin bridge modules. * Existing `js-yaml` dependency for Hermes config parsing and dumping. * Existing AI OS asset, privacy, public-demo, and control-plane validation scripts. ### Risks * Upstream monolithic route copy: translate behavior into current owners and record skipped upstream paths. * Browser-visible secret leakage: extend shared sanitization before command, chat diagnostic, and MoA save output paths. * Local write expansion: preserve loopback, Host-header, same-run token, admin, method, body-size, schema, timeout, and safe-error gates. * Model/provider alias drift: normalize aliases before filtering configured providers and keep MoA presets selectable. * Demo and hosted leakage: keep demo fixture-only and disable writes and live pricing in public/demo mode. * Media policy regression: keep the raw upstream Ministry hero out of commits; use the optimized AI OS copy or another under-cap replacement and validate new assets against `docs/media-policy.md`. * Voice secret handling regression: keep provider credentials environment-only and reject browser-supplied keys. ### Relevant Considerations * \[P38] **Upstream ports are semantic, not wholesale**: Map hunks to AI OS module owners, record superseded or skipped upstream paths, and keep release reconciliation evidence. * \[P38] **Local control-plane gates are defense in depth**: Preserve socket loopback, Host-header, token/admin, method, body-size, schema, timeout, and safe-error checks. * \[P38] **OpenAI Realtime keys stay environment-only**: Voice broker credentials must never come from browser bodies, argv, docs, fixtures, or generated data. * \[P31-P39] **Public-demo, AI Rogue, and hosted-surface gates stay bundled**: Run privacy, fixture, no-bridge, hosted metadata, asset, browser, and review gates for public, media, runtime, or authored-content changes. * \[P00] **Stack conventions**: Bun, Vite 8, TanStack Start, React 19, Radix UI, and Cloudflare Worker compatibility remain baseline constraints. *** ## Success Criteria Phase complete when: * [ ] All 18 sessions completed. * [ ] Actionable Claude OS 2.9, 2.10, and 2.10.1 Hermes changes are implemented in AI OS or explicitly marked not ported with rationale. * [ ] Expanded Hermes model, chat, command, MoA save, and connection contracts are tested. * [ ] Model response parsers tolerate both AI OS and upstream-style envelopes. * [ ] Provider alias normalization covers Google/Gemini, OpenAI subscription, xAI, OpenRouter, and MoA preset paths. * [ ] Chat SSE handling includes the chosen heartbeat, watchdog, stderr diagnostic, and post-output cleanup behavior. * [ ] Ministry is integrated into Pantheon and generates, copies, and saves valid MoA config with admin gating. * [ ] Pricing and model benchmark provenance are visible and demo-safe. * [ ] Voice behavior matches the no-unnecessary-reprompt outcome without browser key persistence. * [ ] Docs describe shipped AI OS behavior only. * [ ] New assets comply with the media policy. * [ ] Required validation commands pass or have documented bounded follow-up. * [ ] No generated private data, raw local paths, account-auth material, logs, coverage, or secret-shaped strings are committed. *** ## Dependencies ### Depends On * Phase 39: AI Rogue Level Authoring Infrastructure. * Claude OS 2.10.1 upstream checkout and diff evidence referenced by the folded source record. ### Enables * Post-port Hermes stabilization, future upstream port reconciliation, and safer Ministry/chat feature iteration in AI OS. *** ## Folded Source Record The sections below preserve the global Phase 40 source planning record after the standalone ongoing-project document was removed, without losing audit, implementation, risk, validation, or direct upstream reference detail. The original Session Split Plan sections are preserved in the matching session stubs in this directory. ### Folded Source Metadata * Original title: Claude OS 2.10.1 Port Plan * Status: Planned * Captured: 2026-07-02 * Source upstream: `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1` * Diff source: `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1_to_v2.10.1.patch` * Previous AI OS port baseline: Claude OS 2.8.1 * Scope: Port actionable Claude OS 2.9, 2.10, and 2.10.1 changes into AI OS while preserving AI OS naming, privacy boundaries, public demo safety, and the current split Hermes bridge architecture. *** ### Folded Session Split Location The original `## Session Split Plan` content is folded into these session stubs: * `session_01_baseline_and_port_invariants.md` * `session_02_models_and_provider_readiness.md` * `session_03_shared_redaction_foundation.md` * `session_04_chat_overrides_and_runtime.md` * `session_05_command_endpoint.md` * `session_06_moa_save_endpoint.md` * `session_07_connection_probe_parity.md` * `session_08_catalog_and_context_metadata.md` * `session_09_model_intelligence_and_pricing.md` * `session_10_assets_and_media_compliance.md` * `session_11_chat_model_selector_and_context_meter.md` * `session_12_compact_and_chat_polish.md` * `session_13_command_ux_and_slash_actions.md` * `session_14_ministry_builder_and_pantheon.md` * `session_15_ministry_config_analytics_and_save_ux.md` * `session_16_voice_parity_and_broker_respawn.md` * `session_17_docs_metadata_and_gitignore_closeout.md` * `session_18_full_validation_and_handoff.md` ## Executive Summary Claude OS 2.10.1 is primarily a Hermes release. The upstream diff adds: * Ministry of Experts, a Mixture-of-Agents builder that writes MoA presets into `~/.hermes/config.yaml`. * A refreshed Hermes chat composer with a configured-provider model selector, per-model context meter, deterministic Hermes command menu, compact action, model/provider overrides, copy buttons, and stronger command-output redaction. * Expanded Hermes model catalog, configured-provider detection, OAuth/subscription provider labels, MoA preset discovery, and model-intelligence updates. * A small saved-key voice respawn fix. * Vendor logos, a Ministry hero image, and route/style polish. AI OS cannot safely port this by copying upstream `src/routes/agents.hermes.tsx` or upstream `vite.config.ts`. Current AI OS already split Hermes into: * route shell: `src/routes/agents.hermes.tsx` * page and panels: `src/components/hermes/...` * public bridge: `scripts/lib/hermes-dev-bridge.ts` * admin/write bridge: `scripts/lib/hermes-admin-bridge.ts` * hooks and schemas: `src/hooks/use-hermes.ts`, `src/hooks/use-hermes-admin.ts`, `src/lib/hermes-types.ts`, `src/lib/hermes-admin-types.ts` The port should translate upstream behavior into those existing boundaries. *** ## Second-Pass Audit Findings This second pass compared the first-pass plan against the upstream 2.10.1 checkout and the current AI OS implementation. The first-pass direction is mostly correct, but the implementation plan needs these corrections before work starts: | Finding | Evidence | Plan update | | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Upstream `/__hermes_models` does not use the current AI OS response envelope. | Upstream returns `default`, `catalog`, `mixtures`, and `configured` without `ok` at `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:2787-2792`; AI OS currently requires `ok: true` and `configuredDefault` in `src/lib/hermes-types.ts`. | Return both AI OS-compatible and upstream-compatible fields from the bridge, and make the parser tolerate either shape during the port. | | Provider filtering can hide valid Google/xAI/OpenRouter paths unless aliases are normalized first. | Upstream catalog uses `googlegemini`, `xai-oauth`, `xai`, `sakana`, `minimax`, and OpenRouter IDs at `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:2592-2702`; upstream configured detection maps `GOOGLEAI_API_KEY`, `XAI_API_KEY`, `GROK_API_KEY`, `DEEPSEEK_API_KEY`, `MINIMAX_API_KEY`, and `NVIDIA_API_KEY` at `:2751-2766`. | Extend `scripts/lib/hermes-provider-readiness.ts` and frontend labels before enabling configured-provider filtering. Preserve AI OS `google`/`gemini` compatibility by aliasing them to upstream `googlegemini` where needed. | | Chat endpoint parity is broader than model/provider argv wiring. | Upstream adds SSE heartbeat, a 120s pre-output watchdog, an 8s post-output idle watchdog, stderr `info` events, `PYTHONUNBUFFERED`, `TERM`, `COLUMNS`, and `LINES` at `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:1202-1206`, `:1268-1285`, and `:1288-1356`; AI OS currently has a fixed chat timeout and only `chunk`/`done`/`error` SSE events. | Port watchdog/heartbeat/env parity and expose sanitized `info` events as diagnostics for UI/Intelligence mapping, never as normal assistant reply text. | | Frontend chat payload validation currently drops new model/provider options. | Upstream active model state and selected model wiring live at `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:2960-3075`; AI OS `chatPayloadOptions` currently only emits `toolsets`, `yolo`, and `graph`. | Update `HermesChatSendOptions`, `chatPayloadOptions`, hook tests, and admin bridge parsing together so selected models actually reach Hermes. | | Command redaction should be shared, not copied into one endpoint. | Upstream `/__hermes_cmd` redaction masks home paths, account identifiers, key/value secrets, known token prefixes, emails, and long opaque strings at `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:2914-2940`; AI OS currently has a narrow admin-local `SECRET_PATTERN`. | Extend the existing `scripts/lib/sanitize.ts` redaction module and use it for chat output, command output, MoA save responses, and future bridge failures. | | Upstream Ministry analytics include a live OpenRouter price fetch, not only bundled model data. | Upstream `useOpenRouterPrices` fetches `https://openrouter.ai/api/v1/models` at `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:8971-8991`; Ministry then overlays live prices at `:10037-10060`. OpenRouter's current Models API returns pricing fields and was reachable keylessly with CORS on 2026-07-02. | Port the keyless live price query for local live mode only, use 30 minute stale time, fail soft to bundled snapshot prices, and label the source of each value. Disable live pricing in public/demo mode. | | MoA YAML generation should be safer than upstream string interpolation. | Upstream emits inline YAML from raw provider/model strings at `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:8597-8623`. | Generate MoA config with `js-yaml` or a tested YAML quoting helper so OpenRouter IDs with `/` or `:` cannot break copied config. | | AI OS already has the privacy-preserving voice respawn path; upstream browser key persistence is not a direct port. | Upstream stores/reuses a browser OpenAI key at `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/components/intelligence-portal.tsx:281-330`; AI OS starts `/__start_voice` from environment-backed provider config and rejects browser-supplied provider config. | Treat the upstream outcome as parity criteria only: broker respawns without reprompt when env config exists; do not add localStorage key persistence. | | Upstream connection probing is partly missing and should be reviewed as a deliberate security/performance choice. | Upstream skips `hermes mcp list` because it hangs without a TTY, then probes CLI services with 500 ms timeouts at `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:2045-2084`; AI OS already has auth/env/generic service scanning. | Port useful CLI probes with allowlisted argv arrays, no shell, no output, short timeouts, and a 30 second status-only cache. Keep MCP probing skipped. | | Gitignore and metadata changes are confirmed non-copy candidates. | Upstream only adds `src/data/graphs/claude-os.json` to `.gitignore`; AI OS currently tracks `src/data/graphs/ai-os.json` and `src/data/graphs/index.json`. Upstream also removes package/README version strings only. | Keep the existing metadata guidance: do not ignore tracked AI OS graph files, and do not remove AI OS package version or README identity text because upstream did. | *** ## Third-Pass Audit Findings This third pass checked the second-pass plan against exact upstream 2.10.1 snippets and current AI OS files. The plan remains directionally right, but the following gaps should be corrected before implementation: | Finding | Evidence | Plan update | | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Redaction should extend AI OS's existing sanitizer instead of creating a parallel Hermes sanitizer. | AI OS already exports `sanitize` and `sanitizeForEmission` from `scripts/lib/sanitize.ts:99-127`; `scripts/lib/hermes-admin-bridge.ts:56-58` still keeps a narrow `SECRET_PATTERN`, and `sanitizeCommandOutput` at `:591-592` applies only that local pattern before home/name redaction. Upstream command redaction is broader at `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:2914-2940`. | Extend `scripts/lib/sanitize.ts` with bridge/output redaction helpers or detectors, then call that helper from Hermes chat/cmd/MoA paths. Keep any YAML secret warning detector shared with the same implementation. | | Provider readiness task overstates missing keys and misses one upstream Google key. | Current AI OS already maps `MINIMAX_API_KEY` and `NVIDIA_API_KEY` in `scripts/lib/hermes-provider-readiness.ts:23-41`; upstream configured detection also maps `GEMINI_API_KEY` in addition to `GOOGLE_API_KEY` and `GOOGLEAI_API_KEY` at `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:2751-2766`. | Add the missing upstream keys and aliases, but treat existing `MINIMAX_API_KEY`/`NVIDIA_API_KEY` support as verification coverage rather than new work. | | MoA presets must stay selectable even when configured-provider filtering is non-empty. | Upstream reads `mixtures` separately from catalog groups at `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:2703-2729`; the selector renders mixtures independently before catalog filtering at `src/routes/agents.hermes.tsx:2507-2526`. | Add tests that discovered MoA presets render while catalog providers are filtered, and make chat payload validation explicitly allow provider `moa` with preset names. | | `Claude Sonnet 5` is an explicit 2.10.1 catalog addition, not just a generic Sonnet fallback. | The 2.10.1 changelog calls it out at `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/CHANGELOG.md:29-33`; upstream catalog adds `anthropic/claude-sonnet-5` at `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:2624-2627`. | Name `anthropic/claude-sonnet-5` in the catalog tasks, context tests, and manual smoke checklist so it is not missed during the catalog refresh. | | Do not add dependencies already present in the fork. | AI OS already imports `dump` and `load` from `js-yaml` in `scripts/lib/hermes-admin-bridge.ts:19`; the plan correctly asks for structured YAML, but package tasks should avoid churn. | Use the existing `js-yaml` dependency for admin-side config merge/dump. Add package changes only if frontend-side YAML generation requires a new, justified path. | | Current AI OS tests already include voice-launch, hook-level, and component-level Intelligence coverage. | Existing files include `scripts/lib/__tests__/voice-launch-bridge.test.ts`, `src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx`, and `src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx`. | Put voice parity tests at the bridge/hook/component layer that owns each behavior; do not create duplicate component coverage unless UI state changes. | *** ## Upstream Change Inventory | Upstream area | 2.10.1 references | AI OS disposition | | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Changelog scope and release intent | `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/CHANGELOG.md:8-44`, `:48-98`, `:101-151` | Use as the feature checklist, but write AI OS docs in current-state language. | | Hermes chat model selector and context meter | `src/routes/agents.hermes.tsx:2140-2535` | Port into new split chat components under `src/components/hermes/chat/`. | | Hermes command menu, compact, active model state | `src/routes/agents.hermes.tsx:2723-3075`, `:3798-3821`, `:4246-4268`, `:4555-4575` | Port behavior into `HermesChatTab`, `ChatComposer`, hooks, and tests. | | Chat model/provider bridge overrides | `vite.config.ts:1103-1305` | Translate into `scripts/lib/hermes-admin-bridge.ts`; do not re-add route logic to `vite.config.ts`. | | Chat streaming watchdog and SSE behavior | `vite.config.ts:1202-1206`, `:1268-1285`, `:1288-1356` | Port heartbeat, buffering env, two-stage timeout, and stderr handling into the admin bridge or document an intentional deviation. | | `/__hermes_cmd` command endpoint | `vite.config.ts:2796-2946` | Add as an admin bridge endpoint with allowlisted commands and hardened sanitizer. | | `/__hermes_models` response shape | `vite.config.ts:2550-2794` | Extend `HermesModelsBody`, public bridge output, and hook consumers. | | `/__hermes_connections` CLI probes | `vite.config.ts:2045-2084` | Port useful probes with bounded non-shell argv, no output, and cache; keep TTY-unsafe MCP probing skipped. | | Ministry direct save endpoint | `vite.config.ts:331-428` | Add to admin bridge with stricter validation and no raw private paths in UI output. | | Ministry UI and save component | `src/routes/agents.hermes.tsx:8551-8615`, `:8841-8968`, `:9735-9845`, `:9905-10379` | Port as dedicated components integrated into current Pantheon UI. | | Ministry live pricing | `src/routes/agents.hermes.tsx:8971-8991`, `:10037-10060` | Port live keyless pricing only for local live mode; fall back to bundled snapshot prices and disable the live fetch in public/demo mode. | | Model intelligence data changes | `src/data/model-intel.json:156-162`, `:234-240`, `:287-312`, `:451-457`, `:1650-1676` | Use upstream data as source material for a Hermes-scoped Ministry subset; do not add a repo-level `src/data/model-intel.json` unless another AI OS surface needs it. | | Voice saved-key respawn | `src/components/intelligence-portal.tsx:281-317` | Preserve current environment-backed `/__start_voice` broker flow; verify parity and fix only if broker-down respawn regresses. | | Assets | `src/assets/logo-*.svg`, `src/assets/ministry-hero.webp` | The 2.8.1 to 2.10.1 media gap adds 15 root provider logo SVGs and `ministry-hero.webp`; staged in AI OS `src/assets/`, with the hero recompressed to 520x654 and 185,156 bytes. Session 10 still owns duplicate/use audit and final path decisions before UI wiring. | | Styles | `src/styles.css:413-567` | Scope styles to current `.hermes-agent-route` and component classes; do not import global `.hermes-skin` assumptions wholesale. | | `.gitignore` graph file | `.gitignore` in upstream adds `src/data/graphs/claude-os.json` | Do not copy the upstream ignore. Keep tracked AI OS seed graph files unless a new local-only graph artifact name is introduced and documented. | | README/package metadata | `README.md`, `package.json` | Do not copy upstream package version removal; AI OS owns `package.json` identity and version. | *** ## Current AI OS Mapping | AI OS current file | Current role | Port impact | | ------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `src/routes/agents.hermes.tsx` | Thin route shell delegating to `HermesReadOnlyPage`. | Keep thin. Do not paste upstream monolithic route. | | `src/components/hermes/hermes-read-only-page.tsx` | Hosts Hermes panels, lazy Intelligence portal, and page-level state. | Add any new Ministry/Pantheon surfaces here only through component props. | | `src/components/hermes/chat/hermes-chat-tab.tsx` | Current Hermes chat, image upload, graph grounding, local messages. | Add active model state, command execution, compact flow, copy replies, and context meter wiring. | | `src/components/hermes/chat/chat-composer.tsx` | Current prompt/image/send/reset controls. | Add toolbar slots for model selector, command menu, and context meter. | | `src/components/hermes/chat/chat-types.ts` | Chat message and send option contracts. | Add `model` and `provider` to `HermesChatSendOptions`. | | `scripts/lib/hermes-dev-bridge.ts` | Public loopback reads for status, connections, models, Pantheon, docs, missions. | Extend models read with catalog, configured providers, context, and MoA presets. | | `scripts/lib/hermes-admin-bridge.ts` | Token/admin-gated writes and chat execution. | Add model/provider overrides, command endpoint, MoA save endpoint, and redaction hardening. | | `scripts/lib/hermes-provider-readiness.ts` | Provider normalization, labels, auth-kind mapping, and env-key readiness. | Add upstream 2.10.1 provider aliases before filtering the model picker. | | `src/lib/hermes-types.ts` | Public bridge response types/parsers. | Extend `HermesModelsBody`; tolerate upstream no-`ok` `default` shape and AI OS `configuredDefault` shape. | | `src/lib/hermes-admin-types.ts` | Admin bridge response types/parsers. | Add command, MoA save, and optional chat `info` event request/response types/parsers. | | `src/hooks/use-hermes.ts` | Public bridge fetch orchestration. | Consume new model response fields without breaking demo fallback. | | `src/hooks/use-hermes-admin.ts` | Admin action orchestration. | Expose `runHermesCommand`, `saveHermesMoaPreset`, and chat model override options. | | `src/hooks/use-hermes-intelligence-voice.ts` | Current AI OS broker-based voice flow. | Review saved-key respawn parity; preserve AI OS broker ownership and docs. | | `src/styles.css` | Current global and Hermes styles. | Add scoped Ministry/context/command styles only as needed. | *** ## Port Rules 1. Translate behavior into AI OS modules. Do not replace AI OS's split Hermes implementation with the upstream monolithic route. 2. Keep AI OS product naming. Use "AI OS" for host app, shell, local operator cockpit, scheduler, Dream host behavior, and platform docs. 3. Use "Claude OS" only when naming the upstream project or historical port source. 4. Preserve compatibility env names such as `VITE_CLAUDE_OS_*` and `CLAUDE_OS_*`. Do not add new global `findtrend` identifiers. 5. Keep public demo and local bridge boundaries separate. All write endpoints remain loopback, same-run-token gated, and admin gated where they mutate local files or installations. 6. Do not commit `.env`, private generated data, account-auth files, raw operator data, local logs, coverage, test results, browser reports, or secret-shaped strings. 7. Browser-facing errors, command output, and scheduler/status output must redact home paths, private paths, emails, account IDs, tokens, and key-shaped values. 8. Treat upstream model data as a snapshot from 2026-06-30. Do not overstate it as live/current unless the implementation refreshes it from a verified source. 9. Demo mode uses committed, browser-safe fixtures only. Do not read local configured-provider summaries or fetch live OpenRouter pricing in demo mode. 10. Ministry uses a Hermes-scoped model subset by default. Do not add a repo-level `src/data/model-intel.json` unless a separate AI OS surface needs the full dataset. 11. Live OpenRouter pricing is allowed only in local live mode, must fail soft to bundled snapshot prices, and must visibly label which source is used. 12. Validate assets against `docs/media-policy.md` before committing. Raw upstream `ministry-hero.webp` is 385,932 bytes and exceeds the current 200 KB non-logo committed asset cap; the staged AI OS copy is recompressed to 185,156 bytes, and any replacement must stay under the cap. 13. Add focused tests for bridge contracts, command sanitization, model picker filtering, chat override arguments, MoA config writes, and public-demo/write gating. 14. Use structured parsers/serializers for YAML config changes. Avoid raw string interpolation for copied or written MoA YAML unless a focused test covers quoting for `/`, `:`, quotes, and whitespace. 15. Do not port upstream browser key persistence into AI OS voice. The parity target is "no unnecessary reprompt" through the environment-backed broker. 16. Keep the surface name "Hermes Intelligence"; use "Voice" only for speech-specific controls and recovery copy. 17. Do not copy upstream graph ignores. Keep committed AI OS seed graph files tracked unless this port creates a new documented local-only artifact name. *** ## Phase 0: Baseline Audit Goal: confirm exactly what changed upstream and lock AI OS invariants before implementation. * [ ] Re-read the upstream diff files: * `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1_to_v2.10.1.patch` * `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1_to_v2.10.1.stat.txt` * `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1_to_v2.10.1.name-status.txt` * [ ] Confirm no local user changes conflict with the port before editing: * `git status --short` * [ ] Snapshot current Hermes tests before the port: * `bun run test -- scripts/lib/__tests__/hermes-admin-bridge.test.ts scripts/lib/__tests__/hermes-dev-bridge.test.ts src/hooks/__tests__/use-hermes-admin.test.tsx src/components/hermes/chat/__tests__/hermes-chat-tab.test.tsx` * [ ] Confirm current control-plane guard expectations around `/__hermes_*`, `/__token`, `/__start_voice`, and public demo mode. * [ ] Verify upstream-vs-AI-OS response envelope differences before coding: * upstream `/__hermes_models` returns `default`, `catalog`, `mixtures`, and `configured` without `ok` * AI OS public parsers currently require `ok: true` * admin chat SSE currently parses `chunk`, `done`, and `error`, while upstream can emit `info` * [ ] Confirm current graph files under `src/data/graphs/` are generated or committed intentionally before applying any `.gitignore` change. * [ ] Confirm media budget before copying upstream images: * `bash scripts/check-asset-sizes.sh` Deliverable: a small implementation note in the first PR or session summary recording which upstream files are translated and which are intentionally not ported. *** ## Phase 1: Bridge Contracts And Type Schemas Goal: make the backend and TypeScript contracts capable of carrying upstream 2.10.1 behavior before wiring UI. ### 1.1 Extend Hermes model response Upstream reference: * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:2550-2794` * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:2147-2161` Tasks: * [ ] Extend `src/lib/hermes-types.ts` so `HermesModelsBody` supports: * `configuredDefault` for current AI OS compatibility, optionally carrying `context` * upstream-compatible `default: { provider; name; context? } | null` * `catalog: Array<{ provider; models: Array<{ name; tier; context? }> }>` * `mixtures: Array<{ name; references; aggregator? }>` * `configured: string[]` * [ ] Preserve parser tolerance so old AI OS bridge responses, upstream 2.10.1 no-`ok` model bodies, and demo fixtures still parse. * [ ] Update `scripts/lib/hermes-dev-bridge.ts` `readHermesModels` to return the expanded shape while retaining existing fields: * `ok: true` * `configuredDefault` * `default` * `catalog` * `mixtures` * `configured` * [ ] Read MoA presets from `~/.hermes/config.yaml` with `js-yaml`, fail soft on absent/malformed files, and never include raw config content in browser output. * [ ] Extend `scripts/lib/hermes-provider-readiness.ts` before filtering: * add OAuth/subscription providers `xai-oauth` and any upstream auth names missing from `HERMES_OAUTH_PROVIDERS` * add provider labels for `googlegemini`, `xai`, `xai-oauth`, `deepseek`, `sakana`, and any retained AI OS aliases * add missing env-key readiness for `GEMINI_API_KEY`, `GOOGLEAI_API_KEY`, `XAI_API_KEY`, `GROK_API_KEY`, and `DEEPSEEK_API_KEY` * verify existing `MINIMAX_API_KEY` and `NVIDIA_API_KEY` handling remains covered by tests * normalize `google`, `gemini`, and `googlegemini` consistently so the configured-provider filter does not hide Google models * [ ] Build `configured` from existing readiness sources: * current default provider * `~/.hermes/auth.json` provider keys * `~/.hermes/.env` API-key presence * `providers:` entries in `~/.hermes/config.yaml` * current `classifyHermesProviderReadiness` behavior in `scripts/lib/hermes-provider-readiness.ts` * [ ] Keep discovered MoA presets selectable even when `configured` is non-empty: * render `mixtures` independently from filtered catalog provider groups, or include provider `moa` only when presets exist * never show raw MoA config content in the browser response * [ ] Add tests in `scripts/lib/__tests__/hermes-dev-bridge.test.ts` for: * default context parsing * configured provider detection * Google/Gemini alias matching * OAuth/subscription provider detection * MoA preset discovery * missing/malformed config fail-soft behavior * no secret or raw path leakage * [ ] Add or update `src/lib/__tests__/hermes-types.test.ts` for: * upstream no-`ok` model body * AI OS `ok: true` model body * optional `context` on default and catalog rows Acceptance: * The model hook can render old and new bridge bodies. * The configured-provider set hides unconfigured providers when non-empty. * Demo/public mode shows only bundled safe catalog and demo MoA rows; it does not expose local configured-provider details. ### 1.2 Add per-chat model/provider overrides Upstream reference: * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:1125-1191` * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:1252-1263` Tasks: * [ ] Extend `src/components/hermes/chat/chat-types.ts` with `model?: string` and `provider?: string` in `HermesChatSendOptions`. * [ ] Extend `src/hooks/use-hermes-admin.ts` chat send payloads to include safe `model` and `provider` values. * [ ] Update `chatPayloadOptions` in `src/hooks/use-hermes-admin.ts` so the frontend does not silently drop selected model/provider values before sending `POST /__hermes_chat`. * [ ] Update `scripts/lib/hermes-admin-bridge.ts` chat request parsing: * model regex from upstream: `^[A-Za-z0-9][A-Za-z0-9_.\/:-]{0,119}$` * provider regex from upstream: `^[A-Za-z0-9][A-Za-z0-9_-]{0,59}$` * reject invalid values before spawning Hermes * pass `-m ` and `--provider ` as argv entries, never shell strings * [ ] Preserve existing `sessionId`, `toolsets`, `yolo`, and `graph` behavior. * [ ] Preserve source-entrypoint resolution and inherited env cleanup, then port the upstream chat runtime safeguards where they improve AI OS: * heartbeat comments while the SSE stream is open * `PYTHONUNBUFFERED=1` * explicit terminal sizing/env only where needed by Hermes output behavior * 120 second pre-output timeout * 8 second post-output idle termination that counts as success only after output was received * browser disconnect kills the child and clears timers * [ ] Expose upstream stderr as sanitized `info` SSE events by extending `HermesChatEvent`, `parseHermesChatEvent`, and `mapHermesChatEvents`; keep info events out of normal assistant bubble text. * [ ] Re-evaluate current empty-toolset handling. Upstream allowed an empty string for "no tools" in Knowledge Graph chat; current AI OS uses graph mode instead. Keep existing graph behavior unless a focused test shows empty toolsets are required. * [ ] Add tests in `scripts/lib/__tests__/hermes-admin-bridge.test.ts` for: * valid model/provider arguments * injection-shaped model/provider rejection * model/provider plus resume args ordering * graph/yolo/toolset compatibility * pre-output timeout failure * post-output idle success after at least one chunk * disconnect cleanup * [ ] Add tests in `src/hooks/__tests__/use-hermes-admin.test.tsx` for: * selected model/provider included in chat payload * MoA preset sends `provider: "moa"` and the preset name as `model` * invalid model/provider rejected client-side before fetch * sanitized `info` SSE event parsing Acceptance: * The UI can select a model or MoA preset for one conversation without mutating `~/.hermes/config.yaml`. * Invalid model/provider payloads return a controlled 400 response. * Chat no longer reports a post-answer Hermes cleanup hang as a failed turn. ### 1.3 Add deterministic Hermes command endpoint Upstream reference: * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:2796-2946` * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:2723-2858` * Changelog hardening: `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/CHANGELOG.md:34-44`, `:64-70`, `:91-95` Tasks: * [ ] Add a POST `/__hermes_cmd` handler inside `scripts/lib/hermes-admin-bridge.ts`. * [ ] Add the endpoint to the current admin endpoint list and Vite bridge registration, preserving loopback and same-run token checks. * [ ] Gate mutating `update` behind admin mode and UI confirmation. Non-mutating commands may still require token because they expose local account/setup status. * [ ] Allowlist only: * `version -> hermes version`, timeout 20 seconds * `status -> hermes status`, timeout 25 seconds * `insights -> hermes insights --days 30`, timeout 30 seconds * `doctor -> hermes doctor`, timeout 60 seconds * `update -> hermes update --yes`, timeout 300 seconds * [ ] Resolve Hermes the same way current chat does: prefer source entrypoint under `~/.hermes/hermes-agent`, fall back to `resolveCliBin("hermes")`, and strip inherited `PYTHONPATH`/`PYTHONHOME`. * [ ] Use `NO_COLOR=1` and `TERM=dumb` for command output. * [ ] Report timeouts as failures. Do not return partial update output as success. * [ ] Replace output use of the current narrow admin-local `SECRET_PATTERN` with an exported helper in the existing `scripts/lib/sanitize.ts` redaction module that covers: * ANSI/CSI escape sequences * raw home path and symlink-realpath home * explicit key/value pairs for api key, access token, refresh token, bearer, secret, password, and token * account, user, channel, chat, id, and home identifiers inside parentheses * OpenAI, Slack, GitHub, Google, JWT, and long opaque token shapes * email addresses * long base64/hex-like strings * [ ] Reuse the same exported secret detector for persona YAML warnings, or leave a small wrapper around the shared detector if the warning semantics need to stay narrower than command-output redaction. * [ ] Use the same helper for: * `/__hermes_chat` stdout/stderr-derived output * `/__hermes_cmd` output and error details * `/__hermes_moa_save` backup labels and controlled errors * future Hermes bridge failures that include command output * [ ] Add tests covering upstream examples, AI OS private-path patterns, and non-secret words that must not be redacted. Acceptance: * Command output is useful, deterministic, and redacted by default. * Unknown commands are rejected. * Timed-out commands fail loudly. * Public demo mode cannot execute the endpoint. ### 1.4 Add MoA save endpoint Upstream reference: * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:331-428` * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:9735-9845` Tasks: * [ ] Add POST `/__hermes_moa_save` or a namespaced admin action equivalent in `scripts/lib/hermes-admin-bridge.ts`. * [ ] Require loopback, same-run token, and explicit admin mode because the endpoint writes `~/.hermes/config.yaml`. * [ ] Validate payload: * sanitized preset name, limited to a short slug * one aggregator with `provider` and `model` * one to three reference models with `provider` and `model` * bounded numeric `reference_temperature`, `aggregator_temperature`, and `max_tokens` * no unknown large payload fields * [ ] Use `homedir()` to find `~/.hermes/config.yaml`. * [ ] If config is missing, return a controlled setup-required error without leaking private paths. * [ ] Before writing, timestamp-backup the existing config. * [ ] Merge into `cfg.moa.presets[name]` and set `cfg.moa.default_preset = name` without clobbering unrelated config keys or other presets. * [ ] Return `{ ok, name, presets }` and a safe backup label. Do not return the full backup path to browser UI. * [ ] Add tests for: * successful merge * existing preset preservation * config backup creation * invalid payload rejection * missing config * admin disabled * token failure * no raw path leakage Acceptance: * Ministry can save a Hermes MoA preset locally. * Other Hermes config remains intact. * Browser-visible responses remain sanitized. ### 1.5 Add safe Hermes connection probe parity Upstream reference: * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:1911-2091` Current AI OS reference: * `scripts/lib/hermes-dev-bridge.ts:1450-1558` * `scripts/lib/hermes-provider-readiness.ts` Tasks: * [ ] Compare current AI OS connection scanning against upstream: * provider default/config readiness * `auth.json` provider map * gateway tokens in `~/.hermes/.env` * generic `*_API_KEY`, `*_TOKEN`, `*_SECRET`, `*_ACCESS_TOKEN`, and `*_API_TOKEN` services * explicit skip for `hermes mcp list` until Hermes provides a non-TTY-safe command * upstream CLI-backed service probes for GitHub, Google Workspace, Linear, Spotify, Notion, and Airtable * [ ] Port useful CLI probes with bounded, no-output, non-shell execution. Do not copy upstream shell probe strings blindly. * [ ] Use allowlisted argv arrays for CLI probes: * `gh auth status` * `gws auth status` * `linear whoami` * `spotify auth status` * [ ] Prefer env parsing for token-only checks such as Notion and Airtable instead of shelling out to `test`. * [ ] Add a 30 second cache for connection status only; keep cache invalidation simple and do not cache secret values. * [ ] Add tests for connected/missing CLI probes, timeout behavior, and no raw env value leakage. * [ ] Record only the TTY-unsafe MCP probe as intentionally skipped until Hermes provides a safe non-interactive command. Acceptance: * Connection summaries include useful CLI probe coverage and explicitly document the MCP probe skip. * No public connection response exposes command output, env values, private paths, emails, account IDs, or tokens. *** ## Phase 2: Catalog, Model Intelligence, And Assets Goal: port the model knowledge needed by chat and Ministry without importing unnecessary upstream product surfaces. ### 2.1 Refresh Hermes model catalog Upstream reference: * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:2592-2702` * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/CHANGELOG.md:29-33`, `:80-82` Tasks: * [ ] Update the current `HERMES_MODEL_CATALOG` in `scripts/lib/hermes-dev-bridge.ts` with the 2.10.1 provider groups and model IDs, while keeping AI OS-supported provider aliases intact. * [ ] Include the explicit 2.10.1 OpenRouter catalog addition `anthropic/claude-sonnet-5` from upstream. * [ ] Treat upstream provider IDs as compatibility-sensitive, especially: * `googlegemini` from upstream catalog * existing AI OS `google` and `gemini` aliases * `openai-codex` for subscription-backed OpenAI models * `xai-oauth` for subscription-backed xAI/Grok models * `openrouter` for routed IDs with `/` and sometimes `:free` * current AI OS `local` versus upstream `ollama` local-model naming * [ ] Include OAuth/subscription providers: * `openai-codex` * `xai-oauth` * [ ] Add friendly provider labels in the frontend: * `openai-codex -> OpenAI / ChatGPT sub` * `xai-oauth -> xAI / X sub` * [ ] Add labels for new or renamed catalog groups such as `googlegemini`, `sakana`, `xai`, `minimax`, `deepseek`, `nvidia`, and retained AI OS local providers. * [ ] Preserve locally useful providers that AI OS already supports if not present upstream. * [ ] Add context window metadata where known, using upstream context table as a fallback. * [ ] Mark this catalog as an upstream 2026-06-30 snapshot in comments or docs, not a live source of truth. Acceptance: * The picker includes the upstream 2.10.1 IDs but only shows unconfigured providers when no configured providers can be detected. ### 2.2 Add Hermes-scoped model intelligence and live-local pricing Upstream reference: * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/data/model-intel.json:156-162` * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/data/model-intel.json:234-240` * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/data/model-intel.json:287-312` * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/data/model-intel.json:451-457` * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/data/model-intel.json:1650-1676` * Ministry consumer: `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:9907-9951` Tasks: * [ ] Create a Hermes-scoped curated subset, for example `src/components/hermes/ministry/ministry-models.ts`, with only the fields Ministry renders. Do not add a repo-level `src/data/model-intel.json` file for this port. * [ ] Use upstream `src/data/model-intel.json` as source material only; keep the committed AI OS shape smaller and Ministry-owned unless another AI OS surface explicitly needs full model intelligence. * [ ] Add lightweight validation for the Ministry model subset so missing cost, speed, context, or benchmark fields fail tests for required default lineup rows. * [ ] Port upstream `useOpenRouterPrices` as a local-live-only pricing overlay with fail-soft behavior, 30-minute stale time, no key requirement, no user identifiers, and demo/public mode disabled. * [ ] Always show whether a price is from live OpenRouter data or bundled snapshot data; do not silently mix the two. * [ ] Include upstream data changes: * Arena agent metrics for Claude Opus 4.8, Opus 4.7, Sonnet 4.6, and GPT-5.5 * GLM 5.1 to GLM 5.2 update * DeepSeek V4 Pro rating coverage * [ ] Add tests for model row parsing and default Ministry lineup availability. * [ ] Add tests for static-price fallback, live-price failure, and demo-disabled live pricing. Acceptance: * Ministry analytics can rank by agent benchmark, cost, and speed without pulling unrelated upstream UI into AI OS. * Pricing copy makes clear whether values are live OpenRouter data or bundled snapshot data, and demo mode never performs the live fetch. ### 2.3 Port vendor logos and Ministry visual asset safely Upstream reference: * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/assets/logo-claude.svg` * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/assets/logo-openai.svg` * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/assets/logo-zai.svg` * all upstream `src/assets/logo-*.svg` * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/assets/ministry-hero.webp` Gap audit: * Comparing `claude-os-v2.8.1` to `claude-os-v2.10.1` found no removed media files and no changed shared `src/assets` media. * Added media files: `logo-claude.svg`, `logo-cohere.svg`, `logo-deepseek.svg`, `logo-gemini.svg`, `logo-grok.svg`, `logo-meta.svg`, `logo-minimax.svg`, `logo-mistral.svg`, `logo-moonshot.svg`, `logo-nvidia.svg`, `logo-openai.svg`, `logo-qwen.svg`, `logo-tencent.svg`, `logo-xiaomi.svg`, `logo-zai.svg`, and `ministry-hero.webp`. * The AI OS copy of `ministry-hero.webp` is recompressed from the 385,932-byte upstream source to 520x654 and 185,156 bytes so `bash scripts/check-asset-sizes.sh` passes. Tasks: * [ ] Audit the staged root `src/assets/logo-*.svg` provider logos before final use. * [ ] Reuse existing AI OS logos when equivalent assets already exist, then rehome or document root usage for any imported logo that remains. * [ ] Check existing `src/assets/logos/openai.png`, `src/assets/logos/openrouter.svg`, `src/assets/logos/googlegemini.svg`, and other current logo assets before wiring upstream `logo-*.svg` files. * [ ] Validate SVG contents before UI wiring. * [ ] Keep `src/assets/ministry-hero.webp` under 200 KB. The staged AI OS copy is optimized to 185,156 bytes; if Session 10 replaces it, the replacement must also pass the asset check. * [ ] Run: * `bash scripts/check-asset-sizes.sh` Acceptance: * All new assets comply with `docs/media-policy.md`. * Ministry UI has meaningful, distinctive visual assets without failing asset checks. *** ## Phase 3: Hermes Chat UI Port Goal: bring the 2.10.1 chat UX into AI OS's split chat implementation. ### 3.1 Create split components for model selector and context meter Upstream reference: * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:2140-2535` Tasks: * [ ] Add `src/components/hermes/chat/context-meter.tsx`. * [ ] Add `src/components/hermes/chat/model-selector.tsx`. * [ ] Keep state ownership in `HermesChatTab`; components receive controlled props. * [ ] Port token estimate behavior: * prose chars divided by about 4 * code/JSON-like text divided by about 3.5 * per-message overhead * visible `~` estimate copy * [ ] Port context fallback table: * GLM 5.2 around 1,048,576 * GLM 5.1 and older around 202,752 * Haiku around 200,000 * Claude/Fable/Opus/Sonnet, including Claude Sonnet 5, around 1,000,000 * GPT-5.5 around 1,050,000 * GPT-5/GPT-4.1/o3/o4 around 400,000 * Gemini around 1,048,576 * Grok, DeepSeek, MiniMax, Qwen, Kimi, Llama, Nemotron, Mistral, Fugu/Sakana as upstream specifies * [ ] Port 100-cell popover breakdown: * conversation * Hermes base estimate * free space * 80 percent compaction marker/copy * [ ] Adapt styling to current AI OS Hermes classes and responsive constraints. Do not use inline styles wholesale if local component patterns already cover the state. * [ ] Add unit tests for: * estimate changes with draft text * active model context selection * configured-provider filtering * MoA preset rows Acceptance: * The composer shows a model selector and useful context meter without layout shift or overlap on mobile and desktop. ### 3.2 Add command menu and slash actions Upstream reference: * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:2723-2858` * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:2978-3075` Tasks: * [ ] Add `src/components/hermes/chat/chat-commands-menu.tsx`. * [ ] Wire `runHermesCommand(cmd)` through `useHermesAdmin`. * [ ] Show command output as a Hermes message with monospace/pre formatting. * [ ] If chat `info` SSE events are ported, show them as dim diagnostics or map them only into the Intelligence activity rail; do not append stderr notices as normal assistant reply text. * [ ] Confirm before running `update`. * [ ] Add slash palette actions for: * `/compact` * `/insights` * `/status` * `/doctor` * `/version` * `/update` * `/new` * [ ] Keep slash behavior discoverable but not intrusive; avoid in-app tutorial prose. * [ ] Add tests for command calls, confirm cancel, confirm accept, command errors, and slash filtering. Acceptance: * Commands run real allowlisted Hermes subcommands, not model prompts. * Output appears redacted and stable. ### 3.3 Add compact flow Upstream reference: * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:3033-3054` * Changelog hardening: `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/CHANGELOG.md:40-44` Tasks: * [ ] Implement "summarize and start fresh" as an ordinary Hermes chat request that asks for a tight context brief. * [ ] Start a new local chat after the summary succeeds. * [ ] Seed the fresh chat with a visible carryover message. * [ ] Prevent carryover from leaking into a different chat/session: * bind carryover to the active chat instance * clear it on new chat/cancel/session load where appropriate * add regression tests * [ ] Preserve current session resume behavior and graph grounding behavior. * [ ] Avoid claiming token window is exactly reclaimed unless Hermes creates a fresh session without `--resume`. Acceptance: * Compact produces a summary and fresh session. * Carryover cannot land in an unrelated chat. ### 3.4 Add reply copy, thinking timer, and benign-warning filter Upstream reference: * Copy button: `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:4246-4268` * Thinking state: `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:4555-4575` * Warning filter: `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:2223-2234` Tasks: * [ ] Add a copy button to Hermes replies using local button/icon patterns. * [ ] Add a "Hermes is thinking" elapsed timer before first output. * [ ] Narrow benign-warning stripping to only Hermes startup diagnostics: * `Warning: Unknown toolset...` * `Warning: Unrecognized...` * `Warning: Deprecat...` * `Warning: No config...` * [ ] Ensure a legitimate model response that starts with "Warning:" is not stripped. * [ ] Add tests for warning stripping and copy button rendering. Acceptance: * Chat polish matches 2.10.1 behavior without hiding real replies. ### 3.5 Preserve Intelligence naming with Voice-specific controls Upstream reference: * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/CHANGELOG.md:76-79` Tasks: * [ ] Keep the current Hermes "Intelligence" portal/surface name because AI OS uses it for typed, spoken, and visual reasoning. * [ ] Use "Voice" only for speech-specific controls, recovery copy, and setup notes. * [ ] Check `docs/intelligence-view.md` and related route copy to ensure the naming distinction is consistent. * [ ] Do not add new Intelligence portal claims unless matching code and tests exist. Acceptance: * The labels match AI OS product language: "Hermes Intelligence" for the portal, "Voice" for the speech loop. *** ## Phase 4: Ministry Of Experts Port Goal: integrate the 2.9 Ministry release into the current Hermes Pantheon without regressing existing persona editing. ### 4.1 Component structure Upstream reference: * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:9905-10379` Tasks: * [ ] Add Ministry components under `src/components/hermes/ministry/`, for example: * `hermes-ministry-card.tsx` * `ministry-models.ts` * `ministry-analytics.tsx` * `ministry-save.tsx` * `vendor-logo.tsx` * [ ] Integrate `MinistryCard` as the first item in the current Pantheon grid or a clearly related Pantheon section in `src/components/hermes/hermes-pantheon.tsx`. * [ ] Keep existing persona create/edit/delete/install behavior intact. * [ ] Do not nest cards inside cards; keep the open builder as a full-width panel or unframed layout consistent with current Hermes panels. * [ ] Preserve keyboard and pointer interactions: * drag model to a seat * click model then click a seat * Escape cancels armed model * remove seat * reset to recommended lineup * [ ] Add tests for opening/closing, seat assignment, no duplicate core/expert, max expert count, reset, and mobile layout stability. Acceptance: * Pantheon gains Ministry without breaking existing persona workflows. ### 4.2 MoA config generation Upstream reference: * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:8551-8615` * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:8841-8968` Tasks: * [ ] Generate Hermes v0.17 MoA schema with provider/model separated: * `reference_models: [{ provider, model }]` * `aggregator: { provider, model }` * `reference_temperature` * `aggregator_temperature` * `max_tokens` * `enabled` * [ ] Generate copyable YAML through `js-yaml` or a tested YAML quoting helper, not raw template interpolation. Cover OpenRouter IDs with `/`, `:`, quotes, and whitespace in tests. * [ ] Prefer the existing `js-yaml` dependency already used by `scripts/lib/hermes-admin-bridge.ts`; do not add package metadata churn unless frontend-only YAML generation needs a separate implementation. * [ ] Use `openai-codex` for OpenAI subscription-backed models where upstream did so, and `openrouter` for OpenRouter IDs. * [ ] Keep a copy-prompt fallback for users who do not enable admin writes. * [ ] Add a max-tokens control with sane bounds: * default 4096 * recommended ceiling 16384 * bounded upper limit to prevent config mistakes * [ ] Add tests for config text and save payload generation. Acceptance: * The builder emits valid MoA config and save payloads. ### 4.3 Ministry analytics Upstream reference: * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:9937-9951` * Upstream changelog: `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/CHANGELOG.md:113-127`, `:138-143` Tasks: * [ ] Show cost, speed, and agent/intelligence ranking from the selected model data. * [ ] Keep analytics clearly "indicative" if the data is bundled/static. * [ ] Use the Session 09 live-local OpenRouter overlay, fail soft to bundled prices when the network request fails, and keep public/demo mode on bundled snapshot prices only. * [ ] Add sorting for arena, cost, and speed. * [ ] Ensure every default lineup model has the fields needed to render without "unknown" gaps: * Claude Opus 4.8 * GPT-5.5 * GLM 5.2 * DeepSeek V4 Pro * [ ] Add tests for sorting and missing-metric fallbacks. Acceptance: * Ministry gives useful lineup feedback without claiming live benchmark data. * Sort order remains stable when live pricing is unavailable, and pricing source labels stay accurate. ### 4.4 Save UX and admin gating Upstream reference: * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:9735-9845` Tasks: * [ ] Wire Ministry save through `useHermesAdmin`. * [ ] Disable direct save in demo mode. * [ ] Disable direct save when admin mode is unavailable. * [ ] Surface setup-required state if `~/.hermes/config.yaml` is missing. * [ ] Show a safe success message that names the preset and says the config was backed up, without printing private backup paths. * [ ] Refresh Hermes models after save so the chat selector can show the new MoA preset. Acceptance: * Save succeeds locally when admin gate is open and fails safely otherwise. *** ## Phase 5: Voice And Intelligence Parity Goal: achieve the upstream "do not reprompt every session" outcome only where AI OS is missing it, without copying upstream browser key storage. Upstream reference: * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/components/intelligence-portal.tsx:281-317` * Changelog: `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/CHANGELOG.md:129-136` Current AI OS reference: * `src/hooks/use-hermes-intelligence-voice.ts:271-330` * `src/hooks/use-hermes-intelligence-voice.ts:489-568` * `scripts/lib/voice-launch-bridge.ts` Tasks: * [ ] Compare upstream saved-key behavior with current AI OS broker startup. AI OS currently starts the broker through `/__start_voice` using environment provider config, not by posting a key from localStorage. * [ ] Confirm the current `voice-launch-bridge` behavior remains intact: * request body must be empty * provider key comes from `OPENAI_API_KEY` * optional base URL comes from `OPENAI_BASE_URL` * response errors distinguish missing key, invalid token, health timeout, and provider/session failure * [ ] Preserve Session 08 broker ownership and Session 09 Intelligence portal ownership caveats from docs. * [ ] Keep the current hook behavior that calls `/__start_voice` before opening setup/error UI. Fix only if tests reveal a broker-down regression when a valid local provider key exists. * [ ] Do not store raw OpenAI keys in browser localStorage or accept provider keys in `/__start_voice` request bodies unless an explicit AI OS security decision changes the voice policy and updates docs/tests. * [ ] Add or update tests in `scripts/lib/__tests__/voice-launch-bridge.test.ts`, `src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx`, and `src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx` where each behavior is owned: * broker down plus local key configured starts broker * missing key opens setup/error state * browser-supplied key remains rejected * token failure is distinct from provider failure Acceptance: * AI OS gets the upstream "do not reprompt every session" outcome without weakening current local secret handling. *** ## Phase 6: Docs, Gitignore, Metadata Goal: keep documentation and repository metadata honest about what shipped. ### 6.1 Documentation Tasks: * [ ] Update Hermes docs after implementation, not before, with current shipped behavior: * model selector * context meter * deterministic commands * compact * Ministry * MoA save requirements * demo/write limitations * [ ] Mention that model benchmark data is a bundled upstream-derived snapshot, while pricing can be live OpenRouter data only in local live mode. * [ ] Keep voice docs aligned with the actual broker behavior and ownership caveats. * [ ] Update `docs/api/README_api.md` bridge tables only after endpoints ship: * expanded `GET /__hermes_models` fields * chat `model`/`provider` request fields * sanitized chat `info` SSE event * `POST /__hermes_cmd` * `POST /__hermes_moa_save` or the chosen namespaced equivalent * [ ] Do not copy upstream changelog entries directly as AI OS shipped behavior until the matching AI OS code and tests exist. Suggested docs to review: * `docs/intelligence-view.md` * `docs/api/README_api.md` * `docs/runbooks/ai-os-dream.md` only if control-plane wording changes * `docs/CONVENTIONS.md` if new bridge conventions are added * `docs/ongoing-projects/TODO.md` after the port lands ### 6.2 Gitignore and generated data Upstream reference: * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/.gitignore` Tasks: * [ ] Treat the upstream `.gitignore` change as evidence only: * upstream added `src/data/graphs/claude-os.json` * AI OS currently tracks `src/data/graphs/ai-os.json` * AI OS currently tracks `src/data/graphs/index.json` * [ ] Do not change `.gitignore` for graph files in this port unless the code introduces a new explicitly local-only graph artifact name, for example `src/data/graphs/ai-os.local.json`. * [ ] Do not ignore or remove committed `src/data/graphs/ai-os.json` unless the graph storage contract is intentionally changed and documented. * [ ] Keep `src/data/live-data.json` generated and gitignored; do not commit it. ### 6.3 Package metadata Upstream reference: * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/package.json:1-28` Tasks: * [ ] Do not remove AI OS `package.json` version just because upstream removed its package version. * [ ] Do not downgrade or blindly copy upstream dependency versions. AI OS currently has its own package identity, scripts, overrides, and validation commands. * [ ] Add `refresh:models` only if a model refresh implementation is actually ported and tested. Acceptance: * AI OS metadata remains AI OS-owned. *** ## Phase 7: Validation Plan Run focused tests as each phase lands, then run broad validation before merging. ### Focused test additions * `src/lib/__tests__/hermes-types.test.ts` * upstream and AI OS model response envelopes * model context metadata parsing * MoA preset body parsing * `scripts/lib/__tests__/hermes-provider-readiness.test.ts` or existing provider-readiness coverage * `googlegemini`/`google`/`gemini` alias behavior * `xai-oauth` and `openai-codex` OAuth/subscription labels * newly mapped env keys, including `GEMINI_API_KEY` and `GOOGLEAI_API_KEY` * `scripts/lib/__tests__/hermes-dev-bridge.test.ts` * expanded models body * configured provider detection * provider alias normalization * MoA preset discovery * safe connection CLI probe parity and MCP skip * no secrets/private paths * `scripts/lib/__tests__/hermes-admin-bridge.test.ts` * chat model/provider validation * chat heartbeat/watchdog behavior * command endpoint allowlist and sanitizer * command timeout failure * MoA save merge/backup/admin gating * `src/hooks/__tests__/use-hermes-admin.test.tsx` * command and MoA save hook methods * chat payload includes model/provider only when selected * sanitized chat `info` SSE event parsing * `src/components/hermes/chat/__tests__/hermes-chat-tab.test.tsx` * model selector * context meter * command menu * compact carryover isolation * copy reply * warning filter * `src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx` and `src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx` where behavior ownership requires coverage * environment-backed broker respawn parity * Add Ministry component tests near the new Ministry components. * Add or update control-plane guard tests for new endpoints. ### Required commands Run before the port is considered complete: ```bash bun run typecheck bun run typecheck:scripts bun run test -- scripts/lib/__tests__/hermes-admin-bridge.test.ts scripts/lib/__tests__/hermes-dev-bridge.test.ts src/lib/__tests__/hermes-types.test.ts src/hooks/__tests__/use-hermes-admin.test.tsx src/components/hermes/chat/__tests__/hermes-chat-tab.test.tsx bun run test bun run lint bash scripts/check-asset-sizes.sh bun run runtime:check-private ``` Run if UI, route splitting, or public demo output changes: ```bash bun run build bun run demo:build:pages bun run demo:scan:pages bun run budget:check ``` Run with the local app for manual verification: ```bash bun run dev ``` Manual smoke checklist: * [ ] Hermes page loads in live mode. * [ ] Hermes page loads in demo/public mode with writes disabled. * [ ] Model selector lists only configured providers when configured set is non-empty. * [ ] Google/Gemini, xAI, OpenAI subscription, OpenRouter, and MoA providers remain selectable when configured through their supported aliases. * [ ] `anthropic/claude-sonnet-5` appears in the refreshed catalog with the expected context-window fallback. * [ ] Selecting an ordinary model sends `model` and `provider` to chat bridge. * [ ] Selecting a MoA preset sends provider `moa`. * [ ] Context meter changes as draft/messages grow. * [ ] Commands menu runs `status`, `version`, `doctor`, and `insights` with redacted output. * [ ] `update` asks for confirmation and handles timeout as failure. * [ ] A Hermes response that emits output and then hangs in cleanup is treated as success, while a pre-output hang is treated as failure. * [ ] Compact creates a summary and fresh chat without cross-chat leakage. * [ ] Ministry opens, seat assignment works, max experts are enforced, and reset restores the default lineup. * [ ] Ministry save writes config only with admin gate active. * [ ] Newly saved MoA preset appears in the model selector after refresh. * [ ] Voice path does not reprompt unnecessarily when the local broker can be respawned from safe local provider config. * [ ] No browser output shows raw home paths, auth JSON paths, API keys, tokens, emails, or account IDs. *** ## Suggested Implementation Sessions The authoritative implementation sequence is the 18-session `Session Split Plan` near the top of this document. The older five-session sketch was replaced because it combined unrelated risk domains and left several decisions open. Use the top-level sessions in order unless a later planner deliberately merges or splits adjacent sessions with equivalent acceptance coverage. *** ## Risk Register | Risk | Why it matters | Mitigation | | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Raw-copying upstream route | Upstream keeps a large monolithic route, while AI OS has split bridges/components. | Translate behavior into current AI OS modules only. | | Model response envelope mismatch | Upstream `/__hermes_models` omits `ok` and uses `default`; AI OS parsers currently require `ok` and `configuredDefault`. | Return both shapes from AI OS bridge and make parsers tolerate both during the port. | | Provider alias mismatch | Upstream uses `googlegemini`, `xai-oauth`, and other provider IDs that do not exactly match current AI OS readiness aliases. | Normalize aliases before filtering and add provider-readiness tests. | | Hermes chat cleanup hangs | Upstream treats post-output idle termination as success; AI OS fixed timeout could mark a completed answer as failed. | Port two-stage watchdog and tests for pre-output vs post-output timeout behavior. | | Command output leaks private state | `hermes status`, `doctor`, and `insights` can include paths, account IDs, emails, and token-like strings. | Extend the existing sanitizer, tests with token/path/email/account fixtures, no raw output in failures. | | MoA save clobbers Hermes config | The endpoint writes local `~/.hermes/config.yaml`. | Admin gate, payload validation, backup first, merge only `moa.presets[name]`, tests with existing config. | | Copied MoA YAML breaks on model IDs | OpenRouter IDs can contain `/` and `:`, and raw string interpolation can produce invalid or ambiguous YAML. | Generate YAML with `js-yaml` or tested quoting helper. | | Update command mutates install | `hermes update --yes` can change local software and time out. | UI confirmation, admin gate, 300 second timeout, timeout returns failure, tell user to finish in terminal if needed. | | Configured-provider detection is incomplete | Picker could hide valid models or show invalid providers. | Combine default, auth, env, config providers; if none detected, show all; add tests. | | Model catalog may be stale | Upstream catalog is a 2026-06-30 snapshot. | Label static data as bundled/snapshot; do not claim live accuracy unless refresh path exists. | | Live price fetch creates unclear data provenance | Upstream fetches keyless OpenRouter pricing at runtime, while AI OS also needs demo/static safety. | Use live OpenRouter pricing only in local live mode, fail soft to bundled snapshot prices, disable live pricing in demo, and label the source in docs/UI. | | Context estimates look exact | Client token estimates are approximate. | Always display `~` labels and explanatory popover copy. | | Compact carryover leak | Upstream specifically hardened wrong-chat carryover. | Bind carryover to active chat instance and add regression tests. | | Ministry hero violates media policy | Raw upstream hero is 385,932 bytes. | Use the optimized AI OS copy at 185,156 bytes or replace it with another under-200 KB asset; do not use a media-policy exception for this port. | | Voice key handling weakens AI OS privacy | Upstream stores/reuses a browser OpenAI key; AI OS currently uses environment-backed broker config. | Preserve AI OS broker flow; avoid browser key storage unless explicitly approved. | | Public demo accidentally exposes writes | New command and save endpoints are attractive to wire broadly. | Demo mode disables writes; control-plane guard tests cover new endpoints. | *** ## Completion Criteria The port is complete when: * [ ] All actionable upstream 2.9, 2.10, and 2.10.1 Hermes changes are either implemented in AI OS or explicitly marked "not ported" with rationale. * [ ] Chat supports configured-provider model selection, MoA preset selection, context meter, command menu, compact, copy replies, thinking state, and the narrowed warning filter. * [ ] Bridge contracts include expanded models, chat model/provider overrides, command endpoint, and MoA save endpoint with tests. * [ ] Model response parsers tolerate both upstream 2.10.1 and AI OS bridge envelopes. * [ ] Provider alias normalization is tested for `googlegemini`/Google, OpenAI subscription, xAI, OpenRouter, and MoA presets. * [ ] Chat SSE handling includes the chosen heartbeat/watchdog/stderr behavior and tests the post-output cleanup-hang case. * [ ] Ministry is integrated into Pantheon and can generate/copy/save valid MoA config with admin gating. * [ ] Ministry analytics state whether pricing is live OpenRouter or bundled snapshot, and benchmark data is labeled as bundled snapshot. * [ ] `/__hermes_connections` upstream CLI probe parity is implemented safely, with TTY-unsafe MCP probing explicitly skipped. * [ ] Voice behavior matches the upstream no-reprompt outcome without weakening AI OS secret handling. * [ ] Docs describe shipped AI OS behavior only. * [ ] New assets comply with the media policy. * [ ] Required validation commands pass or have documented, bounded follow-up. * [ ] No generated private data, raw local paths, account-auth material, logs, coverage, or secret-shaped strings are committed. *** ## Direct Upstream Reference Appendix Use these upstream 2.10.1 references while implementing. ### Release notes * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/CHANGELOG.md:8-44` * V2.10.1 model picker, context meter, model catalog, sanitizer, update, override validation, compact carryover, context size, and warning filter hardening. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/CHANGELOG.md:48-98` * V2.10 Hermes chat release. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/CHANGELOG.md:101-151` * V2.9 Ministry release and voice key persistence. ### Chat frontend * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:2140-2161` * `ChatModelPick`, `HermesModelsData`, `configured`. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:2163-2185` * token formatting and client token estimator. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:2193-2221` * context window fallback table. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:2223-2234` * narrowed benign-warning filter. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:2236-2279` * provider tints and friendly labels. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:2281-2475` * context meter. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:2477-2526` * configured-provider model selector filtering. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:2723-2858` * command menu and compact menu item. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:2960-3075` * active model state, command execution, compact, slash actions. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:3798-3821` * composer toolbar wiring. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:4246-4268` * copy message button. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:4555-4575` * "Hermes is thinking" elapsed state. ### Bridge/backend * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:331-428` * `/__hermes_moa_save`. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:1103-1305` * `/__hermes_chat` model/provider override validation and argv wiring. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:1202-1206` * chat SSE heartbeat. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:1268-1285` * chat spawn environment cleanup, buffering, and terminal sizing. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:1288-1356` * two-stage chat watchdog, stderr `info` event, and post-output success. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:1920-2050` * `/__hermes_connections` provider/auth/env scan. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:2045-2084` * TTY-unsafe MCP skip and CLI-backed service probes. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:2550-2794` * `/__hermes_models` default, catalog, mixtures, configured providers. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/vite.config.ts:2796-2946` * `/__hermes_cmd`, allowlist, timeouts, redaction. ### Ministry * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:8551-8615` * MoA provider/model config generation. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:8841-8968` * Ministry prompt/config copy. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:8971-8991` * live OpenRouter pricing query. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:9735-9845` * Ministry save UI and endpoint payload. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:9905-10379` * Ministry card, data extraction, defaults, palette, council, analytics, save/copy layout. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/routes/agents.hermes.tsx:10037-10060` * live price overlay in Ministry sorting. ### Model intelligence * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/data/model-intel.json:156-162` * Claude Opus 4.8 agent benchmark fields. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/data/model-intel.json:234-240` * Claude Opus 4.7 agent benchmark fields. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/data/model-intel.json:287-312` * Claude Sonnet 4.6 lmarena and agent benchmark fields. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/data/model-intel.json:451-457` * GPT-5.5 agent benchmark fields. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/data/model-intel.json:1650-1676` * GLM 5.2 model row. ### Voice * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/components/intelligence-portal.tsx:281-317` * saved key reuse and voice engine respawn. ### Assets and styles * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/assets/logo-*.svg` * vendor logos. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/assets/ministry-hero.webp` * Ministry hero image; AI OS copy is recompressed to 520x654 and 185,156 bytes before commit. * `/home/aiwithapex/projects/claudeos/claude-os-v2.10.1/src/styles.css:413-567` * Hermes skin and Ministry animation/style additions. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_40/prd_phase_40.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.