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
@@ -467,6 +467,7 @@ export function normalizeObligationRecord(raw) {
467
467
  skill: r.skill,
468
468
  suggested: r.suggested === true,
469
469
  listed: r.listed === true,
470
+ informed: r.informed === true,
470
471
  read: r.read === true,
471
472
  called: r.called === true,
472
473
  applied: r.applied === true,
@@ -501,11 +502,11 @@ export function readObligationRecords(storePath = getSkillsSessionsFilePath()) {
501
502
  return out;
502
503
  }
503
504
  /**
504
- * Fold a session's obligation rows into one record: the five legs OR across
505
- * every row, so a row that saw one leg never erases a leg a later row did not
506
- * have. `called`/`applied` are written once per skill, so the OR is exact
507
- * rather than convenient. A torn or duplicated row folds; a malformed one is
508
- * dropped at normalize, before this sees it.
505
+ * Fold a session's obligation rows into one record: the legs OR across every
506
+ * row, so a row that saw one leg never erases a leg a later row did not have.
507
+ * `called`/`applied` are written once per skill, so the OR is exact rather
508
+ * than convenient. A torn or duplicated row folds; a malformed one is dropped
509
+ * at normalize, before this sees it.
509
510
  */
510
511
  export function foldObligationRecords(records) {
511
512
  const bySession = new Map();
@@ -532,6 +533,7 @@ export function foldObligationRecords(records) {
532
533
  skill: rec.skill,
533
534
  suggested: rec.suggested,
534
535
  listed: rec.listed,
536
+ informed: rec.informed,
535
537
  read: rec.read,
536
538
  called: rec.called,
537
539
  applied: rec.applied,
@@ -540,6 +542,7 @@ export function foldObligationRecords(records) {
540
542
  }
541
543
  held.suggested = held.suggested || rec.suggested;
542
544
  held.listed = held.listed || rec.listed;
545
+ held.informed = held.informed || rec.informed;
543
546
  held.read = held.read || rec.read;
544
547
  held.called = held.called || rec.called;
545
548
  held.applied = held.applied || rec.applied;
@@ -561,6 +564,7 @@ export function recordObligationLegs(ctx, legs, storePath) {
561
564
  skill: legs.skill,
562
565
  suggested: legs.suggested,
563
566
  listed: legs.listed,
567
+ informed: legs.informed,
564
568
  read: legs.read,
565
569
  called: legs.called,
566
570
  applied: legs.applied,
@@ -624,6 +628,7 @@ export function judgeSessionObligations(applicable, obligation) {
624
628
  skill,
625
629
  suggested: false,
626
630
  listed: false,
631
+ informed: false,
627
632
  read: false,
628
633
  called: false,
629
634
  applied: false,
@@ -710,6 +715,137 @@ export function getObligationRate(options = {}) {
710
715
  return undefined;
711
716
  }
712
717
  }
718
+ // The at-use inform, measured against the suggestion channel
719
+ /**
720
+ * The suggestion channel's pair conversion as published from session-file
721
+ * mining: 95 read-followed pairs out of 506 delivered ones, Wilson 15.6-22.4.
722
+ *
723
+ * It is a measurement constant, not a target: it stands in as the comparison
724
+ * arm only while the same store carries too few suggested pairs of its own to
725
+ * stand on its own (see INFORM_DECISION_MIN_PAIRS). A two-pair store arm that
726
+ * happens to have converted nothing is not a baseline; it is a sample. The
727
+ * moment the store holds the floor of suggested pairs, their own fold answers
728
+ * and this number is not read.
729
+ */
730
+ export const CHANNEL_PUBLISHED_CONVERSION = 0.188;
731
+ /** Wilson 95% bounds for that published figure, as proportions. */
732
+ export const CHANNEL_PUBLISHED_INTERVAL = { lower: 0.156, upper: 0.224 };
733
+ /**
734
+ * Informs needed before the comparison decides anything. Below this the
735
+ * answer is "undecided": a verdict from a handful of pairs would be a verdict
736
+ * about the sample, and the report's decision rule says so in writing before
737
+ * the first inform lands. The same floor governs the comparison arm: a store
738
+ * carrying fewer suggested pairs than this is not a baseline to beat.
739
+ */
740
+ export const INFORM_DECISION_MIN_PAIRS = 20;
741
+ /**
742
+ * Wilson score interval for k successes in n trials (95% by default). Chosen
743
+ * over the normal approximation because the inform population is small and a
744
+ * small-sample interval is the only one that can say "undecided" honestly.
745
+ * Returns zeros for n = 0. Pure.
746
+ */
747
+ export function wilsonInterval(successes, total, z = 1.959963985) {
748
+ if (!total || total < 0)
749
+ return { lower: 0, upper: 0 };
750
+ const p = Math.min(1, Math.max(0, successes / total));
751
+ const denominator = 1 + (z * z) / total;
752
+ const centre = (p + (z * z) / (2 * total)) / denominator;
753
+ const half = (z * Math.sqrt((p * (1 - p)) / total + (z * z) / (4 * total * total))) / denominator;
754
+ return {
755
+ lower: round4(Math.max(0, centre - half)),
756
+ upper: round4(Math.min(1, centre + half)),
757
+ };
758
+ }
759
+ /**
760
+ * Fold the obligation rows into the at-use rate and the channel arm beside it.
761
+ * Pure.
762
+ *
763
+ * The rule, applied literally: fewer than the floor is undecided; at the floor
764
+ * the inform beats the channel only when its point estimate is above the
765
+ * channel's AND its lower Wilson bound is above it too. Anything else at the
766
+ * floor is noise, which is the falsifier firing rather than a neutral result.
767
+ */
768
+ export function computeInformRate(obligations) {
769
+ let informs = 0;
770
+ let informRead = 0;
771
+ let channelPairs = 0;
772
+ let channelRead = 0;
773
+ const bySkill = new Map();
774
+ for (const session of obligations) {
775
+ for (const legs of session.skills) {
776
+ if (legs.suggested) {
777
+ channelPairs++;
778
+ if (legs.read)
779
+ channelRead++;
780
+ }
781
+ if (!legs.informed)
782
+ continue;
783
+ informs++;
784
+ if (legs.read)
785
+ informRead++;
786
+ let row = bySkill.get(legs.skill);
787
+ if (!row) {
788
+ row = { skill: legs.skill, informs: 0, readFollowed: 0 };
789
+ bySkill.set(legs.skill, row);
790
+ }
791
+ row.informs++;
792
+ if (legs.read)
793
+ row.readFollowed++;
794
+ }
795
+ }
796
+ const conversion = informs ? round4(informRead / informs) : 0;
797
+ const channel = channelPairs >= INFORM_DECISION_MIN_PAIRS
798
+ ? {
799
+ pairs: channelPairs,
800
+ readFollowed: channelRead,
801
+ conversion: round4(channelRead / channelPairs),
802
+ ci: wilsonInterval(channelRead, channelPairs),
803
+ source: "store",
804
+ }
805
+ : {
806
+ pairs: channelPairs,
807
+ readFollowed: channelRead,
808
+ conversion: CHANNEL_PUBLISHED_CONVERSION,
809
+ ci: CHANNEL_PUBLISHED_INTERVAL,
810
+ source: "published",
811
+ };
812
+ const ci = wilsonInterval(informRead, informs);
813
+ const decidable = informs >= INFORM_DECISION_MIN_PAIRS;
814
+ const verdict = !decidable
815
+ ? "undecided"
816
+ : conversion > channel.conversion && ci.lower > channel.conversion
817
+ ? "beats"
818
+ : "noise";
819
+ return {
820
+ informs,
821
+ readFollowed: informRead,
822
+ conversion,
823
+ ci,
824
+ skills: [...bySkill.values()],
825
+ channel,
826
+ gapPoints: Math.round((conversion - channel.conversion) * 10000) / 100,
827
+ decidable,
828
+ verdict,
829
+ };
830
+ }
831
+ /**
832
+ * The store-wide at-use rate, or undefined when the store carries no inform row
833
+ * at all. Undefined keeps every existing `skill_stats` payload byte-identical
834
+ * for a build or an install that never emitted one.
835
+ */
836
+ export function getInformRate(options = {}) {
837
+ try {
838
+ const storePath = options.storePath ?? getSkillsSessionsFilePath();
839
+ const records = readObligationRecords(storePath);
840
+ if (!records.some((rec) => rec.informed))
841
+ return undefined;
842
+ return computeInformRate(foldObligationRecords(records));
843
+ }
844
+ catch (err) {
845
+ reportRecordFailure(err);
846
+ return undefined;
847
+ }
848
+ }
713
849
  /**
714
850
  * Compute the monthly adoption rollup for the current + previous 2
715
851
  * months, keyed by session profile name. Pure (given records + now).
@@ -7,6 +7,7 @@ import { emitSignal } from "../../../../lib/reasoning/belief-policy-engine.js";
7
7
  import { dream } from "../../../../lib/reasoning/dreamer.js";
8
8
  import { recordAdvice } from "../../../../lib/reasoning/advice-tracker.js";
9
9
  import { tryClaim } from "../../../../lib/enforcement/turn-dedup.js";
10
+ import { getToolLoopState } from "../../../../lib/detection/tool-loop-detector.js";
10
11
  import { getState } from "../../state.js";
11
12
  const log = createLogger("enforcement:dreamer");
12
13
  export async function dreamerHandler(pi, _event, ctx) {
@@ -20,7 +21,10 @@ export async function dreamerHandler(pi, _event, ctx) {
20
21
  historicalSequences.push(turn.actualTools);
21
22
  }
22
23
  }
23
- const dreamAdvice = dream(ctx, gs.toolLog, historicalSequences);
24
+ // The loop path reads the detector's own recorded calls (tool + argument
25
+ // identity); gs.toolLog is names only and cannot distinguish one call
26
+ // repeated from many different calls under one name.
27
+ const dreamAdvice = dream(ctx, gs.toolLog, historicalSequences, getToolLoopState(ctx).history);
24
28
  if (!dreamAdvice)
25
29
  return;
26
30
  emitSignal(ctx, "stability", "predicted-decline", "info", false, {
@@ -29,9 +29,12 @@ export function registerToolCallHandler(pi) {
29
29
  if (!toolName || !toolName.trim())
30
30
  return undefined;
31
31
  recordToolCall(toolName, ctx);
32
- // Record tool call for tool-loop-detector (per-turn tool sets)
32
+ // Record tool call for tool-loop-detector (per-turn tool sets). The
33
+ // arguments ride along: a loop is the same call repeating, and the tool
34
+ // name alone cannot say whether sixteen `bash` calls are sixteen commands
35
+ // or one command sixteen times.
33
36
  const loopState = getToolLoopState(ctx);
34
- recordLoopToolCall(loopState, toolName);
37
+ recordLoopToolCall(loopState, toolName, input);
35
38
  recordToolInput(toolName, input, getState(ctx));
36
39
  if (toolName === "bash") {
37
40
  const cmd = input?.command || "";
@@ -79,6 +79,13 @@ export interface JudgeContext {
79
79
  }
80
80
  /**
81
81
  * Build the verification analysis prompt. Exported for tests.
82
+ *
83
+ * Order is load-bearing: the ground-truth sections (git history, the
84
+ * disk-checked deliverables manifest, the code-changes flag) come BEFORE the
85
+ * bounded ones (task evidence, tool log, reasoning, response). The bounded
86
+ * sections are the ones a bound can shorten: a head kept under a size cap, a
87
+ * tail cut by a redaction. A reader that meets the verdict-bearing sections
88
+ * first cannot have them removed by whatever truncated the evidence.
82
89
  */
83
90
  export declare function buildVerificationPrompt(context: JudgeContext): string;
84
91
  /**
@@ -61,6 +61,13 @@ import { createLogger } from "../../lib/core/logger.js";
61
61
  const log = createLogger("verification-judge");
62
62
  /**
63
63
  * Build the verification analysis prompt. Exported for tests.
64
+ *
65
+ * Order is load-bearing: the ground-truth sections (git history, the
66
+ * disk-checked deliverables manifest, the code-changes flag) come BEFORE the
67
+ * bounded ones (task evidence, tool log, reasoning, response). The bounded
68
+ * sections are the ones a bound can shorten: a head kept under a size cap, a
69
+ * tail cut by a redaction. A reader that meets the verdict-bearing sections
70
+ * first cannot have them removed by whatever truncated the evidence.
64
71
  */
65
72
  export function buildVerificationPrompt(context) {
66
73
  const sections = [];
@@ -70,27 +77,6 @@ export function buildVerificationPrompt(context) {
70
77
  sections.push("## TOOLS USED");
71
78
  sections.push(context.toolsUsed.length > 0 ? context.toolsUsed.join(", ") : "(none)");
72
79
  sections.push("");
73
- // Task-wide evidence (since last user message, session-store
74
- // backed) comes BEFORE the current-window tool log — it is the surviving
75
- // view when turn breaks cut toolLog down to the tail turn.
76
- if (context.taskEvidence && context.taskEvidence.length > 0) {
77
- sections.push("## TASK EVIDENCE (since last user message, disk/session-surviving)");
78
- sections.push(context.taskEvidence.join("\n"));
79
- sections.push("");
80
- }
81
- if (context.toolLog.length > 0) {
82
- sections.push("## TOOL EXECUTION LOG");
83
- sections.push(context.toolLog.slice(-50).join("\n")); // Last 50 entries (matches turnHistory cap)
84
- sections.push("");
85
- }
86
- sections.push(`## CODE CHANGES: ${context.hasCodeChanges ? "YES" : "NO"}`);
87
- // (Verification evidence comes from the TOOL EXECUTION LOG above, not a boolean)
88
- sections.push("");
89
- if (context.thinking) {
90
- sections.push("## AGENT REASONING (thinking blocks)");
91
- sections.push(context.thinking);
92
- sections.push("");
93
- }
94
80
  if (context.gitHistory) {
95
81
  sections.push("## GIT HISTORY (recent commits)");
96
82
  sections.push(context.gitHistory);
@@ -107,6 +93,27 @@ export function buildVerificationPrompt(context) {
107
93
  : "\nSome deliverables missing on disk → real unverified risk.");
108
94
  sections.push("");
109
95
  }
96
+ sections.push(`## CODE CHANGES: ${context.hasCodeChanges ? "YES" : "NO"}`);
97
+ // (Verification evidence comes from the TOOL EXECUTION LOG, not a boolean)
98
+ sections.push("");
99
+ // Task-wide evidence (since last user message, session-store backed) comes
100
+ // BEFORE the current-window tool log — it is the surviving view when turn
101
+ // breaks cut toolLog down to the tail turn.
102
+ if (context.taskEvidence && context.taskEvidence.length > 0) {
103
+ sections.push("## TASK EVIDENCE (since last user message, disk/session-surviving)");
104
+ sections.push(context.taskEvidence.join("\n"));
105
+ sections.push("");
106
+ }
107
+ if (context.toolLog.length > 0) {
108
+ sections.push("## TOOL EXECUTION LOG");
109
+ sections.push(context.toolLog.slice(-50).join("\n")); // Last 50 entries (matches turnHistory cap)
110
+ sections.push("");
111
+ }
112
+ if (context.thinking) {
113
+ sections.push("## AGENT REASONING (thinking blocks)");
114
+ sections.push(context.thinking);
115
+ sections.push("");
116
+ }
110
117
  if (context.lastResponse) {
111
118
  sections.push("## AGENT RESPONSE (visible text)");
112
119
  sections.push(context.lastResponse);
@@ -0,0 +1,95 @@
1
+ /**
2
+ * Session corpus ask - lexical retrieval over the user-turn index.
3
+ *
4
+ * BM25 over one document per user turn. At this corpus size the lexical model
5
+ * is the cheap, testable choice: no embedding pass to keep current, no vector
6
+ * store to back up, no key to spend on a query, and a score a reader can
7
+ * re-derive by eye from the terms it names. What would earn a vector store is
8
+ * a measured failure: recall@3 below the bar on questions whose answering
9
+ * passage is in the index (the report's falsifier is that measurement).
10
+ *
11
+ * Every hit carries its citation - project, session path, line, timestamp -
12
+ * because the answer is the owner's own words and a reader must be able to
13
+ * check them against the session file. The refusal is a first-class result: a
14
+ * query whose terms appear nowhere in the population says so and names what it
15
+ * searched, rather than returning the least bad rows.
16
+ */
17
+ import type { CorpusFreshness, CorpusTurn, LoadedShard } from "./corpus-index.js";
18
+ /** BM25 term-frequency saturation. */
19
+ export declare const BM25_K1 = 1.2;
20
+ /** BM25 length normalisation. */
21
+ export declare const BM25_B = 0.75;
22
+ /** Hits a query returns when the caller names no limit. */
23
+ export declare const MAX_ASK_HITS = 5;
24
+ /**
25
+ * Words a document is scored on: letter/number runs, lowercased, stemmed.
26
+ *
27
+ * A hyphen separates words: the owner's compound names ("looping-clanker",
28
+ * "anti-crowd") are two words a question may spell either way, and a tokenizer
29
+ * that keeps the compound as one token can never match its own parts.
30
+ */
31
+ export declare function tokenizeForIndex(text: string): string[];
32
+ /**
33
+ * Query terms: the document tokens minus function words. Duplicates collapse,
34
+ * so a word typed twice scores once.
35
+ */
36
+ export declare function askQueryTerms(query: string): string[];
37
+ export interface AskHit {
38
+ turn: CorpusTurn;
39
+ score: number;
40
+ /** Query terms this turn carries. */
41
+ matched: string[];
42
+ }
43
+ export interface AskResult {
44
+ query: string;
45
+ /** Query terms after the function-word filter. */
46
+ terms: string[];
47
+ /** Terms that occur in the searched population. */
48
+ matched_terms: string[];
49
+ /** Terms that occur nowhere in the searched population. */
50
+ unmatched_terms: string[];
51
+ hits: AskHit[];
52
+ /** Whether the index could answer at all (at least one hit). */
53
+ answered: boolean;
54
+ population: {
55
+ turns: number;
56
+ sessions: number;
57
+ projects: string[];
58
+ /** Oldest and newest shard build time in the population. */
59
+ built_oldest: string;
60
+ built_newest: string;
61
+ shards: number;
62
+ };
63
+ freshness: CorpusFreshness;
64
+ filters: {
65
+ project: string | null;
66
+ since: string | null;
67
+ };
68
+ /** True when the caller's own session was withheld from the results. */
69
+ self_excluded: boolean;
70
+ }
71
+ export interface AskOptions {
72
+ /** Project label filter; null reads every shard the store loaded. */
73
+ project?: string | null;
74
+ /** Inclusive lower bound on the turn's date (YYYY-MM-DD). */
75
+ since?: string | null;
76
+ limit?: number;
77
+ /** Session file never returned to itself. */
78
+ excludeSession?: string | null;
79
+ freshness: CorpusFreshness;
80
+ }
81
+ /**
82
+ * Retrieve the turns that answer a question, with citations.
83
+ *
84
+ * The population searched is stated in the result, so a refusal can show what
85
+ * it looked at. `df` and the average document length are computed over the
86
+ * filtered population: an index narrowed by `--project` or `--since` is the
87
+ * corpus the answer claims, not a sample of a larger one it never read.
88
+ */
89
+ export declare function askCorpusIndex(shards: LoadedShard[], query: string, opts: AskOptions): AskResult;
90
+ /**
91
+ * Render the answer: cited passages, or a refusal that names the population it
92
+ * searched and the terms it found.
93
+ */
94
+ export declare function formatAskResult(result: AskResult): string;
95
+ //# sourceMappingURL=ask.d.ts.map