pi-braid 0.43.41 → 0.43.43
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +37 -0
- package/CONTRIBUTING.md +1 -1
- package/TOOLS.md +10 -15
- package/build-info.json +4 -4
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +126 -24
- package/dist/extensions/core/skills-tool/auto-inject.js +206 -47
- package/dist/extensions/heartbeat/analytics/index.js +41 -18
- package/dist/index.d.ts +0 -2
- package/dist/index.js +0 -2
- package/dist/loader/api.d.ts +2 -5
- package/dist/loader/api.js +7 -48
- package/dist/loader/loader.d.ts +0 -2
- package/dist/loader/loader.js +0 -4
- package/docs/LOCAL_DEV.md +1 -1
- package/docs/SETUP.md +1 -1
- package/package.json +1 -1
- package/src/extensions/core/AGENTS.md +3 -2
- package/src/extensions/core/skills-tool/auto-inject.ts +255 -50
- package/src/extensions/heartbeat/analytics/AGENTS.md +2 -2
- package/src/extensions/heartbeat/analytics/index.ts +50 -19
- package/src/index.ts +0 -2
- package/src/loader/AGENTS.md +4 -4
- package/src/loader/api.ts +9 -51
- package/src/loader/loader.ts +0 -5
|
@@ -54,21 +54,30 @@
|
|
|
54
54
|
* most likely to match.
|
|
55
55
|
* `sendTrackedMessage` reports whether the message was accepted; a
|
|
56
56
|
* suppressed suggestion is neither sent nor counted.
|
|
57
|
-
* 5. Content delivery: the
|
|
58
|
-
*
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
*
|
|
62
|
-
*
|
|
63
|
-
*
|
|
64
|
-
*
|
|
65
|
-
*
|
|
66
|
-
*
|
|
67
|
-
*
|
|
68
|
-
*
|
|
69
|
-
*
|
|
70
|
-
*
|
|
71
|
-
*
|
|
57
|
+
* 5. Content delivery, two tiers: the best-ranked match arrives WHOLE —
|
|
58
|
+
* its SKILL.md body (frontmatter stripped) as the whisper's first-class
|
|
59
|
+
* payload, up to FULL_BODY_MAX_CHARS, the file named and the remainder
|
|
60
|
+
* pointed at when the body exceeds the cap. Every lower rank stays on
|
|
61
|
+
* the pointer tier: a bounded excerpt (≤ MAX_EXCERPT_CHARS) plus an
|
|
62
|
+
* explicit read pointer. One body per whisper and one per skill per
|
|
63
|
+
* session — a skill whose body already landed is a pointer when it
|
|
64
|
+
* matches again. Best-effort: an unreadable file stays on the pointer
|
|
65
|
+
* tier, because a body that never arrived is not delivered.
|
|
66
|
+
* 6. No reply ritual: the whisper names the SKILL.md path and stops there —
|
|
67
|
+
* a read is the conversion signal where a read is still needed, and the
|
|
68
|
+
* solicited one-line reply is honored 2% of the time (channel noise, not
|
|
69
|
+
* information).
|
|
70
|
+
* 7. Adoption counter: per-skill `suggested`/`loaded`/`fullBody` counters,
|
|
71
|
+
* incremented on delivery, on load, and on a first-class body delivery
|
|
72
|
+
* respectively, surfaced by the `skill_stats` tool. `fullBody` counts
|
|
73
|
+
* deliveries the whisper carried whole (or capped) rather than as an
|
|
74
|
+
* excerpt, so the effect of the body tier is separable from the count
|
|
75
|
+
* of pointers; both move for the same message, so their difference is
|
|
76
|
+
* the pointer-only share. `suggested` counts DELIVERED suggestions: the
|
|
77
|
+
* counter increments only after `sendTrackedMessage` reports the whisper
|
|
78
|
+
* was accepted, so the number measures the suggestion channel rather
|
|
79
|
+
* than the intent to use it. A load has two evidence grades — a verbal
|
|
80
|
+
* claim (the LOADED
|
|
72
81
|
* probe reply, an honor-system grade the whisper does not solicit; the
|
|
73
82
|
* counter stays monotone for the store's series) and a detected actual
|
|
74
83
|
* load (SKILL.md read seen by the tool_result read-detector; failed
|
|
@@ -154,11 +163,31 @@ export const LOADED_COOLDOWN_TURNS = 30;
|
|
|
154
163
|
/** Minimum keyword length to consider significant. */
|
|
155
164
|
const MIN_KEYWORD_LENGTH = 4;
|
|
156
165
|
/**
|
|
157
|
-
* Max characters of SKILL.md body content carried in a
|
|
158
|
-
*
|
|
159
|
-
*
|
|
166
|
+
* Max characters of SKILL.md body content carried in a POINTER row, per
|
|
167
|
+
* skill: the excerpt every match below the top rank gets, and the fallback
|
|
168
|
+
* for a top match whose file cannot be read (~2 rows × 300 chars +
|
|
169
|
+
* boilerplate). Unchanged by the body tier below; the row always points at
|
|
170
|
+
* the full file for the rest.
|
|
160
171
|
*/
|
|
161
172
|
export const MAX_EXCERPT_CHARS = 300;
|
|
173
|
+
/**
|
|
174
|
+
* Max characters of a SKILL.md body delivered first-class: the whole text of
|
|
175
|
+
* the whisper's best match, frontmatter stripped.
|
|
176
|
+
*
|
|
177
|
+
* The number is measured against the shipped pack, not picked. The 34 skill
|
|
178
|
+
* bodies run 385 to 29,997 characters, median 6,614, and 23 of them fit
|
|
179
|
+
* inside 12,000 whole; the ones past it are reference documents whose
|
|
180
|
+
* remainder is one read away and now named at the cut. Under the divisor the
|
|
181
|
+
* rest of the surface prices a read with (CHARS_PER_TOKEN = 4, also pi-core's
|
|
182
|
+
* estimateTokens), a body at the cap is 3,000 estTokens.
|
|
183
|
+
*
|
|
184
|
+
* That is the payload of one delivery: a body, plus at most MAX_EXCERPT_CHARS
|
|
185
|
+
* per other row, at most MAX_INJECTED rows. The read it stands in for costs
|
|
186
|
+
* the same body characters plus a tool call and a round trip, so a body
|
|
187
|
+
* delivered whole is never dearer than the conversion it removes; a body past
|
|
188
|
+
* the cap costs the cap and says where the rest is.
|
|
189
|
+
*/
|
|
190
|
+
export const FULL_BODY_MAX_CHARS = 12_000;
|
|
162
191
|
/**
|
|
163
192
|
* Minimum score for a skill whose match never touches its NAME (description
|
|
164
193
|
* and/or filePath keyword hits only). Name matches qualify at any score.
|
|
@@ -272,6 +301,7 @@ function getState(ctx) {
|
|
|
272
301
|
drift: initialDrift(),
|
|
273
302
|
applicability: initialApplicability(),
|
|
274
303
|
obligations: initialObligations(),
|
|
304
|
+
fullBodies: new Set(),
|
|
275
305
|
}));
|
|
276
306
|
}
|
|
277
307
|
// Shared module-level variable rather than a per-module copy: the import
|
|
@@ -654,18 +684,27 @@ export function stripSkillFrontmatter(content) {
|
|
|
654
684
|
return text; // no closing delimiter — treat the whole doc as body
|
|
655
685
|
}
|
|
656
686
|
/**
|
|
657
|
-
*
|
|
658
|
-
* mark
|
|
687
|
+
* Whole body when it fits, else a cut at a word boundary with the truncation
|
|
688
|
+
* mark. Pure.
|
|
689
|
+
*
|
|
690
|
+
* One rule for both tiers: a pointer row's 300-character excerpt and a
|
|
691
|
+
* first-class body at FULL_BODY_MAX_CHARS cut the same way, so a body ending
|
|
692
|
+
* mid-word reads as a cut in either, and the cut lands at whitespace whenever
|
|
693
|
+
* the text carries any in the last stretch before the cap.
|
|
659
694
|
*/
|
|
660
|
-
export function
|
|
661
|
-
const body = stripSkillFrontmatter(content).trim();
|
|
695
|
+
export function cutSkillBody(body, maxChars) {
|
|
662
696
|
if (body.length <= maxChars)
|
|
663
697
|
return body;
|
|
664
698
|
const cut = body.slice(0, maxChars);
|
|
665
|
-
// Cut at a word boundary when possible; always collapse trailing whitespace.
|
|
666
699
|
const boundary = cut.lastIndexOf(" ");
|
|
667
|
-
|
|
668
|
-
|
|
700
|
+
return (boundary > maxChars * 0.6 ? cut.slice(0, boundary) : cut).trimEnd() + "…";
|
|
701
|
+
}
|
|
702
|
+
/**
|
|
703
|
+
* Bounded excerpt of a skill body: strip frontmatter, trim, cap at maxChars,
|
|
704
|
+
* mark truncation. Pure.
|
|
705
|
+
*/
|
|
706
|
+
export function extractSkillExcerpt(content, maxChars = MAX_EXCERPT_CHARS) {
|
|
707
|
+
return cutSkillBody(stripSkillFrontmatter(content).trim(), maxChars);
|
|
669
708
|
}
|
|
670
709
|
/**
|
|
671
710
|
* Read a SKILL.md from disk and return a bounded body excerpt.
|
|
@@ -680,32 +719,109 @@ export function readSkillExcerpt(filePath, maxChars = MAX_EXCERPT_CHARS) {
|
|
|
680
719
|
return "";
|
|
681
720
|
}
|
|
682
721
|
}
|
|
722
|
+
/**
|
|
723
|
+
* Read a SKILL.md into a deliverable body at the body-tier cap.
|
|
724
|
+
* Returns undefined on any error (missing file, unreadable) AND on an empty
|
|
725
|
+
* body: the caller stays on the pointer tier, because a body that never
|
|
726
|
+
* arrived must not be counted as delivered.
|
|
727
|
+
*/
|
|
728
|
+
export function readSkillBody(filePath, maxChars = FULL_BODY_MAX_CHARS) {
|
|
729
|
+
try {
|
|
730
|
+
const body = stripSkillFrontmatter(readFileSync(filePath, "utf-8")).trim();
|
|
731
|
+
if (!body)
|
|
732
|
+
return undefined;
|
|
733
|
+
return { text: cutSkillBody(body, maxChars), truncated: body.length > maxChars };
|
|
734
|
+
}
|
|
735
|
+
catch {
|
|
736
|
+
return undefined;
|
|
737
|
+
}
|
|
738
|
+
}
|
|
683
739
|
/** Collapse whitespace/newlines to single spaces for a one-line whisper bullet. */
|
|
684
740
|
function toOneLine(text) {
|
|
685
741
|
return text.replace(/\s+/g, " ").trim();
|
|
686
742
|
}
|
|
743
|
+
/** The whisper's opening line when every row is a pointer. */
|
|
744
|
+
const WHISPER_HEADER = "[SKILL SUGGESTION] These skills match your current task; their content is excerpted below:";
|
|
745
|
+
/** The closing catalog pointer every message carries. */
|
|
746
|
+
const WHISPER_TRAILER = "(Use `list_skills` to see all available skills; read a SKILL.md file for full context.)";
|
|
747
|
+
/**
|
|
748
|
+
* One pointer row: a bounded body excerpt (or the description when the file
|
|
749
|
+
* is unreadable), collapsed to one line, followed by the read pointer.
|
|
750
|
+
*/
|
|
751
|
+
function pointerRow(skill) {
|
|
752
|
+
const excerpt = readSkillExcerpt(skill.filePath) || skill.description;
|
|
753
|
+
// Strip the truncation mark (if any) — the read pointer follows immediately.
|
|
754
|
+
const lead = toOneLine(excerpt)
|
|
755
|
+
.slice(0, MAX_EXCERPT_CHARS)
|
|
756
|
+
.replace(/\.\.\.$/, "")
|
|
757
|
+
.replace(/…$/, "");
|
|
758
|
+
return `- ${skill.name}: ${lead} — read \`${skill.filePath}\` for the full skill.`;
|
|
759
|
+
}
|
|
760
|
+
/**
|
|
761
|
+
* Format the steer whisper for a recommendation, in two tiers.
|
|
762
|
+
*
|
|
763
|
+
* `fullBodySkill` names the one skill whose SKILL.md body the message carries
|
|
764
|
+
* first-class. The caller decides it from the session's already-delivered set
|
|
765
|
+
* (see pickFullBodySkill), so a re-match, an unreadable file or a skill this
|
|
766
|
+
* session already received leaves the message on the pointer tier.
|
|
767
|
+
*
|
|
768
|
+
* A body inside the cap is delivered whole and the message says so, which is
|
|
769
|
+
* what makes the read call unnecessary for that skill; a body past it is cut
|
|
770
|
+
* once at a word boundary, the file is named, and the message says the rest
|
|
771
|
+
* is there. Every other row keeps the pointer tier: MAX_EXCERPT_CHARS of
|
|
772
|
+
* body, one line, plus the path.
|
|
773
|
+
*
|
|
774
|
+
* The returned `body` is the fact the counter and the once-per-session record
|
|
775
|
+
* are written from, and it is present only when a body actually landed.
|
|
776
|
+
*/
|
|
777
|
+
export function formatWhisperContent(skills, fullBodySkill) {
|
|
778
|
+
const lead = fullBodySkill ? skills.find((s) => s.name === fullBodySkill) : undefined;
|
|
779
|
+
const body = lead ? readSkillBody(lead.filePath) : undefined;
|
|
780
|
+
if (!lead || !body) {
|
|
781
|
+
return { text: `${WHISPER_HEADER}\n${skills.map(pointerRow).join("\n")}\n${WHISPER_TRAILER}` };
|
|
782
|
+
}
|
|
783
|
+
const rows = skills.filter((s) => s.name !== lead.name).map(pointerRow);
|
|
784
|
+
const parts = [
|
|
785
|
+
body.truncated
|
|
786
|
+
? `[SKILL SUGGESTION] ${lead.name} is the best match for this task; its text is included below up to ${FULL_BODY_MAX_CHARS} characters.`
|
|
787
|
+
: `[SKILL SUGGESTION] ${lead.name} is the best match for this task; its full text is included below, so no read call is needed for it.`,
|
|
788
|
+
"",
|
|
789
|
+
body.truncated
|
|
790
|
+
? `## ${lead.name} (first ${FULL_BODY_MAX_CHARS} characters, \`${lead.filePath}\`)`
|
|
791
|
+
: `## ${lead.name} (full text, \`${lead.filePath}\`)`,
|
|
792
|
+
body.text,
|
|
793
|
+
];
|
|
794
|
+
if (body.truncated) {
|
|
795
|
+
parts.push("", `The rest of ${lead.name} is in \`${lead.filePath}\`; read it for the remainder.`);
|
|
796
|
+
}
|
|
797
|
+
if (rows.length)
|
|
798
|
+
parts.push("", rows.join("\n"));
|
|
799
|
+
parts.push("", WHISPER_TRAILER);
|
|
800
|
+
return { text: parts.join("\n"), body: { name: lead.name, truncated: body.truncated } };
|
|
801
|
+
}
|
|
687
802
|
/**
|
|
688
803
|
* Format the steer whisper content for a set of recommended skills.
|
|
689
804
|
*
|
|
690
|
-
*
|
|
691
|
-
*
|
|
692
|
-
*
|
|
693
|
-
* moment of domain match, not just a truncated description. Unreadable
|
|
694
|
-
* files fall back to the description (also bounded, one line).
|
|
805
|
+
* `skills` arrives ranked (best first). The text is the pointer tier for
|
|
806
|
+
* every row; pass `fullBodySkill` to deliver one body first-class — see
|
|
807
|
+
* formatWhisperContent, which this delegates to.
|
|
695
808
|
*/
|
|
696
|
-
export function formatWhisper(skills) {
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
809
|
+
export function formatWhisper(skills, fullBodySkill) {
|
|
810
|
+
return formatWhisperContent(skills, fullBodySkill).text;
|
|
811
|
+
}
|
|
812
|
+
/**
|
|
813
|
+
* Which skill the whisper may carry first-class: the best-ranked match, and
|
|
814
|
+
* only while this session has not delivered that skill's body already.
|
|
815
|
+
*
|
|
816
|
+
* The rule fixes the payload at one body per message and one per skill per
|
|
817
|
+
* session. A re-match is a pointer because the body is in context; a lower
|
|
818
|
+
* rank is never expanded because the rank is what the body tier is for. Pure.
|
|
819
|
+
*/
|
|
820
|
+
export function pickFullBodySkill(ranked, delivered) {
|
|
821
|
+
const top = ranked[0];
|
|
822
|
+
if (!top)
|
|
823
|
+
return undefined;
|
|
824
|
+
return delivered.has(top.name) ? undefined : top.name;
|
|
709
825
|
}
|
|
710
826
|
const STATS_KEY = "skills-usage-stats";
|
|
711
827
|
function getStats(ctx) {
|
|
@@ -720,7 +836,7 @@ export function getSkillStats(ctx) {
|
|
|
720
836
|
export function recordSkillSuggestion(ctx, names) {
|
|
721
837
|
const stats = getStats(ctx);
|
|
722
838
|
for (const name of names) {
|
|
723
|
-
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0 });
|
|
839
|
+
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0, fullBody: 0 });
|
|
724
840
|
s.suggested++;
|
|
725
841
|
recordDurable(name, "suggested");
|
|
726
842
|
}
|
|
@@ -735,7 +851,7 @@ export function recordSkillLoad(ctx, name) {
|
|
|
735
851
|
if (!name)
|
|
736
852
|
return;
|
|
737
853
|
const stats = getStats(ctx);
|
|
738
|
-
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0 });
|
|
854
|
+
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0, fullBody: 0 });
|
|
739
855
|
s.loaded++;
|
|
740
856
|
s.actual++;
|
|
741
857
|
recordDurable(name, "actual");
|
|
@@ -751,11 +867,29 @@ export function recordSkillClaim(ctx, name) {
|
|
|
751
867
|
if (!name)
|
|
752
868
|
return;
|
|
753
869
|
const stats = getStats(ctx);
|
|
754
|
-
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0 });
|
|
870
|
+
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0, fullBody: 0 });
|
|
755
871
|
s.loaded++;
|
|
756
872
|
s.claimed++;
|
|
757
873
|
recordDurable(name, "claim");
|
|
758
874
|
}
|
|
875
|
+
/**
|
|
876
|
+
* Record a FIRST-CLASS BODY delivery: the whisper carried this skill's body as
|
|
877
|
+
* its payload rather than a bounded excerpt.
|
|
878
|
+
*
|
|
879
|
+
* `suggested` moved for the same message, so the pair reads "of the
|
|
880
|
+
* suggestions delivered, how many arrived whole" without a second channel to
|
|
881
|
+
* instrument later. Only a body that actually landed in a delivered message is
|
|
882
|
+
* recorded: a suppressed whisper moves neither counter, and an unreadable file
|
|
883
|
+
* leaves the message on the pointer tier.
|
|
884
|
+
*/
|
|
885
|
+
export function recordSkillFullDelivery(ctx, name) {
|
|
886
|
+
if (!name)
|
|
887
|
+
return;
|
|
888
|
+
const stats = getStats(ctx);
|
|
889
|
+
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0, fullBody: 0 });
|
|
890
|
+
s.fullBody++;
|
|
891
|
+
recordDurable(name, "fullBody");
|
|
892
|
+
}
|
|
759
893
|
let _durableStore;
|
|
760
894
|
/** Normalize one raw file entry; undefined when the entry is not usable. */
|
|
761
895
|
function normalizeDurableEntry(raw) {
|
|
@@ -770,11 +904,15 @@ function normalizeDurableEntry(raw) {
|
|
|
770
904
|
const actual = typeof r.actual === "number" && Number.isFinite(r.actual)
|
|
771
905
|
? r.actual
|
|
772
906
|
: Math.max(0, loaded - claimed);
|
|
907
|
+
// Rows written before the body tier carry no fullBody: the count starts at
|
|
908
|
+
// zero for them, the same way a legacy row's claimed starts at zero.
|
|
909
|
+
const fullBody = typeof r.fullBody === "number" && Number.isFinite(r.fullBody) ? r.fullBody : 0;
|
|
773
910
|
return {
|
|
774
911
|
suggested,
|
|
775
912
|
loaded,
|
|
776
913
|
claimed,
|
|
777
914
|
actual,
|
|
915
|
+
fullBody,
|
|
778
916
|
lastAt: typeof r.lastAt === "string" ? r.lastAt : "",
|
|
779
917
|
// Rows without an epoch predate the split: their `suggested` may mix
|
|
780
918
|
// pre-delivery-regime increments with delivered ones.
|
|
@@ -849,12 +987,16 @@ function recordDurable(name, kind) {
|
|
|
849
987
|
loaded: 0,
|
|
850
988
|
claimed: 0,
|
|
851
989
|
actual: 0,
|
|
990
|
+
fullBody: 0,
|
|
852
991
|
lastAt: "",
|
|
853
992
|
epoch: "delivered",
|
|
854
993
|
});
|
|
855
994
|
if (kind === "suggested") {
|
|
856
995
|
entry.suggested++;
|
|
857
996
|
}
|
|
997
|
+
else if (kind === "fullBody") {
|
|
998
|
+
entry.fullBody++;
|
|
999
|
+
}
|
|
858
1000
|
else {
|
|
859
1001
|
entry.loaded++;
|
|
860
1002
|
if (kind === "claim")
|
|
@@ -1211,6 +1353,10 @@ function stepInform(pi, ctx, state, ev) {
|
|
|
1211
1353
|
const held = state.obligations.legs.get(skill.name);
|
|
1212
1354
|
if (held?.read)
|
|
1213
1355
|
continue; // the body is in context; the obligation is met
|
|
1356
|
+
// The body arrived first-class in this session's whisper: the line's
|
|
1357
|
+
// premise (a body whose file was never opened) is false, so it stays shut.
|
|
1358
|
+
if (state.fullBodies.has(skill.name))
|
|
1359
|
+
continue;
|
|
1214
1360
|
if (held?.informed)
|
|
1215
1361
|
continue; // one line per session per skill
|
|
1216
1362
|
const delivered = sendTrackedMessage(pi, {
|
|
@@ -1412,7 +1558,11 @@ export function registerAutoInject(pi) {
|
|
|
1412
1558
|
return;
|
|
1413
1559
|
}
|
|
1414
1560
|
const skillsToInject = toInject.map((s) => s.skill);
|
|
1415
|
-
|
|
1561
|
+
// The body tier is the best match's, and only while this session has not
|
|
1562
|
+
// already received that body: the decision is the session's, the render
|
|
1563
|
+
// is the formatter's.
|
|
1564
|
+
const content = formatWhisperContent(skillsToInject, pickFullBodySkill(skillsToInject, state.fullBodies));
|
|
1565
|
+
const text = content.text;
|
|
1416
1566
|
// Delivery first, bookkeeping second: a suggestion that a suppression
|
|
1417
1567
|
// path drops must neither consume its cooldown slot nor move a counter.
|
|
1418
1568
|
// See the module header for why the cap is bypassed here.
|
|
@@ -1424,6 +1574,7 @@ export function registerAutoInject(pi) {
|
|
|
1424
1574
|
[BRAID_INJECTED]: true,
|
|
1425
1575
|
[BRAID_SOURCE]: "skills-auto-inject",
|
|
1426
1576
|
skills: skillsToInject.map((s) => s.name),
|
|
1577
|
+
...(content.body ? { fullBody: content.body.name } : {}),
|
|
1427
1578
|
},
|
|
1428
1579
|
}, { delivery: "park", deliverAs: "steer" }, { type: "context", source: "skills-auto-inject" }, { bypassFloodCap: true });
|
|
1429
1580
|
if (!delivered) {
|
|
@@ -1451,6 +1602,14 @@ export function registerAutoInject(pi) {
|
|
|
1451
1602
|
recordSkillSuggestion(ctx, skillsToInject.map((s) => s.name));
|
|
1452
1603
|
// The same delivery is an obligation leg: the body was offered here.
|
|
1453
1604
|
noteObligationSuggested(ctx, skillsToInject.map((s) => s.name));
|
|
1605
|
+
// The body tier is counted BESIDE the suggestion, not instead of it, and
|
|
1606
|
+
// only now that the message is in the stream: the pair is what makes the
|
|
1607
|
+
// effect measurable from the store. The session set is written with it,
|
|
1608
|
+
// so the next match of the same skill is a pointer.
|
|
1609
|
+
if (content.body) {
|
|
1610
|
+
state.fullBodies.add(content.body.name);
|
|
1611
|
+
recordSkillFullDelivery(ctx, content.body.name);
|
|
1612
|
+
}
|
|
1454
1613
|
}
|
|
1455
1614
|
catch (err) {
|
|
1456
1615
|
log.debug(`[skills-auto-inject] Error in before_agent_start: ${err}`);
|
|
@@ -37,6 +37,33 @@ import { recordToolCall, flushAnalytics } from "./core.js";
|
|
|
37
37
|
import { formatCurrentSession, formatAllSessions } from "./format.js";
|
|
38
38
|
import { TURN_END, TOOL_EXECUTION_START, TOOL_EXECUTION_END, SESSION_SHUTDOWN, } from "../../../lib/core/event-names.js";
|
|
39
39
|
const log = createLogger("analytics");
|
|
40
|
+
/** The three reports one command prints, keyed by the verb a script types. */
|
|
41
|
+
const ANALYTICS_SCOPES = {
|
|
42
|
+
session: {
|
|
43
|
+
label: "This session",
|
|
44
|
+
render: (ctx) => formatCurrentSession(getAnalyticsStateInternal(ctx)),
|
|
45
|
+
},
|
|
46
|
+
all: { label: "All sessions", render: () => formatAllSessions() },
|
|
47
|
+
ab: { label: "A/B variants", render: () => formatABResults() },
|
|
48
|
+
};
|
|
49
|
+
/** Print one scope through the formatter that scope already owned. */
|
|
50
|
+
function showAnalyticsScope(scope, ctx) {
|
|
51
|
+
ctx.ui.notify(ANALYTICS_SCOPES[scope].render(ctx), "info");
|
|
52
|
+
}
|
|
53
|
+
/** No argument: ask the scope in the TUI; headless prints the default scope. */
|
|
54
|
+
async function pickAnalyticsScope(ctx) {
|
|
55
|
+
if (ctx.mode !== "tui") {
|
|
56
|
+
ctx.ui.notify(`${ANALYTICS_SCOPES.session.render(ctx)}\n\nOther scopes: /analytics all, /analytics ab`, "info");
|
|
57
|
+
return;
|
|
58
|
+
}
|
|
59
|
+
const labels = Object.values(ANALYTICS_SCOPES).map((scope) => scope.label);
|
|
60
|
+
const chosen = await ctx.ui.select("Analytics scope", labels);
|
|
61
|
+
if (chosen === undefined)
|
|
62
|
+
return;
|
|
63
|
+
const scope = Object.keys(ANALYTICS_SCOPES).find((key) => ANALYTICS_SCOPES[key].label === chosen);
|
|
64
|
+
if (scope)
|
|
65
|
+
showAnalyticsScope(scope, ctx);
|
|
66
|
+
}
|
|
40
67
|
export default function analyticsExtension(pi) {
|
|
41
68
|
registerSessionStartHandler(pi, SessionPhase.MemoryState, async (_event, ctx) => {
|
|
42
69
|
resetCriticStats();
|
|
@@ -323,29 +350,25 @@ export default function analyticsExtension(pi) {
|
|
|
323
350
|
flushAnalytics(state, false);
|
|
324
351
|
});
|
|
325
352
|
pi.registerCommand("analytics", {
|
|
326
|
-
description: "Show tool analytics
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
pi.registerCommand("analytics:ab", {
|
|
340
|
-
description: "Show A/B experiment results across variants",
|
|
341
|
-
handler: async (_args, ctx) => {
|
|
342
|
-
ctx.ui.notify(formatABResults(), "info");
|
|
353
|
+
description: "Show tool analytics. No argument asks the scope in the TUI. " +
|
|
354
|
+
"Usage: /analytics [session|all|ab]",
|
|
355
|
+
handler: async (args, ctx) => {
|
|
356
|
+
const scope = (args ?? "").trim().toLowerCase();
|
|
357
|
+
if (scope === "") {
|
|
358
|
+
await pickAnalyticsScope(ctx);
|
|
359
|
+
return;
|
|
360
|
+
}
|
|
361
|
+
if (!(scope in ANALYTICS_SCOPES)) {
|
|
362
|
+
ctx.ui.notify(`Unknown scope "${scope}". Usage: /analytics [session|all|ab]`, "warning");
|
|
363
|
+
return;
|
|
364
|
+
}
|
|
365
|
+
showAnalyticsScope(scope, ctx);
|
|
343
366
|
},
|
|
344
367
|
});
|
|
345
368
|
// No agent-callable observability tools here (session metrics / tool
|
|
346
369
|
// reliability): the agent rarely needs self-observability and no internal
|
|
347
370
|
// caller used them. Background tracking (toolMetrics, sessionStartTime)
|
|
348
|
-
// still runs and feeds event-bus alerts and the analytics
|
|
371
|
+
// still runs and feeds event-bus alerts and the analytics scopes; the
|
|
349
372
|
// A/B variant is set programmatically via
|
|
350
373
|
// getAnalyticsStateInternal(ctx).abVariant.
|
|
351
374
|
}
|
package/dist/index.d.ts
CHANGED
|
@@ -18,8 +18,6 @@
|
|
|
18
18
|
* Subagent API:
|
|
19
19
|
* Researcher subagents can call `/modules` (verbs: on, off, toggle, reset,
|
|
20
20
|
* all on|off, list) to control extension loading during benchmark experiments.
|
|
21
|
-
* The six former names (modules-enable, modules-disable, modules-toggle,
|
|
22
|
-
* modules-reset, modules-list, modules-status) forward to it for one release.
|
|
23
21
|
*/
|
|
24
22
|
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
25
23
|
export default function braidExtension(pi: ExtensionAPI): Promise<void>;
|
package/dist/index.js
CHANGED
|
@@ -18,8 +18,6 @@
|
|
|
18
18
|
* Subagent API:
|
|
19
19
|
* Researcher subagents can call `/modules` (verbs: on, off, toggle, reset,
|
|
20
20
|
* all on|off, list) to control extension loading during benchmark experiments.
|
|
21
|
-
* The six former names (modules-enable, modules-disable, modules-toggle,
|
|
22
|
-
* modules-reset, modules-list, modules-status) forward to it for one release.
|
|
23
21
|
*/
|
|
24
22
|
import { readFileSync } from "node:fs";
|
|
25
23
|
import { dirname, join } from "node:path";
|
package/dist/loader/api.d.ts
CHANGED
|
@@ -17,11 +17,8 @@
|
|
|
17
17
|
* alone; argument completion and `list` are the places that enumerate what is
|
|
18
18
|
* accepted.
|
|
19
19
|
*
|
|
20
|
-
* The
|
|
21
|
-
*
|
|
22
|
-
* modules-reset, modules-list, modules-status. Each maps its whole argument
|
|
23
|
-
* onto the equivalent argv, so a script written against the old names keeps
|
|
24
|
-
* working until it is pointed at `/modules`.
|
|
20
|
+
* The list covers the core manifest only: a contrib extension is toggled
|
|
21
|
+
* through its `braid.contrib.<name>` key in settings, not from this command.
|
|
25
22
|
*/
|
|
26
23
|
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
27
24
|
export default function modulesApiExtension(pi: ExtensionAPI): Promise<void>;
|
package/dist/loader/api.js
CHANGED
|
@@ -17,11 +17,8 @@
|
|
|
17
17
|
* alone; argument completion and `list` are the places that enumerate what is
|
|
18
18
|
* accepted.
|
|
19
19
|
*
|
|
20
|
-
* The
|
|
21
|
-
*
|
|
22
|
-
* modules-reset, modules-list, modules-status. Each maps its whole argument
|
|
23
|
-
* onto the equivalent argv, so a script written against the old names keeps
|
|
24
|
-
* working until it is pointed at `/modules`.
|
|
20
|
+
* The list covers the core manifest only: a contrib extension is toggled
|
|
21
|
+
* through its `braid.contrib.<name>` key in settings, not from this command.
|
|
25
22
|
*/
|
|
26
23
|
import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
|
|
27
24
|
import { Container, SettingsList, } from "@earendil-works/pi-tui";
|
|
@@ -39,6 +36,8 @@ const VERBS = {
|
|
|
39
36
|
};
|
|
40
37
|
const USAGE = "Usage: /modules [on|off|toggle|reset|all|list] <ref>\n" +
|
|
41
38
|
"A ref is an extension id or a module group name. Tab completes both.";
|
|
39
|
+
/** Why a contrib extension is absent from this list, stated where it shows. */
|
|
40
|
+
const CONTRIB_NOTE = "Contrib extensions are toggled through braid.contrib in settings, not from this list.";
|
|
42
41
|
export default async function modulesApiExtension(pi) {
|
|
43
42
|
const run = async (argv, ctx) => {
|
|
44
43
|
const notify = (message, type = "info") => {
|
|
@@ -132,34 +131,7 @@ export default async function modulesApiExtension(pi) {
|
|
|
132
131
|
getArgumentCompletions: completeModules,
|
|
133
132
|
handler: (args, ctx) => run(splitArgs(args), ctx),
|
|
134
133
|
});
|
|
135
|
-
|
|
136
|
-
description: "Alias of /modules on <ref>. Retained for one release.",
|
|
137
|
-
getArgumentCompletions: completeRefs("on"),
|
|
138
|
-
handler: (args, ctx) => run([...forwarded("on", args)], ctx),
|
|
139
|
-
});
|
|
140
|
-
pi.registerCommand("modules-disable", {
|
|
141
|
-
description: "Alias of /modules off <ref>. Retained for one release.",
|
|
142
|
-
getArgumentCompletions: completeRefs("off"),
|
|
143
|
-
handler: (args, ctx) => run([...forwarded("off", args)], ctx),
|
|
144
|
-
});
|
|
145
|
-
pi.registerCommand("modules-toggle", {
|
|
146
|
-
description: "Alias of /modules toggle <ref>. Retained for one release.",
|
|
147
|
-
getArgumentCompletions: completeRefs("toggle"),
|
|
148
|
-
handler: (args, ctx) => run([...forwarded("toggle", args)], ctx),
|
|
149
|
-
});
|
|
150
|
-
pi.registerCommand("modules-reset", {
|
|
151
|
-
description: "Alias of /modules reset. Retained for one release.",
|
|
152
|
-
handler: async (_args, ctx) => run(["reset"], ctx),
|
|
153
|
-
});
|
|
154
|
-
pi.registerCommand("modules-list", {
|
|
155
|
-
description: "Alias of /modules list. Retained for one release.",
|
|
156
|
-
handler: async (_args, ctx) => run(["list"], ctx),
|
|
157
|
-
});
|
|
158
|
-
pi.registerCommand("modules-status", {
|
|
159
|
-
description: "Alias of /modules list. Retained for one release.",
|
|
160
|
-
handler: async (_args, ctx) => run(["list"], ctx),
|
|
161
|
-
});
|
|
162
|
-
log.info("Module API registered: /modules (+ six forwarding aliases)");
|
|
134
|
+
log.info("Module API registered: /modules");
|
|
163
135
|
}
|
|
164
136
|
// ── Argument parsing ────────────────────────────────────────────────────────
|
|
165
137
|
/** Split a command's argument string into argv; quoted runs stay one token. */
|
|
@@ -175,10 +147,6 @@ function splitArgs(args) {
|
|
|
175
147
|
}
|
|
176
148
|
return argv;
|
|
177
149
|
}
|
|
178
|
-
/** The argv an old name forwards: its whole argument is the ref. */
|
|
179
|
-
function forwarded(verb, args) {
|
|
180
|
-
return [verb, (args ?? "").trim()];
|
|
181
|
-
}
|
|
182
150
|
/** Why a reference was refused, naming the rule instead of listing refs. */
|
|
183
151
|
function refusal(ref, verb) {
|
|
184
152
|
if (!getModuleRefs().includes(ref)) {
|
|
@@ -212,15 +180,6 @@ function completeModules(prefix) {
|
|
|
212
180
|
}
|
|
213
181
|
return null;
|
|
214
182
|
}
|
|
215
|
-
/** Completion for an old name: the whole argument text is the reference. */
|
|
216
|
-
function completeRefs(verb) {
|
|
217
|
-
return (prefix) => {
|
|
218
|
-
const typed = (prefix ?? "").toLowerCase();
|
|
219
|
-
return getModuleRefs()
|
|
220
|
-
.filter((ref) => ref.startsWith(typed))
|
|
221
|
-
.map((ref) => ({ value: ref, label: ref, description: `Forwarded to /modules ${verb}` }));
|
|
222
|
-
};
|
|
223
|
-
}
|
|
224
183
|
function completeValues(prefix, values) {
|
|
225
184
|
const typed = (prefix ?? "").toLowerCase();
|
|
226
185
|
return values
|
|
@@ -248,7 +207,7 @@ function describe(desc, origin, enabled, loaded) {
|
|
|
248
207
|
/** The rows as text, for RPC mode and the `list` verb. */
|
|
249
208
|
function renderRows() {
|
|
250
209
|
const { rows, source } = moduleRows();
|
|
251
|
-
const lines = [`Extensions (${rows.length}, config: ${source})
|
|
210
|
+
const lines = [`Extensions (${rows.length}, config: ${source}):`, CONTRIB_NOTE];
|
|
252
211
|
const width = Math.min(28, Math.max(...rows.map((row) => row.id.length)));
|
|
253
212
|
for (const row of rows) {
|
|
254
213
|
lines.push(` ${row.value.padEnd(3)} ${row.id.padEnd(width)} ${row.description}`);
|
|
@@ -266,7 +225,7 @@ async function openModuleList(ctx) {
|
|
|
266
225
|
const container = new Container();
|
|
267
226
|
container.addChild(new (class {
|
|
268
227
|
render(_width) {
|
|
269
|
-
return [theme.fg("accent", theme.bold("Extensions"))];
|
|
228
|
+
return [theme.fg("accent", theme.bold("Extensions")), theme.fg("muted", CONTRIB_NOTE)];
|
|
270
229
|
}
|
|
271
230
|
invalidate() { }
|
|
272
231
|
})());
|
package/dist/loader/loader.d.ts
CHANGED
|
@@ -96,6 +96,4 @@ export declare function getModuleStates(_ctx?: ExtensionContext): Record<string,
|
|
|
96
96
|
export declare function resetModuleOverrides(_ctx?: ExtensionContext): void;
|
|
97
97
|
/** Get all valid config reference names for API completion/docs. */
|
|
98
98
|
export declare function getModuleRefs(): string[];
|
|
99
|
-
/** @deprecated Use getModuleRefs. Kept as an alias for existing callers. */
|
|
100
|
-
export declare function getAllRefNames(): string[];
|
|
101
99
|
//# sourceMappingURL=loader.d.ts.map
|
package/dist/loader/loader.js
CHANGED
|
@@ -571,8 +571,4 @@ function topologicalSort(extIds) {
|
|
|
571
571
|
export function getModuleRefs() {
|
|
572
572
|
return allConfigRefs();
|
|
573
573
|
}
|
|
574
|
-
/** @deprecated Use getModuleRefs. Kept as an alias for existing callers. */
|
|
575
|
-
export function getAllRefNames() {
|
|
576
|
-
return getModuleRefs();
|
|
577
|
-
}
|
|
578
574
|
//# sourceMappingURL=loader.js.map
|
package/docs/LOCAL_DEV.md
CHANGED
|
@@ -138,7 +138,7 @@ before and after a full run. A non-zero delta is the leak this rule prevents.
|
|
|
138
138
|
### New fixtures: use `node:test`
|
|
139
139
|
|
|
140
140
|
A new fixture is written on `node:test`. The runner does not care which style a
|
|
141
|
-
file uses -
|
|
141
|
+
file uses - 118 of the core suite's 354 fixtures already use `node:test` - so the
|
|
142
142
|
reason is the failure the other style produces. A hand-rolled helper that calls
|
|
143
143
|
`fn()` without awaiting it discards the case's promise, so an `async` case runs
|
|
144
144
|
detached and the file can print its green tally before that case settles, with
|
package/docs/SETUP.md
CHANGED
|
@@ -397,7 +397,7 @@ braid's loader follows a four-tier precedence (high → low):
|
|
|
397
397
|
| `/modules list` | Print every extension, its description and where its state came from |
|
|
398
398
|
| `/modules reset` | Clear in-process overrides (persisted `braid.modules` stays) |
|
|
399
399
|
|
|
400
|
-
The
|
|
400
|
+
The list covers the core manifest only. A contrib extension has no entry here: it is toggled through its `braid.contrib.<name>` key in `~/.pi/agent/settings.json`.
|
|
401
401
|
|
|
402
402
|
### `BRAID_MODULES` syntax
|
|
403
403
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.43.
|
|
3
|
+
"version": "0.43.43",
|
|
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",
|