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.
- package/CHANGELOG.md +1077 -0
- package/README.md +61 -228
- package/TOOLS.md +12 -14
- package/build-info.json +4 -4
- package/dist/extensions/cognitive/metacognition/handlers/think.js +9 -0
- package/dist/extensions/core/polyfill/index.d.ts +3 -4
- package/dist/extensions/core/polyfill/index.js +34 -131
- package/dist/extensions/core/skills-tool/index.js +47 -26
- package/dist/extensions/enforcement/handlers/register-agent-end-api-error.js +13 -0
- package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +8 -3
- package/dist/extensions/enforcement/session-health.d.ts +52 -4
- package/dist/extensions/enforcement/session-health.js +75 -5
- package/dist/extensions/enforcement/whisper.js +15 -1
- package/dist/extensions/heartbeat/heartbeat-scheduler/index.d.ts +17 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +40 -78
- package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +2 -1
- package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +26 -28
- package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.d.ts +62 -31
- package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.js +130 -55
- package/dist/extensions/manifest.js +6 -0
- package/dist/extensions/memory/context-lifecycle/index.js +11 -10
- package/dist/extensions/memory/context-manager/analysis.d.ts +2 -0
- package/dist/extensions/memory/context-manager/analysis.js +6 -2
- package/dist/extensions/memory/context-manager/handlers/compaction-retry.js +3 -3
- package/dist/extensions/memory/context-manager/handlers/events.js +13 -1
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +10 -14
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +62 -88
- package/dist/extensions/self/path-miss/detect.d.ts +30 -0
- package/dist/extensions/self/path-miss/detect.js +67 -0
- package/dist/extensions/self/path-miss/index.d.ts +33 -0
- package/dist/extensions/self/path-miss/index.js +118 -0
- package/dist/extensions/self/watchdog/engine.d.ts +8 -1
- package/dist/extensions/self/watchdog/engine.js +25 -2
- package/dist/extensions/self/watchdog/index.js +14 -1
- package/dist/lib/ai/llm-call.js +23 -0
- package/dist/lib/ai/model-resolver.d.ts +11 -10
- package/dist/lib/ai/model-resolver.js +16 -19
- package/dist/lib/ai/presend-budget.d.ts +68 -0
- package/dist/lib/ai/presend-budget.js +83 -0
- package/dist/lib/config/braid-settings.d.ts +38 -0
- package/dist/lib/config/braid-settings.js +84 -0
- package/dist/lib/config/per-tool-settings.d.ts +4 -4
- package/dist/lib/config/per-tool-settings.js +4 -4
- package/dist/lib/core/event-names.d.ts +1 -0
- package/dist/lib/core/event-names.js +1 -0
- package/dist/lib/detection/context-tiers.d.ts +18 -5
- package/dist/lib/detection/context-tiers.js +51 -33
- package/dist/lib/detection/context-usage.d.ts +62 -1
- package/dist/lib/detection/context-usage.js +158 -1
- package/dist/lib/errors/llm-error.d.ts +14 -0
- package/dist/lib/errors/llm-error.js +44 -1
- package/dist/lib/state/global-state.d.ts +4 -8
- package/dist/lib/state/global-state.js +11 -28
- package/dist/lib/telemetry/context-heartbeat.d.ts +9 -0
- package/dist/lib/telemetry/context-heartbeat.js +18 -8
- package/dist/lib/utils/argument-report.d.ts +41 -0
- package/dist/lib/utils/argument-report.js +95 -0
- package/dist/lib/utils/wake-gate.d.ts +6 -0
- package/dist/lib/utils/wake-gate.js +52 -4
- package/docs/SETUP.md +7 -6
- package/package.json +11 -13
- package/src/extensions/cognitive/metacognition/handlers/think.ts +9 -0
- package/src/extensions/core/polyfill/index.ts +29 -157
- package/src/extensions/core/skills-tool/index.ts +60 -37
- package/src/extensions/enforcement/AGENTS.md +38 -1
- package/src/extensions/enforcement/handlers/register-agent-end-api-error.ts +13 -0
- package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +8 -2
- package/src/extensions/enforcement/session-health.ts +94 -5
- package/src/extensions/enforcement/whisper.ts +15 -1
- package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +53 -80
- package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +34 -43
- package/src/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.ts +154 -52
- package/src/extensions/manifest.ts +6 -0
- package/src/extensions/memory/AGENTS.md +37 -38
- package/src/extensions/memory/context-lifecycle/index.ts +11 -10
- package/src/extensions/memory/context-manager/analysis.ts +8 -1
- package/src/extensions/memory/context-manager/handlers/compaction-retry.ts +3 -3
- package/src/extensions/memory/context-manager/handlers/events.ts +18 -1
- package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +81 -115
- package/src/extensions/scheduling/timer/AGENTS.md +14 -4
- package/src/extensions/self/AGENTS.md +2 -1
- package/src/extensions/self/path-miss/AGENTS.md +39 -0
- package/src/extensions/self/path-miss/detect.ts +78 -0
- package/src/extensions/self/path-miss/index.ts +135 -0
- package/src/extensions/self/watchdog/AGENTS.md +36 -18
- package/src/extensions/self/watchdog/engine.ts +30 -2
- package/src/extensions/self/watchdog/index.ts +13 -1
- package/src/lib/ai/AGENTS.md +2 -0
- package/src/lib/ai/llm-call.ts +30 -0
- package/src/lib/ai/model-resolver.ts +16 -19
- package/src/lib/ai/presend-budget.ts +117 -0
- package/src/lib/config/braid-settings.ts +125 -0
- package/src/lib/config/per-tool-settings.ts +4 -4
- package/src/lib/core/event-names.ts +1 -0
- package/src/lib/detection/context-tiers.ts +52 -41
- package/src/lib/detection/context-usage.ts +211 -2
- package/src/lib/errors/llm-error.ts +55 -1
- package/src/lib/state/global-state.ts +11 -29
- package/src/lib/telemetry/context-heartbeat.ts +27 -7
- package/src/lib/utils/AGENTS.md +1 -0
- package/src/lib/utils/argument-report.ts +105 -0
- 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
|
|
113
|
-
*
|
|
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
|
|
154
|
-
*
|
|
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
|
|
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
|
-
*
|
|
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
|
-
}
|
|
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
|
|
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
|
|
319
|
-
//
|
|
320
|
-
//
|
|
321
|
-
//
|
|
322
|
-
//
|
|
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
|
|
348
|
-
*
|
|
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
|
|
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 }
|
|
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)
|
|
420
|
-
* queue the tool arms drain through
|
|
421
|
-
*
|
|
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
|
|
426
|
-
*
|
|
427
|
-
*
|
|
428
|
-
*
|
|
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
|
|
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
|
|
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
|
|
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
|
|
517
|
-
// (
|
|
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
|
|
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.
|
|
542
|
-
//
|
|
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
|
-
//
|
|
551
|
-
//
|
|
552
|
-
//
|
|
553
|
-
//
|
|
554
|
-
//
|
|
555
|
-
//
|
|
556
|
-
//
|
|
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).
|
|
564
|
-
//
|
|
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
|
-
|
|
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
|
|
581
|
-
// the
|
|
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
|
-
//
|
|
586
|
-
// abort() is a clean no-op — no
|
|
587
|
-
// the post-compaction resume wake lands when the
|
|
588
|
-
// idle/promptable. The whole pending queue drains here
|
|
589
|
-
// active set is cleared so parked
|
|
590
|
-
// start never saw its end
|
|
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
|
|
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
|
|
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
|
|
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
|
|
1017
|
-
"
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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). */
|