diagrams

codex_sdk_2_prototype_summary.md

@@ -21,6 +21,27 @@ The result is a successful prototype, with one important caveat:
 
 The current transport is still bridge-based delegation, not the final event-by-event host-delegation model from the RFC.
 
+### Prototype architecture
+
+```mermaid
+flowchart LR
+    subgraph Host["Host SDK"]
+        SDK["AgentSDKv2"]
+        Bridge["Host Responses bridge"]
+        Provider["Upstream provider"]
+    end
+
+    subgraph Runtime["Runtime"]
+        AppServer["Codex app-server"]
+        Codex["Codex runtime"]
+    end
+
+    SDK --> AppServer
+    AppServer --> Codex
+    Codex --> Bridge
+    Bridge --> Provider
+```
+
 ## 2. Changes made in Codex
 
 To support the prototype, Codex needed a handful of structural changes.
@@ -56,6 +77,22 @@ In the prototype:
 
 So the host really is performing the upstream HTTP request in this prototype, but Codex still thinks it is talking to a Responses-compatible HTTP endpoint. The transport contract is still HTTP proxying, not app-server-level request delegation.
 
+```mermaid
+sequenceDiagram
+    participant SDK as "Host SDK"
+    participant Codex as "Codex runtime"
+    participant Bridge as "Host bridge"
+    participant Provider as "Model provider"
+
+    SDK->>Codex: thread/start + sdkDelegation.bridgeUrl
+    SDK->>Codex: turn/start
+    Codex->>Bridge: HTTP POST /v1/responses
+    Bridge->>Provider: HTTP POST /v1/responses + auth
+    Provider-->>Bridge: streaming response
+    Bridge-->>Codex: streaming response
+    Codex-->>SDK: app-server events + tool pause-points
+```
+
 ### Built-in tool selection and host-visible control flow
 
 Codex already had built-in tools, but the prototype needed the SDK to decide which ones are present on a thread.
@@ -185,6 +222,23 @@ That future-state is what unlocks:
 
 This is the most important architectural gap to close.
 
+```mermaid
+sequenceDiagram
+    participant SDK as "Host SDK"
+    participant AppServer as "Codex app-server"
+    participant Codex as "Codex runtime"
+    participant Provider as "Model provider"
+
+    SDK->>AppServer: thread/start
+    SDK->>AppServer: turn/start
+    AppServer->>SDK: model/request
+    SDK->>Provider: provider request + auth
+    Provider-->>SDK: streaming provider events
+    SDK-->>AppServer: model/streamEvent*
+    AppServer->>Codex: normalized turn progression
+    Codex-->>SDK: tool approvals / pending tool calls / output
+```
+
 ### Generate typed SDK protocol models
 
 The prototype still hand-rolls Python-side JSON-RPC parsing and event handling.
@@ -382,6 +436,19 @@ Deliverables:
 - load, reliability, and recovery testing
 - documentation and support model
 
+### Roadmap at a glance
+
+```mermaid
+flowchart LR
+    P1["Phase 1<br/>Architecture + protocol contracts"]
+    P2["Phase 2<br/>Full delegation transport"]
+    P3["Phase 3<br/>Host-owned rollout + resume"]
+    P4["Phase 4<br/>Capabilities + backend generalization"]
+    P5["Phase 5<br/>Multi-provider + hardening"]
+
+    P1 --> P2 --> P3 --> P4 --> P5
+```
+
 ## Final assessment
 
 This prototype successfully demonstrates that Codex can act as the execution/runtime layer for a Universal Computer-style SDK without forcing the SDK to re-implement Codex’s built-in tools in Python.