> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase10-session04-web-codex-awareness/spec.md). # Session Specification **Session ID**: `phase10-session04-web-codex-awareness` **Phase**: 10 - Codex Product Integration **Status**: Not Started **Created**: 2026-05-31 **Package**: apps/web, packages/protocol **Package Stack**: TypeScript protocol contracts, React/Vite cockpit, Zustand store, Vitest happy-dom tests, Biome checks *** ## 1. Session Overview This session makes Codex visible as first-class cockpit data in the web app. Phase 10 Sessions 01-03 already added provider-aware CLI behavior, Codex hook install/uninstall, diagnostics, and server ingest for Codex lifecycle events. The remaining gap is the browser surface: heroes, mission filters, tool views, replay, and export-adjacent privacy checks still contain Claude-centric assumptions or raw CLI labels in some places. The work stays cross-package but web-led. `packages/protocol` already owns the shared `HeroCli` vocabulary and display metadata, so this session uses that source of truth instead of creating another web-only label map. `apps/web` then renders `codex-cli` as `Codex CLI`, treats OpenAI model ids as external display data, categorizes Codex tool names, and proves that replay/export helpers keep raw prompts, paths, command previews, terminal output, transcript references, patch bodies, token-like values, and MCP arguments redacted. The expected result is a fixture-driven Codex hero and mission that appear naturally in existing cockpit surfaces: hero cards, hero detail, mission log filters/search, tool usage, leaderboard, standings, replay share, and export failure handling. No new marketing surface, hosted analytics behavior, external replay storage, provider model taxonomy, or Codex settings mutation is introduced. *** ## 2. Objectives 1. Render all shared CLI labels (`Claude Code`, `Codex CLI`, `Cursor`, `OpenCode`, `OpenClaw`, `Web`) through protocol-backed metadata instead of raw fallback values. 2. Add a restrained Codex visual treatment for hero cards and detail surfaces that fits the existing cockpit style without creating a new palette system. 3. Ensure mission filters, search, tool usage, leaderboard, standings, replay, and export-adjacent helpers handle `codex-cli`, OpenAI model ids, `apply_patch`, Bash, and `mcp__*` tool names. 4. Add focused web/protocol tests proving Codex display and privacy behavior without weakening current Claude Code coverage. *** ## 3. Prerequisites ### Required Sessions * [x] `phase10-session03-server-ingest-codex-lifecycle` - provides `codex-cli` server heroes, missions, tools, permissions, and bounded Codex lifecycle fixture coverage. * [x] `phase10-session02-codex-hook-install-uninstall-and-diagnostics` - provides safe Codex hook install/uninstall and diagnostics without exposing raw hook command bodies. * [x] `phase10-session01-cli-provider-selection-and-installer-split` - provides CLI provider selection and local settings behavior. * [x] `phase09-session01-contracts-and-naming-baseline` - provides protocol-owned `HeroCli` vocabulary and display metadata. * [x] `phase02-session03-hero-and-mission-workflow-completion` - provides the current hero/mission cockpit surfaces and filter behavior. ### Required Tools/Knowledge * Node 20+ and npm workspace dependencies. * Current protocol hero metadata in `packages/protocol/src/heroes.ts`. * Current web hero, mission, leaderboard, standings, tool usage, replay, and export helper patterns. * Existing happy-dom test harness and fixture factory style in `apps/web/tests`. * Current privacy requirements for replay links, local exports, and local-only cockpit state. ### Environment Requirements * No OpenAI, Codex, Anthropic, Claude, hosted, Cloudflare, database, or provider credentials are required. * Tests must run locally through Vitest and happy-dom without starting Vite or the local server. * Fixtures must be synthetic and must not include real prompts, raw patch bodies, terminal output, transcript paths, local home paths, tokens, API keys, URLs with secrets, or MCP argument bodies. *** ## 4. Scope ### In Scope (MVP) * Web users can see shared CLI display labels - render `Claude Code`, `Codex CLI`, `Cursor`, `OpenCode`, `OpenClaw`, and `Web` consistently in hero surfaces. * Web users can identify Codex heroes - apply a compact Codex treatment using existing cockpit chips, borders, or accents without a new palette system. * Web users can filter/search Codex missions - include CLI labels, provider labels, hero names, tool names, and `codex-cli` in mission search behavior while preserving current state, tag, and hero-scope filters. * Web users can inspect Codex tool usage - categorize `apply_patch` as file edit, Bash as terminal, and `mcp__*` as custom/MCP without exposing raw arguments. * Web users can rank Codex heroes - ensure leaderboard, standings, and efficiency views include Codex heroes through existing metric paths. * Web replay and export-adjacent helpers preserve privacy - Codex-shaped replay entries and export errors redact prompts, command previews, broad paths, transcript fields, terminal output, patch-like text, token-like values, URLs, and MCP arguments. * Protocol tests protect label vocabulary - keep shared hero CLI metadata exhaustive and user-facing labels stable. ### Out of Scope (Deferred) * New cockpit product surfaces unrelated to Codex display - *Reason: this session adapts existing cockpit surfaces only.* * Hosted analytics, external replay storage, public replay hosting, push delivery, or production-hosted validation - *Reason: Phase 10 keeps Codex support local-first and no-claim for hosted surfaces.* * Provider-specific model tier taxonomy beyond external display labels - *Reason: OpenAI model ids remain external until a provider-neutral taxonomy is scoped later.* * Codex hook installation, uninstall, trust review, server ingest, or CLI diagnostics - *Reason: Phase 10 Sessions 02-03 own those paths.* * Mutating Codex auth, provider, telemetry, model, profile, or OpenAI API settings - *Reason: Phase 10 explicitly forbids unrelated Codex config mutation.* * Raw prompt, patch body, command output, transcript, token, broad path, or MCP argument persistence - *Reason: privacy boundaries remain unchanged and must be covered by tests.* *** ## 5. Technical Approach ### Architecture Keep `packages/protocol/src/heroes.ts` as the shared source of truth for CLI vocabulary and label metadata. The web should consume protocol metadata through a small UI helper that adapts label, provider, model-tier, and visual-treatment data for React components without duplicating the protocol map. If protocol already exposes a needed label, web code should call that helper instead of switching on raw strings. In `apps/web`, add Codex awareness at existing seams rather than branching entire surfaces. Hero cards and detail drawers should swap raw `hero.cli` text for protocol-backed labels and a compact Codex chip/accent. Mission filtering should keep current ordering and state/tag behavior, but expand searchable text to include hero name, CLI label, provider label, raw CLI id, model label/id, and tool names. Tool categorization should normalize Codex tool names in the pure `toolUsage` helper so overlays, pills, and detail sections share one category decision. Replay/export privacy stays local and defensive. Replay link encoding should redact Codex snake\_case fields and suspicious nested payload names before encoding. Export helper hardening should only affect browser-visible failure text and local download metadata, not introduce a second export implementation. Tests should assert negative privacy cases directly so `codex-cli` support cannot quietly reintroduce prompt, command, path, transcript, terminal, patch, token, URL, or MCP argument leakage. ### Design Patterns * Protocol-backed display metadata: shared labels live in protocol, web adapts them for UI. * Thin React integration: pure helpers own categorization, search text, and privacy logic; components render results. * Existing visual vocabulary: Codex treatment uses current chips, borders, and accents rather than a new palette system. * Boundary-specific redaction: replay and export-adjacent helpers redact their own browser-visible data. * Fixture-driven coverage: reusable Codex fixtures keep UI tests focused without rewriting unrelated Claude tests. * Negative ownership: tests assert what is not displayed or encoded, not only what renders. ### Technology Stack * TypeScript ES modules in `packages/protocol` and `apps/web`. * React 18, Vite, Zustand, and Tailwind utility classes in `apps/web`. * Vitest with happy-dom for web component tests. * Biome for formatting and linting. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------ | -------------------------------------------------------------------------------------------- | ---------- | | `apps/web/src/lib/heroCli.ts` | Protocol-backed CLI display, Codex visual treatment, and external model helper | \~100 | | `apps/web/tests/heroCli.test.ts` | Pure helper coverage for CLI labels, provider labels, Codex treatment, and fallback behavior | \~120 | | `apps/web/tests/codexAwarenessFixtures.ts` | Sanitized Codex hero, mission, tool, replay, and export fixture builders for web tests | \~140 | ### Files to Modify | File | Changes | Est. Lines | | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------- | | `packages/protocol/tests/heroes.test.ts` | Lock all shared CLI labels and provider labels, including Codex, Cursor, OpenCode, OpenClaw, and Web | \~40 | | `apps/web/src/lib/toolUsage.ts` | Categorize `apply_patch`, Bash, and `mcp__*` names for web tool surfaces | \~50 | | `apps/web/src/components/HeroCard.tsx` | Render protocol-backed CLI labels and Codex treatment in hero cards | \~70 | | `apps/web/src/components/HeroDetailDrawer.tsx` | Render protocol-backed CLI/provider labels and external model handling in hero details | \~80 | | `apps/web/src/components/MissionLog.tsx` | Add Codex-aware search text and categorized tool pill labels without raw argument exposure | \~90 | | `apps/web/src/components/Leaderboard.tsx` | Include CLI labels in leaderboard row metadata and accessible names | \~40 | | `apps/web/src/components/FactionStandings.tsx` | Ensure standings/efficiency UI remains Codex-inclusive with no provider exclusions | \~30 | | `apps/web/src/data/seedData.ts` | Add sanitized no-server Codex hero/mission fixture data | \~90 | | `apps/web/src/lib/replayLink.ts` | Redact Codex-shaped snake\_case fields, transcript references, patch-like text, terminal output, tokens, and MCP arguments | \~70 | | `apps/web/src/lib/exportSession.ts` | Harden browser-visible export failure sanitization for Codex-shaped command/path/token text | \~40 | | `apps/web/tests/HeroCard.test.tsx` | Add Codex hero card display tests | \~70 | | `apps/web/tests/HeroDetailDrawer.test.tsx` | Add Codex detail display and external model tests | \~70 | | `apps/web/tests/MissionLogFilter.test.tsx` | Add Codex mission search/filter and tool pill tests | \~100 | | `apps/web/tests/toolUsage.test.ts` | Add `apply_patch`, Bash, and MCP categorization tests | \~70 | | `apps/web/tests/replayLink.test.ts` | Add Codex replay privacy tests | \~80 | | `apps/web/tests/exportSession.test.ts` | Add Codex export failure sanitization tests | \~50 | | `apps/web/tests/Leaderboard.test.tsx` | Add Codex leaderboard row label/ranking tests | \~50 | | `apps/web/tests/FactionStandings.test.tsx` | Add Codex standings inclusion tests | \~50 | | `apps/web/README_web.md` | Document Codex display and privacy boundaries for web surfaces | \~40 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Hero cards render `Codex CLI` and do not show raw `codex-cli` as user-facing fallback text. * [ ] Hero detail renders protocol-backed CLI/provider labels and treats OpenAI model ids as external display data. * [ ] Mission search can find Codex missions by `Codex CLI`, `codex-cli`, OpenAI provider label, hero name, model label/id, `apply_patch`, Bash, and MCP tool names. * [ ] Mission log tool pills and tool usage helpers categorize `apply_patch` as file edit, Bash as terminal, and `mcp__*` as custom/MCP. * [ ] Leaderboard, standings, and efficiency views include Codex heroes through existing metrics and do not exclude OpenAI/Codex providers. * [ ] Replay link encoding redacts Codex-shaped prompt, command, path, transcript, terminal output, patch, token, URL, and MCP argument fields. * [ ] Export failure copy redacts Codex-shaped command previews, broad paths, token-like values, and URLs. * [ ] Existing Claude Code hero, mission, tool usage, replay, export, leaderboard, and standings behavior remains stable. ### Testing Requirements * [ ] Protocol hero tests cover every shared CLI label and provider label. * [ ] Web helper tests cover CLI display, Codex treatment, external model display, and fallback behavior. * [ ] Web component tests cover Codex hero cards, hero details, mission filters, tool pills, leaderboard, and standings. * [ ] Web privacy tests cover Codex-shaped replay and export failure redaction. * [ ] Focused web/protocol Vitest suites pass. ### Non-Functional Requirements * [ ] No raw prompts, command bodies, command previews, patch bodies, terminal output, transcript paths, MCP argument bodies, token-like values, broad local paths, hosted payloads, or telemetry payloads are exposed in new fixtures, labels, replay links, or export error copy. * [ ] Codex support remains local-first and requires no external provider credentials. * [ ] Web surfaces reuse existing cockpit density, chips, focus states, and responsive behavior. * [ ] No new provider-specific model taxonomy is introduced beyond external display handling. * [ ] No hosted analytics, public replay, external storage, or Codex settings mutation behavior is added. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `git diff --check` passes. *** ## 8. Implementation Notes ### Key Considerations * The session stub lists `apps/web` and `packages/protocol`, so all task paths stay repo-root package-relative. * `packages/protocol/src/heroes.ts` already owns the shared CLI values and labels. Web work should consume this source instead of adding a second complete label map. * Current `HeroCard` and `HeroDetailDrawer` display raw `hero.cli`; these are primary fallback-label risks for Codex. * `apps/web/src/lib/toolUsage.ts` is the right shared seam for `apply_patch`, Bash, and `mcp__*` categorization so overlays and details stay aligned. * Mission filtering currently searches mission prompt, summary, and assistant text. Codex awareness should expand search context without changing state/tag/hero-scope behavior. * Seed data can include one sanitized Codex hero so no-server/manual mode visibly exercises the new display path. * Replay and export tests should prove negative privacy behavior with Codex-shaped keys and nested payloads, not only happy-path rendering. ### Potential Challenges * Duplicate label maps can drift from protocol: mitigate by importing protocol metadata and testing exhaustive CLI values. * Codex visual treatment can read like a new product palette: mitigate by using existing chips, borders, and subtle accents only. * Search expansion can accidentally expose raw assistant text or arguments: mitigate by constructing bounded searchable labels from hero/model/tool metadata and existing safe mission text. * MCP names can be user-controlled and long: mitigate with trimming, category fallback, deterministic ordering, and UI text fitting. * Replay redaction can miss snake\_case fields: mitigate with tests for `tool_name`, `terminal_output`, `transcript_path`, `mcp_arguments`, `patch`, `command_preview`, and nested payload names. * Adding Codex fixtures can weaken Claude coverage by replacing defaults: mitigate by adding Codex fixtures beside existing defaults instead of rewriting unrelated tests. ### Relevant Considerations * \[P03] **Stable docs are the current contract**: update `apps/web/README_web.md` only for source-backed Codex display and privacy boundaries. * \[P07] **Redaction is boundary-specific**: replay and export-adjacent helper tests must prove browser-bound minimization for Codex-shaped payloads. * \[P02-apps/web] **Responsive and accessibility debt**: new chips, labels, and tool pills need accessible names, focus behavior, and text fitting on mobile and desktop. * \[P09-packages/protocol+apps/hooks] **Provider-neutral hook names need alias discipline**: keep provider-neutral labels aligned with protocol-owned `HeroCli` metadata. * \[P09-apps/hooks] **Do not forward raw Codex payloads**: web fixtures must not include raw patch bodies, terminal output, transcript paths, token-like values, or MCP arguments. * \[Security] **P06-S07-HOSTED-VALIDATION**: this session is local web display only and does not create production-hosted validation claims. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Codex heroes could render raw CLI ids or misleading fallback provider labels in user-facing UI. * Search/filter changes could hide Codex missions or accidentally index sensitive raw payload fields. * Replay/export helper changes could encode command previews, transcript references, patch bodies, terminal output, token-like values, or MCP argument bodies. * New visual chips could overflow compact hero cards or mobile mission rows. * Existing Claude Code display and fixture coverage could regress while adding Codex-specific cases. *** ## 9. Testing Strategy ### Unit Tests * Protocol hero tests for all shared CLI labels and provider labels. * Web `heroCli` helper tests for `Codex CLI`, external OpenAI model display, fallback behavior, and exhaustive CLI metadata. * Web `toolUsage` tests for `apply_patch`, Bash, and `mcp__*` categorization, ordering, colors, and unknown fallback. * Replay/export helper tests for Codex-shaped snake\_case and nested privacy fields. ### Integration Tests * Hero card and hero detail happy-dom tests using a `codex-cli` hero fixture. * Mission log tests proving Codex search by CLI label/id, provider label, model label/id, and tool names while state/tag/hero-scope filters still compose. * Leaderboard and standings tests proving Codex heroes contribute to ranking metrics and visible rows. ### Manual Testing * Start the web app with no local server and confirm the sanitized Codex seed hero appears with `Codex CLI` and external model display. * Use mission search terms `Codex CLI`, `codex-cli`, `OpenAI`, `apply_patch`, `Bash`, and `mcp__` and confirm matching missions are visible. * Open hero detail, leaderboard, standings, and tool usage overlays and confirm labels fit without overlap. ### Edge Cases * `hero.cli` is `codex-cli` with an OpenAI model id unknown to any current model tier. * Mission search combines selected hero scope, state filter, tag filter, and Codex CLI/tool search terms. * MCP tool names are long, mixed-case, or empty after trimming. * Replay entries contain nested `tool_name`, `terminal_output`, `transcript_path`, `mcp_arguments`, `patch`, `command_preview`, token, URL, and path-like fields. * Export error text contains local paths, bearer strings, command previews, URLs, and JSON error envelopes. * Existing Claude Code, Cursor, OpenCode, OpenClaw, and Web labels remain stable. *** ## 10. Dependencies ### External Libraries * No new external libraries. ### Other Sessions * **Depends on**: `phase10-session03-server-ingest-codex-lifecycle`, `phase10-session02-codex-hook-install-uninstall-and-diagnostics`, `phase10-session01-cli-provider-selection-and-installer-split`, `phase09-session01-contracts-and-naming-baseline` * **Depended by**: Phase 11 Codex hardening and validation sessions *** ## Next Steps Run the implement workflow step to begin AI-led 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://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase10-session04-web-codex-awareness/spec.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.