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
@@ -26,7 +26,7 @@
26
26
  * policies) keep their own messages and only share the tier mapping.
27
27
  */
28
28
  import { USAGE_WHISPER_SOFT, USAGE_WHISPER_ADVISORY, USAGE_WHISPER_WARNING, USAGE_WHISPER_CRITICAL, USAGE_COMPACT_MEDIUM, USAGE_FIRED_RESET_BELOW, } from "./context-thresholds.js";
29
- import { tokenArms, formatTokensK } from "./context-usage.js";
29
+ import { tokenArms } from "./context-usage.js";
30
30
  import { getResolvedContextWindow } from "../config/braid-settings.js";
31
31
  /**
32
32
  * Tier ladder, highest first: compact(80) → critical(75) → warning(65)
@@ -54,41 +54,53 @@ export function contextUsageTier(usagePercent) {
54
54
  // ═══════════════════════════════════════════════════════════════════════════
55
55
  // ENFORCEMENT NUDGE MESSAGES (byte-identical across all enforcement sites)
56
56
  // ═══════════════════════════════════════════════════════════════════════════
57
- /** Percent-tier nudge message text (identical at every enforcement site). */
58
- export function contextUsageTierMessage(tier, usagePercent) {
59
- const pct = Math.round(usagePercent);
57
+ /**
58
+ * The deadline every whisper states instead of restating its number. The bars
59
+ * live in context-thresholds.ts and the meter in context-usage.ts; a
60
+ * percentage copied into prose is a second copy that drifts from the one
61
+ * owner. What the reader cannot derive from the bar is WHEN the cost lands:
62
+ * the compaction the advice leads to is armed, not immediate.
63
+ */
64
+ const SETTLE_DEADLINE = "an armed compaction fires when the run settles";
65
+ /**
66
+ * Percent-tier nudge message text (identical at every enforcement site).
67
+ * One sentence names the state and the deadline, then the action. No number
68
+ * is restated: the rung's bar selected this message, and the meter rendered
69
+ * the count where a count belongs (context_inspect, the tool result).
70
+ */
71
+ export function contextUsageTierMessage(tier) {
60
72
  switch (tier) {
61
73
  case "compact":
62
- return (`Context at ${pct}%. Pipeline: context_navigate(action="tag") -> ` +
63
- `context_compress(action="archive") -> context_compress(action="slide"). Tag your position first.`);
74
+ return (`Context is at the compaction arm; ${SETTLE_DEADLINE}. ` +
75
+ `Tag with context_navigate(action="tag") and archive with ` +
76
+ `context_compress(action="archive") before starting the next task.`);
64
77
  case "critical":
65
- return (`Context at ${pct}%. Tag with context_navigate(action="tag"), then ` +
66
- `context_compress(action="archive") to branch with a summary.`);
78
+ return (`Context is above the critical arm; ${SETTLE_DEADLINE}. ` +
79
+ `Tag with context_navigate(action="tag") and archive with ` +
80
+ `context_compress(action="archive") before starting the next task.`);
67
81
  case "warning":
68
- return (`Context at ${pct}%. Warning — tag with context_navigate(action="tag"), then ` +
69
- `context_compress(action="archive") to branch with a summary.`);
82
+ return (`Context is above the warning arm; ${SETTLE_DEADLINE}. ` +
83
+ `Tag with context_navigate(action="tag") and archive with ` +
84
+ `context_compress(action="archive") before starting the next task.`);
70
85
  case "advisory":
71
- return (`Context at ${pct}%. Advisory — consider context_compress(action="archive") for completed tasks. ` +
72
- `context_navigate(action="tag") to mark your position first.`);
86
+ return (`Context is above the advisory arm; ${SETTLE_DEADLINE}. ` +
87
+ `Archive completed work with context_compress(action="archive") and tag with ` +
88
+ `context_navigate(action="tag") before starting the next task.`);
73
89
  case "soft":
74
- return (`Context at ${pct}%. Soft whisper — consider context_inspect(detail="prune") ` +
75
- `to see candidates for archival.`);
90
+ return (`Context is above the soft arm; ${SETTLE_DEADLINE}. ` +
91
+ `Inspect with context_inspect(detail="prune") for candidates, then tag with ` +
92
+ `context_navigate(action="tag") before starting the next task.`);
76
93
  }
77
94
  }
78
95
  /**
79
96
  * Token-tier nudge message text (identical at every enforcement site).
80
97
  * `level` mirrors the tier reached by the token-count check; arms are
81
- * fractions of the resolved window (0.45W warning, 0.18W soft).
98
+ * fractions of the resolved window (0.45W warning, 0.18W soft). The text is
99
+ * the tier's: a rung is a threshold, not a label, and the whisper no longer
100
+ * renders the count that selected it.
82
101
  */
83
- export function contextUsageTokenMessage(level, usagePercent, usageTokens) {
84
- const tokensK = formatTokensK(usageTokens);
85
- const pct = Math.round(usagePercent);
86
- if (level === "warning") {
87
- return (`Context at ${tokensK} tokens (${pct}%). ` +
88
- `Pipeline: context_navigate(action="tag") -> context_compress(action="archive") -> context_compress(action="slide").`);
89
- }
90
- return (`Context at ${tokensK} tokens. ` +
91
- `Consider context_inspect(detail="prune") to see candidates, or tag position with context_navigate(action="tag").`);
102
+ export function contextUsageTokenMessage(level) {
103
+ return contextUsageTierMessage(level === "warning" ? "warning" : "soft");
92
104
  }
93
105
  /**
94
106
  * The ladder for one window, weakest position first. Token rungs carry the
@@ -105,39 +117,39 @@ function nudgeRungs(window) {
105
117
  unit: "tokens",
106
118
  threshold: arms.soft,
107
119
  position: positionOf(arms.soft),
108
- render: (p, t) => contextUsageTokenMessage("soft", p, t),
120
+ render: () => contextUsageTokenMessage("soft"),
109
121
  },
110
122
  {
111
123
  id: "percent:soft",
112
124
  ...pct(USAGE_WHISPER_SOFT),
113
- render: (p) => contextUsageTierMessage("soft", p),
125
+ render: () => contextUsageTierMessage("soft"),
114
126
  },
115
127
  {
116
128
  id: "tokens:warning",
117
129
  unit: "tokens",
118
130
  threshold: arms.warning,
119
131
  position: positionOf(arms.warning),
120
- render: (p, t) => contextUsageTokenMessage("warning", p, t),
132
+ render: () => contextUsageTokenMessage("warning"),
121
133
  },
122
134
  {
123
135
  id: "percent:advisory",
124
136
  ...pct(USAGE_WHISPER_ADVISORY),
125
- render: (p) => contextUsageTierMessage("advisory", p),
137
+ render: () => contextUsageTierMessage("advisory"),
126
138
  },
127
139
  {
128
140
  id: "percent:warning",
129
141
  ...pct(USAGE_WHISPER_WARNING),
130
- render: (p) => contextUsageTierMessage("warning", p),
142
+ render: () => contextUsageTierMessage("warning"),
131
143
  },
132
144
  {
133
145
  id: "percent:critical",
134
146
  ...pct(USAGE_WHISPER_CRITICAL),
135
- render: (p) => contextUsageTierMessage("critical", p),
147
+ render: () => contextUsageTierMessage("critical"),
136
148
  },
137
149
  {
138
150
  id: "percent:compact",
139
151
  ...pct(USAGE_COMPACT_MEDIUM),
140
- render: (p) => contextUsageTierMessage("compact", p),
152
+ render: () => contextUsageTierMessage("compact"),
141
153
  },
142
154
  ];
143
155
  }
@@ -148,7 +160,13 @@ function nudgeRungs(window) {
148
160
  * (the ladder is built weakest-first), and an equal position is not an
149
161
  * escalation.
150
162
  */
151
- export function resolveContextNudge(usagePercent, usageTokens, window) {
163
+ export function resolveContextNudge(usagePercent, usageTokens, window,
164
+ /**
165
+ * How the number was produced (measured / estimated). Rendered with the
166
+ * message so a reader can tell a large context from a badly counted one;
167
+ * the ladder itself is unchanged, since a rung is a bar, not a label.
168
+ */
169
+ provenance) {
152
170
  let best = null;
153
171
  for (const rung of nudgeRungs(window)) {
154
172
  const reached = rung.unit === "tokens" ? usageTokens >= rung.threshold : usagePercent >= rung.threshold;
@@ -162,7 +180,7 @@ export function resolveContextNudge(usagePercent, usageTokens, window) {
162
180
  unit: best.unit,
163
181
  threshold: best.threshold,
164
182
  position: best.position,
165
- message: best.render(usagePercent, usageTokens),
183
+ message: provenance ? `${best.render()} (${provenance})` : best.render(),
166
184
  };
167
185
  }
168
186
  /**
@@ -18,6 +18,42 @@
18
18
  */
19
19
  /** Tokens carried by a span of messages - the same per-message chars/4 estimate. */
20
20
  export declare function estimateMessagesTokens(messages: readonly unknown[]): number;
21
+ /**
22
+ * Tokens an OUTGOING REQUEST carries: system prompt, tool definitions and
23
+ * messages. The session-tree walk sees only the messages, so anything that
24
+ * compares a request against a window has to start here - the system prompt
25
+ * and the tool schemas never appear in the tree at all.
26
+ */
27
+ export declare function estimatePayloadTokens(parts: {
28
+ systemPrompt?: string;
29
+ messages?: readonly unknown[];
30
+ tools?: unknown;
31
+ }): number;
32
+ export type UsageSource = "measured" | "estimated";
33
+ /**
34
+ * Record one paired observation: the chars/4 estimate for a request span and
35
+ * the provider's own count for that same span. Returns the median ratio after
36
+ * the insert, or null when the pair measures nothing (a span under the harness
37
+ * floor, or a non-positive measured count).
38
+ *
39
+ * `key` dedupes: callers re-measure the same span many times per turn, and the
40
+ * same pair must not weight the median more than once.
41
+ */
42
+ export declare function recordCalibrationSample(estimatedTokens: number, measuredTokens: number, key?: string): number | null;
43
+ /** Median of the retained ratios; null before the first usable pair. */
44
+ export declare function calibrationRatio(): number | null;
45
+ /**
46
+ * Apply the session's ratio to a chars-based estimate. No ratio (first call of
47
+ * a session) leaves the number as the plain estimate - it never pretends to be
48
+ * measured, and it never invents a correction it has not observed.
49
+ */
50
+ export declare function calibrateEstimate(rawTokens: number): {
51
+ tokens: number;
52
+ ratio: number | null;
53
+ calibrated: boolean;
54
+ };
55
+ /** Test hook: clear the retained pairs (also clears the dedupe key). */
56
+ export declare function resetCalibrationForTests(): void;
21
57
  /** The resolved context window with an explicit source label. */
22
58
  export interface ResolvedWindow {
23
59
  contextWindow: number;
@@ -31,8 +67,19 @@ export interface ResolvedWindow {
31
67
  }
32
68
  export declare function resolveWindow(modelWindow?: number | null): ResolvedWindow;
33
69
  export interface LiveUsage {
34
- /** Estimated tokens of the next request payload. */
70
+ /**
71
+ * Tokens of the next request payload, calibrated. This is the number guards
72
+ * read: a measured base plus a calibrated estimate of the trailing entries.
73
+ */
35
74
  tokens: number;
75
+ /** Where `tokens` came from: an API response, or the chars-based estimate. */
76
+ source: UsageSource;
77
+ /** The uncalibrated chars/4 walk over the same span (never rendered as the total). */
78
+ estimatedTokens: number;
79
+ /** The trailing part that only the estimate covers, after calibration. 0 when measured. */
80
+ estimatedTrailingTokens: number;
81
+ /** The session ratio applied, when one was observed. */
82
+ calibrationRatio?: number;
36
83
  contextWindow: number;
37
84
  percent: number;
38
85
  windowSource: "configured" | "provider";
@@ -72,4 +119,18 @@ export declare function tokenArms(providerWindow?: number | null): TokenArms;
72
119
  * same 160K/128K setting).
73
120
  */
74
121
  export declare function formatTokensK(tokens: number): string;
122
+ /**
123
+ * One label for any rendered usage number, naming its provenance. The word is
124
+ * `measured` only when an API response supplied the anchor; everything else is
125
+ * `estimated`, with the calibration factor shown when one was applied. A
126
+ * trailing estimate behind a measured anchor is named rather than folded in -
127
+ * rounding it away is how the number stops meaning anything.
128
+ */
129
+ export declare function describeUsage(usage: {
130
+ source: UsageSource;
131
+ estimatedTrailingTokens?: number;
132
+ calibrationRatio?: number;
133
+ }): string;
134
+ /** `<pct>% <provenance>` - the percent form used wherever a percentage renders. */
135
+ export declare function describeUsagePercent(usage: LiveUsage): string;
75
136
  //# sourceMappingURL=context-usage.d.ts.map
@@ -60,6 +60,109 @@ export function estimateMessagesTokens(messages) {
60
60
  tokens += estimateMessageTokens(message);
61
61
  return tokens;
62
62
  }
63
+ /**
64
+ * Tokens an OUTGOING REQUEST carries: system prompt, tool definitions and
65
+ * messages. The session-tree walk sees only the messages, so anything that
66
+ * compares a request against a window has to start here - the system prompt
67
+ * and the tool schemas never appear in the tree at all.
68
+ */
69
+ export function estimatePayloadTokens(parts) {
70
+ let tokens = 0;
71
+ if (parts.systemPrompt)
72
+ tokens += Math.ceil(parts.systemPrompt.length / 4);
73
+ if (parts.messages)
74
+ tokens += estimateMessagesTokens(parts.messages);
75
+ if (parts.tools !== undefined) {
76
+ try {
77
+ tokens += Math.ceil(JSON.stringify(parts.tools).length / 4);
78
+ }
79
+ catch {
80
+ /* non-serializable tool definitions: leave them out rather than throw */
81
+ }
82
+ }
83
+ return tokens;
84
+ }
85
+ /** Paired observations kept for the ratio. */
86
+ const CALIBRATION_SAMPLES = 8;
87
+ /**
88
+ * A pair smaller than this measures nothing: below it the fixed part of the
89
+ * request (system prompt, tool schemas) dominates the measured count, so the
90
+ * ratio would describe the harness rather than the tokenizer's view of content.
91
+ */
92
+ const CALIBRATION_MIN_ESTIMATE_TOKENS = 2_000;
93
+ /**
94
+ * Clamp. Below 0.5 the estimate would over-count by more than half (a span
95
+ * whose shape changed under the pair, not a tokenizer effect); above 6 the
96
+ * correction exceeds anything a character-count can explain for text, so the
97
+ * pair is not describing the tokenizer either.
98
+ */
99
+ const CALIBRATION_MIN_RATIO = 0.5;
100
+ const CALIBRATION_MAX_RATIO = 6;
101
+ let _calibrationRatios = [];
102
+ let _lastCalibrationKey = null;
103
+ let _calibrationSession = null;
104
+ /**
105
+ * Ratios belong to one session: a new session has its own content mix, and a
106
+ * process that outlives sessions must not apply yesterday's ratio to today's
107
+ * tree. Called from the measure path with whatever session key the context
108
+ * exposes; a context without one leaves the store alone.
109
+ */
110
+ function scopeCalibrationToSession(sessionKey) {
111
+ if (!sessionKey)
112
+ return;
113
+ if (_calibrationSession === sessionKey)
114
+ return;
115
+ _calibrationRatios = [];
116
+ _lastCalibrationKey = null;
117
+ _calibrationSession = sessionKey;
118
+ }
119
+ /**
120
+ * Record one paired observation: the chars/4 estimate for a request span and
121
+ * the provider's own count for that same span. Returns the median ratio after
122
+ * the insert, or null when the pair measures nothing (a span under the harness
123
+ * floor, or a non-positive measured count).
124
+ *
125
+ * `key` dedupes: callers re-measure the same span many times per turn, and the
126
+ * same pair must not weight the median more than once.
127
+ */
128
+ export function recordCalibrationSample(estimatedTokens, measuredTokens, key) {
129
+ if (estimatedTokens < CALIBRATION_MIN_ESTIMATE_TOKENS || measuredTokens <= 0)
130
+ return null;
131
+ if (key && key === _lastCalibrationKey)
132
+ return calibrationRatio();
133
+ const raw = measuredTokens / estimatedTokens;
134
+ const ratio = Math.min(CALIBRATION_MAX_RATIO, Math.max(CALIBRATION_MIN_RATIO, raw));
135
+ _calibrationRatios.push(ratio);
136
+ if (_calibrationRatios.length > CALIBRATION_SAMPLES)
137
+ _calibrationRatios.shift();
138
+ _lastCalibrationKey = key ?? null;
139
+ return calibrationRatio();
140
+ }
141
+ /** Median of the retained ratios; null before the first usable pair. */
142
+ export function calibrationRatio() {
143
+ if (_calibrationRatios.length === 0)
144
+ return null;
145
+ const sorted = [..._calibrationRatios].sort((a, b) => a - b);
146
+ const mid = Math.floor(sorted.length / 2);
147
+ return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
148
+ }
149
+ /**
150
+ * Apply the session's ratio to a chars-based estimate. No ratio (first call of
151
+ * a session) leaves the number as the plain estimate - it never pretends to be
152
+ * measured, and it never invents a correction it has not observed.
153
+ */
154
+ export function calibrateEstimate(rawTokens) {
155
+ const ratio = calibrationRatio();
156
+ if (ratio === null || rawTokens <= 0)
157
+ return { tokens: rawTokens, ratio: null, calibrated: false };
158
+ return { tokens: Math.round(rawTokens * ratio), ratio, calibrated: true };
159
+ }
160
+ /** Test hook: clear the retained pairs (also clears the dedupe key). */
161
+ export function resetCalibrationForTests() {
162
+ _calibrationRatios = [];
163
+ _lastCalibrationKey = null;
164
+ _calibrationSession = null;
165
+ }
63
166
  /** Tokens carried by one session entry (message, compaction summary, etc.). */
64
167
  function entryTokens(entry) {
65
168
  if (!entry || typeof entry !== "object")
@@ -114,6 +217,12 @@ export function measureLiveUsage(ctx) {
114
217
  return undefined;
115
218
  const modelWindow = ctx?.model?.contextWindow;
116
219
  const window = resolveWindow(modelWindow);
220
+ try {
221
+ scopeCalibrationToSession(ctx.sessionManager?.getSessionId?.());
222
+ }
223
+ catch {
224
+ /* no session key: keep the store as it is */
225
+ }
117
226
  // Latest compaction boundary: entries strictly before it are compacted
118
227
  // away and are not part of the live payload.
119
228
  let boundary = -1;
@@ -150,14 +259,41 @@ export function measureLiveUsage(ctx) {
150
259
  break;
151
260
  }
152
261
  }
262
+ const estimatedTokens = liveTokens;
263
+ let source = "estimated";
264
+ let estimatedTrailingTokens;
265
+ let calibrationRatioApplied;
153
266
  if (usageBacked) {
267
+ // The provider's count covers exactly the entries from the boundary through
268
+ // the message that carries the usage; pair that count with the walk over
269
+ // the same slice. This is the only place both numbers describe one request.
270
+ let rawUpToUsage = 0;
271
+ for (let i = liveStart; i <= usageBacked.index; i++)
272
+ rawUpToUsage += entryTokens(branch[i]);
273
+ recordCalibrationSample(rawUpToUsage, usageBacked.usageTokens, `${liveStart}:${usageBacked.index}:${usageBacked.usageTokens}`);
154
274
  let trailing = 0;
155
275
  for (let i = usageBacked.index + 1; i < branch.length; i++)
156
276
  trailing += entryTokens(branch[i]);
157
- liveTokens = usageBacked.usageTokens + trailing;
277
+ const calibratedTrailing = calibrateEstimate(trailing);
278
+ liveTokens = usageBacked.usageTokens + calibratedTrailing.tokens;
279
+ source = "measured";
280
+ estimatedTrailingTokens = calibratedTrailing.tokens;
281
+ if (calibratedTrailing.ratio !== null)
282
+ calibrationRatioApplied = calibratedTrailing.ratio;
283
+ }
284
+ else {
285
+ const calibrated = calibrateEstimate(liveTokens);
286
+ liveTokens = calibrated.tokens;
287
+ estimatedTrailingTokens = calibrated.tokens;
288
+ if (calibrated.ratio !== null)
289
+ calibrationRatioApplied = calibrated.ratio;
158
290
  }
159
291
  return {
160
292
  tokens: liveTokens,
293
+ source,
294
+ estimatedTokens,
295
+ estimatedTrailingTokens,
296
+ calibrationRatio: calibrationRatioApplied,
161
297
  contextWindow: window.contextWindow,
162
298
  percent: window.contextWindow > 0 ? (liveTokens / window.contextWindow) * 100 : 0,
163
299
  windowSource: window.windowSource,
@@ -206,4 +342,25 @@ export function tokenArms(providerWindow) {
206
342
  export function formatTokensK(tokens) {
207
343
  return `${Math.round(tokens / 1000)}K`;
208
344
  }
345
+ /**
346
+ * One label for any rendered usage number, naming its provenance. The word is
347
+ * `measured` only when an API response supplied the anchor; everything else is
348
+ * `estimated`, with the calibration factor shown when one was applied. A
349
+ * trailing estimate behind a measured anchor is named rather than folded in -
350
+ * rounding it away is how the number stops meaning anything.
351
+ */
352
+ export function describeUsage(usage) {
353
+ const ratio = usage.calibrationRatio !== undefined ? ` x${usage.calibrationRatio.toFixed(2)}` : "";
354
+ if (usage.source === "measured") {
355
+ const trailing = usage.estimatedTrailingTokens ?? 0;
356
+ return trailing > 0
357
+ ? `measured + ${formatTokensK(trailing)} estimated${ratio}`
358
+ : `measured${ratio}`;
359
+ }
360
+ return `estimated${ratio}`;
361
+ }
362
+ /** `<pct>% <provenance>` - the percent form used wherever a percentage renders. */
363
+ export function describeUsagePercent(usage) {
364
+ return `${usage.percent.toFixed(1)}% ${describeUsage(usage)}`;
365
+ }
209
366
  //# sourceMappingURL=context-usage.js.map
@@ -34,6 +34,13 @@ export interface ClassifiedLlmError {
34
34
  fallbackToNonLlm: boolean;
35
35
  /** Does the user need to do something (top up balance, fix key)? */
36
36
  userActionRequired: boolean;
37
+ /**
38
+ * Set when the failure is about the SHAPE of the request rather than its
39
+ * timing: the same request will be refused the same way, so the retry path
40
+ * and any wake that would start a fresh turn are both wrong. The ring
41
+ * records the same class as a request-shape death.
42
+ */
43
+ requestShape?: "context_length";
37
44
  /** Plain-text hint for the user. Empty for transient/unknown. */
38
45
  userMessage?: string;
39
46
  /** Hint from Retry-After header or computed backoff (ms). */
@@ -75,5 +82,12 @@ export declare function extractHttpCodeFromText(text: string): number | undefine
75
82
  * text predicate so emergency-offload consumers never fork the pattern list.
76
83
  */
77
84
  export declare function isContextWindowErrorText(text: string): boolean;
85
+ /**
86
+ * True when the text names a context-length refusal. Used by consumers that
87
+ * only have text (pi-core surfaces session failures as the assistant's
88
+ * errorMessage string) and must tell "the request must change" apart from
89
+ * "try again later" without re-deriving the pattern list.
90
+ */
91
+ export declare function isContextLengthRequestShape(err: unknown): boolean;
78
92
  export declare function classifyLlmError(err: unknown): ClassifiedLlmError;
79
93
  //# sourceMappingURL=llm-error.d.ts.map
@@ -85,6 +85,43 @@ const CONTEXT_WINDOW_PATTERNS = [
85
85
  /maximum[_ ]context/i,
86
86
  /prompt[_ ]is[_ ]too[_ ]long/i,
87
87
  ];
88
+ /**
89
+ * Context-length refusals in their 400-shaped wordings. A provider that
90
+ * rejects an oversized body with `400 invalid_request_error` is naming a
91
+ * request-shape problem: the numbers change, the verdict does not. Kept apart
92
+ * from CONTEXT_WINDOW_PATTERNS so the bare `413` arm keeps its meaning and a
93
+ * 5xx body cannot be pulled in by a phrase like "too many tokens".
94
+ */
95
+ const REQUEST_SHAPE_CONTEXT_PATTERNS = [
96
+ /maximum[_ ]context[_ ]length/i,
97
+ /context[_ ]length/i,
98
+ /reduce[ _]the[ _]length[ _]of[ _]the/i,
99
+ /(input|prompt|request|messages?)[ _]is[ _]too[ _]long/i,
100
+ /too[ _]many[ _](input[ _])?tokens/i,
101
+ /exceeds?[ _]the[ _](model'?s?[ _])?(maximum|max)/i,
102
+ ];
103
+ /**
104
+ * True when the text names a context-length refusal. Used by consumers that
105
+ * only have text (pi-core surfaces session failures as the assistant's
106
+ * errorMessage string) and must tell "the request must change" apart from
107
+ * "try again later" without re-deriving the pattern list.
108
+ */
109
+ export function isContextLengthRequestShape(err) {
110
+ const text = typeof err === "string"
111
+ ? err
112
+ : typeof err === "object" && err !== null
113
+ ? String(err.message ?? "")
114
+ : "";
115
+ if (!text)
116
+ return false;
117
+ return (matchesAny(text, [
118
+ /context[_ ]length[_ ]exceeded/i,
119
+ /context[_ ]window/i,
120
+ /maximum[_ ]context/i,
121
+ /prompt[_ ]is[_ ]too[_ ]long/i,
122
+ ...REQUEST_SHAPE_CONTEXT_PATTERNS,
123
+ ]) && !matchesAny(text, TRANSIENT_PATTERNS));
124
+ }
88
125
  const TRANSIENT_PATTERNS = [
89
126
  /500/,
90
127
  /502/,
@@ -228,7 +265,13 @@ export function classifyLlmError(err) {
228
265
  return makeError("auth", err);
229
266
  }
230
267
  if (status === 413 || matchesAny(text, CONTEXT_WINDOW_PATTERNS)) {
231
- return makeError("context_window", err);
268
+ return makeError("context_window", err, { requestShape: "context_length" });
269
+ }
270
+ // A 400 whose body names a context-length refusal is the same class as a
271
+ // 413: the request shape is wrong, so it must never fall through to
272
+ // `unknown` (which is retryable, and retrying it unchanged cannot work).
273
+ if (status === 400 && matchesAny(text, REQUEST_SHAPE_CONTEXT_PATTERNS)) {
274
+ return makeError("context_window", err, { requestShape: "context_length" });
232
275
  }
233
276
  if (status === 500 || status === 502 || status === 503 || status === 504 || status === 529) {
234
277
  return makeError("transient", err);
@@ -19,25 +19,21 @@ export declare const CUSTOM_MODEL_KEYS_KEY = "__braid_custom_model_keys";
19
19
  export type CustomModelKeyValue = string | string[];
20
20
  /**
21
21
  * Get the shared custom model keys map.
22
- * polyfill writes to it (/vision-model command).
22
+ * polyfill writes to it (/utility-model command).
23
23
  * model-resolver reads from it (model resolution).
24
24
  */
25
25
  export declare function getCustomModelKeys(): Map<string, CustomModelKeyValue>;
26
26
  /**
27
- * Read a custom model key (e.g. "utilityModel", "visionModel"): a pattern or an
28
- * ordered list of them.
27
+ * Read a custom model key (e.g. "utilityModel"): a pattern or an ordered list
28
+ * of them.
29
29
  */
30
30
  export declare function getCustomModelKey(key: string): CustomModelKeyValue | undefined;
31
31
  /**
32
32
  * Set a custom model key: one pattern or an ordered list. Used by polyfill for
33
- * /utility-model and /vision-model.
33
+ * /utility-model.
34
34
  */
35
35
  export declare function setCustomModelKey(key: string, value: CustomModelKeyValue): void;
36
- export declare const VISION_MODEL_KEY = "visionModel";
37
36
  export declare const UTILITY_MODEL_KEY = "utilityModel";
38
- export declare const MAX_POWER_MODEL_KEY = "maxPowerModel";
39
- /** True the first time it is called in this process, false afterwards. */
40
- export declare function consumeMaxPowerDeprecationNotice(): boolean;
41
37
  export interface RotationState {
42
38
  lastRotationTimestamp: number;
43
39
  turnsSinceRotation: number;
@@ -16,13 +16,14 @@
16
16
  // compiled DIST (dist/lib/state/global-state.js via the pi-braid/lib export).
17
17
  // That yields TWO module instances of this file in one process; a module-level
18
18
  // Map would be populated by the src instance and read (empty) by the dist
19
- // instance — the visionModel custom key would fall through to priority-3
20
- // first-available (MiniMax 429). Same cross-bundle hazard as
21
- // KEY_RING_FEEDBACK_KEY above; the slot must also survive /reload.
19
+ // instance, so the role setting would read as unset and resolution would fall
20
+ // away from it (first-available is where the MiniMax 429 lived). Same
21
+ // cross-bundle hazard as KEY_RING_FEEDBACK_KEY above; the slot must also
22
+ // survive /reload.
22
23
  export const CUSTOM_MODEL_KEYS_KEY = "__braid_custom_model_keys";
23
24
  /**
24
25
  * Get the shared custom model keys map.
25
- * polyfill writes to it (/vision-model command).
26
+ * polyfill writes to it (/utility-model command).
26
27
  * model-resolver reads from it (model resolution).
27
28
  */
28
29
  export function getCustomModelKeys() {
@@ -33,41 +34,23 @@ export function getCustomModelKeys() {
33
34
  return slot[CUSTOM_MODEL_KEYS_KEY];
34
35
  }
35
36
  /**
36
- * Read a custom model key (e.g. "utilityModel", "visionModel"): a pattern or an
37
- * ordered list of them.
37
+ * Read a custom model key (e.g. "utilityModel"): a pattern or an ordered list
38
+ * of them.
38
39
  */
39
40
  export function getCustomModelKey(key) {
40
41
  return getCustomModelKeys().get(key);
41
42
  }
42
43
  /**
43
44
  * Set a custom model key: one pattern or an ordered list. Used by polyfill for
44
- * /utility-model and /vision-model.
45
+ * /utility-model.
45
46
  */
46
47
  export function setCustomModelKey(key, value) {
47
48
  getCustomModelKeys().set(key, value);
48
49
  }
49
- // The vision role is deprecated: the key keeps priority-1 status as an alias
50
- // for one release, after which the merged role supplies image-capable models.
51
- export const VISION_MODEL_KEY = "visionModel";
50
+ // The auxiliary role's key. Both the polyfill (which writes it) and the
51
+ // resolver (which reads it) address the one merged role: vision analysis falls
52
+ // back to its first image-capable entry, so there is no separate vision key.
52
53
  export const UTILITY_MODEL_KEY = "utilityModel";
53
- // The max-power role is folded into utility; the constant survives so the
54
- // polyfill can recognize and clean the legacy key from settings.json; nothing
55
- // resolves it as a live role.
56
- export const MAX_POWER_MODEL_KEY = "maxPowerModel";
57
- /**
58
- * One-shot latch for the maxPowerModel deprecation notice. Process-global for
59
- * the same reason as the keys above: a src-loaded and a dist-loaded instance
60
- * of this module must agree on whether the notice already fired.
61
- */
62
- const MAX_POWER_NOTICE_KEY = "__braid_max_power_deprecation_notice";
63
- /** True the first time it is called in this process, false afterwards. */
64
- export function consumeMaxPowerDeprecationNotice() {
65
- const slot = globalThis;
66
- if (slot[MAX_POWER_NOTICE_KEY])
67
- return false;
68
- slot[MAX_POWER_NOTICE_KEY] = true;
69
- return true;
70
- }
71
54
  function createDefaultRotationState() {
72
55
  return {
73
56
  lastRotationTimestamp: Date.now(),
@@ -103,6 +103,15 @@ export declare function collectAndEmitContextHeartbeat(ctx: ExtensionContext, op
103
103
  export interface SelfStateSample {
104
104
  /** Current context size in tokens (live read, not the last-tick snapshot). */
105
105
  contextTokens: number | null;
106
+ /** Percent of the resolved window the same reading fills; null when unmeasured. */
107
+ contextPercent: number | null;
108
+ /**
109
+ * The meter's own provenance word for the two fields above (`measured`,
110
+ * `estimated`, or a measured anchor plus its estimated trailing part). Null
111
+ * when no reading was available. A reader that cannot tell the two apart
112
+ * cannot tell a large context from a badly counted one.
113
+ */
114
+ contextProvenance: string | null;
106
115
  /** Cache-hit share, percent 0-100 (last assistant message). */
107
116
  cacheHitShare: number | null;
108
117
  /** Near-duplicate message count from the context-density evaluator. */