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
|
@@ -53,10 +53,54 @@ export declare function contextUsageTierMessage(tier: ContextUsageTier, usagePer
|
|
|
53
53
|
* fractions of the resolved window (0.45W warning, 0.18W soft).
|
|
54
54
|
*/
|
|
55
55
|
export declare function contextUsageTokenMessage(level: "warning" | "soft", usagePercent: number, usageTokens: number): string;
|
|
56
|
+
export type ContextNudgeId = "tokens:soft" | "tokens:warning" | "percent:soft" | "percent:advisory" | "percent:warning" | "percent:critical" | "percent:compact";
|
|
57
|
+
export interface ContextNudgeRung {
|
|
58
|
+
/** Stable rung identity — what a latch records to suppress a repeat. */
|
|
59
|
+
id: ContextNudgeId;
|
|
60
|
+
/** Unit the rung is measured in, and the unit the latch re-arms in. */
|
|
61
|
+
unit: "tokens" | "percent";
|
|
62
|
+
/** The rung's threshold in `unit` (a resolved token count, or a percent). */
|
|
63
|
+
threshold: number;
|
|
64
|
+
/** The same threshold as a percent of the resolved window: ladder order. */
|
|
65
|
+
position: number;
|
|
66
|
+
}
|
|
67
|
+
export interface ContextNudge extends ContextNudgeRung {
|
|
68
|
+
message: string;
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* The strongest rung these numbers reach, or null below the first rung.
|
|
72
|
+
* Highest POSITION wins, not first match: that is what stops a token arm from
|
|
73
|
+
* shadowing a percent tier above it. Equal positions keep the earlier rung
|
|
74
|
+
* (the ladder is built weakest-first), and an equal position is not an
|
|
75
|
+
* escalation.
|
|
76
|
+
*/
|
|
77
|
+
export declare function resolveContextNudge(usagePercent: number, usageTokens: number, window?: number | null): ContextNudge | null;
|
|
78
|
+
/**
|
|
79
|
+
* One rung by id, resolved against the window in hand: a window change
|
|
80
|
+
* re-derives the rung's bar instead of comparing a live count against a stale
|
|
81
|
+
* one. Unknown or absent ids yield null (a latch armed by something that is
|
|
82
|
+
* not a rung).
|
|
83
|
+
*/
|
|
84
|
+
export declare function findContextNudgeRung(id: string | null | undefined, window?: number | null): ContextNudgeRung | null;
|
|
85
|
+
/**
|
|
86
|
+
* Has usage fallen back below the rung that armed the latch? The comparison is
|
|
87
|
+
* in the rung's own unit: a token rung clears on a token count below its arm,
|
|
88
|
+
* a percent rung on a percent below its threshold. With no recorded rung (the
|
|
89
|
+
* latch was armed by an act that then stood down) the percent reset bar
|
|
90
|
+
* applies, which is the pre-ladder behavior for that path.
|
|
91
|
+
*/
|
|
92
|
+
export declare function contextNudgeFellBelow(id: string | null | undefined, usagePercent: number, usageTokens: number, window?: number | null): boolean;
|
|
93
|
+
/**
|
|
94
|
+
* Was this rung crossed from below since the previous sample? A nudge is an
|
|
95
|
+
* event: a session that lands above a rung and stays there must not read the
|
|
96
|
+
* same advice every turn, while a rung climbed past is new information. The
|
|
97
|
+
* previous sample is a token count, so a percent rung is tested against it
|
|
98
|
+
* re-expressed as a percent of the window in hand.
|
|
99
|
+
*/
|
|
100
|
+
export declare function contextNudgeCrossed(rung: ContextNudgeRung, prevUsageTokens: number | undefined, window?: number | null): boolean;
|
|
56
101
|
/**
|
|
57
|
-
* Combined enforcement
|
|
58
|
-
* for
|
|
59
|
-
* Returns null when no tier is reached.
|
|
102
|
+
* Combined enforcement nudge: the strongest rung reached, its text, or null.
|
|
103
|
+
* Kept as a text accessor for callers that need nothing but the message.
|
|
60
104
|
*/
|
|
61
105
|
export declare function contextUsageNudgeMessage(usagePercent: number, usageTokens: number, window?: number | null): string | null;
|
|
62
106
|
/** The duck-typed usage shape current sites read. percent may be null (no data). */
|
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
* here in a single copy too. Sites with different copy (heartbeat
|
|
26
26
|
* policies) keep their own messages and only share the tier mapping.
|
|
27
27
|
*/
|
|
28
|
-
import { USAGE_WHISPER_SOFT, USAGE_WHISPER_ADVISORY, USAGE_WHISPER_WARNING, USAGE_WHISPER_CRITICAL, USAGE_COMPACT_MEDIUM, } from "./context-thresholds.js";
|
|
28
|
+
import { USAGE_WHISPER_SOFT, USAGE_WHISPER_ADVISORY, USAGE_WHISPER_WARNING, USAGE_WHISPER_CRITICAL, USAGE_COMPACT_MEDIUM, USAGE_FIRED_RESET_BELOW, } from "./context-thresholds.js";
|
|
29
29
|
import { tokenArms, formatTokensK } from "./context-usage.js";
|
|
30
30
|
import { getResolvedContextWindow } from "../config/braid-settings.js";
|
|
31
31
|
/**
|
|
@@ -91,22 +91,131 @@ export function contextUsageTokenMessage(level, usagePercent, usageTokens) {
|
|
|
91
91
|
`Consider context_inspect(detail="prune") to see candidates, or tag position with context_navigate(action="tag").`);
|
|
92
92
|
}
|
|
93
93
|
/**
|
|
94
|
-
*
|
|
95
|
-
*
|
|
96
|
-
*
|
|
94
|
+
* The ladder for one window, weakest position first. Token rungs carry the
|
|
95
|
+
* absolute count in their copy (that is what they are for on a large window);
|
|
96
|
+
* percent rungs carry the percent.
|
|
97
97
|
*/
|
|
98
|
-
|
|
98
|
+
function nudgeRungs(window) {
|
|
99
99
|
const arms = tokenArms(window);
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
100
|
+
const positionOf = (tokens) => (arms.W > 0 ? (tokens / arms.W) * 100 : 0);
|
|
101
|
+
const pct = (threshold) => ({ unit: "percent", threshold, position: threshold });
|
|
102
|
+
return [
|
|
103
|
+
{
|
|
104
|
+
id: "tokens:soft",
|
|
105
|
+
unit: "tokens",
|
|
106
|
+
threshold: arms.soft,
|
|
107
|
+
position: positionOf(arms.soft),
|
|
108
|
+
render: (p, t) => contextUsageTokenMessage("soft", p, t),
|
|
109
|
+
},
|
|
110
|
+
{
|
|
111
|
+
id: "percent:soft",
|
|
112
|
+
...pct(USAGE_WHISPER_SOFT),
|
|
113
|
+
render: (p) => contextUsageTierMessage("soft", p),
|
|
114
|
+
},
|
|
115
|
+
{
|
|
116
|
+
id: "tokens:warning",
|
|
117
|
+
unit: "tokens",
|
|
118
|
+
threshold: arms.warning,
|
|
119
|
+
position: positionOf(arms.warning),
|
|
120
|
+
render: (p, t) => contextUsageTokenMessage("warning", p, t),
|
|
121
|
+
},
|
|
122
|
+
{
|
|
123
|
+
id: "percent:advisory",
|
|
124
|
+
...pct(USAGE_WHISPER_ADVISORY),
|
|
125
|
+
render: (p) => contextUsageTierMessage("advisory", p),
|
|
126
|
+
},
|
|
127
|
+
{
|
|
128
|
+
id: "percent:warning",
|
|
129
|
+
...pct(USAGE_WHISPER_WARNING),
|
|
130
|
+
render: (p) => contextUsageTierMessage("warning", p),
|
|
131
|
+
},
|
|
132
|
+
{
|
|
133
|
+
id: "percent:critical",
|
|
134
|
+
...pct(USAGE_WHISPER_CRITICAL),
|
|
135
|
+
render: (p) => contextUsageTierMessage("critical", p),
|
|
136
|
+
},
|
|
137
|
+
{
|
|
138
|
+
id: "percent:compact",
|
|
139
|
+
...pct(USAGE_COMPACT_MEDIUM),
|
|
140
|
+
render: (p) => contextUsageTierMessage("compact", p),
|
|
141
|
+
},
|
|
142
|
+
];
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* The strongest rung these numbers reach, or null below the first rung.
|
|
146
|
+
* Highest POSITION wins, not first match: that is what stops a token arm from
|
|
147
|
+
* shadowing a percent tier above it. Equal positions keep the earlier rung
|
|
148
|
+
* (the ladder is built weakest-first), and an equal position is not an
|
|
149
|
+
* escalation.
|
|
150
|
+
*/
|
|
151
|
+
export function resolveContextNudge(usagePercent, usageTokens, window) {
|
|
152
|
+
let best = null;
|
|
153
|
+
for (const rung of nudgeRungs(window)) {
|
|
154
|
+
const reached = rung.unit === "tokens" ? usageTokens >= rung.threshold : usagePercent >= rung.threshold;
|
|
155
|
+
if (reached && (best === null || rung.position > best.position))
|
|
156
|
+
best = rung;
|
|
105
157
|
}
|
|
106
|
-
|
|
107
|
-
if (!tier)
|
|
158
|
+
if (!best)
|
|
108
159
|
return null;
|
|
109
|
-
return
|
|
160
|
+
return {
|
|
161
|
+
id: best.id,
|
|
162
|
+
unit: best.unit,
|
|
163
|
+
threshold: best.threshold,
|
|
164
|
+
position: best.position,
|
|
165
|
+
message: best.render(usagePercent, usageTokens),
|
|
166
|
+
};
|
|
167
|
+
}
|
|
168
|
+
/**
|
|
169
|
+
* One rung by id, resolved against the window in hand: a window change
|
|
170
|
+
* re-derives the rung's bar instead of comparing a live count against a stale
|
|
171
|
+
* one. Unknown or absent ids yield null (a latch armed by something that is
|
|
172
|
+
* not a rung).
|
|
173
|
+
*/
|
|
174
|
+
export function findContextNudgeRung(id, window) {
|
|
175
|
+
if (!id)
|
|
176
|
+
return null;
|
|
177
|
+
for (const rung of nudgeRungs(window)) {
|
|
178
|
+
if (rung.id === id)
|
|
179
|
+
return { id: rung.id, unit: rung.unit, threshold: rung.threshold, position: rung.position };
|
|
180
|
+
}
|
|
181
|
+
return null;
|
|
182
|
+
}
|
|
183
|
+
/**
|
|
184
|
+
* Has usage fallen back below the rung that armed the latch? The comparison is
|
|
185
|
+
* in the rung's own unit: a token rung clears on a token count below its arm,
|
|
186
|
+
* a percent rung on a percent below its threshold. With no recorded rung (the
|
|
187
|
+
* latch was armed by an act that then stood down) the percent reset bar
|
|
188
|
+
* applies, which is the pre-ladder behavior for that path.
|
|
189
|
+
*/
|
|
190
|
+
export function contextNudgeFellBelow(id, usagePercent, usageTokens, window) {
|
|
191
|
+
const rung = findContextNudgeRung(id, window);
|
|
192
|
+
if (!rung)
|
|
193
|
+
return usagePercent < USAGE_FIRED_RESET_BELOW;
|
|
194
|
+
return rung.unit === "tokens" ? usageTokens < rung.threshold : usagePercent < rung.threshold;
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* Was this rung crossed from below since the previous sample? A nudge is an
|
|
198
|
+
* event: a session that lands above a rung and stays there must not read the
|
|
199
|
+
* same advice every turn, while a rung climbed past is new information. The
|
|
200
|
+
* previous sample is a token count, so a percent rung is tested against it
|
|
201
|
+
* re-expressed as a percent of the window in hand.
|
|
202
|
+
*/
|
|
203
|
+
export function contextNudgeCrossed(rung, prevUsageTokens, window) {
|
|
204
|
+
if (prevUsageTokens === undefined)
|
|
205
|
+
return true;
|
|
206
|
+
if (rung.unit === "tokens")
|
|
207
|
+
return prevUsageTokens < rung.threshold;
|
|
208
|
+
const { W } = tokenArms(window);
|
|
209
|
+
if (W <= 0)
|
|
210
|
+
return true;
|
|
211
|
+
return (prevUsageTokens / W) * 100 < rung.threshold;
|
|
212
|
+
}
|
|
213
|
+
/**
|
|
214
|
+
* Combined enforcement nudge: the strongest rung reached, its text, or null.
|
|
215
|
+
* Kept as a text accessor for callers that need nothing but the message.
|
|
216
|
+
*/
|
|
217
|
+
export function contextUsageNudgeMessage(usagePercent, usageTokens, window) {
|
|
218
|
+
return resolveContextNudge(usagePercent, usageTokens, window)?.message ?? null;
|
|
110
219
|
}
|
|
111
220
|
/**
|
|
112
221
|
* ONE duck-typed `getContextUsage()` extraction. Mirrors the fallbacks
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The turn-boundary rule: whether a deferred compaction may fire at a given
|
|
3
|
+
* `turn_end`.
|
|
4
|
+
*
|
|
5
|
+
* A deferred `ctx.compact()` aborts the active agent operation, and pi's
|
|
6
|
+
* manual compaction never retries or continues the interrupted turn. So the
|
|
7
|
+
* abort has to land where nothing is in flight, which makes the boundary a
|
|
8
|
+
* question about the run, not about the compaction: is the loop still
|
|
9
|
+
* dispatching?
|
|
10
|
+
*
|
|
11
|
+
* One home for that question. Two sites read it today (the drain in the
|
|
12
|
+
* context_compress batch scheduler and the hygiene act in enforcement), and a
|
|
13
|
+
* copy drifts silently: a wrong answer shows up as a torn turn under load,
|
|
14
|
+
* never as a failing check.
|
|
15
|
+
*
|
|
16
|
+
* The rule is an ALLOW-LIST over `message.stopReason`, not a deny-list, so an
|
|
17
|
+
* unreadable or unrecognized boundary parks instead of firing:
|
|
18
|
+
*
|
|
19
|
+
* "stop" the model finished its response. fire
|
|
20
|
+
* "length" the response hit its output ceiling. fire
|
|
21
|
+
* "error" the turn ended in an error. fire
|
|
22
|
+
* "aborted" the run was aborted. fire
|
|
23
|
+
* "toolUse" the loop dispatches its next request as park
|
|
24
|
+
* soon as the turn_end handlers return.
|
|
25
|
+
* "pending" the response is not final yet. park
|
|
26
|
+
* "deferred" the provider deferred the response. park
|
|
27
|
+
* absent, or the boundary says nothing usable. An park
|
|
28
|
+
* any other unreadable boundary is not evidence that the
|
|
29
|
+
* value loop is done.
|
|
30
|
+
*
|
|
31
|
+
* RESIDUAL, and the reason this rule is narrower than the safety property it
|
|
32
|
+
* stands for: a loop-done stop reason is necessary, not sufficient. The loop
|
|
33
|
+
* dispatches anyway in two measured cases, a tool call carrying a non-"toolUse"
|
|
34
|
+
* stop reason ("length" with tool calls, for instance) and a steer queued at
|
|
35
|
+
* any boundary (pi polls steering after the turn_end emit). A boundary the rule
|
|
36
|
+
* reads as loop-done while either holds still reaches the abort it exists to
|
|
37
|
+
* avoid. Reading "is anything left to dispatch" from the loop itself would
|
|
38
|
+
* close that gap; this rule does not, and it is the whole of what the drain
|
|
39
|
+
* and the act share.
|
|
40
|
+
*
|
|
41
|
+
* Two deliberate exceptions:
|
|
42
|
+
* - The 0.90W hard backstop cuts a live loop anyway. Above 0.90W of the
|
|
43
|
+
* window the loop is the runaway this exists to stop, so the abort it
|
|
44
|
+
* risks is cheaper than the overflow it prevents. Usage arrives from the
|
|
45
|
+
* caller because each site measures it from its own source.
|
|
46
|
+
* - No boundary at all (`undefined`) fires, keeping the pre-existing
|
|
47
|
+
* contract for callers that arm without boundary knowledge. The tool path
|
|
48
|
+
* is parked there by its own tool call identity instead (an arm inside a
|
|
49
|
+
* live batch still holds an active call id).
|
|
50
|
+
*/
|
|
51
|
+
import type { TurnEndEvent } from "@earendil-works/pi-coding-agent";
|
|
52
|
+
/**
|
|
53
|
+
* A boundary as this rule reads it: a real `turn_end` payload, or the partial
|
|
54
|
+
* projection a caller may hold. `undefined` means the caller has no boundary
|
|
55
|
+
* knowledge at all, which is a different statement from an empty boundary.
|
|
56
|
+
*/
|
|
57
|
+
export type TurnBoundary = Partial<Pick<TurnEndEvent, "message">> | undefined;
|
|
58
|
+
/** The usage a backstop decision reads. */
|
|
59
|
+
export interface TurnBoundaryUsage {
|
|
60
|
+
/** Live tokens in the working set (compaction-aware). */
|
|
61
|
+
tokens: number;
|
|
62
|
+
/** The window the backstop fraction resolves against, when known. */
|
|
63
|
+
contextWindow?: number | null;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* True when the boundary carries a stop reason that ends the turn's work.
|
|
67
|
+
* Fail-closed: a boundary with no readable reason, or one this rule does not
|
|
68
|
+
* recognize, is not loop-done.
|
|
69
|
+
*/
|
|
70
|
+
export declare function turnBoundaryIsLoopDone(boundary: TurnBoundary): boolean;
|
|
71
|
+
/**
|
|
72
|
+
* Whether a deferred compaction may abort the run at this boundary.
|
|
73
|
+
*
|
|
74
|
+
* `readUsage` is called only when the boundary is not loop-done, so a
|
|
75
|
+
* loop-done boundary never pays for a usage measurement.
|
|
76
|
+
*/
|
|
77
|
+
export declare function turnBoundaryMayAbortRun(boundary: TurnBoundary, readUsage?: () => TurnBoundaryUsage | null | undefined): boolean;
|
|
78
|
+
//# sourceMappingURL=turn-boundary.d.ts.map
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The turn-boundary rule: whether a deferred compaction may fire at a given
|
|
3
|
+
* `turn_end`.
|
|
4
|
+
*
|
|
5
|
+
* A deferred `ctx.compact()` aborts the active agent operation, and pi's
|
|
6
|
+
* manual compaction never retries or continues the interrupted turn. So the
|
|
7
|
+
* abort has to land where nothing is in flight, which makes the boundary a
|
|
8
|
+
* question about the run, not about the compaction: is the loop still
|
|
9
|
+
* dispatching?
|
|
10
|
+
*
|
|
11
|
+
* One home for that question. Two sites read it today (the drain in the
|
|
12
|
+
* context_compress batch scheduler and the hygiene act in enforcement), and a
|
|
13
|
+
* copy drifts silently: a wrong answer shows up as a torn turn under load,
|
|
14
|
+
* never as a failing check.
|
|
15
|
+
*
|
|
16
|
+
* The rule is an ALLOW-LIST over `message.stopReason`, not a deny-list, so an
|
|
17
|
+
* unreadable or unrecognized boundary parks instead of firing:
|
|
18
|
+
*
|
|
19
|
+
* "stop" the model finished its response. fire
|
|
20
|
+
* "length" the response hit its output ceiling. fire
|
|
21
|
+
* "error" the turn ended in an error. fire
|
|
22
|
+
* "aborted" the run was aborted. fire
|
|
23
|
+
* "toolUse" the loop dispatches its next request as park
|
|
24
|
+
* soon as the turn_end handlers return.
|
|
25
|
+
* "pending" the response is not final yet. park
|
|
26
|
+
* "deferred" the provider deferred the response. park
|
|
27
|
+
* absent, or the boundary says nothing usable. An park
|
|
28
|
+
* any other unreadable boundary is not evidence that the
|
|
29
|
+
* value loop is done.
|
|
30
|
+
*
|
|
31
|
+
* RESIDUAL, and the reason this rule is narrower than the safety property it
|
|
32
|
+
* stands for: a loop-done stop reason is necessary, not sufficient. The loop
|
|
33
|
+
* dispatches anyway in two measured cases, a tool call carrying a non-"toolUse"
|
|
34
|
+
* stop reason ("length" with tool calls, for instance) and a steer queued at
|
|
35
|
+
* any boundary (pi polls steering after the turn_end emit). A boundary the rule
|
|
36
|
+
* reads as loop-done while either holds still reaches the abort it exists to
|
|
37
|
+
* avoid. Reading "is anything left to dispatch" from the loop itself would
|
|
38
|
+
* close that gap; this rule does not, and it is the whole of what the drain
|
|
39
|
+
* and the act share.
|
|
40
|
+
*
|
|
41
|
+
* Two deliberate exceptions:
|
|
42
|
+
* - The 0.90W hard backstop cuts a live loop anyway. Above 0.90W of the
|
|
43
|
+
* window the loop is the runaway this exists to stop, so the abort it
|
|
44
|
+
* risks is cheaper than the overflow it prevents. Usage arrives from the
|
|
45
|
+
* caller because each site measures it from its own source.
|
|
46
|
+
* - No boundary at all (`undefined`) fires, keeping the pre-existing
|
|
47
|
+
* contract for callers that arm without boundary knowledge. The tool path
|
|
48
|
+
* is parked there by its own tool call identity instead (an arm inside a
|
|
49
|
+
* live batch still holds an active call id).
|
|
50
|
+
*/
|
|
51
|
+
import { tokenArms } from "../detection/context-usage.js";
|
|
52
|
+
import { getStopReason } from "../state/extension-state.js";
|
|
53
|
+
/**
|
|
54
|
+
* The stop reasons that end the turn's work, keyed by the union pi-ai
|
|
55
|
+
* declares. Typing the record as a total map over the reasons this rule does
|
|
56
|
+
* not park on makes a new provider stop reason a compile error here instead of
|
|
57
|
+
* a silent "park" or a silent "fire": someone has to classify it.
|
|
58
|
+
*/
|
|
59
|
+
const LOOP_DONE_STOP_REASONS = {
|
|
60
|
+
stop: true,
|
|
61
|
+
length: true,
|
|
62
|
+
error: true,
|
|
63
|
+
aborted: true,
|
|
64
|
+
};
|
|
65
|
+
const LOOP_DONE = new Set(Object.keys(LOOP_DONE_STOP_REASONS));
|
|
66
|
+
/**
|
|
67
|
+
* True when the boundary carries a stop reason that ends the turn's work.
|
|
68
|
+
* Fail-closed: a boundary with no readable reason, or one this rule does not
|
|
69
|
+
* recognize, is not loop-done.
|
|
70
|
+
*/
|
|
71
|
+
export function turnBoundaryIsLoopDone(boundary) {
|
|
72
|
+
const stopReason = getStopReason(boundary?.message);
|
|
73
|
+
return stopReason !== undefined && LOOP_DONE.has(stopReason);
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Whether a deferred compaction may abort the run at this boundary.
|
|
77
|
+
*
|
|
78
|
+
* `readUsage` is called only when the boundary is not loop-done, so a
|
|
79
|
+
* loop-done boundary never pays for a usage measurement.
|
|
80
|
+
*/
|
|
81
|
+
export function turnBoundaryMayAbortRun(boundary, readUsage) {
|
|
82
|
+
if (boundary === undefined)
|
|
83
|
+
return true;
|
|
84
|
+
if (turnBoundaryIsLoopDone(boundary))
|
|
85
|
+
return true;
|
|
86
|
+
const usage = readUsage?.();
|
|
87
|
+
if (!usage)
|
|
88
|
+
return false;
|
|
89
|
+
return usage.tokens >= tokenArms(usage.contextWindow).backstop;
|
|
90
|
+
}
|
|
91
|
+
//# sourceMappingURL=turn-boundary.js.map
|
|
@@ -444,8 +444,9 @@ export type PopulationCensus = (revision: string) => number | null;
|
|
|
444
444
|
* Read every gate row for a population stamp and compare the `files` ones
|
|
445
445
|
* against the census the caller supplies for their named revision. Pure: the
|
|
446
446
|
* count is a lookup parameter, so the parse and the comparison are testable
|
|
447
|
-
* without a repository. Rows of another unit are not census subjects
|
|
448
|
-
* left uncompared; an unreadable stamp is named,
|
|
447
|
+
* without a repository. Rows of another unit are not census subjects: they are
|
|
448
|
+
* read, named in the lines, and left uncompared; an unreadable stamp is named,
|
|
449
|
+
* never silently dropped.
|
|
449
450
|
*/
|
|
450
451
|
export declare function readPopulationStamps(gates: unknown, censusAt: PopulationCensus): PopulationRead;
|
|
451
452
|
/**
|
|
@@ -842,8 +842,15 @@ export function productionWriteRefusalDetail(read) {
|
|
|
842
842
|
* Bare-token revision rules: an all-hex token is a sha only at 7-40 chars, so
|
|
843
843
|
* a six-char prefix does not slip through the ref-name alternative as a
|
|
844
844
|
* revision git can never resolve.
|
|
845
|
+
*
|
|
846
|
+
* The unit is one token of lowercase letters and digits, joined by single
|
|
847
|
+
* hyphens or underscores and starting with a letter: a reporter writes
|
|
848
|
+
* `test-files` as readily as `files`, and the earlier letters-only rule threw
|
|
849
|
+
* that evidence away as unreadable. A unit is never a phrase — `scanned 5 test
|
|
850
|
+
* files at main` stays refused, because a two-word unit cannot be told from a
|
|
851
|
+
* malformed stamp.
|
|
845
852
|
*/
|
|
846
|
-
const POPULATION_STAMP_RE = /^scanned (\d+) ([a-z]+) at ([0-9a-fA-F]{7,40}|[A-Za-z0-9][A-Za-z0-9._/-]*)$/;
|
|
853
|
+
const POPULATION_STAMP_RE = /^scanned (\d+) ([a-z][a-z0-9]*(?:[_-][a-z0-9]+)*) at ([0-9a-fA-F]{7,40}|[A-Za-z0-9][A-Za-z0-9._/-]*)$/;
|
|
847
854
|
const ALL_HEX_RE = /^[0-9a-fA-F]+$/;
|
|
848
855
|
/** Parse the stamp shape above; null when the value is not that shape. */
|
|
849
856
|
export function parsePopulationStamp(value) {
|
|
@@ -864,8 +871,18 @@ function populationLines(rows) {
|
|
|
864
871
|
lines.push(`population stamp unreadable: row ${row.row} ${JSON.stringify(row.raw)}`);
|
|
865
872
|
continue;
|
|
866
873
|
}
|
|
867
|
-
if (row.stamp === null
|
|
874
|
+
if (row.stamp === null)
|
|
875
|
+
continue;
|
|
876
|
+
if (row.stamp.unit !== "files") {
|
|
877
|
+
// A stamp names the population it scanned. Only `files` is a census
|
|
878
|
+
// subject here (the tracked-entry count at the revision), so another
|
|
879
|
+
// unit is read and named but never compared — and never dropped as if it
|
|
880
|
+
// had been unreadable, which is what the old unit pattern did to
|
|
881
|
+
// `test-files`.
|
|
882
|
+
lines.push(`population recorded: ${row.stamp.n} ${row.stamp.unit} at ${row.stamp.revision} ` +
|
|
883
|
+
`(row ${row.row}; unit is not the tracked-entry census, not compared)`);
|
|
868
884
|
continue;
|
|
885
|
+
}
|
|
869
886
|
if (row.verdict === "unresolved") {
|
|
870
887
|
lines.push(`population delta: recorded ${row.stamp.n} at ${row.stamp.revision} ` +
|
|
871
888
|
`(row ${row.row}; revision unresolved, not compared)`);
|
|
@@ -884,8 +901,9 @@ function populationLines(rows) {
|
|
|
884
901
|
* Read every gate row for a population stamp and compare the `files` ones
|
|
885
902
|
* against the census the caller supplies for their named revision. Pure: the
|
|
886
903
|
* count is a lookup parameter, so the parse and the comparison are testable
|
|
887
|
-
* without a repository. Rows of another unit are not census subjects
|
|
888
|
-
* left uncompared; an unreadable stamp is named,
|
|
904
|
+
* without a repository. Rows of another unit are not census subjects: they are
|
|
905
|
+
* read, named in the lines, and left uncompared; an unreadable stamp is named,
|
|
906
|
+
* never silently dropped.
|
|
889
907
|
*/
|
|
890
908
|
export function readPopulationStamps(gates, censusAt) {
|
|
891
909
|
const rows = [];
|
|
@@ -297,7 +297,7 @@ export declare function getShownDiscoveryBundles(): Set<string>;
|
|
|
297
297
|
export declare function resetShownDiscoveryBundles(): void;
|
|
298
298
|
/** Signal type identifiers used by the discoverability handler.
|
|
299
299
|
* These are the dedup keys — keep them stable across releases. */
|
|
300
|
-
export type DiscoverySignalType = "scratchpad_prior" | "memory_prior" | "sessions_prior" | "resume" | "tags_prior" | "context_hygiene_tip";
|
|
300
|
+
export type DiscoverySignalType = "scratchpad_prior" | "memory_prior" | "sessions_prior" | "resume" | "tags_prior" | "journal_prior" | "context_hygiene_tip";
|
|
301
301
|
/** Get the shared shown-signal-types set (process-global, survives /reload). */
|
|
302
302
|
export declare function getShownSignals(): Set<DiscoverySignalType>;
|
|
303
303
|
/** Reset the shown-signal set. Test helper. */
|
package/docs/CONTEXT-POLICY.md
CHANGED
|
@@ -35,6 +35,14 @@ arms fire late on large windows, which is why both ladders exist. `CONTEXT_COMPA
|
|
|
35
35
|
mode, guarding against max-call-stack crashes and session corruption at high
|
|
36
36
|
usage; hygiene acts re-arm at most once every three turns.
|
|
37
37
|
|
|
38
|
+
The two ladders arm one enforcement nudge between them, ordered by position on
|
|
39
|
+
the percent axis both units measure: 0.18W, 30%, 0.45W, 50%, 65%, 75%, 80%. The
|
|
40
|
+
highest reached rung renders, so a token arm never shadows a percent tier above
|
|
41
|
+
it (0.45W is 45% of every window). The nudge latch records the rung that fired
|
|
42
|
+
and re-arms on a fall back below that rung, in that rung's own unit - a percent
|
|
43
|
+
bar would clear a 0.45W arm on the very next turn, repeating the same line.
|
|
44
|
+
Owner: [`src/lib/detection/context-tiers.ts`](../src/lib/detection/context-tiers.ts).
|
|
45
|
+
|
|
38
46
|
Owner: [`src/lib/detection/context-thresholds.ts`](../src/lib/detection/context-thresholds.ts)
|
|
39
47
|
(single home; consumers import, never restate).
|
|
40
48
|
|
package/docs/LOCAL_DEV.md
CHANGED
|
@@ -53,7 +53,6 @@ npm run format:check # prettier --check .
|
|
|
53
53
|
npm run check:docs # every in-scope .md has a status marker
|
|
54
54
|
npm run check:doc-drift # current-state docs must not reference APIs missing from code
|
|
55
55
|
npm run check:deps # layer-boundary check
|
|
56
|
-
npm run check:private-data # whole-tree private-data scan
|
|
57
56
|
```
|
|
58
57
|
|
|
59
58
|
Per-workspace variants use the workspace flag, e.g.
|
package/docs/ROADMAP.md
CHANGED
|
@@ -46,8 +46,7 @@ provenance; they are no longer work.
|
|
|
46
46
|
1. **Providers de-reference (P10b)** - RESOLVED: the Venice registration is a
|
|
47
47
|
userland catalog seam (`providers/venice-catalog.ts`, resolved from
|
|
48
48
|
`$VENICE_CATALOG_FILE` or `~/.pi/agent/venice-models.json`); the provider
|
|
49
|
-
registers only when that catalog exists
|
|
50
|
-
whole tree in `ci:check`.
|
|
49
|
+
registers only when that catalog exists.
|
|
51
50
|
2. **Version-drift cleanup** - RESOLVED: the four workspace packages declare
|
|
52
51
|
the pi peer as `"*"`; the root manifest pins the installed version
|
|
53
52
|
(`package.json`, the `@earendil-works/*` deps).
|
|
@@ -55,9 +54,10 @@ provenance; they are no longer work.
|
|
|
55
54
|
the root `CHANGELOG.md` - core keeps the bare `v` (iteration tags `v0.40.0-main.N`,
|
|
56
55
|
`package.json` `0.40.0-main.N`; release tag `v0.40.0`), every sibling tags as
|
|
57
56
|
`<workspace>-v<version>` (`telegram-v0.1.4`).
|
|
58
|
-
4. **
|
|
59
|
-
|
|
60
|
-
|
|
57
|
+
4. **Documentation path rule** - RESOLVED: docs may name product paths
|
|
58
|
+
(`~/.pi/agent/…`, `~/pi-braid/…`) and never a private home layout;
|
|
59
|
+
`check-doc-links` fails on the latter, and every in-repo reference must
|
|
60
|
+
resolve.
|
|
61
61
|
5. **Skills pack** - finish validating the five skills still marked
|
|
62
62
|
`verdict: UNVALIDATED` (`braid-reference`, `misdirection-audit`,
|
|
63
63
|
`placement-discipline`, `probe-evaluation`, `voice-replies`); keep the pack
|
package/docs/SETUP.md
CHANGED
|
@@ -298,24 +298,25 @@ The user-global file always exists; the project one is optional and belongs to p
|
|
|
298
298
|
|
|
299
299
|
`packages` is pi-native - what to load as extensions. Everything braid reads sits under the top-level `braid` key. Keys that exist in code today:
|
|
300
300
|
|
|
301
|
-
| Key | Type
|
|
302
|
-
| --------------------------------------- |
|
|
303
|
-
| `braid.modules.<ref>` | boolean
|
|
304
|
-
| `braid.suppressNudges` | boolean
|
|
305
|
-
| `braid.timezone` | IANA name
|
|
306
|
-
| `braid.enforcement.nudgeConfigs.<type>` | object
|
|
307
|
-
| `braid.memory.writeGate` | object
|
|
308
|
-
| `braid.timers.maxWakeAttempts` | integer 1..10
|
|
309
|
-
| `braid.timers.wakeAlert` | object
|
|
310
|
-
| `braid.context.contextLimitTokens` | positive number
|
|
311
|
-
| `braid.context.toolResultSizeCap` | object
|
|
312
|
-
| `braid.context.staleToolResultOffload` | object
|
|
313
|
-
| `braid.context.contextEmergencyOffload` | object
|
|
314
|
-
| `braid.
|
|
315
|
-
| `braid.telegram.
|
|
316
|
-
| `braid.telegram.
|
|
317
|
-
| `braid.
|
|
318
|
-
| `braid.contrib.<
|
|
301
|
+
| Key | Type | Default | Purpose |
|
|
302
|
+
| --------------------------------------- | ------------------------ | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
303
|
+
| `braid.modules.<ref>` | boolean | per manifest | Force-enable (`true`) or disable (`false`) an extension id or module group (`memory`, `heartbeat`); a persisted `false` removes a default-enabled extension from the boot set (see [§ Module toggling](#module-toggling)). |
|
|
304
|
+
| `braid.suppressNudges` | boolean | `false` | Silence all cognitive nudges (enforcement whispers, heartbeat suggestions, feedback reminders). |
|
|
305
|
+
| `braid.timezone` | IANA name | `Europe/Moscow` | Time zone for all braid-facing time rendering. |
|
|
306
|
+
| `braid.enforcement.nudgeConfigs.<type>` | object | built-in per-type defaults | Per-nudge-type overrides with leaf shape `braid.enforcement.nudgeConfigs.<type>.<key>`; accepted fields are `baseCooldownMs` (number), `escalateAfter` (number), and `deduplicate` (boolean). Types: `validation`, `recordFailure`, `malformed`, `memory`, `scratchpad`, `context`, `sessionSignals`. Invalid entries are logged and dropped. |
|
|
307
|
+
| `braid.memory.writeGate` | object | gate ON, 20-min cooldown, `enforce` | Review-before-write gate on episode writes; `mode: "warn"` logs decisions and writes anyway; `sites` opts individual writers out. |
|
|
308
|
+
| `braid.timers.maxWakeAttempts` | integer 1..10 | `3` | Redelivery cap for a failed timer wake before it is dropped with a visible notice. |
|
|
309
|
+
| `braid.timers.wakeAlert` | object | ON, `outcomeTimeouts: 2` | Dead-wake page: repeated outcome timeouts / exhausted redeliveries feed the watchdog's wake-delivery condition, which pages the owner out of band (telegram) once per episode plus one recovery line. `mode: "off"` disables the feed (delivery itself is unchanged); `outcomeTimeouts` is an integer 2..10 (1 would page on every normal long turn). |
|
|
310
|
+
| `braid.context.contextLimitTokens` | positive number | provider context window | The window every surface computes with (usage math, density, fallbacks, pi-core threshold compaction and overflow detection, TUI footer). A CEILING: min(contextLimitTokens, true window) when known, else the cap; re-plumbed on session start and /reload and never widens a smaller true window. The provider catalog keeps the true size. |
|
|
311
|
+
| `braid.context.toolResultSizeCap` | object | ON, 262144 chars | Capture-time cap: oversized tool results are flushed to disk and replaced by a stub. |
|
|
312
|
+
| `braid.context.staleToolResultOffload` | object | OFF | Opt-in age/size offload of stale large tool results (defaults: `minChars` 4000, `stalenessTurns` 40, `keepRecentTurns` 20, `maxOffloadCharsPerRun` 65536). |
|
|
313
|
+
| `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). |
|
|
314
|
+
| `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`. |
|
|
315
|
+
| `braid.telegram.sendMaxChars` | positive number | `4096` | Plain-text cap for `telegram_send`, re-read per call. |
|
|
316
|
+
| `braid.telegram.notifyMaxChars` | positive number | `1200` | Craft target and guard for turn-end notifications. |
|
|
317
|
+
| `braid.telegram.pauseStateFile` | path string | built-in default | Override for the `/telegram` pause-state file path. |
|
|
318
|
+
| `braid.contrib.<name>` | boolean or object | enabled / per-extension | Per-contrib-extension config - see [§ Contrib extensions](#contrib-extensions). |
|
|
319
|
+
| `braid.contrib.<extensionName>.enabled` | string[] | unset | Generic per-extension tool-enable list. The shared helper reads and writes string entries; the `/tools` surface stores its shared list in `braid.contrib._global.enabled`. |
|
|
319
320
|
|
|
320
321
|
### Worked example
|
|
321
322
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.40.
|
|
3
|
+
"version": "0.40.6",
|
|
4
4
|
"description": "Metacognitive extension suite for pi-coding-agent: enforcement, memory, reasoning, self-improvement, and structured cognitive signals.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -86,6 +86,7 @@
|
|
|
86
86
|
"pi-package",
|
|
87
87
|
"pi",
|
|
88
88
|
"pi-extension",
|
|
89
|
+
"pi-coding-agent",
|
|
89
90
|
"llm-agent",
|
|
90
91
|
"cognitive-systems",
|
|
91
92
|
"enforcement",
|
|
@@ -52,7 +52,12 @@ columns or short rows.
|
|
|
52
52
|
|
|
53
53
|
Keep the user's focus where it is unless they asked to switch context. Do
|
|
54
54
|
not close workspaces, tabs, panes, or sessions you did not create unless
|
|
55
|
-
the user explicitly asks.
|
|
55
|
+
the user explicitly asks. The one exception is the pane of the agent you
|
|
56
|
+
replaced: a process cannot close the pane it runs in, so during a
|
|
57
|
+
mastership transfer the incoming seat owns that close and runs
|
|
58
|
+
`herdr_pane close <pane>` on the outgoing seat's pane. The exception covers
|
|
59
|
+
that pane and nothing else - worker panes you did not spawn, tabs, and
|
|
60
|
+
workspaces still wait for the user's word.
|
|
56
61
|
|
|
57
62
|
## Panes: raw terminal control
|
|
58
63
|
|