pi-braid 0.43.7 → 0.43.8
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 +39 -0
- package/TOOLS.md +1 -1
- package/build-info.json +4 -4
- package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +21 -0
- package/dist/extensions/core/skills-tool/auto-inject.js +105 -1
- package/dist/extensions/core/skills-tool/index.js +20 -2
- package/dist/extensions/core/skills-tool/loading-guidance.d.ts +4 -1
- package/dist/extensions/core/skills-tool/loading-guidance.js +4 -1
- package/dist/extensions/core/skills-tool/session-records.d.ts +107 -9
- package/dist/extensions/core/skills-tool/session-records.js +141 -5
- package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +5 -1
- package/dist/extensions/enforcement/handlers/register-tool-call.js +5 -2
- package/dist/extensions/enforcement/verification-judge.d.ts +7 -0
- package/dist/extensions/enforcement/verification-judge.js +28 -21
- package/dist/extensions/memory/session-recall/ask.d.ts +95 -0
- package/dist/extensions/memory/session-recall/ask.js +376 -0
- package/dist/extensions/memory/session-recall/corpus-index.d.ts +200 -0
- package/dist/extensions/memory/session-recall/corpus-index.js +480 -0
- package/dist/extensions/memory/session-recall/index.js +173 -21
- package/dist/extensions/memory/session-recall/search.d.ts +29 -0
- package/dist/extensions/memory/session-recall/search.js +42 -9
- package/dist/lib/ai/payload-hygiene.d.ts +3 -0
- package/dist/lib/ai/payload-hygiene.js +34 -2
- package/dist/lib/config/braid-paths.d.ts +4 -0
- package/dist/lib/config/braid-paths.js +6 -0
- package/dist/lib/config/braid-settings.d.ts +22 -0
- package/dist/lib/config/braid-settings.js +15 -0
- package/dist/lib/detection/tool-loop-detector.d.ts +95 -46
- package/dist/lib/detection/tool-loop-detector.js +288 -180
- package/dist/lib/reasoning/dreamer.d.ts +2 -1
- package/dist/lib/reasoning/dreamer.js +12 -7
- package/docs/LOCAL_DEV.md +1 -1
- package/docs/SETUP.md +1 -0
- package/package.json +1 -1
- package/src/extensions/core/AGENTS.md +3 -2
- package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
- package/src/extensions/core/skills-tool/auto-inject.ts +118 -1
- package/src/extensions/core/skills-tool/index.ts +21 -1
- package/src/extensions/core/skills-tool/loading-guidance.ts +4 -1
- package/src/extensions/core/skills-tool/session-records.ts +201 -9
- package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +5 -1
- package/src/extensions/enforcement/handlers/register-tool-call.ts +5 -2
- package/src/extensions/enforcement/verification-judge.ts +32 -25
- package/src/extensions/memory/AGENTS.md +2 -2
- package/src/extensions/memory/session-recall/AGENTS.md +92 -18
- package/src/extensions/memory/session-recall/ask.ts +435 -0
- package/src/extensions/memory/session-recall/corpus-index.ts +609 -0
- package/src/extensions/memory/session-recall/index.ts +202 -21
- package/src/extensions/memory/session-recall/search.ts +61 -10
- package/src/lib/ai/payload-hygiene.ts +47 -3
- package/src/lib/config/braid-paths.ts +7 -0
- package/src/lib/config/braid-settings.ts +42 -3
- package/src/lib/detection/AGENTS.md +8 -7
- package/src/lib/detection/tool-loop-detector.ts +339 -195
- package/src/lib/reasoning/dreamer.ts +13 -6
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Tool Loop Detector - single source of truth for "agent stuck
|
|
3
|
-
* the same
|
|
2
|
+
* Tool Loop Detector - single source of truth for "agent stuck repeating
|
|
3
|
+
* the same call".
|
|
4
4
|
*
|
|
5
5
|
* One detector, one threshold, one window, one cooldown, one remedy.
|
|
6
6
|
* Consumers (turn-outcome, dreamer, policy-rules) call detectToolLoop()
|
|
@@ -15,26 +15,44 @@
|
|
|
15
15
|
* The two paths share a tryClaim-based dedup so only ONE whisper
|
|
16
16
|
* per loop event reaches the agent.
|
|
17
17
|
*
|
|
18
|
+
* IDENTITY, NOT NAME. A recorded call carries the tool name and an
|
|
19
|
+
* identity built from the arguments (toolCallIdentity). Sixteen `bash`
|
|
20
|
+
* calls running sixteen different commands are a chain of work: the agent
|
|
21
|
+
* is exploring, testing, committing, and nothing repeats. Sixteen runs of
|
|
22
|
+
* the same command are a repeat, and sixteen turns of that same command
|
|
23
|
+
* are a loop across turns. Name-only counting could not tell those apart,
|
|
24
|
+
* which is why the detector used to accuse a chain of work at the same
|
|
25
|
+
* threshold as a repeat. Measured over 672 stored accusations before the
|
|
26
|
+
* change: 667 had a tail of twenty distinct calls under one name, none was
|
|
27
|
+
* an identical repeat.
|
|
28
|
+
*
|
|
18
29
|
* STATE LIFECYCLE:
|
|
19
30
|
* - getToolLoopState(ctx) returns the per-session state via
|
|
20
31
|
* getExtensionState. Resets on session_start, no manual reset
|
|
21
32
|
* needed.
|
|
22
|
-
* - recordToolCall() is called from the tool_call
|
|
23
|
-
* with the
|
|
33
|
+
* - recordToolCall(state, toolName, input) is called from the tool_call
|
|
34
|
+
* event handler with the call's arguments.
|
|
24
35
|
* - recordTurnEnd() is called from turn_end to bump the counter
|
|
25
36
|
* used for cooldown comparison.
|
|
26
37
|
* - detectToolLoop() reads the state and returns the verdict.
|
|
27
38
|
*
|
|
28
39
|
* THRESHOLDS (one of each - change here, change everywhere):
|
|
29
|
-
* - TOOL_LOOP_THRESHOLD: 16 consecutive
|
|
30
|
-
*
|
|
40
|
+
* - TOOL_LOOP_THRESHOLD: 16 consecutive calls with one identity, or 16
|
|
41
|
+
* strictly alternating calls of two identities, or one identity across
|
|
42
|
+
* 16 consecutive turns
|
|
43
|
+
* - TOOL_LOOP_WINDOW: 20 calls of history kept
|
|
31
44
|
* - TOOL_LOOP_COOLDOWN_TURNS: 8 turns between emissions
|
|
45
|
+
* - TOOL_TURN_WINDOW: 20 turns of per-turn history kept (the cross-turn
|
|
46
|
+
* shape needs 16 consecutive turns, so this bound is in turns)
|
|
32
47
|
*
|
|
33
|
-
* 16 catches
|
|
34
|
-
*
|
|
35
|
-
*
|
|
48
|
+
* 16 catches the same call returning sixteen times. It does not catch a chain
|
|
49
|
+
* of work that happens to use one tool, which is the whole point of the
|
|
50
|
+
* identity rule: reading several files, running a build, a commit, and a grep
|
|
51
|
+
* are different calls.
|
|
36
52
|
*
|
|
37
|
-
* Only
|
|
53
|
+
* Only this file decides a loop. The whisper that reaches the agent is the
|
|
54
|
+
* enforcement handler's, driven by this verdict; the analytics and dreamer
|
|
55
|
+
* paths keep their observations and deliver nothing. If any intentional
|
|
38
56
|
* (metacognitive) tool - think, verify, verify_claim, finalize,
|
|
39
57
|
* hypothesize, scratchpad, memory, memory_store, repl - appears anywhere
|
|
40
58
|
* in the recorded window, the agent is engaged, not stuck, and
|
|
@@ -42,14 +60,30 @@
|
|
|
42
60
|
* Per-episode single delivery is enforced here by markLoopFired() + the
|
|
43
61
|
* 8-turn TOOL_LOOP_COOLDOWN_TURNS gate, and the whisper never wakes the
|
|
44
62
|
* agent (triggerTurn:false, see enforcement/handlers/turn-end-handler.ts).
|
|
63
|
+
*
|
|
64
|
+
* The whisper states what was observed - the same call, with identical
|
|
65
|
+
* arguments, repeated - and never claims the absence of progress, which
|
|
66
|
+
* this module cannot see.
|
|
45
67
|
*/
|
|
46
68
|
import { getExtensionState } from "../state/extension-state.js";
|
|
47
|
-
|
|
69
|
+
import { hashForDedup } from "../utils/dedup.js";
|
|
70
|
+
/** Minimum consecutive same-identity calls (or turns) in the recent history to flag. */
|
|
48
71
|
export const TOOL_LOOP_THRESHOLD = 16;
|
|
49
|
-
/** How many recent
|
|
72
|
+
/** How many recent calls to retain in the rolling window. Must be >= TOOL_LOOP_THRESHOLD + 1. */
|
|
50
73
|
export const TOOL_LOOP_WINDOW = 20;
|
|
51
74
|
/** Minimum turns between successive loop whispers. */
|
|
52
75
|
export const TOOL_LOOP_COOLDOWN_TURNS = 8;
|
|
76
|
+
/** How many turns of per-turn history to retain. A cross-turn loop needs
|
|
77
|
+
* TOOL_LOOP_THRESHOLD consecutive turns, so the bound is turn-shaped rather
|
|
78
|
+
* than call-shaped: bounding the total call count would evict the older turns
|
|
79
|
+
* of a busy agent and hide the very run the cross-turn shape looks for. Each
|
|
80
|
+
* turn's own call list is bounded by TOOL_LOOP_WINDOW. */
|
|
81
|
+
export const TOOL_TURN_WINDOW = TOOL_LOOP_THRESHOLD + 4;
|
|
82
|
+
/** Longest argument string kept verbatim in an identity. Longer values are
|
|
83
|
+
* replaced by a digest plus their length: a heredoc command runs to thousands
|
|
84
|
+
* of characters and would otherwise be retained twenty times over, while
|
|
85
|
+
* equality - the only thing the detector reads - survives the digest. */
|
|
86
|
+
const MAX_IDENTITY_VALUE_CHARS = 80;
|
|
53
87
|
// Intentional-use filter: metacognitive tools that prove the agent is
|
|
54
88
|
// engaged, not stuck. If any of these appears in the recorded window, the
|
|
55
89
|
// agent is deliberately reflecting/verifying/closing-out, not mechanically
|
|
@@ -66,21 +100,6 @@ const INTENTIONAL_TOOLS = new Set([
|
|
|
66
100
|
"memory_store",
|
|
67
101
|
"repl",
|
|
68
102
|
]);
|
|
69
|
-
/** True when the agent showed any intentional (metacognitive) tool in the
|
|
70
|
-
* recorded history window. History is already capped at TOOL_LOOP_WINDOW. */
|
|
71
|
-
function hasIntentionalToolInHistory(history) {
|
|
72
|
-
return history.some((t) => INTENTIONAL_TOOLS.has(t));
|
|
73
|
-
}
|
|
74
|
-
/** True when any per-turn tool set in the window contains an intentional tool. */
|
|
75
|
-
function hasIntentionalToolInTurns(perTurn) {
|
|
76
|
-
for (const turn of perTurn) {
|
|
77
|
-
for (const tool of turn) {
|
|
78
|
-
if (INTENTIONAL_TOOLS.has(tool))
|
|
79
|
-
return true;
|
|
80
|
-
}
|
|
81
|
-
}
|
|
82
|
-
return false;
|
|
83
|
-
}
|
|
84
103
|
export function createToolLoopState() {
|
|
85
104
|
return {
|
|
86
105
|
perTurn: [],
|
|
@@ -93,28 +112,76 @@ export function getToolLoopState(ctx) {
|
|
|
93
112
|
return getExtensionState(ctx, "tool-loop-detector", createToolLoopState);
|
|
94
113
|
}
|
|
95
114
|
/**
|
|
96
|
-
*
|
|
97
|
-
*
|
|
98
|
-
* tool set. If no turn has started yet, creates one.
|
|
115
|
+
* Normalize an argument value for equality: whitespace collapsed, object keys
|
|
116
|
+
* sorted (argument order is not identity), long strings digested.
|
|
99
117
|
*/
|
|
100
|
-
|
|
101
|
-
if (
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
118
|
+
function normalizeArgValue(value) {
|
|
119
|
+
if (typeof value === "string") {
|
|
120
|
+
const collapsed = value.replace(/\s+/g, " ").trim();
|
|
121
|
+
return collapsed.length > MAX_IDENTITY_VALUE_CHARS
|
|
122
|
+
? `#${hashForDedup(collapsed)}:${collapsed.length}`
|
|
123
|
+
: collapsed;
|
|
105
124
|
}
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
125
|
+
if (Array.isArray(value))
|
|
126
|
+
return value.map(normalizeArgValue);
|
|
127
|
+
if (value && typeof value === "object") {
|
|
128
|
+
const out = {};
|
|
129
|
+
const source = value;
|
|
130
|
+
for (const key of Object.keys(source).sort()) {
|
|
131
|
+
const normalized = normalizeArgValue(source[key]);
|
|
132
|
+
if (normalized !== undefined)
|
|
133
|
+
out[key] = normalized;
|
|
134
|
+
}
|
|
135
|
+
return out;
|
|
115
136
|
}
|
|
116
|
-
|
|
117
|
-
|
|
137
|
+
return value;
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* Build the equality key for one tool call: the tool name plus its normalized
|
|
141
|
+
* arguments. Two calls share an identity exactly when they are the same call -
|
|
142
|
+
* same tool, same arguments - which is what "the agent repeated itself" means.
|
|
143
|
+
*
|
|
144
|
+
* A call whose arguments are absent or empty is identified by its name alone;
|
|
145
|
+
* there is no argument evidence to distinguish it from another call of the
|
|
146
|
+
* same tool, so they count as the same call.
|
|
147
|
+
*/
|
|
148
|
+
export function toolCallIdentity(toolName, input) {
|
|
149
|
+
if (!toolName)
|
|
150
|
+
return "";
|
|
151
|
+
if (input === undefined || input === null)
|
|
152
|
+
return toolName;
|
|
153
|
+
const normalized = normalizeArgValue(input);
|
|
154
|
+
const serialized = JSON.stringify(normalized);
|
|
155
|
+
if (!serialized || serialized === "{}" || serialized === "null")
|
|
156
|
+
return toolName;
|
|
157
|
+
return `${toolName} ${serialized}`;
|
|
158
|
+
}
|
|
159
|
+
function openTurn() {
|
|
160
|
+
return { tools: new Set(), calls: [] };
|
|
161
|
+
}
|
|
162
|
+
/** Drop whole turns from the oldest end past the per-turn window. */
|
|
163
|
+
function trimPerTurn(state) {
|
|
164
|
+
while (state.perTurn.length > TOOL_TURN_WINDOW)
|
|
165
|
+
state.perTurn.pop();
|
|
166
|
+
}
|
|
167
|
+
/**
|
|
168
|
+
* Record a tool invocation. Call this from the tool_call event handler with
|
|
169
|
+
* the tool name and its arguments. Adds the call to the current (most recent)
|
|
170
|
+
* turn. If no turn has started yet, creates one.
|
|
171
|
+
*/
|
|
172
|
+
export function recordToolCall(state, toolName, input) {
|
|
173
|
+
if (!toolName)
|
|
174
|
+
return;
|
|
175
|
+
if (state.perTurn.length === 0)
|
|
176
|
+
state.perTurn.push(openTurn());
|
|
177
|
+
const turn = state.perTurn[0];
|
|
178
|
+
turn.tools.add(toolName);
|
|
179
|
+
const record = { tool: toolName, identity: toolCallIdentity(toolName, input) };
|
|
180
|
+
turn.calls.push(record);
|
|
181
|
+
if (turn.calls.length > TOOL_LOOP_WINDOW)
|
|
182
|
+
turn.calls.shift();
|
|
183
|
+
trimPerTurn(state);
|
|
184
|
+
state.history.push(record);
|
|
118
185
|
if (state.history.length > TOOL_LOOP_WINDOW) {
|
|
119
186
|
state.history.shift();
|
|
120
187
|
}
|
|
@@ -122,21 +189,11 @@ export function recordToolCall(state, toolName) {
|
|
|
122
189
|
/**
|
|
123
190
|
* Record the end of a turn. Call this from the turn_end handler to
|
|
124
191
|
* bump the counter and open a new turn for the next round of tool calls.
|
|
125
|
-
* Pushes a fresh perTurn entry so the next recordToolCall adds to the new
|
|
126
|
-
* turn's set. History rotation happens in recordToolCall; perTurn entries
|
|
127
|
-
* are trimmed to TOOL_LOOP_WINDOW here.
|
|
128
192
|
*/
|
|
129
193
|
export function recordTurnEnd(state) {
|
|
130
194
|
state.turnCount++;
|
|
131
|
-
state.perTurn.unshift(
|
|
132
|
-
|
|
133
|
-
for (const turn of state.perTurn) {
|
|
134
|
-
totalTools += turn.size;
|
|
135
|
-
}
|
|
136
|
-
while (totalTools > TOOL_LOOP_WINDOW && state.perTurn.length > 1) {
|
|
137
|
-
const removed = state.perTurn.pop();
|
|
138
|
-
totalTools -= removed.size;
|
|
139
|
-
}
|
|
195
|
+
state.perTurn.unshift(openTurn());
|
|
196
|
+
trimPerTurn(state);
|
|
140
197
|
}
|
|
141
198
|
/**
|
|
142
199
|
* Mark a loop whisper as fired at the current turn. Call this after
|
|
@@ -146,157 +203,208 @@ export function recordTurnEnd(state) {
|
|
|
146
203
|
export function markLoopFired(state) {
|
|
147
204
|
state.lastFiredAtTurn = state.turnCount;
|
|
148
205
|
}
|
|
206
|
+
/** True when the agent showed any intentional (metacognitive) tool in the
|
|
207
|
+
* recorded history window. History is already capped at TOOL_LOOP_WINDOW. */
|
|
208
|
+
function hasIntentionalToolInHistory(history) {
|
|
209
|
+
return history.some((call) => INTENTIONAL_TOOLS.has(call.tool));
|
|
210
|
+
}
|
|
211
|
+
/** True when any per-turn tool set in the window contains an intentional tool. */
|
|
212
|
+
function hasIntentionalToolInTurns(perTurn) {
|
|
213
|
+
for (const turn of perTurn) {
|
|
214
|
+
for (const tool of turn.tools) {
|
|
215
|
+
if (INTENTIONAL_TOOLS.has(tool))
|
|
216
|
+
return true;
|
|
217
|
+
}
|
|
218
|
+
}
|
|
219
|
+
return false;
|
|
220
|
+
}
|
|
221
|
+
/** Length of the run of one identity at the end of the history. */
|
|
222
|
+
function identityTailRun(history) {
|
|
223
|
+
if (history.length === 0)
|
|
224
|
+
return null;
|
|
225
|
+
const last = history[history.length - 1];
|
|
226
|
+
let count = 1;
|
|
227
|
+
for (let i = history.length - 2; i >= 0; i--) {
|
|
228
|
+
if (history[i].identity === last.identity)
|
|
229
|
+
count++;
|
|
230
|
+
else
|
|
231
|
+
break;
|
|
232
|
+
}
|
|
233
|
+
return { count, call: last };
|
|
234
|
+
}
|
|
235
|
+
/** Length of a strict two-identity oscillation at the end of the history
|
|
236
|
+
* (A,B,A,B,... - never A,A). Returns null when the last two calls are the
|
|
237
|
+
* same call, which is the repeat path's case, not this one. */
|
|
238
|
+
function alternationTailRun(history) {
|
|
239
|
+
if (history.length < 2)
|
|
240
|
+
return null;
|
|
241
|
+
const a = history[history.length - 1];
|
|
242
|
+
const b = history[history.length - 2];
|
|
243
|
+
if (a.identity === b.identity)
|
|
244
|
+
return null;
|
|
245
|
+
let count = 2;
|
|
246
|
+
for (let i = history.length - 3; i >= 0; i--) {
|
|
247
|
+
const expected = count % 2 === 0 ? a : b;
|
|
248
|
+
if (history[i].identity === expected.identity)
|
|
249
|
+
count++;
|
|
250
|
+
else
|
|
251
|
+
break;
|
|
252
|
+
}
|
|
253
|
+
return { count, a, b };
|
|
254
|
+
}
|
|
255
|
+
const SUGGESTED_ACTIONS = `\n\n**Suggested actions:**\n` +
|
|
256
|
+
`1. Use \`think()\` tool to re-evaluate your approach\n` +
|
|
257
|
+
`2. Check if the problem has changed - you may be solving the wrong issue\n` +
|
|
258
|
+
`3. Consider breaking the task into smaller steps\n` +
|
|
259
|
+
`4. Use the \`memory()\` tool to find past solutions to similar problems`;
|
|
260
|
+
function repeatMessage(call, count, acrossTurns) {
|
|
261
|
+
const observed = acrossTurns
|
|
262
|
+
? `the same \`${call.tool}\` call, with identical arguments, ran in ${count} consecutive turns.`
|
|
263
|
+
: `the same \`${call.tool}\` call, with identical arguments, repeated ${count} times in a row.`;
|
|
264
|
+
return `Tool loop detected: ${observed}${SUGGESTED_ACTIONS}`;
|
|
265
|
+
}
|
|
266
|
+
function alternationMessage(a, b, count) {
|
|
267
|
+
const pair = a.tool === b.tool
|
|
268
|
+
? `\`${a.tool}\` with two different arguments`
|
|
269
|
+
: `\`${a.tool}\`, \`${b.tool}\``;
|
|
270
|
+
return (`Tool loop detected: two calls alternated ${count} times in a row ` +
|
|
271
|
+
`(${pair}), each call identical to its counterpart.` +
|
|
272
|
+
SUGGESTED_ACTIONS);
|
|
273
|
+
}
|
|
274
|
+
const NOT_A_LOOP = { isLoop: false, tool: "", count: 0, message: "", pattern: "" };
|
|
149
275
|
/**
|
|
150
|
-
* Detect a
|
|
151
|
-
*
|
|
152
|
-
* 1. Tail-run (intra-turn): checks the ordered `history` array for N
|
|
153
|
-
* consecutive same-tool calls. Catches the common `read*8` loop even
|
|
154
|
-
* when all calls happen in a single turn. This is the primary path;
|
|
155
|
-
* the test suite and the stateless detectToolLoopFromSequence share
|
|
156
|
-
* the same tail-run semantics.
|
|
157
|
-
*
|
|
158
|
-
* 2. Cross-turn (inter-turn): checks perTurn sets for the same tool
|
|
159
|
-
* appearing in N consecutive turns. Catches loops where the agent
|
|
160
|
-
* calls different tools but always returns to the same one.
|
|
276
|
+
* Detect a loop at the tail of a call sequence. Three shapes:
|
|
161
277
|
*
|
|
162
|
-
*
|
|
163
|
-
*
|
|
164
|
-
*
|
|
278
|
+
* 1. Repeat: one identity at the end of the history, TOOL_LOOP_THRESHOLD or
|
|
279
|
+
* more calls long. The common `read the same file 16 times` loop.
|
|
280
|
+
* 2. Alternation: two identities oscillating strictly (A,B,A,B,...) for
|
|
281
|
+
* TOOL_LOOP_THRESHOLD or more calls. Each call is distinct from the one
|
|
282
|
+
* before it, so only the whole-window shape names this as a loop.
|
|
283
|
+
* 3. Cross-turn: one identity present in TOOL_LOOP_THRESHOLD consecutive
|
|
284
|
+
* turns. Catches an agent that does other work in between but returns to
|
|
285
|
+
* the same call every turn.
|
|
165
286
|
*
|
|
166
|
-
*
|
|
167
|
-
*
|
|
287
|
+
* A tail of one tool name whose calls are all distinct is a chain of work and
|
|
288
|
+
* matches none of the three.
|
|
168
289
|
*/
|
|
169
290
|
export function detectToolLoop(state) {
|
|
170
|
-
// Cooldown gate. Only applies once we've fired at least once
|
|
291
|
+
// Cooldown gate. Only applies once we've fired at least once.
|
|
171
292
|
if (state.lastFiredAtTurn >= 0 &&
|
|
172
293
|
state.turnCount - state.lastFiredAtTurn < TOOL_LOOP_COOLDOWN_TURNS) {
|
|
173
|
-
return
|
|
294
|
+
return NOT_A_LOOP;
|
|
174
295
|
}
|
|
175
296
|
// If the agent used any intentional (metacognitive) tool anywhere in the
|
|
176
|
-
// recorded window, it is deliberately engaged, not stuck in a loop.
|
|
177
|
-
//
|
|
178
|
-
//
|
|
179
|
-
// verdict even when the tail still runs 16+ same-tool calls (the
|
|
180
|
-
// false-positive class the 16 threshold guards against).
|
|
297
|
+
// recorded window, it is deliberately engaged, not stuck in a loop. Applies
|
|
298
|
+
// to all three shapes; a think/verify/finalize inside the window kills the
|
|
299
|
+
// loop verdict even when the tail still repeats.
|
|
181
300
|
if (hasIntentionalToolInHistory(state.history) || hasIntentionalToolInTurns(state.perTurn)) {
|
|
182
|
-
return
|
|
301
|
+
return NOT_A_LOOP;
|
|
183
302
|
}
|
|
184
|
-
// Path 1: tail-run detection (ordered history) - count consecutive
|
|
185
|
-
// same-tool calls at the end of the history array. This matches the
|
|
186
|
-
// stateless detectToolLoopFromSequence semantics.
|
|
187
303
|
if (state.history.length >= TOOL_LOOP_THRESHOLD) {
|
|
188
|
-
const
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
304
|
+
const repeat = identityTailRun(state.history);
|
|
305
|
+
if (repeat && repeat.count >= TOOL_LOOP_THRESHOLD) {
|
|
306
|
+
return {
|
|
307
|
+
isLoop: true,
|
|
308
|
+
tool: repeat.call.tool,
|
|
309
|
+
count: repeat.count,
|
|
310
|
+
message: repeatMessage(repeat.call, repeat.count, false),
|
|
311
|
+
pattern: "repeat",
|
|
312
|
+
};
|
|
195
313
|
}
|
|
196
|
-
|
|
314
|
+
const alternation = alternationTailRun(state.history);
|
|
315
|
+
if (alternation && alternation.count >= TOOL_LOOP_THRESHOLD) {
|
|
197
316
|
return {
|
|
198
317
|
isLoop: true,
|
|
199
|
-
tool:
|
|
200
|
-
count,
|
|
201
|
-
message:
|
|
202
|
-
|
|
203
|
-
`1. Use \`think()\` tool to re-evaluate your approach\n` +
|
|
204
|
-
`2. Check if the problem has changed - you may be solving the wrong issue\n` +
|
|
205
|
-
`3. Consider breaking the task into smaller steps\n` +
|
|
206
|
-
`4. Use the \`memory()\` tool to find past solutions to similar problems`,
|
|
318
|
+
tool: alternation.a.tool,
|
|
319
|
+
count: alternation.count,
|
|
320
|
+
message: alternationMessage(alternation.a, alternation.b, alternation.count),
|
|
321
|
+
pattern: "alternation",
|
|
207
322
|
};
|
|
208
323
|
}
|
|
209
324
|
}
|
|
210
|
-
//
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
325
|
+
// Cross-turn: only relevant when the agent spans multiple turns. Empty
|
|
326
|
+
// turns are transparent: recordTurnEnd() opens the next turn, so the newest
|
|
327
|
+
// entry is empty at detection time by construction, and a turn that made no
|
|
328
|
+
// tool calls carries no evidence either way. A populated turn without the
|
|
329
|
+
// call ends the run.
|
|
330
|
+
const populated = state.perTurn.filter((turn) => turn.calls.length > 0);
|
|
331
|
+
if (populated.length >= 2) {
|
|
332
|
+
let best = null;
|
|
333
|
+
const seen = new Set();
|
|
334
|
+
for (const call of populated[0].calls) {
|
|
335
|
+
if (seen.has(call.identity))
|
|
336
|
+
continue;
|
|
337
|
+
seen.add(call.identity);
|
|
338
|
+
let turns = 0;
|
|
339
|
+
for (const turn of populated) {
|
|
340
|
+
if (turn.calls.some((c) => c.identity === call.identity))
|
|
341
|
+
turns++;
|
|
342
|
+
else
|
|
343
|
+
break;
|
|
224
344
|
}
|
|
345
|
+
if (!best || turns > best.turns)
|
|
346
|
+
best = { call, turns };
|
|
225
347
|
}
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
bestExclusive = counts.exclusiveTurns;
|
|
235
|
-
}
|
|
236
|
-
}
|
|
237
|
-
if (bestCount < TOOL_LOOP_THRESHOLD) {
|
|
238
|
-
return { isLoop: false, tool: "", count: 0, message: "" };
|
|
239
|
-
}
|
|
240
|
-
let consecutiveTurns = 0;
|
|
241
|
-
for (const turn of state.perTurn) {
|
|
242
|
-
if (turn.has(bestTool)) {
|
|
243
|
-
consecutiveTurns++;
|
|
244
|
-
}
|
|
245
|
-
else {
|
|
246
|
-
break;
|
|
348
|
+
if (best && best.turns >= TOOL_LOOP_THRESHOLD) {
|
|
349
|
+
return {
|
|
350
|
+
isLoop: true,
|
|
351
|
+
tool: best.call.tool,
|
|
352
|
+
count: best.turns,
|
|
353
|
+
message: repeatMessage(best.call, best.turns, true),
|
|
354
|
+
pattern: "cross-turn",
|
|
355
|
+
};
|
|
247
356
|
}
|
|
248
357
|
}
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
? ` In ${bestExclusive} of those turns, it was the only tool called.`
|
|
259
|
-
: ``) +
|
|
260
|
-
`\n\n**Suggested actions:**\n` +
|
|
261
|
-
`1. Use \`think()\` tool to re-evaluate your approach\n` +
|
|
262
|
-
`2. Check if the problem has changed - you may be solving the wrong issue\n` +
|
|
263
|
-
`3. Consider breaking the task into smaller steps\n` +
|
|
264
|
-
`4. Use the \`memory()\` tool to find past solutions to similar problems`,
|
|
265
|
-
};
|
|
358
|
+
return NOT_A_LOOP;
|
|
359
|
+
}
|
|
360
|
+
/** Narrow a ToolCallLike to a record, or null when it is a bare name. */
|
|
361
|
+
function asRecord(entry) {
|
|
362
|
+
if (typeof entry === "string")
|
|
363
|
+
return null;
|
|
364
|
+
if (!entry || typeof entry.tool !== "string" || typeof entry.identity !== "string")
|
|
365
|
+
return null;
|
|
366
|
+
return entry;
|
|
266
367
|
}
|
|
267
368
|
export function detectToolLoopFromSequence(sequence) {
|
|
268
369
|
if (sequence.length < TOOL_LOOP_THRESHOLD) {
|
|
269
|
-
return { isLoop: false, tool: "", count: 0, message: "" };
|
|
370
|
+
return { isLoop: false, tool: "", count: 0, message: "", pattern: "" };
|
|
270
371
|
}
|
|
271
|
-
// Cap to WINDOW so the check is consistent with the stateful path
|
|
372
|
+
// Cap to WINDOW so the check is consistent with the stateful path.
|
|
272
373
|
const windowed = sequence.length > TOOL_LOOP_WINDOW ? sequence.slice(-TOOL_LOOP_WINDOW) : sequence;
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
374
|
+
const records = [];
|
|
375
|
+
for (const entry of windowed) {
|
|
376
|
+
const record = asRecord(entry);
|
|
377
|
+
if (!record) {
|
|
378
|
+
// A bare name is not a call: no argument evidence, no identity.
|
|
379
|
+
return { isLoop: false, tool: "", count: 0, message: "", pattern: "" };
|
|
380
|
+
}
|
|
381
|
+
records.push(record);
|
|
278
382
|
}
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
count++;
|
|
284
|
-
else
|
|
285
|
-
break;
|
|
383
|
+
// Intentional-use filter: any metacognitive tool in the windowed slice means
|
|
384
|
+
// the agent is engaged, not stuck. Mirrors the stateful path.
|
|
385
|
+
if (hasIntentionalToolInHistory(records)) {
|
|
386
|
+
return { isLoop: false, tool: "", count: 0, message: "", pattern: "" };
|
|
286
387
|
}
|
|
287
|
-
|
|
288
|
-
|
|
388
|
+
const repeat = identityTailRun(records);
|
|
389
|
+
if (repeat && repeat.count >= TOOL_LOOP_THRESHOLD) {
|
|
390
|
+
return {
|
|
391
|
+
isLoop: true,
|
|
392
|
+
tool: repeat.call.tool,
|
|
393
|
+
count: repeat.count,
|
|
394
|
+
message: repeatMessage(repeat.call, repeat.count, false),
|
|
395
|
+
pattern: "repeat",
|
|
396
|
+
};
|
|
289
397
|
}
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
};
|
|
398
|
+
const alternation = alternationTailRun(records);
|
|
399
|
+
if (alternation && alternation.count >= TOOL_LOOP_THRESHOLD) {
|
|
400
|
+
return {
|
|
401
|
+
isLoop: true,
|
|
402
|
+
tool: alternation.a.tool,
|
|
403
|
+
count: alternation.count,
|
|
404
|
+
message: alternationMessage(alternation.a, alternation.b, alternation.count),
|
|
405
|
+
pattern: "alternation",
|
|
406
|
+
};
|
|
407
|
+
}
|
|
408
|
+
return { isLoop: false, tool: "", count: 0, message: "", pattern: "" };
|
|
301
409
|
}
|
|
302
410
|
//# sourceMappingURL=tool-loop-detector.js.map
|
|
@@ -8,6 +8,7 @@
|
|
|
8
8
|
* Not a cognitive simulation - a simple histogram-based predictor.
|
|
9
9
|
*/
|
|
10
10
|
import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
11
|
+
import type { ToolCallLike } from "../detection/tool-loop-detector.js";
|
|
11
12
|
export interface SimulatedPath {
|
|
12
13
|
sequence: string[];
|
|
13
14
|
probability: number;
|
|
@@ -31,7 +32,7 @@ export declare function simulatePaths(currentSequence: string[], historicalSeque
|
|
|
31
32
|
* Generate proactive advice from simulated paths.
|
|
32
33
|
* Only returns advice if a concerning path is detected with sufficient confidence.
|
|
33
34
|
*/
|
|
34
|
-
export declare function dream(ctx: ExtensionContext, currentSequence: string[], historicalSequences?: string[][]): DreamAdvice | null;
|
|
35
|
+
export declare function dream(ctx: ExtensionContext, currentSequence: string[], historicalSequences?: string[][], loopSequence?: ToolCallLike[]): DreamAdvice | null;
|
|
35
36
|
/** Reset dreamer state (for testing or session reset) */
|
|
36
37
|
export declare function resetDreamer(ctx: ExtensionContext): void;
|
|
37
38
|
//# sourceMappingURL=dreamer.d.ts.map
|
|
@@ -89,19 +89,24 @@ export function simulatePaths(currentSequence, historicalSequences = []) {
|
|
|
89
89
|
* Generate proactive advice from simulated paths.
|
|
90
90
|
* Only returns advice if a concerning path is detected with sufficient confidence.
|
|
91
91
|
*/
|
|
92
|
-
export function dream(ctx, currentSequence, historicalSequences) {
|
|
92
|
+
export function dream(ctx, currentSequence, historicalSequences, loopSequence) {
|
|
93
93
|
const state = getState(ctx);
|
|
94
94
|
const now = Date.now();
|
|
95
95
|
// Cooldown check - dynamic threshold adjusted by advice tracker feedback loop
|
|
96
96
|
if (now - state.lastDreamAt < dynamicCooldown)
|
|
97
97
|
return null;
|
|
98
98
|
// Path 1: detect a tool loop in the current sequence (consecutive-
|
|
99
|
-
// same-
|
|
100
|
-
// format are all owned by lib/detection/tool-loop-detector - the
|
|
101
|
-
// source of truth. Delegating avoids the contradictory-whisper
|
|
102
|
-
// separate detectors with separate thresholds firing in one turn
|
|
103
|
-
// the agent conflicting remedies.
|
|
104
|
-
|
|
99
|
+
// same-call heuristic). The threshold, window, cooldown, identity rule, and
|
|
100
|
+
// message format are all owned by lib/detection/tool-loop-detector - the
|
|
101
|
+
// single source of truth. Delegating avoids the contradictory-whisper
|
|
102
|
+
// failure: separate detectors with separate thresholds firing in one turn
|
|
103
|
+
// hand the agent conflicting remedies.
|
|
104
|
+
//
|
|
105
|
+
// loopSequence carries the recorded calls (name + argument identity). A
|
|
106
|
+
// caller that holds only the name log passes nothing, and the detector then
|
|
107
|
+
// returns no loop: names cannot show one call repeating, only one name
|
|
108
|
+
// repeating.
|
|
109
|
+
const loopResult = detectToolLoopFromSequence(loopSequence ?? currentSequence);
|
|
105
110
|
if (loopResult.isLoop) {
|
|
106
111
|
state.lastDreamAt = now;
|
|
107
112
|
return {
|
package/docs/LOCAL_DEV.md
CHANGED
|
@@ -138,7 +138,7 @@ before and after a full run. A non-zero delta is the leak this rule prevents.
|
|
|
138
138
|
### New fixtures: use `node:test`
|
|
139
139
|
|
|
140
140
|
A new fixture is written on `node:test`. The runner does not care which style a
|
|
141
|
-
file uses -
|
|
141
|
+
file uses - 93 of the core suite's 328 fixtures already use `node:test` - so the
|
|
142
142
|
reason is the failure the other style produces. A hand-rolled helper that calls
|
|
143
143
|
`fn()` without awaiting it discards the case's promise, so an `async` case runs
|
|
144
144
|
detached and the file can print its green tally before that case settles, with
|
package/docs/SETUP.md
CHANGED
|
@@ -313,6 +313,7 @@ The user-global file always exists; the project one is optional and belongs to p
|
|
|
313
313
|
| `braid.context.staleToolResultOffload` | object | OFF | Opt-in age/size offload of stale large tool results (defaults: `minChars` 4000, `stalenessTurns` 40, `keepRecentTurns` 20, `maxOffloadCharsPerRun` 65536). |
|
|
314
314
|
| `braid.context.contextEmergencyOffload` | object | ON | Emergency offload of the largest tool results when a context-window (413) error fires, then one retry (defaults: `minChars` 262144, `maxCharsPerRun` 1048576, `keepRecentTurns` 1). |
|
|
315
315
|
| `braid.skills.ranking` | `keyword`/`auto`/`model` | `keyword` | Tier policy for the `list_skills` relevance ranking. `keyword` (implemented): the deterministic scorer orders the rows and reports its own verdict (`unambiguous` / `tie` / `thin-margin` / `short-task` / `no-score` / `no-task`) with per-row `relevance {score, reason}`. `auto` and `model` are reserved for a model tier that would answer on an ambiguous verdict; it was measured against the scorer and not kept, so both evaluate to the keyword path and the read echoes the configured value as `ranking.policy`. An unknown value falls back to `keyword`. |
|
|
316
|
+
| `braid.skills.inform` | `off`/`inform` | `off` | At-use line. When `inform`, a completed call in a tool family a visible skill declares with `governs:` and no read of that body in the session emits one steer naming the file and the obligation, once per session per skill. It observes a call that already ran: it never refuses, delays or rewrites a tool result. Its conversion is reported by `skill_stats` (`inform.verdict`: `undecided` below 20 informs, `beats` when the lower Wilson bound clears the suggestion channel's 18.8%, `noise` otherwise). An unknown value falls back to `off`. |
|
|
316
317
|
| `braid.telegram.sendMaxChars` | positive number | `4096` | Plain-text cap for `telegram_send`, re-read per call. |
|
|
317
318
|
| `braid.telegram.notifyMaxChars` | positive number | `1200` | Craft target and guard for turn-end notifications. |
|
|
318
319
|
| `braid.telegram.pauseStateFile` | path string | built-in default | Override for the `/telegram` pause-state file path. |
|