Skip to content

Commit 886f6eb

Browse files
committed
fix: close council audit findings on budget derivation
Addresses all 8 actionable findings from the solo Athena council audit of the prior two commits (emergency drop bypass + budget derivation). - #1 (unanimous, MEDIUM): `historianChunkTokens` was cached once per hook while RPC/TUI re-derived fresh on each invocation. Same trigger could produce different chunk sizes depending on source. Unified by turning the hook's value into a `getHistorianChunkTokens` thunk called at each historian spawn site. - #2 + #8 (MEDIUM + LOW): `modelContextLimitsCache` was never populated in production. Removed the dead field from `MagicContextDeps.config`, `EventHandlerDeps.config`, `resolveContextLimit`, and `resolveHistorianContextLimit`. Context limits are resolved through `getModelsDevContextLimit` which already reads both models.dev cache and custom `provider.*.models.*.limit.context` from opencode.json. Dropped the unsafe `(config as { modelContextLimitsCache? }).X` casts in rpc-handlers.ts and tui-action-consumer.ts. - #3 (MEDIUM, latent coupling): `shouldApplyPendingOps` only bypassed the `!compartmentRunning` gate but still required `scheduler==="execute"`. If `MAX_EXECUTE_THRESHOLD` were ever raised above 85%, heuristic cleanup would fire at emergency threshold while pending ops silently stopped materializing. Added `forceMaterialization` to the first clause so the emergency bypass is self-sufficient. - #4 (MAJORITY, MEDIUM): `pickHistorianModelKey` returned only the first fallback chain entry, silently ignoring malformed (provider-less) overrides. Rewrote `resolveHistorianContextLimit` to: - use an explicit `provider/model` override as-is; - warn and fall through for provider-less overrides (never silently pick a wrong default); - scan the full expanded fallback chain and use the MINIMUM resolved context, protecting against OpenCode falling back to a smaller-context entry. - #7 (LOW, clarity): Comment on the emergency bypass overstated safety as "SQLite WAL-safe." Actual safety comes from disjoint databases (historian reads opencode.db, drops write context.db). Rewrote the comment to reflect the true invariant plus `queueDropsForCompartmentalizedMessages` idempotency. Also tightened the pending-op read gate to include `forceMaterialization` so queued ops are visible during emergency bypass even if the scheduler returned "defer" in edge configurations. Tests: - Removed in-test `modelContextLimitsCache` fixtures from `event-resolvers.test.ts` and `event-handler.test.ts` (no longer part of the API). - Added three targeted tests for `resolveHistorianContextLimit` (no-override chain scan, explicit override, provider-less warn+fallthrough). - Made `TransformDeps.getHistorianChunkTokens` optional with a 20K default so existing tests keep working without explicit threading. Verified: 479 plugin tests pass, 13 e2e tests pass, typecheck clean.
1 parent 08a26df commit 886f6eb

11 files changed

Lines changed: 155 additions & 127 deletions

‎packages/plugin/src/hooks/magic-context/derive-budgets.test.ts‎

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
11
/// <reference types="bun-types" />
22

33
import { describe, expect, it } from "bun:test";
4-
import { deriveHistorianChunkTokens, deriveTriggerBudget } from "./derive-budgets";
4+
import {
5+
deriveHistorianChunkTokens,
6+
deriveTriggerBudget,
7+
resolveHistorianContextLimit,
8+
} from "./derive-budgets";
59

610
describe("deriveTriggerBudget", () => {
711
it("scales with main_context × execute_threshold × 0.05", () => {
@@ -77,3 +81,38 @@ describe("deriveHistorianChunkTokens", () => {
7781
expect(deriveHistorianChunkTokens(Number.NaN)).toBe(8_000);
7882
});
7983
});
84+
85+
describe("resolveHistorianContextLimit", () => {
86+
it("returns a positive context limit with no override (scans fallback chain)", () => {
87+
// No override — should traverse the fallback chain and return the minimum
88+
// known context across entries (or 128K if nothing resolves).
89+
const limit = resolveHistorianContextLimit();
90+
expect(limit).toBeGreaterThan(0);
91+
expect(limit).toBeLessThanOrEqual(1_000_000);
92+
});
93+
94+
it("returns a positive context limit for an explicit provider/model override", () => {
95+
// Explicit override with / form. Whether or not models.dev knows this
96+
// model, the function should never return 0 or NaN.
97+
const limit = resolveHistorianContextLimit("anthropic/claude-sonnet-4-6");
98+
expect(limit).toBeGreaterThan(0);
99+
expect(Number.isFinite(limit)).toBe(true);
100+
});
101+
102+
it("falls through to chain for provider-less override and returns a positive value", () => {
103+
// Provider-less override should warn and fall through to the chain
104+
// (rather than silently returning DEFAULT and losing the derivation).
105+
const originalWarn = console.warn;
106+
let warnedWith: string | undefined;
107+
console.warn = (msg: unknown) => {
108+
warnedWith = typeof msg === "string" ? msg : String(msg);
109+
};
110+
try {
111+
const limit = resolveHistorianContextLimit("llama3-32k");
112+
expect(limit).toBeGreaterThan(0);
113+
expect(warnedWith).toContain("llama3-32k");
114+
} finally {
115+
console.warn = originalWarn;
116+
}
117+
});
118+
});

‎packages/plugin/src/hooks/magic-context/derive-budgets.ts‎

Lines changed: 49 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -75,48 +75,62 @@ export function deriveHistorianChunkTokens(historianContextLimit: number): numbe
7575
}
7676

7777
/**
78-
* Resolve the historian model's context limit.
78+
* Resolve the historian model's context limit for chunk budget sizing.
7979
*
80-
* Priority:
81-
* 1. Explicit `historian.model` config ("provider/model-id")
82-
* 2. First entry of the historian fallback chain
83-
* 3. Conservative 128K default
80+
* Behavior:
81+
* - If `historianModelOverride` is a full `provider/model-id` → use that model's
82+
* context directly. This honors explicit user intent.
83+
* - If the override is set but lacks `/` (e.g. `"llama3-32k"`) → warn and fall
84+
* through to the fallback chain, since we can't look up models without a
85+
* provider and silently ignoring would produce incorrect chunk sizes.
86+
* - If no override → scan the expanded fallback chain (all `provider/model`
87+
* combinations OpenCode might try) and use the MINIMUM resolved context.
88+
* This is defensive: if the first-choice model is unavailable and OpenCode
89+
* falls back to a smaller-context entry, the chunk budget is still safe.
90+
* - If neither models.dev nor opencode.json custom providers know the model,
91+
* fall back to 128K as a conservative default.
92+
*
93+
* Context limits are resolved through `getModelsDevContextLimit`, which reads
94+
* both OpenCode's models.dev cache and custom `provider.*.models.*.limit.context`
95+
* entries from `opencode.json(c)`.
8496
*/
85-
export function resolveHistorianContextLimit(
86-
historianModelOverride?: string,
87-
modelContextLimitsCache?: Map<string, number>,
88-
): number {
89-
const modelKey = pickHistorianModelKey(historianModelOverride);
90-
if (!modelKey) {
91-
return DEFAULT_HISTORIAN_CONTEXT_FALLBACK;
92-
}
93-
94-
const [providerID, ...rest] = modelKey.split("/");
95-
const modelID = rest.join("/");
96-
if (!providerID || !modelID) {
97+
export function resolveHistorianContextLimit(historianModelOverride?: string): number {
98+
// Explicit override with full provider/model form — user intent wins.
99+
if (typeof historianModelOverride === "string" && historianModelOverride.includes("/")) {
100+
const [providerID, ...rest] = historianModelOverride.split("/");
101+
const modelID = rest.join("/");
102+
if (providerID && modelID) {
103+
const limit = getModelsDevContextLimit(providerID, modelID);
104+
if (typeof limit === "number" && limit > 0) return limit;
105+
}
97106
return DEFAULT_HISTORIAN_CONTEXT_FALLBACK;
98107
}
99108

100-
// User-configured override wins
101-
const userOverride = modelContextLimitsCache?.get(modelKey);
102-
if (typeof userOverride === "number" && userOverride > 0) {
103-
return userOverride;
104-
}
105-
106-
const fromModelsDev = getModelsDevContextLimit(providerID, modelID);
107-
if (typeof fromModelsDev === "number" && fromModelsDev > 0) {
108-
return fromModelsDev;
109+
// Warn-and-fall-through for malformed overrides (Finding #4 sub-fix).
110+
if (typeof historianModelOverride === "string" && historianModelOverride.trim() !== "") {
111+
// Intentional: this is a config error we surface at log level, not a crash,
112+
// because the fallback chain still produces a workable budget.
113+
// eslint-disable-next-line no-console
114+
console.warn(
115+
`[magic-context] historian.model "${historianModelOverride}" lacks provider prefix ("provider/model-id"); using fallback chain for chunk-budget derivation.`,
116+
);
109117
}
110118

111-
return DEFAULT_HISTORIAN_CONTEXT_FALLBACK;
112-
}
113-
114-
function pickHistorianModelKey(override?: string): string | undefined {
115-
if (typeof override === "string" && override.includes("/")) {
116-
return override;
117-
}
119+
// Defensive minimum across the full expanded chain. This protects against
120+
// the first-choice model being unavailable and OpenCode falling back to a
121+
// smaller-context entry that would overflow with the larger chunk budget.
118122
const chain = AGENT_MODEL_REQUIREMENTS[HISTORIAN_AGENT]?.fallbackChain;
119-
if (!chain || chain.length === 0) return undefined;
123+
if (!chain || chain.length === 0) return DEFAULT_HISTORIAN_CONTEXT_FALLBACK;
120124
const expanded = expandFallbackChain(chain);
121-
return expanded[0];
125+
126+
let minLimit: number | undefined;
127+
for (const key of expanded) {
128+
const [providerID, ...rest] = key.split("/");
129+
const modelID = rest.join("/");
130+
if (!providerID || !modelID) continue;
131+
const limit = getModelsDevContextLimit(providerID, modelID);
132+
if (typeof limit !== "number" || limit <= 0) continue;
133+
if (minLimit === undefined || limit < minLimit) minLimit = limit;
134+
}
135+
return minLimit ?? DEFAULT_HISTORIAN_CONTEXT_FALLBACK;
122136
}

‎packages/plugin/src/hooks/magic-context/event-handler.test.ts‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,6 @@ function createDeps(contextUsageMap: Map<string, { usage: ContextUsage; updatedA
9292
config: {
9393
protected_tags: 5,
9494
cache_ttl: "5m" as string | Record<string, string>,
95-
modelContextLimitsCache: undefined as Map<string, number> | undefined,
9695
},
9796
tagger: {
9897
assignTag: mock(() => 0),
@@ -256,12 +255,11 @@ describe("createEventHandler", () => {
256255
expect(entry?.usage.inputTokens).toBe(124_000);
257256
});
258257

259-
it("uses provider/model-specific context limits and cache ttl", async () => {
258+
it("resolves model-specific cache ttl via per-model config", async () => {
260259
useTempDataHome("context-event-provider-model-");
261260
const contextUsageMap = new Map<string, { usage: ContextUsage; updatedAt: number }>();
262261
const deps = createDeps(contextUsageMap);
263262
deps.config.cache_ttl = { default: "5m", "gpt-4o": "1m" };
264-
deps.config.modelContextLimitsCache = new Map([["openai/gpt-4o", 400_000]]);
265263
const handler = createEventHandler(deps);
266264

267265
await handler({
@@ -280,8 +278,8 @@ describe("createEventHandler", () => {
280278
},
281279
});
282280

283-
const usage = contextUsageMap.get("ses-model");
284-
expect(usage?.usage.percentage).toBeCloseTo(50, 5);
281+
// Context-limit resolution is covered by event-resolvers.test.ts; here we
282+
// validate that per-model cache_ttl is applied via the shared event path.
285283
expect(getOrCreateSessionMeta(openDatabase(), "ses-model").cacheTtl).toBe("1m");
286284
});
287285

‎packages/plugin/src/hooks/magic-context/event-handler.ts‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,6 @@ export interface EventHandlerDeps {
6969
clear_reasoning_age?: number;
7070
execute_threshold_percentage?: number | { default: number; [modelKey: string]: number };
7171
cache_ttl: CacheTtlConfig;
72-
modelContextLimitsCache?: Map<string, number>;
7372
commit_cluster_trigger?: { enabled: boolean; min_clusters: number };
7473
};
7574
tagger: Tagger;
@@ -262,9 +261,7 @@ export function createEventHandler(deps: EventHandlerDeps) {
262261
(info.tokens?.input ?? 0) +
263262
(info.tokens?.cache?.read ?? 0) +
264263
(info.tokens?.cache?.write ?? 0);
265-
const contextLimit = resolveContextLimit(info.providerID, info.modelID, {
266-
modelContextLimitsCache: deps.config.modelContextLimitsCache,
267-
});
264+
const contextLimit = resolveContextLimit(info.providerID, info.modelID);
268265
const percentage =
269266
contextLimit > 0 ? (totalInputTokens / contextLimit) * 100 : 0;
270267

‎packages/plugin/src/hooks/magic-context/event-resolvers.test.ts‎

Lines changed: 14 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -8,52 +8,31 @@ import {
88

99
describe("event-resolvers", () => {
1010
describe("resolveContextLimit", () => {
11-
it("returns model-specific cache limit for non-anthropic providers", () => {
12-
//#given
13-
const config = {
14-
modelContextLimitsCache: new Map([["openai/gpt-4o", 300_000]]),
15-
};
16-
17-
//#when
18-
const limit = resolveContextLimit("openai", "gpt-4o", config);
19-
20-
//#then
21-
expect(limit).toBe(300_000);
22-
});
23-
24-
it("returns model-specific cache limit for anthropic when user overrides", () => {
25-
//#given — user explicitly sets a custom limit in their provider config
26-
const config = {
27-
modelContextLimitsCache: new Map([["anthropic/claude-opus-4-6", 500_000]]),
28-
};
29-
30-
//#when
31-
const limit = resolveContextLimit("anthropic", "claude-opus-4-6", config);
32-
33-
//#then
34-
expect(limit).toBe(500_000);
35-
});
36-
37-
it("resolves anthropic context from models.dev when no cache entry exists", () => {
38-
//#given
39-
const config = {
40-
modelContextLimitsCache: new Map<string, number>(),
41-
};
11+
// resolveContextLimit reads from getModelsDevContextLimit (which overlays
12+
// opencode.json custom provider limits on top of the models.dev cache).
13+
// The tests below validate the fallback-to-default path. The models.dev
14+
// integration is covered by models-dev-cache tests.
4215

16+
it("resolves anthropic context from models.dev when available", () => {
4317
//#when — models.dev may return 200K (real limit) or 128K (default if no models.json)
44-
const limit = resolveContextLimit("anthropic", "claude-opus-4-5", config);
18+
const limit = resolveContextLimit("anthropic", "claude-opus-4-5");
4519

4620
//#then — should NOT be 1M; uses models.dev real limit or conservative default
4721
expect(limit).toBeLessThanOrEqual(200_000);
4822
expect(limit).toBeGreaterThan(0);
4923
});
5024

5125
it("returns default for missing provider", () => {
52-
//#given
53-
const config = { modelContextLimitsCache: new Map<string, number>() };
26+
//#when
27+
const limit = resolveContextLimit(undefined, "gpt-4o");
28+
29+
//#then
30+
expect(limit).toBe(128_000);
31+
});
5432

33+
it("returns default for unknown provider/model not in models.dev or opencode.json", () => {
5534
//#when
56-
const limit = resolveContextLimit(undefined, "gpt-4o", config);
35+
const limit = resolveContextLimit("unknown-provider", "unknown-model-xyz");
5736

5837
//#then
5938
expect(limit).toBe(128_000);

‎packages/plugin/src/hooks/magic-context/event-resolvers.ts‎

Lines changed: 4 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -7,33 +7,22 @@ type CacheTtlConfig = string | Record<string, string>;
77
export function resolveContextLimit(
88
providerID: string | undefined,
99
modelID: string | undefined,
10-
config: {
11-
modelContextLimitsCache?: Map<string, number>;
12-
},
1310
): number {
1411
if (!providerID) {
1512
return DEFAULT_CONTEXT_LIMIT;
1613
}
1714

18-
// 1. Check user-configured model-specific limits first (highest priority)
19-
if (modelID) {
20-
const modelSpecific = config.modelContextLimitsCache?.get(`${providerID}/${modelID}`);
21-
if (typeof modelSpecific === "number" && modelSpecific > 0) {
22-
return modelSpecific;
23-
}
24-
}
25-
26-
// 2. Check OpenCode's models.dev cache for accurate per-model limits.
27-
// This file is maintained by OpenCode at ~/.cache/opencode/models.json
28-
// and contains limit.context for every known provider/model combination.
15+
// Read from OpenCode's models.dev cache file at ~/.cache/opencode/models.json.
16+
// `getModelsDevContextLimit` also overlays custom `provider.*.models.*.limit.context`
17+
// entries from the user's opencode.json(c), so explicit user overrides are honored.
2918
if (modelID) {
3019
const modelsDevLimit = getModelsDevContextLimit(providerID, modelID);
3120
if (modelsDevLimit !== undefined) {
3221
return modelsDevLimit;
3322
}
3423
}
3524

36-
// 3. Conservative default for models not found in models.dev
25+
// Conservative default for models not in models.dev and not configured.
3726
return DEFAULT_CONTEXT_LIMIT;
3827
}
3928

‎packages/plugin/src/hooks/magic-context/hook.ts‎

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,6 @@ export interface MagicContextDeps {
6969
iteration_nudge_threshold?: number;
7070
execute_threshold_percentage?: number | { default: number; [modelKey: string]: number };
7171
cache_ttl: string | Record<string, string>;
72-
modelContextLimitsCache?: Map<string, number>;
7372

7473
historian?: z.infer<typeof AgentOverrideConfigSchema>;
7574
history_budget_percentage?: number;
@@ -154,12 +153,11 @@ export function createMagicContextHook(deps: MagicContextDeps) {
154153

155154
// Derive historian chunk budget from the historian model's own context window.
156155
// Historian is a single-shot summarizer, so its input is bounded by its OWN
157-
// context, not the main session model's. Computed once per hook instance.
158-
const historianContextLimit = resolveHistorianContextLimit(
159-
deps.config.historian?.model,
160-
deps.config.modelContextLimitsCache,
161-
);
162-
const historianChunkTokens = deriveHistorianChunkTokens(historianContextLimit);
156+
// context, not the main session model's. Re-derived per historian invocation
157+
// (matching RPC/TUI paths) so config/model changes take effect without
158+
// restart, and so all trigger sources produce consistent chunk sizes.
159+
const getHistorianChunkTokens = (): number =>
160+
deriveHistorianChunkTokens(resolveHistorianContextLimit(deps.config.historian?.model));
163161

164162
const nudgePlacements = createNudgePlacementStore(db);
165163
const flushedSessions = new Set<string>();
@@ -207,7 +205,7 @@ export function createMagicContextHook(deps: MagicContextDeps) {
207205
injectionBudgetTokens: deps.config.memory.injection_budget_tokens,
208206
}
209207
: undefined,
210-
historianChunkTokens,
208+
getHistorianChunkTokens,
211209
historyBudgetPercentage: deps.config.history_budget_percentage,
212210
executeThresholdPercentage: deps.config.execute_threshold_percentage,
213211
historianTimeoutMs: deps.config.historian_timeout_ms ?? DEFAULT_HISTORIAN_TIMEOUT_MS,
@@ -305,7 +303,7 @@ export function createMagicContextHook(deps: MagicContextDeps) {
305303
client: deps.client,
306304
db,
307305
sessionId,
308-
historianChunkTokens,
306+
historianChunkTokens: getHistorianChunkTokens(),
309307
historianTimeoutMs:
310308
deps.config.historian_timeout_ms ?? DEFAULT_HISTORIAN_TIMEOUT_MS,
311309
directory: deps.directory,

‎packages/plugin/src/hooks/magic-context/transform-postprocess-phase.ts‎

Lines changed: 20 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -109,24 +109,35 @@ export function runPostTransformPhase(args: RunPostTransformPhaseArgs): void {
109109
// Emergency bypass: at forceMaterialization threshold (>=85%), allow both
110110
// pending-op materialization and heuristic cleanup to run even while a
111111
// historian run is in progress. This is safe because:
112-
// - Historian reads raw messages from opencode.db and writes to
113-
// compartments/session_facts/memories tables. It does not read or
114-
// write `tags` or `pending_ops`.
115-
// - Drops mutate `tags` and `pending_ops` only.
116-
// - The only shared mutation point is `queueDropsForCompartmentalizedMessages`,
117-
// which historian calls AFTER publication from a DB transaction — safe
118-
// against concurrent reads in SQLite WAL mode.
112+
// - Historian reads raw OpenCode messages from opencode.db (read-only).
113+
// It does not touch the plugin's context.db where tags/pending_ops live.
114+
// The two databases are fully disjoint on the read/write side.
115+
// - Drops mutate tags + pending_ops in context.db only.
116+
// - The only shared mutation point is historian's call to
117+
// `queueDropsForCompartmentalizedMessages` after it publishes, which
118+
// writes to context.db's tags/pending_ops in a separate transaction.
119+
// That function is idempotent against already-dropped tags (filters by
120+
// `tag.status !== "active"`), so any ordering with the emergency bypass
121+
// is benign.
119122
// Without this bypass, fast autonomous loops with sustained pressure can
120123
// keep compartmentRunning=true across every turn, so drops queued for
121124
// already-published compartments accumulate forever and context overflows.
122125
// At emergency levels we prioritize overflow prevention over cache stability.
123126
const emergencyBypassCompartmentGate = forceMaterialization;
124127
const shouldReadPendingOps =
125-
isExplicitFlush || args.schedulerDecision === "execute" || compartmentRunning;
128+
isExplicitFlush ||
129+
args.schedulerDecision === "execute" ||
130+
forceMaterialization ||
131+
compartmentRunning;
126132
const pendingOps = shouldReadPendingOps ? getPendingOps(args.db, args.sessionId) : [];
127133
const hasPendingUserOps = pendingOps.length > 0;
134+
// Finding #3: include `forceMaterialization` so the emergency bypass is
135+
// self-sufficient. Without it, if `MAX_EXECUTE_THRESHOLD` is ever raised
136+
// above 85%, scheduler would return "defer" at 85% usage, but heuristic
137+
// cleanup would still fire (it gates on forceMaterialization directly),
138+
// causing unguarded cache busts while pending ops stop materializing.
128139
const shouldApplyPendingOps =
129-
(args.schedulerDecision === "execute" || isExplicitFlush) &&
140+
(args.schedulerDecision === "execute" || isExplicitFlush || forceMaterialization) &&
130141
(!compartmentRunning || emergencyBypassCompartmentGate);
131142
// Central cache-busting gate used by all mutation paths below.
132143
const isCacheBustingPass = isExplicitFlush || shouldApplyPendingOps;

0 commit comments

Comments
 (0)