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.
- package/CHANGELOG.md +72 -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 +44 -0
- package/dist/lib/config/braid-settings.js +41 -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/memory/constants.d.ts +38 -0
- package/dist/lib/memory/constants.js +196 -0
- package/dist/lib/memory/index.js +49 -10
- package/dist/lib/memory/lifecycle.d.ts +8 -0
- package/dist/lib/memory/lifecycle.js +43 -18
- 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 +2 -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 +93 -3
- package/src/lib/detection/AGENTS.md +8 -7
- package/src/lib/detection/tool-loop-detector.ts +339 -195
- package/src/lib/memory/constants.ts +202 -0
- package/src/lib/memory/index.ts +59 -8
- package/src/lib/memory/lifecycle.ts +50 -16
- 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,50 +60,85 @@
|
|
|
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 type { ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
47
|
-
/** Minimum consecutive same-
|
|
69
|
+
/** Minimum consecutive same-identity calls (or turns) in the recent history to flag. */
|
|
48
70
|
export declare const TOOL_LOOP_THRESHOLD = 16;
|
|
49
|
-
/** How many recent
|
|
71
|
+
/** How many recent calls to retain in the rolling window. Must be >= TOOL_LOOP_THRESHOLD + 1. */
|
|
50
72
|
export declare const TOOL_LOOP_WINDOW = 20;
|
|
51
73
|
/** Minimum turns between successive loop whispers. */
|
|
52
74
|
export declare const TOOL_LOOP_COOLDOWN_TURNS = 8;
|
|
75
|
+
/** How many turns of per-turn history to retain. A cross-turn loop needs
|
|
76
|
+
* TOOL_LOOP_THRESHOLD consecutive turns, so the bound is turn-shaped rather
|
|
77
|
+
* than call-shaped: bounding the total call count would evict the older turns
|
|
78
|
+
* of a busy agent and hide the very run the cross-turn shape looks for. Each
|
|
79
|
+
* turn's own call list is bounded by TOOL_LOOP_WINDOW. */
|
|
80
|
+
export declare const TOOL_TURN_WINDOW: number;
|
|
81
|
+
/** One recorded call: the tool, and the equality key for its arguments. */
|
|
82
|
+
export interface ToolCallRecord {
|
|
83
|
+
tool: string;
|
|
84
|
+
identity: string;
|
|
85
|
+
}
|
|
86
|
+
/** A call to score, or a bare tool name. A bare name is what a caller has when
|
|
87
|
+
* it kept only names (the dreamer's historical log): it carries no argument
|
|
88
|
+
* evidence, so it cannot show that two calls are the same call. See
|
|
89
|
+
* detectToolLoopFromSequence for what that rules out. */
|
|
90
|
+
export type ToolCallLike = string | ToolCallRecord;
|
|
91
|
+
/** One turn's recorded calls, most recent turn first in ToolLoopState.perTurn. */
|
|
92
|
+
export interface ToolTurn {
|
|
93
|
+
/** Tool names seen in this turn - what the intentional-use filter reads. */
|
|
94
|
+
tools: Set<string>;
|
|
95
|
+
/** This turn's calls, oldest first, capped at TOOL_LOOP_WINDOW. */
|
|
96
|
+
calls: ToolCallRecord[];
|
|
97
|
+
}
|
|
53
98
|
export interface ToolLoopState {
|
|
54
|
-
/**
|
|
55
|
-
*
|
|
56
|
-
*
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
*
|
|
61
|
-
|
|
62
|
-
* shifted when exceeding WINDOW. */
|
|
63
|
-
history: string[];
|
|
99
|
+
/** Calls per turn, most recent turn first. Turn boundaries are kept so a
|
|
100
|
+
* cross-turn loop (the same call every turn) can be scored separately from
|
|
101
|
+
* an intra-turn repeat, whose window spans the flat history below. */
|
|
102
|
+
perTurn: ToolTurn[];
|
|
103
|
+
/** Ordered flat history of the last TOOL_LOOP_WINDOW calls. Used for
|
|
104
|
+
* identity-run detection: consecutive calls that are the same call,
|
|
105
|
+
* whether within one turn or across turns. */
|
|
106
|
+
history: ToolCallRecord[];
|
|
64
107
|
/** Turn index when we last emitted a loop whisper. -1 if never. */
|
|
65
108
|
lastFiredAtTurn: number;
|
|
66
109
|
/** Monotonically increasing turn counter for cooldown math. */
|
|
67
110
|
turnCount: number;
|
|
68
111
|
}
|
|
112
|
+
/** Which shape of repetition produced the verdict. */
|
|
113
|
+
export type ToolLoopPattern = "repeat" | "alternation" | "cross-turn" | "";
|
|
69
114
|
export interface ToolLoopResult {
|
|
70
115
|
isLoop: boolean;
|
|
71
116
|
tool: string;
|
|
72
117
|
count: number;
|
|
73
118
|
message: string;
|
|
119
|
+
pattern: ToolLoopPattern;
|
|
74
120
|
}
|
|
75
121
|
export declare function createToolLoopState(): ToolLoopState;
|
|
76
122
|
export declare function getToolLoopState(ctx: ExtensionContext): ToolLoopState;
|
|
77
123
|
/**
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
* tool
|
|
124
|
+
* Build the equality key for one tool call: the tool name plus its normalized
|
|
125
|
+
* arguments. Two calls share an identity exactly when they are the same call -
|
|
126
|
+
* same tool, same arguments - which is what "the agent repeated itself" means.
|
|
127
|
+
*
|
|
128
|
+
* A call whose arguments are absent or empty is identified by its name alone;
|
|
129
|
+
* there is no argument evidence to distinguish it from another call of the
|
|
130
|
+
* same tool, so they count as the same call.
|
|
131
|
+
*/
|
|
132
|
+
export declare function toolCallIdentity(toolName: string, input?: unknown): string;
|
|
133
|
+
/**
|
|
134
|
+
* Record a tool invocation. Call this from the tool_call event handler with
|
|
135
|
+
* the tool name and its arguments. Adds the call to the current (most recent)
|
|
136
|
+
* turn. If no turn has started yet, creates one.
|
|
81
137
|
*/
|
|
82
|
-
export declare function recordToolCall(state: ToolLoopState, toolName: string): void;
|
|
138
|
+
export declare function recordToolCall(state: ToolLoopState, toolName: string, input?: unknown): void;
|
|
83
139
|
/**
|
|
84
140
|
* Record the end of a turn. Call this from the turn_end handler to
|
|
85
141
|
* bump the counter and open a new turn for the next round of tool calls.
|
|
86
|
-
* Pushes a fresh perTurn entry so the next recordToolCall adds to the new
|
|
87
|
-
* turn's set. History rotation happens in recordToolCall; perTurn entries
|
|
88
|
-
* are trimmed to TOOL_LOOP_WINDOW here.
|
|
89
142
|
*/
|
|
90
143
|
export declare function recordTurnEnd(state: ToolLoopState): void;
|
|
91
144
|
/**
|
|
@@ -95,24 +148,19 @@ export declare function recordTurnEnd(state: ToolLoopState): void;
|
|
|
95
148
|
*/
|
|
96
149
|
export declare function markLoopFired(state: ToolLoopState): void;
|
|
97
150
|
/**
|
|
98
|
-
* Detect a
|
|
99
|
-
*
|
|
100
|
-
* 1. Tail-run (intra-turn): checks the ordered `history` array for N
|
|
101
|
-
* consecutive same-tool calls. Catches the common `read*8` loop even
|
|
102
|
-
* when all calls happen in a single turn. This is the primary path;
|
|
103
|
-
* the test suite and the stateless detectToolLoopFromSequence share
|
|
104
|
-
* the same tail-run semantics.
|
|
105
|
-
*
|
|
106
|
-
* 2. Cross-turn (inter-turn): checks perTurn sets for the same tool
|
|
107
|
-
* appearing in N consecutive turns. Catches loops where the agent
|
|
108
|
-
* calls different tools but always returns to the same one.
|
|
151
|
+
* Detect a loop at the tail of a call sequence. Three shapes:
|
|
109
152
|
*
|
|
110
|
-
*
|
|
111
|
-
*
|
|
112
|
-
*
|
|
153
|
+
* 1. Repeat: one identity at the end of the history, TOOL_LOOP_THRESHOLD or
|
|
154
|
+
* more calls long. The common `read the same file 16 times` loop.
|
|
155
|
+
* 2. Alternation: two identities oscillating strictly (A,B,A,B,...) for
|
|
156
|
+
* TOOL_LOOP_THRESHOLD or more calls. Each call is distinct from the one
|
|
157
|
+
* before it, so only the whole-window shape names this as a loop.
|
|
158
|
+
* 3. Cross-turn: one identity present in TOOL_LOOP_THRESHOLD consecutive
|
|
159
|
+
* turns. Catches an agent that does other work in between but returns to
|
|
160
|
+
* the same call every turn.
|
|
113
161
|
*
|
|
114
|
-
*
|
|
115
|
-
*
|
|
162
|
+
* A tail of one tool name whose calls are all distinct is a chain of work and
|
|
163
|
+
* matches none of the three.
|
|
116
164
|
*/
|
|
117
165
|
export declare function detectToolLoop(state: ToolLoopState): ToolLoopResult;
|
|
118
166
|
export interface StatelessLoopResult {
|
|
@@ -120,6 +168,7 @@ export interface StatelessLoopResult {
|
|
|
120
168
|
tool: string;
|
|
121
169
|
count: number;
|
|
122
170
|
message: string;
|
|
171
|
+
pattern: ToolLoopPattern;
|
|
123
172
|
}
|
|
124
|
-
export declare function detectToolLoopFromSequence(sequence:
|
|
173
|
+
export declare function detectToolLoopFromSequence(sequence: ToolCallLike[]): StatelessLoopResult;
|
|
125
174
|
//# sourceMappingURL=tool-loop-detector.d.ts.map
|