[Design] How should Chat2DB integrate Codex and ChatGPT subscription access?

[openai0229]

Context

PR #2371 demonstrates that Chat2DB Community can package and supervise the official Codex app-server, authenticate with a ChatGPT account, discover available models, stream Codex turns, and expose Chat2DB database tools through MCP.

This is a valuable product direction and a substantial feasibility effort. Thank you @HaijieChen for exploring authentication safety, packaging, model discovery, tool execution, and recovery concerns in depth.

Before choosing a production architecture, we should make the product and ownership boundaries explicit. This Discussion is intentionally question-driven. It does not assume that the current pull-request structure should be retained, that Codex must be modeled as a separate provider, or that any particular persistence and packaging approach is required.

Product goal to discuss

A Chat2DB Community desktop user may want to:

1. Connect a supported ChatGPT/Codex subscription account without supplying an OpenAI API key.
2. Use models and reasoning options made available through the Codex app-server from the Chat2DB AI experience.
3. Ask questions in Chat2DB and allow explicitly permitted access to Chat2DB database capabilities.
4. Sign out and recover from failures without exposing credentials or silently repeating database writes.

The related Feature Issue will define the user problem and observable outcome. This Discussion is only for the unresolved design.

Open questions

1. What is the product concept?

• Should users see Codex as a separate AI provider?
• Should ChatGPT subscription be an authentication or access mode under an existing provider?
• Should it appear as an Agent integration rather than a model provider?
• What terminology will make the quota, runtime, and model ownership clear to users?
• Which existing Chat2DB AI configuration concepts can represent it without special cases?

2. Which runtime owns the agent loop?

The Codex app-server exposes thread and turn APIs rather than a raw model-completion API.

• Does Codex own the complete inner agent turn?
• Does Chat2DB own an outer orchestration layer?
• Which component owns conversation context, retries, cancellation, stop conditions, and history?
• Can Chat2DB treat Codex as a provider adapter, or is it more accurately a hosted sub-agent?
• How should the product communicate that usage consumes the connected ChatGPT/Codex subscription?

3. What should the routing boundary be?

• Should the existing AI stream service select among provider implementations?
• Should a new provider-neutral router be introduced?
• Is a dedicated subscription route appropriate?
• Which request fields are stable product concepts, and which are implementation details?
• Where should app-server events be normalized into the existing Chat2DB stream contract?

4. How should authentication and account state work?

• Should Chat2DB initiate and display app-server login, logout, and reauthentication?
• Which account facts may Chat2DB persist?
• Is OS Keyring mandatory on every supported platform?
• Can an existing Codex login be reused, or should Chat2DB use an isolated account state?
• How should multiple Chat2DB profiles or operating-system users be handled?
• What errors and rate-limit information can be shown without exposing credentials?

5. How should models and configuration be represented?

• Are app-server-discovered models part of the existing model catalog?
• How are provider identity, model identity, reasoning capability, and availability represented?
• Where do global and conversation-scoped model preferences live?
• What is the single source of truth for model configuration?
• How are stale model snapshots handled?
• How should existing chat history identify the model and runtime that produced a message?

6. How should Codex app-server be delivered?

• Should the runtime be downloaded only when a user first enables the Codex provider?
• How should Chat2DB pin a compatible runtime version without accepting arbitrary installed Codex versions?
• Should downloads use an official source, a Chat2DB CDN mirror, or both?
• How are the runtime manifest, source provenance, checksum, signature, license, platform, and architecture verified?
• Which runtime files may be shared by profiles, and which account and thread state must remain profile-isolated?
• How should download progress, cancellation, retry, proxy failures, disk limits, offline reuse, removal, and upgrades work?
• How are app-server initialization, required-capability checks, health checks, restart, and shutdown handled?
• What support matrix applies to macOS, Windows, Linux Desktop, Web, Docker, headless, and CLI environments?

7. What database capabilities should Codex receive?

• Should Chat2DB define a provider-neutral database tool contract and expose it to Codex through an MCP adapter?
• What is the minimum metadata, schema, explain, and query tool set?
• Which operations are read-only by definition?
• Should DML and DDL be disabled by default and require explicit per-operation confirmation?
• How are datasource, database, schema, user-permission, and SQL-operation scopes enforced?
• What schema, SQL, query results, and metadata may be sent to Codex?
• How are cancellation, timeout, output limits, result truncation, and log redaction handled?
• If a write may have completed before a disconnect, how is an unknown outcome represented without blindly retrying it?

8. How should state ownership remain within existing Chat2DB domains?

• Which domain owns provider connection metadata, model preferences, conversation-to-thread mappings, approvals, and database execution results?
• Which thread and model-context state must remain exclusively owned by the Codex app-server?
• Which account, model, capability, and rate-limit data should remain live projections rather than durable product state?
• How should each domain use existing Chat2DB storage abstractions without introducing a cross-domain state authority?
• How are stale mappings and runtime state reconciled after restart or logout?

9. What are the release gates?

• Which unit, integration, download, runtime-contract, database-tool, and live-account tests are required?
• Which platforms need signed installer and downloaded-runtime validation?
• What non-disclosure checks are required for logs, errors, renderer state, account flows, and transport?
• Which download interruption, checksum failure, protocol mismatch, app-server crash, and restart scenarios must pass?
• Which database permission, confirmation, timeout, truncation, cancellation, and unknown-outcome scenarios must pass?
• Should the feature remain default-off until each platform independently passes?
• What disablement and rollback behavior is required?

Evidence to bring into the discussion

Useful input includes:

• Provider and runtime ownership diagrams.
• Alternative request and streaming contracts.
• Storage ownership and retention tables.
• Tool permission and recovery state machines.
• Packaging and platform-support matrices.
• Small prototypes that compare alternative integration boundaries.
• Test results from PR feat(subscription-ai): Community ChatGPT subscription-backed AI (gated) #2371 that validate reusable behavior independently of its current architecture.

Tracking

• Tracking Issue: Use ChatGPT/Codex subscription access in Chat2DB Community #2413
• Feasibility implementation: feat(subscription-ai): Community ChatGPT subscription-backed AI (gated) #2371 by @HaijieChen

The Issue owns the user problem, scope, priority, acceptance criteria, and implementation tracking. This Discussion owns unresolved design questions, alternatives, and decision records.

[openai0229]

Design decision log

This comment will be updated as each question in this Discussion is resolved.

1. Product concept

Decision:

• Codex will be a separate, first-class CODEX provider. It will not be modeled as OPENAI + SUBSCRIPTION, and it will not appear as a generic custom-model entry.
• The user-facing name is Codex, managed in the existing AI model configuration page.
• The provider supports ChatGPT/Codex subscription authentication only. It does not accept an OpenAI API key.
• The account connection flow starts inside Chat2DB. Users should not need to run codex login manually.
• Available models are discovered dynamically through the Codex app-server. Chat2DB does not maintain a hard-coded Codex model list and does not modify the user global Codex configuration.
• Chat2DB stores its own Codex provider default model and allows a conversation-level override. Both selections are limited to models currently reported by the app-server.
• The UI must state explicitly that usage consumes the connected ChatGPT/Codex subscription quota.
• Existing Chat2DB concepts remain the product model: provider, provider connection state, model catalog, provider default model, and conversation-level model selection. The provider-specific difference is that Codex uses an account connection control instead of API-key fields.
• Subscription access is a property of the Codex provider, not a separate top-level Subscription AI product concept.

2. Runtime ownership

Decision:

• The Codex app-server owns the complete inner agent turn: model invocation, reasoning and tool-selection loops, internal iteration, and natural completion.
• Chat2DB owns only a thin outer host-orchestration layer and the product security boundary. It checks provider readiness, selects the Chat2DB-scoped model, creates or resumes the mapped Codex thread, limits datasource and tool access, enforces permissions and confirmations, normalizes streamed events, and presents status in the UI.
• Chat2DB persists the mapping from a Chat2DB conversation ID to a Codex thread ID. The Codex thread is the source of truth for model-visible runtime context; Chat2DB conversation and message history are the source of truth for the user-visible product record. Chat2DB does not rebuild every Codex turn by replaying its visible message history.
• Codex owns retries inside an accepted agent turn. Chat2DB may retry read-only status requests, but it must not blindly resend turn/start after a timeout or disconnect. It first reconciles the existing thread or turn state; an unrecoverable ambiguous outcome is shown as unknown and requires an explicit user retry.
• The stop control belongs to Chat2DB, which forwards it through turn/interrupt. Codex owns the actual termination, and Chat2DB waits for the terminal interrupted state. Cancellation does not imply that an already-submitted database operation was rolled back.
• Codex owns semantic stop conditions such as natural completion and internal iteration limits. Chat2DB enforces only host-level hard boundaries such as user cancellation, application shutdown, absolute timeout, provider loss, and security-policy rejection. A single database-tool timeout is returned to Codex as a tool error so Codex can decide whether to continue.
• The product concept remains Codex Provider. The implementation boundary is a Codex Agent Runtime Adapter, not a hosted sub-agent and not a raw completion adapter.
• User-facing quota text should say: Uses your connected ChatGPT account and counts against your ChatGPT/Codex subscription limits. The Codex app-server implementation name belongs in provider details and diagnostics, not the primary usage explanation.

3. Routing boundary

Decision:

• All providers continue to use the existing POST /api/v3/ai/chat/stream product endpoint. There is no Codex-specific or subscription-specific controller route.
• A provider-neutral AiChatStreamRouter is introduced at the stream-service boundary. It resolves the selected model configuration and dispatches by provider.
• Existing completion providers are handled by a CompletionChatStreamAdapter, which retains the current AiModelFactory path for OpenAI, Claude, Gemini, and other ordinary completion clients.
• CODEX is handled by a separate CodexAgentRuntimeAdapter. Codex is not added as a special branch inside AiModelFactory, because a Thread/Turn agent runtime does not implement the raw completion-client contract.
• Routing is based on provider identity, not on subscription state, access type, or a separate Subscription AI route kind.
• The stable public chat request contains product concepts such as input, session ID, model-config ID, an optional conversation-scoped model override, attachments, datasource scope, question type, tool enablement, and Chat2DB business context.
• Provider identity is resolved on the server from the selected model configuration. Codex thread IDs, turn IDs, auth mode, CODEX_HOME, app-server process details, raw Codex event names, and internal route kinds remain server-side implementation state.
• Existing completion providers may continue to use request history. The Codex path restores model context through the stored Chat2DB session ID to Codex thread ID mapping instead of replaying frontend history.
• Each runtime adapter normalizes provider-specific output into the stable Chat2DB stream events: reasoning, tool_call, tool_result, answer, error, and done. A shared SSE writer serializes those events.
• The router does not parse provider events, and raw Codex protocol events are never exposed to the frontend.
• Normal completion emits exactly one done event. User interruption also emits done with a compatible status: interrupted field; actual failures emit error.

4. Authentication and account state

Decision:

• Chat2DB owns the user-facing connect, logout, cancellation, and reauthentication controls for the Codex provider. Users are not required to run codex login manually.
• Chat2DB uses an isolated Codex account space for each local Chat2DB profile instead of reusing the global Codex login.
• Login uses the app-server-managed ChatGPT browser flow. Device-code login is the fallback when the browser callback is not reliable.
• OAuth tokens, refresh tokens, and other credentials remain owned by the app-server. They never enter Chat2DB persistence, frontend storage, or logs.
• Chat2DB persists only a non-secret provider connection ID and connectionGeneration. The live app-server account state is the source of truth for whether the provider is connected.
• Account email, plan type, authentication state, rate-limit usage, and reset time are read dynamically from account/read, account notifications, and account/rateLimits/read. Each field or section is shown only when the app-server actually returns it; missing optional fields do not produce placeholder values.
• Rate-limit information and account-display projections are not persisted.
• Reauthentication is offered only after an observed authentication failure or loss of the active account state. Chat2DB does not infer expired credentials from unrelated runtime failures.
• A supported secure credential store is mandatory. macOS uses Keychain, Windows uses Credential Manager, and supported Linux Desktop environments use a system secret service. There is no silent fallback to auth.json or another plaintext credential file.
• Each operating-system user and each local Chat2DB profile has an independent Codex home, secure-store namespace, connection generation, and thread mapping. The first release runs the app-server only for the active local profile.
• Multi-user Web Server, Docker, and headless environments are outside the first-release support scope.
• Logging and diagnostics redact OAuth URLs and parameters, credentials, secure-store contents, and raw provider errors. User-facing failures are normalized to stable Chat2DB error codes and actionable messages.
• Logout ends the current connection generation. Existing Chat2DB history remains visible, but its Codex thread mappings cannot be resumed under a newly connected account.

5. Models and configuration

Decision:

• Each local Chat2DB profile owns one Codex provider connection. App-server-discovered models appear as dynamic children of that provider, not as separately persisted model configurations.
• Model identity is the pair CODEX + modelId. Display name, availability, reasoning-effort options, and other capabilities come from model/list.
• The live app-server model list is the source of truth. Chat2DB may use a short-lived projection for rendering, but it is not a second model catalog.
• Chat2DB stores a provider-level default model and an optional conversation-level override. These preferences affect Chat2DB only and never write global Codex configuration.
• Capability-specific controls are shown only when the selected model reports support for them.
• If an explicitly selected model is no longer available, Chat2DB marks it unavailable and requires a new choice instead of silently substituting another model.
• Each assistant response records the resolved provider, model, reasoning effort, and runtime version needed to explain historical output. Thread and turn identifiers remain internal metadata.

6. Runtime delivery

Decision:

• The Codex runtime is not bundled inside the Chat2DB installer. It is downloaded only after the user explicitly enables the Codex provider and chooses Download and connect.
• Each Chat2DB release contains a signed runtime manifest that pins the accepted Codex runtime version, platform, architecture, file size, checksum, and download sources.
• The manifest may list an exact Chat2DB CDN mirror and the official source. Both must serve the same unmodified artifact and pass the same checksum validation.
• Chat2DB uploads a CDN mirror only after redistribution rights for the official artifact and its dependencies are confirmed. Without that approval, the official source remains the only download source.
• The manifest signature is verified with a public key embedded in Chat2DB. A CDN response is never trusted as the source of its own checksum.
• Downloads use a staging path and become executable only after signature, checksum, size, platform, and architecture validation, followed by an atomic install.
• A downloaded runtime binary may be shared by profiles under the same operating-system user. Each profile keeps an isolated Codex home, account state, connection generation, and thread state.
• The runtime is not added to PATH, does not replace an installed Codex, and does not read global Codex configuration.
• The UI exposes download progress, cancellation, retry, proxy and disk-space failures, offline reuse, and explicit runtime removal.
• Runtime updates require an explicit compatible-version prompt. Chat2DB does not silently replace a runtime that is in use.
• The runtime manager owns initialization, required-capability checks, health checks, bounded restart, and shutdown. A runtime failure disables only the Codex provider.
• Desktop platforms are enabled independently after their download and runtime gates pass. Web, Docker, headless, CLI, and multi-user server environments are not first-release targets.

7. Database capabilities

Decision:

• Chat2DB defines the canonical, provider-neutral database tool contract. Codex consumes that contract through an MCP adapter; MCP is transport, not the authorization or execution authority.
• Codex never receives database credentials, JDBC URLs, or connection objects. All database access is executed through Chat2DB.
• Every tool invocation is bound to the current Chat2DB user, conversation, datasource, database, schema, and allowed operation scope.
• The initial tool set covers metadata discovery, schema and table description, EXPLAIN, and bounded read-only queries.
• DML and DDL are disabled by default. When enabled, every operation requires an explicit Chat2DB confirmation showing the exact SQL, datasource, operation class, and available impact information.
• Multi-statement, out-of-scope, unclassifiable, or unsafe-to-preflight SQL is denied by default.
• Chat2DB enforces permission checks, timeouts, cancellation, maximum rows, output truncation, and log redaction.
• Tool results are structured and include execution status, affected rows when available, and truncation metadata.
• A write whose outcome becomes ambiguous after a disconnect is recorded by the database tool-execution domain as unknown and is never blindly retried by the Codex adapter.

8. State ownership

Decision:

• Codex integration does not introduce a cross-domain state authority. Each state remains owned and persisted through its existing Chat2DB domain.
• Provider connection metadata, connection generation, and provider-default model belong to model configuration.
• Conversation-visible history and the Chat2DB conversation ID to Codex thread ID mapping belong to the conversation domain.
• Account details, rate limits, available models, and runtime capabilities remain live app-server projections and are not durable product state.
• Database approvals and write-execution outcomes belong to the database tool-execution domain.
• Codex threads, turns, and model-visible context remain exclusively owned by the Codex app-server.
• After logout, account-generation change, or missing runtime state, stale mappings are marked detached. Chat2DB does not fabricate a Codex terminal state or rebuild a thread by replaying visible history.

9. Release gates

Decision:

• Unit tests cover provider routing, model capability projection, event normalization, account-state mapping, redaction, and database policy decisions.
• Runtime contract tests cover initialization, required capabilities, model discovery, thread creation and resume, streaming, interruption, and normalized failures against the pinned runtime.
• Download tests cover manifest signature, checksum, platform and architecture selection, cancellation, interruption, retry, proxy failure, insufficient disk space, corrupt artifacts, offline reuse, removal, and explicit upgrades.
• Authentication tests cover browser login, device-code fallback, cancellation, logout, reauthentication, unavailable secure storage, and absence of credentials from logs and renderer state.
• Database tests cover datasource and schema scope, permission denial, SQL classification, DML and DDL confirmation, timeout, cancellation, truncation, and unknown write outcomes.
• Packaging tests validate each signed desktop installer together with a real downloaded runtime on the target platform.
• A release candidate passes a live ChatGPT/Codex subscription flow without retaining credentials in artifacts or diagnostics.
• The shared AI route and SSE contract test suites must pass after the provider router is introduced.
• The feature remains disabled per platform until that platform passes every applicable gate.
• Rollback can disable the Codex provider or select a previously accepted runtime without altering Chat2DB conversations, model preferences, or database state.