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.
Files changed (56) hide show
  1. package/CHANGELOG.md +39 -0
  2. package/TOOLS.md +1 -1
  3. package/build-info.json +4 -4
  4. package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
  5. package/dist/extensions/core/skills-tool/auto-inject.d.ts +21 -0
  6. package/dist/extensions/core/skills-tool/auto-inject.js +105 -1
  7. package/dist/extensions/core/skills-tool/index.js +20 -2
  8. package/dist/extensions/core/skills-tool/loading-guidance.d.ts +4 -1
  9. package/dist/extensions/core/skills-tool/loading-guidance.js +4 -1
  10. package/dist/extensions/core/skills-tool/session-records.d.ts +107 -9
  11. package/dist/extensions/core/skills-tool/session-records.js +141 -5
  12. package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +5 -1
  13. package/dist/extensions/enforcement/handlers/register-tool-call.js +5 -2
  14. package/dist/extensions/enforcement/verification-judge.d.ts +7 -0
  15. package/dist/extensions/enforcement/verification-judge.js +28 -21
  16. package/dist/extensions/memory/session-recall/ask.d.ts +95 -0
  17. package/dist/extensions/memory/session-recall/ask.js +376 -0
  18. package/dist/extensions/memory/session-recall/corpus-index.d.ts +200 -0
  19. package/dist/extensions/memory/session-recall/corpus-index.js +480 -0
  20. package/dist/extensions/memory/session-recall/index.js +173 -21
  21. package/dist/extensions/memory/session-recall/search.d.ts +29 -0
  22. package/dist/extensions/memory/session-recall/search.js +42 -9
  23. package/dist/lib/ai/payload-hygiene.d.ts +3 -0
  24. package/dist/lib/ai/payload-hygiene.js +34 -2
  25. package/dist/lib/config/braid-paths.d.ts +4 -0
  26. package/dist/lib/config/braid-paths.js +6 -0
  27. package/dist/lib/config/braid-settings.d.ts +22 -0
  28. package/dist/lib/config/braid-settings.js +15 -0
  29. package/dist/lib/detection/tool-loop-detector.d.ts +95 -46
  30. package/dist/lib/detection/tool-loop-detector.js +288 -180
  31. package/dist/lib/reasoning/dreamer.d.ts +2 -1
  32. package/dist/lib/reasoning/dreamer.js +12 -7
  33. package/docs/LOCAL_DEV.md +1 -1
  34. package/docs/SETUP.md +1 -0
  35. package/package.json +1 -1
  36. package/src/extensions/core/AGENTS.md +3 -2
  37. package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
  38. package/src/extensions/core/skills-tool/auto-inject.ts +118 -1
  39. package/src/extensions/core/skills-tool/index.ts +21 -1
  40. package/src/extensions/core/skills-tool/loading-guidance.ts +4 -1
  41. package/src/extensions/core/skills-tool/session-records.ts +201 -9
  42. package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +5 -1
  43. package/src/extensions/enforcement/handlers/register-tool-call.ts +5 -2
  44. package/src/extensions/enforcement/verification-judge.ts +32 -25
  45. package/src/extensions/memory/AGENTS.md +2 -2
  46. package/src/extensions/memory/session-recall/AGENTS.md +92 -18
  47. package/src/extensions/memory/session-recall/ask.ts +435 -0
  48. package/src/extensions/memory/session-recall/corpus-index.ts +609 -0
  49. package/src/extensions/memory/session-recall/index.ts +202 -21
  50. package/src/extensions/memory/session-recall/search.ts +61 -10
  51. package/src/lib/ai/payload-hygiene.ts +47 -3
  52. package/src/lib/config/braid-paths.ts +7 -0
  53. package/src/lib/config/braid-settings.ts +42 -3
  54. package/src/lib/detection/AGENTS.md +8 -7
  55. package/src/lib/detection/tool-loop-detector.ts +339 -195
  56. 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.7",
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
- The auto-inject whisper in `skills-tool/` is the only channel that surfaces a matching skill to the agent, so the rules about whether it arrived live in one place, here, and nowhere else:
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
- - **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`/`read`/`applied` belong to the record that owns each skill's declared tool family; the verdict row joins it on the skill name.
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 = [legs.suggested, legs.listed, legs.read, legs.called, legs.applied]
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
- /** Note that a skill surface (a suggestion or a SKILL.md read) just landed. */
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 `listed` are the surfaces that made the body findable in
632
- * this session (a delivered suggestion, a list_skills row); they carry the
633
- * "was it offered" half of adoption, which the call facts cannot.
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 five legs, read back as one row per skill. */
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 five legs OR across
721
- * every row, so a row that saw one leg never erases a leg a later row did not
722
- * have. `called`/`applied` are written once per skill, so the OR is exact
723
- * rather than convenient. A torn or duplicated row folds; a malformed one is
724
- * dropped at normalize, before this sees it.
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
- const dreamAdvice = dream(ctx, gs.toolLog, historicalSequences);
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") {