# starstorm-ai/dsh-embedded-codex architecture

> Architecture diagram of the GitHub repository starstorm-ai/dsh-embedded-codex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/starstorm-ai/dsh-embedded-codex
- Repository: https://github.com/starstorm-ai/dsh-embedded-codex

## Overview

This package adds a Codex-mode agent to DeepSeek Harness (DSH). A Web Session selects the preset, the runtime resolves its permission mode and starts or resumes a Codex App Server thread, then projects Codex turn events into DSH session events. Codex owns model execution, native tools, sandboxing, approvals, hidden history, and compaction; DSH retains session and persistence responsibilities. The README documents compatibility providers and permission UI behavior, though their implementation details were not sampled; the graph includes those documented branches without inferring internal calls.

Main entry points: [`src/index.ts`](https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/index.ts) (Runtime registration), [`src/app-server.ts`](https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/app-server.ts) (App Server host), [`src/agent.ts`](https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/agent.ts) (Turn projection), [`src/permissions.ts`](https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/permissions.ts) (Permission resolution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and turns"]
  node_entry["Runtime registration<br/>[index.ts]"]
  node_agent["Turn projection<br/>[agent.ts]"]
  node_serverhost["App Server host<br/>[app-server.ts]"]
  node_permissions["Permission resolution<br/>[permissions.ts]"]
  node_catalog["Model catalog<br/>[catalog.ts]"]
end

subgraph group_compat["DSH integration"]
  node_presetprovider["Agent preset provider<br/>[agent-presets.ts]"]
  node_registry["Agent registry provider<br/>[agent-registry.ts]"]
  node_sessionprovider["Session controller provider"]
  node_permissionprovider["Permission presets provider"]
  node_conversationui["Conversation UI<br/>[ui-conversation.ts]"]
  node_permissionui["Permission UI"]
end

subgraph group_contracts["Protocol contracts"]
  node_protocol["Codex RPC schemas<br/>[ClientRequest.ts]"]
  node_v2contracts["Codex v2 schemas<br/>[index.ts]"]
end

node_user(("Web user"))
node_websession["DSH Web Session"]
node_codex["Codex App Server"]
node_session["DSH session events"]

node_user -->|"selects mode"| node_websession
node_websession -->|"activates runtime"| node_entry
node_entry -->|"registers runtime"| node_agent
node_entry -->|"constructs host"| node_serverhost
node_entry -->|"registers adapter"| node_catalog
node_entry -->|"resolves modes"| node_permissions
node_agent -->|"uses thread host"| node_serverhost
node_serverhost -->|"JSON-RPC requests"| node_codex
node_agent -->|"projects turn events"| node_session
node_permissions -->|"supplies policy"| node_serverhost
node_presetprovider -->|"provides preset"| node_websession
node_sessionprovider -->|"replaces controller"| node_websession
node_registry -.->|"registers preset"| node_websession
node_permissionprovider -->|"provides modes"| node_websession
node_conversationui -->|"adapts conversation UI"| node_websession
node_permissionui -->|"adapts permission UI"| node_websession
node_protocol -->|"exports v2 types"| node_v2contracts
node_serverhost -.->|"uses RPC contracts"| node_protocol
node_agent -.->|"uses turn types"| node_v2contracts

click node_entry "https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/index.ts"
click node_agent "https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/agent.ts"
click node_serverhost "https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/app-server.ts"
click node_permissions "https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/permissions.ts"
click node_catalog "https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/catalog.ts"
click node_presetprovider "https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/compat/providers/agent-presets.ts"
click node_registry "https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/compat/providers/agent-registry.ts"
click node_sessionprovider "https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/compat/providers/session-controller.ts"
click node_permissionprovider "https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/compat/providers/permission-presets.ts"
click node_conversationui "https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/compat/providers/ui-conversation.ts"
click node_permissionui "https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/compat/providers/ui-permission-presets.ts"
click node_protocol "https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/protocol/ClientRequest.ts"
click node_v2contracts "https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/protocol/v2/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_agent,node_serverhost,node_permissions,node_catalog,node_user toneBlue
class node_presetprovider,node_registry,node_sessionprovider,node_permissionprovider,node_conversationui,node_permissionui toneAmber
class node_protocol,node_v2contracts,node_codex toneMint
class node_websession,node_session toneIndigo
```

## Components

### Runtime and turns

- [Runtime registration](https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/index.ts): `src/index.ts`
- [Turn projection](https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/agent.ts): `src/agent.ts`
- [App Server host](https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/app-server.ts): `src/app-server.ts`
- [Permission resolution](https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/permissions.ts): `src/permissions.ts`
- [Model catalog](https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/catalog.ts): `src/catalog.ts`

### DSH integration

- [Agent preset provider](https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/compat/providers/agent-presets.ts): `src/compat/providers/agent-presets.ts`
- [Agent registry provider](https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/compat/providers/agent-registry.ts): `src/compat/providers/agent-registry.ts`
- [Session controller provider](https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/compat/providers/session-controller.ts): `src/compat/providers/session-controller.ts`
- [Permission presets provider](https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/compat/providers/permission-presets.ts): `src/compat/providers/permission-presets.ts`
- [Conversation UI](https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/compat/providers/ui-conversation.ts): `src/compat/providers/ui-conversation.ts`
- [Permission UI](https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/src/compat/providers/ui-permission-presets.ts): `src/compat/providers/ui-permission-presets.ts`

### Protocol contracts

- [Codex RPC schemas](https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/protocol/ClientRequest.ts): `protocol/ClientRequest.ts`
- [Codex v2 schemas](https://github.com/starstorm-ai/dsh-embedded-codex/blob/main/protocol/v2/index.ts): `protocol/v2/index.ts`

### Other components

- **Web user**
- **DSH Web Session**
- **Codex App Server**
- **DSH session events**

## Connections

- Web user → DSH Web Session: selects mode (evidence: `README.md`)
- DSH Web Session → Runtime registration: activates runtime (evidence: `README.md`)
- Runtime registration → Turn projection: registers runtime (evidence: `src/index.ts`)
- Runtime registration → App Server host: constructs host (evidence: `src/index.ts`)
- Runtime registration → Model catalog: registers adapter (evidence: `src/index.ts`)
- Runtime registration → Permission resolution: resolves modes (evidence: `src/index.ts`)
- Turn projection → App Server host: uses thread host (evidence: `src/agent.ts`)
- App Server host → Codex App Server: JSON-RPC requests (evidence: `src/app-server.ts`)
- Turn projection → DSH session events: projects turn events (evidence: `src/agent.ts`)
- Permission resolution → App Server host: supplies policy (evidence: `README.md`)
- Agent preset provider → DSH Web Session: provides preset (evidence: `README.md`)
- Session controller provider → DSH Web Session: replaces controller (evidence: `src/compat/providers/session-controller.ts`)
- Agent registry provider → DSH Web Session: registers preset
- Permission presets provider → DSH Web Session: provides modes (evidence: `README.md`)
- Conversation UI → DSH Web Session: adapts conversation UI (evidence: `README.md`)
- Permission UI → DSH Web Session: adapts permission UI (evidence: `README.md`)
- Codex RPC schemas → Codex v2 schemas: exports v2 types
- App Server host → Codex RPC schemas: uses RPC contracts
- Turn projection → Codex v2 schemas: uses turn types