pi-braid 0.43.7 → 0.43.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/CHANGELOG.md +72 -0
  2. package/TOOLS.md +1 -1
  3. package/build-info.json +4 -4
  4. package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
  5. package/dist/extensions/core/skills-tool/auto-inject.d.ts +21 -0
  6. package/dist/extensions/core/skills-tool/auto-inject.js +105 -1
  7. package/dist/extensions/core/skills-tool/index.js +20 -2
  8. package/dist/extensions/core/skills-tool/loading-guidance.d.ts +4 -1
  9. package/dist/extensions/core/skills-tool/loading-guidance.js +4 -1
  10. package/dist/extensions/core/skills-tool/session-records.d.ts +107 -9
  11. package/dist/extensions/core/skills-tool/session-records.js +141 -5
  12. package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +5 -1
  13. package/dist/extensions/enforcement/handlers/register-tool-call.js +5 -2
  14. package/dist/extensions/enforcement/verification-judge.d.ts +7 -0
  15. package/dist/extensions/enforcement/verification-judge.js +28 -21
  16. package/dist/extensions/memory/session-recall/ask.d.ts +95 -0
  17. package/dist/extensions/memory/session-recall/ask.js +376 -0
  18. package/dist/extensions/memory/session-recall/corpus-index.d.ts +200 -0
  19. package/dist/extensions/memory/session-recall/corpus-index.js +480 -0
  20. package/dist/extensions/memory/session-recall/index.js +173 -21
  21. package/dist/extensions/memory/session-recall/search.d.ts +29 -0
  22. package/dist/extensions/memory/session-recall/search.js +42 -9
  23. package/dist/lib/ai/payload-hygiene.d.ts +3 -0
  24. package/dist/lib/ai/payload-hygiene.js +34 -2
  25. package/dist/lib/config/braid-paths.d.ts +4 -0
  26. package/dist/lib/config/braid-paths.js +6 -0
  27. package/dist/lib/config/braid-settings.d.ts +44 -0
  28. package/dist/lib/config/braid-settings.js +41 -0
  29. package/dist/lib/detection/tool-loop-detector.d.ts +95 -46
  30. package/dist/lib/detection/tool-loop-detector.js +288 -180
  31. package/dist/lib/memory/constants.d.ts +38 -0
  32. package/dist/lib/memory/constants.js +196 -0
  33. package/dist/lib/memory/index.js +49 -10
  34. package/dist/lib/memory/lifecycle.d.ts +8 -0
  35. package/dist/lib/memory/lifecycle.js +43 -18
  36. package/dist/lib/reasoning/dreamer.d.ts +2 -1
  37. package/dist/lib/reasoning/dreamer.js +12 -7
  38. package/docs/LOCAL_DEV.md +1 -1
  39. package/docs/SETUP.md +2 -0
  40. package/package.json +1 -1
  41. package/src/extensions/core/AGENTS.md +3 -2
  42. package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
  43. package/src/extensions/core/skills-tool/auto-inject.ts +118 -1
  44. package/src/extensions/core/skills-tool/index.ts +21 -1
  45. package/src/extensions/core/skills-tool/loading-guidance.ts +4 -1
  46. package/src/extensions/core/skills-tool/session-records.ts +201 -9
  47. package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +5 -1
  48. package/src/extensions/enforcement/handlers/register-tool-call.ts +5 -2
  49. package/src/extensions/enforcement/verification-judge.ts +32 -25
  50. package/src/extensions/memory/AGENTS.md +2 -2
  51. package/src/extensions/memory/session-recall/AGENTS.md +92 -18
  52. package/src/extensions/memory/session-recall/ask.ts +435 -0
  53. package/src/extensions/memory/session-recall/corpus-index.ts +609 -0
  54. package/src/extensions/memory/session-recall/index.ts +202 -21
  55. package/src/extensions/memory/session-recall/search.ts +61 -10
  56. package/src/lib/ai/payload-hygiene.ts +47 -3
  57. package/src/lib/config/braid-paths.ts +7 -0
  58. package/src/lib/config/braid-settings.ts +93 -3
  59. package/src/lib/detection/AGENTS.md +8 -7
  60. package/src/lib/detection/tool-loop-detector.ts +339 -195
  61. package/src/lib/memory/constants.ts +202 -0
  62. package/src/lib/memory/index.ts +59 -8
  63. package/src/lib/memory/lifecycle.ts +50 -16
  64. 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 calling
3
- * the same tool repeatedly."
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 event handler
23
- * with the tool name.
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 same-tool calls
30
- * - TOOL_LOOP_WINDOW: 20 tools of history kept
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 real stuck loops without firing on heavy-but-productive
34
- * single-tool use (reading several files in succession); a lower
35
- * threshold false-positives on legitimate batch operations.
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 THIS file emits the loop/addiction whisper. If any intentional
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
- /** Minimum consecutive same-tool calls in the recent history to flag. */
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 tools to retain in the rolling window. Must be >= TOOL_LOOP_THRESHOLD + 1. */
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
- * Record a tool invocation. Call this from the tool_call event handler
97
- * with the tool name. Adds the tool to the current (most recent) turn's
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
- export function recordToolCall(state, toolName) {
101
- if (!toolName)
102
- return;
103
- if (state.perTurn.length === 0) {
104
- state.perTurn.push(new Set());
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
- state.perTurn[0].add(toolName);
107
- // Trim perTurn to keep tool counts within WINDOW
108
- let totalTools = 0;
109
- for (const turn of state.perTurn) {
110
- totalTools += turn.size;
111
- }
112
- while (totalTools > TOOL_LOOP_WINDOW && state.perTurn.length > 1) {
113
- const removed = state.perTurn.pop();
114
- totalTools -= removed.size;
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
- // Push to ordered history for tail-run detection
117
- state.history.push(toolName);
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(new Set());
132
- let totalTools = 0;
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 tool loop. Uses TWO detection paths:
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
- * Returns:
163
- * { isLoop: true, tool, count, message } when a loop is detected.
164
- * { isLoop: false, tool: "", count: 0, message: "" } otherwise.
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
- * The message is the unified whisper body. Consumers can either emit
167
- * it verbatim, customize it, or just observe the verdict.
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 { isLoop: false, tool: "", count: 0, message: "" };
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
- // Applies to BOTH detection paths (tail-run on `history` and cross-turn
178
- // on `perTurn`); a think/verify/finalize inside the window kills the loop
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 { isLoop: false, tool: "", count: 0, message: "" };
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 last = state.history[state.history.length - 1];
189
- let count = 1;
190
- for (let i = state.history.length - 2; i >= 0; i--) {
191
- if (state.history[i] === last)
192
- count++;
193
- else
194
- break;
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
- if (count >= TOOL_LOOP_THRESHOLD) {
314
+ const alternation = alternationTailRun(state.history);
315
+ if (alternation && alternation.count >= TOOL_LOOP_THRESHOLD) {
197
316
  return {
198
317
  isLoop: true,
199
- tool: last,
200
- count,
201
- message: `Tool loop detected: \`${last}\` called ${count} times in a row with no progress.` +
202
- `\n\n**Suggested actions:**\n` +
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
- // Only relevant when the agent spans multiple turns with the same tool.
211
- if (state.perTurn.length < 2) {
212
- return { isLoop: false, tool: "", count: 0, message: "" };
213
- }
214
- const toolTurnCounts = new Map();
215
- for (const turn of state.perTurn) {
216
- for (const tool of turn) {
217
- if (!toolTurnCounts.has(tool)) {
218
- toolTurnCounts.set(tool, { turnCount: 0, exclusiveTurns: 0 });
219
- }
220
- const entry = toolTurnCounts.get(tool);
221
- entry.turnCount++;
222
- if (turn.size === 1) {
223
- entry.exclusiveTurns++;
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
- let bestTool = "";
228
- let bestCount = 0;
229
- let bestExclusive = 0;
230
- for (const [tool, counts] of toolTurnCounts) {
231
- if (counts.turnCount > bestCount) {
232
- bestTool = tool;
233
- bestCount = counts.turnCount;
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
- if (consecutiveTurns < TOOL_LOOP_THRESHOLD) {
250
- return { isLoop: false, tool: "", count: 0, message: "" };
251
- }
252
- return {
253
- isLoop: true,
254
- tool: bestTool,
255
- count: consecutiveTurns,
256
- message: `Tool loop detected: \`${bestTool}\` called in ${consecutiveTurns} consecutive turns.` +
257
- (bestExclusive >= 2
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
- // Intentional-use filter: any metacognitive tool in the windowed
274
- // slice means the agent is engaged, not stuck — not a loop. Mirrors the
275
- // stateful detectToolLoop() so the dreamer's stateless path agrees with it.
276
- if (hasIntentionalToolInHistory(windowed)) {
277
- return { isLoop: false, tool: "", count: 0, message: "" };
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
- const last = windowed[windowed.length - 1];
280
- let count = 1;
281
- for (let i = windowed.length - 2; i >= 0; i--) {
282
- if (windowed[i] === last)
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
- if (count < TOOL_LOOP_THRESHOLD) {
288
- return { isLoop: false, tool: "", count: 0, message: "" };
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
- return {
291
- isLoop: true,
292
- tool: last,
293
- count,
294
- message: `Tool loop detected: \`${last}\` called ${count} times in a row with no progress.\n\n` +
295
- `**Suggested actions:**\n` +
296
- `1. Use \`think()\` tool to re-evaluate your approach\n` +
297
- `2. Check if the problem has changed - you may be solving the wrong issue\n` +
298
- `3. Consider breaking the task into smaller steps\n` +
299
- `4. Use the \`memory()\` tool to find past solutions to similar problems`,
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
@@ -7,5 +7,43 @@ export declare const MEMORY_FILE: string;
7
7
  export declare const MAX_ENTRIES = 200;
8
8
  export declare const MIN_UTILITY_THRESHOLD = 0.15;
9
9
  export declare const CONSOLIDATION_INTERVAL = 5;
10
+ /**
11
+ * Shortest token the matcher looks at. One- and two-character tokens carry no
12
+ * topic in any language this store sees, and matching them turns a query into
13
+ * a scan of nearly every entry.
14
+ */
15
+ export declare const QUERY_MIN_TOKEN_LENGTH = 3;
16
+ /**
17
+ * English function words, dropped from a query before matching. They name no
18
+ * topic, and counting each as a full word match is what let a long entry
19
+ * outrank a short quote that shared the question's actual subject.
20
+ *
21
+ * Generic vocabulary only. A word that names anything about this deployment,
22
+ * its files, or its roles belongs to that owner, not in a shared matcher.
23
+ */
24
+ export declare const QUERY_STOP_WORDS: ReadonlySet<string>;
25
+ /**
26
+ * What a query-named tag is worth, in matched-word units: two ordinary terms.
27
+ * The shipped matcher counted a word as 1 and a tag as 2, so 2 keeps the
28
+ * shipped meaning now that a word's weight is a rarity weight instead.
29
+ */
30
+ export declare const MEMORY_TAG_BONUS_WORDS = 2;
31
+ /**
32
+ * Document-frequency fraction that fixes the "ordinary term" the weights are
33
+ * expressed in: a token carried by this share of the store. At 0.5 the
34
+ * reference weight is ln(1 + 1 / 0.5) = ln 3, and a tag is worth
35
+ * MEMORY_TAG_BONUS_WORDS of those.
36
+ */
37
+ export declare const MEMORY_REFERENCE_DF_FRACTION = 0.5;
38
+ /**
39
+ * Defaults for `braid.memory.reservedProvenance`. The partition ships OFF:
40
+ * which entries carry a provenance class is a property of the writer that
41
+ * filed them, so the operator names it with a source prefix. An empty prefix
42
+ * and a zero slot count both mean "no partition", leaving the prune as it was.
43
+ */
44
+ export declare const RESERVED_PROVENANCE_DEFAULTS: {
45
+ readonly prefix: "";
46
+ readonly slots: 0;
47
+ };
10
48
  export declare const CATEGORY_BASE_UTILITY: Record<CognitiveMemoryType, number>;
11
49
  //# sourceMappingURL=constants.d.ts.map