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.
- package/CHANGELOG.md +92 -0
- package/README.md +61 -228
- package/TOOLS.md +12 -14
- package/build-info.json +4 -4
- package/dist/extensions/core/polyfill/index.d.ts +3 -4
- package/dist/extensions/core/polyfill/index.js +34 -131
- 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/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/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/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/wake-gate.d.ts +6 -0
- package/dist/lib/utils/wake-gate.js +52 -4
- package/docs/SETUP.md +7 -6
- package/package.json +8 -11
- package/src/extensions/core/polyfill/index.ts +29 -157
- 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/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/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/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/wake-gate.ts +59 -4
|
@@ -15,7 +15,6 @@ import { StringEnum } from "@earendil-works/pi-ai";
|
|
|
15
15
|
import { Type } from "typebox";
|
|
16
16
|
import { createLogger } from "../../../lib/core/logger.js";
|
|
17
17
|
import { applyWhisperEnvelope } from "../../../lib/utils/whisper-format.js";
|
|
18
|
-
import { formatTokensK } from "../../../lib/detection/context-usage.js";
|
|
19
18
|
import { existsSync, readFileSync } from "node:fs";
|
|
20
19
|
import * as path from "node:path";
|
|
21
20
|
import { braidDir, tagsSlugFromCwd } from "../../../lib/config/braid-paths.js";
|
|
@@ -128,13 +127,14 @@ function sendCompactNudge(pi, evaluated, usage, tokens) {
|
|
|
128
127
|
// >= USAGE_TOKENS_ESCALATE (0.85W) escalated wording (archive-or-handoff)
|
|
129
128
|
// >= HARD_BACKSTOP (0.90W) or usage >= 80 full pipeline message
|
|
130
129
|
// else light tag/checkout message
|
|
131
|
-
// Percent stays as the secondary trigger (sub-1M windows).
|
|
132
|
-
|
|
130
|
+
// Percent stays as the secondary trigger (sub-1M windows). The text names
|
|
131
|
+
// the deadline and the action, never the number: the bars own the number,
|
|
132
|
+
// and a percentage copied into prose drifts from the meter.
|
|
133
133
|
const pipelineMsg = tokens >= USAGE_TOKENS_ESCALATE()
|
|
134
|
-
? `
|
|
134
|
+
? `Escalated: an armed compaction fires when the run settles. Archive the current phase with context_compress(action="archive"), or hand off to a fresh session (write a handoff note first).`
|
|
135
135
|
: usage >= 80 || tokens >= HYGIENE_AUTO_COMPACT_HARD_BACKSTOP()
|
|
136
|
-
? `
|
|
137
|
-
: `
|
|
136
|
+
? `An armed compaction fires when the run settles. Pipeline: context_navigate(action="tag") -> context_navigate(action="checkout") -> context_compress(action="archive") -> context_compress(action="slide").`
|
|
137
|
+
: `An armed compaction fires when the run settles. Tag with context_navigate(action="tag"), then context_navigate(action="checkout") to branch with a summary before the next task.`;
|
|
138
138
|
sendTrackedMessage(pi, {
|
|
139
139
|
customType: "context-lifecycle",
|
|
140
140
|
content: [
|
|
@@ -145,7 +145,7 @@ function sendCompactNudge(pi, evaluated, usage, tokens) {
|
|
|
145
145
|
],
|
|
146
146
|
display: true,
|
|
147
147
|
details: { [BRAID_INJECTED]: true, [BRAID_SOURCE]: "context-lifecycle/compact-suggestion" },
|
|
148
|
-
}, {
|
|
148
|
+
}, { deliverAs: "nextTurn" }, { type: "context", source: "context-lifecycle/compact-suggestion" });
|
|
149
149
|
log.info(`Suggested compact: ${evaluated.policy.name} (context ${Math.round(usage)}%, ` +
|
|
150
150
|
`priority ${evaluated.policy.priority})`);
|
|
151
151
|
}
|
|
@@ -225,7 +225,7 @@ function executeAction(evaluated, pi, ctx, usage, branchLength) {
|
|
|
225
225
|
customType: "context-lifecycle",
|
|
226
226
|
content: [{ type: "text", text: msg }],
|
|
227
227
|
display: true,
|
|
228
|
-
}, {
|
|
228
|
+
}, { deliverAs: "nextTurn" }, { type: "context", source: "context-lifecycle/nudge" });
|
|
229
229
|
}
|
|
230
230
|
break;
|
|
231
231
|
}
|
|
@@ -246,7 +246,8 @@ function hasConcreteCompressionSignal(evaluated) {
|
|
|
246
246
|
/**
|
|
247
247
|
* Proposals triggered by PERSISTENT conditions - usage %, token counts,
|
|
248
248
|
* density - stay true across turns, so the policy re-fires every cooldown
|
|
249
|
-
* with a fresh copy of the SAME advice ("
|
|
249
|
+
* with a fresh copy of the SAME advice ("an armed compaction fires when the
|
|
250
|
+
* run settles").
|
|
250
251
|
* This is the measured 33% exact-repeat class. Event-triggered proposals
|
|
251
252
|
* (topic_shift, task_boundary, task_complexity, decision_density,
|
|
252
253
|
* task_completion_candidate) fire on discrete moments and are NOT this class
|
|
@@ -486,7 +487,7 @@ async function queueProposal(evaluated, pi, ctx, branchLength) {
|
|
|
486
487
|
customType: "context-lifecycle",
|
|
487
488
|
content: [{ type: "text", text: msg }],
|
|
488
489
|
display: true,
|
|
489
|
-
}, { deliverAs: "
|
|
490
|
+
}, { deliverAs: "nextTurn" }, { type: "context", source: "context-lifecycle/phase-boundary-enforcement" });
|
|
490
491
|
// Track navigation whisper for escalation monitoring
|
|
491
492
|
state(ctx).lastNavigationWhisperTurn = state(ctx).turnCount;
|
|
492
493
|
}
|
|
@@ -19,6 +19,8 @@ export interface AuditResult {
|
|
|
19
19
|
};
|
|
20
20
|
/** How the usage number was produced (live working set vs fallback). */
|
|
21
21
|
usageSource: string;
|
|
22
|
+
/** The short provenance word for the number: measured or estimated. */
|
|
23
|
+
usageSourceKind: "measured" | "estimated" | "unavailable";
|
|
22
24
|
/** Whole-branch token sum - labeled "not sent" wherever displayed. */
|
|
23
25
|
branchTokens: number;
|
|
24
26
|
branchLength: number;
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { getContextUsage } from "../../../lib/detection/context-tiers.js";
|
|
2
2
|
import { formatTokensK } from "../../../lib/detection/context-usage.js";
|
|
3
|
-
import { measureLiveUsage, tokenArms, resolveWindow, } from "../../../lib/detection/context-usage.js";
|
|
3
|
+
import { describeUsage, measureLiveUsage, tokenArms, resolveWindow, } from "../../../lib/detection/context-usage.js";
|
|
4
4
|
import { CONTEXT_COMPACT_REFUSE_PERCENT } from "../../../lib/detection/context-thresholds.js";
|
|
5
5
|
import { isInternal } from "./handlers/shared.js";
|
|
6
6
|
// isInternal comes from ./handlers/shared.js — the canonical list shared
|
|
@@ -38,6 +38,7 @@ export function analyzeSession(ctx) {
|
|
|
38
38
|
const tree = sm.getTree();
|
|
39
39
|
let usage = { percent: 0, tokens: 0, contextWindow: 0 };
|
|
40
40
|
let usageSource = "unavailable";
|
|
41
|
+
let usageSourceKind = "unavailable";
|
|
41
42
|
let branchTokens = 0;
|
|
42
43
|
try {
|
|
43
44
|
const live = measureLiveUsage(ctx);
|
|
@@ -47,7 +48,8 @@ export function analyzeSession(ctx) {
|
|
|
47
48
|
tokens: live.tokens,
|
|
48
49
|
contextWindow: live.contextWindow,
|
|
49
50
|
};
|
|
50
|
-
usageSource = `session tree
|
|
51
|
+
usageSource = `session tree, ${live.windowSource} window, ${describeUsage(live)}`;
|
|
52
|
+
usageSourceKind = live.source;
|
|
51
53
|
branchTokens = live.branchTokens;
|
|
52
54
|
}
|
|
53
55
|
else {
|
|
@@ -61,6 +63,7 @@ export function analyzeSession(ctx) {
|
|
|
61
63
|
contextWindow: ctxUsage?.contextWindow ?? window.contextWindow,
|
|
62
64
|
};
|
|
63
65
|
usageSource = "ctx.getContextUsage fallback";
|
|
66
|
+
usageSourceKind = "estimated";
|
|
64
67
|
branchTokens = usage.tokens;
|
|
65
68
|
}
|
|
66
69
|
}
|
|
@@ -233,6 +236,7 @@ export function analyzeSession(ctx) {
|
|
|
233
236
|
return {
|
|
234
237
|
usage,
|
|
235
238
|
usageSource,
|
|
239
|
+
usageSourceKind,
|
|
236
240
|
branchTokens,
|
|
237
241
|
branchLength: branch.length,
|
|
238
242
|
treeDepth: tree.length,
|
|
@@ -85,7 +85,7 @@ export async function handleOverflowFailure(pi, event, ctx, errorMessage) {
|
|
|
85
85
|
try {
|
|
86
86
|
const analysis = await analyzeSession(ctx);
|
|
87
87
|
if (analysis.usage.percent >= 75) {
|
|
88
|
-
log.warn(`[Critical] Context at ${analysis.usage.percent.toFixed(1)}% - triggering emergency rotation (overflow)`);
|
|
88
|
+
log.warn(`[Critical] Context at ${analysis.usage.percent.toFixed(1)}% ${analysis.usageSourceKind} - triggering emergency rotation (overflow)`);
|
|
89
89
|
triggerEmergencyRotation(pi, ctx);
|
|
90
90
|
return;
|
|
91
91
|
}
|
|
@@ -150,7 +150,7 @@ export async function handleTransientError(pi, event, ctx, errorMessage) {
|
|
|
150
150
|
try {
|
|
151
151
|
const analysis = await analyzeSession(ctx);
|
|
152
152
|
if (analysis.usage.percent >= 75) {
|
|
153
|
-
log.warn(`[Critical] Context at ${analysis.usage.percent.toFixed(1)}% - triggering emergency rotation (transient)`);
|
|
153
|
+
log.warn(`[Critical] Context at ${analysis.usage.percent.toFixed(1)}% ${analysis.usageSourceKind} - triggering emergency rotation (transient)`);
|
|
154
154
|
triggerEmergencyRotation(pi, ctx);
|
|
155
155
|
return;
|
|
156
156
|
}
|
|
@@ -252,7 +252,7 @@ export async function handleThresholdFailure(pi, event, ctx, errorMessage) {
|
|
|
252
252
|
try {
|
|
253
253
|
const analysis = await analyzeSession(ctx);
|
|
254
254
|
if (analysis.usage.percent >= 75) {
|
|
255
|
-
log.warn(`[Critical] Context at ${analysis.usage.percent.toFixed(1)}% - triggering emergency rotation (threshold)`);
|
|
255
|
+
log.warn(`[Critical] Context at ${analysis.usage.percent.toFixed(1)}% ${analysis.usageSourceKind} - triggering emergency rotation (threshold)`);
|
|
256
256
|
triggerEmergencyRotation(pi, ctx);
|
|
257
257
|
return;
|
|
258
258
|
}
|
|
@@ -15,6 +15,8 @@ import { determineCompressionLevel } from "../../../../lib/detection/compression
|
|
|
15
15
|
import { semanticCompress } from "../semantic-compress.js";
|
|
16
16
|
import { updateContextDensity } from "../../../heartbeat/analytics/index.js";
|
|
17
17
|
import { AGENT_END } from "../../../../lib/core/event-names.js";
|
|
18
|
+
import { clearRequestShapeFailure, noteRequestShapeFailure, } from "../../../../lib/utils/wake-gate.js";
|
|
19
|
+
import { isContextLengthRequestShape } from "../../../../lib/errors/llm-error.js";
|
|
18
20
|
import { log, getCmState, compactionRetryState, overflowRetryState, COMPACTION_RETRY_MAX_ATTEMPTS, OVERFLOW_RETRY_MAX_ATTEMPTS, COMPACTION_RETRY_CUSTOM_TYPE, resetCompactionRetry, resetOverflowRetry, getCompactionRetryDelay, getOverflowRetryDelay, } from "./shared.js";
|
|
19
21
|
export function registerAgentEndRetryHandler(pi) {
|
|
20
22
|
pi.on(AGENT_END, async (event, ctx) => {
|
|
@@ -112,9 +114,19 @@ export function registerAgentEndApiErrorHandler(pi) {
|
|
|
112
114
|
break;
|
|
113
115
|
}
|
|
114
116
|
}
|
|
115
|
-
if (!lastAssistant || lastAssistant.stopReason !== "error")
|
|
117
|
+
if (!lastAssistant || lastAssistant.stopReason !== "error") {
|
|
118
|
+
// A turn that ended without an error means a request fit and came back:
|
|
119
|
+
// the shape verdict from an earlier refusal no longer applies.
|
|
120
|
+
clearRequestShapeFailure();
|
|
116
121
|
return;
|
|
122
|
+
}
|
|
117
123
|
const finalError = lastAssistant.errorMessage ?? "Unknown error";
|
|
124
|
+
// A context-length refusal is the request's shape, not the provider's
|
|
125
|
+
// mood. Record it here so the wake gate can keep failed-open wakes from
|
|
126
|
+
// re-firing a request that cannot succeed.
|
|
127
|
+
if (isContextLengthRequestShape(finalError)) {
|
|
128
|
+
noteRequestShapeFailure(finalError.slice(0, 200));
|
|
129
|
+
}
|
|
118
130
|
sendTrackedMessage(pi, {
|
|
119
131
|
customType: "context",
|
|
120
132
|
content: [
|
|
@@ -13,7 +13,6 @@
|
|
|
13
13
|
*/
|
|
14
14
|
import { Type } from "typebox";
|
|
15
15
|
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
16
|
-
import { type TurnBoundary } from "../../../../../lib/events/turn-boundary.js";
|
|
17
16
|
/**
|
|
18
17
|
* Read the pending queue without creating state (inspect surfaces it).
|
|
19
18
|
* Exported so context_inspect and the heartbeat advisory can report
|
|
@@ -32,8 +31,8 @@ export declare function readPendingCompactions(ctx: any): Array<{
|
|
|
32
31
|
export declare function hasPendingLlmCompaction(ctx: any): boolean;
|
|
33
32
|
/**
|
|
34
33
|
* One pending-state line for the armed-but-unfired compaction queue
|
|
35
|
-
* ("slide armed 17:28 — fires
|
|
36
|
-
*
|
|
34
|
+
* ("slide armed 17:28 — fires when the run settles; live usage drops when it
|
|
35
|
+
* lands"). Null when nothing is pending: no surface may fabricate an
|
|
37
36
|
* expectation of a drop that is not armed. Shared by context_inspect and the
|
|
38
37
|
* heartbeat advisory so both state the same fact the same way.
|
|
39
38
|
*/
|
|
@@ -61,20 +60,17 @@ export declare function resolveAutoSlideKeep(branchLength: number): number;
|
|
|
61
60
|
* Usage-driven auto-arm: when live usage sits above the configured threshold
|
|
62
61
|
* for `confirmTicks` consecutive observations, arm ONE deterministic slide so
|
|
63
62
|
* a session that never gets a manual cleanup still gets relief. Reuses the
|
|
64
|
-
* accounting context_inspect computes (analyzeSession)
|
|
65
|
-
* queue the tool arms drain through
|
|
66
|
-
*
|
|
67
|
-
* settle, never mid-run.
|
|
63
|
+
* accounting context_inspect computes (analyzeSession) and the same pending
|
|
64
|
+
* queue the tool arms drain through: arming only queues; the compaction itself
|
|
65
|
+
* fires when the run settles (or at the 0.90W backstop), never mid-run.
|
|
68
66
|
*
|
|
69
67
|
* Called from the heartbeat tick — the only cadence that runs while a session
|
|
70
|
-
* works
|
|
71
|
-
*
|
|
72
|
-
*
|
|
73
|
-
*
|
|
74
|
-
* loop is about to dispatch. Returns what happened and why, so the caller can
|
|
75
|
-
* log it.
|
|
68
|
+
* works. Arming only queues: the entry waits for `agent_settled`, because the
|
|
69
|
+
* tick runs while the run is live and nothing at that point can prove the loop
|
|
70
|
+
* has no request left to dispatch. Returns what happened and why, so the
|
|
71
|
+
* caller can log it.
|
|
76
72
|
*/
|
|
77
|
-
export declare function maybeArmAutoCompaction(pi: ExtensionAPI, ctx: any
|
|
73
|
+
export declare function maybeArmAutoCompaction(pi: ExtensionAPI, ctx: any): {
|
|
78
74
|
armed: boolean;
|
|
79
75
|
reason: string;
|
|
80
76
|
};
|
|
@@ -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"),
|
|
@@ -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). */
|