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
@@ -19,10 +19,9 @@ import { analyzeSession } from "../../analysis.js";
19
19
  import * as timerMod from "../../../../scheduling/timer/index.js";
20
20
  import { getState } from "../../../../enforcement/state.js";
21
21
  import { CONTEXT_COMPACT_REFUSE_PERCENT } from "../../../../../lib/detection/context-thresholds.js";
22
- import { turnBoundaryMayAbortRun, } from "../../../../../lib/events/turn-boundary.js";
23
22
  import { getCmState, isCompactionActive, log, recordNavigationAction } from "../shared.js";
24
23
  import { snapBoundaryOutsideToolBatch } from "../tool-batch-boundary.js";
25
- import { formatTokensK } from "../../../../../lib/detection/context-usage.js";
24
+ import { formatTokensK, tokenArms } from "../../../../../lib/detection/context-usage.js";
26
25
  import { formatLocalTime } from "../../../../../lib/utils/local-time.js";
27
26
  import { getAutoCompactConfig, } from "../../../../../lib/config/braid-settings.js";
28
27
  // Helpers
@@ -109,8 +108,8 @@ function getBatchSettleState(ctx) {
109
108
  /**
110
109
  * Release the call ids a turn's persisted tool results account for. A result
111
110
  * with no usable id is ignored: an unmatched active id stays protective, so a
112
- * malformed event can only delay a drain to a later boundary or the settle
113
- * backstop, never release a sibling that is still executing.
111
+ * malformed event can only delay a drain to the settle backstop, never
112
+ * release a sibling that is still executing.
114
113
  */
115
114
  function releaseSettledToolCallIds(st, toolResults) {
116
115
  if (!Array.isArray(toolResults))
@@ -150,8 +149,8 @@ export function hasPendingLlmCompaction(ctx) {
150
149
  }
151
150
  /**
152
151
  * One pending-state line for the armed-but-unfired compaction queue
153
- * ("slide armed 17:28 — fires at the next turn boundary; live usage drops
154
- * when it lands"). Null when nothing is pending: no surface may fabricate an
152
+ * ("slide armed 17:28 — fires when the run settles; live usage drops when it
153
+ * lands"). Null when nothing is pending: no surface may fabricate an
155
154
  * expectation of a drop that is not armed. Shared by context_inspect and the
156
155
  * heartbeat advisory so both state the same fact the same way.
157
156
  */
@@ -162,7 +161,7 @@ export function formatPendingCompactionsLine(ctx) {
162
161
  const newest = pending.reduce((a, b) => (b.armedAt > a.armedAt ? b : a));
163
162
  const kinds = [...new Set(pending.map((p) => p.kind))].join("+");
164
163
  const armedClock = formatLocalTime(new Date(newest.armedAt));
165
- return (`${kinds} armed ${armedClock} — fires at the next turn boundary (turn end or run settle); ` +
164
+ return (`${kinds} armed ${armedClock} — fires when the run settles (or at the 0.90W backstop); ` +
166
165
  `until then live usage reads pre-compaction state`);
167
166
  }
168
167
  /**
@@ -260,20 +259,7 @@ export function scheduleDegradedCompact(trigger) {
260
259
  setTimeout(trigger, DEGRADED_DEFERRAL_MS);
261
260
  }
262
261
  /**
263
- * Whether an arm may fire its own entry. Firing a compact aborts whatever run
264
- * is live, so an arm that happens inside a turn boundary dispatch hands that
265
- * boundary in and is judged by the same rule the TURN_END handler applies
266
- * (the rule lives in lib/events/turn-boundary.ts; it owns the "no boundary
267
- * known" case, which fires). Every other arm site runs inside a tool call,
268
- * where there is no boundary to read and the prior contract stands: the arm
269
- * drains unless a batch is still active (the arm's own call id keeps it
270
- * parked, so it does not fire there).
271
- */
272
- function armMayDrainNow(boundary, ctx) {
273
- return turnBoundaryMayAbortRun(boundary, () => captureUsage(ctx));
274
- }
275
- /**
276
- * Arm a one-shot compaction at a safe boundary (next turn end or run settle).
262
+ * Arm a one-shot compaction for the settle drain (or the 0.90W backstop).
277
263
  * Returns "pending-exists" when an LLM-class compaction is already armed: the
278
264
  * caller must NOT have written its own range/anchor state in that case (the
279
265
  * drain fires the first-armed trigger with the FIRST declaration's state).
@@ -285,7 +271,7 @@ function armMayDrainNow(boundary, ctx) {
285
271
  */
286
272
  function scheduleCompactionAtBatchSettle(pi, ctx, options, meta = {
287
273
  kind: "compact",
288
- }, boundary) {
274
+ }) {
289
275
  const trigger = () => {
290
276
  try {
291
277
  // Signal to session_compact handler that this is agent-initiated
@@ -306,7 +292,7 @@ function scheduleCompactionAtBatchSettle(pi, ctx, options, meta = {
306
292
  // coalesces them to the earliest cut.
307
293
  if (isLlmClass(meta.kind) && st.pending.some((p) => isLlmClass(p.kind))) {
308
294
  log.info(`[context-compress] ${meta.kind} arm refused: an LLM-class compaction is ` +
309
- `already armed and will fire at the next boundary.`);
295
+ `already armed and will fire when the run settles.`);
310
296
  return "pending-exists";
311
297
  }
312
298
  st.pending.push({ trigger, armedAt: Date.now(), ...meta });
@@ -315,14 +301,11 @@ function scheduleCompactionAtBatchSettle(pi, ctx, options, meta = {
315
301
  log.warn(`[context-compress] Pending queue overflow: dropped the newest armed ${dropped?.kind}` +
316
302
  ` (cap ${PENDING_COMPACT_QUEUE_MAX}); the first-armed entry still fires.`);
317
303
  }
318
- // Arming fires only where that is safe. Firing a compaction aborts whatever
319
- // run is live, and an arm site is not in a position to tell: the tool path
320
- // arms inside its own call (whose id parks the queue anyway), and the
321
- // heartbeat's arm runs inside a turn_end dispatch, where whether the loop
322
- // still has work to dispatch is a fact the event carries. That caller hands
323
- // its boundary in; every other caller keeps the prior contract.
324
- if (armMayDrainNow(boundary, ctx))
325
- firePendingCompactionsIfSettled(ctx, st);
304
+ // Arming never fires. Every arm site runs while the run is live - inside
305
+ // the tool call that asked for it, or inside the heartbeat's turn_end
306
+ // dispatch - and no arm site can see the steering queue that decides
307
+ // whether another request follows. The entry waits for the settle drain or
308
+ // the 0.90W backstop.
326
309
  return "queued";
327
310
  }
328
311
  catch {
@@ -344,10 +327,10 @@ function scheduleCompactionAtBatchSettle(pi, ctx, options, meta = {
344
327
  * and the usage-driven auto-arm, so both produce the same cut shape: the
345
328
  * boundary is snapped out of any tool batch, the slide state is persisted for
346
329
  * the SLIDE_MODE compaction branch, an audit entry is appended, and the
347
- * trigger is queued for the next safe boundary. Returns null when the branch
348
- * is not longer than the keep window (nothing to slide).
330
+ * trigger is queued for the settle drain. Returns null when the branch is not
331
+ * longer than the keep window (nothing to slide).
349
332
  */
350
- function armSlideCompaction(pi, ctx, keepCount, boundary) {
333
+ function armSlideCompaction(pi, ctx, keepCount) {
351
334
  const sm = ctx.sessionManager;
352
335
  if (!sm || typeof sm.getBranch !== "function")
353
336
  return null;
@@ -395,7 +378,7 @@ function armSlideCompaction(pi, ctx, keepCount, boundary) {
395
378
  catch {
396
379
  // Non-fatal
397
380
  }
398
- scheduleCompactionAtBatchSettle(pi, ctx, { customInstructions: "SLIDE_MODE:true" }, { kind: "slide", cutEntryId }, boundary);
381
+ scheduleCompactionAtBatchSettle(pi, ctx, { customInstructions: "SLIDE_MODE:true" }, { kind: "slide", cutEntryId });
399
382
  return { cutEntryId, keptCount, droppedCount };
400
383
  }
401
384
  /**
@@ -416,20 +399,17 @@ function getAutoArmState(ctx) {
416
399
  * Usage-driven auto-arm: when live usage sits above the configured threshold
417
400
  * for `confirmTicks` consecutive observations, arm ONE deterministic slide so
418
401
  * a session that never gets a manual cleanup still gets relief. Reuses the
419
- * accounting context_inspect computes (analyzeSession), the same pending
420
- * queue the tool arms drain through, and the same boundary discipline: arming
421
- * only queues; the compaction itself still fires at the next turn boundary or
422
- * settle, never mid-run.
402
+ * accounting context_inspect computes (analyzeSession) and the same pending
403
+ * queue the tool arms drain through: arming only queues; the compaction itself
404
+ * fires when the run settles (or at the 0.90W backstop), never mid-run.
423
405
  *
424
406
  * Called from the heartbeat tick — the only cadence that runs while a session
425
- * works, and the only arm site that runs inside a turn boundary dispatch. It
426
- * hands that boundary in, so the arm is judged by the same rule the drain
427
- * applies: a "toolUse" boundary below the 0.90W backstop leaves the entry
428
- * queued for the next loop-done boundary instead of aborting the request the
429
- * loop is about to dispatch. Returns what happened and why, so the caller can
430
- * log it.
407
+ * works. Arming only queues: the entry waits for `agent_settled`, because the
408
+ * tick runs while the run is live and nothing at that point can prove the loop
409
+ * has no request left to dispatch. Returns what happened and why, so the
410
+ * caller can log it.
431
411
  */
432
- export function maybeArmAutoCompaction(pi, ctx, boundary) {
412
+ export function maybeArmAutoCompaction(pi, ctx) {
433
413
  const config = getAutoCompactConfig();
434
414
  if (!config.enabled)
435
415
  return { armed: false, reason: "disabled" };
@@ -452,13 +432,13 @@ export function maybeArmAutoCompaction(pi, ctx, boundary) {
452
432
  }
453
433
  const branchLength = ctx?.sessionManager?.getBranch?.().length ?? 0;
454
434
  const keep = resolveAutoSlideKeep(branchLength);
455
- const armed = armSlideCompaction(pi, ctx, keep, boundary);
435
+ const armed = armSlideCompaction(pi, ctx, keep);
456
436
  st.aboveCount = 0;
457
437
  if (!armed)
458
438
  return { armed: false, reason: "branch-too-short" };
459
439
  log.info(`[context-compress] Auto-arm: usage sustained at ${usage.percent.toFixed(1)}% ` +
460
440
  `(>= ${config.armPercent}% for ${config.confirmTicks} observations) — slide armed ` +
461
- `(${armed.droppedCount} entries before the cut), fires at the next boundary.`);
441
+ `(${armed.droppedCount} entries before the cut), fires when the run settles.`);
462
442
  return { armed: true, reason: `usage ${usage.percent.toFixed(1)}% sustained` };
463
443
  }
464
444
  // Schema
@@ -513,9 +493,9 @@ export const contextCompressSchema = Type.Object({
513
493
  });
514
494
  export function registerContextCompress(pi) {
515
495
  // Batch-settle scheduling: track the ACTIVE tool calls of every running
516
- // batch by call id and fire the deferred compaction only at a safe boundary
517
- // (a loop-done turn_end or agent_settled). Never mid-batch (would drop a
518
- // parallel sibling's result) and never at tool_execution_end (the run is
496
+ // batch by call id and fire the deferred compaction when the run settles
497
+ // (plus the 0.90W backstop at a turn boundary). Never mid-batch (would drop
498
+ // a parallel sibling's result) and never at tool_execution_end (the run is
519
499
  // still live there — an aborting compact would surface a spurious "This
520
500
  // operation was aborted" error and tear the finishing turn).
521
501
  onEvent(pi, TOOL_EXECUTION_START, (event, ctx) => {
@@ -524,7 +504,7 @@ export function registerContextCompress(pi) {
524
504
  st.activeToolCallIds.add(toolCallIdOf(event) ?? UNIDENTIFIED_TOOL_CALL);
525
505
  }
526
506
  catch {
527
- // Settle tracking is unavailable — the pending compact then only fires
507
+ // Settle tracking is unavailable — the pending compact then fires only
528
508
  // via AGENT_SETTLED below, which is the conservative path.
529
509
  }
530
510
  });
@@ -538,8 +518,8 @@ export function registerContextCompress(pi) {
538
518
  // NOTE: do NOT fire here. The run is still active (the agent is
539
519
  // processing this tool's result and streaming its next response); an
540
520
  // aborting compact now would surface a spurious "This operation was
541
- // aborted" error and tear the finishing turn. Safe boundaries are
542
- // turn_end (below) and agent_settled.
521
+ // aborted" error and tear the finishing turn. The settle drain owns the
522
+ // fire.
543
523
  }
544
524
  catch {
545
525
  // Settle tracking unavailable — see TOOL_EXECUTION_START above; the
@@ -547,24 +527,19 @@ export function registerContextCompress(pi) {
547
527
  }
548
528
  });
549
529
  onEvent(pi, TURN_END, (event, ctx) => {
550
- // Turn boundary. The turn's assistant message and tool results are already
551
- // persisted here, but that alone does not make the run safe to abort: a
552
- // "toolUse" stop means the loop dispatches its next request the moment the
553
- // handlers return, so the deferred ctx.compact() tears that request
554
- // mid-stream and the compaction replaces the work it was about to do (the
555
- // rule is lib/events/turn-boundary.ts, and its residual section lists the
556
- // two cases a loop-done stop reason does not rule out). Only a loop-done
557
- // boundary drains, except at the 0.90W hard backstop, which exists
558
- // precisely to stop a runaway live loop before it overflows.
530
+ // The 0.90W hard backstop, the ONLY drain that fires while the run may
531
+ // still dispatch. Below it the queue waits for `agent_settled`: the loop
532
+ // polls its steering queue after this dispatch and a single queued steer
533
+ // starts another request, which the deferred ctx.compact() would abort.
534
+ // Above it the overflow is the worse failure: a run kept alive by
535
+ // continuous steers never settles, and without this cut the queue stays
536
+ // armed until the context is gone.
559
537
  //
560
538
  // The persisted results carry the toolCallIds of the calls they answer,
561
539
  // which releases a call whose tool_execution_end never arrived; an active
562
540
  // id with NO result in this event is kept (it may still be executing, and
563
- // a count could not tell which sibling completed). A run kept alive by
564
- // continuous steers never reaches agent_settled — this boundary keeps an
565
- // armed compaction from stalling behind live work. Ids are never blanket-
566
- // reset here (only agent_settled owns that backstop, which is what keeps a
567
- // missed end event from parking the queue forever).
541
+ // a count could not tell which sibling completed). The active set is never
542
+ // blanket-reset here; agent_settled owns that release.
568
543
  try {
569
544
  const st = getBatchSettleState(ctx);
570
545
  releaseSettledToolCallIds(st, event?.toolResults);
@@ -572,24 +547,23 @@ export function registerContextCompress(pi) {
572
547
  return;
573
548
  if (isCompactionActive(ctx))
574
549
  return;
575
- if (!turnBoundaryMayAbortRun(event, () => captureUsage(ctx)))
550
+ const usage = captureUsage(ctx);
551
+ if (!usage || usage.tokens < tokenArms(usage.contextWindow).backstop)
576
552
  return;
577
553
  firePendingCompactionsIfSettled(ctx, st);
578
554
  }
579
555
  catch {
580
- // A failed boundary drain must not tear the turn_end event pipeline;
581
- // the pending compactions retry on the next boundary.
556
+ // A failed backstop check must not tear the turn_end event pipeline;
557
+ // the queue stays armed for the settle drain.
582
558
  }
583
559
  });
584
560
  onEvent(pi, AGENT_SETTLED, (_event, ctx) => {
585
- // Backstop boundary: the run has fully settled, so ctx.compact()'s
586
- // abort() is a clean no-op — no spurious abort error, no torn turn, and
587
- // the post-compaction resume wake lands when the session is
588
- // idle/promptable. The whole pending queue drains here (coalesced); the
589
- // active set is cleared so parked compactions always fire even when a
590
- // start never saw its end and no turn boundary ever accounted for it.
591
- // Turn boundaries drain first when a run stays alive; this handler catches
592
- // everything they cannot reach.
561
+ // The one unconditional drain: `agent_settled` is emitted after the run
562
+ // is no longer active, so ctx.compact()'s abort() is a clean no-op — no
563
+ // torn request, and the post-compaction resume wake lands when the
564
+ // session is idle/promptable. The whole pending queue drains here
565
+ // (coalesced), and the active set is cleared first so a parked compaction
566
+ // always fires even when a start never saw its end.
593
567
  try {
594
568
  const st = getBatchSettleState(ctx);
595
569
  st.activeToolCallIds.clear();
@@ -659,7 +633,7 @@ export function registerContextCompress(pi) {
659
633
  ` Before: ${usageLine2}`,
660
634
  ` Keep recent: ${params?.keep ?? "auto"}`,
661
635
  ``,
662
- `Compaction armed; it fires at the next turn boundary (turn end or run settle) — live usage will NOT drop until it lands.`,
636
+ `Compaction armed; it fires when the run settles — live usage will NOT drop until it lands.`,
663
637
  `Agent will resume automatically after compaction completes.`,
664
638
  `Run context_inspect(detail='quick') after resume to verify.`,
665
639
  ].join("\n"),
@@ -733,7 +707,7 @@ export function registerContextCompress(pi) {
733
707
  };
734
708
  }
735
709
  // LLM-class dedup: refuse BEFORE any state write. An already-armed
736
- // compaction fires at the next boundary with the FIRST declaration's
710
+ // compaction fires when the run settles with the FIRST declaration's
737
711
  // range; a second arm here would overwrite rangeMode (clobber-class
738
712
  // loss) and queue an entry that can never fire.
739
713
  if (hasPendingLlmCompaction(ctx)) {
@@ -742,7 +716,7 @@ export function registerContextCompress(pi) {
742
716
  {
743
717
  type: "text",
744
718
  text: [
745
- `**Archive skipped — a compaction is already armed and will fire at the next turn boundary.**`,
719
+ `**Archive skipped — a compaction is already armed and will fire when the run settles.**`,
746
720
  `Nothing was recorded for "${topic}"; the pending compaction covers the cleanup.`,
747
721
  `After it lands, re-run this archive if the range still needs a record.`,
748
722
  ].join("\n"),
@@ -1013,8 +987,8 @@ export function registerContextCompress(pi) {
1013
987
  if (usageBefore) {
1014
988
  feedbackLines.push(` Before: ${usageBefore.percent.toFixed(1)}% used (${formatTokensK(usageBefore.tokens)} tokens)`);
1015
989
  }
1016
- feedbackLines.push("", "Compaction is armed and fires at the next turn boundary (turn end or run settle) — it may " +
1017
- "land while the run stays alive; live usage will NOT drop until it fires.", "Verify after it lands: context_inspect(detail='quick') shows the drop and any still-pending arm.");
990
+ feedbackLines.push("", "Compaction is armed and fires when the run settles — live usage " +
991
+ "will NOT drop until it fires.", "Verify after it lands: context_inspect(detail='quick') shows the drop and any still-pending arm.");
1018
992
  // Cancel any stale resume timer from a previous compaction cycle.
1019
993
  try {
1020
994
  const sessionId = ctx?.sessionManager?.getSessionId?.() ?? "anonymous";
@@ -1082,7 +1056,7 @@ export function registerContextCompress(pi) {
1082
1056
  };
1083
1057
  }
1084
1058
  // LLM-class dedup (same contract as archive): an armed compaction
1085
- // fires at the next boundary; refuse before writing the tag or the
1059
+ // fires when the run settles; refuse before writing the tag or the
1086
1060
  // archive anchor so the first declaration stands unmodified.
1087
1061
  if (hasPendingLlmCompaction(ctx)) {
1088
1062
  return {
@@ -1090,7 +1064,7 @@ export function registerContextCompress(pi) {
1090
1064
  {
1091
1065
  type: "text",
1092
1066
  text: [
1093
- `**Deep clean skipped — a compaction is already armed and will fire at the next turn boundary.**`,
1067
+ `**Deep clean skipped — a compaction is already armed and will fire when the run settles.**`,
1094
1068
  `Nothing was tagged for "${topic}"; the pending compaction covers the cleanup.`,
1095
1069
  ].join("\n"),
1096
1070
  },
@@ -1140,7 +1114,7 @@ export function registerContextCompress(pi) {
1140
1114
  ` 2. ~${count} entries before the tag point, estimated`,
1141
1115
  ` 3. Compaction scheduled${usageLine}`,
1142
1116
  "",
1143
- `Compaction armed; it fires at the next turn boundary (turn end or run settle) — live usage will NOT drop until it lands.`,
1117
+ `Compaction armed; it fires when the run settles — live usage will NOT drop until it lands.`,
1144
1118
  `Agent will resume automatically after compaction completes.`,
1145
1119
  `Run context_inspect(detail='quick') after resume to verify.`,
1146
1120
  "",
@@ -1266,7 +1240,7 @@ export function registerContextCompress(pi) {
1266
1240
  ` ~${droppedCount} entries before the slide point, estimated`,
1267
1241
  ` Before: ${usageLine}`,
1268
1242
  ``,
1269
- `Compaction armed; it fires at the next turn boundary (turn end or run settle) — live usage will NOT drop until it lands.`,
1243
+ `Compaction armed; it fires when the run settles — live usage will NOT drop until it lands.`,
1270
1244
  `Agent will resume automatically after compaction completes.`,
1271
1245
  `Run context_inspect(detail='quick') after resume to verify.`,
1272
1246
  ].join("\n"),
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Recognition of a missing-path tool failure, and the path it names.
3
+ *
4
+ * The shapes below are the ones the tools actually emit on this platform,
5
+ * measured rather than invented:
6
+ *
7
+ * read ENOENT: no such file or directory, access '/x/y.ts'
8
+ * edit Could not edit file: /x/y.ts. Error code: ENOENT.
9
+ * bash ls: /x/y: No such file or directory
10
+ * bash /bin/bash: line 0: cd: /x/y: No such file or directory
11
+ *
12
+ * Two of those carry a usable path in the call and the rest only in the text,
13
+ * so the call wins when it has one: a path the model asked for is the path the
14
+ * whisper should name, even when the tool's own wording echoes it loosely.
15
+ *
16
+ * Only a missing path is a path miss. A permission error, an unreadable file
17
+ * or a failed assertion is a different failure with a different next move, and
18
+ * steering toward `ls` there would cost a call without teaching anything.
19
+ */
20
+ export interface PathMiss {
21
+ /** The tool whose call missed. */
22
+ tool: string;
23
+ /** The path that was not there, as the tool or the call reported it. */
24
+ path: string;
25
+ }
26
+ /**
27
+ * The path a failed call missed, or null when this result is not a path miss.
28
+ */
29
+ export declare function detectPathMiss(toolName: string, input: unknown, text: string): PathMiss | null;
30
+ //# sourceMappingURL=detect.d.ts.map
@@ -0,0 +1,67 @@
1
+ /**
2
+ * Recognition of a missing-path tool failure, and the path it names.
3
+ *
4
+ * The shapes below are the ones the tools actually emit on this platform,
5
+ * measured rather than invented:
6
+ *
7
+ * read ENOENT: no such file or directory, access '/x/y.ts'
8
+ * edit Could not edit file: /x/y.ts. Error code: ENOENT.
9
+ * bash ls: /x/y: No such file or directory
10
+ * bash /bin/bash: line 0: cd: /x/y: No such file or directory
11
+ *
12
+ * Two of those carry a usable path in the call and the rest only in the text,
13
+ * so the call wins when it has one: a path the model asked for is the path the
14
+ * whisper should name, even when the tool's own wording echoes it loosely.
15
+ *
16
+ * Only a missing path is a path miss. A permission error, an unreadable file
17
+ * or a failed assertion is a different failure with a different next move, and
18
+ * steering toward `ls` there would cost a call without teaching anything.
19
+ */
20
+ /** Tools whose failure can mean "the path was a guess". */
21
+ const PATH_BEARING_TOOLS = new Set(["read", "edit", "write", "bash"]);
22
+ /** The two spellings of "this path is not there" the tools emit. */
23
+ const MISSING_PATH = /ENOENT|no such file or directory/i;
24
+ /** A path quoted by a Node error: `ENOENT: ..., access '/x/y'`. */
25
+ const QUOTED_AFTER_SYSCALL = /\b(?:access|open|stat|lstat|scandir|opendir|unlink|readlink)\s+'([^']+)'/;
26
+ /** A shell builtin naming the directory it could not enter. */
27
+ const BASH_CD_TARGET = /(?:^|[:\s])cd:\s+(.+?):\s*no such file/i;
28
+ /** A program naming the operand it could not find: `ls: /x/y: No such file`. */
29
+ const PROGRAM_OPERAND = /([^\s:]+):\s*no such file or directory/i;
30
+ /** A bare errno (`ENOENT`), not a path. */
31
+ const ERRNO_ONLY = /^[A-Z][A-Z0-9_]*$/;
32
+ /** The path the call itself asked for, when the tool takes one. */
33
+ function pathFromCall(input) {
34
+ if (!input || typeof input !== "object")
35
+ return undefined;
36
+ const path = input.path;
37
+ return typeof path === "string" && path.length > 0 ? path : undefined;
38
+ }
39
+ /** The path an error message names, when the call did not carry one. */
40
+ function pathFromText(text) {
41
+ const candidates = [
42
+ QUOTED_AFTER_SYSCALL.exec(text)?.[1],
43
+ BASH_CD_TARGET.exec(text)?.[1],
44
+ PROGRAM_OPERAND.exec(text)?.[1],
45
+ ];
46
+ for (const candidate of candidates) {
47
+ const path = candidate?.trim();
48
+ if (!path || ERRNO_ONLY.test(path))
49
+ continue;
50
+ return path;
51
+ }
52
+ return undefined;
53
+ }
54
+ /**
55
+ * The path a failed call missed, or null when this result is not a path miss.
56
+ */
57
+ export function detectPathMiss(toolName, input, text) {
58
+ if (!PATH_BEARING_TOOLS.has(toolName))
59
+ return null;
60
+ if (!text || !MISSING_PATH.test(text))
61
+ return null;
62
+ const path = pathFromCall(input) ?? pathFromText(text);
63
+ if (!path)
64
+ return null;
65
+ return { tool: toolName, path };
66
+ }
67
+ //# sourceMappingURL=detect.js.map
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Path-miss steer — the tool failure that says what would have worked.
3
+ *
4
+ * A turn that guesses paths spends calls discovering a layout a listing would
5
+ * have named. The failure itself is the one moment the cheaper move is
6
+ * obvious, so it is where the line belongs: one steer per turn, the path that
7
+ * missed, and the three instruments that answer it (`ls`, `find`,
8
+ * `explore_paths`).
9
+ *
10
+ * Delivery is the standard whisper funnel (`sendTrackedMessage`), so this
11
+ * emitter inherits the envelope, the flood cap and the live-steer resolution
12
+ * every other whisper uses. The event is pi's existing `tool_result`, the only
13
+ * seat that carries both the failure text and the arguments the call made —
14
+ * the call's own `path` is more reliable than parsing the error wording.
15
+ *
16
+ * Budget: one line per turn, at most one line per path per session. A path
17
+ * already steered is not steered again, because a repeat tells the agent
18
+ * nothing it was not told, and the second occurrence usually means the agent
19
+ * chose to proceed rather than that it failed to read.
20
+ */
21
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
22
+ /**
23
+ * One line: the path, and the cheaper moves next to it.
24
+ *
25
+ * The parent is named when the path has one, because `ls` needs an operand and
26
+ * a model that guessed a leaf usually had the parent wrong too — listing the
27
+ * parent is what tells it which of the two it got wrong.
28
+ */
29
+ export declare function pathMissLine(path: string): string;
30
+ /** Test hook: forget every steered path and the current turn's budget. */
31
+ export declare function _resetForTests(): void;
32
+ export default function pathMissExtension(pi: ExtensionAPI): void;
33
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,118 @@
1
+ /**
2
+ * Path-miss steer — the tool failure that says what would have worked.
3
+ *
4
+ * A turn that guesses paths spends calls discovering a layout a listing would
5
+ * have named. The failure itself is the one moment the cheaper move is
6
+ * obvious, so it is where the line belongs: one steer per turn, the path that
7
+ * missed, and the three instruments that answer it (`ls`, `find`,
8
+ * `explore_paths`).
9
+ *
10
+ * Delivery is the standard whisper funnel (`sendTrackedMessage`), so this
11
+ * emitter inherits the envelope, the flood cap and the live-steer resolution
12
+ * every other whisper uses. The event is pi's existing `tool_result`, the only
13
+ * seat that carries both the failure text and the arguments the call made —
14
+ * the call's own `path` is more reliable than parsing the error wording.
15
+ *
16
+ * Budget: one line per turn, at most one line per path per session. A path
17
+ * already steered is not steered again, because a repeat tells the agent
18
+ * nothing it was not told, and the second occurrence usually means the agent
19
+ * chose to proceed rather than that it failed to read.
20
+ */
21
+ import { dirname } from "node:path";
22
+ import { createLogger } from "../../../lib/core/logger.js";
23
+ import { INPUT, TOOL_RESULT } from "../../../lib/core/event-names.js";
24
+ import { sendTrackedMessage } from "../../../lib/utils/injection-tracker.js";
25
+ import { detectPathMiss } from "./detect.js";
26
+ const log = createLogger("path-miss");
27
+ /**
28
+ * Sessions whose steered paths are remembered. A session id is stable for the
29
+ * life of a session and a long-lived process can host more than one, so the
30
+ * map is bounded rather than trusted to stay small.
31
+ */
32
+ const MAX_TRACKED_SESSIONS = 16;
33
+ /** Paths already steered, per session. */
34
+ const steeredPaths = new Map();
35
+ /** Turn-scoped: the first path miss of a turn is the one worth a line. */
36
+ let steeredThisTurn = false;
37
+ function sessionKey(ctx) {
38
+ const manager = ctx?.sessionManager;
39
+ return manager?.getSessionId?.() ?? manager?.getSessionFile?.() ?? "unknown";
40
+ }
41
+ function remember(session, path) {
42
+ const paths = steeredPaths.get(session) ?? new Set();
43
+ paths.add(path);
44
+ steeredPaths.set(session, paths);
45
+ if (steeredPaths.size > MAX_TRACKED_SESSIONS) {
46
+ // Insertion order: the oldest session is the first key.
47
+ const oldest = steeredPaths.keys().next().value;
48
+ if (oldest !== undefined && oldest !== session)
49
+ steeredPaths.delete(oldest);
50
+ }
51
+ }
52
+ function alreadySteered(session, path) {
53
+ return steeredPaths.get(session)?.has(path) ?? false;
54
+ }
55
+ /** The error text of a tool result, with any non-text parts ignored. */
56
+ function resultText(content) {
57
+ if (typeof content === "string")
58
+ return content;
59
+ if (!Array.isArray(content))
60
+ return "";
61
+ return content
62
+ .map((part) => part && typeof part === "object" && typeof part.text === "string"
63
+ ? part.text
64
+ : "")
65
+ .join("\n");
66
+ }
67
+ /**
68
+ * One line: the path, and the cheaper moves next to it.
69
+ *
70
+ * The parent is named when the path has one, because `ls` needs an operand and
71
+ * a model that guessed a leaf usually had the parent wrong too — listing the
72
+ * parent is what tells it which of the two it got wrong.
73
+ */
74
+ export function pathMissLine(path) {
75
+ const parent = dirname(path);
76
+ const listing = parent && parent !== "." && parent !== "/" ? `ls ${parent}` : "ls on its parent";
77
+ return `path miss: ${path} — ${listing} names the layout in one call; find and explore_paths when the parent is unknown too`;
78
+ }
79
+ /** Test hook: forget every steered path and the current turn's budget. */
80
+ export function _resetForTests() {
81
+ steeredPaths.clear();
82
+ steeredThisTurn = false;
83
+ }
84
+ export default function pathMissExtension(pi) {
85
+ // The same turn boundary the whisper family uses: a new user input opens a
86
+ // new turn, and a turn that has already been steered is done.
87
+ pi.on(INPUT, () => {
88
+ steeredThisTurn = false;
89
+ });
90
+ pi.on(TOOL_RESULT, (event, ctx) => {
91
+ if (steeredThisTurn)
92
+ return;
93
+ if (!event?.isError)
94
+ return;
95
+ const miss = detectPathMiss(event.toolName, event.input, resultText(event.content));
96
+ if (!miss)
97
+ return;
98
+ const session = sessionKey(ctx);
99
+ if (alreadySteered(session, miss.path))
100
+ return;
101
+ steeredThisTurn = true;
102
+ const delivered = sendTrackedMessage(pi, {
103
+ customType: "path-miss",
104
+ content: [{ type: "text", text: pathMissLine(miss.path) }],
105
+ display: true,
106
+ }, { delivery: "live" }, { type: "enforcement", source: "path-miss/steer" });
107
+ // A suppressed send must not spend the path's budget: the line did not
108
+ // arrive, so the next turn is still the first place the agent can read it.
109
+ if (!delivered) {
110
+ steeredThisTurn = false;
111
+ log.debug(`[path-miss] suppressed by the whisper funnel: ${miss.path}`);
112
+ return;
113
+ }
114
+ remember(session, miss.path);
115
+ log.debug(`[path-miss] steered ${miss.path} (${miss.tool})`);
116
+ });
117
+ }
118
+ //# sourceMappingURL=index.js.map
@@ -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
@@ -164,6 +165,12 @@ export interface WatchdogEngineDeps {
164
165
  /** True when a timer/wake is due for this session: a due wake legitimately
165
166
  * keeps a quiet session quiet, so the turn is not classified dead. */
166
167
  isWakeDue?: (key: string) => boolean;
168
+ /** True when a self-started turn would park right now (the session's route
169
+ * has failed every attempt since its last successful call). An escalation
170
+ * is then delivered through `quietWhisper` while the out-of-band signal
171
+ * still fires — the content is not withdrawn, only the turn it would
172
+ * start. Absent or throwing ⇒ never parked (fail-open). */
173
+ isTurnStartBlocked?: () => boolean;
167
174
  log?: (level: "debug" | "info" | "warn" | "error", message: string, ...rest: unknown[]) => void;
168
175
  }
169
176
  /** Scalar-only watchdog observer line (see lib/telemetry/context-heartbeat.ts). */