Skip to content

Commit 7733a2a

Browse files
ualtinokAlfonso
andcommitted
docs(#347): cache_ttl wording — MC's own deferral gate, not provider cache control
cache_ttl decides how long Magic Context ASSUMES a provider's cached prefix stays valid; it has no effect on the provider's actual cache lifetime. The previous wording ('matches most providers', 'Cache TTL' unqualified, 'never expires (always-warm lane)') composed into a wrong mental model that the setting controls the provider's cache. Reword all three surfaces the issue names plus the TUI/Pi status twins: - CONFIGURATION.md: 'matches most providers' -> states it is MC's own deferral gate and does not change the provider's cache lifetime; the default 5m matches Anthropic's default TTL. The 'never' sentinel now says MC never ASSUMES expiry, and notes provider-side extended TTL is a separate request-level concern (cache_control: { ttl }). - magic-context.ts .describe(): leads with the scope (MC-side assumption, does not extend provider TTL) and qualifies 'never' as MC never assuming expiry for externally-kept-warm lanes. - execute-status.ts / tui/index.tsx / tui-compiled / pi status-dialog: 'never expires (always-warm lane)' -> 'never (MC never assumes expiry — external cache-keep)'. Regenerated assets/magic-context.schema.json and the docs-site config reference from the Zod schema (generator-owned). Updated the execute-status test to assert the new wording. No rename of the key (breaking config change); wording only. Co-Authored-By: Alfonso <[email protected]>
1 parent 04a3f91 commit 7733a2a

9 files changed

Lines changed: 14 additions & 11 deletions

File tree

‎CONFIGURATION.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ Magic Context uses the runtime's built-in SQLite: `bun:sqlite` under Bun (OpenCo
119119

120120
LLM providers cache conversation prefixes server-side. The cache window depends on your provider and subscription tier — Claude Pro offers 5 minutes, Max offers 1 hour, and pricing for cached vs. uncached tokens differs between API and subscription usage.
121121

122-
Magic Context defers all mutations until the cached prefix expires. The default `cache_ttl` of `"5m"` matches most providers. You can tune it:
122+
Magic Context defers all mutations until the cached prefix expires. `cache_ttl` is how long Magic Context *assumes* a provider's cached prefix stays valid — it is MC's own deferral gate, not a control over the provider's cache. It does not change the provider's actual cache lifetime. The default `"5m"` matches Anthropic's default TTL. You can tune it:
123123

124124
```jsonc
125125
{
@@ -140,13 +140,16 @@ Per-model overrides for mixed-model workflows:
140140

141141
Supported formats: `"30s"`, `"5m"`, `"1h"`.
142142

143-
**`"never"` sentinel:** set `cache_ttl` to `"never"` to disable the idle-TTL heuristic entirely. Both consumers —
143+
**`"never"` sentinel:** set `cache_ttl` to `"never"` to mean Magic Context *never assumes* the cached prefix expires — it disables the idle-TTL heuristic entirely. Both consumers —
144144
the scheduler (which converts defer passes to execute after TTL expiry) and the HARD-fold trigger (which folds
145145
m[1] into m[0] on a "free" prefix rebuild) — no longer act on idle time. Use this on lanes kept warm by an
146146
external keepwarm mechanism (prewarm proxies, dedicated cache-keep tools) where the idle heuristic false-positives
147147
and causes paid full-prefix cache-writes. After a genuine cold start (e.g. the keepwarm process died), MC
148148
won't detect the free-fold window on that lane — mutations then apply only at the execute threshold.
149149

150+
`"never"` only changes MC's assumption; it does not extend the provider's cache lifetime. Provider-side extended
151+
TTL is a separate request-level concern (`cache_control: { ttl: "1h" }` in the request body).
152+
150153
Higher-tier models with longer cache windows benefit from a longer TTL. Setting it too low wastes cache hits. Setting it too high delays reduction on long sessions.
151154

152155
---

‎assets/magic-context.schema.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1097,7 +1097,7 @@
10971097
},
10981098
"cache_ttl": {
10991099
"default": "5m",
1100-
"description": "Cache TTL: string (e.g. \"5m\", \"1h\", \"30s\") or per-model object ({ default: \"5m\", \"model-id\": \"10m\" }). Set to \"never\" for lanes kept warm by an external keepwarm proxy — disables the idle-TTL heuristic so MC never initiates a rebuild based on elapsed time.",
1100+
"description": "How long Magic Context assumes the provider's cached prefix stays valid. This is MC's own deferral gate — it does not change the provider's actual cache lifetime. String (e.g. \"5m\", \"1h\", \"30s\") or per-model object ({ default: \"5m\", \"model-id\": \"10m\" }). Set to \"never\" to mean MC never assumes expiry (for lanes kept warm externally by a cache-keep tool) — disables the idle-TTL heuristic so MC never initiates a rebuild based on elapsed time. Provider-side extended TTL is a separate request-level concern (cache_control: { ttl } in the request body).",
11011101
"anyOf": [
11021102
{
11031103
"type": "string"

‎packages/docs/src/content/docs/reference/configuration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ When and how aggressively Magic Context manages the session's context window. Pe
6262

6363
| Key | Type | Default | Description |
6464
|---|---|---|---|
65-
| `cache_ttl` | string \\| map<string, string> | `"5m"` | Cache TTL: string (e.g. "5m", "1h", "30s") or per-model object ({ default: "5m", "model-id": "10m" }). Set to "never" for lanes kept warm by an external keepwarm proxy — disables the idle-TTL heuristic so MC never initiates a rebuild based on elapsed time. |
65+
| `cache_ttl` | string \\| map<string, string> | `"5m"` | How long Magic Context assumes the provider's cached prefix stays valid. This is MC's own deferral gate — it does not change the provider's actual cache lifetime. String (e.g. "5m", "1h", "30s") or per-model object ({ default: "5m", "model-id": "10m" }). Set to "never" to mean MC never assumes expiry (for lanes kept warm externally by a cache-keep tool) — disables the idle-TTL heuristic so MC never initiates a rebuild based on elapsed time. Provider-side extended TTL is a separate request-level concern (cache_control: { ttl } in the request body). |
6666
| `output_reserve` | number (0–) \\| map<string, number (0–)> | — | User-only output-token reservation override. Number or per-model object ({ default: 16384, "provider/model": 8192 }); 0 disables reservation. Takes precedence over every derived source: an explicit value here always wins against catalog output limits, provider window-geometry facts, and the 25%-of-context fallback (usable window = context window minus this reserve). When unset, Magic Context reserves the catalog output limit (capped at 25% of context) for shared-window providers and keeps proven separate-quota Google/Gemini windows unchanged. |
6767
| `execute_threshold_percentage` | number (20–90) \\| map<string, number (20–90)> | `65` | Context percentage that forces queued operations to execute. Number or per-model object ({ default: 65, "provider/model": 45 }). Values above 90 are rejected because the runtime caps at 90% of the output-reserved safe window (MAX_EXECUTE_THRESHOLD). Default: DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE |
6868
| `execute_threshold_tokens` | object | — | Absolute token thresholds per model. When matched, overrides execute_threshold_percentage for that model. Accepts `default` for all models or per-model keys. Values above 90% × context_limit are clamped with a warning log. Min 5_000, max 2_000_000. |

‎packages/pi-plugin/src/dialogs/status-dialog.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -351,7 +351,7 @@ function renderInner(
351351
s.cacheExpired
352352
? theme.fg("warning", "expired")
353353
: s.cacheRemainingMs === Number.POSITIVE_INFINITY
354-
? "never expires (always-warm lane)"
354+
? "never (MC never assumes expiry — external cache-keep)"
355355
: `${Math.round(s.cacheRemainingMs / 1000)}s remaining`
356356
}`,
357357
);

‎packages/plugin/src/config/schema/magic-context.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -709,7 +709,7 @@ export const MagicContextConfigSchema = z
709709
.union([z.string(), z.object({ default: z.string() }).catchall(z.string())])
710710
.default("5m")
711711
.describe(
712-
'Cache TTL: string (e.g. "5m", "1h", "30s") or per-model object ({ default: "5m", "model-id": "10m" }). Set to "never" for lanes kept warm by an external keepwarm proxy — disables the idle-TTL heuristic so MC never initiates a rebuild based on elapsed time.',
712+
'How long Magic Context assumes the provider\'s cached prefix stays valid. This is MC\'s own deferral gate — it does not change the provider\'s actual cache lifetime. String (e.g. "5m", "1h", "30s") or per-model object ({ default: "5m", "model-id": "10m" }). Set to "never" to mean MC never assumes expiry (for lanes kept warm externally by a cache-keep tool) — disables the idle-TTL heuristic so MC never initiates a rebuild based on elapsed time. Provider-side extended TTL is a separate request-level concern (cache_control: { ttl } in the request body).'
713713
),
714714
prompt_surface: PromptSurfaceConfigSchema.default({ default: "full" }).describe(
715715
"Prompt-surface presets: default is full; models use bare model IDs, provider/model, or provider/* routing keys. Guidance and tool-description overrides are user-level only. On OpenCode and Pi, per-model routing applies to the guidance block only: tool descriptions are registered once per process, so they follow the default preset (a v1 plugin-surface limitation; per-model tool descriptions are planned for the OpenCode v2 plugin API once the SDK stabilizes).",

‎packages/plugin/src/hooks/magic-context/execute-status.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -115,8 +115,8 @@ describe("executeStatus", () => {
115115
const status = executeStatus(db, SESSION_ID, 20);
116116

117117
expect(status).toContain("- Configured: never");
118-
expect(status).toContain("- Remaining: never expires (always-warm lane)");
119-
expect(status).toContain("never expires");
118+
expect(status).toContain("- Remaining: never (MC never assumes expiry — external cache-keep)");
119+
expect(status).toContain("never (MC never assumes expiry");
120120
expect(status).not.toContain("Infinity");
121121
db.close();
122122
});

‎packages/plugin/src/hooks/magic-context/execute-status.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,7 @@ export function executeStatus(
141141
"### Cache TTL",
142142
`- Configured: ${meta.cacheTtl}`,
143143
`- Last response: ${meta.lastResponseTime > 0 ? `${Math.round(elapsed / 1000)}s ago` : "never"}`,
144-
`- Remaining: ${cacheExpired ? "expired" : ttlMs === Number.POSITIVE_INFINITY ? "never expires (always-warm lane)" : `${Math.round(remainingMs / 1000)}s`}`,
144+
`- Remaining: ${cacheExpired ? "expired" : ttlMs === Number.POSITIVE_INFINITY ? "never (MC never assumes expiry — external cache-keep)" : `${Math.round(remainingMs / 1000)}s`}`,
145145
`- Queue will auto-execute: ${cacheExpired ? "yes (cache expired)" : ttlMs === Number.POSITIVE_INFINITY ? `when context >= ${executeThresholdPercentage}%` : `when TTL expires or context >= ${executeThresholdPercentage}%`}`,
146146
"",
147147
"### Execute Threshold",

‎packages/plugin/src/tui-compiled/index.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -671,7 +671,7 @@ const StatusDialog = props => {
671671
},
672672
l: "Remaining",
673673
get v() {
674-
return _$memo(() => !!s().cacheExpired)() ? "expired" : _$memo(() => !!s().cacheNeverExpires)() ? "never expires (always-warm lane)" : `${Math.round(s().cacheRemainingMs / 1000)}s`;
674+
return _$memo(() => !!s().cacheExpired)() ? "expired" : _$memo(() => !!s().cacheNeverExpires)() ? "never (MC never assumes expiry — external cache-keep)" : `${Math.round(s().cacheRemainingMs / 1000)}s`;
675675
},
676676
get fg() {
677677
return _$memo(() => !!s().cacheExpired)() ? t().warning : t().textMuted;

‎packages/plugin/src/tui/index.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -356,7 +356,7 @@ const StatusDialog = (props: { api: TuiPluginApi; s: StatusDetail }) => {
356356
</box>
357357
<R t={t()} l="Configured" v={s().cacheTtl} />
358358
<R t={t()} l="Last response" v={s().lastResponseTime > 0 ? `${Math.round(elapsed() / 1000)}s ago` : "never"} />
359-
<R t={t()} l="Remaining" v={s().cacheExpired ? "expired" : s().cacheNeverExpires ? "never expires (always-warm lane)" : `${Math.round(s().cacheRemainingMs / 1000)}s`} fg={s().cacheExpired ? t().warning : t().textMuted} />
359+
<R t={t()} l="Remaining" v={s().cacheExpired ? "expired" : s().cacheNeverExpires ? "never (MC never assumes expiry — external cache-keep)" : `${Math.round(s().cacheRemainingMs / 1000)}s`} fg={s().cacheExpired ? t().warning : t().textMuted} />
360360
<R t={t()} l="Auto-execute" v={s().cacheExpired ? "yes (expired)" : s().cacheNeverExpires ? `at ≥${formatThresholdPercent(s().executeThreshold)}%` : `at TTL or ≥${formatThresholdPercent(s().executeThreshold)}%`} fg={t().textMuted} />
361361
<box marginTop={1}>
362362
<text fg={t().text}><b>Memory</b></text>

0 commit comments

Comments
 (0)