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