| 1 | # Capacity Controller |
| 2 | |
| 3 | `deepseek-tui` includes an opt-in capacity-aware context controller. In the |
| 4 | default V4 path it is disabled, because its active interventions can rewrite |
| 5 | the live prompt and break prefix-cache affinity. Treat it as telemetry or an |
| 6 | experimental guardrail unless `capacity.enabled = true` is set explicitly. |
| 7 | |
| 8 | ## Policy Overview |
| 9 | |
| 10 | Each checkpoint computes: |
| 11 | |
| 12 | - `H_hat` (runtime pressure proxy) |
| 13 | - `C_hat` (model capacity prior) |
| 14 | - `slack = C_hat - H_hat` |
| 15 | - dynamic slack profile over last `N=8` observations |
| 16 | |
| 17 | ### Runtime Pressure Proxy (`H_hat`) |
| 18 | |
| 19 | - `action_complexity_bits = log2(1 + action_count_this_turn)` |
| 20 | - `tool_complexity_bits = log2(1 + tool_calls_recent_window)` |
| 21 | - `ref_complexity_bits = log2(1 + unique_reference_ids_recent_window)` |
| 22 | - `context_pressure_bits = 6.0 * context_used_ratio` |
| 23 | |
| 24 | Formula: |
| 25 | |
| 26 | `H_hat = 0.35*action_complexity_bits + 0.30*tool_complexity_bits + 0.20*ref_complexity_bits + 0.15*context_pressure_bits` |
| 27 | |
| 28 | ### Capacity Prior (`C_hat`) |
| 29 | |
| 30 | Per-model priors: |
| 31 | |
| 32 | - `deepseek_v3_2_chat = 3.9` |
| 33 | - `deepseek_v3_2_reasoner = 4.1` |
| 34 | - `deepseek_v4_pro = 3.5` |
| 35 | - `deepseek_v4_flash = 4.2` |
| 36 | - fallback `3.8` (used for other DeepSeek IDs, including future releases) |
| 37 | |
| 38 | ### Failure Probability |
| 39 | |
| 40 | Using rolling profile fields: |
| 41 | |
| 42 | - `final_slack` |
| 43 | - `min_slack` |
| 44 | - `violation_ratio` |
| 45 | - `slack_volatility` |
| 46 | - `slack_drop` |
| 47 | |
| 48 | Formula: |
| 49 | |
| 50 | `z = -1.65*final_slack -0.85*min_slack +1.35*violation_ratio +0.70*slack_volatility +0.28*slack_drop -0.12` |
| 51 | |
| 52 | `p_fail = sigmoid(z)` clamped to `[0,1]`. |
| 53 | |
| 54 | Risk bands: |
| 55 | |
| 56 | - low: `p_fail <= low_risk_max` |
| 57 | - medium: `p_fail <= medium_risk_max` |
| 58 | - high: otherwise |
| 59 | |
| 60 | Action mapping when the controller is explicitly enabled: |
| 61 | |
| 62 | - low -> `NoIntervention` |
| 63 | - medium -> `TargetedContextRefresh` |
| 64 | - high + severe dynamics (`min_slack <= severe_min_slack` or `violation_ratio >= severe_violation_ratio`) -> `VerifyAndReplan` |
| 65 | - otherwise high -> `VerifyWithToolReplay` |
| 66 | |
| 67 | ## Checkpoints |
| 68 | |
| 69 | When enabled, the engine evaluates controller policy at: |
| 70 | |
| 71 | 1. Pre-request checkpoint (before `MessageRequest` assembly). |
| 72 | 2. Post-tool checkpoint (after tool result append). |
| 73 | 3. Error-escalation checkpoint (tool error streak path). |
| 74 | |
| 75 | ## Interventions |
| 76 | |
| 77 | Interventions are not part of the default v0.7.5 V4 path. The default path is: |
| 78 | append messages, preserve prefix-cache reuse, suggest manual `/compact` near |
| 79 | real model pressure, and use overflow recovery only if the request would exceed |
| 80 | the model input budget. |
| 81 | |
| 82 | ### `TargetedContextRefresh` |
| 83 | |
| 84 | - Runs compaction (`compact_messages_safe`) when possible. |
| 85 | - Falls back to local trim if compaction path fails. |
| 86 | - Persists canonical state. |
| 87 | - Replaces long-tail active context with compact canonical prompt + memory pointer. |
| 88 | |
| 89 | ### `VerifyWithToolReplay` |
| 90 | |
| 91 | - Replays one read-only critical tool call from recent turn context. |
| 92 | - Appends verification note with pass/fail + diff summary. |
| 93 | - On replay conflict/error, marks escalation candidate and disables replay for current turn. |
| 94 | |
| 95 | ### `VerifyAndReplan` |
| 96 | |
| 97 | - Persists canonical snapshot. |
| 98 | - Clears volatile prompt tail while preserving latest user ask and latest verification note. |
| 99 | - Injects canonical replan instruction into system prompt. |
| 100 | - Continues turn loop from compact canonical state. |
| 101 | |
| 102 | ## Safety Controls |
| 103 | |
| 104 | - Max one intervention per turn. |
| 105 | - Cooldowns for refresh and replan. |
| 106 | - Replay budget per turn (`max_replay_per_turn`). |
| 107 | - Fail-open behavior when controller inputs are unavailable. |
| 108 | - Compaction/replay failures are logged; turn continues. |
| 109 | |
| 110 | ## Memory Store |
| 111 | |
| 112 | Path: |
| 113 | |
| 114 | - `DEEPSEEK_CAPACITY_MEMORY_DIR` (if set) |
| 115 | - otherwise `~/.deepseek/memory/<session_id>.jsonl` |
| 116 | - fallback: `<workspace>/.deepseek/memory/<session_id>.jsonl` when home path is unavailable/unwritable |
| 117 | |
| 118 | Record fields: |
| 119 | |
| 120 | - `id`, `ts`, `turn_index`, `action_trigger` |
| 121 | - `h_hat`, `c_hat`, `slack`, `risk_band` |
| 122 | - `canonical_state` |
| 123 | - `source_message_ids` |
| 124 | - optional `replay_info` |
| 125 | |
| 126 | Loader utility supports fetching last `K` snapshots for rehydration. |
| 127 | |
| 128 | ## Configuration |
| 129 | |
| 130 | `[capacity]` keys: |
| 131 | |
| 132 | - `enabled` (default `false`) |
| 133 | - `low_risk_max` (default `0.50`) |
| 134 | - `medium_risk_max` (default `0.62`) |
| 135 | - `severe_min_slack` (default `-0.25`) |
| 136 | - `severe_violation_ratio` (default `0.40`) |
| 137 | - `refresh_cooldown_turns` (default `6`) |
| 138 | - `replan_cooldown_turns` (default `5`) |
| 139 | - `max_replay_per_turn` (default `1`) |
| 140 | - `min_turns_before_guardrail` (default `4`) |
| 141 | - `profile_window` (default `8`) |
| 142 | - `deepseek_v3_2_chat_prior` (default `3.9`) |
| 143 | - `deepseek_v3_2_reasoner_prior` (default `4.1`) |
| 144 | - `deepseek_v4_pro_prior` (default `3.5`) |
| 145 | - `deepseek_v4_flash_prior` (default `4.2`) |
| 146 | - `fallback_default_prior` (default `3.8`) |
| 147 | |
| 148 | Equivalent environment overrides are available with `DEEPSEEK_CAPACITY_*`. |
| 149 |