main.rs owns the Agent facade, CLI and slash-command dispatch, prompt/context assembly, compaction, built-in tool adapters, and eval harness. Provider stream parsing lives in streaming.rs; tool planning and dispatch live in tool_round.rs; durable side-effect records live in tool_journal.rs.

Agent Loop

The central Agent struct drives a turn-based loop:

1. Prompt composition — Builds the system prompt from DEXT.md, project context, tool catalog, session header, work ledger, shelf abilities, and recall cache.
2. History management — Maintains a Vec<Message> with automatic compaction when context pressure exceeds configurable thresholds (default: 90% at end-turn, 80% after safe tool-result checkpoints).
3. Provider dispatch — Sends streaming requests to the active provider. Applies connect, first-byte, and between-chunk idle deadlines, then parses bounded SSE frames into Block variants.
4. Tool execution — Dispatches tool_use blocks to native Rust implementations. Supports parallel execution for read-only tools.
5. Permission gating — Routes tool calls through EventSink::request_permission() based on the active ApprovalProfile and tool risk classification.
6. Steering — Active-turn user input is routed to a steering channel, injected at safe boundaries.

Stream Parsing

Transport Deadlines and Body Bounds

The shared provider client uses a 15-second connect timeout. Cloud requests allow 180 seconds to first response headers and 90 seconds between stream chunks; local llama.cpp requests default to 600 seconds and 300 seconds respectively. DEXT_PROVIDER_CONNECT_TIMEOUT_SECS, DEXT_PROVIDER_FIRST_BYTE_TIMEOUT_SECS, and DEXT_PROVIDER_STREAM_IDLE_TIMEOUT_SECS accept positive overrides. Initial requests and compaction retries use the same first-byte policy. Non-stream compaction responses use the stream-idle deadline while reading and reject JSON bodies above 4 MiB; provider error diagnostics stop at 4,000 bytes.

src/sse.rs limits its in-progress input buffer to one configured event plus at most four delimiter bytes before rejection. One large network read may still contain many valid small events; the decoder drains complete frames incrementally rather than rejecting by chunk size.

ChatGPT Responses terminal events with status=incomplete are recoverable rather than fatal protocol errors. Dext executes only function calls that reached a streamed completion event and discards truncated calls, ignoring complete-looking terminal snapshots for those unfinished calls. Discarded live text/thinking preview state is reset; interactive warnings identify the recovery. If no executable call remains, Dext issues a bounded continuation request with a concise runtime hint; provider-reported content filtering halts immediately instead of retrying. Recovery lowers ChatGPT reasoning effort for that request only (for example, xhigh to medium) without changing the user-selected effort or consuming the normal tool-iteration budget. After three unsuccessful continuation requests, Dext halts the turn with guidance while keeping the session usable.

Session Persistence

Sessions are stored as JSONL files under ~/.dext/projects/<project-key>/sessions/. The first line is a SessionHeader with full provenance (model/provider, tool policy surface, approval/sandbox profiles, context mode, usage ledger, work ledger, provider health, and runtime diagnostics). This header is the replay anchor for deterministic restore behavior.

Eval Harness

Outcome-oriented assertions on files and command output. The eval path validates objective completion semantically (not just command exit) and records verification artifacts for later audit. Run via dext --eval.

Crash Recovery

A panic hook writes an owner-private JSON snapshot under ~/.dext/crashes/ with a generated crash id, hashed source-location metadata, terminal dimensions, process id, current generated session id, recent event breadcrumbs, and whether backtraces were enabled. Free-form panic payloads, raw source paths, environment text, and backtrace content are omitted.

Manages all persistent state for Dext sessions, logs, and project-scoped data.

State Directories

~/.dext/                         # DEXT_HOME (overridable)
├── providers.json               # Provider catalog
├── auth.json                    # Stored credentials (0600 on Unix)
├── .env                         # Optional user-owned Dext dotenv settings
├── settings.json                 # user compaction threshold settings
├── crashes/                     # owner-private crash snapshots
├── shelves/                     # User-scoped shelves and packs
└── projects/
    └── <project-key>/
        └── sessions/
            ├── <name>.jsonl     # Named session export
            └── <session-id>/
                ├── _latest.jsonl
                ├── latest.log
                ├── session.lock.json
                ├── DEXT.todo.json
                ├── tool-journal.json
                ├── artifacts/
                ├── git-auth/
                └── sudo/

Project Key

Each project gets a stable key derived from its canonical path: <slug>-<FNV-1a-hash>. This ensures isolated state per project even with identical directory names.

Atomic Writes

Sensitive state writes use a temp-file-and-replace helper. On Windows the replacement uses MoveFileExW; on Unix it uses fs::rename. Session logs normally use private append writes while they remain below the cap.

Session State Lock

Each active session directory has a session.lock.json record containing PID, token, project, sandbox, and session identity. Matching locks are released through a cleanup registry; a lock is removed as stale only when its recorded process is no longer running.

Log Rotation

Each session's latest.log is capped at 64,000 bytes. DEXT_LOG_ARCHIVES may retain up to 16 rotated archives; the default is zero.

Manages the catalog of model providers, authentication, request shaping, and model normalization.

ApiProvider Enum

Three wire-format families:

• Anthropic — Anthropic Messages API (also used by GLM via api.z.ai/api/anthropic)
• OpenAi — OpenAI Chat Completions API (also used by DeepSeek, local llama.cpp)
• ChatGpt — ChatGPT Responses API (OAuth-backed)

Built-in Providers

Provider Resolution Chain

1. DEXT_PROVIDER env var
2. DEXT_PROFILE env var
3. DEXT_API_PROVIDER env var
4. active_provider field in providers.json
5. Default: glm

Model Resolution Chain

1. DEXT_MODEL_{PROVIDER} (provider-specific)
2. DEXT_MODEL (with DEXT_MODEL_FORCE override)
3. Profile's default_model

ChatGPT Model Normalization

Compact aliases are canonicalized (for example gpt5codex → gpt-5-codex and ChatGPT gpt-5.6 → gpt-5.6-sol). GLM models get an automatic glm- prefix when omitted, and model-name context hints such as [1m] are honored.

Authentication

Credentials stored in ~/.dext/auth.json. Two types: ApiKey (plain key, supports env var refs and !command secret references) and OAuth (access token + refresh token + expiry, used by ChatGPT). Provider/profile resolution merges built-ins with user catalog overrides while pruning retired bundled providers.

Defines all provider-visible tools, their schemas, permission requirements, and parallel-safety classification.

Tool Profiles

Controlled via DEXT_TOOL_PROFILE. Lean mode saves significant prompt tokens per turn. A separate toolset profile is selected by --toolset or DEXT_TOOLSET: default hides specialized tools and full exposes the complete catalog. Frugal/tiny reduce context and result budgets without overriding explicit toolset or schema selections.

Tool Classification

Wire Format Adapters

• wire_tools() — Anthropic format with cache_control: ephemeral
• wire_tools_oai() — OpenAI function type format
• wire_tools_chatgpt() — ChatGPT flattened format with strict: null

Runtime-only pack and shelf commands are intentionally separate from provider-visible tools. Packs act as modular battery packs: Dext creates, discovers, inspects, maintains, and invokes shelf-contained workflows through the existing tool, approval, and sandbox surface. Dext ships no pack content and adds no pack-specific provider-visible tools.

Validates tool inputs, classifies command risk, and enforces bash guardrails.

Command Risk Levels

Bash Guardrails

• Auto-injects set -o pipefail if missing
• Blocks --break-system-packages pip flag (overridable)
• Detects sudo commands needing password and routes to local auth prompt
• Bash calls are atomic: Unix roots run in detached sessions/process groups; Windows roots start suspended, enter kill-on-close Job Objects, then resume. Dext cleans the full child tree after completion, timeout, or interrupt.
• On Windows, shell-backed tools skip Windows/WSL app aliases and select a real bash.exe from PATH (for example Git for Windows); DEXT_BASH_PATH provides an explicit override.
• Advisories: prefer rg over grep -r, prefer fd over find

Input Validation

Every tool call is validated for required fields before execution. Missing/empty required fields, type mismatches, and mutually exclusive params are caught early with descriptive errors.

Auth Failure Detection

Tool output is scanned for auth failure markers (unauthorized, 401, 403, invalid api key) to trigger circuit breakers and prevent repeated credential burn on failing hosts.

An inline TUI built on Ratatui + Crossterm that renders in the regular terminal buffer and preserves native terminal scrollback. The backend output viewer is the only alternate-screen surface.

Layout

• Transcript area — Scrollable message history with user, assistant, tool, thinking, and steering lines
• Live status bar — Provider, model, thinking effort, approval profile, context pressure, usage stats
• Input panel — Multi-line text input with history (200 entries), completion for slash commands
• Work map drawer — Collapsible work-ledger visualization

Startup Welcome

The startup welcome remains inline transcript content, so it scrolls away naturally with the conversation. One transcript-owned blank separator row keeps it visually distinct from CLI approval and sandbox diagnostics, including after inline viewport placement or replay. Its brand row shows Dext and the version, plus the working directory and cached Git branch/state at 80 columns or wider; narrower terminals drop that right segment. Exactly two facts, Model and Approval, sit between horizontal rules, followed by one rotating tip selected from verified commands and key bindings. Terminal-cell width controls alignment and path truncation. Git status uses one git status --porcelain=v1 --branch probe off the render loop, with only an 8 ms startup wait before path-only fallback. The empty composer reads ❯ Type a request…   @ files · / commands.

Permission Prompts

Tool calls requiring permission show inline prompts with risk tier color coding (yellow for Read/Write, red for Danger). Choices: Once, Always (session), Deny.

Key Bindings

Status and Active Time

The main status row presents the exact main branch label as Main, including Main (dirty) when the working tree is dirty, without renaming the branch or changing any other branch casing. It reserves its right edge for a live cumulative agent-active clock while Dext handles a turn. The clock advances during provider waits, tool calls, permission/auth waits, and in-turn compaction; while Dext is idle awaiting user input, it pauses and is hidden, then resumes on the next turn. It updates through the existing redraw cadence and uses compact forms such as 7s, 7m 05s, and 1h 07m without adding a timer thread.

Todo View

Ctrl+L opens a clean read-only modal during ordinary idle or busy work. Security-critical permission and local-auth prompts intentionally retain input and rendering priority and must be resolved or canceled first. The modal loads persisted session/project todos at startup, refreshes after todo_read/todo_write, scrolls with arrows, Page Up/Down, Home/End, or the mouse wheel, and closes with Ctrl+L, Esc, or q. Empty-state parsing matches Dext's generated sentinel lines exactly, so ordinary todo text cannot clear the modal accidentally. When todo progress is the live-status fallback above the composer, the battery follows the list length up to seven cells: Todos 3/4 ■■■□ maps one cell to each short-list item, while a longer list such as Todos 15/20 ■■■■■□□ stays capped and proportional. Partial progress retains at least one filled and one empty cell, and the active task remains visible when space permits. Editing remains on the existing todo_write path so validation, approval, checkpoint, and session-state behavior are not duplicated. The backend viewer remains the only alternate-screen surface.

Tool Result Rendering

Tool results are rendered as collapsible blocks with density grouping. Long outputs are compressed with head+tail preservation and JSON shape hints. Failed native write_file, edit_file, and multi_edit blocks explicitly state that no edits were applied, matching the atomic prepare-and-replace invariant. The alternate-screen backend viewer normalizes CRLF across arbitrary output chunks without introducing blank rows and visually matches the main TUI with a Dext header, agent-active clock, command summary, styled stdout/stderr lanes, output panel, command position, and compact controls. It continues to use the existing bounded ring buffer, selection, scrolling, event stream, and permission/auth priority.

Markdown Rendering

Assistant text blocks are rendered using tui-markdown with sanitization and terminal-safe formatting rules. Rendering preserves readability under narrow widths and avoids alternate-screen dependence.

Dependency and resize contract

The exact stack is ratatui 0.30.2, ratatui-core 0.1.2, tui-markdown 0.3.8, crossterm 0.29.0, and unicode-width 0.2.2. Dext selects exact versions and patches exact vendored ratatui-core source to avoid synchronous cursor-position queries during inline replay and whole-display clears during horizontal shrink.

The real-PTY regression suite verifies editable input during streaming, resize survival with populated history, zero whole-screen resize clears, bounded cursor queries, terminal-height-bounded replay chunks, and completed output after resize. Its final stream marker has a bounded 10-second wait so slower macOS CI hosts do not create false negatives. See docs/TUI.md and vendor/ratatui-core/DEXT_PATCH.md for the maintained contract and patch rationale.

Git-native recovery checkpoints created before approved non-read-risk tool calls in Git workspaces.

Checkpoint Lifecycle

1. Create — Before a tool executes, a checkpoint is created under refs/dext/checkpoints/<session>/<timestamp>-<ordinal>-<tool>
2. Dirty state capture — If the worktree is dirty, git stash create captures a snapshot without touching the working tree or reflog
3. Untracked sidecar — For direct file tools, untracked files are saved to owner-private .dext/checkpoints/<id>/ storage; symlinked storage paths are rejected on Unix
4. Manifest — Appended to owner-private .dext/checkpoints/manifest.txt; /.dext/ is added to the repository-local Git exclude

Restore Modes

Pruning

Default: keep the 20 newest checkpoints and remove entries older than 168 hours (7 days). Pruning rebuilds local manifests, removes orphaned refs/dext/checkpoints/*, and deletes associated sidecar directories for bounded disk growth. Never mirror-push refs/dext/*.

Checkpoint Triggers

Always checkpointed: write_file, edit_file, multi_edit, todo_write, git_commit. Other tools are checkpointed when tool_policy::classify_command_risk() returns Write or Danger (for example write-risk bash/awk/csvkit or non-GET http).

Generates in-memory line-level mutation previews before applying direct file mutations. Shows the preview during permission prompts without touching disk.

Preview Flow

1. Read the current file content (or empty for new files)
2. Compute the proposed content (apply edit/multi-edit transforms in memory)
3. Generate a simple line-level diff with one context line around changed hunks
4. Cap at 4,096 bytes with a truncation notice
5. Show added/removed line counts and whether it's a new file

Sandbox Validation

All paths are canonicalized and validated to be within the sandbox root. Paths outside the sandbox are rejected. Cross-platform display and Git pathspec rendering strips Windows verbatim prefixes and normalizes separators to forward slashes; work-ledger filtering recognizes both native and foreign-platform absolute paths.

Per-turn runtime state that guards against loops, manages external resource access, and tracks objectives.

Work Phases

Guard Systems

• Dedupe cache — Short-circuits identical external requests within a turn
• Similarity guard — Blocks after 3+ similar unproductive bash/file operations
• Tool retry budget — Circuit breaker after 3+ failures with same error signature
• Empty tool call loop detection — Detects provider bug where tool arguments are dropped (threshold: 4 consecutive empty calls)
• Auth circuit breaker — Blocks hosts after 2 auth failures
• Feasibility guard — Requires single-item probes before bulk external collection

Objective Tracker

Parses user prompts to extract checkpoints (plan, analyze, implement, verify, document). Tracks satisfaction by examining tool usage patterns, bash commands, and assistant text.

Adaptive Caps

Tool UI content and result caps scale down dynamically based on context pressure: ≥90% → 25%, ≥75% → 50%, ≥60% → 75% of default. This preserves critical evidence near context limits while reducing prompt bloat.

Packs are shelf-contained workflow documents, not plugin binaries. Dext supplies the create, discover, inspect, maintain, and run lifecycle; users own the content. The runtime reads PACK.md and executes through the existing Dext tool surface, keeping packs provider-neutral and auditable without bloating the core binary.

Design Contract

• No provider-visible tool expansion: packs orchestrate existing tools (bash, read_file, rg, etc.).
• Source-first reviewability: every pack is plain files in a directory.
• Deterministic discovery and precedence: first resolved name wins after ordered search roots.
• Optional hooks via phooks.json, isolated from project hooks.json.

Pack Object Model (PackInfo)

packs.rs normalizes each discovered pack into PackInfo with:

• name, description, declared credential_env names (from front matter or directory defaults)
• path, pack_md_path, optional phooks_path
• source label (project/env/user) and shelf ownership

Invocation wraps this as PackInvocation { pack, task } so the task is explicit and auditable.

Discovery and Creation

1. Project shelves: .dext/shelves/*/packs
2. Explicit shelf roots: DEXT_SHELVES_DIR
3. User shelves: ~/.dext/shelves/*/packs

Create reusable packs with dext pack create <shelf>/<name>; add --project only for an explicitly project-local pack. The scaffold creates a minimal PACK.md, refuses overwrite, and is immediately available to normal inspection and invocation. Direct packs/, .dext/packs, ~/.dext/packs, DEXT_PACKS_DIR, and per-pack override roots are not discovery inputs.

The resolver deduplicates by canonicalized path and normalized pack name. Name collisions are resolved by precedence order, not random filesystem order.

Pack Layout and Front Matter

my-pack/
├── PACK.md          # required; markdown workflow with YAML front matter
├── phooks.json      # optional hook template for this pack
├── bin/             # optional helper scripts
└── README.md        # optional human docs

---
name: my-pack
description: One-line workflow summary
credential-env: [SERVICE_TOKEN]
---

# Workflow
1) Setup
2) Probe
3) Transform
4) Verify
5) Deliver

Only PACK.md is required. Front matter stays minimal: identity/description plus an optional inline credential-env list of exact credential-shaped names required by the pack's own helper. That field is honored only for user and DEXT_SHELVES_DIR packs; project-local declarations are ignored.

Prompt Injection Model

pack_prompt() builds a bounded invocation prompt (cap: PACK_PROMPT_CAP = 32_000 bytes) containing:

• pack identity and source metadata
• paths for workflow and optional hooks
• pack-scoped environment names (DEXT_PACK_DIR, DEXT_PACK_<NAME>_DIR), which the runtime supplies to active-pack bash calls and hook processes
• declared credential names only, never their values
• full PACK.md workflow body
• explicit user task text

This gives the model procedural guidance without changing core runtime policy. The selected pack remains active for the session: its phooks.json entries are added to the hook set, and pack-scoped environment variables are passed to subsequent bash tool commands and hook processes. Declared credential values are narrower: for user and DEXT_SHELVES_DIR packs, they reach only a simple direct invocation of the active pack's own native bin/ helper, never hooks, arbitrary bash, pipelines/redirections, prompts, logs, or sessions; provider-auth names remain excluded. Project-local declarations are ignored. Changing the sandbox root clears active pack state.

Execution Paths

• CLI: dext pack create <shelf>/<name>, list, inspect, and run
• Interactive: /pack create, list, inspect, and run
• Conversational detection: invoke <name> / run <name> on ... patterns mapped by selector inference

Operational Guidance for Pack Authors

• Write reproducible loops: inputs, stop conditions, verification gates.
• Install reusable packs under user-global Dext scope by default; use project-local roots only for intentionally repo-scoped packs.
• Keep shell helpers idempotent; prefer deterministic outputs for agent reuse.
• Use phooks.json only when needed; packs must still function without hooks.
• Treat pack workflows as code: version, test on disposable repos, and review diffs.

Outside the active sandbox, native mutation tools may write only below a concrete user pack directory (~/.dext/shelves/<shelf>/packs/<pack>/...) containing a regular PACK.md. Shelf manifests and loose files directly under packs/ remain outside that exception. Dext revalidates the destination and marker before atomic replacement; same-user path races remain outside the isolation boundary and are tracked in the risk register.

Shelves are typed metadata registries over packs. They describe capabilities and signal/effect behavior without adding provider-visible tools.

Why Shelves Exist

• Give the model structured capability hints (commands/hooks/context) with low token cost.
• Separate extension metadata from prompt prose.
• Enable scoped override rules across core/user/project/run environments.

Manifest and Type System

shelf.json is parsed into ShelfManifest → PackManifest → Ability enums:

Signal and Effect Types

The shelf module defines a typed signal/effect vocabulary for in-process shelf implementations. Filesystem shelf.json manifests are declarative metadata: a matching load/prompt hook declaration can opt declared context into bounded prompt injection, but manifests do not register executable tools or slash commands and do not supply arbitrary effect handlers.

Block effects terminate in-process signal flow early. Static manifest shelves only produce context/note data for opted-in load or prompt signals.

Discovery and Scope Precedence

resolve() keeps one winning ability per key using tuple ordering by scope rank and stable discovery order. This gives deterministic override semantics.

Prompt and CLI Surfaces

• render_registry_listing() powers dext shelves / /shelves operator visibility.
• registry_summary_for_prompt() injects compact typed ability summaries into model context.
• Ability metadata is provider-neutral and does not modify the external tool schema.

Methodology for Building Shelf Ecosystems

1. Start with pure packs; add shelf metadata only for reusable capability contracts.
2. Define ability keys as stable API-like surfaces.
3. Use project scope for repository policy, user scope for personal defaults, run scope for experiments.
4. Treat shelf.json as versioned interface documentation and test precedence resolution.

Unit Tests (main_tests.rs)

The test suite covers provider catalogs and request shaping, auth and state formats, stream/tool-call assembly, tool policy, sandboxing, side-effect journals, recovery checkpoints, TUI rendering, and runtime orchestration. Git fixture subprocesses explicitly clear ambient repository-routing variables such as GIT_DIR and GIT_WORK_TREE, so parallel environment-isolation tests cannot redirect unrelated temporary repositories.

• Provider catalog loading, normalization, and model resolution
• Auth store operations (save, load, normalize)
• Session header parsing and backwards compatibility
• Tool input validation and risk classification
• Bash guardrails and sudo detection
• Checkpoint creation and restore logic
• Objective tracking and satisfaction assessment
• URL host extraction, proxy isolation, destination policy, and exact redirect limits; redirect fixtures use bounded blocking reads on accepted sockets for consistent Windows behavior

Run with: cargo test --release --locked

Real-PTY TUI Regression Suite (tests/tui_smoke.rs)

Spawns the real Dext binary in a Unix PTY at narrow and wide terminal sizes and verifies:

• Application launch, banner/composer rendering, help, multiline input, and clean Ctrl+D exit
• Editable input while output streams and process survival during populated-history resize bursts
• Zero whole-screen clears, resize-bounded cursor queries, and terminal-height-bounded replay chunks
• Completed stream output and accepted input after resize, with no crash markers

Run with: cargo test --release --locked --test tui_smoke -- --nocapture

The complete verification gate also runs formatting, Clippy with warnings denied across the Linux, macOS, and Windows CI matrix, vulnerability auditing, dependency-license policy checks, the vendored ratatui-core unit tests, and a locked release build. Release publication generates dext.cdx.json, includes it in SHA256SUMS, and attests and verifies it alongside the four platform archives. The first successful tag run remains tracked in docs/RELEASING.md until the publication path has end-to-end evidence. On Windows CI and release builders, the scheduler-sensitive fast_bash_command_returns_without_100ms_poll_tail regression runs alone after the remaining release tests. Its original <90 ms assertion remains unchanged; isolation prevents unrelated suite load from obscuring the process-wait regression it measures. The tool-call mock provider consumes its bounded Content-Length request body before responding so Windows does not reset the connection with unread request data. See docs/TUI.md for renderer-specific live-terminal checks.

GitHub Pages

The public site at siliconstate.github.io/Dext is deployed from the static docs/ tree by .github/workflows/pages.yml. The workflow validates local links and anchors, uploads an immutable Pages artifact, and deploys with only pages: write and id-token: write in the deployment job. Third-party actions are pinned to full commit hashes and checkout credentials are not persisted.

Criterion benchmarks for performance-critical paths:

Run with cargo bench; CI and the release quality job compile the benchmark with cargo bench --no-run --locked.

Build Profile

Release builds use: lto = false, codegen-units = 16, strip = "symbols" — optimized for build speed while keeping binary size small.

Auth Subcommands

Other Subcommands

Dext implements 18 provider-visible tools. The default profile contains 13 core tool names. Specialized tools (jq, fzf, awk, git_log, csvkit) require dext --toolset full, DEXT_TOOLSET=full, or /tools full. User-authored shelf packs orchestrate this existing surface and do not modify the tool count.

File Operations

Search & Discovery

Shell & Process

Data Processing

HTTP

Git Operations

Task Management

GLM (ZAI)

• Default built-in provider. Uses the Anthropic-compatible API at api.z.ai/api/anthropic
• Catalog models: glm-5.2[1m] (default), glm-5.2, glm-5.1, glm-5.0, and glm-4.6. The 5.2 variants declare 1M context; the provider fallback is 200K.
• Auth: API key via ZAI_API_KEY or dext auth login glm <key>

ChatGPT / Codex

• Uses the OpenAI OAuth flow with a local callback server on port 1455
• Catalog models include GPT-5.6 Sol/Terra/Luna, gpt-5.4 and 5.4-mini, gpt-5.5, Codex variants, gpt-5/mini, gpt-4.1, gpt-4o/mini, o3/o3-mini, and o4-mini.
• GPT-5.6 variants declare 1.05M context and 128K output metadata; other models use the provider fallback or explicit model overrides. Auth: dext auth login chatgpt or CHATGPT_ACCESS_TOKEN.

OpenAI API

• Standard OpenAI Platform API using API-key auth
• Catalog models include the official gpt-5.6 Sol alias plus Sol/Terra/Luna variants, gpt-5/mini, gpt-4.1/mini, gpt-4o/mini, o3/o3-mini, and o4-mini. Model-specific metadata overrides the 400K provider fallback.
• Auth: API key via OPENAI_API_KEY or dext auth login openai <key>

Anthropic

• The catalog includes current Sonnet, Opus, Fable, and Haiku model variants.
• Context fallback: 200K tokens. Auth: ANTHROPIC_API_KEY or dext auth login anthropic <key>.

Kimi Code

• Uses Anthropic Messages semantics at api.kimi.com/coding; default model K3 declares 1,048,576-token context, 131,072-token output metadata, and adaptive max thinking.
• Auth: Kimi Code plan API key via KIMI_API_KEY or dext auth login kimi <key>. This key is distinct from MOONSHOT_API_KEY.

DeepSeek

• OpenAI-compatible API
• Models: deepseek-chat, deepseek-reasoner — Context: 128K tokens — Auth: DEEPSEEK_API_KEY

Local (llama.cpp)

• OpenAI-compatible local server at 127.0.0.1:8080 — No API key required — accepts the configured server model alias; local providers default to frugal context and probe llama.cpp for the live runtime context window without model-specific built-in context values. If the local server is offline, discovery falls back cleanly and the later provider request reports the ordinary connection error.

Provider catalogs and auth stores are read through bounded non-symlink regular-file checks. On Unix, foreign ownership is rejected; group/world-writable provider catalogs are rejected; owner-owned auth files with loose mode are repaired to 0600 before parsing. dext doctor uses bounded, no-follow, inode-stable inspection and reports the same ownership/mode policy without repairing files.

providers.json (~/.dext/providers.json)

Provider catalog with merged built-in + custom profiles. Editable via /provider and /model commands. Auto-normalized on load.

Catalog v2 profiles may set request_contract to anthropic-messages, openai-chat-completions, or chatgpt-responses. Optional model_aliases, model_defaults, and model_specs provide canonical model ids, limits, effort levels, capabilities, and pricing. Explicit per-model metadata wins; context hints in model names such as -128k and [1m] win over provider-wide context defaults. Built-in metadata only fills omissions, and v1 profile fields remain accepted. DEXT_PROMPT_CACHE=on|off overrides catalog prompt-cache capabilities for Anthropic-style requests; auto mode uses catalog metadata.

auth.json (~/.dext/auth.json)

API-key entries may reference a parent environment variable by name or intentionally run a !command through bash -lc. Treat write access to this store as code-execution authority.

Stored credentials per provider. Set to mode 0600 on Unix. Supports ApiKey and OAuth credential types. Credential-shaped parent environment variables are removed from agent-run subprocesses by default. DEXT_INHERIT_TOOL_CREDENTIALS=1 opts in only trusted model-invoked bash/external tools; hooks and Dext-owned subprocesses remain scrubbed.

.env (~/.dext/.env or $DEXT_HOME/.env)

Optional user-owned Dext settings. Project .env files and parent directories are never auto-loaded, so repository content cannot silently alter runtime policy.

DEXT.md (sandbox ancestry)

Tracked machine-facing project guidance auto-injected into the system prompt. Dext scans the sandbox root and ancestors and does not modify the file automatically.

recall.md (optional sandbox ancestry)

Optional ignored prompt cache. It is auto-injected only when present; Dext does not create or update it automatically.

hooks.json (project root or DEXT_HOOKS_FILE)

Project-root hooks configuration loaded from hooks.json by default, or from DEXT_HOOKS_FILE when set. This is not the same as pack phooks.json.