> 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/sessions/phase40-session02-models-and-provider-readiness/spec.md).

# Session Specification

**Session ID**: `phase40-session02-models-and-provider-readiness` **Phase**: 40 - Claude OS v2.10.1 Semantic Port **Status**: Not Started **Created**: 2026-07-02 **Base Commit**: decf476f8dfe08c740c32e57cc12f2cfbaed5097

***

## 1. Session Overview

This session expands the Hermes public model contract so AI OS can accept the upstream Claude OS v2.10.1 `/__hermes_models` shape without breaking current AI OS consumers. It keeps `ok` and `configuredDefault` compatibility while adding the upstream-compatible `default`, `catalog`, `mixtures`, and `configured` fields that later chat selector, context meter, catalog, and Ministry work will depend on.

The session is next because Session 01 completed the Phase 40 invariant and classification baseline, and Session 02 is the first executable bridge contract dependency for Sessions 04, 08, 09, and 11. The work stays on the public read path and provider-readiness helpers; UI selector wiring, chat payload overrides, live catalog refresh, command execution, and MoA save writes remain later sessions.

Implementation must preserve AI OS local-control and privacy boundaries. Model and provider readiness output may expose safe provider labels, model IDs, contexts, preset names, and configured-provider slugs, but it must not expose raw Hermes config content, home paths, auth JSON, environment values, tokens, or private file paths.

***

## 2. Objectives

1. Extend Hermes model response types and parser behavior for both AI OS `ok/configuredDefault` bodies and upstream no-`ok` `default/catalog/mixtures/configured` bodies.
2. Expand the public Hermes read bridge to return `configuredDefault`, upstream-compatible `default`, `catalog`, `mixtures`, and `configured` while keeping demo and existing hook consumers stable.
3. Add provider readiness aliases, labels, OAuth/subscription classification, environment key detection, and configured-provider derivation without hiding valid Google/Gemini, xAI, OpenRouter, or MoA paths.
4. Add focused tests for model parsing, configured-provider detection, alias matching, MoA preset discovery, malformed config fail-soft behavior, and no secret or private path leakage.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase40-session01-baseline-and-port-invariants` - Provides `INV-001` through `INV-015`, `DEC-011`, owner mapping `MAP-001` and `MAP-002`, and classifications `CLS-001` and `CLS-002`.

### Required Tools Or Knowledge

* Bun 1.3.14 package/runtime baseline.
* Existing `js-yaml` dependency already used by Hermes admin code.
* Phase 40 PRD source sections for `/__hermes_models`, provider aliases, configured-provider filtering, and MoA preset discovery.
* Current Hermes owners: `scripts/lib/hermes-dev-bridge.ts`, `scripts/lib/hermes-provider-readiness.ts`, `src/lib/hermes-types.ts`, `src/lib/hermes-demo-data.ts`, `src/hooks/use-hermes.ts`, and focused test files.

### Environment Requirements

* Local checkout with dependencies installed or installable through `bun install`.
* No credentials, live provider access, third-party dashboards, or local Hermes installation required; tests should use temp fixtures.
* If local Hermes config files exist, implementation must treat them as private inputs and expose only safe derived fields.

***

## 4. Scope

### In Scope (MVP)

* AI OS public Hermes readers return a model body that preserves current `ok: true`, `configuredDefault`, and `catalog` behavior while also exposing upstream-compatible `default`, `mixtures`, and `configured` fields.
* Browser parser consumers accept current AI OS bodies, expanded AI OS bodies, upstream no-`ok` bodies, and demo fixtures with optional context metadata.
* Hermes config reads discover safe MoA preset summaries from `~/.hermes/config.yaml` using `js-yaml`, fail softly for missing or malformed config, and never include raw YAML, private paths, or secret-shaped values in browser output.
* Provider readiness maps upstream and retained AI OS provider IDs, including `googlegemini`, `google`, `gemini`, `xai`, `xai-oauth`, `openai-codex`, `deepseek`, `sakana`, `minimax`, `nvidia`, and OpenRouter-compatible IDs.
* Configured providers are derived from the default provider, Hermes auth JSON provider keys, Hermes `.env` key presence, config `providers:` entries, and current readiness classification.
* MoA presets remain available as safe mixture rows even when configured provider filtering would narrow catalog groups.

### Out Of Scope (Deferred)

* Chat payload override wiring - Reason: Session 04 owns model/provider argv and admin chat parsing.
* UI model selector and context meter components - Reason: Session 11 owns the product-facing selector and meter surfaces after the model body is stable.
* Full model catalog refresh and Claude Sonnet 5 catalog closeout - Reason: Session 08 owns catalog/context metadata refresh.
* Live OpenRouter pricing and Ministry analytics - Reason: Session 09 owns pricing provenance and local-live fetch behavior.
* MoA config save endpoint and write UX - Reason: Sessions 06, 14, and 15 own admin-gated local writes and Ministry builder UX.

***

## 5. Technical Approach

### Architecture

Keep the public model contract in the existing split Hermes owners. The local read bridge remains in `scripts/lib/hermes-dev-bridge.ts`; provider alias, label, key, and OAuth classification stays in `scripts/lib/hermes-provider-readiness.ts`; browser-facing types and parsers stay in `src/lib/hermes-types.ts`; demo fixtures stay in `src/lib/hermes-demo-data.ts`; and hook behavior stays in `src/hooks/use-hermes.ts`.

The bridge should derive safe summaries from local config and auth files, then return normalized slugs and display-safe model metadata. Parser code should be tolerant at the boundary but normalize into one stable client shape. Tests should prove compatibility with old AI OS bodies, expanded AI OS bodies, upstream-style no-`ok` bodies, malformed config, missing config, and filtered provider scenarios.

### Design Patterns

* Compatibility parser: Accept old and upstream bodies, normalize to one AI OS client shape.
* Local-only safe projection: Derive provider and preset summaries without exposing raw config, paths, keys, or file contents.
* Alias-first filtering: Normalize provider aliases before configured-provider filtering so valid provider groups are not hidden.
* Fail-soft config read: Missing or malformed Hermes config yields empty mixtures or configured providers, not endpoint failure.
* Existing owner mapping: Implement in current AI OS split files, not upstream monolithic route or Vite middleware.

***

## 6. Deliverables

### Files To Create

| File | Purpose                                        | Est. Lines |
| ---- | ---------------------------------------------- | ---------- |
| None | No new source files expected for this session. | 0          |

### Files To Modify

| File                                              | Changes                                                                                                                 | Est. Lines |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------- |
| `src/lib/hermes-types.ts`                         | Extend model types and parser compatibility for expanded AI OS and upstream no-`ok` bodies.                             | \~110      |
| `src/lib/hermes-demo-data.ts`                     | Update demo model fixtures with safe expanded fields.                                                                   | \~25       |
| `src/hooks/use-hermes.ts`                         | Preserve hook empty-state behavior against expanded model shapes if parser normalization requires it.                   | \~15       |
| `scripts/lib/hermes-dev-bridge.ts`                | Return expanded model body, read safe MoA presets, derive configured providers, and keep read route fail-soft.          | \~220      |
| `scripts/lib/hermes-provider-readiness.ts`        | Add aliases, labels, key readiness, OAuth/subscription IDs, and normalization helpers.                                  | \~120      |
| `scripts/lib/__tests__/hermes-dev-bridge.test.ts` | Add bridge tests for configured detection, alias filtering, MoA discovery, malformed config, and leakage safety.        | \~180      |
| `src/lib/__tests__/hermes-types.test.ts`          | Add parser tests for old AI OS, expanded AI OS, upstream no-`ok`, optional context, mixtures, and configured providers. | \~120      |
| `src/hooks/__tests__/use-hermes.test.tsx`         | Update hook fixture expectations if expanded demo/model fields affect query data.                                       | \~40       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `parseHermesModelsResponse` accepts old AI OS bodies, expanded AI OS bodies, upstream no-`ok` bodies, and demo fixtures.
* [ ] `/__hermes_models` returns `ok`, `configuredDefault`, `default`, `catalog`, `mixtures`, and `configured` without exposing raw local config, auth JSON, environment values, home paths, or secret-shaped strings.
* [ ] Provider aliases normalize before filtering so Google/Gemini variants, xAI variants, OpenRouter, MiniMax, NVIDIA, DeepSeek, Sakana, and retained AI OS aliases behave predictably.
* [ ] MoA presets are discoverable as safe mixture rows and remain available when configured-provider filtering narrows catalog providers.

### Testing Requirements

* [ ] Unit tests cover model parser compatibility and invalid-shape failures.
* [ ] Bridge tests cover configured provider derivation from default provider, auth JSON keys, Hermes `.env`, config providers, readiness classification, missing config, and malformed config.
* [ ] Provider readiness tests cover aliases, labels, OAuth/subscription IDs, and existing `MINIMAX_API_KEY` and `NVIDIA_API_KEY` behavior.
* [ ] Leakage tests verify browser output does not include raw config content, private paths, env values, auth JSON payloads, or token-shaped strings.
* [ ] Focused checks pass: `bunx vitest run scripts/lib/__tests__/hermes-dev-bridge.test.ts src/lib/__tests__/hermes-types.test.ts src/hooks/__tests__/use-hermes.test.tsx`.
* [ ] `bun run typecheck` and `bun run typecheck:scripts` pass.

### Non-Functional Requirements

* [ ] Public/demo mode remains fixture-backed and does not read local Hermes state or configured-provider summaries.
* [ ] Local bridge route behavior stays GET-only for this public read endpoint and does not introduce admin writes, shell execution, network fetches, or new dependencies.
* [ ] Model and provider lists stay bounded, deterministic, and display-safe.
* [ ] Session changes follow AI OS naming and Phase 40 semantic-port boundaries.

### Quality Gates

* [ ] All files ASCII-encoded
* [ ] Unix LF line endings
* [ ] Code follows project conventions
* [ ] No upstream monolithic route or Vite middleware file copied

***

## 8. Implementation Notes

### Working Assumptions

* `js-yaml` remains the correct parser for Hermes config reads: the Phase 40 stub states this assumption, `package.json` already carries `js-yaml`, and `scripts/lib/hermes-admin-bridge.ts` already imports structured YAML helpers. Planning can proceed without dependency churn.
* Session 02 can update demo fixture shape without changing demo behavior: `src/lib/hermes-demo-data.ts` already owns `HERMES_DEMO_MODELS`, and `DEC-006` requires demo data to remain committed, read-only, and free of local configured-provider summaries.

### Conflict Resolutions

* Session 02 stub includes model contract and provider readiness, while Session 08 also mentions catalog/context metadata. The chosen interpretation is that Session 02 adds only fields and safe baseline rows needed to prove contract compatibility; Session 08 owns the broader catalog/context refresh, including explicit Claude Sonnet 5 catalog closeout.

### Key Considerations

* `INV-001` and `INV-002`: Translate upstream behavior into current AI OS owners; keep `src/routes/agents.hermes.tsx` thin.
* `INV-007` and `DEC-006`: Public/demo surfaces remain fixture-backed and must not read local configured-provider summaries.
* `INV-009`: Browser-facing bridge output must redact or avoid private paths, credentials, account IDs, and token-shaped values.
* `INV-015`: Treat upstream model data as a 2026-06-30 snapshot unless a later verified live refresh path is implemented.
* `DEC-011`: Support both AI OS `ok/configuredDefault` and upstream `default/catalog/mixtures/configured` model body shapes.

### Potential Challenges

* Provider alias drift: Mitigate by adding dedicated normalization tests before filtered configured-provider behavior.
* Over-redaction or under-redaction in safe summaries: Avoid raw text emission entirely for config/auth files and assert output fields against known private fixture values.
* Malformed YAML: Keep parse failures local to mixtures/configured derivation and return a valid model body.
* Hook compatibility: Normalize parser output so hook and route consumers do not need to branch on old versus upstream response shapes.

### Relevant Considerations

* \[P38] **Upstream ports are semantic, not wholesale**: Map hunks to AI OS module owners, record superseded or skipped upstream paths, and keep 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.
* \[P00] **Stack conventions**: Bun, Vite 8, TanStack Start, React 19, Radix UI, and Cloudflare Worker compatibility remain baseline constraints.
* \[P21] **Claude OAuth material stays script-only**: Token-bearing fields, bearer headers, and credential-shaped strings must stay out of browser state, logs, and generated data.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Browser contract drift between old AI OS responses, expanded AI OS responses, upstream-style responses, and demo fixtures.
* Private local config or auth data leaking through model/provider summaries.
* Configured-provider filtering hiding valid catalog groups or MoA presets.

***

## 9. Testing Strategy

### Unit Tests

* Add parser tests in `src/lib/__tests__/hermes-types.test.ts` for old AI OS, expanded AI OS, upstream no-`ok`, invalid catalog, optional context, mixtures, and configured-provider arrays.
* Add provider readiness assertions in `scripts/lib/__tests__/hermes-dev-bridge.test.ts` or existing readiness-adjacent tests for aliases, labels, OAuth IDs, and key detection.

### Integration Tests

* Extend `scripts/lib/__tests__/hermes-dev-bridge.test.ts` with temp Hermes homes containing `config.yaml`, `.env`, and auth JSON fixtures to verify `/__hermes_models` output.
* Verify malformed and missing config files return valid expanded model bodies with empty or fallback fields rather than errors.

### Runtime Verification

* Run focused tests: `bunx vitest run scripts/lib/__tests__/hermes-dev-bridge.test.ts src/lib/__tests__/hermes-types.test.ts src/hooks/__tests__/use-hermes.test.tsx`.
* Run TypeScript gates: `bun run typecheck` and `bun run typecheck:scripts`.
* Run ASCII/LF checks over touched source, test, and session artifact files.

### Edge Cases

* Upstream no-`ok` body has `default` but no `configuredDefault`.
* Current AI OS body has `configuredDefault` but no `default`.
* Catalog provider IDs use `google`, `gemini`, or `googlegemini`.
* Configured providers are empty, so all catalog groups remain visible.
* Configured providers are non-empty, so configured groups are filtered while MoA mixtures remain available.
* Hermes `config.yaml` is missing, malformed, or contains provider/model names with slash, colon, quote, or whitespace characters.
* Hermes `.env` includes placeholder values; only key presence and key names may be exposed.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase40-session01-baseline-and-port-invariants`.
* Depended by: `phase40-session04-chat-overrides-and-runtime`, `phase40-session08-catalog-and-context-metadata`, `phase40-session09-model-intelligence-and-pricing`, and `phase40-session11-chat-model-selector-and-context-meter`.

***

## Next Steps

Run the `implement` workflow step to begin implementation.


---

# 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/sessions/phase40-session02-models-and-provider-readiness/spec.md?ask=<question>&goal=<endgoal>
```

`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.