pi-braid 0.42.1 → 0.43.1

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 (81) hide show
  1. package/CHANGELOG.md +92 -0
  2. package/README.md +61 -228
  3. package/TOOLS.md +12 -14
  4. package/build-info.json +4 -4
  5. package/dist/extensions/core/polyfill/index.d.ts +3 -4
  6. package/dist/extensions/core/polyfill/index.js +34 -131
  7. package/dist/extensions/enforcement/handlers/register-agent-end-api-error.js +13 -0
  8. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +8 -3
  9. package/dist/extensions/enforcement/session-health.d.ts +52 -4
  10. package/dist/extensions/enforcement/session-health.js +75 -5
  11. package/dist/extensions/enforcement/whisper.js +15 -1
  12. package/dist/extensions/heartbeat/heartbeat-scheduler/index.d.ts +17 -0
  13. package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +40 -78
  14. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +2 -1
  15. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +26 -28
  16. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.d.ts +62 -31
  17. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.js +130 -55
  18. package/dist/extensions/memory/context-lifecycle/index.js +11 -10
  19. package/dist/extensions/memory/context-manager/analysis.d.ts +2 -0
  20. package/dist/extensions/memory/context-manager/analysis.js +6 -2
  21. package/dist/extensions/memory/context-manager/handlers/compaction-retry.js +3 -3
  22. package/dist/extensions/memory/context-manager/handlers/events.js +13 -1
  23. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +10 -14
  24. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +62 -88
  25. package/dist/extensions/self/watchdog/engine.d.ts +8 -1
  26. package/dist/extensions/self/watchdog/engine.js +25 -2
  27. package/dist/extensions/self/watchdog/index.js +14 -1
  28. package/dist/lib/ai/llm-call.js +23 -0
  29. package/dist/lib/ai/model-resolver.d.ts +11 -10
  30. package/dist/lib/ai/model-resolver.js +16 -19
  31. package/dist/lib/ai/presend-budget.d.ts +68 -0
  32. package/dist/lib/ai/presend-budget.js +83 -0
  33. package/dist/lib/config/braid-settings.d.ts +38 -0
  34. package/dist/lib/config/braid-settings.js +84 -0
  35. package/dist/lib/config/per-tool-settings.d.ts +4 -4
  36. package/dist/lib/config/per-tool-settings.js +4 -4
  37. package/dist/lib/detection/context-tiers.d.ts +18 -5
  38. package/dist/lib/detection/context-tiers.js +51 -33
  39. package/dist/lib/detection/context-usage.d.ts +62 -1
  40. package/dist/lib/detection/context-usage.js +158 -1
  41. package/dist/lib/errors/llm-error.d.ts +14 -0
  42. package/dist/lib/errors/llm-error.js +44 -1
  43. package/dist/lib/state/global-state.d.ts +4 -8
  44. package/dist/lib/state/global-state.js +11 -28
  45. package/dist/lib/telemetry/context-heartbeat.d.ts +9 -0
  46. package/dist/lib/telemetry/context-heartbeat.js +18 -8
  47. package/dist/lib/utils/wake-gate.d.ts +6 -0
  48. package/dist/lib/utils/wake-gate.js +52 -4
  49. package/docs/SETUP.md +7 -6
  50. package/package.json +8 -11
  51. package/src/extensions/core/polyfill/index.ts +29 -157
  52. package/src/extensions/enforcement/AGENTS.md +38 -1
  53. package/src/extensions/enforcement/handlers/register-agent-end-api-error.ts +13 -0
  54. package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +8 -2
  55. package/src/extensions/enforcement/session-health.ts +94 -5
  56. package/src/extensions/enforcement/whisper.ts +15 -1
  57. package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +53 -80
  58. package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +34 -43
  59. package/src/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.ts +154 -52
  60. package/src/extensions/memory/AGENTS.md +37 -38
  61. package/src/extensions/memory/context-lifecycle/index.ts +11 -10
  62. package/src/extensions/memory/context-manager/analysis.ts +8 -1
  63. package/src/extensions/memory/context-manager/handlers/compaction-retry.ts +3 -3
  64. package/src/extensions/memory/context-manager/handlers/events.ts +18 -1
  65. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +81 -115
  66. package/src/extensions/scheduling/timer/AGENTS.md +14 -4
  67. package/src/extensions/self/watchdog/AGENTS.md +36 -18
  68. package/src/extensions/self/watchdog/engine.ts +30 -2
  69. package/src/extensions/self/watchdog/index.ts +13 -1
  70. package/src/lib/ai/AGENTS.md +2 -0
  71. package/src/lib/ai/llm-call.ts +30 -0
  72. package/src/lib/ai/model-resolver.ts +16 -19
  73. package/src/lib/ai/presend-budget.ts +117 -0
  74. package/src/lib/config/braid-settings.ts +125 -0
  75. package/src/lib/config/per-tool-settings.ts +4 -4
  76. package/src/lib/detection/context-tiers.ts +52 -41
  77. package/src/lib/detection/context-usage.ts +211 -2
  78. package/src/lib/errors/llm-error.ts +55 -1
  79. package/src/lib/state/global-state.ts +11 -29
  80. package/src/lib/telemetry/context-heartbeat.ts +27 -7
  81. package/src/lib/utils/wake-gate.ts +59 -4
@@ -20,7 +20,8 @@
20
20
  * 3. tunnel-down: ≥ tunnelFailures consecutive getUpdates failures
21
21
  * (telegram emits the transition; this engine hosts the
22
22
  * confirmation gate + escalation).
23
- * - ESCALATE: waking whisper (wakeWhisper) + optional 1-line tg signal
23
+ * - ESCALATE: waking whisper (wakeWhisper) + optional 1-line tg signal,
24
+ * or the quiet whisper when the session's route latch is open
24
25
  * (tgSignal). The FIRST escalation of an open condition always fires
25
26
  * (threshold crossing). Repeats while the condition stays continuously
26
27
  * open are milestone-throttled so one long outage cannot flood the owner
@@ -221,8 +222,30 @@ export function createWatchdogEngine(config, deps) {
221
222
  function anyOpen() {
222
223
  return openConditions().length > 0;
223
224
  }
225
+ /**
226
+ * Fail-open read of the turn-start latch. A broken reader costs the gate,
227
+ * never the escalation: the bark still fires, it just wakes.
228
+ */
229
+ function turnStartBlocked() {
230
+ try {
231
+ return deps.isTurnStartBlocked?.() === true;
232
+ }
233
+ catch {
234
+ return false;
235
+ }
236
+ }
224
237
  function fireEscalation(text, tg) {
225
- wakeWhisper(text);
238
+ // While the route latch is open a waking bark would spend the very call
239
+ // the gate exists to save. The escalation is not dropped: the same text
240
+ // rides the quiet channel into the session, and the tg line — which costs
241
+ // no provider call — still fires, so the owner keeps the out-of-band
242
+ // signal.
243
+ if (turnStartBlocked()) {
244
+ quietWhisper(text);
245
+ }
246
+ else {
247
+ wakeWhisper(text);
248
+ }
226
249
  try {
227
250
  tgSignal?.(tg);
228
251
  }
@@ -29,7 +29,7 @@ import { getKeyRingFeedbackHandler, setKeyRingFeedbackHandler, subscribeWatchdog
29
29
  import { loadWatchdogConfig } from "./config.js";
30
30
  import { createWatchdogEngine } from "./engine.js";
31
31
  import { appendContextHeartbeatLine } from "../../../lib/telemetry/context-heartbeat.js";
32
- import { getSessionHealth } from "../../enforcement/session-health.js";
32
+ import { getSessionHealth, isRouteLatchOpen } from "../../enforcement/session-health.js";
33
33
  const log = createLogger("watchdog");
34
34
  /** Extension-state bucket key for the per-session watchdog engine. */
35
35
  const WATCHDOG_ENGINE_KEY = "watchdog-engine";
@@ -247,6 +247,19 @@ export default function (pi) {
247
247
  return false;
248
248
  }
249
249
  },
250
+ // Route-failure latch: the engine asks the health layer, once per
251
+ // escalation, whether a self-started turn would park. While it is
252
+ // open the bark rides the quiet channel and the tg line below still
253
+ // fires (see fireEscalation). Read-only, fail-open: a broken reader
254
+ // must never silence an escalation.
255
+ isTurnStartBlocked: () => {
256
+ try {
257
+ return isRouteLatchOpen(ctx);
258
+ }
259
+ catch {
260
+ return false;
261
+ }
262
+ },
250
263
  log: (level, message, ...rest) => {
251
264
  switch (level) {
252
265
  case "debug":
@@ -45,6 +45,8 @@ import { createLogger } from "../core/logger.js";
45
45
  import { isRateLimitText } from "../errors/llm-error.js";
46
46
  import { isContextWindowErrorText } from "../errors/llm-error.js";
47
47
  import { sanitizeLlmErrorForLog, sanitizeLlmRequestText } from "./payload-hygiene.js";
48
+ import { calibrateEstimate, estimatePayloadTokens, resolveWindow, } from "../detection/context-usage.js";
49
+ import { guardAgainstDoomedSend } from "./presend-budget.js";
48
50
  import { getContextEmergencyOffloadRunner, getExtensionCtxProvider, hasWarnedAuxDegradedTransport, markAuxDegradedTransportWarned, } from "../state/global-state.js";
49
51
  const log = createLogger("llm-call");
50
52
  /** Read the published extension context, or null when none was published. */
@@ -254,6 +256,27 @@ export async function callLlm(model, apiKey, systemPrompt, userPrompt, options =
254
256
  systemPrompt: systemSafe.text,
255
257
  messages: [{ role: "user", content: userSafe.text, timestamp: Date.now() }],
256
258
  };
259
+ // ── pre-send budget ──
260
+ // A request over the window cannot succeed, and a provider 400 is a late,
261
+ // expensive way to learn it. Measure the payload the provider would receive
262
+ // (system + messages, calibrated against this session's own measured ratio),
263
+ // add the output budget, and compare against the resolved window - a
264
+ // configured cap binding below the model's window counts, because the
265
+ // provider will refuse what the cap already refused.
266
+ const resolvedWindow = resolveWindow(model.contextWindow);
267
+ const budget = await guardAgainstDoomedSend({
268
+ measure: () => calibrateEstimate(estimatePayloadTokens({ systemPrompt: context.systemPrompt, messages: context.messages })).tokens,
269
+ outputTokens: maxTokens,
270
+ contextWindow: resolvedWindow.contextWindow,
271
+ // The only compaction available to an auxiliary call is the published
272
+ // offload: it shrinks the session's largest toolResults, which is where an
273
+ // oversized prompt came from. One attempt; nothing freed means still over.
274
+ compact: async () => (await runEmergencyOffloadForCall()) > 0,
275
+ onRefusal: (line) => log.error(line),
276
+ subject: "LLM call",
277
+ });
278
+ if (!budget.allowed)
279
+ return { error: budget.line };
257
280
  // ── per-model concurrency limiter: acquire ONCE at function entry, release in finally ──
258
281
  // (One slot per callLlm invocation, not per retry - otherwise retries could
259
282
  // pile up beyond MAX_CONCURRENT_PER_MODEL.)
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * Model resolution helpers for pi-braid extensions.
3
3
  *
4
- * Resolves the merged auxiliary role (utilityModel) and the deprecated vision
5
- * alias: a setting may hold one model pattern or an ordered list, and the
4
+ * Resolves the merged auxiliary role (utilityModel) and the model a vision call
5
+ * needs: a setting may hold one model pattern or an ordered list, and the
6
6
  * resolver walks the list with the provider layer deciding per entry.
7
7
  */
8
8
  import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -27,15 +27,16 @@ export declare function normaliseRoleSetting(raw: unknown): string[];
27
27
  */
28
28
  export declare function resolveUtilityModels(ctx: ExtensionContext): Model<Api>[];
29
29
  /**
30
- * Get the best vision model.
30
+ * The model a vision call should use.
31
+ *
31
32
  * Priority:
32
- * 1. Custom visionModel setting (deprecated alias, honored this release);
33
- * when it is an ordered list, the first entry that accepts image input
34
- * and whose route the provider layer reports usable
35
- * 2. Current model if vision-capable
36
- * 3. The merged role's first image-capable entry whose route the provider
37
- * layer reports usable (same ordered-list semantics as any role)
38
- * 4. First available vision model
33
+ * 1. The current model when it accepts images: the image stays in the call
34
+ * that already carries the prompt and the conversation
35
+ * 2. The merged role's first image-capable entry whose route the provider
36
+ * layer reports usable (the same ordered-list semantics as any role)
37
+ * 3. The first available model that accepts images
38
+ *
39
+ * A text-only entry is never selected for an image call.
39
40
  */
40
41
  export declare function resolveVisionModel(ctx: ExtensionContext): Model<Api> | undefined;
41
42
  /**
@@ -1,11 +1,11 @@
1
1
  /**
2
2
  * Model resolution helpers for pi-braid extensions.
3
3
  *
4
- * Resolves the merged auxiliary role (utilityModel) and the deprecated vision
5
- * alias: a setting may hold one model pattern or an ordered list, and the
4
+ * Resolves the merged auxiliary role (utilityModel) and the model a vision call
5
+ * needs: a setting may hold one model pattern or an ordered list, and the
6
6
  * resolver walks the list with the provider layer deciding per entry.
7
7
  */
8
- import { getCustomModelKey, UTILITY_MODEL_KEY, VISION_MODEL_KEY } from "../state/global-state.js";
8
+ import { getCustomModelKey, UTILITY_MODEL_KEY } from "../state/global-state.js";
9
9
  import { callLlm, isModelRouteUsable } from "./llm-call.js";
10
10
  /**
11
11
  * Resolve a model from a pattern like "provider/model-id" or just "model-id".
@@ -83,30 +83,27 @@ export function resolveUtilityModels(ctx) {
83
83
  .filter((model) => model !== undefined);
84
84
  }
85
85
  /**
86
- * Get the best vision model.
86
+ * The model a vision call should use.
87
+ *
87
88
  * Priority:
88
- * 1. Custom visionModel setting (deprecated alias, honored this release);
89
- * when it is an ordered list, the first entry that accepts image input
90
- * and whose route the provider layer reports usable
91
- * 2. Current model if vision-capable
92
- * 3. The merged role's first image-capable entry whose route the provider
93
- * layer reports usable (same ordered-list semantics as any role)
94
- * 4. First available vision model
89
+ * 1. The current model when it accepts images: the image stays in the call
90
+ * that already carries the prompt and the conversation
91
+ * 2. The merged role's first image-capable entry whose route the provider
92
+ * layer reports usable (the same ordered-list semantics as any role)
93
+ * 3. The first available model that accepts images
94
+ *
95
+ * A text-only entry is never selected for an image call.
95
96
  */
96
97
  export function resolveVisionModel(ctx) {
97
- // 1. Deprecated role key; still priority 1 for one release
98
- const custom = resolveRoleModel(ctx, VISION_MODEL_KEY, true);
99
- if (custom)
100
- return custom;
101
- // 2. Current model if vision-capable
98
+ // 1. Current model if vision-capable
102
99
  if (ctx.model?.input?.includes("image"))
103
100
  return ctx.model;
104
- // 3. The merged role supplies an image-capable entry, so the vision pin is
105
- // redundant after this release except as a determinism override.
101
+ // 2. The merged role supplies an image-capable entry; a text-only entry in
102
+ // the list is skipped rather than sent an image.
106
103
  const role = resolveRoleModel(ctx, UTILITY_MODEL_KEY, true);
107
104
  if (role)
108
105
  return role;
109
- // 4. First available vision model
106
+ // 3. First available vision model
110
107
  const available = ctx.modelRegistry.getAvailable();
111
108
  return available.find((m) => m?.input?.includes("image"));
112
109
  }
@@ -0,0 +1,68 @@
1
+ /**
2
+ * Pre-send budget: compare the request about to be sent against the model's
3
+ * resolved window, and refuse instead of letting the provider refuse.
4
+ *
5
+ * Why here: this is a request-layer decision. It needs three things at once -
6
+ * the outgoing payload, the requested output budget, and the resolved window -
7
+ * and only the layer that BUILDS the request has all three. A consumer that
8
+ * reads a percentage sees a number someone else measured; it cannot see what
9
+ * the provider is about to be handed.
10
+ *
11
+ * Why a guard and not a warning: a request over the window cannot succeed, so
12
+ * sending it buys nothing and costs a full round trip, a retry, and a session
13
+ * that looks wedged to whoever is watching. The remedy that actually frees
14
+ * space is compaction, and the caller owns it - so the guard runs it once and
15
+ * re-measures, and only then decides.
16
+ */
17
+ export interface SendBudgetInput {
18
+ /** Calibrated tokens of the payload as it stands now. */
19
+ payloadTokens: number;
20
+ /** The output budget the request asks for; it is spent from the same window. */
21
+ outputTokens: number;
22
+ /** Resolved window (a configured cap may already bind below the model's). */
23
+ contextWindow: number;
24
+ }
25
+ export interface SendBudgetVerdict {
26
+ fits: boolean;
27
+ /** payloadTokens + outputTokens. */
28
+ projectedTokens: number;
29
+ contextWindow: number;
30
+ /** Tokens past the window; 0 when the request fits. */
31
+ overBy: number;
32
+ }
33
+ export declare function checkSendBudget(input: SendBudgetInput): SendBudgetVerdict;
34
+ /**
35
+ * The one line a refusal is allowed to say. It carries the three numbers a
36
+ * reader needs to act (payload, output budget, window) and names the remedy,
37
+ * because "context overflow" alone leaves nothing to do.
38
+ */
39
+ export declare function formatSendBudgetRefusal(verdict: SendBudgetVerdict, subject?: string): string;
40
+ export type GuardedSend = {
41
+ allowed: true;
42
+ verdict: SendBudgetVerdict;
43
+ compacted: boolean;
44
+ } | {
45
+ allowed: false;
46
+ verdict: SendBudgetVerdict;
47
+ line: string;
48
+ compacted: boolean;
49
+ };
50
+ /**
51
+ * Decide whether the send may proceed: measure, compare, and when the request
52
+ * cannot fit, run the caller's compaction ONCE and measure again.
53
+ *
54
+ * `compact` returns true only when it actually freed context. A compaction
55
+ * that frees nothing must not re-open the door - the second measurement is the
56
+ * one that decides, and it is taken after the compaction, not assumed from it.
57
+ * `measure` is called fresh each time for the same reason: the payload after a
58
+ * compaction is a different payload.
59
+ */
60
+ export declare function guardAgainstDoomedSend(params: {
61
+ measure: () => number;
62
+ outputTokens: number;
63
+ contextWindow: number;
64
+ compact?: () => Promise<boolean> | boolean;
65
+ onRefusal?: (line: string, verdict: SendBudgetVerdict) => void;
66
+ subject?: string;
67
+ }): Promise<GuardedSend>;
68
+ //# sourceMappingURL=presend-budget.d.ts.map
@@ -0,0 +1,83 @@
1
+ /**
2
+ * Pre-send budget: compare the request about to be sent against the model's
3
+ * resolved window, and refuse instead of letting the provider refuse.
4
+ *
5
+ * Why here: this is a request-layer decision. It needs three things at once -
6
+ * the outgoing payload, the requested output budget, and the resolved window -
7
+ * and only the layer that BUILDS the request has all three. A consumer that
8
+ * reads a percentage sees a number someone else measured; it cannot see what
9
+ * the provider is about to be handed.
10
+ *
11
+ * Why a guard and not a warning: a request over the window cannot succeed, so
12
+ * sending it buys nothing and costs a full round trip, a retry, and a session
13
+ * that looks wedged to whoever is watching. The remedy that actually frees
14
+ * space is compaction, and the caller owns it - so the guard runs it once and
15
+ * re-measures, and only then decides.
16
+ */
17
+ import { formatTokensK } from "../detection/context-usage.js";
18
+ export function checkSendBudget(input) {
19
+ const projectedTokens = input.payloadTokens + Math.max(0, input.outputTokens);
20
+ const contextWindow = input.contextWindow;
21
+ const overBy = contextWindow > 0 ? Math.max(0, projectedTokens - contextWindow) : 0;
22
+ return {
23
+ fits: contextWindow > 0 && overBy === 0,
24
+ projectedTokens,
25
+ contextWindow,
26
+ overBy,
27
+ };
28
+ }
29
+ /**
30
+ * The one line a refusal is allowed to say. It carries the three numbers a
31
+ * reader needs to act (payload, output budget, window) and names the remedy,
32
+ * because "context overflow" alone leaves nothing to do.
33
+ */
34
+ export function formatSendBudgetRefusal(verdict, subject = "request") {
35
+ const window = verdict.contextWindow > 0 ? formatTokensK(verdict.contextWindow) : "unknown window";
36
+ return (`Context budget refused: ${subject} needs ${formatTokensK(verdict.projectedTokens)} ` +
37
+ `(payload + output budget) against a ${window} window, over by ${formatTokensK(verdict.overBy)}. ` +
38
+ `Nothing was sent. Compact first (\`context_compress action="archive"\`), or lower the output ` +
39
+ `budget, then retry.`);
40
+ }
41
+ /**
42
+ * Decide whether the send may proceed: measure, compare, and when the request
43
+ * cannot fit, run the caller's compaction ONCE and measure again.
44
+ *
45
+ * `compact` returns true only when it actually freed context. A compaction
46
+ * that frees nothing must not re-open the door - the second measurement is the
47
+ * one that decides, and it is taken after the compaction, not assumed from it.
48
+ * `measure` is called fresh each time for the same reason: the payload after a
49
+ * compaction is a different payload.
50
+ */
51
+ export async function guardAgainstDoomedSend(params) {
52
+ const window = params.contextWindow;
53
+ let verdict = checkSendBudget({
54
+ payloadTokens: params.measure(),
55
+ outputTokens: params.outputTokens,
56
+ contextWindow: window,
57
+ });
58
+ if (verdict.fits)
59
+ return { allowed: true, verdict, compacted: false };
60
+ let compacted = false;
61
+ if (params.compact) {
62
+ try {
63
+ compacted = (await params.compact()) === true;
64
+ }
65
+ catch {
66
+ // A failed compaction leaves the request where it was: still over.
67
+ compacted = false;
68
+ }
69
+ }
70
+ if (compacted) {
71
+ verdict = checkSendBudget({
72
+ payloadTokens: params.measure(),
73
+ outputTokens: params.outputTokens,
74
+ contextWindow: window,
75
+ });
76
+ if (verdict.fits)
77
+ return { allowed: true, verdict, compacted: true };
78
+ }
79
+ const line = formatSendBudgetRefusal(verdict, params.subject);
80
+ params.onRefusal?.(line, verdict);
81
+ return { allowed: false, verdict, line, compacted };
82
+ }
83
+ //# sourceMappingURL=presend-budget.js.map
@@ -340,6 +340,44 @@ export declare function resolveTerminalBreaker(raw: unknown): TerminalBreakerCon
340
340
  * reads this once per fire.
341
341
  */
342
342
  export declare function getTerminalBreakerConfig(): TerminalBreakerConfig;
343
+ /** Default provider-failure count before self-started turns park. */
344
+ export declare const ROUTE_BREAKER_DEFAULT_THRESHOLD = 3;
345
+ /** Upper bound for a configured threshold (guards a typo'd huge value). */
346
+ export declare const ROUTE_BREAKER_THRESHOLD_MAX = 20;
347
+ /**
348
+ * Default cadence of the single released turn while the latch stays open.
349
+ * One hour: long enough that a parked session does not spend a call per
350
+ * retry against a route that is failing every time, short enough that an
351
+ * owner who never touches the session still gets an automatic attempt.
352
+ */
353
+ export declare const ROUTE_BREAKER_DEFAULT_FLOOR_MS = 3600000;
354
+ /** Bounds on a configured floor: below the slowest retry cadence it would
355
+ * release a turn per retry; above a day it stops being a floor at all. */
356
+ export declare const ROUTE_BREAKER_FLOOR_MIN_MS = 60000;
357
+ export declare const ROUTE_BREAKER_FLOOR_MAX_MS = 86400000;
358
+ export interface RouteBreakerConfig {
359
+ /** Master gate. Default true. */
360
+ enabled: boolean;
361
+ /** Provider failures since the last successful call before wakes park. */
362
+ threshold: number;
363
+ /** The one released turn's cadence while the latch stays open. */
364
+ floorMs: number;
365
+ }
366
+ /**
367
+ * Pure resolver for braid.session.routeBreaker. Absent block ⇒ default-on with
368
+ * threshold 3 and a 1h floor. `enabled: false` ⇒ the breaker is inert. A
369
+ * threshold or floor that is not a valid integer in range warns once and
370
+ * falls back to its default; a non-object block counts as absent. Kept pure
371
+ * so the validation is unit-testable without touching live settings.json.
372
+ */
373
+ export declare function resolveRouteBreaker(raw: unknown): RouteBreakerConfig;
374
+ /**
375
+ * Read the effective route-failure wake-breaker config from settings.json,
376
+ * fresh on every call (no caching), like the other readers. The predicate and
377
+ * the feed read this once per call; the floor's clock leans on it, so a
378
+ * runtime change takes effect on the next turn-start question.
379
+ */
380
+ export declare function getRouteBreakerConfig(): RouteBreakerConfig;
343
381
  /** Default wake-delivery alerting: on, page after 2 outcome timeouts. */
344
382
  export declare const WAKE_DELIVERY_ALERT_DEFAULT: WakeDeliveryAlertConfig;
345
383
  /** Upper bound for the outcome-timeout page threshold. */
@@ -637,6 +637,90 @@ export function resolveTerminalBreaker(raw) {
637
637
  export function getTerminalBreakerConfig() {
638
638
  return resolveTerminalBreaker(readSettings().braid?.session?.terminalBreaker);
639
639
  }
640
+ // ── route-failure wake breaker (braid.session.routeBreaker) ────────────
641
+ /** Default provider-failure count before self-started turns park. */
642
+ export const ROUTE_BREAKER_DEFAULT_THRESHOLD = 3;
643
+ /** Upper bound for a configured threshold (guards a typo'd huge value). */
644
+ export const ROUTE_BREAKER_THRESHOLD_MAX = 20;
645
+ /**
646
+ * Default cadence of the single released turn while the latch stays open.
647
+ * One hour: long enough that a parked session does not spend a call per
648
+ * retry against a route that is failing every time, short enough that an
649
+ * owner who never touches the session still gets an automatic attempt.
650
+ */
651
+ export const ROUTE_BREAKER_DEFAULT_FLOOR_MS = 3_600_000;
652
+ /** Bounds on a configured floor: below the slowest retry cadence it would
653
+ * release a turn per retry; above a day it stops being a floor at all. */
654
+ export const ROUTE_BREAKER_FLOOR_MIN_MS = 60_000;
655
+ export const ROUTE_BREAKER_FLOOR_MAX_MS = 86_400_000;
656
+ /** Warned once per process about an invalid routeBreaker field. */
657
+ let _warnedInvalidRouteBreaker = false;
658
+ /** Once-per-process warning for an ignored routeBreaker value. */
659
+ function _warnInvalidRouteBreaker(field, value) {
660
+ if (_warnedInvalidRouteBreaker)
661
+ return;
662
+ _warnedInvalidRouteBreaker = true;
663
+ const expected = field === "threshold"
664
+ ? `an integer 1..${ROUTE_BREAKER_THRESHOLD_MAX}`
665
+ : `an integer ${ROUTE_BREAKER_FLOOR_MIN_MS}..${ROUTE_BREAKER_FLOOR_MAX_MS} (ms)`;
666
+ const fallback = field === "threshold" ? ROUTE_BREAKER_DEFAULT_THRESHOLD : ROUTE_BREAKER_DEFAULT_FLOOR_MS;
667
+ _log.warn(`Invalid braid.session.routeBreaker in settings.json - ignoring ${field} and ` +
668
+ `using the default (${fallback}). Expected ${expected}.`, { field, value });
669
+ }
670
+ /**
671
+ * Pure resolver for braid.session.routeBreaker. Absent block ⇒ default-on with
672
+ * threshold 3 and a 1h floor. `enabled: false` ⇒ the breaker is inert. A
673
+ * threshold or floor that is not a valid integer in range warns once and
674
+ * falls back to its default; a non-object block counts as absent. Kept pure
675
+ * so the validation is unit-testable without touching live settings.json.
676
+ */
677
+ export function resolveRouteBreaker(raw) {
678
+ const defaults = {
679
+ enabled: true,
680
+ threshold: ROUTE_BREAKER_DEFAULT_THRESHOLD,
681
+ floorMs: ROUTE_BREAKER_DEFAULT_FLOOR_MS,
682
+ };
683
+ if (raw === undefined || raw === null || typeof raw !== "object")
684
+ return defaults;
685
+ const block = raw;
686
+ const enabled = block.enabled !== false;
687
+ let threshold = defaults.threshold;
688
+ if (block.threshold !== undefined) {
689
+ const v = block.threshold;
690
+ if (typeof v === "number" &&
691
+ Number.isInteger(v) &&
692
+ v >= 1 &&
693
+ v <= ROUTE_BREAKER_THRESHOLD_MAX) {
694
+ threshold = v;
695
+ }
696
+ else {
697
+ _warnInvalidRouteBreaker("threshold", v);
698
+ }
699
+ }
700
+ let floorMs = defaults.floorMs;
701
+ if (block.floorMs !== undefined) {
702
+ const v = block.floorMs;
703
+ if (typeof v === "number" &&
704
+ Number.isInteger(v) &&
705
+ v >= ROUTE_BREAKER_FLOOR_MIN_MS &&
706
+ v <= ROUTE_BREAKER_FLOOR_MAX_MS) {
707
+ floorMs = v;
708
+ }
709
+ else {
710
+ _warnInvalidRouteBreaker("floorMs", v);
711
+ }
712
+ }
713
+ return { enabled, threshold, floorMs };
714
+ }
715
+ /**
716
+ * Read the effective route-failure wake-breaker config from settings.json,
717
+ * fresh on every call (no caching), like the other readers. The predicate and
718
+ * the feed read this once per call; the floor's clock leans on it, so a
719
+ * runtime change takes effect on the next turn-start question.
720
+ */
721
+ export function getRouteBreakerConfig() {
722
+ return resolveRouteBreaker(readSettings().braid?.session?.routeBreaker);
723
+ }
640
724
  // ── wake-delivery stall alert (braid.timers.wakeAlert) ───────────────
641
725
  /** Default wake-delivery alerting: on, page after 2 outcome timeouts. */
642
726
  export const WAKE_DELIVERY_ALERT_DEFAULT = {
@@ -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
@@ -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
@@ -45,14 +45,21 @@ export declare const CONTEXT_USAGE_TIERS: readonly ContextUsageTierInfo[];
45
45
  * (compact → critical → warning → advisory → soft).
46
46
  */
47
47
  export declare function contextUsageTier(usagePercent: number): ContextUsageTierInfo | null;
48
- /** Percent-tier nudge message text (identical at every enforcement site). */
49
- export declare function contextUsageTierMessage(tier: ContextUsageTier, usagePercent: number): string;
48
+ /**
49
+ * Percent-tier nudge message text (identical at every enforcement site).
50
+ * One sentence names the state and the deadline, then the action. No number
51
+ * is restated: the rung's bar selected this message, and the meter rendered
52
+ * the count where a count belongs (context_inspect, the tool result).
53
+ */
54
+ export declare function contextUsageTierMessage(tier: ContextUsageTier): string;
50
55
  /**
51
56
  * Token-tier nudge message text (identical at every enforcement site).
52
57
  * `level` mirrors the tier reached by the token-count check; arms are
53
- * fractions of the resolved window (0.45W warning, 0.18W soft).
58
+ * fractions of the resolved window (0.45W warning, 0.18W soft). The text is
59
+ * the tier's: a rung is a threshold, not a label, and the whisper no longer
60
+ * renders the count that selected it.
54
61
  */
55
- export declare function contextUsageTokenMessage(level: "warning" | "soft", usagePercent: number, usageTokens: number): string;
62
+ export declare function contextUsageTokenMessage(level: "warning" | "soft"): string;
56
63
  export type ContextNudgeId = "tokens:soft" | "tokens:warning" | "percent:soft" | "percent:advisory" | "percent:warning" | "percent:critical" | "percent:compact";
57
64
  export interface ContextNudgeRung {
58
65
  /** Stable rung identity — what a latch records to suppress a repeat. */
@@ -74,7 +81,13 @@ export interface ContextNudge extends ContextNudgeRung {
74
81
  * (the ladder is built weakest-first), and an equal position is not an
75
82
  * escalation.
76
83
  */
77
- export declare function resolveContextNudge(usagePercent: number, usageTokens: number, window?: number | null): ContextNudge | null;
84
+ export declare function resolveContextNudge(usagePercent: number, usageTokens: number, window?: number | null,
85
+ /**
86
+ * How the number was produced (measured / estimated). Rendered with the
87
+ * message so a reader can tell a large context from a badly counted one;
88
+ * the ladder itself is unchanged, since a rung is a bar, not a label.
89
+ */
90
+ provenance?: string): ContextNudge | null;
78
91
  /**
79
92
  * One rung by id, resolved against the window in hand: a window change
80
93
  * re-derives the rung's bar instead of comparing a live count against a stale