pi-braid 0.43.7 → 0.43.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +39 -0
- package/TOOLS.md +1 -1
- package/build-info.json +4 -4
- package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +21 -0
- package/dist/extensions/core/skills-tool/auto-inject.js +105 -1
- package/dist/extensions/core/skills-tool/index.js +20 -2
- package/dist/extensions/core/skills-tool/loading-guidance.d.ts +4 -1
- package/dist/extensions/core/skills-tool/loading-guidance.js +4 -1
- package/dist/extensions/core/skills-tool/session-records.d.ts +107 -9
- package/dist/extensions/core/skills-tool/session-records.js +141 -5
- package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +5 -1
- package/dist/extensions/enforcement/handlers/register-tool-call.js +5 -2
- package/dist/extensions/enforcement/verification-judge.d.ts +7 -0
- package/dist/extensions/enforcement/verification-judge.js +28 -21
- package/dist/extensions/memory/session-recall/ask.d.ts +95 -0
- package/dist/extensions/memory/session-recall/ask.js +376 -0
- package/dist/extensions/memory/session-recall/corpus-index.d.ts +200 -0
- package/dist/extensions/memory/session-recall/corpus-index.js +480 -0
- package/dist/extensions/memory/session-recall/index.js +173 -21
- package/dist/extensions/memory/session-recall/search.d.ts +29 -0
- package/dist/extensions/memory/session-recall/search.js +42 -9
- package/dist/lib/ai/payload-hygiene.d.ts +3 -0
- package/dist/lib/ai/payload-hygiene.js +34 -2
- package/dist/lib/config/braid-paths.d.ts +4 -0
- package/dist/lib/config/braid-paths.js +6 -0
- package/dist/lib/config/braid-settings.d.ts +22 -0
- package/dist/lib/config/braid-settings.js +15 -0
- package/dist/lib/detection/tool-loop-detector.d.ts +95 -46
- package/dist/lib/detection/tool-loop-detector.js +288 -180
- package/dist/lib/reasoning/dreamer.d.ts +2 -1
- package/dist/lib/reasoning/dreamer.js +12 -7
- package/docs/LOCAL_DEV.md +1 -1
- package/docs/SETUP.md +1 -0
- package/package.json +1 -1
- package/src/extensions/core/AGENTS.md +3 -2
- package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
- package/src/extensions/core/skills-tool/auto-inject.ts +118 -1
- package/src/extensions/core/skills-tool/index.ts +21 -1
- package/src/extensions/core/skills-tool/loading-guidance.ts +4 -1
- package/src/extensions/core/skills-tool/session-records.ts +201 -9
- package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +5 -1
- package/src/extensions/enforcement/handlers/register-tool-call.ts +5 -2
- package/src/extensions/enforcement/verification-judge.ts +32 -25
- package/src/extensions/memory/AGENTS.md +2 -2
- package/src/extensions/memory/session-recall/AGENTS.md +92 -18
- package/src/extensions/memory/session-recall/ask.ts +435 -0
- package/src/extensions/memory/session-recall/corpus-index.ts +609 -0
- package/src/extensions/memory/session-recall/index.ts +202 -21
- package/src/extensions/memory/session-recall/search.ts +61 -10
- package/src/lib/ai/payload-hygiene.ts +47 -3
- package/src/lib/config/braid-paths.ts +7 -0
- package/src/lib/config/braid-settings.ts +42 -3
- package/src/lib/detection/AGENTS.md +8 -7
- package/src/lib/detection/tool-loop-detector.ts +339 -195
- package/src/lib/reasoning/dreamer.ts +13 -6
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.43.
|
|
3
|
+
"version": "0.43.8",
|
|
4
4
|
"description": "🥨 Braid - Metacognitive extension suite for pi coding agent: Adds memory, plan tracking, structured cognitive signals and completion checks on top of pi core loop, so long sessions keep their context and stop claiming unfinished work.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -26,7 +26,7 @@ environmental awareness, and system prompt assembly.
|
|
|
26
26
|
|
|
27
27
|
## Skills adoption contract
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
Two surfaces in `skills-tool/` put a skill body in front of the agent: the auto-inject whisper, before the prompt is answered, and the at-use line, after a call in a family a file's `governs:` declaration names has already run. The rules about whether either arrived live in one place, here, and nowhere else:
|
|
30
30
|
|
|
31
31
|
- **Delivery is observable.** `sendTrackedMessage` returns a boolean: `true` when the message was handed to `pi.sendMessage` (immediately or on the deferred triggerTurn macrotask), `false` when a suppression path dropped it (cognitive nudges disabled, per-turn/per-source flood cap, reprime cooldown). A suggestion is delivered with the park class (`delivery: "park", deliverAs: "steer"`) at source `skills-auto-inject`, which pi-core appends to the session stream - immediately when the session is idle, at the turn's end when a run is active. Both land in the session JSONL; a suppression upstream of `pi.sendMessage` reaches no stream at all.
|
|
32
32
|
- **Counters move after delivery.** `recordSkillSuggestion` runs only on a `true` return, and the cooldown/LRU bookkeeping runs after the send too, so `suggested` counts arrivals and an undelivered suggestion consumes no slot. The suggestion bypasses the per-turn whisper cap (`bypassFloodCap: true`) because prompt-builder's once-per-session hygiene whisper fires earlier in the same `before_agent_start` at the same priority and would otherwise spend the only advisory slot; the module's own budget (cooldown turns, max active suggestions, one send per turn) is the bound that keeps the whisper a whisper.
|
|
@@ -34,4 +34,5 @@ The auto-inject whisper in `skills-tool/` is the only channel that surfaces a ma
|
|
|
34
34
|
- **The trigger has a mechanical form.** `skills-tool/loading-guidance.ts` carries both the judgment form (the task entered a listed skill's domain) and the mechanical form (about to call a tool family whose word appears in a skill's name). `prompt-builder` renders that text through the `skillsLoadingText` builder as the `skills-loading` section and holds no copy of the rules; the trigger's worked examples are derived at assembly from the live tool and skill names, so the text names no pair that the running session does not have. The identity's skills prose stays one sentence.
|
|
35
35
|
- **The catalog is in the prompt.** The same section renders every visible skill as one `- name: description` row, with the read path derived from the skills' own file paths (one root for a single pack, a directory heading per pack when a catalog is installed from several). A tool call is no longer the way the agent learns which skills exist: the floor exists because the prompt that opens a resumed session carries no domain vocabulary for a matcher to rank against. `list_skills` remains the price tool (reach, headings, ranking) rather than the catalog.
|
|
36
36
|
- **Drift re-points at the floor.** When the session's own path-taking calls (`read`/`edit`/`write`) accumulate entries in a work area the floor was not rendered against, one steer line names that area and points back at the catalog. The rule and its bounds (two entries, one fire per twelve calls, three per session, quiet for the same window after any skill surface) live in `loading-guidance.ts` beside the floor text; the wiring is the `tool_result` handler in `auto-inject.ts`. Bounds are the whole design: the line is only worth its noise if it stays rare.
|
|
37
|
-
- **
|
|
37
|
+
- **The at-use line is observed, never enforced.** With `braid.skills.inform` set to `inform` (default `off`), a `tool_result` whose call **succeeded**, whose tool name yields a family token some visible cached skill declares with `governs:`, and whose obligation row carries no `read` leg emits one steer line naming the file path and the family. It runs after the result exists, returns no replacement, and refuses, delays and rewrites nothing: any gating change can only make it quieter, which is the property that separates it from a refusal gate. The payload is derived from the declaration and the catalogue entry only (the skill's own `filePath`, the token the call's name yields), so no skill name is invented in code and no tool argument is echoed. Once per session per skill, suppressed by the same obligation record the legs write (its `informed` leg), silenced by a read at any point, and hidden skills are never named. `skill_stats` reports it as `inform` from the store: `undecided` below twenty informs, `beats` only when the lower Wilson bound clears the suggestion channel's 18.8% pair conversion, `noise` otherwise.
|
|
38
|
+
- **Applicability is recorded, never enforced.** The counters cannot tell a skill that applied and was ignored from one that never applied, and the sessions that read nothing are mostly sessions no phrase matches. `skills-tool/applicability.ts` decides that difference from the skill's own declaration (the trigger phrases its file carries: frontmatter `trigger:`/`triggers:`, a `## trigger:` body heading, a description `Triggers:` tail), never from the ranking heuristic, with the injector's occurrence boundary and a clause-scoped negation read, so a phrase inside "do not research this" is not a condition met. The verdict is `read` (condition held and a detected read followed), `ignored` (condition held and no read followed), or `not-applicable` (derived: the census's `evaluated` minus the verdict rows); a skill whose file declares no phrase is named `undeclared` rather than judged either way. It reaches disk as `kind: "applicability"` rows in the per-session store (one verdict row per applicable skill keyed on `sessionId` + `skill`, one census row per session) and out through `skill_stats`. It is an observer: it writes no delivery, slot, cooldown, counter or prompt, and it owns no compliance leg. `suggested`/`listed`/`informed`/`read`/`applied` belong to the record that owns each skill's declared tool family; the verdict row joins it on the skill name.
|
|
@@ -128,7 +128,7 @@ export const TOOL_GUIDELINES: Record<string, string> = {
|
|
|
128
128
|
|
|
129
129
|
// ── session-recall (default-enabled) ──
|
|
130
130
|
session:
|
|
131
|
-
"when: prior-work context needed across sessions (search/query/analyze/stats); args: action + query/sessionPath; caveat: project-scoped by default",
|
|
131
|
+
"when: prior-work context needed across sessions (search/query/analyze/stats), or a question about what was said or decided earlier (ask, which cites project, session, line and time); args: action + query/sessionPath; caveat: project-scoped by default, and ask refuses when the corpus index cannot answer",
|
|
132
132
|
|
|
133
133
|
// ── error-tracking (opt-in) ──
|
|
134
134
|
error:
|
|
@@ -95,6 +95,15 @@
|
|
|
95
95
|
* and never within that window of a suggestion or a SKILL.md read). The
|
|
96
96
|
* rule and its bounds live in loading-guidance.ts beside the floor text
|
|
97
97
|
* the line points at; this module only wires them to tool results.
|
|
98
|
+
* 11. At-use inform (`braid.skills.inform`, default off): a COMPLETED call in
|
|
99
|
+
* a family a visible skill's file declares with `governs:` and no read of
|
|
100
|
+
* that body on the session record gets one steer line naming the file and
|
|
101
|
+
* the obligation. Once per session per skill, suppressed by the same
|
|
102
|
+
* obligation record the legs already write (the `informed` leg). It
|
|
103
|
+
* observes a call that already ran and can only add a line: no refusal,
|
|
104
|
+
* no delay, and no rewrite of the result it arrives after. This is the
|
|
105
|
+
* timed alternative to refusing the call, and the difference is the whole
|
|
106
|
+
* point of it.
|
|
98
107
|
*
|
|
99
108
|
* Structure matches the existing steer whisper pattern used by topic-drift,
|
|
100
109
|
* turn-outcome, compaction-retry, context-lifecycle, and others.
|
|
@@ -128,6 +137,8 @@ import type { SkillApplicabilityVerdict } from "./applicability.js";
|
|
|
128
137
|
import { triggerMatches } from "./skill-triggers.js";
|
|
129
138
|
import type { TriggerSource } from "./skill-triggers.js";
|
|
130
139
|
import { toolFamilyToken } from "./skill-families.js";
|
|
140
|
+
import { getSkillsInformMode } from "../../../lib/config/braid-settings.js";
|
|
141
|
+
import type { SkillsInformMode } from "../../../lib/config/braid-settings.js";
|
|
131
142
|
import {
|
|
132
143
|
advanceDrift,
|
|
133
144
|
driftDirectoryFor,
|
|
@@ -296,6 +307,12 @@ interface AutoInjectState {
|
|
|
296
307
|
applicability: ApplicabilityState;
|
|
297
308
|
/** What the session did with each skill body it met (see ObligationState). */
|
|
298
309
|
obligations: ObligationState;
|
|
310
|
+
/**
|
|
311
|
+
* The resolved `braid.skills.inform` policy, read once per session. A
|
|
312
|
+
* settings edit takes effect in the next session, the same way the session
|
|
313
|
+
* profile does, so a tool_result never reads and parses settings.json.
|
|
314
|
+
*/
|
|
315
|
+
informMode?: SkillsInformMode;
|
|
299
316
|
}
|
|
300
317
|
|
|
301
318
|
/**
|
|
@@ -1305,6 +1322,7 @@ function legsFor(state: AutoInjectState, name: string): ObligationLegs {
|
|
|
1305
1322
|
skill: name,
|
|
1306
1323
|
suggested: false,
|
|
1307
1324
|
listed: false,
|
|
1325
|
+
informed: false,
|
|
1308
1326
|
read: false,
|
|
1309
1327
|
called: false,
|
|
1310
1328
|
applied: false,
|
|
@@ -1323,7 +1341,14 @@ function legsFor(state: AutoInjectState, name: string): ObligationLegs {
|
|
|
1323
1341
|
function appendObligationRow(ctx: ExtensionContext, state: AutoInjectState, name: string): void {
|
|
1324
1342
|
const legs = state.obligations.legs.get(name);
|
|
1325
1343
|
if (!legs) return;
|
|
1326
|
-
const signature = [
|
|
1344
|
+
const signature = [
|
|
1345
|
+
legs.suggested,
|
|
1346
|
+
legs.listed,
|
|
1347
|
+
legs.informed,
|
|
1348
|
+
legs.read,
|
|
1349
|
+
legs.called,
|
|
1350
|
+
legs.applied,
|
|
1351
|
+
]
|
|
1327
1352
|
.map((flag) => (flag ? "1" : "0"))
|
|
1328
1353
|
.join("");
|
|
1329
1354
|
if (state.obligations.written.get(name) === signature) return;
|
|
@@ -1441,6 +1466,95 @@ function stepFamilyCalls(
|
|
|
1441
1466
|
}
|
|
1442
1467
|
}
|
|
1443
1468
|
|
|
1469
|
+
/**
|
|
1470
|
+
* The at-use line: the payload names the file and the obligation, and nothing
|
|
1471
|
+
* else.
|
|
1472
|
+
*
|
|
1473
|
+
* Both facts are derivable from the declaration and the catalog entry. The path
|
|
1474
|
+
* is the cached skill's own file path, never constructed; the family is the
|
|
1475
|
+
* token the call's own name yields, which is the same token the declaration is
|
|
1476
|
+
* written in. No skill name is invented in code, no tool argument is echoed,
|
|
1477
|
+
* and there is nothing here for a model to reconcile with the result it just
|
|
1478
|
+
* received. Pure.
|
|
1479
|
+
*/
|
|
1480
|
+
export function formatInformPayload(filePath: string, family: string): string {
|
|
1481
|
+
return (
|
|
1482
|
+
`[SKILL INFORM] \`${filePath}\` governs the \`${family}\` tool family; ` +
|
|
1483
|
+
`a call in it just ran, and that file has not been read this session. ` +
|
|
1484
|
+
`Read it before the next call in the family.`
|
|
1485
|
+
);
|
|
1486
|
+
}
|
|
1487
|
+
|
|
1488
|
+
/**
|
|
1489
|
+
* Inform at use: a COMPLETED call landed in a tool family a visible skill's
|
|
1490
|
+
* file declares with `governs:`, and no read of that body is on the session
|
|
1491
|
+
* record. One steer line, once per session per skill.
|
|
1492
|
+
*
|
|
1493
|
+
* This is the timed alternative to refusing the call. It runs after the result
|
|
1494
|
+
* exists, it touches no result, and the only thing it can do is add a line to
|
|
1495
|
+
* the stream; every gating decision below can only make it quieter. The
|
|
1496
|
+
* suppression is the obligation record itself (the `informed` leg, beside the
|
|
1497
|
+
* `read` leg), not a parallel set, so the record that says what the session did
|
|
1498
|
+
* and the record that stops a second line are one row.
|
|
1499
|
+
*
|
|
1500
|
+
* The applied leg counts a failed call because a refusal would fire before the
|
|
1501
|
+
* tool ran and could not know the outcome; this line does not, because its
|
|
1502
|
+
* premise is a call that ran in a family the body governs.
|
|
1503
|
+
*/
|
|
1504
|
+
function stepInform(
|
|
1505
|
+
pi: ExtensionAPI,
|
|
1506
|
+
ctx: ExtensionContext,
|
|
1507
|
+
state: AutoInjectState,
|
|
1508
|
+
ev: ToolResultEvent,
|
|
1509
|
+
): void {
|
|
1510
|
+
state.informMode ??= getSkillsInformMode();
|
|
1511
|
+
if (state.informMode !== "inform") return;
|
|
1512
|
+
if (!ev?.toolName) return;
|
|
1513
|
+
if (ev.isError) return;
|
|
1514
|
+
const family = toolFamilyToken(ev.toolName);
|
|
1515
|
+
if (!family) return;
|
|
1516
|
+
for (const skill of _skillsCache) {
|
|
1517
|
+
// The at-use line is an advertisement with a path: a body the prompt
|
|
1518
|
+
// deliberately hides from the model must not be named by it either.
|
|
1519
|
+
if (skill.disableModelInvocation) continue;
|
|
1520
|
+
if (!skill.families?.length || !skill.families.includes(family)) continue;
|
|
1521
|
+
const held = state.obligations.legs.get(skill.name);
|
|
1522
|
+
if (held?.read) continue; // the body is in context; the obligation is met
|
|
1523
|
+
if (held?.informed) continue; // one line per session per skill
|
|
1524
|
+
const delivered = sendTrackedMessage(
|
|
1525
|
+
pi,
|
|
1526
|
+
{
|
|
1527
|
+
customType: "skills-inform",
|
|
1528
|
+
content: [{ type: "text" as const, text: formatInformPayload(skill.filePath, family) }],
|
|
1529
|
+
display: true,
|
|
1530
|
+
details: {
|
|
1531
|
+
[BRAID_INJECTED]: true,
|
|
1532
|
+
[BRAID_SOURCE]: "skills-auto-inject",
|
|
1533
|
+
skill: skill.name,
|
|
1534
|
+
family,
|
|
1535
|
+
},
|
|
1536
|
+
},
|
|
1537
|
+
{ delivery: "park", deliverAs: "steer" },
|
|
1538
|
+
{ type: "context", source: "skills-auto-inject" },
|
|
1539
|
+
// The module's own budget is the bound: one line per session per skill,
|
|
1540
|
+
// and only on a call in a family the body itself declares. A flood cap
|
|
1541
|
+
// would drop the line in exactly the call it exists for.
|
|
1542
|
+
{ bypassFloodCap: true },
|
|
1543
|
+
);
|
|
1544
|
+
if (!delivered) {
|
|
1545
|
+
log.debug("[skills-auto-inject] at-use line suppressed before delivery; not counted");
|
|
1546
|
+
continue;
|
|
1547
|
+
}
|
|
1548
|
+
const legs = legsFor(state, skill.name);
|
|
1549
|
+
legs.informed = true;
|
|
1550
|
+
appendObligationRow(ctx, state, skill.name);
|
|
1551
|
+
// The line is a skill surface: the drift trigger stays quiet for its
|
|
1552
|
+
// window, because the pointer it exists to supply has just landed.
|
|
1553
|
+
noteDriftSurface(state.drift);
|
|
1554
|
+
log.info(`[skills-auto-inject] at-use line for "${skill.name}" (family ${family})`);
|
|
1555
|
+
}
|
|
1556
|
+
}
|
|
1557
|
+
|
|
1444
1558
|
/**
|
|
1445
1559
|
* Fire the drift line when the work has moved into a new work area (the rule
|
|
1446
1560
|
* and its bounds live in loading-guidance.ts, beside the floor text the line
|
|
@@ -1517,6 +1631,9 @@ export function registerAutoInject(pi: ExtensionAPI): void {
|
|
|
1517
1631
|
// detector so a SKILL.md read of the very tool call in flight is already
|
|
1518
1632
|
// on record when the family is looked up.
|
|
1519
1633
|
stepFamilyCalls(ctx, state, ev);
|
|
1634
|
+
// The at-use line runs after both: it needs the read leg (a read in this
|
|
1635
|
+
// very result silences it) and it does not depend on the applied leg.
|
|
1636
|
+
stepInform(pi, ctx, state, ev);
|
|
1520
1637
|
stepDrift(pi, ctx, state, ev);
|
|
1521
1638
|
} catch {
|
|
1522
1639
|
// best-effort — never break the tool loop over a counter or a whisper
|
|
@@ -36,7 +36,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
|
|
|
36
36
|
import { Type } from "typebox";
|
|
37
37
|
import type { Static } from "typebox";
|
|
38
38
|
import { createLogger } from "../../../lib/core/logger.js";
|
|
39
|
-
import { getSkillsRankingMode } from "../../../lib/config/braid-settings.js";
|
|
39
|
+
import { getSkillsInformMode, getSkillsRankingMode } from "../../../lib/config/braid-settings.js";
|
|
40
40
|
import type { SkillsRankingMode } from "../../../lib/config/braid-settings.js";
|
|
41
41
|
import {
|
|
42
42
|
registerAutoInject,
|
|
@@ -58,6 +58,7 @@ import {
|
|
|
58
58
|
readSkillReach,
|
|
59
59
|
} from "./reach.js";
|
|
60
60
|
import {
|
|
61
|
+
getInformRate,
|
|
61
62
|
getMonthlyAdoptionRollup,
|
|
62
63
|
getObligationRate,
|
|
63
64
|
getSessionApplicability,
|
|
@@ -477,6 +478,13 @@ export default function skillsToolExtension(pi: ExtensionAPI): void {
|
|
|
477
478
|
// obligation row at all: a build that predates the leg reads the same
|
|
478
479
|
// sessions and must see the same payload.
|
|
479
480
|
const obligationRate = getObligationRate();
|
|
481
|
+
// The at-use line's counters, folded from the same store as the channel
|
|
482
|
+
// arm beside them. Absent when the mode is off and no row was ever
|
|
483
|
+
// written, so a reader of a pre-inform store is unchanged.
|
|
484
|
+
const informRate = getInformRate();
|
|
485
|
+
const informMode = getSkillsInformMode();
|
|
486
|
+
const inform =
|
|
487
|
+
informMode !== "off" || informRate ? { mode: informMode, ...informRate } : undefined;
|
|
480
488
|
return {
|
|
481
489
|
content: [
|
|
482
490
|
{
|
|
@@ -500,6 +508,7 @@ export default function skillsToolExtension(pi: ExtensionAPI): void {
|
|
|
500
508
|
...(applicability ? { applicability } : {}),
|
|
501
509
|
...(obligations ? { obligations } : {}),
|
|
502
510
|
...(obligationRate ? { obligationRate } : {}),
|
|
511
|
+
...(inform ? { inform } : {}),
|
|
503
512
|
discovery: {
|
|
504
513
|
// Whether the stock skill catalog sits in the persisted
|
|
505
514
|
// transcript (it re-enters via pi's post-compaction
|
|
@@ -531,6 +540,17 @@ export default function skillsToolExtension(pi: ExtensionAPI): void {
|
|
|
531
540
|
}
|
|
532
541
|
: {}),
|
|
533
542
|
...(obligationRate ? { obligationRate } : {}),
|
|
543
|
+
...(inform
|
|
544
|
+
? {
|
|
545
|
+
inform: {
|
|
546
|
+
mode: informMode,
|
|
547
|
+
informs: informRate?.informs ?? 0,
|
|
548
|
+
readFollowed: informRate?.readFollowed ?? 0,
|
|
549
|
+
conversion: informRate?.conversion ?? 0,
|
|
550
|
+
verdict: informRate?.verdict ?? "undecided",
|
|
551
|
+
},
|
|
552
|
+
}
|
|
553
|
+
: {}),
|
|
534
554
|
},
|
|
535
555
|
};
|
|
536
556
|
},
|
|
@@ -346,7 +346,10 @@ export function recordDriftDrop(tracker: DriftTracker): void {
|
|
|
346
346
|
tracker.entries = {};
|
|
347
347
|
}
|
|
348
348
|
|
|
349
|
-
/**
|
|
349
|
+
/**
|
|
350
|
+
* Note that a skill surface (a suggestion, an at-use line, or a SKILL.md read)
|
|
351
|
+
* just landed.
|
|
352
|
+
*/
|
|
350
353
|
export function noteDriftSurface(tracker: DriftTracker): void {
|
|
351
354
|
tracker.lastSurface = tracker.calls;
|
|
352
355
|
}
|
|
@@ -628,9 +628,10 @@ export function getSessionApplicability(
|
|
|
628
628
|
* no family; most declare none, and an obligation that names no family is
|
|
629
629
|
* satisfied by the read alone.
|
|
630
630
|
*
|
|
631
|
-
* `suggested` and `
|
|
632
|
-
* this session (a delivered suggestion, a list_skills row
|
|
633
|
-
* "was it offered" half of adoption, which the
|
|
631
|
+
* `suggested`, `listed` and `informed` are the surfaces that offered the body
|
|
632
|
+
* in this session (a delivered suggestion, a list_skills row, a delivered
|
|
633
|
+
* at-use line); they carry the "was it offered" half of adoption, which the
|
|
634
|
+
* call facts cannot.
|
|
634
635
|
*/
|
|
635
636
|
export interface ObligationLegRecord {
|
|
636
637
|
kind: "obligation";
|
|
@@ -641,16 +642,19 @@ export interface ObligationLegRecord {
|
|
|
641
642
|
skill: string;
|
|
642
643
|
suggested: boolean;
|
|
643
644
|
listed: boolean;
|
|
645
|
+
/** An at-use inform was DELIVERED for this body in this session. */
|
|
646
|
+
informed: boolean;
|
|
644
647
|
read: boolean;
|
|
645
648
|
called: boolean;
|
|
646
649
|
applied: boolean;
|
|
647
650
|
}
|
|
648
651
|
|
|
649
|
-
/** A record's
|
|
652
|
+
/** A record's six legs, read back as one row per skill. */
|
|
650
653
|
export interface ObligationLegs {
|
|
651
654
|
skill: string;
|
|
652
655
|
suggested: boolean;
|
|
653
656
|
listed: boolean;
|
|
657
|
+
informed: boolean;
|
|
654
658
|
read: boolean;
|
|
655
659
|
called: boolean;
|
|
656
660
|
applied: boolean;
|
|
@@ -683,6 +687,7 @@ export function normalizeObligationRecord(raw: unknown): ObligationLegRecord | n
|
|
|
683
687
|
skill: r.skill,
|
|
684
688
|
suggested: r.suggested === true,
|
|
685
689
|
listed: r.listed === true,
|
|
690
|
+
informed: r.informed === true,
|
|
686
691
|
read: r.read === true,
|
|
687
692
|
called: r.called === true,
|
|
688
693
|
applied: r.applied === true,
|
|
@@ -717,11 +722,11 @@ export function readObligationRecords(
|
|
|
717
722
|
}
|
|
718
723
|
|
|
719
724
|
/**
|
|
720
|
-
* Fold a session's obligation rows into one record: the
|
|
721
|
-
*
|
|
722
|
-
*
|
|
723
|
-
*
|
|
724
|
-
*
|
|
725
|
+
* Fold a session's obligation rows into one record: the legs OR across every
|
|
726
|
+
* row, so a row that saw one leg never erases a leg a later row did not have.
|
|
727
|
+
* `called`/`applied` are written once per skill, so the OR is exact rather
|
|
728
|
+
* than convenient. A torn or duplicated row folds; a malformed one is dropped
|
|
729
|
+
* at normalize, before this sees it.
|
|
725
730
|
*/
|
|
726
731
|
export function foldObligationRecords(records: ObligationLegRecord[]): SessionObligation[] {
|
|
727
732
|
const bySession = new Map<string, SessionObligation>();
|
|
@@ -747,6 +752,7 @@ export function foldObligationRecords(records: ObligationLegRecord[]): SessionOb
|
|
|
747
752
|
skill: rec.skill,
|
|
748
753
|
suggested: rec.suggested,
|
|
749
754
|
listed: rec.listed,
|
|
755
|
+
informed: rec.informed,
|
|
750
756
|
read: rec.read,
|
|
751
757
|
called: rec.called,
|
|
752
758
|
applied: rec.applied,
|
|
@@ -755,6 +761,7 @@ export function foldObligationRecords(records: ObligationLegRecord[]): SessionOb
|
|
|
755
761
|
}
|
|
756
762
|
held.suggested = held.suggested || rec.suggested;
|
|
757
763
|
held.listed = held.listed || rec.listed;
|
|
764
|
+
held.informed = held.informed || rec.informed;
|
|
758
765
|
held.read = held.read || rec.read;
|
|
759
766
|
held.called = held.called || rec.called;
|
|
760
767
|
held.applied = held.applied || rec.applied;
|
|
@@ -780,6 +787,7 @@ export function recordObligationLegs(
|
|
|
780
787
|
skill: legs.skill,
|
|
781
788
|
suggested: legs.suggested,
|
|
782
789
|
listed: legs.listed,
|
|
790
|
+
informed: legs.informed,
|
|
783
791
|
read: legs.read,
|
|
784
792
|
called: legs.called,
|
|
785
793
|
applied: legs.applied,
|
|
@@ -863,6 +871,7 @@ export function judgeSessionObligations(
|
|
|
863
871
|
skill,
|
|
864
872
|
suggested: false,
|
|
865
873
|
listed: false,
|
|
874
|
+
informed: false,
|
|
866
875
|
read: false,
|
|
867
876
|
called: false,
|
|
868
877
|
applied: false,
|
|
@@ -988,6 +997,189 @@ export function getObligationRate(
|
|
|
988
997
|
}
|
|
989
998
|
}
|
|
990
999
|
|
|
1000
|
+
// The at-use inform, measured against the suggestion channel
|
|
1001
|
+
|
|
1002
|
+
/**
|
|
1003
|
+
* The suggestion channel's pair conversion as published from session-file
|
|
1004
|
+
* mining: 95 read-followed pairs out of 506 delivered ones, Wilson 15.6-22.4.
|
|
1005
|
+
*
|
|
1006
|
+
* It is a measurement constant, not a target: it stands in as the comparison
|
|
1007
|
+
* arm only while the same store carries too few suggested pairs of its own to
|
|
1008
|
+
* stand on its own (see INFORM_DECISION_MIN_PAIRS). A two-pair store arm that
|
|
1009
|
+
* happens to have converted nothing is not a baseline; it is a sample. The
|
|
1010
|
+
* moment the store holds the floor of suggested pairs, their own fold answers
|
|
1011
|
+
* and this number is not read.
|
|
1012
|
+
*/
|
|
1013
|
+
export const CHANNEL_PUBLISHED_CONVERSION = 0.188;
|
|
1014
|
+
|
|
1015
|
+
/** Wilson 95% bounds for that published figure, as proportions. */
|
|
1016
|
+
export const CHANNEL_PUBLISHED_INTERVAL: WilsonInterval = { lower: 0.156, upper: 0.224 };
|
|
1017
|
+
|
|
1018
|
+
/**
|
|
1019
|
+
* Informs needed before the comparison decides anything. Below this the
|
|
1020
|
+
* answer is "undecided": a verdict from a handful of pairs would be a verdict
|
|
1021
|
+
* about the sample, and the report's decision rule says so in writing before
|
|
1022
|
+
* the first inform lands. The same floor governs the comparison arm: a store
|
|
1023
|
+
* carrying fewer suggested pairs than this is not a baseline to beat.
|
|
1024
|
+
*/
|
|
1025
|
+
export const INFORM_DECISION_MIN_PAIRS = 20;
|
|
1026
|
+
|
|
1027
|
+
/** A two-sided interval on a proportion, both ends in 0-1. */
|
|
1028
|
+
export interface WilsonInterval {
|
|
1029
|
+
lower: number;
|
|
1030
|
+
upper: number;
|
|
1031
|
+
}
|
|
1032
|
+
|
|
1033
|
+
/**
|
|
1034
|
+
* Wilson score interval for k successes in n trials (95% by default). Chosen
|
|
1035
|
+
* over the normal approximation because the inform population is small and a
|
|
1036
|
+
* small-sample interval is the only one that can say "undecided" honestly.
|
|
1037
|
+
* Returns zeros for n = 0. Pure.
|
|
1038
|
+
*/
|
|
1039
|
+
export function wilsonInterval(successes: number, total: number, z = 1.959963985): WilsonInterval {
|
|
1040
|
+
if (!total || total < 0) return { lower: 0, upper: 0 };
|
|
1041
|
+
const p = Math.min(1, Math.max(0, successes / total));
|
|
1042
|
+
const denominator = 1 + (z * z) / total;
|
|
1043
|
+
const centre = (p + (z * z) / (2 * total)) / denominator;
|
|
1044
|
+
const half = (z * Math.sqrt((p * (1 - p)) / total + (z * z) / (4 * total * total))) / denominator;
|
|
1045
|
+
return {
|
|
1046
|
+
lower: round4(Math.max(0, centre - half)),
|
|
1047
|
+
upper: round4(Math.min(1, centre + half)),
|
|
1048
|
+
};
|
|
1049
|
+
}
|
|
1050
|
+
|
|
1051
|
+
/** One skill's at-use pairs: informs delivered, and how many a read followed. */
|
|
1052
|
+
export interface InformSkillRow {
|
|
1053
|
+
skill: string;
|
|
1054
|
+
informs: number;
|
|
1055
|
+
readFollowed: number;
|
|
1056
|
+
}
|
|
1057
|
+
|
|
1058
|
+
/** Where the comparison arm's number came from. */
|
|
1059
|
+
export type ChannelBaselineSource = "store" | "published";
|
|
1060
|
+
|
|
1061
|
+
/**
|
|
1062
|
+
* The at-use line's numbers beside the suggestion channel's, same store.
|
|
1063
|
+
*
|
|
1064
|
+
* A pair is (session, skill). An inform pair carries `informed: true`; it
|
|
1065
|
+
* converted when that session also carries the `read` leg for the same skill.
|
|
1066
|
+
* The read leg is ordered by construction here: a read silences the inform, so
|
|
1067
|
+
* a pair that has both legs can only have read after the line landed.
|
|
1068
|
+
*/
|
|
1069
|
+
export interface InformRate {
|
|
1070
|
+
/** Inform pairs in the store. */
|
|
1071
|
+
informs: number;
|
|
1072
|
+
/** Of those, pairs whose session carries the read leg. */
|
|
1073
|
+
readFollowed: number;
|
|
1074
|
+
/** readFollowed / informs, 4 decimals; 0 when no inform. */
|
|
1075
|
+
conversion: number;
|
|
1076
|
+
/** Wilson 95% bounds on `conversion`. */
|
|
1077
|
+
ci: WilsonInterval;
|
|
1078
|
+
/** Per skill, in first-seen order (only skills with an inform). */
|
|
1079
|
+
skills: InformSkillRow[];
|
|
1080
|
+
/** The comparison arm: the same fold's suggested pairs. */
|
|
1081
|
+
channel: {
|
|
1082
|
+
pairs: number;
|
|
1083
|
+
readFollowed: number;
|
|
1084
|
+
conversion: number;
|
|
1085
|
+
ci: WilsonInterval;
|
|
1086
|
+
source: ChannelBaselineSource;
|
|
1087
|
+
};
|
|
1088
|
+
/** conversion - channel.conversion, in percentage points, 2 decimals. */
|
|
1089
|
+
gapPoints: number;
|
|
1090
|
+
/** False below INFORM_DECISION_MIN_PAIRS: no verdict is derivable. */
|
|
1091
|
+
decidable: boolean;
|
|
1092
|
+
/** undecided | beats | noise (see the report's pre-registered rule). */
|
|
1093
|
+
verdict: "undecided" | "beats" | "noise";
|
|
1094
|
+
}
|
|
1095
|
+
|
|
1096
|
+
/**
|
|
1097
|
+
* Fold the obligation rows into the at-use rate and the channel arm beside it.
|
|
1098
|
+
* Pure.
|
|
1099
|
+
*
|
|
1100
|
+
* The rule, applied literally: fewer than the floor is undecided; at the floor
|
|
1101
|
+
* the inform beats the channel only when its point estimate is above the
|
|
1102
|
+
* channel's AND its lower Wilson bound is above it too. Anything else at the
|
|
1103
|
+
* floor is noise, which is the falsifier firing rather than a neutral result.
|
|
1104
|
+
*/
|
|
1105
|
+
export function computeInformRate(obligations: SessionObligation[]): InformRate {
|
|
1106
|
+
let informs = 0;
|
|
1107
|
+
let informRead = 0;
|
|
1108
|
+
let channelPairs = 0;
|
|
1109
|
+
let channelRead = 0;
|
|
1110
|
+
const bySkill = new Map<string, InformSkillRow>();
|
|
1111
|
+
for (const session of obligations) {
|
|
1112
|
+
for (const legs of session.skills) {
|
|
1113
|
+
if (legs.suggested) {
|
|
1114
|
+
channelPairs++;
|
|
1115
|
+
if (legs.read) channelRead++;
|
|
1116
|
+
}
|
|
1117
|
+
if (!legs.informed) continue;
|
|
1118
|
+
informs++;
|
|
1119
|
+
if (legs.read) informRead++;
|
|
1120
|
+
let row = bySkill.get(legs.skill);
|
|
1121
|
+
if (!row) {
|
|
1122
|
+
row = { skill: legs.skill, informs: 0, readFollowed: 0 };
|
|
1123
|
+
bySkill.set(legs.skill, row);
|
|
1124
|
+
}
|
|
1125
|
+
row.informs++;
|
|
1126
|
+
if (legs.read) row.readFollowed++;
|
|
1127
|
+
}
|
|
1128
|
+
}
|
|
1129
|
+
const conversion = informs ? round4(informRead / informs) : 0;
|
|
1130
|
+
const channel =
|
|
1131
|
+
channelPairs >= INFORM_DECISION_MIN_PAIRS
|
|
1132
|
+
? {
|
|
1133
|
+
pairs: channelPairs,
|
|
1134
|
+
readFollowed: channelRead,
|
|
1135
|
+
conversion: round4(channelRead / channelPairs),
|
|
1136
|
+
ci: wilsonInterval(channelRead, channelPairs),
|
|
1137
|
+
source: "store" as ChannelBaselineSource,
|
|
1138
|
+
}
|
|
1139
|
+
: {
|
|
1140
|
+
pairs: channelPairs,
|
|
1141
|
+
readFollowed: channelRead,
|
|
1142
|
+
conversion: CHANNEL_PUBLISHED_CONVERSION,
|
|
1143
|
+
ci: CHANNEL_PUBLISHED_INTERVAL,
|
|
1144
|
+
source: "published" as ChannelBaselineSource,
|
|
1145
|
+
};
|
|
1146
|
+
const ci = wilsonInterval(informRead, informs);
|
|
1147
|
+
const decidable = informs >= INFORM_DECISION_MIN_PAIRS;
|
|
1148
|
+
const verdict: InformRate["verdict"] = !decidable
|
|
1149
|
+
? "undecided"
|
|
1150
|
+
: conversion > channel.conversion && ci.lower > channel.conversion
|
|
1151
|
+
? "beats"
|
|
1152
|
+
: "noise";
|
|
1153
|
+
return {
|
|
1154
|
+
informs,
|
|
1155
|
+
readFollowed: informRead,
|
|
1156
|
+
conversion,
|
|
1157
|
+
ci,
|
|
1158
|
+
skills: [...bySkill.values()],
|
|
1159
|
+
channel,
|
|
1160
|
+
gapPoints: Math.round((conversion - channel.conversion) * 10000) / 100,
|
|
1161
|
+
decidable,
|
|
1162
|
+
verdict,
|
|
1163
|
+
};
|
|
1164
|
+
}
|
|
1165
|
+
|
|
1166
|
+
/**
|
|
1167
|
+
* The store-wide at-use rate, or undefined when the store carries no inform row
|
|
1168
|
+
* at all. Undefined keeps every existing `skill_stats` payload byte-identical
|
|
1169
|
+
* for a build or an install that never emitted one.
|
|
1170
|
+
*/
|
|
1171
|
+
export function getInformRate(options: { storePath?: string } = {}): InformRate | undefined {
|
|
1172
|
+
try {
|
|
1173
|
+
const storePath = options.storePath ?? getSkillsSessionsFilePath();
|
|
1174
|
+
const records = readObligationRecords(storePath);
|
|
1175
|
+
if (!records.some((rec) => rec.informed)) return undefined;
|
|
1176
|
+
return computeInformRate(foldObligationRecords(records));
|
|
1177
|
+
} catch (err) {
|
|
1178
|
+
reportRecordFailure(err);
|
|
1179
|
+
return undefined;
|
|
1180
|
+
}
|
|
1181
|
+
}
|
|
1182
|
+
|
|
991
1183
|
/** Adoption numbers for one profile in one month. */
|
|
992
1184
|
export interface ProfileAdoption {
|
|
993
1185
|
/** Sessions active in the month (records with a turn). */
|
|
@@ -9,6 +9,7 @@ import { emitSignal } from "../../../../lib/reasoning/belief-policy-engine.js";
|
|
|
9
9
|
import { dream } from "../../../../lib/reasoning/dreamer.js";
|
|
10
10
|
import { recordAdvice } from "../../../../lib/reasoning/advice-tracker.js";
|
|
11
11
|
import { tryClaim } from "../../../../lib/enforcement/turn-dedup.js";
|
|
12
|
+
import { getToolLoopState } from "../../../../lib/detection/tool-loop-detector.js";
|
|
12
13
|
import { getState } from "../../state.js";
|
|
13
14
|
|
|
14
15
|
const log = createLogger("enforcement:dreamer");
|
|
@@ -25,7 +26,10 @@ export async function dreamerHandler(pi: any, _event: any, ctx: ExtensionContext
|
|
|
25
26
|
}
|
|
26
27
|
}
|
|
27
28
|
|
|
28
|
-
|
|
29
|
+
// The loop path reads the detector's own recorded calls (tool + argument
|
|
30
|
+
// identity); gs.toolLog is names only and cannot distinguish one call
|
|
31
|
+
// repeated from many different calls under one name.
|
|
32
|
+
const dreamAdvice = dream(ctx, gs.toolLog, historicalSequences, getToolLoopState(ctx).history);
|
|
29
33
|
if (!dreamAdvice) return;
|
|
30
34
|
|
|
31
35
|
emitSignal(ctx, "stability", "predicted-decline", "info", false, {
|
|
@@ -46,9 +46,12 @@ export function registerToolCallHandler(pi: ExtensionAPI): void {
|
|
|
46
46
|
|
|
47
47
|
recordToolCall(toolName, ctx);
|
|
48
48
|
|
|
49
|
-
// Record tool call for tool-loop-detector (per-turn tool sets)
|
|
49
|
+
// Record tool call for tool-loop-detector (per-turn tool sets). The
|
|
50
|
+
// arguments ride along: a loop is the same call repeating, and the tool
|
|
51
|
+
// name alone cannot say whether sixteen `bash` calls are sixteen commands
|
|
52
|
+
// or one command sixteen times.
|
|
50
53
|
const loopState = getToolLoopState(ctx);
|
|
51
|
-
recordLoopToolCall(loopState, toolName);
|
|
54
|
+
recordLoopToolCall(loopState, toolName, input);
|
|
52
55
|
recordToolInput(toolName, input, getState(ctx));
|
|
53
56
|
|
|
54
57
|
if (toolName === "bash") {
|