pi-braid 0.43.7 → 0.43.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/CHANGELOG.md +72 -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 +44 -0
  28. package/dist/lib/config/braid-settings.js +41 -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/memory/constants.d.ts +38 -0
  32. package/dist/lib/memory/constants.js +196 -0
  33. package/dist/lib/memory/index.js +49 -10
  34. package/dist/lib/memory/lifecycle.d.ts +8 -0
  35. package/dist/lib/memory/lifecycle.js +43 -18
  36. package/dist/lib/reasoning/dreamer.d.ts +2 -1
  37. package/dist/lib/reasoning/dreamer.js +12 -7
  38. package/docs/LOCAL_DEV.md +1 -1
  39. package/docs/SETUP.md +2 -0
  40. package/package.json +1 -1
  41. package/src/extensions/core/AGENTS.md +3 -2
  42. package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
  43. package/src/extensions/core/skills-tool/auto-inject.ts +118 -1
  44. package/src/extensions/core/skills-tool/index.ts +21 -1
  45. package/src/extensions/core/skills-tool/loading-guidance.ts +4 -1
  46. package/src/extensions/core/skills-tool/session-records.ts +201 -9
  47. package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +5 -1
  48. package/src/extensions/enforcement/handlers/register-tool-call.ts +5 -2
  49. package/src/extensions/enforcement/verification-judge.ts +32 -25
  50. package/src/extensions/memory/AGENTS.md +2 -2
  51. package/src/extensions/memory/session-recall/AGENTS.md +92 -18
  52. package/src/extensions/memory/session-recall/ask.ts +435 -0
  53. package/src/extensions/memory/session-recall/corpus-index.ts +609 -0
  54. package/src/extensions/memory/session-recall/index.ts +202 -21
  55. package/src/extensions/memory/session-recall/search.ts +61 -10
  56. package/src/lib/ai/payload-hygiene.ts +47 -3
  57. package/src/lib/config/braid-paths.ts +7 -0
  58. package/src/lib/config/braid-settings.ts +93 -3
  59. package/src/lib/detection/AGENTS.md +8 -7
  60. package/src/lib/detection/tool-loop-detector.ts +339 -195
  61. package/src/lib/memory/constants.ts +202 -0
  62. package/src/lib/memory/index.ts +59 -8
  63. package/src/lib/memory/lifecycle.ts +50 -16
  64. package/src/lib/reasoning/dreamer.ts +13 -6
@@ -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") {
@@ -126,6 +126,13 @@ export interface JudgeContext {
126
126
 
127
127
  /**
128
128
  * Build the verification analysis prompt. Exported for tests.
129
+ *
130
+ * Order is load-bearing: the ground-truth sections (git history, the
131
+ * disk-checked deliverables manifest, the code-changes flag) come BEFORE the
132
+ * bounded ones (task evidence, tool log, reasoning, response). The bounded
133
+ * sections are the ones a bound can shorten: a head kept under a size cap, a
134
+ * tail cut by a redaction. A reader that meets the verdict-bearing sections
135
+ * first cannot have them removed by whatever truncated the evidence.
129
136
  */
130
137
  export function buildVerificationPrompt(context: JudgeContext): string {
131
138
  const sections: string[] = [];
@@ -138,31 +145,6 @@ export function buildVerificationPrompt(context: JudgeContext): string {
138
145
  sections.push(context.toolsUsed.length > 0 ? context.toolsUsed.join(", ") : "(none)");
139
146
  sections.push("");
140
147
 
141
- // Task-wide evidence (since last user message, session-store
142
- // backed) comes BEFORE the current-window tool log — it is the surviving
143
- // view when turn breaks cut toolLog down to the tail turn.
144
- if (context.taskEvidence && context.taskEvidence.length > 0) {
145
- sections.push("## TASK EVIDENCE (since last user message, disk/session-surviving)");
146
- sections.push(context.taskEvidence.join("\n"));
147
- sections.push("");
148
- }
149
-
150
- if (context.toolLog.length > 0) {
151
- sections.push("## TOOL EXECUTION LOG");
152
- sections.push(context.toolLog.slice(-50).join("\n")); // Last 50 entries (matches turnHistory cap)
153
- sections.push("");
154
- }
155
-
156
- sections.push(`## CODE CHANGES: ${context.hasCodeChanges ? "YES" : "NO"}`);
157
- // (Verification evidence comes from the TOOL EXECUTION LOG above, not a boolean)
158
- sections.push("");
159
-
160
- if (context.thinking) {
161
- sections.push("## AGENT REASONING (thinking blocks)");
162
- sections.push(context.thinking);
163
- sections.push("");
164
- }
165
-
166
148
  if (context.gitHistory) {
167
149
  sections.push("## GIT HISTORY (recent commits)");
168
150
  sections.push(context.gitHistory);
@@ -188,6 +170,31 @@ export function buildVerificationPrompt(context: JudgeContext): string {
188
170
  sections.push("");
189
171
  }
190
172
 
173
+ sections.push(`## CODE CHANGES: ${context.hasCodeChanges ? "YES" : "NO"}`);
174
+ // (Verification evidence comes from the TOOL EXECUTION LOG, not a boolean)
175
+ sections.push("");
176
+
177
+ // Task-wide evidence (since last user message, session-store backed) comes
178
+ // BEFORE the current-window tool log — it is the surviving view when turn
179
+ // breaks cut toolLog down to the tail turn.
180
+ if (context.taskEvidence && context.taskEvidence.length > 0) {
181
+ sections.push("## TASK EVIDENCE (since last user message, disk/session-surviving)");
182
+ sections.push(context.taskEvidence.join("\n"));
183
+ sections.push("");
184
+ }
185
+
186
+ if (context.toolLog.length > 0) {
187
+ sections.push("## TOOL EXECUTION LOG");
188
+ sections.push(context.toolLog.slice(-50).join("\n")); // Last 50 entries (matches turnHistory cap)
189
+ sections.push("");
190
+ }
191
+
192
+ if (context.thinking) {
193
+ sections.push("## AGENT REASONING (thinking blocks)");
194
+ sections.push(context.thinking);
195
+ sections.push("");
196
+ }
197
+
191
198
  if (context.lastResponse) {
192
199
  sections.push("## AGENT RESPONSE (visible text)");
193
200
  sections.push(context.lastResponse);
@@ -117,8 +117,8 @@ The memory extensions expose 4 LLM-callable tools. The unified `memory` tool cov
117
117
  | -------------- | ------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
118
118
  | `memory_store` | memory-agent-bridge | semantic (unified) | Save insights/patterns for cross-session recall |
119
119
  | `memory` | memory-agent-bridge | all three | Unified access: `recall_search` (semantic search, also cross-searches episodes), `recall_list`, `recall_get`, `episodes_search` (case-based reasoning), `episodes_list`, `episodes_add`, `heuristics_list`, `heuristics_add`, `heuristics_evolve` |
120
- | `session` | session-recall | session log | Search past sessions (action=search) or query one (action=query) |
120
+ | `session` | session-recall | session log | Search past sessions (action=search), ask what the owner said earlier with citations (action=ask), or query one (action=query) |
121
121
 
122
- **Rule of thumb:** start with `memory` action=recall_search for "have I seen this before?". Use `memory` action=episodes_search for "how did a similar task go?". Use `memory` action=heuristics_list when investigating behavior tuning. Use `session` for cross-session history.
122
+ **Rule of thumb:** start with `memory` action=recall_search for "have I seen this before?". Use `memory` action=episodes_search for "how did a similar task go?". Use `memory` action=heuristics_list when investigating behavior tuning. Use `session` for cross-session history, and `session` action=ask when the question is "what did the owner say or decide about X?" - it reads the indexed user turns and cites each hit.
123
123
 
124
124
  The data-layer functions (`addEpisode`, `addPrinciple`, `recordToolCall`, etc.) live in `three-memory-stores/episodes.ts`, `heuristics.ts`, `tool-reliability.ts` and are imported by many extensions (e.g. `finalize.ts` adds episodes on task completion). These are infrastructure and should not be moved out of the directory.