Skip to content

settings-runtime-config-contract.md

Latest commit

 

History

History
201 lines (149 loc) · 6.59 KB

settings-runtime-config-contract.md

File metadata and controls

201 lines (149 loc) · 6.59 KB

Settings and Runtime Config Contract

Goal

The dex-code settings panel exposes safe runtime, model, reasoning, Flow, and context controls without leaking secrets or pretending unsupported actions are connected.

Sources Of Truth

Configuration is resolved in this order:

  1. Explicit selection in the current session.
  2. Workspace/session settings stored by dex-code.
  3. Global app defaults.
  4. %USERPROFILE%\.deepseek\config.toml.
  5. Internal safe defaults.

The DeepSeek CLI config is an input and optional persistence target. It is not the only source of truth while a session is already active.

Safe DeepSeek CLI Fields

dex-code may read and write only these known fields:

  • default_text_model
  • reasoning_effort
  • [ui].default_mode
  • top-level provider
  • [providers.<provider>].base_url
  • [providers.<provider>].model
  • [providers.<provider>].text_model
  • [providers.<provider>].image_model
  • [providers.<provider>].image_edit_model
  • [providers.<provider>].audio_model
  • [providers.<provider>].tts_model
  • [providers.<provider>].voice

Unknown fields must be preserved. Secret-like fields or sections may be detected as present, but their values must never be displayed, logged, committed, or included in evidence.

Before writing %USERPROFILE%\.deepseek\config.toml, dex-code must create a timestamped backup beside the file.

Settings Sections

DeepSeek Runtime

Shows the current runtime URL, health/workspace/stream status, token presence as yes/no, and the canonical/diagnostic port note. Token values are never shown.

Model And Reasoning

Allows selection of:

  • model: deepseek-v4-pro or deepseek-v4-flash
  • mode: agent, plan, yolo
  • thinking: off, auto, high, max

Saving writes the safe fields to the DeepSeek CLI config through the backup flow. The active runtime config should be reset after saving so new turns can pick up the updated values.

Provider Textual Principal

dex-code.exe remains a client of the local DeepSeek Runtime. Providers such as deepseek, ollama, openrouter, and custom-openai are configured below that runtime, not as replacement runtime URLs.

The Provedores panel configures only the main text provider:

  • top-level provider
  • [providers.<provider>].base_url
  • [providers.<provider>].model
  • [providers.<provider>].text_model
  • [providers.<provider>].api_key, only when the user enters a replacement

When provider = "deepseek", text models must be limited to deepseek-v4-pro and deepseek-v4-flash. External model ids such as google/*, openai/*, anthropic/*, llama*, or gemma* must not be shown or saved as DeepSeek text models.

provider = "openrouter"
default_text_model = "auto"

[providers.openrouter]
base_url = "https://openrouter.ai/api/v1"
model = "openai/gpt-5.4-mini"
text_model = "openai/gpt-5.4-mini"

Rules:

  • model is the backward-compatible alias for the text/default model.
  • text_model, when filled, is the effective text model sent to the runtime.
  • external providers should keep top-level default_text_model = "auto".
  • saving a text provider restarts the local DeepSeek Runtime so the running process reloads config.toml.
  • secret fields are never loaded back into UI controls; a new value is saved only when the user explicitly provides one.

Auxiliary Services And Capability Slots

Image/audio/TTS slots are configured outside the main text provider. In this cut, the Servicos auxiliares panel exposes only OpenRouter as the auxiliary provider and writes sidecar fields under [providers.openrouter]:

provider = "deepseek"
default_text_model = "deepseek-v4-flash"

[providers.deepseek]
model = "deepseek-v4-flash"
text_model = "deepseek-v4-flash"

[providers.openrouter]
base_url = "https://openrouter.ai/api/v1"
image_model = ""
image_edit_model = ""
audio_model = ""
tts_model = ""
voice = ""
  • empty image/audio/TTS slots mean sem modelo.
  • saving auxiliary services must not change top-level provider.
  • saving auxiliary services should not restart the text runtime unless a later implementation proves a reload is required.
  • OpenRouter may coexist as a sidecar while provider = "deepseek".

Capability status must be honest:

  • connected: text provider path proven through DeepSeek Runtime.
  • advisory: configured or cataloged, but not proven as native runtime payload.
  • hidden: capability has no safe connected contract yet.

Image/audio slots must not be presented as native multimodal support unless the DeepSeek Runtime endpoint proves it consumed image/audio payloads. A connected vision skill/tool may produce text context, but that is separate from native runtime multimodal.

Audio Via Dex Agent

The explicit Audio Dex action is disabled in this stabilization cut. It must not live inside the main VCL service or composer menu until it returns through a small FeatureAdapter with its own SPEC and end-to-end evidence.

Contract for future reintroduction:

  • Keep Dex Agent audio separate from OpenRouter audio_model and tts_model slots.
  • Resolve any external repo or wrapper without reading or displaying .env contents.
  • Report advisory, unavailable, dry-run, or delivery JSON honestly.
  • OpenRouter TTS remains advisory until a separate end-to-end synthesis path is proven.

Flow And Telemetry

Allows toggling optional display sections:

  • tokens
  • cost
  • IDs
  • safety
  • activity timeline
  • recent prompt count

Missing telemetry fields must be omitted or shown as unavailable. Missing data must not raise UI or Delphi exceptions.

Context And Compaction

/compact is a user-facing instruction marker for the runtime. dex-code must not run automatic compaction without confirmation.

If the runtime does not expose a connected HTTP compaction endpoint, the UI must report that limitation clearly and send /compact as prompt text only when the user requests it.

Slash Command Boundary

/GOAL and /compact are pass-through prompt text markers in dex-code. They must not trigger the local unknown-command error.

Evidence Requirements

Validation should cover:

  • settings panel opens with DeepSeek sections visible
  • config values load without printing secrets
  • save creates a backup and preserves unknown fields
  • model/mode/thinking are reflected in new runtime config
  • provider capability slots round-trip without exposing secrets
  • model selector categories reuse textGeneration, imageCreation, audioCreation, and textToSpeech
  • vision/audio states are labelled connected/advisory/hidden based on evidence
  • /GOAL and /compact are accepted as prompt text
  • Flow/footer remain stable when optional fields are absent