> 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_16/prd_phase_16.md). # PRD Phase 16: Hermes v2.3 Port Foundation **Status**: Complete **Sessions**: 3 (initial estimate) **Estimated Duration**: 4-6 days **Source Code Roots**: `V23/` = `/home/aiwithapex/projects/claudeos/claude-os-v2.3/`; `AIOS/` = `/home/aiwithapex/projects/aios/`; diff reference = `/home/aiwithapex/projects/claudeos/diff-v1-v2.3/`. **Progress**: 3/3 sessions (100%) *** ## Overview Phase 16 lands the foundation for porting **every** feature of the v2.3 "Hermes" build into the existing aios Hermes route, without regressing aios's modular architecture, typed data layer, security gating, or test coverage. It is the first of five phases (16-20) that together complete the Hermes feature port. This Phase 16 PRD is the **master reference** for the whole port. It carries the code-reference legend, the architecture decision, the full v2.3 component inventory, the backend endpoint gap, the Write-Path Safety Contract, the complete write-operation inventory, dependencies, assets, the validation strategy, non-goals, resolved decisions, open questions, and completion criteria. Phases 17-20 reference this document for the shared contract and only add their phase-specific source-to-target detail. Phase 16 itself delivers the safety machinery and data layer before any new UI: guardrails and the architecture decision (Session 01), backend endpoint parity plus the write-safety foundation (Session 02), and the data layer with demo fixtures for every new domain (Session 03). > **Status (source):** Planned **Source build:** `claude-os-v2.3` (the "Hermes" build) -> `aios` (`AI OS`, v0.1.232) **Scope:** Bring every feature of the v2.3 Hermes system into the existing aios Hermes route, without regressing aios's modular architecture, typed data layer, security gating, or test coverage. > > **Hard requirement:** ALL write features port over -- none are deferred or dropped. Chat send, persona create/edit/delete, Pantheon install + GitHub sync, mission create/optimize/tick/clear, document delete/restore/purge, image upload, and the Obsidian bridge are all in scope. The only thing that changes versus v2.3 is how safely they are wired: every write must satisfy the Write-Path Safety Contract below. *** ## Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | ----------------------------------------------------- | --------- | ---------- | --------- | | 01 | Guardrails, Architecture Decision And Parity Baseline | Completed | \~12-16 | Yes | | 02 | Backend Endpoint Parity And Write-Safety Foundation | Completed | \~20-25 | Yes | | 03 | Data Layer And Demo Fixtures | Completed | \~16-20 | Yes | *** ## Cross-Phase Session Plan (Full Port Rollup) The full Hermes port is sequenced across five phases. Each session is one 2-4h spec (12-25 tasks). Sessions are shippable in order; the `/agents/hermes` page stays working after every session. This rollup is the high-level map for phases 16-20. | Phase | Session | Focus | Source-Code Scope | | --------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | **16 Foundation** | S01 | Guardrails, architecture decision, tab-vs-scroll IA, parity baseline | Existing `AIOS/` Hermes modules and V23 route/component inventory | | | S02 | Backend endpoint parity (5 reads + 10 writes) + write-safety foundation (`confinePath`, reuse `requirePreflight`/redaction) | `V23/vite.config.ts`, `AIOS/scripts/lib/hermes-dev-bridge.ts`, `AIOS/scripts/lib/hermes-admin-bridge.ts` | | | S03 | Data layer + demo fixtures for every new domain; type guards + tests | V23 inline payload/demo shapes and AIOS hooks/types/demo-data | | **17 Shell + Core Writes** | S01 | Visual system, cinematic shell, global status pill | `V23/src/routes/agents.hermes.tsx`, `V23/src/components/hermes-status-pill.tsx` | | | S02 | Chat tab (write: send + image upload) | V23 chat components and image-upload client/handler anchors | | | S03 | Pantheon upgrade (write: edit/delete/templates/GitHub sync) | V23 Pantheon components, templates handler, and sync handler anchors | | **18 Memory + Viz** | S01 | Memory upgrade (sensitive reads + Obsidian write) | V23 memory section and Obsidian bridge anchors | | | S02 | Mnemosyne 3D constellation (read-only, code-split) | `V23/src/components/hermes-mnemosyne.tsx` | | **19 Orchestration + Docs** | S01 | Mission Control (write: create/optimize/tick/clear) | `V23/src/components/hermes-mission-control.tsx` and mission handlers | | | S02 | Documents Gallery (write: delete/restore/purge) | `V23/src/components/hermes-documents-gallery.tsx` and document handlers | | **20 Long-Tail + Sign-off** | S01 | Connections, stats, skills, sessions, roles, activity, CLI | V23 long-tail route component anchors | | | S02 | Cleanup, dead-code removal, full parity sign-off | AIOS implementation plus V23 side-by-side parity inventory | **Sequencing rule:** Phase 16 lands the safety machinery and data layer before any new UI; every write session (Phases 17-19) is gated on its security tests (the merge gate). See the Write-Path Safety Contract and the Complete Write Operation Inventory below for the task-level detail behind each session. *** ## Source Reference Coverage Map These phase records are self-contained and point directly to source code. The table below maps each reference category to the spec location that preserves its code anchors and implementation constraints. | Source-code detail | Preserved in | | ------------------------------------------------ | ----------------------------------------------------------------------------------------------- | | `V23/` and `AIOS/` roots plus diff artifacts | Code Reference Legend in this PRD; repeated roots in phase PRDs 17-20 | | Existing AIOS Hermes architecture | Core Decision and Current State in this PRD; Phase 16 Session 01 | | V23 route/component inventory | v2.3 component inventory in this PRD; owning session stubs repeat local source anchors | | V23 Vite handler anchors and AIOS bridge targets | Backend / Bridge Endpoint Gap in this PRD; Phase 16 Sessions 02-03 | | Existing AIOS security primitives | Sensitivity And Security Model in this PRD; write-session stubs repeat local safeguards | | Required write safeguards | Write-Path Safety Contract in this PRD; Phase 16 Session 02; all write-session stubs | | Complete write operation inventory | Complete Write Operation Inventory in this PRD; owning write-session stubs | | Runtime dependency and asset references | Dependencies and Assets in this PRD; owning phase/session notes repeat local consumers | | Phase/session sequencing | Cross-phase rollup in this PRD; phase PRDs 16-20; session stubs 16.01-20.02 | | Validation and sign-off requirements | Validation Strategy in this PRD; phase success criteria and Phase 20 sign-off | | Non-goals and resolved decisions | Non-Goals and Resolved sections in this PRD; owning phase notes | | Open questions and completion criteria | Open Questions and Completion Criteria in this PRD; owning phase PRDs and session prerequisites | *** ## Code Reference Legend All file references in this phase and Phases 17-20 use these two roots (paste-able / clickable): * **`V23/`** = `/home/aiwithapex/projects/claudeos/claude-os-v2.3/` -- the source. * **`AIOS/`** = `/home/aiwithapex/projects/aios/` -- the target (this repo). * **Diff source of truth:** `/home/aiwithapex/projects/claudeos/diff-v1-v2.3/` (`full.diff`, `SUMMARY.md`, `changed-text.txt`, `added-text.txt`). `file:line` anchors are accurate as of the 2026-06-01 indexing pass; treat them as "start reading here," not exact post-edit positions. **Big correction discovered while indexing the code:** aios does **not** keep its Hermes bridge inline in `vite.config.ts`. It has already factored the bridge into two modules, wired from `AIOS/vite.config.ts:11-12`: * `AIOS/scripts/lib/hermes-dev-bridge.ts` (970 lines) -- **read** endpoints. * `AIOS/scripts/lib/hermes-admin-bridge.ts` (937 lines) -- **write/admin** endpoints, and it **already implements most of the Write-Path Safety Contract** (see that section). Several writes are already ported. This means the port is *smaller and safer* than a v2.3-monolith read implies: the safety machinery and \~6 writes already exist; we extend these modules rather than build from scratch. *** ## Core Decision (Architecture) The two Hermes implementations have **diverged in opposite directions**: * **aios** is the better *architecture*: a 16-line route delegating to `HermesReadOnlyPage`, which composes a hero + status bar + 5 tabs (Sessions / Memory / Pantheon / Skills / Admin) out of small, typed, individually-tested components. It has a real data layer (`useHermes` / `useHermesAdmin` hooks with `live` / `offline` / `endpoint-error` / `setup-required` / `demo` modes), validated types, and a deliberate security model (loopback-gated reads, token-gated sensitive reads, admin-gated writes). \~2,884 lines incl. tests. * **v2.3** is the better *feature set*: a single 7,364-line `src/routes/agents.hermes.tsx` plus four large standalone components (\~5,700 more lines) -- a full chat interface, persona editor with GitHub sync, three-layer memory + Obsidian bridge, a 3D "Mnemosyne" memory constellation, a "Mission Control" surface, a documents gallery, a global status pill, and a rich cinematic art system. Writes are baked directly into the page with little gating. **Therefore: we port v2.3's *****features***** into aios's *****architecture*****.** We do **not** copy the v2.3 monolith over. Every v2.3 feature is decomposed into aios-style modules, routed through aios's hooks/types/demo-data layer, and every write path is forced through the existing admin-token + loopback gate. The goal is **feature parity, not file parity.** *** ## Current State | Dimension | aios (target repo) | v2.3 (source) | | ---------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | Route file | `agents.hermes.tsx` -- 16 lines (delegates) | `agents.hermes.tsx` -- 7,364 lines (monolith) | | Component layout | `src/components/hermes/` -- 9 files + tests | 4 standalone `src/components/hermes-*.tsx` | | Data layer | `useHermes`, `useHermesAdmin` hooks; `hermes-types.ts`, `hermes-admin-types.ts`, `hermes-demo-data.ts`; validated, tested | `DEMO_*` consts inline in the route; `LiveIntegration` / `PersonaYaml` / `HermesMemoryData` types | | Modes | live / offline / endpoint-error / setup-required / demo | demo-mode toggle (localStorage) + live | | Security | loopback + per-run token; sensitive reads gated; writes require admin mode | writes inline, minimal gating | | Visual system | CSS classes (`hermes-hero`, `hermes-stat-tile`...), `hermes-agent.webp` | cinematic banner, `hermes-art/*`, Fraunces/Courier type, amber halos | | Tests | `hermes-sections.test.tsx`, `hermes-admin-types.test.ts`, live-data validation | none | ### aios surface today (5 tabs) `Sessions` / `Memory` / `Pantheon` / `Skills` / `Admin` -- all **read-only** projections of bridge telemetry, with a demo fallback. ### v2.3 component inventory (to be ported) All in **`V23/src/routes/agents.hermes.tsx`** unless noted. Anchors are the component declaration lines. This inventory is the authoritative map of what gets ported; each session references the subset it owns. * Page shell: `HermesPage` `:980`; route def `:599`; theme consts (`CREAM`/`BG`/`BG_GRADIENT`) `:615-621`; `HERMES_LOCAL_LOGOS` `:90`; `PANTHEON_AVATARS` `:175`; demo fixtures `DEMO_*` `:259-556`. * `HermesDemoBanner` `:1080`, `HermesDemoCTA` `:1163`, `HermesLoading` `:1198`, `RunInTerminalCard` `:7262`. * Connections: `HermesConnectionsStrip` `:1335`, `ConnectionsModeToggle` `:1476`, `ConnectionLogo` `:1523`, `ProviderLogoChip` `:1246`. * Status: `HermesStatusBar` `:1584`, `StatusChip` `:2077`, cards `VersionCard` `:1630` / `ModelCard` `:1836` / `MemoryCard` `:1751` / `ActivityCard` `:1978`. * **Chat (\~700 lines):** `HermesChat` `:2114`, `HermesChatActive` `:2141`, `ChatSidebar` `:2825`, `SessionPill` `:3010`, `ChatBubble` `:3100`, `UserAvatar` `:3144`, `HermesAvatar` `:3199`, `ChatTyping` `:3224`, `ChatEmptyState` `:3074`. *(writes -- see inventory)* * Stats: `HermesStatsSection` `:3257`, `HermesLiveStats` `:5716`, `RichStatCell` `:5896`, `LiveStatCell` `:5935`, `HermesClaudeOsBridgeCard` `:6000`, `StatTile` `:7214`. * **Pantheon:** `HermesProfileTemplates` `:3414`, `PantheonCatalog` `:3488`, `AddPersonaTile` `:3576` *(write)*, `PersonaCard` `:3975`, `PersonaEditModal` `:4084` *(write)*, `ModelDropdown` `:4544`, `SyncBadge` `:4492`, `HermesPantheonGitHubSync` `:4752` *(write)*, `GHSyncStepCard` `:4792`, `GH_SYNC_STEPS` `:4662`. * **Memory:** `HermesMemorySection` `:4921`, `MemoryThreeLayers` `:4992`, `ManuscriptPage` `:5042`, `CharCountRing` `:5202`, `ConversationHistoryStrip` `:5267`, `ProfileMemoryGrid` `:5321`, `ObsidianBridge` `:5421` *(write)*. * Skills: `HermesLiveSkills` `:6165`, `SkillTile` `:6386`, `HermesSkillsSection` `:7005`, `SectionHead` `:6521`. * Sessions: `HermesRecentSessions` `:6565`, `SessionRow` `:6691`, `PlatformBadge` `:6661`, `PlatformBadgeIcon` `:6623`. * Roles: `HermesRolesSection` `:6794`, `RoleCell` `:6830`, `ROLES` `:6743`. * Activity: `HermesActivityPanels` `:6909`, `Capability` `:6981`. * CLI: `HermesCliCheatsheet` `:7118`, `CliCategoryCell` `:7139`, `CliCommandRow` `:7162`, `CLI_CATEGORIES` `:7061`. **Standalone components** (`V23/src/components/`): * `hermes-mission-control.tsx` (2,365 lines) -- mission surface, Athena video loop, confetti. *(writes: tick `:611`, clear `:634`)* * `hermes-mnemosyne.tsx` (1,104 lines) -- 3D memory constellation, Three.js bloom, auto-orbit, view modes. *(read-only)* * `hermes-documents-gallery.tsx` (2,158 lines) -- artifact gallery over `~/Documents/Hermes/`, 5s polling. *(writes: delete `:428`, restore `:459`/`:1094`, purge `:1118`/`:1141`)* * `hermes-status-pill.tsx` (91 lines) -- global top-bar dot + "Hermes" indicator + quick link, polls `/__hermes_status`. *(read-only)* *** ## Backend / Bridge Endpoint Gap v2.3 defines its handlers inline in `V23/vite.config.ts` (handler start lines cited below). aios serves them from two extracted modules: * Reads -> `AIOS/scripts/lib/hermes-dev-bridge.ts` (register fn `:964`) * Writes -> `AIOS/scripts/lib/hermes-admin-bridge.ts` (register fn `:926`) ### Reads | Endpoint | aios status | v2.3 source | aios target | | -------------------------------------- | ----------- | ------------------------------------------- | -------------------------- | | `/__hermes_status` | done | `vite.config.ts:306` | `hermes-dev-bridge.ts:242` | | `/__hermes_models` | done | `:1847` | `hermes-dev-bridge.ts:243` | | `/__hermes_skills` | done | `:1123` | `hermes-dev-bridge.ts:244` | | `/__hermes_sessions` | done | `:2291` | `hermes-dev-bridge.ts:245` | | `/__hermes_session` | done | `:2449` | `hermes-dev-bridge.ts:246` | | `/__hermes_memory` | done | `:2126` | `hermes-dev-bridge.ts:247` | | `/__hermes_pantheon` (GET) | done | `:1510` | `hermes-dev-bridge.ts:248` | | `/__hermes_connections` | add | `:1303` | new in dev-bridge | | `/__hermes_profiles` | add | `:1231` | new in dev-bridge | | `/__hermes_pantheon_templates` | add | `:1734` | new in dev-bridge | | `/__hermes_missions` (GET) | add | `:780` | new in dev-bridge | | `/__hermes_documents` (GET/file/trash) | add | `:2832` (`/file` `:2843`, `/trash` `:3009`) | new in dev-bridge | ### Writes (all in scope -- see Safety Contract) | Endpoint | aios status | v2.3 source | aios target | | ------------------------------------ | ----------- | -------------------------------- | ---------------------------------------- | | `/__hermes_admin_status` | done | *(aios-only)* | `hermes-admin-bridge.ts:218` | | `POST /__hermes_chat` | done | `vite.config.ts:532` | `hermes-admin-bridge.ts:219,660,742` | | `POST /__hermes_pantheon/validate` | done | `:1612` | `hermes-admin-bridge.ts:220,781` | | `POST /__hermes_pantheon/install` | done | `:1554` | `hermes-admin-bridge.ts:221,816` | | `POST /__hermes_pantheon/create` | done | `:1657` | `hermes-admin-bridge.ts:222,851` | | `PUT/DELETE /__hermes_pantheon/` | done | `:1756` | `hermes-admin-bridge.ts:223,908` | | `POST /__hermes_image_upload` | add | `:454` | new in admin-bridge | | `POST /__hermes_missions/create` | add | `:952` | new in admin-bridge | | `POST /__hermes_missions/optimize` | add | `:804` | new in admin-bridge | | `POST /__hermes_missions/tick` | add | `:1054` | new in admin-bridge | | `POST /__hermes_missions/clear` | add | `:1103` | new in admin-bridge | | `POST /__hermes_pantheon_sync` | add | `:1984` (GET status) + git push | new in admin-bridge | | `PUT /__hermes_session` | not needed | client `agents.hermes.tsx:758`\* | covered by `PUT /__hermes_pantheon/` | | `DELETE /__hermes_documents?name=` | add | `:2914` | new in admin-bridge | | `POST /__hermes_documents/restore` | add | `:2952` | new in admin-bridge | | `DELETE /__hermes_documents/trash` | add | `:3049` | new in admin-bridge | | `POST /__hermes_obsidian` (write) | add | *(new -- vault write)* | new in admin-bridge | \* `agents.hermes.tsx:758` issues `PUT /__hermes_pantheon/` for persona edit; confirm whether a separate session-edit write exists or if "session edit" is purely client-side before adding the endpoint. (Resolved below: the route's `PUT` at `:758` is persona edit, not a session write -- there is no separate session-write endpoint to port.) aios already has `/__hermes_admin_status` (its token gate) which v2.3 lacks -- **keep it** and route every new write endpoint behind it. *** ## Sensitivity And Security Model (non-negotiable) aios's read-only-first + token-gated-write model is a strict superset of v2.3's safety posture and must be preserved. Every ported feature is classified: * **Read (loopback only):** connections, sessions/session detail, stats, live skills, roles, activity, CLI cheatsheet, documents *list/preview*, mission *view*, mnemosyne (derived from local files), memory *excerpts*. * **Sensitive read (loopback + token):** full memory bodies, profile grids, Obsidian vault contents. * **Write (loopback + token + admin mode):** see the full inventory below -- **all of them ship.** ### Existing aios primitives we build on (do not reinvent) These already exist -- **reuse them, do not re-implement:** * `isLoopback(req)` -- `AIOS/vite.config.ts:57`; rejects any socket whose `remoteAddress` isn't `127.0.0.1` / `::1` / `::ffff:127.0.0.1`, alongside `server.host = "127.0.0.1"`. * Per-run `REFRESH_TOKEN` (`randomBytes(32)`) -- `AIOS/vite.config.ts:42`, written to `~/.ai-os/dev-token` (mode `0600`), handed to the browser via `/__token` (`:670`), replayed as the `x-claude-os-token` header. * `requirePreflight(req, options, method, tokenRequired)` -- `AIOS/scripts/lib/hermes-admin-bridge.ts:297` -- the one call that enforces method + loopback + token (returns `403 invalid_token`). **Every write uses it.** * Path-confinement pattern -- `hermes-admin-bridge.ts:522-524` (`resolve` + `relative` + reject `..`). Generalize into a `confinePath` helper for documents/missions/uploads. * Secret-redaction regex -- `hermes-admin-bridge.ts:27` -- scrub before logging or returning command output. * Args-array spawn -- `hermes-admin-bridge.ts:696` (`/__hermes_chat`); the template for mission-optimize and git sync. * `/__hermes_admin_status` -- the admin-mode gate (v2.3 has no equivalent), `hermes-admin-bridge.ts:218`. The client mutation layer already exists too: `useHermesAdmin` (`AIOS/src/hooks/use-hermes-admin.ts:236`) holds the token and is the **only** sanctioned path for writes -- existing mutations at `:272` (validate), `:283` (install), `:294` (create) are the copy-paste templates for new ones. ### Write-Path Safety Contract (every write endpoint MUST satisfy all) This is the heart of "port all writes *safely*." No write handler merges without each of these: 1. **Loopback-gated** -- first line is `if (!isLoopback(req)) return 403`. 2. **Method-pinned** -- reject any verb other than the one intended (`if (req.method !== "POST") return next()`). 3. **Token-gated** -- require the `REFRESH_TOKEN` header; reject `401` if missing/mismatched. Demo mode never carries the token, so demo can never write. 4. **Body-bounded** -- cap request body size; reject oversized payloads before buffering (image upload especially). 5. **Path-confined** -- for any file op, `resolve()` the target and assert it `startsWith()` the intended base dir (e.g. `~/.hermes/pantheon/personas`, the Hermes documents root, the image cache). Blocks `../` traversal from `name=` / `id=` / `trashId=` params. **This is mandatory; treat v2.3 as not having done it and add it.** 6. **Command-injection-safe** -- for the two endpoints that spawn `hermes` (`/__hermes_chat`, `/__hermes_missions/optimize`): `spawn(binPath, [args])` with an **args array, never `shell: true`, never string interpolation**; resolve and verify `binPath` against the known Hermes install; enforce a timeout and an output-size cap; pass the user prompt only as a discrete argv element. 7. **Soft-delete + confirm** -- destructive ops keep v2.3's good pattern: documents delete moves to a trash dir with a `restore` path; persona/mission deletes require an explicit client confirmation step. The UI affordance is disabled (with an "admin mode required" hint) whenever the token is absent. 8. **Audited** -- log every write (endpoint, outcome, not the payload contents) so the local operator has a trail. Rule: a v2.3 feature that writes inline must be refactored so its mutation goes through `useHermesAdmin` on the client and a handler satisfying the contract above on the server. ### Complete Write Operation Inventory (all in scope) Columns: **Done?** in aios / **V23 src** (handler / client) / **AIOS target** / risk / key safeguard. Done = already ported with the contract satisfied. | # | Operation | Done? | V23 source | AIOS target | Risk | Key safeguard | | -- | ---------------------- | ----- | ----------------------------------------------------------------------- | ---------------------------------------------------- | ---------------------------- | ----------------------------------------------------------------- | | 1 | Chat send | done | `vite.config.ts:532` / client `agents.hermes.tsx:2394` | `hermes-admin-bridge.ts:660` + `use-hermes-admin.ts` | **Cmd exec** | args-array spawn `:696`, binPath verify, timeout, redaction `:27` | | 2 | Mission optimize | add | `vite.config.ts:804` | `hermes-admin-bridge.ts` (new) | **Cmd exec** | clone chat's spawn path | | 3 | Mission create | add | `vite.config.ts:952` | admin-bridge (new) | FS write | `confinePath` to missions file | | 4 | Mission tick | add | `:1054` / client `hermes-mission-control.tsx:611` | admin-bridge (new) | FS write | confined; validate goal id | | 5 | Mission clear | add | `:1103` / client `hermes-mission-control.tsx:634` | admin-bridge (new) | FS delete | confirm; confined | | 6 | Image upload | add | `vite.config.ts:454` / client `agents.hermes.tsx:2175` | admin-bridge (new) | FS write | body-size cap, content-type check, confined cache dir | | 7 | Pantheon install seeds | done | `vite.config.ts:1554` / client `agents.hermes.tsx:794` | `hermes-admin-bridge.ts:816` | FS write | confined to personas dir | | 8 | Persona create | done | `vite.config.ts:1657` / client `agents.hermes.tsx:3615` | `hermes-admin-bridge.ts:851` | FS write | schema-validate, confined | | 9 | Persona edit | done | `vite.config.ts:1756` / client `agents.hermes.tsx:758` | `hermes-admin-bridge.ts:908` | FS write | id confined `:522`, schema-validate | | 10 | Persona delete | done | `vite.config.ts:1756` / client `agents.hermes.tsx:4161` | `hermes-admin-bridge.ts:908` (DELETE `:878`) | FS delete | id confined, confirm | | 11 | Persona validate | done | `vite.config.ts:1612` | `hermes-admin-bridge.ts:781` | none (read) | still token-gated | | 12 | Pantheon GitHub sync | add | `vite.config.ts:1984` (status) + git push | admin-bridge (new) | **Net + exec** | confirm, args-array git, no shell interpolation of refs | | 13 | Document soft-delete | add | `vite.config.ts:2914` / client `hermes-documents-gallery.tsx:428` | admin-bridge (new) | FS move->trash | name confined, reversible | | 14 | Document restore | add | `vite.config.ts:2952` / client `hermes-documents-gallery.tsx:459,1094` | admin-bridge (new) | FS move | trashId confined | | 15 | Document purge | add | `vite.config.ts:3049` / client `hermes-documents-gallery.tsx:1118,1141` | admin-bridge (new) | FS delete (perm) | trashId confined, confirm | | 16 | Obsidian vault write | add | *(new -- `ObsidianBridge` client `agents.hermes.tsx:5421`)* | admin-bridge (new) | FS write outside Hermes home | explicit vault-path allow-list, confined, confirm | Already ported: **6 of 16** (chat, persona validate/install/create/edit/delete). Remaining: **10** (missions x4, image upload, GitHub sync, documents x3, Obsidian). Items 1/2/12 (command/git execution) are the **highest-risk** and get the strictest treatment + dedicated security tests. Item 16 (Obsidian) writes *outside* the Hermes home, so it needs a user-configured vault-path allow-list, not a fixed base dir. Note: the route's `PUT` at `agents.hermes.tsx:758` is **persona edit** (`/__hermes_pantheon/`), not a session write -- there is no separate session-write endpoint to port. *** ## Dependencies (runtime) Good news -- **no new runtime deps are strictly required**: | Dep | aios | v2.3 | Note | | ----------------- | ---------- | ---------- | ------------------------------------------- | | `three` | yes ^0.184 | yes ^0.184 | Mnemosyne base; same version. | | `canvas-confetti` | yes ^1.9.4 | yes ^1.9.4 | Mission Control. | | `react-markdown` | yes ^10.1 | -- | aios already ahead. | | `simple-icons` | -- | -- | v2.3 uses slug sets + CDN, not the npm pkg. | If Mnemosyne's bloom proves hard to port on raw Three.js, evaluate adding `postprocessing` / `@react-three/fiber` -- but treat that as a contained decision in its phase (Phase 18 Session 02), not an upfront install. *** ## Assets The v2.3-only Hermes assets are **already copied** into aios: `src/assets/hermes-art/` (Pantheon imagery, banner, GH connect/push, skill hero, overlay, style reference), `src/assets/hermes-art/file-types/*.webp` (all 10 Documents-Gallery file-type cards -- pdf/html/markdown/text/data/video/audio/ archive/code/other), `hermes-portrait*.png` (2), and `claude-art/mission-claude.mp4` (1) -- see the v1->v2.3 diff work. They are currently unreferenced; each port phase wires the ones it needs (Phase 19's Documents Gallery consumes the `file-types/` set directly; Phase 17's shell consumes `00-banner-wide.png`). The two v2.3 **asset-gen scripts** that *produced* the file-type art -- `scripts/gen-hermes-file-type-art.ts` and `scripts/webp-file-type-art.sh` -- are **not** ported (their output is already present); copy them only if you want regeneration parity. The dream/skills/setup assets were intentionally **not** copied (aios already has optimized `.webp` versions). In short: the dream/skills/setup assets are intentionally absent from this port. *** ## Validation Strategy (shared across Phases 16-20) * **Typecheck + lint** clean after each phase (aios's eslint/prettier/tsconfig); run `bun run typecheck`, `bun run typecheck:scripts`, lint, format, and `git diff --check`. * **Unit tests** for every new type guard, transform, and demo fixture; extend `hermes-sections.test.tsx` per new tab. * **Mode matrix** per feature: render correctly in `demo`, `live`, `setup-required`, `offline`, `endpoint-error`. * **Security tests (gating the write port):** for **every** write endpoint, assert it rejects without the token, rejects a non-loopback origin, rejects the wrong HTTP method, and rejects an oversized body. For path-confined handlers, assert a `../` traversal in `name`/`id`/`trashId` is refused. For the spawn endpoints (chat, mission optimize, GitHub sync), assert shell metacharacters in the prompt/ref reach the binary as inert argv (no shell expansion) and that a runaway process is killed by the timeout. These tests are the merge gate for each write feature -- no write ships without them. * **Manual:** drive each tab via the webapp-testing/Playwright harness; compare visual parity with v2.3 screenshots. *** ## Non-Goals * Copying the v2.3 monolith file verbatim. * Importing the format-superseded `.png`/`.jpg` assets aios already ships as `.webp`. * Weakening aios's loopback/token/admin gating to match v2.3's looser writes. * Rebranding aios back to "Claude OS / Hermes"; this stays "AI OS" with Hermes as one agent surface. *** ## Resolved (per operator direction) * **All write features are in scope** -- chat, missions (create/optimize/tick/ clear), pantheon (install/create/edit/delete/sync), session edit, documents (delete/restore/purge), image upload, and the Obsidian bridge all ship. Nothing is deferred. Each goes through the Write-Path Safety Contract. * **Mission Control is full write/orchestration** (not read-only telemetry). * **Obsidian bridge is in scope** for v1, with the vault-path allow-list safeguard (inventory item 16). * **Session "edit" is persona edit:** the route's `PUT` at `agents.hermes.tsx:758` is `/__hermes_pantheon/`; there is no separate session-write endpoint to port. *** ## Open Questions (carried to the owning phase) 1. **IA (Phase 16 Session 01):** new top-level tabs vs. nested sub-tabs vs. long-scroll for the \~12 added surfaces? (Recommendation: top-level tabs -- keep the Tabs shell, add new tabs `Chat`, `Mission`, `Documents`, `Mnemosyne`, `Connections`.) 2. **Mnemosyne bloom (Phase 18 Session 02):** acceptable on raw `three`, or do we add `postprocessing`/`@react-three/fiber`? 3. **Documents root (Phase 19 Session 02):** v2.3 hardcodes `~/Documents/Hermes/` -- make it configurable via setup/config, or keep the fixed path for v1? 4. **GitHub sync auth (Phase 17 Session 03):** does the Pantheon<->GitHub sync rely on the user's ambient `git`/`gh` credentials, or should aios manage a scoped token? *** ## Completion Criteria (whole port, verified in Phase 20) * Every v2.3 Hermes feature listed in the inventory is reachable from aios's `/agents/hermes` (or the global status pill), rendered through aios modules. * All 15 missing endpoints exist (5 reads + 10 writes), loopback-gated, with writes token+admin-gated. (Reads: connections, profiles, pantheon\_templates, missions GET, documents GET/file/trash. Writes: missions create/optimize/tick/clear, image upload, GitHub sync, documents delete/restore/purge, Obsidian.) * `AIOS/README.md` documents the aios Hermes surface + `~/.hermes/` layout (parity with v2.3's README sections), and `AIOS/docs/CHANGELOG.md` records the port. * Demo mode renders the entire page with no bridge running. * Typecheck, lint, and the expanded test suite pass. * No write path bypasses `useHermesAdmin`; no sensitive read bypasses the token. * Side-by-side visual parity with v2.3 confirmed for each surface. *** ## Objectives (Phase 16) 1. Confirm the architecture decision (port into modules, not the monolith) and the tab-vs-scroll IA, and snapshot the current `hermes-sections.test.tsx` as the parity baseline. 2. Generalize the existing path-confinement into a reusable `confinePath` helper and add the 5 missing read endpoints plus the 10 missing write endpoints behind `requirePreflight` + `confinePath`, satisfying the Write-Path Safety Contract. 3. Extend `use-hermes.ts` and `use-hermes-admin.ts` with queries/mutations for the new endpoints and port v2.3 payload shapes into `hermes-types.ts` / `hermes-admin-types.ts` with validators and tests. 4. Extend `hermes-demo-data.ts` with demo fixtures for every new domain so demo mode renders the full page with zero bridge, and unit-test each new type guard/transform. *** ## Prerequisites * Phase 15 completed. * Existing Phase 03-04 Hermes read-only foundation, product surface, and admin bridge are available and remain the source of truth. * `AIOS/scripts/lib/hermes-dev-bridge.ts`, `AIOS/scripts/lib/hermes-admin-bridge.ts`, `AIOS/src/hooks/use-hermes.ts`, `AIOS/src/hooks/use-hermes-admin.ts`, `AIOS/src/lib/hermes-types.ts`, `AIOS/src/lib/hermes-admin-types.ts`, and `AIOS/src/lib/hermes-demo-data.ts` are the extension points. *** ## Technical Considerations ### Architecture Port v2.3 *features* into aios's *architecture*: decompose each v2.3 component into aios-style modules under `AIOS/src/components/hermes/`, route through the existing hooks/types/demo-data layer, and force every write through the existing admin-token + loopback gate. Build/confirm `confinePath`, `requirePreflight`, and redaction reuse first; every write endpoint depends on them. ### Technologies * Bun scripts and Vite `configureServer` dev middleware (dev-only bridges). * TypeScript bridge modules under `AIOS/scripts/lib/`. * React Query hooks (`use-hermes.ts`, `use-hermes-admin.ts`). * Zod-style validated types in `AIOS/src/lib/hermes-types.ts` and `hermes-admin-types.ts`. ### Risks * **New write endpoints widen the attack surface**: Mitigation -- land the Write-Path Safety Contract helpers and security tests in Session 02 before any UI consumes them (Phases 17-19). * **Payload shape drift between v2.3 and aios types**: Mitigation -- port v2.3 payload shapes into typed validators with tests mirroring `validate-live-data.test.ts`. * **Demo mode regressions when new domains are added**: Mitigation -- add demo fixtures for every new domain in Session 03 and assert the full page renders with no bridge. ### Relevant Considerations * \[P04] **Hermes bridge guardrails must stay intact**: Sensitive reads and opt-in writes depend on loopback + token checks, no-clobber path safety, and disabled-by-default admin mode. Every new endpoint preserves this. * \[P01] **Bundle budget tight on 3D vendor chunks**: relevant when Mnemosyne lands (Phase 18); keep new foundation code lean and code-split heavy surfaces. * \[P01] **Old `claude-os-*` naming remains a compatibility contract**: the dev token header stays `x-claude-os-token`; do not rename without aliases. *** ## Success Criteria Phase complete when: * [ ] All 3 sessions completed and validated. * [ ] The architecture decision and IA are recorded; the parity baseline test snapshot exists. * [ ] `confinePath` exists and is reused; all 5 read and 10 write endpoints are registered, each write satisfying the Write-Path Safety Contract with passing security tests. * [ ] `use-hermes.ts` / `use-hermes-admin.ts` expose queries/mutations for the new endpoints; v2.3 payload shapes are typed and validated with tests. * [ ] `hermes-demo-data.ts` renders the full expanded page in demo mode with no bridge running. * [ ] Typecheck, lint, and the expanded test suite pass. *** ## Dependencies ### Depends On * Phase 03: Hermes Read-Only Foundation * Phase 04: Hermes Product Surface And Admin Gate ### Enables * Phase 17: Hermes Shell And Core Writes * Phase 18: Hermes Memory And Visualization * Phase 19: Hermes Orchestration And Documents * Phase 20: Hermes Long-Tail And Parity Sign-off --- # 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_16/prd_phase_16.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.