pi-braid 0.42.0 → 0.43.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. package/CHANGELOG.md +1077 -0
  2. package/README.md +61 -228
  3. package/TOOLS.md +12 -14
  4. package/build-info.json +4 -4
  5. package/dist/extensions/cognitive/metacognition/handlers/think.js +9 -0
  6. package/dist/extensions/core/polyfill/index.d.ts +3 -4
  7. package/dist/extensions/core/polyfill/index.js +34 -131
  8. package/dist/extensions/core/skills-tool/index.js +47 -26
  9. package/dist/extensions/enforcement/handlers/register-agent-end-api-error.js +13 -0
  10. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +8 -3
  11. package/dist/extensions/enforcement/session-health.d.ts +52 -4
  12. package/dist/extensions/enforcement/session-health.js +75 -5
  13. package/dist/extensions/enforcement/whisper.js +15 -1
  14. package/dist/extensions/heartbeat/heartbeat-scheduler/index.d.ts +17 -0
  15. package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +40 -78
  16. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +2 -1
  17. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +26 -28
  18. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.d.ts +62 -31
  19. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.js +130 -55
  20. package/dist/extensions/manifest.js +6 -0
  21. package/dist/extensions/memory/context-lifecycle/index.js +11 -10
  22. package/dist/extensions/memory/context-manager/analysis.d.ts +2 -0
  23. package/dist/extensions/memory/context-manager/analysis.js +6 -2
  24. package/dist/extensions/memory/context-manager/handlers/compaction-retry.js +3 -3
  25. package/dist/extensions/memory/context-manager/handlers/events.js +13 -1
  26. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +10 -14
  27. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +62 -88
  28. package/dist/extensions/self/path-miss/detect.d.ts +30 -0
  29. package/dist/extensions/self/path-miss/detect.js +67 -0
  30. package/dist/extensions/self/path-miss/index.d.ts +33 -0
  31. package/dist/extensions/self/path-miss/index.js +118 -0
  32. package/dist/extensions/self/watchdog/engine.d.ts +8 -1
  33. package/dist/extensions/self/watchdog/engine.js +25 -2
  34. package/dist/extensions/self/watchdog/index.js +14 -1
  35. package/dist/lib/ai/llm-call.js +23 -0
  36. package/dist/lib/ai/model-resolver.d.ts +11 -10
  37. package/dist/lib/ai/model-resolver.js +16 -19
  38. package/dist/lib/ai/presend-budget.d.ts +68 -0
  39. package/dist/lib/ai/presend-budget.js +83 -0
  40. package/dist/lib/config/braid-settings.d.ts +38 -0
  41. package/dist/lib/config/braid-settings.js +84 -0
  42. package/dist/lib/config/per-tool-settings.d.ts +4 -4
  43. package/dist/lib/config/per-tool-settings.js +4 -4
  44. package/dist/lib/core/event-names.d.ts +1 -0
  45. package/dist/lib/core/event-names.js +1 -0
  46. package/dist/lib/detection/context-tiers.d.ts +18 -5
  47. package/dist/lib/detection/context-tiers.js +51 -33
  48. package/dist/lib/detection/context-usage.d.ts +62 -1
  49. package/dist/lib/detection/context-usage.js +158 -1
  50. package/dist/lib/errors/llm-error.d.ts +14 -0
  51. package/dist/lib/errors/llm-error.js +44 -1
  52. package/dist/lib/state/global-state.d.ts +4 -8
  53. package/dist/lib/state/global-state.js +11 -28
  54. package/dist/lib/telemetry/context-heartbeat.d.ts +9 -0
  55. package/dist/lib/telemetry/context-heartbeat.js +18 -8
  56. package/dist/lib/utils/argument-report.d.ts +41 -0
  57. package/dist/lib/utils/argument-report.js +95 -0
  58. package/dist/lib/utils/wake-gate.d.ts +6 -0
  59. package/dist/lib/utils/wake-gate.js +52 -4
  60. package/docs/SETUP.md +7 -6
  61. package/package.json +11 -13
  62. package/src/extensions/cognitive/metacognition/handlers/think.ts +9 -0
  63. package/src/extensions/core/polyfill/index.ts +29 -157
  64. package/src/extensions/core/skills-tool/index.ts +60 -37
  65. package/src/extensions/enforcement/AGENTS.md +38 -1
  66. package/src/extensions/enforcement/handlers/register-agent-end-api-error.ts +13 -0
  67. package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +8 -2
  68. package/src/extensions/enforcement/session-health.ts +94 -5
  69. package/src/extensions/enforcement/whisper.ts +15 -1
  70. package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +53 -80
  71. package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +34 -43
  72. package/src/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.ts +154 -52
  73. package/src/extensions/manifest.ts +6 -0
  74. package/src/extensions/memory/AGENTS.md +37 -38
  75. package/src/extensions/memory/context-lifecycle/index.ts +11 -10
  76. package/src/extensions/memory/context-manager/analysis.ts +8 -1
  77. package/src/extensions/memory/context-manager/handlers/compaction-retry.ts +3 -3
  78. package/src/extensions/memory/context-manager/handlers/events.ts +18 -1
  79. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +81 -115
  80. package/src/extensions/scheduling/timer/AGENTS.md +14 -4
  81. package/src/extensions/self/AGENTS.md +2 -1
  82. package/src/extensions/self/path-miss/AGENTS.md +39 -0
  83. package/src/extensions/self/path-miss/detect.ts +78 -0
  84. package/src/extensions/self/path-miss/index.ts +135 -0
  85. package/src/extensions/self/watchdog/AGENTS.md +36 -18
  86. package/src/extensions/self/watchdog/engine.ts +30 -2
  87. package/src/extensions/self/watchdog/index.ts +13 -1
  88. package/src/lib/ai/AGENTS.md +2 -0
  89. package/src/lib/ai/llm-call.ts +30 -0
  90. package/src/lib/ai/model-resolver.ts +16 -19
  91. package/src/lib/ai/presend-budget.ts +117 -0
  92. package/src/lib/config/braid-settings.ts +125 -0
  93. package/src/lib/config/per-tool-settings.ts +4 -4
  94. package/src/lib/core/event-names.ts +1 -0
  95. package/src/lib/detection/context-tiers.ts +52 -41
  96. package/src/lib/detection/context-usage.ts +211 -2
  97. package/src/lib/errors/llm-error.ts +55 -1
  98. package/src/lib/state/global-state.ts +11 -29
  99. package/src/lib/telemetry/context-heartbeat.ts +27 -7
  100. package/src/lib/utils/AGENTS.md +1 -0
  101. package/src/lib/utils/argument-report.ts +105 -0
  102. package/src/lib/utils/wake-gate.ts +59 -4
@@ -10,10 +10,10 @@
10
10
  *
11
11
  * This module is the one writer for settings.json. Every write goes through
12
12
  * `updateSettings`, which keeps read-modify-write in a single synchronous
13
- * transaction and installs the result with temp-file-plus-rename. The model
14
- * Two writers rewriting the whole file from their own async read-modify-write
15
- * can interleave: the later write replaces the file with its own read snapshot
16
- * and drops the other's key (a `/vision-model` key lost to a concurrent
13
+ * transaction and installs the result with temp-file-plus-rename. Two writers
14
+ * rewriting the whole file from their own async read-modify-write can
15
+ * interleave: the later write replaces the file with its own read snapshot
16
+ * and drops the other's key (a `/utility-model` key lost to a concurrent
17
17
  * toggle).
18
18
  *
19
19
  * A refused write is reported as a return value, not a thrown exception. The
@@ -23,6 +23,7 @@ export const MESSAGE_START = "message_start" as const;
23
23
  export const MESSAGE_END = "message_end" as const;
24
24
  export const TOOL_EXECUTION_START = "tool_execution_start" as const;
25
25
  export const TOOL_EXECUTION_END = "tool_execution_end" as const;
26
+ export const TOOL_RESULT = "tool_result" as const;
26
27
  export const AGENT_SETTLED = "agent_settled" as const;
27
28
 
28
29
  // ── Extension Communication ─────────────────────────────────────────────────
@@ -34,7 +34,7 @@ import {
34
34
  USAGE_COMPACT_MEDIUM,
35
35
  USAGE_FIRED_RESET_BELOW,
36
36
  } from "./context-thresholds.js";
37
- import { tokenArms, formatTokensK } from "./context-usage.js";
37
+ import { tokenArms } from "./context-usage.js";
38
38
  import { getResolvedContextWindow } from "../config/braid-settings.js";
39
39
 
40
40
  // ═══════════════════════════════════════════════════════════════════════════
@@ -80,34 +80,52 @@ export function contextUsageTier(usagePercent: number): ContextUsageTierInfo | n
80
80
  // ENFORCEMENT NUDGE MESSAGES (byte-identical across all enforcement sites)
81
81
  // ═══════════════════════════════════════════════════════════════════════════
82
82
 
83
- /** Percent-tier nudge message text (identical at every enforcement site). */
84
- export function contextUsageTierMessage(tier: ContextUsageTier, usagePercent: number): string {
85
- const pct = Math.round(usagePercent);
83
+ /**
84
+ * The deadline every whisper states instead of restating its number. The bars
85
+ * live in context-thresholds.ts and the meter in context-usage.ts; a
86
+ * percentage copied into prose is a second copy that drifts from the one
87
+ * owner. What the reader cannot derive from the bar is WHEN the cost lands:
88
+ * the compaction the advice leads to is armed, not immediate.
89
+ */
90
+ const SETTLE_DEADLINE = "an armed compaction fires when the run settles";
91
+
92
+ /**
93
+ * Percent-tier nudge message text (identical at every enforcement site).
94
+ * One sentence names the state and the deadline, then the action. No number
95
+ * is restated: the rung's bar selected this message, and the meter rendered
96
+ * the count where a count belongs (context_inspect, the tool result).
97
+ */
98
+ export function contextUsageTierMessage(tier: ContextUsageTier): string {
86
99
  switch (tier) {
87
100
  case "compact":
88
101
  return (
89
- `Context at ${pct}%. Pipeline: context_navigate(action="tag") -> ` +
90
- `context_compress(action="archive") -> context_compress(action="slide"). Tag your position first.`
102
+ `Context is at the compaction arm; ${SETTLE_DEADLINE}. ` +
103
+ `Tag with context_navigate(action="tag") and archive with ` +
104
+ `context_compress(action="archive") before starting the next task.`
91
105
  );
92
106
  case "critical":
93
107
  return (
94
- `Context at ${pct}%. Tag with context_navigate(action="tag"), then ` +
95
- `context_compress(action="archive") to branch with a summary.`
108
+ `Context is above the critical arm; ${SETTLE_DEADLINE}. ` +
109
+ `Tag with context_navigate(action="tag") and archive with ` +
110
+ `context_compress(action="archive") before starting the next task.`
96
111
  );
97
112
  case "warning":
98
113
  return (
99
- `Context at ${pct}%. Warning — tag with context_navigate(action="tag"), then ` +
100
- `context_compress(action="archive") to branch with a summary.`
114
+ `Context is above the warning arm; ${SETTLE_DEADLINE}. ` +
115
+ `Tag with context_navigate(action="tag") and archive with ` +
116
+ `context_compress(action="archive") before starting the next task.`
101
117
  );
102
118
  case "advisory":
103
119
  return (
104
- `Context at ${pct}%. Advisory — consider context_compress(action="archive") for completed tasks. ` +
105
- `context_navigate(action="tag") to mark your position first.`
120
+ `Context is above the advisory arm; ${SETTLE_DEADLINE}. ` +
121
+ `Archive completed work with context_compress(action="archive") and tag with ` +
122
+ `context_navigate(action="tag") before starting the next task.`
106
123
  );
107
124
  case "soft":
108
125
  return (
109
- `Context at ${pct}%. Soft whisper — consider context_inspect(detail="prune") ` +
110
- `to see candidates for archival.`
126
+ `Context is above the soft arm; ${SETTLE_DEADLINE}. ` +
127
+ `Inspect with context_inspect(detail="prune") for candidates, then tag with ` +
128
+ `context_navigate(action="tag") before starting the next task.`
111
129
  );
112
130
  }
113
131
  }
@@ -115,25 +133,12 @@ export function contextUsageTierMessage(tier: ContextUsageTier, usagePercent: nu
115
133
  /**
116
134
  * Token-tier nudge message text (identical at every enforcement site).
117
135
  * `level` mirrors the tier reached by the token-count check; arms are
118
- * fractions of the resolved window (0.45W warning, 0.18W soft).
136
+ * fractions of the resolved window (0.45W warning, 0.18W soft). The text is
137
+ * the tier's: a rung is a threshold, not a label, and the whisper no longer
138
+ * renders the count that selected it.
119
139
  */
120
- export function contextUsageTokenMessage(
121
- level: "warning" | "soft",
122
- usagePercent: number,
123
- usageTokens: number,
124
- ): string {
125
- const tokensK = formatTokensK(usageTokens);
126
- const pct = Math.round(usagePercent);
127
- if (level === "warning") {
128
- return (
129
- `Context at ${tokensK} tokens (${pct}%). ` +
130
- `Pipeline: context_navigate(action="tag") -> context_compress(action="archive") -> context_compress(action="slide").`
131
- );
132
- }
133
- return (
134
- `Context at ${tokensK} tokens. ` +
135
- `Consider context_inspect(detail="prune") to see candidates, or tag position with context_navigate(action="tag").`
136
- );
140
+ export function contextUsageTokenMessage(level: "warning" | "soft"): string {
141
+ return contextUsageTierMessage(level === "warning" ? "warning" : "soft");
137
142
  }
138
143
 
139
144
  // ═══════════════════════════════════════════════════════════════════════════
@@ -180,7 +185,7 @@ export interface ContextNudge extends ContextNudgeRung {
180
185
  }
181
186
 
182
187
  interface RungSpec extends ContextNudgeRung {
183
- render: (usagePercent: number, usageTokens: number) => string;
188
+ render: () => string;
184
189
  }
185
190
 
186
191
  /**
@@ -198,39 +203,39 @@ function nudgeRungs(window?: number | null): RungSpec[] {
198
203
  unit: "tokens",
199
204
  threshold: arms.soft,
200
205
  position: positionOf(arms.soft),
201
- render: (p, t) => contextUsageTokenMessage("soft", p, t),
206
+ render: () => contextUsageTokenMessage("soft"),
202
207
  },
203
208
  {
204
209
  id: "percent:soft",
205
210
  ...pct(USAGE_WHISPER_SOFT),
206
- render: (p) => contextUsageTierMessage("soft", p),
211
+ render: () => contextUsageTierMessage("soft"),
207
212
  },
208
213
  {
209
214
  id: "tokens:warning",
210
215
  unit: "tokens",
211
216
  threshold: arms.warning,
212
217
  position: positionOf(arms.warning),
213
- render: (p, t) => contextUsageTokenMessage("warning", p, t),
218
+ render: () => contextUsageTokenMessage("warning"),
214
219
  },
215
220
  {
216
221
  id: "percent:advisory",
217
222
  ...pct(USAGE_WHISPER_ADVISORY),
218
- render: (p) => contextUsageTierMessage("advisory", p),
223
+ render: () => contextUsageTierMessage("advisory"),
219
224
  },
220
225
  {
221
226
  id: "percent:warning",
222
227
  ...pct(USAGE_WHISPER_WARNING),
223
- render: (p) => contextUsageTierMessage("warning", p),
228
+ render: () => contextUsageTierMessage("warning"),
224
229
  },
225
230
  {
226
231
  id: "percent:critical",
227
232
  ...pct(USAGE_WHISPER_CRITICAL),
228
- render: (p) => contextUsageTierMessage("critical", p),
233
+ render: () => contextUsageTierMessage("critical"),
229
234
  },
230
235
  {
231
236
  id: "percent:compact",
232
237
  ...pct(USAGE_COMPACT_MEDIUM),
233
- render: (p) => contextUsageTierMessage("compact", p),
238
+ render: () => contextUsageTierMessage("compact"),
234
239
  },
235
240
  ];
236
241
  }
@@ -246,6 +251,12 @@ export function resolveContextNudge(
246
251
  usagePercent: number,
247
252
  usageTokens: number,
248
253
  window?: number | null,
254
+ /**
255
+ * How the number was produced (measured / estimated). Rendered with the
256
+ * message so a reader can tell a large context from a badly counted one;
257
+ * the ladder itself is unchanged, since a rung is a bar, not a label.
258
+ */
259
+ provenance?: string,
249
260
  ): ContextNudge | null {
250
261
  let best: RungSpec | null = null;
251
262
  for (const rung of nudgeRungs(window)) {
@@ -259,7 +270,7 @@ export function resolveContextNudge(
259
270
  unit: best.unit,
260
271
  threshold: best.threshold,
261
272
  position: best.position,
262
- message: best.render(usagePercent, usageTokens),
273
+ message: provenance ? `${best.render()} (${provenance})` : best.render(),
263
274
  };
264
275
  }
265
276
 
@@ -66,6 +66,138 @@ export function estimateMessagesTokens(messages: readonly unknown[]): number {
66
66
  return tokens;
67
67
  }
68
68
 
69
+ /**
70
+ * Tokens an OUTGOING REQUEST carries: system prompt, tool definitions and
71
+ * messages. The session-tree walk sees only the messages, so anything that
72
+ * compares a request against a window has to start here - the system prompt
73
+ * and the tool schemas never appear in the tree at all.
74
+ */
75
+ export function estimatePayloadTokens(parts: {
76
+ systemPrompt?: string;
77
+ messages?: readonly unknown[];
78
+ tools?: unknown;
79
+ }): number {
80
+ let tokens = 0;
81
+ if (parts.systemPrompt) tokens += Math.ceil(parts.systemPrompt.length / 4);
82
+ if (parts.messages) tokens += estimateMessagesTokens(parts.messages);
83
+ if (parts.tools !== undefined) {
84
+ try {
85
+ tokens += Math.ceil(JSON.stringify(parts.tools).length / 4);
86
+ } catch {
87
+ /* non-serializable tool definitions: leave them out rather than throw */
88
+ }
89
+ }
90
+ return tokens;
91
+ }
92
+
93
+ // ── Calibration against the provider's own count ──────────────────────
94
+ //
95
+ // chars/4 is not a tokenizer. It is a guess about a distribution, and the
96
+ // distribution moves with the content: prose runs near 4 chars/token, dense
97
+ // tool-call JSON and base64 payloads run near 2, and characters the encoder
98
+ // spends several tokens on (non-Latin scripts) sit lower still. A single
99
+ // divisor therefore cannot be right everywhere, and the guard that reads it
100
+ // is wrong by the same factor in the same direction.
101
+ //
102
+ // Every successful call returns usage. Pairing that count with the estimate
103
+ // for the SAME span yields the one number that can correct the guess without
104
+ // a tokenizer: the ratio. It is kept as the median of the last few pairs
105
+ // because the ratio is content-dependent - a single oversized tool result
106
+ // moves one sample, not the level - and applied to the estimated part of the
107
+ // live number.
108
+
109
+ export type UsageSource = "measured" | "estimated";
110
+
111
+ /** Paired observations kept for the ratio. */
112
+ const CALIBRATION_SAMPLES = 8;
113
+ /**
114
+ * A pair smaller than this measures nothing: below it the fixed part of the
115
+ * request (system prompt, tool schemas) dominates the measured count, so the
116
+ * ratio would describe the harness rather than the tokenizer's view of content.
117
+ */
118
+ const CALIBRATION_MIN_ESTIMATE_TOKENS = 2_000;
119
+ /**
120
+ * Clamp. Below 0.5 the estimate would over-count by more than half (a span
121
+ * whose shape changed under the pair, not a tokenizer effect); above 6 the
122
+ * correction exceeds anything a character-count can explain for text, so the
123
+ * pair is not describing the tokenizer either.
124
+ */
125
+ const CALIBRATION_MIN_RATIO = 0.5;
126
+ const CALIBRATION_MAX_RATIO = 6;
127
+
128
+ let _calibrationRatios: number[] = [];
129
+ let _lastCalibrationKey: string | null = null;
130
+ let _calibrationSession: string | null = null;
131
+
132
+ /**
133
+ * Ratios belong to one session: a new session has its own content mix, and a
134
+ * process that outlives sessions must not apply yesterday's ratio to today's
135
+ * tree. Called from the measure path with whatever session key the context
136
+ * exposes; a context without one leaves the store alone.
137
+ */
138
+ function scopeCalibrationToSession(sessionKey: string | undefined): void {
139
+ if (!sessionKey) return;
140
+ if (_calibrationSession === sessionKey) return;
141
+ _calibrationRatios = [];
142
+ _lastCalibrationKey = null;
143
+ _calibrationSession = sessionKey;
144
+ }
145
+
146
+ /**
147
+ * Record one paired observation: the chars/4 estimate for a request span and
148
+ * the provider's own count for that same span. Returns the median ratio after
149
+ * the insert, or null when the pair measures nothing (a span under the harness
150
+ * floor, or a non-positive measured count).
151
+ *
152
+ * `key` dedupes: callers re-measure the same span many times per turn, and the
153
+ * same pair must not weight the median more than once.
154
+ */
155
+ export function recordCalibrationSample(
156
+ estimatedTokens: number,
157
+ measuredTokens: number,
158
+ key?: string,
159
+ ): number | null {
160
+ if (estimatedTokens < CALIBRATION_MIN_ESTIMATE_TOKENS || measuredTokens <= 0) return null;
161
+ if (key && key === _lastCalibrationKey) return calibrationRatio();
162
+ const raw = measuredTokens / estimatedTokens;
163
+ const ratio = Math.min(CALIBRATION_MAX_RATIO, Math.max(CALIBRATION_MIN_RATIO, raw));
164
+ _calibrationRatios.push(ratio);
165
+ if (_calibrationRatios.length > CALIBRATION_SAMPLES) _calibrationRatios.shift();
166
+ _lastCalibrationKey = key ?? null;
167
+ return calibrationRatio();
168
+ }
169
+
170
+ /** Median of the retained ratios; null before the first usable pair. */
171
+ export function calibrationRatio(): number | null {
172
+ if (_calibrationRatios.length === 0) return null;
173
+ const sorted = [..._calibrationRatios].sort((a, b) => a - b);
174
+ const mid = Math.floor(sorted.length / 2);
175
+ return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
176
+ }
177
+
178
+ /**
179
+ * Apply the session's ratio to a chars-based estimate. No ratio (first call of
180
+ * a session) leaves the number as the plain estimate - it never pretends to be
181
+ * measured, and it never invents a correction it has not observed.
182
+ */
183
+ export function calibrateEstimate(rawTokens: number): {
184
+ tokens: number;
185
+ ratio: number | null;
186
+ calibrated: boolean;
187
+ } {
188
+ const ratio = calibrationRatio();
189
+ if (ratio === null || rawTokens <= 0)
190
+ return { tokens: rawTokens, ratio: null, calibrated: false };
191
+ return { tokens: Math.round(rawTokens * ratio), ratio, calibrated: true };
192
+ }
193
+
194
+ /** Test hook: clear the retained pairs (also clears the dedupe key). */
195
+ export function resetCalibrationForTests(): void {
196
+ _calibrationRatios = [];
197
+ _lastCalibrationKey = null;
198
+ _calibrationSession = null;
199
+ }
200
+
69
201
  /** Tokens carried by one session entry (message, compaction summary, etc.). */
70
202
  function entryTokens(entry: any): number {
71
203
  if (!entry || typeof entry !== "object") return 0;
@@ -107,8 +239,19 @@ export function resolveWindow(modelWindow?: number | null): ResolvedWindow {
107
239
  }
108
240
 
109
241
  export interface LiveUsage {
110
- /** Estimated tokens of the next request payload. */
242
+ /**
243
+ * Tokens of the next request payload, calibrated. This is the number guards
244
+ * read: a measured base plus a calibrated estimate of the trailing entries.
245
+ */
111
246
  tokens: number;
247
+ /** Where `tokens` came from: an API response, or the chars-based estimate. */
248
+ source: UsageSource;
249
+ /** The uncalibrated chars/4 walk over the same span (never rendered as the total). */
250
+ estimatedTokens: number;
251
+ /** The trailing part that only the estimate covers, after calibration. 0 when measured. */
252
+ estimatedTrailingTokens: number;
253
+ /** The session ratio applied, when one was observed. */
254
+ calibrationRatio?: number;
112
255
  contextWindow: number;
113
256
  percent: number;
114
257
  windowSource: "configured" | "provider";
@@ -139,6 +282,15 @@ export function measureLiveUsage(ctx: unknown): LiveUsage | undefined {
139
282
 
140
283
  const modelWindow = (ctx as { model?: { contextWindow?: number } })?.model?.contextWindow;
141
284
  const window = resolveWindow(modelWindow);
285
+ try {
286
+ scopeCalibrationToSession(
287
+ (
288
+ ctx as { sessionManager?: { getSessionId?: () => string } }
289
+ ).sessionManager?.getSessionId?.(),
290
+ );
291
+ } catch {
292
+ /* no session key: keep the store as it is */
293
+ }
142
294
 
143
295
  // Latest compaction boundary: entries strictly before it are compacted
144
296
  // away and are not part of the live payload.
@@ -188,14 +340,43 @@ export function measureLiveUsage(ctx: unknown): LiveUsage | undefined {
188
340
  break;
189
341
  }
190
342
  }
343
+ const estimatedTokens = liveTokens;
344
+ let source: UsageSource = "estimated";
345
+ let estimatedTrailingTokens: number;
346
+ let calibrationRatioApplied: number | undefined;
347
+
191
348
  if (usageBacked) {
349
+ // The provider's count covers exactly the entries from the boundary through
350
+ // the message that carries the usage; pair that count with the walk over
351
+ // the same slice. This is the only place both numbers describe one request.
352
+ let rawUpToUsage = 0;
353
+ for (let i = liveStart; i <= usageBacked.index; i++) rawUpToUsage += entryTokens(branch[i]);
354
+ recordCalibrationSample(
355
+ rawUpToUsage,
356
+ usageBacked.usageTokens,
357
+ `${liveStart}:${usageBacked.index}:${usageBacked.usageTokens}`,
358
+ );
359
+
192
360
  let trailing = 0;
193
361
  for (let i = usageBacked.index + 1; i < branch.length; i++) trailing += entryTokens(branch[i]);
194
- liveTokens = usageBacked.usageTokens + trailing;
362
+ const calibratedTrailing = calibrateEstimate(trailing);
363
+ liveTokens = usageBacked.usageTokens + calibratedTrailing.tokens;
364
+ source = "measured";
365
+ estimatedTrailingTokens = calibratedTrailing.tokens;
366
+ if (calibratedTrailing.ratio !== null) calibrationRatioApplied = calibratedTrailing.ratio;
367
+ } else {
368
+ const calibrated = calibrateEstimate(liveTokens);
369
+ liveTokens = calibrated.tokens;
370
+ estimatedTrailingTokens = calibrated.tokens;
371
+ if (calibrated.ratio !== null) calibrationRatioApplied = calibrated.ratio;
195
372
  }
196
373
 
197
374
  return {
198
375
  tokens: liveTokens,
376
+ source,
377
+ estimatedTokens,
378
+ estimatedTrailingTokens,
379
+ calibrationRatio: calibrationRatioApplied,
199
380
  contextWindow: window.contextWindow,
200
381
  percent: window.contextWindow > 0 ? (liveTokens / window.contextWindow) * 100 : 0,
201
382
  windowSource: window.windowSource,
@@ -268,3 +449,31 @@ export function tokenArms(providerWindow?: number | null): TokenArms {
268
449
  export function formatTokensK(tokens: number): string {
269
450
  return `${Math.round(tokens / 1000)}K`;
270
451
  }
452
+
453
+ /**
454
+ * One label for any rendered usage number, naming its provenance. The word is
455
+ * `measured` only when an API response supplied the anchor; everything else is
456
+ * `estimated`, with the calibration factor shown when one was applied. A
457
+ * trailing estimate behind a measured anchor is named rather than folded in -
458
+ * rounding it away is how the number stops meaning anything.
459
+ */
460
+ export function describeUsage(usage: {
461
+ source: UsageSource;
462
+ estimatedTrailingTokens?: number;
463
+ calibrationRatio?: number;
464
+ }): string {
465
+ const ratio =
466
+ usage.calibrationRatio !== undefined ? ` x${usage.calibrationRatio.toFixed(2)}` : "";
467
+ if (usage.source === "measured") {
468
+ const trailing = usage.estimatedTrailingTokens ?? 0;
469
+ return trailing > 0
470
+ ? `measured + ${formatTokensK(trailing)} estimated${ratio}`
471
+ : `measured${ratio}`;
472
+ }
473
+ return `estimated${ratio}`;
474
+ }
475
+
476
+ /** `<pct>% <provenance>` - the percent form used wherever a percentage renders. */
477
+ export function describeUsagePercent(usage: LiveUsage): string {
478
+ return `${usage.percent.toFixed(1)}% ${describeUsage(usage)}`;
479
+ }
@@ -43,6 +43,13 @@ export interface ClassifiedLlmError {
43
43
  fallbackToNonLlm: boolean;
44
44
  /** Does the user need to do something (top up balance, fix key)? */
45
45
  userActionRequired: boolean;
46
+ /**
47
+ * Set when the failure is about the SHAPE of the request rather than its
48
+ * timing: the same request will be refused the same way, so the retry path
49
+ * and any wake that would start a fresh turn are both wrong. The ring
50
+ * records the same class as a request-shape death.
51
+ */
52
+ requestShape?: "context_length";
46
53
  /** Plain-text hint for the user. Empty for transient/unknown. */
47
54
  userMessage?: string;
48
55
  /** Hint from Retry-After header or computed backoff (ms). */
@@ -117,6 +124,47 @@ const CONTEXT_WINDOW_PATTERNS = [
117
124
  /prompt[_ ]is[_ ]too[_ ]long/i,
118
125
  ];
119
126
 
127
+ /**
128
+ * Context-length refusals in their 400-shaped wordings. A provider that
129
+ * rejects an oversized body with `400 invalid_request_error` is naming a
130
+ * request-shape problem: the numbers change, the verdict does not. Kept apart
131
+ * from CONTEXT_WINDOW_PATTERNS so the bare `413` arm keeps its meaning and a
132
+ * 5xx body cannot be pulled in by a phrase like "too many tokens".
133
+ */
134
+ const REQUEST_SHAPE_CONTEXT_PATTERNS = [
135
+ /maximum[_ ]context[_ ]length/i,
136
+ /context[_ ]length/i,
137
+ /reduce[ _]the[ _]length[ _]of[ _]the/i,
138
+ /(input|prompt|request|messages?)[ _]is[ _]too[ _]long/i,
139
+ /too[ _]many[ _](input[ _])?tokens/i,
140
+ /exceeds?[ _]the[ _](model'?s?[ _])?(maximum|max)/i,
141
+ ];
142
+
143
+ /**
144
+ * True when the text names a context-length refusal. Used by consumers that
145
+ * only have text (pi-core surfaces session failures as the assistant's
146
+ * errorMessage string) and must tell "the request must change" apart from
147
+ * "try again later" without re-deriving the pattern list.
148
+ */
149
+ export function isContextLengthRequestShape(err: unknown): boolean {
150
+ const text =
151
+ typeof err === "string"
152
+ ? err
153
+ : typeof err === "object" && err !== null
154
+ ? String((err as { message?: unknown }).message ?? "")
155
+ : "";
156
+ if (!text) return false;
157
+ return (
158
+ matchesAny(text, [
159
+ /context[_ ]length[_ ]exceeded/i,
160
+ /context[_ ]window/i,
161
+ /maximum[_ ]context/i,
162
+ /prompt[_ ]is[_ ]too[_ ]long/i,
163
+ ...REQUEST_SHAPE_CONTEXT_PATTERNS,
164
+ ]) && !matchesAny(text, TRANSIENT_PATTERNS)
165
+ );
166
+ }
167
+
120
168
  const TRANSIENT_PATTERNS = [
121
169
  /500/,
122
170
  /502/,
@@ -276,7 +324,13 @@ export function classifyLlmError(err: unknown): ClassifiedLlmError {
276
324
  return makeError("auth", err);
277
325
  }
278
326
  if (status === 413 || matchesAny(text, CONTEXT_WINDOW_PATTERNS)) {
279
- return makeError("context_window", err);
327
+ return makeError("context_window", err, { requestShape: "context_length" });
328
+ }
329
+ // A 400 whose body names a context-length refusal is the same class as a
330
+ // 413: the request shape is wrong, so it must never fall through to
331
+ // `unknown` (which is retryable, and retrying it unchanged cannot work).
332
+ if (status === 400 && matchesAny(text, REQUEST_SHAPE_CONTEXT_PATTERNS)) {
333
+ return makeError("context_window", err, { requestShape: "context_length" });
280
334
  }
281
335
  if (status === 500 || status === 502 || status === 503 || status === 504 || status === 529) {
282
336
  return makeError("transient", err);
@@ -17,9 +17,10 @@
17
17
  // compiled DIST (dist/lib/state/global-state.js via the pi-braid/lib export).
18
18
  // That yields TWO module instances of this file in one process; a module-level
19
19
  // Map would be populated by the src instance and read (empty) by the dist
20
- // instance — the visionModel custom key would fall through to priority-3
21
- // first-available (MiniMax 429). Same cross-bundle hazard as
22
- // KEY_RING_FEEDBACK_KEY above; the slot must also survive /reload.
20
+ // instance, so the role setting would read as unset and resolution would fall
21
+ // away from it (first-available is where the MiniMax 429 lived). Same
22
+ // cross-bundle hazard as KEY_RING_FEEDBACK_KEY above; the slot must also
23
+ // survive /reload.
23
24
  export const CUSTOM_MODEL_KEYS_KEY = "__braid_custom_model_keys";
24
25
 
25
26
  /**
@@ -31,7 +32,7 @@ export type CustomModelKeyValue = string | string[];
31
32
 
32
33
  /**
33
34
  * Get the shared custom model keys map.
34
- * polyfill writes to it (/vision-model command).
35
+ * polyfill writes to it (/utility-model command).
35
36
  * model-resolver reads from it (model resolution).
36
37
  */
37
38
  export function getCustomModelKeys(): Map<string, CustomModelKeyValue> {
@@ -43,8 +44,8 @@ export function getCustomModelKeys(): Map<string, CustomModelKeyValue> {
43
44
  }
44
45
 
45
46
  /**
46
- * Read a custom model key (e.g. "utilityModel", "visionModel"): a pattern or an
47
- * ordered list of them.
47
+ * Read a custom model key (e.g. "utilityModel"): a pattern or an ordered list
48
+ * of them.
48
49
  */
49
50
  export function getCustomModelKey(key: string): CustomModelKeyValue | undefined {
50
51
  return getCustomModelKeys().get(key);
@@ -52,35 +53,16 @@ export function getCustomModelKey(key: string): CustomModelKeyValue | undefined
52
53
 
53
54
  /**
54
55
  * Set a custom model key: one pattern or an ordered list. Used by polyfill for
55
- * /utility-model and /vision-model.
56
+ * /utility-model.
56
57
  */
57
58
  export function setCustomModelKey(key: string, value: CustomModelKeyValue): void {
58
59
  getCustomModelKeys().set(key, value);
59
60
  }
60
61
 
61
- // The vision role is deprecated: the key keeps priority-1 status as an alias
62
- // for one release, after which the merged role supplies image-capable models.
63
- export const VISION_MODEL_KEY = "visionModel";
62
+ // The auxiliary role's key. Both the polyfill (which writes it) and the
63
+ // resolver (which reads it) address the one merged role: vision analysis falls
64
+ // back to its first image-capable entry, so there is no separate vision key.
64
65
  export const UTILITY_MODEL_KEY = "utilityModel";
65
- // The max-power role is folded into utility; the constant survives so the
66
- // polyfill can recognize and clean the legacy key from settings.json; nothing
67
- // resolves it as a live role.
68
- export const MAX_POWER_MODEL_KEY = "maxPowerModel";
69
-
70
- /**
71
- * One-shot latch for the maxPowerModel deprecation notice. Process-global for
72
- * the same reason as the keys above: a src-loaded and a dist-loaded instance
73
- * of this module must agree on whether the notice already fired.
74
- */
75
- const MAX_POWER_NOTICE_KEY = "__braid_max_power_deprecation_notice";
76
-
77
- /** True the first time it is called in this process, false afterwards. */
78
- export function consumeMaxPowerDeprecationNotice(): boolean {
79
- const slot = globalThis as Record<string, unknown>;
80
- if (slot[MAX_POWER_NOTICE_KEY]) return false;
81
- slot[MAX_POWER_NOTICE_KEY] = true;
82
- return true;
83
- }
84
66
 
85
67
  export interface RotationState {
86
68
  lastRotationTimestamp: number;
@@ -46,7 +46,7 @@ import {
46
46
  safeSessionManagerTyped,
47
47
  } from "../state/extension-state.js";
48
48
  import { getContextUsage } from "../detection/context-tiers.js";
49
- import { measureLiveUsage } from "../detection/context-usage.js";
49
+ import { measureLiveUsage, describeUsage } from "../detection/context-usage.js";
50
50
 
51
51
  const log = createLogger("context-heartbeat");
52
52
 
@@ -479,6 +479,15 @@ export function collectAndEmitContextHeartbeat(
479
479
  export interface SelfStateSample {
480
480
  /** Current context size in tokens (live read, not the last-tick snapshot). */
481
481
  contextTokens: number | null;
482
+ /** Percent of the resolved window the same reading fills; null when unmeasured. */
483
+ contextPercent: number | null;
484
+ /**
485
+ * The meter's own provenance word for the two fields above (`measured`,
486
+ * `estimated`, or a measured anchor plus its estimated trailing part). Null
487
+ * when no reading was available. A reader that cannot tell the two apart
488
+ * cannot tell a large context from a badly counted one.
489
+ */
490
+ contextProvenance: string | null;
482
491
  /** Cache-hit share, percent 0-100 (last assistant message). */
483
492
  cacheHitShare: number | null;
484
493
  /** Near-duplicate message count from the context-density evaluator. */
@@ -498,19 +507,30 @@ export interface SelfStateSample {
498
507
  export function getSelfStateSample(ctx: ExtensionContext): SelfStateSample {
499
508
  const sample: SelfStateSample = {
500
509
  contextTokens: null,
510
+ contextPercent: null,
511
+ contextProvenance: null,
501
512
  cacheHitShare: null,
502
513
  nearDupCount: null,
503
514
  tpsEma: null,
504
515
  hygieneActs: null,
505
516
  };
506
517
  try {
507
- // Context tokens: live read (compaction-aware session-tree measure),
508
- // not the last-tick snapshot — a summary rendered right after a slide
509
- // must not report the pre-slide size. Falls back to the duck-typed
510
- // accessor when the session tree is unavailable.
518
+ // Context size: live read (compaction-aware session-tree measure), not the
519
+ // last-tick snapshot - a summary rendered right after a slide must not
520
+ // report the pre-slide size.
521
+ //
522
+ // One instrument, and it is this one. Size, percent and provenance come
523
+ // from a single reading here; the provider accessor answers a different
524
+ // question over a different tree (session projection vs branch), and a
525
+ // delivery that prints both is two ages of one fact. When this meter has
526
+ // no reading, the line says n/a rather than borrowing a second opinion:
527
+ // the reader cannot act on a number whose instrument it cannot name.
511
528
  const live = measureLiveUsage(ctx);
512
- const usage = live ?? getContextUsage(ctx);
513
- if (usage && typeof usage.tokens === "number") sample.contextTokens = usage.tokens;
529
+ if (live) {
530
+ sample.contextTokens = live.tokens;
531
+ sample.contextPercent = live.percent;
532
+ sample.contextProvenance = describeUsage(live);
533
+ }
514
534
  } catch {
515
535
  /* keep null */
516
536
  }