pi-braid 0.40.3 → 0.40.6
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/AGENTS.md +17 -18
- package/README.md +116 -130
- package/TOOLS.md +35 -35
- package/build-info.json +4 -4
- package/dist/extensions/core/agent-environment/index.js +4 -3
- package/dist/extensions/core/prompt-builder/index.js +12 -7
- package/dist/extensions/core/prompt-builder/instance-composition.d.ts +51 -10
- package/dist/extensions/core/prompt-builder/instance-composition.js +87 -14
- package/dist/extensions/core/prompt-builder/system-info-tool.d.ts +3 -3
- package/dist/extensions/core/prompt-builder/system-info-tool.js +3 -3
- package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +178 -17
- package/dist/extensions/core/skills-tool/auto-inject.js +264 -23
- package/dist/extensions/core/skills-tool/index.d.ts +70 -2
- package/dist/extensions/core/skills-tool/index.js +149 -15
- package/dist/extensions/core/skills-tool/reach.d.ts +119 -0
- package/dist/extensions/core/skills-tool/reach.js +213 -0
- package/dist/extensions/core/skills-tool/skill-triggers.d.ts +74 -13
- package/dist/extensions/core/skills-tool/skill-triggers.js +105 -24
- package/dist/extensions/enforcement/handlers/register-session-compact.js +12 -1
- package/dist/extensions/enforcement/handlers/register-session-shutdown-resumption.js +15 -34
- package/dist/extensions/enforcement/handlers/register-session-start-discoverability.d.ts +2 -1
- package/dist/extensions/enforcement/handlers/register-session-start-discoverability.js +55 -28
- package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.d.ts +14 -10
- package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +88 -82
- package/dist/extensions/enforcement/resume-state.d.ts +76 -0
- package/dist/extensions/enforcement/resume-state.js +90 -0
- package/dist/extensions/enforcement/substate/context-hygiene-state.d.ts +9 -0
- package/dist/extensions/enforcement/substate/context-hygiene-state.js +8 -0
- package/dist/extensions/enforcement/whisper.d.ts +12 -0
- package/dist/extensions/enforcement/whisper.js +16 -1
- package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +14 -6
- package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +7 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +372 -0
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +8 -2
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +54 -21
- package/dist/lib/config/braid-paths.d.ts +14 -0
- package/dist/lib/config/braid-paths.js +18 -0
- package/dist/lib/config/braid-settings.d.ts +21 -0
- package/dist/lib/config/braid-settings.js +16 -0
- package/dist/lib/detection/context-tiers.d.ts +47 -3
- package/dist/lib/detection/context-tiers.js +122 -13
- package/dist/lib/events/turn-boundary.d.ts +78 -0
- package/dist/lib/events/turn-boundary.js +91 -0
- package/dist/lib/orchestrator/workers.d.ts +3 -2
- package/dist/lib/orchestrator/workers.js +22 -4
- package/dist/lib/state/global-state.d.ts +1 -1
- package/docs/CONTEXT-POLICY.md +8 -0
- package/docs/LOCAL_DEV.md +0 -1
- package/docs/ROADMAP.md +5 -5
- package/docs/SETUP.md +19 -18
- package/package.json +2 -1
- package/skills/herdr-topology/SKILL.md +6 -1
- package/skills/research/SKILL.md +32 -0
- package/skills/subagent-orchestration/SKILL.md +2 -2
- package/src/extensions/core/agent-environment/index.ts +4 -3
- package/src/extensions/core/prompt-builder/AGENTS.md +8 -4
- package/src/extensions/core/prompt-builder/index.ts +12 -7
- package/src/extensions/core/prompt-builder/instance-composition.ts +98 -14
- package/src/extensions/core/prompt-builder/system-info-tool.ts +3 -3
- package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
- package/src/extensions/core/skills-tool/auto-inject.ts +350 -27
- package/src/extensions/core/skills-tool/index.ts +217 -15
- package/src/extensions/core/skills-tool/reach.ts +256 -0
- package/src/extensions/core/skills-tool/skill-triggers.ts +130 -23
- package/src/extensions/enforcement/handlers/register-session-compact.ts +12 -1
- package/src/extensions/enforcement/handlers/register-session-shutdown-resumption.ts +23 -36
- package/src/extensions/enforcement/handlers/register-session-start-discoverability.ts +59 -29
- package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +101 -81
- package/src/extensions/enforcement/resume-state.ts +127 -0
- package/src/extensions/enforcement/substate/context-hygiene-state.ts +17 -0
- package/src/extensions/enforcement/whisper.ts +21 -1
- package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +20 -5
- package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +370 -0
- package/src/extensions/memory/AGENTS.md +25 -1
- package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +80 -27
- package/src/lib/config/braid-paths.ts +20 -0
- package/src/lib/config/braid-settings.ts +46 -0
- package/src/lib/detection/context-tiers.ts +186 -13
- package/src/lib/events/AGENTS.md +1 -0
- package/src/lib/events/turn-boundary.ts +115 -0
- package/src/lib/orchestrator/workers.ts +33 -12
- package/src/lib/state/global-state.ts +1 -0
- package/src/lib/utils/AGENTS.md +1 -1
- package/src/types/extension-context.d.ts +22 -79
|
@@ -44,6 +44,376 @@ export const WEB_TOOLS = new Set(["fetch_content", "browser_navigate", "browser_
|
|
|
44
44
|
|
|
45
45
|
export const CODE_TOOLS = new Set(["bash", "write", "edit"]);
|
|
46
46
|
|
|
47
|
+
// ═══════════════════════════════════════════════════════════════════════════
|
|
48
|
+
// VERIFICATION-SHAPE RECOGNITION FOR BASH
|
|
49
|
+
// ═══════════════════════════════════════════════════════════════════════════
|
|
50
|
+
// VERIFICATION_TOOLS is a tool-NAME set, and the same work routinely runs
|
|
51
|
+
// through bash: `grep -rn "needle" src`, `git diff main...HEAD`, `node -e
|
|
52
|
+
// 'console.log(m.x)'`. The set cannot see it, so the verification counter
|
|
53
|
+
// stayed at zero while the agent verified and the hint below told the agent it
|
|
54
|
+
// had not verified in ten turns. Counting every bash call would swing the
|
|
55
|
+
// defect the other way — an edit, a build or a publish script is not
|
|
56
|
+
// verification, and a counter that accepts them silences the hint it exists to
|
|
57
|
+
// raise.
|
|
58
|
+
//
|
|
59
|
+
// The rule, in one sentence: a command counts when it puts an inspecting
|
|
60
|
+
// program at a program position and no mutating program anywhere.
|
|
61
|
+
// - program positions are the first word of each `;` `&&` `||` `|` `&`
|
|
62
|
+
// segment, tokenized quote-aware (`grep -n "a|b" f` is one segment);
|
|
63
|
+
// - inspecting: search/locate, read, compare/extract programs, git read
|
|
64
|
+
// subcommands, and an inline interpreter probe (`node -e`, `python -c`)
|
|
65
|
+
// whose script shows no write primitive;
|
|
66
|
+
// - mutating: rm/mv/cp/mkdir/tee/dd/chmod…, `sed -i`, `perl -i`, git write
|
|
67
|
+
// subcommands, and any unquoted redirect to a file other than /dev/null.
|
|
68
|
+
// Both directions matter: the two named holes are an interpreter script that
|
|
69
|
+
// writes through a primitive outside INLINE_WRITE_RE, and a mutating program
|
|
70
|
+
// behind `eval` or a heredoc body (both are read as inspection when the same
|
|
71
|
+
// command also inspects — they are listed here rather than guessed at).
|
|
72
|
+
|
|
73
|
+
/** Programs that inspect existing state: search, locate, read, compare, extract. */
|
|
74
|
+
const INSPECT_PROGRAMS = new Set([
|
|
75
|
+
"grep",
|
|
76
|
+
"egrep",
|
|
77
|
+
"fgrep",
|
|
78
|
+
"rg",
|
|
79
|
+
"ag",
|
|
80
|
+
"ack",
|
|
81
|
+
"ack-grep",
|
|
82
|
+
"ugrep",
|
|
83
|
+
"pcregrep",
|
|
84
|
+
"find",
|
|
85
|
+
"fd",
|
|
86
|
+
"fdfind",
|
|
87
|
+
"locate",
|
|
88
|
+
"cat",
|
|
89
|
+
"tac",
|
|
90
|
+
"head",
|
|
91
|
+
"tail",
|
|
92
|
+
"bat",
|
|
93
|
+
"less",
|
|
94
|
+
"more",
|
|
95
|
+
"wc",
|
|
96
|
+
"nl",
|
|
97
|
+
"od",
|
|
98
|
+
"xxd",
|
|
99
|
+
"strings",
|
|
100
|
+
"file",
|
|
101
|
+
"stat",
|
|
102
|
+
"ls",
|
|
103
|
+
"tree",
|
|
104
|
+
"realpath",
|
|
105
|
+
"readlink",
|
|
106
|
+
"jq",
|
|
107
|
+
"yq",
|
|
108
|
+
"diff",
|
|
109
|
+
"diff3",
|
|
110
|
+
"cmp",
|
|
111
|
+
"comm",
|
|
112
|
+
"cut",
|
|
113
|
+
"uniq",
|
|
114
|
+
"tr",
|
|
115
|
+
"column",
|
|
116
|
+
"awk",
|
|
117
|
+
"gawk",
|
|
118
|
+
"sed",
|
|
119
|
+
]);
|
|
120
|
+
|
|
121
|
+
/** Programs that mutate the tree. Any one of them vetoes the call. */
|
|
122
|
+
const MUTATE_PROGRAMS = new Set([
|
|
123
|
+
"rm",
|
|
124
|
+
"rmdir",
|
|
125
|
+
"mv",
|
|
126
|
+
"cp",
|
|
127
|
+
"ln",
|
|
128
|
+
"touch",
|
|
129
|
+
"mkdir",
|
|
130
|
+
"install",
|
|
131
|
+
"truncate",
|
|
132
|
+
"dd",
|
|
133
|
+
"shred",
|
|
134
|
+
"tee",
|
|
135
|
+
"patch",
|
|
136
|
+
"chmod",
|
|
137
|
+
"chown",
|
|
138
|
+
"chgrp",
|
|
139
|
+
]);
|
|
140
|
+
|
|
141
|
+
/**
|
|
142
|
+
* `git` subcommands that only read (the inspection side of the verbs the
|
|
143
|
+
* destructive gate covers separately).
|
|
144
|
+
*/
|
|
145
|
+
const GIT_READ_SUBS = new Set([
|
|
146
|
+
"diff",
|
|
147
|
+
"diff-tree",
|
|
148
|
+
"diff-index",
|
|
149
|
+
"diff-files",
|
|
150
|
+
"show",
|
|
151
|
+
"log",
|
|
152
|
+
"status",
|
|
153
|
+
"grep",
|
|
154
|
+
"blame",
|
|
155
|
+
"shortlog",
|
|
156
|
+
"whatchanged",
|
|
157
|
+
"ls-files",
|
|
158
|
+
"ls-tree",
|
|
159
|
+
"cat-file",
|
|
160
|
+
"rev-parse",
|
|
161
|
+
"rev-list",
|
|
162
|
+
"show-ref",
|
|
163
|
+
"for-each-ref",
|
|
164
|
+
"describe",
|
|
165
|
+
"merge-base",
|
|
166
|
+
"name-rev",
|
|
167
|
+
"count-objects",
|
|
168
|
+
"fsck",
|
|
169
|
+
]);
|
|
170
|
+
|
|
171
|
+
/** `git` subcommands that write. Conservative: a remote/config/branch/tag
|
|
172
|
+
* verb may mutate, so it vetoes rather than counts. */
|
|
173
|
+
const GIT_WRITE_SUBS = new Set([
|
|
174
|
+
"add",
|
|
175
|
+
"commit",
|
|
176
|
+
"push",
|
|
177
|
+
"pull",
|
|
178
|
+
"fetch",
|
|
179
|
+
"checkout",
|
|
180
|
+
"switch",
|
|
181
|
+
"restore",
|
|
182
|
+
"reset",
|
|
183
|
+
"revert",
|
|
184
|
+
"merge",
|
|
185
|
+
"rebase",
|
|
186
|
+
"cherry-pick",
|
|
187
|
+
"stash",
|
|
188
|
+
"apply",
|
|
189
|
+
"am",
|
|
190
|
+
"clean",
|
|
191
|
+
"rm",
|
|
192
|
+
"mv",
|
|
193
|
+
"tag",
|
|
194
|
+
"branch",
|
|
195
|
+
"init",
|
|
196
|
+
"clone",
|
|
197
|
+
"config",
|
|
198
|
+
"remote",
|
|
199
|
+
"submodule",
|
|
200
|
+
"worktree",
|
|
201
|
+
"update-index",
|
|
202
|
+
"update-ref",
|
|
203
|
+
"symbolic-ref",
|
|
204
|
+
"notes",
|
|
205
|
+
"gc",
|
|
206
|
+
"prune",
|
|
207
|
+
"reflog",
|
|
208
|
+
]);
|
|
209
|
+
|
|
210
|
+
/** Interpreters whose inline-eval form can be a probe. */
|
|
211
|
+
const INLINE_INTERPRETERS = new Set(["node", "deno", "bun", "python", "python3", "ruby"]);
|
|
212
|
+
|
|
213
|
+
/** Write primitives inside an inline script (both JS/TS and Python spellings). */
|
|
214
|
+
const INLINE_WRITE_RE =
|
|
215
|
+
/writeFileSync|writeFile\(|appendFileSync|createWriteStream|rmSync|unlinkSync|renameSync|mkdirSync|copyFileSync|truncateSync|chmodSync|openSync\([^)]*["'`][wa]|os\.remove|os\.rename|shutil\.|open\([^)]*["'`][wa]/;
|
|
216
|
+
|
|
217
|
+
/** Wrappers whose presence does not decide the kind of the segment. */
|
|
218
|
+
const WRAPPER_PROGRAMS = new Set(["sudo", "env", "time", "nice", "command", "nohup"]);
|
|
219
|
+
|
|
220
|
+
/** Tokens that end one command segment. */
|
|
221
|
+
const SEGMENT_SEPARATORS = new Set([";", "&&", "||", "|", "&", "\n"]);
|
|
222
|
+
|
|
223
|
+
/** The program name without its path (`/usr/bin/grep` → `grep`). */
|
|
224
|
+
function baseName(token: string): string {
|
|
225
|
+
const parts = token.split("/");
|
|
226
|
+
return parts[parts.length - 1] ?? token;
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
/**
|
|
230
|
+
* Quote-aware tokenizer that keeps shell operators as their own tokens
|
|
231
|
+
* (`;` `&&` `||` `|` `&` newline `>` `>>`, and `&1`/`&2` as one token) and
|
|
232
|
+
* strips quote characters. An escaped character stays literal, so `find …
|
|
233
|
+
* -exec grep … \;` yields the word `;` rather than a separator.
|
|
234
|
+
*/
|
|
235
|
+
function tokenizeCommand(command: string): string[] {
|
|
236
|
+
const tokens: string[] = [];
|
|
237
|
+
let cur = "";
|
|
238
|
+
let quote: '"' | "'" | null = null;
|
|
239
|
+
const flush = (): void => {
|
|
240
|
+
if (cur) {
|
|
241
|
+
tokens.push(cur);
|
|
242
|
+
cur = "";
|
|
243
|
+
}
|
|
244
|
+
};
|
|
245
|
+
for (let i = 0; i < command.length; i++) {
|
|
246
|
+
const ch = command[i] ?? "";
|
|
247
|
+
if (quote) {
|
|
248
|
+
if (ch === "\\" && quote === '"') {
|
|
249
|
+
cur += command[i + 1] ?? "";
|
|
250
|
+
i++;
|
|
251
|
+
continue;
|
|
252
|
+
}
|
|
253
|
+
if (ch === quote) {
|
|
254
|
+
quote = null;
|
|
255
|
+
continue;
|
|
256
|
+
}
|
|
257
|
+
cur += ch;
|
|
258
|
+
continue;
|
|
259
|
+
}
|
|
260
|
+
if (ch === "\\") {
|
|
261
|
+
cur += command[i + 1] ?? "";
|
|
262
|
+
i++;
|
|
263
|
+
continue;
|
|
264
|
+
}
|
|
265
|
+
if (ch === '"' || ch === "'") {
|
|
266
|
+
quote = ch;
|
|
267
|
+
continue;
|
|
268
|
+
}
|
|
269
|
+
if (/\s/.test(ch)) {
|
|
270
|
+
flush();
|
|
271
|
+
if (ch === "\n") tokens.push("\n");
|
|
272
|
+
continue;
|
|
273
|
+
}
|
|
274
|
+
if (ch === ";" || ch === "&") {
|
|
275
|
+
flush();
|
|
276
|
+
const next = command[i + 1] ?? "";
|
|
277
|
+
if (ch === "&" && /\d/.test(next)) {
|
|
278
|
+
tokens.push(`&${next}`);
|
|
279
|
+
i++;
|
|
280
|
+
continue;
|
|
281
|
+
}
|
|
282
|
+
if (ch === "&" && next === "&") {
|
|
283
|
+
tokens.push("&&");
|
|
284
|
+
i++;
|
|
285
|
+
continue;
|
|
286
|
+
}
|
|
287
|
+
tokens.push(ch);
|
|
288
|
+
continue;
|
|
289
|
+
}
|
|
290
|
+
if (ch === "|") {
|
|
291
|
+
flush();
|
|
292
|
+
if ((command[i + 1] ?? "") === "|") {
|
|
293
|
+
tokens.push("||");
|
|
294
|
+
i++;
|
|
295
|
+
continue;
|
|
296
|
+
}
|
|
297
|
+
tokens.push("|");
|
|
298
|
+
continue;
|
|
299
|
+
}
|
|
300
|
+
if (ch === ">") {
|
|
301
|
+
flush();
|
|
302
|
+
if ((command[i + 1] ?? "") === ">") {
|
|
303
|
+
tokens.push(">>");
|
|
304
|
+
i++;
|
|
305
|
+
continue;
|
|
306
|
+
}
|
|
307
|
+
tokens.push(">");
|
|
308
|
+
continue;
|
|
309
|
+
}
|
|
310
|
+
cur += ch;
|
|
311
|
+
}
|
|
312
|
+
flush();
|
|
313
|
+
return tokens;
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
/** Split tokenized commands into segments at the separators. */
|
|
317
|
+
function splitSegments(tokens: string[]): string[][] {
|
|
318
|
+
const out: string[][] = [];
|
|
319
|
+
let cur: string[] = [];
|
|
320
|
+
for (const token of tokens) {
|
|
321
|
+
if (SEGMENT_SEPARATORS.has(token)) {
|
|
322
|
+
if (cur.length > 0) out.push(cur);
|
|
323
|
+
cur = [];
|
|
324
|
+
continue;
|
|
325
|
+
}
|
|
326
|
+
cur.push(token);
|
|
327
|
+
}
|
|
328
|
+
if (cur.length > 0) out.push(cur);
|
|
329
|
+
return out;
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
/**
|
|
333
|
+
* A redirect that writes a real file. `/dev/null` and fd duplications
|
|
334
|
+
* (`2>&1`) are the ordinary shapes of a silent inspection and stay benign — a
|
|
335
|
+
* redirect into a path is a write, whatever program it follows.
|
|
336
|
+
*/
|
|
337
|
+
function writesFile(tokens: string[]): boolean {
|
|
338
|
+
for (let i = 0; i < tokens.length; i++) {
|
|
339
|
+
const token = tokens[i];
|
|
340
|
+
if (token !== ">" && token !== ">>") continue;
|
|
341
|
+
const target = tokens[i + 1];
|
|
342
|
+
if (!target || SEGMENT_SEPARATORS.has(target)) continue;
|
|
343
|
+
if (/^\/dev\/(?:null|stdout|stderr)$/.test(target)) continue;
|
|
344
|
+
if (/^&\d$/.test(target)) continue;
|
|
345
|
+
return true;
|
|
346
|
+
}
|
|
347
|
+
return false;
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
/** The first argument that is not a flag (`xargs -I{} rm` → `rm`). */
|
|
351
|
+
function firstArgument(args: string[]): string | null {
|
|
352
|
+
for (const arg of args) if (!arg.startsWith("-")) return arg;
|
|
353
|
+
return null;
|
|
354
|
+
}
|
|
355
|
+
|
|
356
|
+
/** Classify one segment by the program in its program position. */
|
|
357
|
+
function classifySegment(tokens: string[]): "inspect" | "mutate" | "neutral" {
|
|
358
|
+
let i = 0;
|
|
359
|
+
while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i] ?? "")) i++;
|
|
360
|
+
while (i < tokens.length && WRAPPER_PROGRAMS.has(baseName(tokens[i] ?? ""))) i++;
|
|
361
|
+
const program = tokens[i] ? baseName(tokens[i] as string) : "";
|
|
362
|
+
if (!program) return "neutral";
|
|
363
|
+
const args = tokens.slice(i + 1);
|
|
364
|
+
|
|
365
|
+
if (MUTATE_PROGRAMS.has(program)) return "mutate";
|
|
366
|
+
// xargs runs its first non-flag argument: classify the thing it runs.
|
|
367
|
+
if (program === "xargs") {
|
|
368
|
+
const target = firstArgument(args);
|
|
369
|
+
return target ? classifySegment([target]) : "neutral";
|
|
370
|
+
}
|
|
371
|
+
if (program === "git") {
|
|
372
|
+
const sub = args.find((a) => GIT_READ_SUBS.has(a) || GIT_WRITE_SUBS.has(a));
|
|
373
|
+
if (!sub) return "neutral";
|
|
374
|
+
return GIT_WRITE_SUBS.has(sub) ? "mutate" : "inspect";
|
|
375
|
+
}
|
|
376
|
+
const inPlace = args.some(
|
|
377
|
+
(a) => a === "--in-place" || /^-[A-Za-z]*i/.test(a) || /^--in-place=/.test(a),
|
|
378
|
+
);
|
|
379
|
+
if (program === "sed" || program === "perl") {
|
|
380
|
+
if (inPlace) return "mutate";
|
|
381
|
+
return "inspect";
|
|
382
|
+
}
|
|
383
|
+
if (INLINE_INTERPRETERS.has(program)) {
|
|
384
|
+
const inline = args.some((a) => a === "-e" || a === "-p" || a === "--eval" || a === "-c");
|
|
385
|
+
if (!inline) return "neutral";
|
|
386
|
+
return INLINE_WRITE_RE.test(args.join(" ")) ? "mutate" : "inspect";
|
|
387
|
+
}
|
|
388
|
+
if (INSPECT_PROGRAMS.has(program)) return "inspect";
|
|
389
|
+
return "neutral";
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
/** True when the command is inspection-shaped (see the rule above). */
|
|
393
|
+
export function bashCommandIsVerification(command: string): boolean {
|
|
394
|
+
if (!command.trim()) return false;
|
|
395
|
+
const tokens = tokenizeCommand(command);
|
|
396
|
+
if (writesFile(tokens)) return false;
|
|
397
|
+
let inspected = false;
|
|
398
|
+
for (const segment of splitSegments(tokens)) {
|
|
399
|
+
const kind = classifySegment(segment);
|
|
400
|
+
if (kind === "mutate") return false;
|
|
401
|
+
if (kind === "inspect") inspected = true;
|
|
402
|
+
}
|
|
403
|
+
return inspected;
|
|
404
|
+
}
|
|
405
|
+
|
|
406
|
+
/**
|
|
407
|
+
* Does this tool call count as verification activity? The name set first, then
|
|
408
|
+
* bash by the command's shape. Every other tool is not verification.
|
|
409
|
+
*/
|
|
410
|
+
export function isVerificationToolCall(toolName: string, input: unknown): boolean {
|
|
411
|
+
if (VERIFICATION_TOOLS.has(toolName)) return true;
|
|
412
|
+
if (toolName !== "bash") return false;
|
|
413
|
+
const command = (input as { command?: unknown } | undefined)?.command;
|
|
414
|
+
return typeof command === "string" && bashCommandIsVerification(command);
|
|
415
|
+
}
|
|
416
|
+
|
|
47
417
|
export function createDefaultPolicies(
|
|
48
418
|
getToolTracking: () => ToolTracking,
|
|
49
419
|
onSignal: (type: string, data: Record<string, unknown>) => void,
|
|
@@ -49,7 +49,8 @@ The `cancelTimersByTag` helper from `extensions/scheduling/timer/index.ts` is th
|
|
|
49
49
|
`context_compress` returns its result immediately and defers the actual
|
|
50
50
|
`ctx.compact()` to the next safe boundary (batch-settle scheduler in
|
|
51
51
|
`context-manager/handlers/tools/context-compress.ts`): the first `turn_end`
|
|
52
|
-
whose persisted `toolResults` account for every active tool call
|
|
52
|
+
whose persisted `toolResults` account for every active tool call AND whose
|
|
53
|
+
assistant message reads as loop-done under the shared boundary rule, or
|
|
53
54
|
`agent_settled`, whichever comes first. Active calls are tracked by
|
|
54
55
|
`toolCallId`, registered at `tool_execution_start` and released by its own
|
|
55
56
|
`tool_execution_end` or by a boundary event whose `toolResults` carry that
|
|
@@ -71,6 +72,29 @@ deferred `ctx.compact()` still aborts the run at the settle point, so
|
|
|
71
72
|
compaction remains a turn-boundary action, not a mid-batch one. The
|
|
72
73
|
mechanism is loss-preserving; the boundary discipline stands.
|
|
73
74
|
|
|
75
|
+
### The turn-boundary rule
|
|
76
|
+
|
|
77
|
+
Which boundaries may abort a run is one rule in one home,
|
|
78
|
+
`lib/events/turn-boundary.ts`, read by the drain above and by the enforcement
|
|
79
|
+
hygiene act (`enforcement/handlers/register-turn-end-hygiene.ts`). It is an
|
|
80
|
+
allow-list over `message.stopReason`: the reasons that end a turn's work
|
|
81
|
+
(`stop`, `length`, `error`, `aborted`) fire, `toolUse` parks, and so does any
|
|
82
|
+
boundary it cannot read or does not recognize (`pending`, `deferred`, a
|
|
83
|
+
missing or misspelled reason, an empty object). A caller holding no boundary
|
|
84
|
+
at all (`undefined`) keeps the prior contract and fires, because the tool path
|
|
85
|
+
is parked by its own tool call id instead. The 0.90W hard backstop cuts a live
|
|
86
|
+
loop anyway.
|
|
87
|
+
|
|
88
|
+
The rule is narrower than the safety property it stands for. The loop still
|
|
89
|
+
dispatches when a tool call rides a non-`toolUse` stop reason, and when a steer
|
|
90
|
+
is queued at any boundary (pi polls steering after the `turn_end` emit), so a
|
|
91
|
+
boundary this rule accepts can still reach the abort it exists to avoid.
|
|
92
|
+
Reading "is anything left to dispatch" from the loop itself would close that
|
|
93
|
+
gap; the rule does not, and the drain inherits the residual. Its truth table is
|
|
94
|
+
pinned in `test/runtime/memory/test-compress-drain-boundaries.mjs`, and the
|
|
95
|
+
heartbeat's forwarding of the boundary into the arm path end to end in
|
|
96
|
+
`test/runtime/heartbeat/test-turn-boundary-arm-wiring.mjs`.
|
|
97
|
+
|
|
74
98
|
## Whisper wake-up policy in this module
|
|
75
99
|
|
|
76
100
|
Whispers from compaction-retry, navigation, and memory hooks use `triggerTurn: true` for messages that demand the agent's action:
|
|
@@ -26,6 +26,10 @@ import { analyzeSession } from "../../analysis.js";
|
|
|
26
26
|
import * as timerMod from "../../../../scheduling/timer/index.js";
|
|
27
27
|
import { getState } from "../../../../enforcement/state.js";
|
|
28
28
|
import { CONTEXT_COMPACT_REFUSE_PERCENT } from "../../../../../lib/detection/context-thresholds.js";
|
|
29
|
+
import {
|
|
30
|
+
turnBoundaryMayAbortRun,
|
|
31
|
+
type TurnBoundary,
|
|
32
|
+
} from "../../../../../lib/events/turn-boundary.js";
|
|
29
33
|
import { getCmState, isCompactionActive, log, recordNavigationAction } from "../shared.js";
|
|
30
34
|
import { snapBoundaryOutsideToolBatch } from "../tool-batch-boundary.js";
|
|
31
35
|
import { formatTokensK } from "../../../../../lib/detection/context-usage.js";
|
|
@@ -91,16 +95,30 @@ function optionalNumber(v: unknown): number | undefined {
|
|
|
91
95
|
// Batch-settle compaction scheduler.
|
|
92
96
|
// Contract: the tool returns its result FIRST (execute() resolves before a
|
|
93
97
|
// compaction is armed), but ctx.compact() — which aborts the turn — fires only
|
|
94
|
-
// at a
|
|
95
|
-
// no-op) or
|
|
96
|
-
//
|
|
97
|
-
//
|
|
98
|
-
//
|
|
99
|
-
//
|
|
100
|
-
//
|
|
101
|
-
//
|
|
102
|
-
//
|
|
103
|
-
//
|
|
98
|
+
// at a boundary where the abort cannot tear live work: agent_settled (the run
|
|
99
|
+
// fully settled, abort a clean no-op), or a turn_end that reads as loop-done.
|
|
100
|
+
// The rule that decides the second case lives in one place
|
|
101
|
+
// (lib/events/turn-boundary.ts) and is shared with the hygiene act, because a
|
|
102
|
+
// copy of it drifts silently. Read the residual there too: a loop-done stop
|
|
103
|
+
// reason is necessary, not sufficient. The loop still dispatches when a tool
|
|
104
|
+
// call rides a non-"toolUse" stop reason, and when a steer is queued at any
|
|
105
|
+
// boundary (pi polls steering after the turn_end emit), so a boundary this
|
|
106
|
+
// rule accepts can still reach the abort it exists to avoid. The 0.90W hard
|
|
107
|
+
// backstop is the one deliberate mid-loop cut, kept for a loop whose usage must
|
|
108
|
+
// not be allowed to overflow. A boundary with a tool call still active is
|
|
109
|
+
// unsafe for a further reason: a parallel sibling's result has not been
|
|
110
|
+
// delivered, so the abort drops it while the agent is still streaming its
|
|
111
|
+
// response to the context_compress result, surfacing a spurious "This operation
|
|
112
|
+
// was aborted" error in the TUI and tearing the finishing turn. agent_settled
|
|
113
|
+
// alone never drains a run kept alive by continuous steers, so the armed
|
|
114
|
+
// compaction stalls behind live work while usage keeps climbing, hence the
|
|
115
|
+
// turn_end boundary. The arm side asks the same question, from the one arm site
|
|
116
|
+
// that can see a boundary: the heartbeat's usage-driven auto-arm runs inside a
|
|
117
|
+
// turn_end dispatch and hands that event in, so a live-loop boundary below the
|
|
118
|
+
// 0.90W backstop leaves its entry queued for the next loop-done boundary (pinned
|
|
119
|
+
// end to end by test/runtime/heartbeat/test-turn-boundary-arm-wiring.mjs).
|
|
120
|
+
// Arming inside a tool call has no boundary to read, and its own call id parks
|
|
121
|
+
// the queue there anyway.
|
|
104
122
|
//
|
|
105
123
|
// Active work is tracked by TOOL CALL ID, never by a count: tool_execution_start
|
|
106
124
|
// registers an id, tool_execution_end deletes its own, and a turn boundary
|
|
@@ -317,6 +335,20 @@ export function scheduleDegradedCompact(trigger: () => void): void {
|
|
|
317
335
|
setTimeout(trigger, DEGRADED_DEFERRAL_MS);
|
|
318
336
|
}
|
|
319
337
|
|
|
338
|
+
/**
|
|
339
|
+
* Whether an arm may fire its own entry. Firing a compact aborts whatever run
|
|
340
|
+
* is live, so an arm that happens inside a turn boundary dispatch hands that
|
|
341
|
+
* boundary in and is judged by the same rule the TURN_END handler applies
|
|
342
|
+
* (the rule lives in lib/events/turn-boundary.ts; it owns the "no boundary
|
|
343
|
+
* known" case, which fires). Every other arm site runs inside a tool call,
|
|
344
|
+
* where there is no boundary to read and the prior contract stands: the arm
|
|
345
|
+
* drains unless a batch is still active (the arm's own call id keeps it
|
|
346
|
+
* parked, so it does not fire there).
|
|
347
|
+
*/
|
|
348
|
+
function armMayDrainNow(boundary: TurnBoundary | undefined, ctx: any): boolean {
|
|
349
|
+
return turnBoundaryMayAbortRun(boundary, () => captureUsage(ctx));
|
|
350
|
+
}
|
|
351
|
+
|
|
320
352
|
/**
|
|
321
353
|
* Arm a one-shot compaction at a safe boundary (next turn end or run settle).
|
|
322
354
|
* Returns "pending-exists" when an LLM-class compaction is already armed: the
|
|
@@ -335,6 +367,7 @@ function scheduleCompactionAtBatchSettle(
|
|
|
335
367
|
meta: { kind: PendingCompaction["kind"]; cutEntryId?: string; firstKeptEntryId?: string } = {
|
|
336
368
|
kind: "compact",
|
|
337
369
|
},
|
|
370
|
+
boundary?: TurnBoundary,
|
|
338
371
|
): "queued" | "pending-exists" {
|
|
339
372
|
const trigger = () => {
|
|
340
373
|
try {
|
|
@@ -368,7 +401,13 @@ function scheduleCompactionAtBatchSettle(
|
|
|
368
401
|
` (cap ${PENDING_COMPACT_QUEUE_MAX}); the first-armed entry still fires.`,
|
|
369
402
|
);
|
|
370
403
|
}
|
|
371
|
-
|
|
404
|
+
// Arming fires only where that is safe. Firing a compaction aborts whatever
|
|
405
|
+
// run is live, and an arm site is not in a position to tell: the tool path
|
|
406
|
+
// arms inside its own call (whose id parks the queue anyway), and the
|
|
407
|
+
// heartbeat's arm runs inside a turn_end dispatch, where whether the loop
|
|
408
|
+
// still has work to dispatch is a fact the event carries. That caller hands
|
|
409
|
+
// its boundary in; every other caller keeps the prior contract.
|
|
410
|
+
if (armMayDrainNow(boundary, ctx)) firePendingCompactionsIfSettled(ctx, st);
|
|
372
411
|
return "queued";
|
|
373
412
|
} catch {
|
|
374
413
|
// Degraded path: batch-settle bookkeeping is unavailable (extension state
|
|
@@ -397,6 +436,7 @@ function armSlideCompaction(
|
|
|
397
436
|
pi: ExtensionAPI,
|
|
398
437
|
ctx: any,
|
|
399
438
|
keepCount: number,
|
|
439
|
+
boundary?: TurnBoundary,
|
|
400
440
|
): { cutEntryId: string; keptCount: number; droppedCount: number } | null {
|
|
401
441
|
const sm = ctx.sessionManager;
|
|
402
442
|
if (!sm || typeof sm.getBranch !== "function") return null;
|
|
@@ -453,6 +493,7 @@ function armSlideCompaction(
|
|
|
453
493
|
ctx,
|
|
454
494
|
{ customInstructions: "SLIDE_MODE:true" },
|
|
455
495
|
{ kind: "slide", cutEntryId },
|
|
496
|
+
boundary,
|
|
456
497
|
);
|
|
457
498
|
return { cutEntryId, keptCount, droppedCount };
|
|
458
499
|
}
|
|
@@ -488,11 +529,17 @@ function getAutoArmState(ctx: any): AutoArmState {
|
|
|
488
529
|
* settle, never mid-run.
|
|
489
530
|
*
|
|
490
531
|
* Called from the heartbeat tick — the only cadence that runs while a session
|
|
491
|
-
* works
|
|
532
|
+
* works, and the only arm site that runs inside a turn boundary dispatch. It
|
|
533
|
+
* hands that boundary in, so the arm is judged by the same rule the drain
|
|
534
|
+
* applies: a "toolUse" boundary below the 0.90W backstop leaves the entry
|
|
535
|
+
* queued for the next loop-done boundary instead of aborting the request the
|
|
536
|
+
* loop is about to dispatch. Returns what happened and why, so the caller can
|
|
537
|
+
* log it.
|
|
492
538
|
*/
|
|
493
539
|
export function maybeArmAutoCompaction(
|
|
494
540
|
pi: ExtensionAPI,
|
|
495
541
|
ctx: any,
|
|
542
|
+
boundary?: TurnBoundary,
|
|
496
543
|
): { armed: boolean; reason: string } {
|
|
497
544
|
const config: ResolvedAutoCompactConfig = getAutoCompactConfig();
|
|
498
545
|
if (!config.enabled) return { armed: false, reason: "disabled" };
|
|
@@ -513,7 +560,7 @@ export function maybeArmAutoCompaction(
|
|
|
513
560
|
}
|
|
514
561
|
const branchLength = ctx?.sessionManager?.getBranch?.().length ?? 0;
|
|
515
562
|
const keep = resolveAutoSlideKeep(branchLength);
|
|
516
|
-
const armed = armSlideCompaction(pi, ctx, keep);
|
|
563
|
+
const armed = armSlideCompaction(pi, ctx, keep, boundary);
|
|
517
564
|
st.aboveCount = 0;
|
|
518
565
|
if (!armed) return { armed: false, reason: "branch-too-short" };
|
|
519
566
|
log.info(
|
|
@@ -607,10 +654,10 @@ export const contextCompressSchema = Type.Object({
|
|
|
607
654
|
export function registerContextCompress(pi: ExtensionAPI): void {
|
|
608
655
|
// Batch-settle scheduling: track the ACTIVE tool calls of every running
|
|
609
656
|
// batch by call id and fire the deferred compaction only at a safe boundary
|
|
610
|
-
// (turn_end or agent_settled). Never mid-batch (would drop a
|
|
611
|
-
// sibling's result) and never at tool_execution_end (the run is
|
|
612
|
-
// there — an aborting compact would surface a spurious "This
|
|
613
|
-
// aborted" error and tear the finishing turn).
|
|
657
|
+
// (a loop-done turn_end or agent_settled). Never mid-batch (would drop a
|
|
658
|
+
// parallel sibling's result) and never at tool_execution_end (the run is
|
|
659
|
+
// still live there — an aborting compact would surface a spurious "This
|
|
660
|
+
// operation was aborted" error and tear the finishing turn).
|
|
614
661
|
onEvent(pi, TOOL_EXECUTION_START, (event: any, ctx: any) => {
|
|
615
662
|
try {
|
|
616
663
|
const st = getBatchSettleState(ctx);
|
|
@@ -637,17 +684,22 @@ export function registerContextCompress(pi: ExtensionAPI): void {
|
|
|
637
684
|
}
|
|
638
685
|
});
|
|
639
686
|
onEvent(pi, TURN_END, (event: any, ctx: any) => {
|
|
640
|
-
//
|
|
641
|
-
//
|
|
642
|
-
//
|
|
643
|
-
//
|
|
644
|
-
//
|
|
645
|
-
//
|
|
646
|
-
//
|
|
687
|
+
// Turn boundary. The turn's assistant message and tool results are already
|
|
688
|
+
// persisted here, but that alone does not make the run safe to abort: a
|
|
689
|
+
// "toolUse" stop means the loop dispatches its next request the moment the
|
|
690
|
+
// handlers return, so the deferred ctx.compact() tears that request
|
|
691
|
+
// mid-stream and the compaction replaces the work it was about to do (the
|
|
692
|
+
// rule is lib/events/turn-boundary.ts, and its residual section lists the
|
|
693
|
+
// two cases a loop-done stop reason does not rule out). Only a loop-done
|
|
694
|
+
// boundary drains, except at the 0.90W hard backstop, which exists
|
|
695
|
+
// precisely to stop a runaway live loop before it overflows.
|
|
696
|
+
//
|
|
697
|
+
// The persisted results carry the toolCallIds of the calls they answer,
|
|
698
|
+
// which releases a call whose tool_execution_end never arrived; an active
|
|
699
|
+
// id with NO result in this event is kept (it may still be executing, and
|
|
700
|
+
// a count could not tell which sibling completed). A run kept alive by
|
|
647
701
|
// continuous steers never reaches agent_settled — this boundary keeps an
|
|
648
|
-
// armed compaction from stalling behind live work.
|
|
649
|
-
// moment survives: the loop appends it before the aborted response stream,
|
|
650
|
-
// and its turn runs on the post-compaction resume. Ids are never blanket-
|
|
702
|
+
// armed compaction from stalling behind live work. Ids are never blanket-
|
|
651
703
|
// reset here (only agent_settled owns that backstop, which is what keeps a
|
|
652
704
|
// missed end event from parking the queue forever).
|
|
653
705
|
try {
|
|
@@ -655,6 +707,7 @@ export function registerContextCompress(pi: ExtensionAPI): void {
|
|
|
655
707
|
releaseSettledToolCallIds(st, event?.toolResults);
|
|
656
708
|
if (st.pending.length === 0 || st.activeToolCallIds.size > 0) return;
|
|
657
709
|
if (isCompactionActive(ctx)) return;
|
|
710
|
+
if (!turnBoundaryMayAbortRun(event, () => captureUsage(ctx))) return;
|
|
658
711
|
firePendingCompactionsIfSettled(ctx, st);
|
|
659
712
|
} catch {
|
|
660
713
|
// A failed boundary drain must not tear the turn_end event pipeline;
|
|
@@ -122,6 +122,13 @@ export function scratchpadDir(): string {
|
|
|
122
122
|
return path.join(braidDir(), "scratchpads");
|
|
123
123
|
}
|
|
124
124
|
|
|
125
|
+
/** Journal root (one dir per project slug), resolved on every call. Durable
|
|
126
|
+
* write state: the append-only record of what a seat decided, which a
|
|
127
|
+
* replacement seat reads before acting, so BRAID_HOME pinning must move it. */
|
|
128
|
+
export function journalDir(): string {
|
|
129
|
+
return path.join(braidDir(), "journal");
|
|
130
|
+
}
|
|
131
|
+
|
|
125
132
|
/** Healthcheck scratch and report root, resolved on every call. Durable-write
|
|
126
133
|
* state: the probes and the saved report must follow a pinned BRAID_HOME. */
|
|
127
134
|
export function healthcheckDir(): string {
|
|
@@ -305,6 +312,19 @@ export function tagsSlugFromCwd(cwd?: string): string {
|
|
|
305
312
|
return cwd.split("/").filter(Boolean).join("-") || "default";
|
|
306
313
|
}
|
|
307
314
|
|
|
315
|
+
/**
|
|
316
|
+
* Append-only journal file for one project: `<journal root>/<slug>/journal.jsonl`.
|
|
317
|
+
*
|
|
318
|
+
* The slug is the scratchpad's `projectSlugFromCwd` form, passed in rather than
|
|
319
|
+
* re-derived here: the writer, the checker and the session-start pointer must
|
|
320
|
+
* name ONE file, and a second slug rule is how the tag file split into a writer
|
|
321
|
+
* and a reader that could never meet (see tagsSlugFromCwd). Resolved on every
|
|
322
|
+
* call, so a pinned BRAID_HOME writes and reads its own journal.
|
|
323
|
+
*/
|
|
324
|
+
export function journalFilePath(projectSlug: string): string {
|
|
325
|
+
return path.join(journalDir(), projectSlug, "journal.jsonl");
|
|
326
|
+
}
|
|
327
|
+
|
|
308
328
|
/**
|
|
309
329
|
* Get the lossless flush file path for one offloaded tool result.
|
|
310
330
|
* Layout: <offload dir>/<sessionId>/<toolName>-<toolCallId>.txt.
|