pi-braid 0.43.6 → 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 (62) hide show
  1. package/CHANGELOG.md +83 -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/applicability.d.ts +134 -0
  6. package/dist/extensions/core/skills-tool/applicability.js +161 -0
  7. package/dist/extensions/core/skills-tool/auto-inject.d.ts +31 -0
  8. package/dist/extensions/core/skills-tool/auto-inject.js +320 -1
  9. package/dist/extensions/core/skills-tool/index.js +83 -4
  10. package/dist/extensions/core/skills-tool/loading-guidance.d.ts +4 -1
  11. package/dist/extensions/core/skills-tool/loading-guidance.js +6 -2
  12. package/dist/extensions/core/skills-tool/session-records.d.ts +395 -8
  13. package/dist/extensions/core/skills-tool/session-records.js +645 -5
  14. package/dist/extensions/core/skills-tool/skill-families.d.ts +60 -0
  15. package/dist/extensions/core/skills-tool/skill-families.js +105 -0
  16. package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +5 -1
  17. package/dist/extensions/enforcement/handlers/register-tool-call.js +5 -2
  18. package/dist/extensions/enforcement/verification-judge.d.ts +7 -0
  19. package/dist/extensions/enforcement/verification-judge.js +28 -21
  20. package/dist/extensions/memory/session-recall/ask.d.ts +95 -0
  21. package/dist/extensions/memory/session-recall/ask.js +376 -0
  22. package/dist/extensions/memory/session-recall/corpus-index.d.ts +200 -0
  23. package/dist/extensions/memory/session-recall/corpus-index.js +480 -0
  24. package/dist/extensions/memory/session-recall/index.js +173 -21
  25. package/dist/extensions/memory/session-recall/search.d.ts +29 -0
  26. package/dist/extensions/memory/session-recall/search.js +42 -9
  27. package/dist/lib/ai/payload-hygiene.d.ts +3 -0
  28. package/dist/lib/ai/payload-hygiene.js +34 -2
  29. package/dist/lib/config/braid-paths.d.ts +4 -0
  30. package/dist/lib/config/braid-paths.js +6 -0
  31. package/dist/lib/config/braid-settings.d.ts +22 -0
  32. package/dist/lib/config/braid-settings.js +15 -0
  33. package/dist/lib/detection/tool-loop-detector.d.ts +95 -46
  34. package/dist/lib/detection/tool-loop-detector.js +288 -180
  35. package/dist/lib/reasoning/dreamer.d.ts +2 -1
  36. package/dist/lib/reasoning/dreamer.js +12 -7
  37. package/docs/LOCAL_DEV.md +1 -1
  38. package/docs/SETUP.md +1 -0
  39. package/package.json +1 -1
  40. package/src/extensions/core/AGENTS.md +3 -1
  41. package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
  42. package/src/extensions/core/skills-tool/applicability.ts +220 -0
  43. package/src/extensions/core/skills-tool/auto-inject.ts +391 -0
  44. package/src/extensions/core/skills-tool/index.ts +96 -3
  45. package/src/extensions/core/skills-tool/loading-guidance.ts +6 -2
  46. package/src/extensions/core/skills-tool/session-records.ts +932 -5
  47. package/src/extensions/core/skills-tool/skill-families.ts +112 -0
  48. package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +5 -1
  49. package/src/extensions/enforcement/handlers/register-tool-call.ts +5 -2
  50. package/src/extensions/enforcement/verification-judge.ts +32 -25
  51. package/src/extensions/memory/AGENTS.md +2 -2
  52. package/src/extensions/memory/session-recall/AGENTS.md +92 -18
  53. package/src/extensions/memory/session-recall/ask.ts +435 -0
  54. package/src/extensions/memory/session-recall/corpus-index.ts +609 -0
  55. package/src/extensions/memory/session-recall/index.ts +202 -21
  56. package/src/extensions/memory/session-recall/search.ts +61 -10
  57. package/src/lib/ai/payload-hygiene.ts +47 -3
  58. package/src/lib/config/braid-paths.ts +7 -0
  59. package/src/lib/config/braid-settings.ts +42 -3
  60. package/src/lib/detection/AGENTS.md +8 -7
  61. package/src/lib/detection/tool-loop-detector.ts +339 -195
  62. package/src/lib/reasoning/dreamer.ts +13 -6
@@ -0,0 +1,60 @@
1
+ /**
2
+ * The tool families a skill declares it governs.
3
+ *
4
+ * A trigger phrase says WHEN to open a skill file; nothing in the file says
5
+ * what the file's advice is then used FOR. `governs:` closes that: the tool
6
+ * families whose calls the body is written to direct. A family is the tool
7
+ * name's first underscore-delimited segment (`search_documents` → `search`),
8
+ * the same token `loading-guidance.ts` pairs with a skill name in the
9
+ * mechanical trigger, so "before the first call in the family" in the prompt
10
+ * and "a call in a declared family" in the record cannot mean two things.
11
+ *
12
+ * The declaration is authored data in the skill's own frontmatter — pi's
13
+ * parser already returns it, and the pack's authoring contract already admits
14
+ * any YAML-valid extra key. No new file format and no new field parser is
15
+ * needed, which is why this module only reads.
16
+ *
17
+ * Most skills govern nothing: advice about prose, a palette or a checklist
18
+ * directs no tool, and a file without the key is read as declaring no family.
19
+ * The absence is a fact, not a gap — an obligation that names no family is
20
+ * satisfied by the read alone.
21
+ *
22
+ * A declared family may not be the detector's own tool (`read`): a call to it
23
+ * IS the read leg, so counting it as an applied call would let an obligation
24
+ * satisfy itself. The parser drops such an entry; the shipped pack's contract
25
+ * refuses it by name so an author sees the problem before a release.
26
+ *
27
+ * Nothing here names a skill, a package or a path. Reads are memoized by file
28
+ * mtime + size, so a turn pays one stat per skill file and a parse only when
29
+ * a file changed.
30
+ */
31
+ /**
32
+ * Max families read from one declaration. A body that directs more than four
33
+ * tool families is not one skill's job, and the record's per-session rows are
34
+ * bounded by the same number. The pack's contract mirrors this cap.
35
+ */
36
+ export declare const MAX_GOVERNED_FAMILIES = 4;
37
+ /** The token shape a declaration must use: a tool name's first segment. */
38
+ export declare const GOVERNED_FAMILY_SHAPE: RegExp;
39
+ /**
40
+ * The tool whose call is the read leg itself. Never a declarable family: see
41
+ * the module header.
42
+ */
43
+ export declare const DETECTOR_TOOL = "read";
44
+ /** The family a tool name belongs to: its first underscore-delimited segment. */
45
+ export declare function toolFamilyToken(toolName: string): string;
46
+ /**
47
+ * Normalize a frontmatter `governs` value into family tokens. Accepts a YAML
48
+ * list or a comma-separated string, lowercases, drops malformed, detector, and
49
+ * surplus entries, and dedupes in authored order. Pure.
50
+ */
51
+ export declare function parseGovernedFamilies(value: unknown): string[];
52
+ /**
53
+ * Read the families a skill file declares. Missing or unreadable file, or
54
+ * malformed frontmatter, yields an empty list (a declaration that cannot be
55
+ * read is not a declaration). Memoized: an unchanged file never re-reads.
56
+ */
57
+ export declare function readGovernedFamilies(filePath: string): string[];
58
+ /** Test seam: forget every memoized read. */
59
+ export declare function clearGovernedFamilyCache(): void;
60
+ //# sourceMappingURL=skill-families.d.ts.map
@@ -0,0 +1,105 @@
1
+ /**
2
+ * The tool families a skill declares it governs.
3
+ *
4
+ * A trigger phrase says WHEN to open a skill file; nothing in the file says
5
+ * what the file's advice is then used FOR. `governs:` closes that: the tool
6
+ * families whose calls the body is written to direct. A family is the tool
7
+ * name's first underscore-delimited segment (`search_documents` → `search`),
8
+ * the same token `loading-guidance.ts` pairs with a skill name in the
9
+ * mechanical trigger, so "before the first call in the family" in the prompt
10
+ * and "a call in a declared family" in the record cannot mean two things.
11
+ *
12
+ * The declaration is authored data in the skill's own frontmatter — pi's
13
+ * parser already returns it, and the pack's authoring contract already admits
14
+ * any YAML-valid extra key. No new file format and no new field parser is
15
+ * needed, which is why this module only reads.
16
+ *
17
+ * Most skills govern nothing: advice about prose, a palette or a checklist
18
+ * directs no tool, and a file without the key is read as declaring no family.
19
+ * The absence is a fact, not a gap — an obligation that names no family is
20
+ * satisfied by the read alone.
21
+ *
22
+ * A declared family may not be the detector's own tool (`read`): a call to it
23
+ * IS the read leg, so counting it as an applied call would let an obligation
24
+ * satisfy itself. The parser drops such an entry; the shipped pack's contract
25
+ * refuses it by name so an author sees the problem before a release.
26
+ *
27
+ * Nothing here names a skill, a package or a path. Reads are memoized by file
28
+ * mtime + size, so a turn pays one stat per skill file and a parse only when
29
+ * a file changed.
30
+ */
31
+ import { readFileSync, statSync } from "node:fs";
32
+ import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
33
+ /**
34
+ * Max families read from one declaration. A body that directs more than four
35
+ * tool families is not one skill's job, and the record's per-session rows are
36
+ * bounded by the same number. The pack's contract mirrors this cap.
37
+ */
38
+ export const MAX_GOVERNED_FAMILIES = 4;
39
+ /** The token shape a declaration must use: a tool name's first segment. */
40
+ export const GOVERNED_FAMILY_SHAPE = /^[a-z][a-z0-9]*$/;
41
+ /**
42
+ * The tool whose call is the read leg itself. Never a declarable family: see
43
+ * the module header.
44
+ */
45
+ export const DETECTOR_TOOL = "read";
46
+ /** The family a tool name belongs to: its first underscore-delimited segment. */
47
+ export function toolFamilyToken(toolName) {
48
+ return (toolName ?? "").split("_")[0].toLowerCase();
49
+ }
50
+ /**
51
+ * Normalize a frontmatter `governs` value into family tokens. Accepts a YAML
52
+ * list or a comma-separated string, lowercases, drops malformed, detector, and
53
+ * surplus entries, and dedupes in authored order. Pure.
54
+ */
55
+ export function parseGovernedFamilies(value) {
56
+ const raw = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
57
+ const families = [];
58
+ for (const item of raw) {
59
+ if (typeof item !== "string")
60
+ continue;
61
+ const family = item.trim().toLowerCase();
62
+ if (!GOVERNED_FAMILY_SHAPE.test(family) || family === DETECTOR_TOOL)
63
+ continue;
64
+ if (families.includes(family))
65
+ continue;
66
+ families.push(family);
67
+ if (families.length >= MAX_GOVERNED_FAMILIES)
68
+ break;
69
+ }
70
+ return families;
71
+ }
72
+ const cache = new Map();
73
+ /**
74
+ * Read the families a skill file declares. Missing or unreadable file, or
75
+ * malformed frontmatter, yields an empty list (a declaration that cannot be
76
+ * read is not a declaration). Memoized: an unchanged file never re-reads.
77
+ */
78
+ export function readGovernedFamilies(filePath) {
79
+ let st;
80
+ try {
81
+ st = statSync(filePath);
82
+ }
83
+ catch {
84
+ cache.delete(filePath);
85
+ return [];
86
+ }
87
+ const cached = cache.get(filePath);
88
+ if (cached && cached.mtimeMs === st.mtimeMs && cached.size === st.size)
89
+ return cached.families;
90
+ let families = [];
91
+ try {
92
+ const { frontmatter } = parseFrontmatter(readFileSync(filePath, "utf-8"));
93
+ families = parseGovernedFamilies(frontmatter.governs);
94
+ }
95
+ catch {
96
+ // Unreadable or unparseable: no declared family, and no throw on a turn.
97
+ }
98
+ cache.set(filePath, { mtimeMs: st.mtimeMs, size: st.size, families });
99
+ return families;
100
+ }
101
+ /** Test seam: forget every memoized read. */
102
+ export function clearGovernedFamilyCache() {
103
+ cache.clear();
104
+ }
105
+ //# sourceMappingURL=skill-families.js.map
@@ -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