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
@@ -32,7 +32,7 @@ import { getSessionIdSafe } from "../../../lib/state/extension-state.js";
32
32
  import { deriveProjectIdFromCwd } from "../../../lib/memory/past-insights.js";
33
33
  import { shouldWriteOutcomeEpisode } from "../../../lib/memory/write-quality.js";
34
34
  import { getMemoryWriteGateConfig } from "../../../lib/config/braid-settings.js";
35
- import { formatLocalTime } from "../../../lib/utils/local-time.js";
35
+ import { nowOrOverride } from "../../../lib/utils/local-time.js";
36
36
  /** Derive a short project id from the current working directory. */
37
37
  function deriveProject(ctx) {
38
38
  return typeof ctx.cwd === "string" ? deriveProjectIdFromCwd(ctx.cwd) : "unknown";
@@ -96,7 +96,12 @@ const _heartbeatWhisperBuffer = new Map();
96
96
  // lastWriteAt is owned here (module scope, survives across sessions within the
97
97
  // process) so the cooldown actually throttles back-to-back session ends.
98
98
  let _lastOutcomeWriteAt = 0;
99
- function bufferHeartbeatWhisper(sessionId, message, priority, source) {
99
+ /**
100
+ * Buffer one whisper for the next delivery. Exported because it and
101
+ * flushDelayedWhispers are the delivery boundary a fixture must drive to
102
+ * assert on the text that ships (the same pair before_agent_start calls).
103
+ */
104
+ export function bufferHeartbeatWhisper(sessionId, message, priority, source, family) {
100
105
  let buffer = _heartbeatWhisperBuffer.get(sessionId);
101
106
  if (!buffer) {
102
107
  buffer = [];
@@ -106,70 +111,27 @@ function bufferHeartbeatWhisper(sessionId, message, priority, source) {
106
111
  // ticks can pile up while the session is idle (no before_agent_start to
107
112
  // flush). Cap at 100 entries per session, drop-oldest — stale heartbeat
108
113
  // messages past 100 are noise by definition.
109
- pushBounded(buffer, { message, priority, source }, 100);
114
+ pushBounded(buffer, { message, priority, source, family }, 100);
110
115
  }
111
- function flushDelayedWhispers(sessionId, pi, selfState) {
116
+ /**
117
+ * Drain the delayed buffer as one delivery per priority tier.
118
+ *
119
+ * The sample is taken here, at delivery, and is the only source of the
120
+ * numbers and of the tier the context family is re-labelled with: a family
121
+ * rendered from an older reading is what printed a label beside numbers it
122
+ * never measured.
123
+ */
124
+ export function flushDelayedWhispers(sessionId, pi, sample) {
112
125
  const buffer = _heartbeatWhisperBuffer.get(sessionId);
113
126
  if (!buffer || buffer.length === 0)
114
127
  return;
115
128
  const batch = buffer.splice(0);
116
- // Deduplicate near-duplicate messages: extract a semantic type key from
117
- // each message. Messages of the same type (e.g., "Context at 40%..." and
118
- // "Context at 50%...") collapse to one, so the Heartbeat Summary never
119
- // lists 9 near-identical context-percentage messages with slightly
120
- // different token counts.
121
- function dedupKey(message) {
122
- // Context percentage messages: "Context at 40%. context_tag..."
123
- if (/^Context at \d+%/.test(message))
124
- return "context-percentage";
125
- // Duplicate count messages: "39 near-duplicate messages..."
126
- if (/^\d+ near-duplicate messages/.test(message))
127
- return "duplicate-count";
128
- // Context density messages
129
- if (/^Low context density/.test(message))
130
- return "density-low";
131
- if (/^High density/.test(message))
132
- return "density-high";
133
- if (/^Context density still low/.test(message))
134
- return "density-low-persistent";
135
- // Proactive projection messages
136
- if (/^\[proactive\]/.test(message))
137
- return "proactive-projection";
138
- // Degradation messages
139
- if (/^Degradation detected/.test(message))
140
- return "degradation";
141
- // Fallback: use first 80 chars
142
- return message.slice(0, 80);
143
- }
144
- const deduped = [];
145
- const seen = new Set();
146
- for (const entry of batch) {
147
- const key = dedupKey(entry.message);
148
- if (seen.has(key))
149
- continue;
150
- seen.add(key);
151
- deduped.push({ message: entry.message, priority: entry.priority });
152
- }
153
- // Aggregate by priority tier
154
- const groups = new Map();
155
- for (const entry of deduped) {
156
- const p = entry.priority;
157
- if (!groups.has(p))
158
- groups.set(p, []);
159
- groups.get(p).push(entry.message);
160
- }
161
- for (const [, messages] of groups) {
162
- // Fresh clock: every Heartbeat Summary carries a `now:` line (date +
163
- // owner-TZ time via the ONE formatter) so a long session never reasons on
164
- // a stale clock — the heartbeat is the only mid-session channel guaranteed
165
- // to re-fire. One context-health line follows the clock (tokens /
166
- // cache-hit / near-dups / tok-s trend), so every heartbeat delivery is
167
- // also a self-state checkpoint.
168
- const nowLine = `now: ${formatLocalTime(new Date(), true)}`;
169
- const selfStateSuffix = selfState ? `\n${selfState}` : "";
170
- const text = messages.length === 1
171
- ? `${nowLine}${selfStateSuffix}\n${messages[0]}`
172
- : `[Heartbeat Summary]\n${nowLine}${selfStateSuffix}\n${messages.map((m, i) => `${i + 1}. ${m}`).join("\n")}`;
129
+ const deliveries = renderDelayedDelivery(batch, {
130
+ at: nowOrOverride(),
131
+ contextPercent: sample?.contextPercent ?? null,
132
+ selfState: buildSelfStateLine(sample),
133
+ });
134
+ for (const text of deliveries) {
173
135
  try {
174
136
  sendTrackedMessage(pi, {
175
137
  customType: "heartbeat",
@@ -216,13 +178,14 @@ export function sendSopCoachWhisper(pi, message) {
216
178
  }, { delivery: "park", deliverAs: "steer" }, { type: "context", source: "heartbeat/sop-coach" });
217
179
  }
218
180
  // Whisper Batching
219
- // flushWhisperBuffer lives in ./whisper-batcher.ts. The tick function
220
- // imports it to flush module whispers as aggregated messages.
221
- import { flushWhisperBuffer } from "./whisper-batcher.js";
222
- import { buildSelfStateLine } from "./whisper-batcher.js";
181
+ // flushWhisperBuffer and the delayed-delivery renderer live in
182
+ // ./whisper-batcher.ts. This file owns the buffer and the send channel; the
183
+ // batcher owns the text, so the shipped delivery and the tested delivery are
184
+ // the same function.
185
+ import { flushWhisperBuffer, buildSelfStateLine, renderDelayedDelivery, } from "./whisper-batcher.js";
223
186
  import { getSelfStateSample } from "../../../lib/telemetry/context-heartbeat.js";
224
187
  // Tick Engine
225
- function tick(pi, state, config, ctx, turnEvent) {
188
+ function tick(pi, state, config, ctx) {
226
189
  state.stats.totalTicks++;
227
190
  // Real telemetry: collect live context/RSS/session metrics, append the
228
191
  // JSONL heartbeat line, and feed recordTurnMetrics real values (not
@@ -296,7 +259,7 @@ function tick(pi, state, config, ctx, turnEvent) {
296
259
  log.warn(`[heartbeat] pending-compaction advisory failed: ${err}`);
297
260
  }
298
261
  try {
299
- maybeArmAutoCompaction(pi, ctx, turnEvent);
262
+ maybeArmAutoCompaction(pi, ctx);
300
263
  }
301
264
  catch (err) {
302
265
  log.warn(`[heartbeat] context auto-arm check failed: ${err}`);
@@ -496,12 +459,9 @@ export default function heartbeatExtension(pi) {
496
459
  const interval = getAdaptiveInterval(state);
497
460
  if (state.turnCount % interval !== 0)
498
461
  return;
499
- // The boundary travels with the tick: the usage-driven auto-arm arms inside
500
- // this dispatch, and a drain there can only be judged from the event that
501
- // named the boundary. Dropping this argument is invisible to every other
502
- // fixture, so one drives the real handler end to end:
503
- // test/runtime/heartbeat/test-turn-boundary-arm-wiring.mjs.
504
- tick(pi, state, config, ctx, event);
462
+ // The tick arms the usage-driven auto compaction on its own cadence. The
463
+ // arm only queues; the queue drains at settle (or the 0.90W backstop).
464
+ tick(pi, state, config, ctx);
505
465
  });
506
466
  // Event: before_agent_start - flush delayed whispers
507
467
  // Deliver buffered heartbeat whispers as part of the turn context,
@@ -519,9 +479,11 @@ export default function heartbeatExtension(pi) {
519
479
  if (typeof prompt === "string" && prompt.length > 0) {
520
480
  getTurnStartPrompt(ctx).prompt = prompt;
521
481
  }
522
- // Self-state (Refine-2): every heartbeat-family delivery carries the
523
- // self-state line. Sampling never throws; missing telemetry -> "n/a".
524
- flushDelayedWhispers(sid, pi, buildSelfStateLine(getSelfStateSample(ctx)));
482
+ // The sample is taken here, at delivery: the self-state line and the
483
+ // context family's arm are both rendered from it, so one delivery never
484
+ // prints two ages of one fact. Sampling never throws; missing telemetry
485
+ // renders "n/a".
486
+ flushDelayedWhispers(sid, pi, getSelfStateSample(ctx));
525
487
  });
526
488
  // Event: tool_call
527
489
  pi.on(TOOL_CALL, async (event, ctx) => {
@@ -644,9 +606,9 @@ export default function heartbeatExtension(pi) {
644
606
  // (below) still delivers immediately because it uses
645
607
  // deliverAs:"steer" and is time-critical (at ≥90% context the
646
608
  // whisper may never get a next turn — steer it into the current run).
647
- (msg) => {
609
+ (msg, family) => {
648
610
  const sid = getSessionIdSafe(ctx) ?? "anonymous";
649
- bufferHeartbeatWhisper(sid, msg, "medium", "heartbeat/policy");
611
+ bufferHeartbeatWhisper(sid, msg, "medium", "heartbeat/policy", family);
650
612
  }, (msg) => {
651
613
  sendTrackedMessage(pi, {
652
614
  customType: "heartbeat",
@@ -7,6 +7,7 @@
7
7
  */
8
8
  import type { Policy } from "../../../lib/store/belief-store.js";
9
9
  import type { ToolTracking } from "./types.js";
10
+ import type { WhisperFamily } from "./whisper-batcher.js";
10
11
  export declare const VERIFICATION_TOOLS: Set<string>;
11
12
  export declare const WEB_TOOLS: Set<string>;
12
13
  export declare const CODE_TOOLS: Set<string>;
@@ -17,5 +18,5 @@ export declare function bashCommandIsVerification(command: string): boolean;
17
18
  * bash by the command's shape. Every other tool is not verification.
18
19
  */
19
20
  export declare function isVerificationToolCall(toolName: string, input: unknown): boolean;
20
- export declare function createDefaultPolicies(getToolTracking: () => ToolTracking, onSignal: (type: string, data: Record<string, unknown>) => void, sendWhisper: (msg: string) => void, sendSteerMessage: (msg: string) => void): Policy[];
21
+ export declare function createDefaultPolicies(getToolTracking: () => ToolTracking, onSignal: (type: string, data: Record<string, unknown>) => void, sendWhisper: (msg: string, family?: WhisperFamily) => void, sendSteerMessage: (msg: string) => void): Policy[];
21
22
  //# sourceMappingURL=policies.d.ts.map
@@ -6,8 +6,8 @@
6
6
  * and proactive context monitoring with auto-finalize at 90%.
7
7
  */
8
8
  import { createLogger } from "../../../lib/core/logger.js";
9
- import { USAGE_WHISPER_SOFT, USAGE_WHISPER_ADVISORY, USAGE_WHISPER_WARNING, USAGE_WHISPER_CRITICAL, USAGE_FIRED_RESET_BELOW, } from "../../../lib/detection/context-thresholds.js";
10
- import { CONTEXT_USAGE_TIERS, getContextUsage, } from "../../../lib/detection/context-tiers.js";
9
+ import { USAGE_WHISPER_CRITICAL, USAGE_FIRED_RESET_BELOW, } from "../../../lib/detection/context-thresholds.js";
10
+ import { CONTEXT_USAGE_TIERS, contextUsageTierMessage, getContextUsage, } from "../../../lib/detection/context-tiers.js";
11
11
  const log = createLogger("heartbeat:policies");
12
12
  /**
13
13
  * Persist fired threshold set across invocations so the context-monitor
@@ -413,9 +413,10 @@ export function createDefaultPolicies(getToolTracking, onSignal, sendWhisper, se
413
413
  return turnsSince >= 10 && t.totalToolsUsed > 3;
414
414
  },
415
415
  action: async (ctx) => {
416
+ // One instruction, not a menu. The agent does not need to be asked
417
+ // whether it is sure; it needs the step that would settle it.
416
418
  sendWhisper("No verification (grep/read/search) in 10+ turns. " +
417
- "Consider: Are you sure the implementation is correct? " +
418
- "Verify with grep or read to confirm.");
419
+ "Verify with grep or read before continuing.");
419
420
  onSignal("verification_reminder", {
420
421
  turn: ctx.turnNumber,
421
422
  turnsSinceVerification: ctx.turnNumber - getToolTracking().lastVerificationTurn,
@@ -480,35 +481,32 @@ export function createDefaultPolicies(getToolTracking, onSignal, sendWhisper, se
480
481
  // subset). Values are always present per the wiring (heartbeat-scheduler
481
482
  // index.ts), so these defaults never fire — preserved from the original
482
483
  // required-typed destructure.
483
- const { percent = 0, tokens = 0, contextWindow = 0 } = usage;
484
+ const { percent = 0 } = usage;
484
485
  if (percent < USAGE_FIRED_RESET_BELOW && _firedThresholds.size > 0) {
485
486
  _firedThresholds.clear();
486
487
  }
487
- // Threshold ladder: soft -> advisory -> warning -> critical
488
- // Each threshold fires ONCE until usage resets below USAGE_FIRED_RESET_BELOW.
489
- // Pipeline taught fully at critical level; lighter hints below that.
490
- // Tier→(threshold, priority) mapping shared from
491
- // lib/detection/context-tiers.ts (CONTEXT_USAGE_TIERS); this policy
492
- // keeps its own per-tier message copy (different copy from the
493
- // enforcement nudge text).
494
- const TIER_MESSAGES = {
495
- soft: `Context at ${USAGE_WHISPER_SOFT}%. Inspect and track: context_inspect(detail="quick"). Tag with context_navigate(action="tag") to mark progress.`,
496
- advisory: `Context at ${USAGE_WHISPER_ADVISORY}%. Light pruning: context_inspect(detail="prune") then context_compress(action="archive") or context_navigate(action="tag") + context_compress(action="archive").`,
497
- warning: `Context at ${USAGE_WHISPER_WARNING}%. Deep compaction: tag + archive now. Pipeline: context_navigate(action="tag") -> context_compress(action="archive") -> compact if needed.`,
498
- critical: `CRITICAL: Context at ${USAGE_WHISPER_CRITICAL}%. FORCE IMMEDIATE HYGIENE. Pipeline: context_navigate(action="tag") -> context_compress(action="archive") -> context_compress(action="slide"). Do not continue work until done.`,
499
- };
488
+ // Threshold ladder: soft -> advisory -> warning -> critical, each
489
+ // firing ONCE until usage resets below USAGE_FIRED_RESET_BELOW.
490
+ //
491
+ // A rung decides WHETHER a whisper fires; it is never what the
492
+ // whisper prints. A threshold is a configuration value, and a delivery
493
+ // that prints it puts a number where a reader expects a reading. The
494
+ // wording lives with the meter in lib/detection/context-tiers.ts (one
495
+ // owner for both the enforcement ladder and this one), and the number
496
+ // the reader acts on is the measurement sampled at delivery, carrying
497
+ // its own provenance word.
500
498
  const thresholds = CONTEXT_USAGE_TIERS.filter((t) => t.tier !== "compact")
501
499
  .slice()
502
- .reverse()
503
- .map((t) => ({ pct: t.threshold, priority: t.priority, msg: TIER_MESSAGES[t.tier] }));
504
- for (const { pct, msg } of thresholds) {
505
- if (percent >= pct && !_firedThresholds.has(pct)) {
506
- _firedThresholds.add(pct);
507
- sendWhisper(`${msg} (${tokens?.toLocaleString()} / ${contextWindow?.toLocaleString()} tokens, ${percent?.toFixed(1)}%)`);
508
- if (pct === USAGE_WHISPER_CRITICAL) {
509
- const finalizationMessage = `[heartbeat] Context critical at ${percent?.toFixed(1)}%. ` +
510
- `Tag your position with context_navigate(action="tag") now and archive with context_compress(action="archive").`;
511
- sendSteerMessage(finalizationMessage);
500
+ .reverse();
501
+ for (const { tier, threshold } of thresholds) {
502
+ if (percent >= threshold && !_firedThresholds.has(threshold)) {
503
+ _firedThresholds.add(threshold);
504
+ // The family marker lets the batcher re-render this instruction
505
+ // from the measurement taken at delivery, so the arm named here and
506
+ // the percent printed beside it are one snapshot.
507
+ sendWhisper(contextUsageTierMessage(tier), "context-tier");
508
+ if (threshold === USAGE_WHISPER_CRITICAL) {
509
+ sendSteerMessage(contextUsageTierMessage("critical"));
512
510
  log.warn(`Auto-finalize triggered at ${USAGE_WHISPER_CRITICAL}%`);
513
511
  }
514
512
  break;
@@ -1,52 +1,83 @@
1
1
  /**
2
- * Whisper batcher for heartbeat ticks.
2
+ * Whisper batcher: the ONE place the shape of a heartbeat delivery is built.
3
3
  *
4
- * During a heartbeat tick, multiple cognitive modules may want to
5
- * whisper to the agent. If we just forward them through ctx.whisper,
6
- * the agent gets N separate messages -- which is both noisy and
7
- * expensive (each message becomes a turn boundary in the agent's
8
- * context).
4
+ * Two buffers feed it. The tick batcher collects module whispers and flushes
5
+ * them once per tick; the delayed buffer collects policy whispers and flushes
6
+ * them on the next before_agent_start. Both deliver the same shape: one
7
+ * clock line, one self-state line, numbered bodies. The shape has one
8
+ * owner here instead of a copy per flush site.
9
9
  *
10
- * The batcher intercepts the whisper call during the tick, buffers
11
- * messages grouped by priority, and flushes them as aggregated
12
- * messages per priority tier. High-priority messages flush first.
10
+ * Two rules make the delivered text trustworthy, and each is enforced by the
11
+ * way this module is written rather than by the emitter remembering it:
12
+ *
13
+ * 1. One snapshot per delivery. The clock comes from the seam, and a
14
+ * family that renders a measurement is re-rendered from the sample
15
+ * taken at delivery, so a label cannot outlive the number beside it.
16
+ * 2. Last arrival wins in a collapse. Keeping the first arrival per
17
+ * family is what printed the oldest label beside the newest numbers:
18
+ * the newest instruction is the only one whose advice can still apply.
13
19
  */
14
20
  import type { SelfStateSample } from "../../../lib/telemetry/context-heartbeat.js";
21
+ /**
22
+ * Families whose body is a rendering of a live measurement. The emitter
23
+ * declares the family so the batcher can re-render it from the delivery
24
+ * sample; a family sniffed from the prose silently stops collapsing the day
25
+ * the prose changes.
26
+ */
27
+ export type WhisperFamily = "context-tier";
15
28
  export interface WhisperBufferEntry {
16
29
  message: string;
17
30
  priority: string;
31
+ /** Set by the emitter for a family the batcher must own at delivery. */
32
+ family?: WhisperFamily;
18
33
  }
19
34
  export type WhisperSendFn = (msg: string, opts?: {
20
35
  category?: string;
21
36
  priority?: string;
22
37
  }) => void;
23
38
  /**
24
- * Self-state line (2 directive): every heartbeat
25
- * summary makes the agent self-aware of its own context health. ONE line,
26
- * <= 40 tokens, appended to every heartbeat summary:
39
+ * Self-state line: ONE line, appended to every heartbeat delivery.
27
40
  *
28
- * self-state: ctx 213K tok · cache 96% · dup 39 · tps-ema 87
41
+ * self-state: ctx 413K tok (41.3% measured)
29
42
  *
30
- * An unavailable metric renders "n/a" — never zero (a zero looks like a
31
- * healthy reading; "n/a" honestly says the telemetry is missing).
43
+ * The count and the percent are one meter reading from one snapshot, and the
44
+ * provenance word is the meter's own (context-usage describeUsage), so the two
45
+ * cannot disagree and a reader can tell a large context from a badly counted
46
+ * one. A percent whose provenance is missing is not rendered at all: an
47
+ * unlabelled percentage is the class that cost a session its window.
48
+ *
49
+ * Metrics this line no longer carries (cache-hit share, near-duplicate count,
50
+ * tok/s trend, hygiene acts) name no action at the moment they are read. They
51
+ * stay in the telemetry JSONL and in the tools an agent calls while
52
+ * diagnosing, where a reader has already decided to look. An unavailable
53
+ * metric renders "n/a", never zero: a zero looks like a healthy reading.
32
54
  */
33
55
  export declare function buildSelfStateLine(sample: Partial<SelfStateSample> | null | undefined): string;
56
+ export interface DeliveryRenderOptions {
57
+ /** Self-state line, rendered from the same sample as the rest of the delivery. */
58
+ selfState?: string;
59
+ /** Clock instant for the `now:` line; the clock seam applies when omitted. */
60
+ at?: Date;
61
+ }
34
62
  /**
35
- * Flush batched whispers: group by priority tier, concatenate per tier,
36
- * and send as aggregated messages. This prevents N separate injected
37
- * messages per heartbeat tick when multiple modules activate.
38
- *
39
- * Fresh clock: every batched summary
40
- * (and its single-message form) prepends a `now:` line rendered by the
41
- * ONE local-time formatter (lib/utils/local-time.ts) so the agent never
42
- * reasons on a stale clock mid-session.
43
- *
44
- * Self-state (Refine-2): when `selfState` is provided (the caller
45
- * samples context tokens / cache-hit share / near-duplicates / tok/s trend
46
- * via lib/telemetry/context-heartbeat.ts getSelfStateSample), the summary
47
- * gains ONE self-state line right after the `now:` line — every heartbeat
48
- * summary makes the agent aware of its own context health. Absent sample =
49
- * no line (callers opt in).
63
+ * Render one batched delivery. The clock is read through the seam the envelope
64
+ * formatter uses, never from a fresh `Date` at flush time: a delivery that was
65
+ * delayed must not claim an instant it never observed.
66
+ */
67
+ export declare function renderHeartbeatDelivery(bodies: readonly string[], opts?: DeliveryRenderOptions): string;
68
+ /**
69
+ * Flush the tick buffer: group by priority tier, render one delivery per tier.
70
+ * Self-state (when a sample was taken) lands right after the clock line, so
71
+ * every heartbeat summary is also a self-state checkpoint.
72
+ */
73
+ export declare function flushWhisperBuffer(buffer: WhisperBufferEntry[], send: WhisperSendFn | undefined, selfState?: string, at?: Date): void;
74
+ export interface DelayedRenderOptions extends DeliveryRenderOptions {
75
+ /** Context percent measured at delivery, or null when nothing was measured. */
76
+ contextPercent?: number | null;
77
+ }
78
+ /**
79
+ * Collapse the delayed buffer and render its deliveries: last arrival wins per
80
+ * key, then one delivery per priority tier.
50
81
  */
51
- export declare function flushWhisperBuffer(buffer: WhisperBufferEntry[], send: WhisperSendFn | undefined, selfState?: string): void;
82
+ export declare function renderDelayedDelivery(batch: readonly WhisperBufferEntry[], opts?: DelayedRenderOptions): string[];
52
83
  //# sourceMappingURL=whisper-batcher.d.ts.map
@@ -1,83 +1,158 @@
1
1
  /**
2
- * Whisper batcher for heartbeat ticks.
2
+ * Whisper batcher: the ONE place the shape of a heartbeat delivery is built.
3
3
  *
4
- * During a heartbeat tick, multiple cognitive modules may want to
5
- * whisper to the agent. If we just forward them through ctx.whisper,
6
- * the agent gets N separate messages -- which is both noisy and
7
- * expensive (each message becomes a turn boundary in the agent's
8
- * context).
4
+ * Two buffers feed it. The tick batcher collects module whispers and flushes
5
+ * them once per tick; the delayed buffer collects policy whispers and flushes
6
+ * them on the next before_agent_start. Both deliver the same shape: one
7
+ * clock line, one self-state line, numbered bodies. The shape has one
8
+ * owner here instead of a copy per flush site.
9
9
  *
10
- * The batcher intercepts the whisper call during the tick, buffers
11
- * messages grouped by priority, and flushes them as aggregated
12
- * messages per priority tier. High-priority messages flush first.
10
+ * Two rules make the delivered text trustworthy, and each is enforced by the
11
+ * way this module is written rather than by the emitter remembering it:
12
+ *
13
+ * 1. One snapshot per delivery. The clock comes from the seam, and a
14
+ * family that renders a measurement is re-rendered from the sample
15
+ * taken at delivery, so a label cannot outlive the number beside it.
16
+ * 2. Last arrival wins in a collapse. Keeping the first arrival per
17
+ * family is what printed the oldest label beside the newest numbers:
18
+ * the newest instruction is the only one whose advice can still apply.
13
19
  */
14
- import { formatLocalTime } from "../../../lib/utils/local-time.js";
20
+ import { formatLocalTime, nowOrOverride } from "../../../lib/utils/local-time.js";
15
21
  import { formatTokensK } from "../../../lib/detection/context-usage.js";
22
+ import { contextUsageTier, contextUsageTierMessage } from "../../../lib/detection/context-tiers.js";
16
23
  /** Render a token count compactly: 0 -> "0K", 1234 -> "1K", 237785 -> "238K". */
17
24
  function renderTokensK(tokens) {
18
25
  return formatTokensK(tokens);
19
26
  }
20
27
  /**
21
- * Self-state line (2 directive): every heartbeat
22
- * summary makes the agent self-aware of its own context health. ONE line,
23
- * <= 40 tokens, appended to every heartbeat summary:
28
+ * Self-state line: ONE line, appended to every heartbeat delivery.
29
+ *
30
+ * self-state: ctx 413K tok (41.3% measured)
24
31
  *
25
- * self-state: ctx 213K tok · cache 96% · dup 39 · tps-ema 87
32
+ * The count and the percent are one meter reading from one snapshot, and the
33
+ * provenance word is the meter's own (context-usage describeUsage), so the two
34
+ * cannot disagree and a reader can tell a large context from a badly counted
35
+ * one. A percent whose provenance is missing is not rendered at all: an
36
+ * unlabelled percentage is the class that cost a session its window.
26
37
  *
27
- * An unavailable metric renders "n/a" — never zero (a zero looks like a
28
- * healthy reading; "n/a" honestly says the telemetry is missing).
38
+ * Metrics this line no longer carries (cache-hit share, near-duplicate count,
39
+ * tok/s trend, hygiene acts) name no action at the moment they are read. They
40
+ * stay in the telemetry JSONL and in the tools an agent calls while
41
+ * diagnosing, where a reader has already decided to look. An unavailable
42
+ * metric renders "n/a", never zero: a zero looks like a healthy reading.
29
43
  */
30
44
  export function buildSelfStateLine(sample) {
31
45
  const s = sample ?? {};
32
46
  const ctxTok = typeof s.contextTokens === "number" ? `${renderTokensK(s.contextTokens)} tok` : "n/a";
33
- const cache = typeof s.cacheHitShare === "number" ? `${Math.round(s.cacheHitShare)}%` : "n/a";
34
- const dup = typeof s.nearDupCount === "number" ? String(s.nearDupCount) : "n/a";
35
- const tps = typeof s.tpsEma === "number" ? `${Math.round(s.tpsEma)} tok/s` : "n/a";
36
- const acts = typeof s.hygieneActs === "number" ? String(s.hygieneActs) : null;
37
- const actPart = acts ? ` · acts ${acts}` : "";
38
- return `self-state: ctx ${ctxTok} · cache ${cache} · dup ${dup} · tps-ema ${tps}${actPart}`;
47
+ const percent = typeof s.contextPercent === "number" &&
48
+ typeof s.contextProvenance === "string" &&
49
+ s.contextProvenance.length > 0
50
+ ? ` (${s.contextPercent.toFixed(1)}% ${s.contextProvenance})`
51
+ : "";
52
+ return `self-state: ctx ${ctxTok}${percent}`;
39
53
  }
40
54
  /**
41
- * Flush batched whispers: group by priority tier, concatenate per tier,
42
- * and send as aggregated messages. This prevents N separate injected
43
- * messages per heartbeat tick when multiple modules activate.
44
- *
45
- * Fresh clock: every batched summary
46
- * (and its single-message form) prepends a `now:` line rendered by the
47
- * ONE local-time formatter (lib/utils/local-time.ts) so the agent never
48
- * reasons on a stale clock mid-session.
49
- *
50
- * Self-state (Refine-2): when `selfState` is provided (the caller
51
- * samples context tokens / cache-hit share / near-duplicates / tok/s trend
52
- * via lib/telemetry/context-heartbeat.ts getSelfStateSample), the summary
53
- * gains ONE self-state line right after the `now:` line — every heartbeat
54
- * summary makes the agent aware of its own context health. Absent sample =
55
- * no line (callers opt in).
55
+ * Render one batched delivery. The clock is read through the seam the envelope
56
+ * formatter uses, never from a fresh `Date` at flush time: a delivery that was
57
+ * delayed must not claim an instant it never observed.
58
+ */
59
+ export function renderHeartbeatDelivery(bodies, opts = {}) {
60
+ const nowLine = `now: ${formatLocalTime(opts.at ?? nowOrOverride(), true)}`;
61
+ const selfStateSuffix = opts.selfState ? `\n${opts.selfState}` : "";
62
+ const head = `${nowLine}${selfStateSuffix}`;
63
+ if (bodies.length === 1)
64
+ return `${head}\n${bodies[0]}`;
65
+ return `[Heartbeat Summary]\n${head}\n${bodies.map((m, i) => `${i + 1}. ${m}`).join("\n")}`;
66
+ }
67
+ /**
68
+ * Flush the tick buffer: group by priority tier, render one delivery per tier.
69
+ * Self-state (when a sample was taken) lands right after the clock line, so
70
+ * every heartbeat summary is also a self-state checkpoint.
56
71
  */
57
- export function flushWhisperBuffer(buffer, send, selfState) {
72
+ export function flushWhisperBuffer(buffer, send, selfState, at) {
58
73
  if (buffer.length === 0 || !send)
59
74
  return;
60
75
  const groups = new Map();
61
76
  for (const entry of buffer) {
62
- const p = entry.priority;
63
- if (!groups.has(p))
64
- groups.set(p, []);
65
- groups.get(p).push(entry.message);
77
+ const group = groups.get(entry.priority) ?? [];
78
+ group.push(entry.message);
79
+ groups.set(entry.priority, group);
66
80
  }
67
- // Flush one message per priority tier
68
81
  for (const [priority, messages] of groups) {
69
- const nowLine = `now: ${formatLocalTime(new Date(), true)}`;
70
- const selfStateSuffix = selfState ? `\n${selfState}` : "";
71
- if (messages.length === 1) {
72
- send(`${nowLine}${selfStateSuffix}\n${messages[0]}`, {
73
- category: "cognitive",
74
- priority: priority,
75
- });
76
- }
77
- else {
78
- const combined = `[Heartbeat Summary]\n${nowLine}${selfStateSuffix}\n${messages.map((m, i) => `${i + 1}. ${m}`).join("\n")}`;
79
- send(combined, { category: "cognitive", priority: priority });
80
- }
82
+ send(renderHeartbeatDelivery(messages, { selfState, at }), {
83
+ category: "cognitive",
84
+ priority,
85
+ });
86
+ }
87
+ }
88
+ /**
89
+ * Collapse key for the delayed buffer. A declared family is its own key (the
90
+ * emitter knows what it measured). The prose rules below cover emitters that
91
+ * still describe themselves by their first line: each one is a coupling, so a
92
+ * copy change there must come with a look at this list.
93
+ */
94
+ function dedupKey(entry) {
95
+ if (entry.family)
96
+ return `family:${entry.family}`;
97
+ const message = entry.message;
98
+ // Duplicate count messages: "39 near-duplicate messages..."
99
+ if (/^\d+ near-duplicate messages/.test(message))
100
+ return "duplicate-count";
101
+ // Context density messages
102
+ if (/^Low context density/.test(message))
103
+ return "density-low";
104
+ if (/^High density/.test(message))
105
+ return "density-high";
106
+ if (/^Context density still low/.test(message))
107
+ return "density-low-persistent";
108
+ // Proactive projection messages
109
+ if (/^\[proactive\]/.test(message))
110
+ return "proactive-projection";
111
+ // Degradation messages
112
+ if (/^Degradation detected/.test(message))
113
+ return "degradation";
114
+ // Fallback: use first 80 chars
115
+ return message.slice(0, 80);
116
+ }
117
+ /**
118
+ * The body to deliver for one entry.
119
+ *
120
+ * A declared family is re-rendered from the delivery sample, so the
121
+ * instruction and the number beside it describe one measurement. When the
122
+ * measured state no longer reaches the family's first arm, the entry is
123
+ * silence: advice about a condition that has passed is worse than none.
124
+ * With no measurement in hand the emitter's own wording stands: it carries no
125
+ * number, so it cannot contradict one.
126
+ */
127
+ function deliveryBody(entry, contextPercent) {
128
+ if (entry.family !== "context-tier")
129
+ return entry.message;
130
+ if (contextPercent === null)
131
+ return entry.message;
132
+ const tier = contextUsageTier(contextPercent);
133
+ return tier ? contextUsageTierMessage(tier.tier) : null;
134
+ }
135
+ /**
136
+ * Collapse the delayed buffer and render its deliveries: last arrival wins per
137
+ * key, then one delivery per priority tier.
138
+ */
139
+ export function renderDelayedDelivery(batch, opts = {}) {
140
+ const collapsed = new Map();
141
+ for (const entry of batch) {
142
+ // Last arrival wins: the newest instruction is the only one whose advice
143
+ // can still be right, and the keystroke of keying on the first arrival is
144
+ // what printed the oldest label beside the newest numbers.
145
+ collapsed.set(dedupKey(entry), entry);
146
+ }
147
+ const groups = new Map();
148
+ for (const entry of collapsed.values()) {
149
+ const body = deliveryBody(entry, opts.contextPercent ?? null);
150
+ if (body === null)
151
+ continue;
152
+ const group = groups.get(entry.priority) ?? [];
153
+ group.push(body);
154
+ groups.set(entry.priority, group);
81
155
  }
156
+ return [...groups.values()].map((bodies) => renderHeartbeatDelivery(bodies, opts));
82
157
  }
83
158
  //# sourceMappingURL=whisper-batcher.js.map