pi-braid 0.43.7 → 0.43.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +39 -0
- package/TOOLS.md +1 -1
- package/build-info.json +4 -4
- package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +21 -0
- package/dist/extensions/core/skills-tool/auto-inject.js +105 -1
- package/dist/extensions/core/skills-tool/index.js +20 -2
- package/dist/extensions/core/skills-tool/loading-guidance.d.ts +4 -1
- package/dist/extensions/core/skills-tool/loading-guidance.js +4 -1
- package/dist/extensions/core/skills-tool/session-records.d.ts +107 -9
- package/dist/extensions/core/skills-tool/session-records.js +141 -5
- package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +5 -1
- package/dist/extensions/enforcement/handlers/register-tool-call.js +5 -2
- package/dist/extensions/enforcement/verification-judge.d.ts +7 -0
- package/dist/extensions/enforcement/verification-judge.js +28 -21
- package/dist/extensions/memory/session-recall/ask.d.ts +95 -0
- package/dist/extensions/memory/session-recall/ask.js +376 -0
- package/dist/extensions/memory/session-recall/corpus-index.d.ts +200 -0
- package/dist/extensions/memory/session-recall/corpus-index.js +480 -0
- package/dist/extensions/memory/session-recall/index.js +173 -21
- package/dist/extensions/memory/session-recall/search.d.ts +29 -0
- package/dist/extensions/memory/session-recall/search.js +42 -9
- package/dist/lib/ai/payload-hygiene.d.ts +3 -0
- package/dist/lib/ai/payload-hygiene.js +34 -2
- package/dist/lib/config/braid-paths.d.ts +4 -0
- package/dist/lib/config/braid-paths.js +6 -0
- package/dist/lib/config/braid-settings.d.ts +22 -0
- package/dist/lib/config/braid-settings.js +15 -0
- package/dist/lib/detection/tool-loop-detector.d.ts +95 -46
- package/dist/lib/detection/tool-loop-detector.js +288 -180
- package/dist/lib/reasoning/dreamer.d.ts +2 -1
- package/dist/lib/reasoning/dreamer.js +12 -7
- package/docs/LOCAL_DEV.md +1 -1
- package/docs/SETUP.md +1 -0
- package/package.json +1 -1
- package/src/extensions/core/AGENTS.md +3 -2
- package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
- package/src/extensions/core/skills-tool/auto-inject.ts +118 -1
- package/src/extensions/core/skills-tool/index.ts +21 -1
- package/src/extensions/core/skills-tool/loading-guidance.ts +4 -1
- package/src/extensions/core/skills-tool/session-records.ts +201 -9
- package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +5 -1
- package/src/extensions/enforcement/handlers/register-tool-call.ts +5 -2
- package/src/extensions/enforcement/verification-judge.ts +32 -25
- package/src/extensions/memory/AGENTS.md +2 -2
- package/src/extensions/memory/session-recall/AGENTS.md +92 -18
- package/src/extensions/memory/session-recall/ask.ts +435 -0
- package/src/extensions/memory/session-recall/corpus-index.ts +609 -0
- package/src/extensions/memory/session-recall/index.ts +202 -21
- package/src/extensions/memory/session-recall/search.ts +61 -10
- package/src/lib/ai/payload-hygiene.ts +47 -3
- package/src/lib/config/braid-paths.ts +7 -0
- package/src/lib/config/braid-settings.ts +42 -3
- package/src/lib/detection/AGENTS.md +8 -7
- package/src/lib/detection/tool-loop-detector.ts +339 -195
- package/src/lib/reasoning/dreamer.ts +13 -6
package/CHANGELOG.md
CHANGED
|
@@ -53,6 +53,45 @@ record; the tag scheme above applies unchanged.
|
|
|
53
53
|
|
|
54
54
|
---
|
|
55
55
|
|
|
56
|
+
## Core — 0.43.8 (2026-10-31: the harness stops accusing work that happened, and starts answering from the archive)
|
|
57
|
+
|
|
58
|
+
- **An unterminated page cannot delete the evidence tail any more.** A redaction of a detected HTML page
|
|
59
|
+
ended at the end of the whole outbound prompt whenever the page arrived without its closing tag, and that
|
|
60
|
+
sanitizer runs on every internal LLM body, judges included. One unterminated page inside one tool result
|
|
61
|
+
deleted 85 of 140 evidence lines and all four ground-truth sections before the model saw them, and a
|
|
62
|
+
verification judge, whose schema has no way to say "cannot verify", then reported work-not-done against a
|
|
63
|
+
delivered project. The span now ends at the end of the enclosing line or at a page cap far above any
|
|
64
|
+
observed page, whichever comes first, and a clamped span logs one line naming the byte count so a tail loss
|
|
65
|
+
is visible instead of silent. The judge's prompt also puts git history, the deliverables manifest and the
|
|
66
|
+
code-changes flag ahead of the bounded sections, so a future bound degrades evidence rather than truth. The
|
|
67
|
+
module had no test before; it has one now, and it carries both directions, including the control that an
|
|
68
|
+
oversized unterminated page is still redacted up to the cap.
|
|
69
|
+
- **The loop whisper counts calls, not tool names.** The detector kept an array of tool names and fired on
|
|
70
|
+
sixteen consecutive equal names, so a chain of seventeen different shell commands was indistinguishable from
|
|
71
|
+
seventeen identical retries, and the message claimed "no progress" while looking at nothing but names. In
|
|
72
|
+
the archive that whisper appears in 485 of 2,526 sessions, and both owner-run sessions examined were false
|
|
73
|
+
accusations: twenty distinct commands in one, seventeen in the other. A call now has an identity (name plus
|
|
74
|
+
normalized arguments); consecutive identical calls still fire, two alternating calls still fire, a long
|
|
75
|
+
chain of distinct calls never does, and the sentence names the repeated call and its count instead of
|
|
76
|
+
claiming progress it cannot observe.
|
|
77
|
+
- **The archive's own words are queryable.** Every user turn in the session corpus is a quarter of one
|
|
78
|
+
percent of it: 20,484 turns totalling 9.66 MB across 3,833 sessions and 341 projects, out of an archive of
|
|
79
|
+
3.8 GB. A derived index of exactly those turns is built in under two seconds and refreshed by file mtime, and
|
|
80
|
+
a `session ask` verb answers a question from them with citations, excluding the calling session by
|
|
81
|
+
construction. Recall at three is eight of ten on a pre-registered question set, with both misses shown and
|
|
82
|
+
mechanised, and the two existing search verbs are byte-identical when the index is absent.
|
|
83
|
+
- **A skill names the family it governs, and the harness says so once, after the call.** A refusal was
|
|
84
|
+
designed, measured and killed: simulated over 703 sessions and 107,463 tool calls, 2 of 30 refused calls
|
|
85
|
+
changed course. The mechanism that ships instead is an at-use inform, one line after a completed call in a
|
|
86
|
+
declared family when the body was never read, off by default, with its falsifier pre-registered: it must beat
|
|
87
|
+
the suggestion channel's own 18.8% read-follow conversion or it is noise to be deleted. Its own verdict is
|
|
88
|
+
undecided at zero informs, and 20 informs with 8 conversions is what would decide it.
|
|
89
|
+
- **The obligation rate exists and discriminates.** Per session and per skill, `suggested`, `listed`, `read`,
|
|
90
|
+
`called`, `applied`, where a call made before the read cannot be credited and a read with no call still
|
|
91
|
+
satisfies; an applicable skill with no leg row is counted unsatisfied rather than dropped. `allSatisfied`
|
|
92
|
+
over the sessions that carry both a verdict and a leg row, reported beside the read rate with that
|
|
93
|
+
denominator stated rather than implied, and a gap under five points marks the metric as worthless.
|
|
94
|
+
|
|
56
95
|
## Core — 0.43.7 (2026-10-30: an ignored skill is visible, and two rates say whether the obligation held)
|
|
57
96
|
|
|
58
97
|
- **A skill that applied and was ignored is now distinguishable from one that never applied.** The
|
package/TOOLS.md
CHANGED
|
@@ -75,7 +75,7 @@ enablement (see appendix).
|
|
|
75
75
|
| `memory` | Unified memory: recall/episodes/heuristics | memory-agent-bridge - default-enabled (manifest.ts:197) | when: before non-trivial work — build on known context; args: action recall_search / episodes_search / heuristics_list + query |
|
|
76
76
|
| `explore_paths` | Per-hypothesis file search with first-15-lines evidence | memory-agent-bridge - default-enabled (manifest.ts:197) | when: debugging with a named failure-mode hypothesis; args: hypothesis_1/2/3, each 'file because reason'; caveat: local search — no sub-agent |
|
|
77
77
|
| `conflict_qa` | Resolve contradictions between sources via the evidence pool | memory-agent-bridge - default-enabled (manifest.ts:197) | when: sources or beliefs contradict; args: action resolve + verdict; caveat: evidence-pool based, reports classification |
|
|
78
|
-
| `session` | Access past session history
|
|
78
|
+
| `session` | Access past session history: search/ask/query/analyze/stats/context | session-recall - default-enabled (manifest.ts:176, dep three-memory-stores) | when: prior-work context needed across sessions (search/query/analyze/stats), or a question about what was said or decided earlier (ask, which cites project, session, line and time); args: action + query/sessionPath; caveat: project-scoped by default, and ask refuses when the corpus index cannot answer |
|
|
79
79
|
| `error` | Inspect captured extension errors (list/get/clear/stats) | error-tracking - opt-in, disabledByDefault (manifest.ts:276) | when: a tool or extension failed and you need the captured error history; args: action list/get/clear/stats |
|
|
80
80
|
| `session_health` | Read/reset session LLM-provider health state | health-maintenance - opt-in, disabledByDefault (manifest.ts:259) | when: provider errors / auth / balance events occurred; args: action get/diagnose/recover; caveat: recover only after the user acted |
|
|
81
81
|
| `health_maintenance` | Health-based maintenance (check/commit/rollback/benchmark) | health-maintenance - opt-in, disabledByDefault (manifest.ts:259) | when: agent self-state hygiene (check/commit/rollback/benchmark); args: action; caveat: rollback needs a checkpoint hash |
|
package/build-info.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.43.
|
|
4
|
-
"sha": "
|
|
5
|
-
"shaShort": "
|
|
3
|
+
"version": "0.43.8",
|
|
4
|
+
"sha": "62f2682ee788864913159b5de15fe8cd58f39dc2",
|
|
5
|
+
"shaShort": "62f2682e",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-10-
|
|
8
|
+
"packedAt": "2026-10-31T11:13:27.517Z"
|
|
9
9
|
}
|
|
@@ -91,7 +91,7 @@ export const TOOL_GUIDELINES = {
|
|
|
91
91
|
explore_paths: "when: debugging with a named failure-mode hypothesis; args: hypothesis_1/2/3, each 'file because reason'; caveat: local search — no sub-agent",
|
|
92
92
|
conflict_qa: "when: sources or beliefs contradict; args: action resolve + verdict; caveat: evidence-pool based, reports classification",
|
|
93
93
|
// ── session-recall (default-enabled) ──
|
|
94
|
-
session: "when: prior-work context needed across sessions (search/query/analyze/stats); args: action + query/sessionPath; caveat: project-scoped by default",
|
|
94
|
+
session: "when: prior-work context needed across sessions (search/query/analyze/stats), or a question about what was said or decided earlier (ask, which cites project, session, line and time); args: action + query/sessionPath; caveat: project-scoped by default, and ask refuses when the corpus index cannot answer",
|
|
95
95
|
// ── error-tracking (opt-in) ──
|
|
96
96
|
error: "when: a tool or extension failed and you need the captured error history; args: action list/get/clear/stats",
|
|
97
97
|
// ── health-maintenance (opt-in) ──
|
|
@@ -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.
|
|
@@ -507,6 +516,18 @@ export declare function resolveDiscoveryMode(ctx: ExtensionContext): DiscoverySt
|
|
|
507
516
|
export declare function noteObligationSuggested(ctx: ExtensionContext, names: string[]): void;
|
|
508
517
|
/** Record the skills a catalog page listed (called from the list_skills tool). */
|
|
509
518
|
export declare function noteObligationListed(ctx: ExtensionContext, names: string[]): void;
|
|
519
|
+
/**
|
|
520
|
+
* The at-use line: the payload names the file and the obligation, and nothing
|
|
521
|
+
* else.
|
|
522
|
+
*
|
|
523
|
+
* Both facts are derivable from the declaration and the catalog entry. The path
|
|
524
|
+
* is the cached skill's own file path, never constructed; the family is the
|
|
525
|
+
* token the call's own name yields, which is the same token the declaration is
|
|
526
|
+
* written in. No skill name is invented in code, no tool argument is echoed,
|
|
527
|
+
* and there is nothing here for a model to reconcile with the result it just
|
|
528
|
+
* received. Pure.
|
|
529
|
+
*/
|
|
530
|
+
export declare function formatInformPayload(filePath: string, family: string): string;
|
|
510
531
|
/**
|
|
511
532
|
* Register the auto-inject handler on before_agent_start, the read-tool load
|
|
512
533
|
* detector and the drift trigger on tool_result.
|
|
@@ -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.
|
|
@@ -116,6 +125,7 @@ import { getSessionProfile, recordApplicabilityCensus, recordApplicabilityVerdic
|
|
|
116
125
|
import { evaluateApplicability } from "./applicability.js";
|
|
117
126
|
import { triggerMatches } from "./skill-triggers.js";
|
|
118
127
|
import { toolFamilyToken } from "./skill-families.js";
|
|
128
|
+
import { getSkillsInformMode } from "../../../lib/config/braid-settings.js";
|
|
119
129
|
import { advanceDrift, driftDirectoryFor, driftPayload, initialDrift, noteDriftSurface, recordDriftDrop, recordDriftFire, skillReadRoot, } from "./loading-guidance.js";
|
|
120
130
|
const log = createLogger("skills-auto-inject");
|
|
121
131
|
// Constants
|
|
@@ -1010,6 +1020,7 @@ function legsFor(state, name) {
|
|
|
1010
1020
|
skill: name,
|
|
1011
1021
|
suggested: false,
|
|
1012
1022
|
listed: false,
|
|
1023
|
+
informed: false,
|
|
1013
1024
|
read: false,
|
|
1014
1025
|
called: false,
|
|
1015
1026
|
applied: false,
|
|
@@ -1028,7 +1039,14 @@ function appendObligationRow(ctx, state, name) {
|
|
|
1028
1039
|
const legs = state.obligations.legs.get(name);
|
|
1029
1040
|
if (!legs)
|
|
1030
1041
|
return;
|
|
1031
|
-
const signature = [
|
|
1042
|
+
const signature = [
|
|
1043
|
+
legs.suggested,
|
|
1044
|
+
legs.listed,
|
|
1045
|
+
legs.informed,
|
|
1046
|
+
legs.read,
|
|
1047
|
+
legs.called,
|
|
1048
|
+
legs.applied,
|
|
1049
|
+
]
|
|
1032
1050
|
.map((flag) => (flag ? "1" : "0"))
|
|
1033
1051
|
.join("");
|
|
1034
1052
|
if (state.obligations.written.get(name) === signature)
|
|
@@ -1133,6 +1151,89 @@ function stepFamilyCalls(ctx, state, event) {
|
|
|
1133
1151
|
appendObligationRow(ctx, state, skill.name);
|
|
1134
1152
|
}
|
|
1135
1153
|
}
|
|
1154
|
+
/**
|
|
1155
|
+
* The at-use line: the payload names the file and the obligation, and nothing
|
|
1156
|
+
* else.
|
|
1157
|
+
*
|
|
1158
|
+
* Both facts are derivable from the declaration and the catalog entry. The path
|
|
1159
|
+
* is the cached skill's own file path, never constructed; the family is the
|
|
1160
|
+
* token the call's own name yields, which is the same token the declaration is
|
|
1161
|
+
* written in. No skill name is invented in code, no tool argument is echoed,
|
|
1162
|
+
* and there is nothing here for a model to reconcile with the result it just
|
|
1163
|
+
* received. Pure.
|
|
1164
|
+
*/
|
|
1165
|
+
export function formatInformPayload(filePath, family) {
|
|
1166
|
+
return (`[SKILL INFORM] \`${filePath}\` governs the \`${family}\` tool family; ` +
|
|
1167
|
+
`a call in it just ran, and that file has not been read this session. ` +
|
|
1168
|
+
`Read it before the next call in the family.`);
|
|
1169
|
+
}
|
|
1170
|
+
/**
|
|
1171
|
+
* Inform at use: a COMPLETED call landed in a tool family a visible skill's
|
|
1172
|
+
* file declares with `governs:`, and no read of that body is on the session
|
|
1173
|
+
* record. One steer line, once per session per skill.
|
|
1174
|
+
*
|
|
1175
|
+
* This is the timed alternative to refusing the call. It runs after the result
|
|
1176
|
+
* exists, it touches no result, and the only thing it can do is add a line to
|
|
1177
|
+
* the stream; every gating decision below can only make it quieter. The
|
|
1178
|
+
* suppression is the obligation record itself (the `informed` leg, beside the
|
|
1179
|
+
* `read` leg), not a parallel set, so the record that says what the session did
|
|
1180
|
+
* and the record that stops a second line are one row.
|
|
1181
|
+
*
|
|
1182
|
+
* The applied leg counts a failed call because a refusal would fire before the
|
|
1183
|
+
* tool ran and could not know the outcome; this line does not, because its
|
|
1184
|
+
* premise is a call that ran in a family the body governs.
|
|
1185
|
+
*/
|
|
1186
|
+
function stepInform(pi, ctx, state, ev) {
|
|
1187
|
+
state.informMode ??= getSkillsInformMode();
|
|
1188
|
+
if (state.informMode !== "inform")
|
|
1189
|
+
return;
|
|
1190
|
+
if (!ev?.toolName)
|
|
1191
|
+
return;
|
|
1192
|
+
if (ev.isError)
|
|
1193
|
+
return;
|
|
1194
|
+
const family = toolFamilyToken(ev.toolName);
|
|
1195
|
+
if (!family)
|
|
1196
|
+
return;
|
|
1197
|
+
for (const skill of _skillsCache) {
|
|
1198
|
+
// The at-use line is an advertisement with a path: a body the prompt
|
|
1199
|
+
// deliberately hides from the model must not be named by it either.
|
|
1200
|
+
if (skill.disableModelInvocation)
|
|
1201
|
+
continue;
|
|
1202
|
+
if (!skill.families?.length || !skill.families.includes(family))
|
|
1203
|
+
continue;
|
|
1204
|
+
const held = state.obligations.legs.get(skill.name);
|
|
1205
|
+
if (held?.read)
|
|
1206
|
+
continue; // the body is in context; the obligation is met
|
|
1207
|
+
if (held?.informed)
|
|
1208
|
+
continue; // one line per session per skill
|
|
1209
|
+
const delivered = sendTrackedMessage(pi, {
|
|
1210
|
+
customType: "skills-inform",
|
|
1211
|
+
content: [{ type: "text", text: formatInformPayload(skill.filePath, family) }],
|
|
1212
|
+
display: true,
|
|
1213
|
+
details: {
|
|
1214
|
+
[BRAID_INJECTED]: true,
|
|
1215
|
+
[BRAID_SOURCE]: "skills-auto-inject",
|
|
1216
|
+
skill: skill.name,
|
|
1217
|
+
family,
|
|
1218
|
+
},
|
|
1219
|
+
}, { delivery: "park", deliverAs: "steer" }, { type: "context", source: "skills-auto-inject" },
|
|
1220
|
+
// The module's own budget is the bound: one line per session per skill,
|
|
1221
|
+
// and only on a call in a family the body itself declares. A flood cap
|
|
1222
|
+
// would drop the line in exactly the call it exists for.
|
|
1223
|
+
{ bypassFloodCap: true });
|
|
1224
|
+
if (!delivered) {
|
|
1225
|
+
log.debug("[skills-auto-inject] at-use line suppressed before delivery; not counted");
|
|
1226
|
+
continue;
|
|
1227
|
+
}
|
|
1228
|
+
const legs = legsFor(state, skill.name);
|
|
1229
|
+
legs.informed = true;
|
|
1230
|
+
appendObligationRow(ctx, state, skill.name);
|
|
1231
|
+
// The line is a skill surface: the drift trigger stays quiet for its
|
|
1232
|
+
// window, because the pointer it exists to supply has just landed.
|
|
1233
|
+
noteDriftSurface(state.drift);
|
|
1234
|
+
log.info(`[skills-auto-inject] at-use line for "${skill.name}" (family ${family})`);
|
|
1235
|
+
}
|
|
1236
|
+
}
|
|
1136
1237
|
/**
|
|
1137
1238
|
* Fire the drift line when the work has moved into a new work area (the rule
|
|
1138
1239
|
* and its bounds live in loading-guidance.ts, beside the floor text the line
|
|
@@ -1195,6 +1296,9 @@ export function registerAutoInject(pi) {
|
|
|
1195
1296
|
// detector so a SKILL.md read of the very tool call in flight is already
|
|
1196
1297
|
// on record when the family is looked up.
|
|
1197
1298
|
stepFamilyCalls(ctx, state, ev);
|
|
1299
|
+
// The at-use line runs after both: it needs the read leg (a read in this
|
|
1300
|
+
// very result silences it) and it does not depend on the applied leg.
|
|
1301
|
+
stepInform(pi, ctx, state, ev);
|
|
1198
1302
|
stepDrift(pi, ctx, state, ev);
|
|
1199
1303
|
}
|
|
1200
1304
|
catch {
|
|
@@ -33,12 +33,12 @@
|
|
|
33
33
|
*/
|
|
34
34
|
import { Type } from "typebox";
|
|
35
35
|
import { createLogger } from "../../../lib/core/logger.js";
|
|
36
|
-
import { getSkillsRankingMode } from "../../../lib/config/braid-settings.js";
|
|
36
|
+
import { getSkillsInformMode, getSkillsRankingMode } from "../../../lib/config/braid-settings.js";
|
|
37
37
|
import { registerAutoInject, updateSkillCache, getSkillStats, getDurableSkillStats, noteObligationListed, resolveDiscoveryMode, rankSkillsDeterministic, } from "./auto-inject.js";
|
|
38
38
|
import { readSkillTriggerEntries } from "./skill-triggers.js";
|
|
39
39
|
import { readGovernedFamilies } from "./skill-families.js";
|
|
40
40
|
import { clampSectionsMax, DEFAULT_SECTIONS_MAX, SECTIONS_MAX_LIMIT, readSkillReach, } from "./reach.js";
|
|
41
|
-
import { getMonthlyAdoptionRollup, getObligationRate, getSessionApplicability, getSessionObligation, judgeSessionObligations, } from "./session-records.js";
|
|
41
|
+
import { getInformRate, getMonthlyAdoptionRollup, getObligationRate, getSessionApplicability, getSessionObligation, judgeSessionObligations, } from "./session-records.js";
|
|
42
42
|
import { checkArgumentValues } from "../../../lib/utils/argument-report.js";
|
|
43
43
|
const log = createLogger("skills-tool");
|
|
44
44
|
let cachedSkills = [];
|
|
@@ -358,6 +358,12 @@ export default function skillsToolExtension(pi) {
|
|
|
358
358
|
// obligation row at all: a build that predates the leg reads the same
|
|
359
359
|
// sessions and must see the same payload.
|
|
360
360
|
const obligationRate = getObligationRate();
|
|
361
|
+
// The at-use line's counters, folded from the same store as the channel
|
|
362
|
+
// arm beside them. Absent when the mode is off and no row was ever
|
|
363
|
+
// written, so a reader of a pre-inform store is unchanged.
|
|
364
|
+
const informRate = getInformRate();
|
|
365
|
+
const informMode = getSkillsInformMode();
|
|
366
|
+
const inform = informMode !== "off" || informRate ? { mode: informMode, ...informRate } : undefined;
|
|
361
367
|
return {
|
|
362
368
|
content: [
|
|
363
369
|
{
|
|
@@ -380,6 +386,7 @@ export default function skillsToolExtension(pi) {
|
|
|
380
386
|
...(applicability ? { applicability } : {}),
|
|
381
387
|
...(obligations ? { obligations } : {}),
|
|
382
388
|
...(obligationRate ? { obligationRate } : {}),
|
|
389
|
+
...(inform ? { inform } : {}),
|
|
383
390
|
discovery: {
|
|
384
391
|
// Whether the stock skill catalog sits in the persisted
|
|
385
392
|
// transcript (it re-enters via pi's post-compaction
|
|
@@ -408,6 +415,17 @@ export default function skillsToolExtension(pi) {
|
|
|
408
415
|
}
|
|
409
416
|
: {}),
|
|
410
417
|
...(obligationRate ? { obligationRate } : {}),
|
|
418
|
+
...(inform
|
|
419
|
+
? {
|
|
420
|
+
inform: {
|
|
421
|
+
mode: informMode,
|
|
422
|
+
informs: informRate?.informs ?? 0,
|
|
423
|
+
readFollowed: informRate?.readFollowed ?? 0,
|
|
424
|
+
conversion: informRate?.conversion ?? 0,
|
|
425
|
+
verdict: informRate?.verdict ?? "undecided",
|
|
426
|
+
},
|
|
427
|
+
}
|
|
428
|
+
: {}),
|
|
411
429
|
},
|
|
412
430
|
};
|
|
413
431
|
},
|
|
@@ -160,7 +160,10 @@ export declare function recordDriftFire(tracker: DriftTracker, directory: string
|
|
|
160
160
|
* a suppressed line is retried only after the session has done more work.
|
|
161
161
|
*/
|
|
162
162
|
export declare function recordDriftDrop(tracker: DriftTracker): void;
|
|
163
|
-
/**
|
|
163
|
+
/**
|
|
164
|
+
* Note that a skill surface (a suggestion, an at-use line, or a SKILL.md read)
|
|
165
|
+
* just landed.
|
|
166
|
+
*/
|
|
164
167
|
export declare function noteDriftSurface(tracker: DriftTracker): void;
|
|
165
168
|
/**
|
|
166
169
|
* The one-line steer: the work area and a pointer back at the catalog in the
|
|
@@ -298,7 +298,10 @@ export function recordDriftDrop(tracker) {
|
|
|
298
298
|
tracker.lastFire = tracker.calls;
|
|
299
299
|
tracker.entries = {};
|
|
300
300
|
}
|
|
301
|
-
/**
|
|
301
|
+
/**
|
|
302
|
+
* Note that a skill surface (a suggestion, an at-use line, or a SKILL.md read)
|
|
303
|
+
* just landed.
|
|
304
|
+
*/
|
|
302
305
|
export function noteDriftSurface(tracker) {
|
|
303
306
|
tracker.lastSurface = tracker.calls;
|
|
304
307
|
}
|
|
@@ -237,9 +237,10 @@ export declare function getSessionApplicability(ctx: ExtensionContext, options?:
|
|
|
237
237
|
* no family; most declare none, and an obligation that names no family is
|
|
238
238
|
* satisfied by the read alone.
|
|
239
239
|
*
|
|
240
|
-
* `suggested` and `
|
|
241
|
-
* this session (a delivered suggestion, a list_skills row
|
|
242
|
-
* "was it offered" half of adoption, which the
|
|
240
|
+
* `suggested`, `listed` and `informed` are the surfaces that offered the body
|
|
241
|
+
* in this session (a delivered suggestion, a list_skills row, a delivered
|
|
242
|
+
* at-use line); they carry the "was it offered" half of adoption, which the
|
|
243
|
+
* call facts cannot.
|
|
243
244
|
*/
|
|
244
245
|
export interface ObligationLegRecord {
|
|
245
246
|
kind: "obligation";
|
|
@@ -250,15 +251,18 @@ export interface ObligationLegRecord {
|
|
|
250
251
|
skill: string;
|
|
251
252
|
suggested: boolean;
|
|
252
253
|
listed: boolean;
|
|
254
|
+
/** An at-use inform was DELIVERED for this body in this session. */
|
|
255
|
+
informed: boolean;
|
|
253
256
|
read: boolean;
|
|
254
257
|
called: boolean;
|
|
255
258
|
applied: boolean;
|
|
256
259
|
}
|
|
257
|
-
/** A record's
|
|
260
|
+
/** A record's six legs, read back as one row per skill. */
|
|
258
261
|
export interface ObligationLegs {
|
|
259
262
|
skill: string;
|
|
260
263
|
suggested: boolean;
|
|
261
264
|
listed: boolean;
|
|
265
|
+
informed: boolean;
|
|
262
266
|
read: boolean;
|
|
263
267
|
called: boolean;
|
|
264
268
|
applied: boolean;
|
|
@@ -280,11 +284,11 @@ export declare function normalizeObligationRecord(raw: unknown): ObligationLegRe
|
|
|
280
284
|
*/
|
|
281
285
|
export declare function readObligationRecords(storePath?: string): ObligationLegRecord[];
|
|
282
286
|
/**
|
|
283
|
-
* Fold a session's obligation rows into one record: the
|
|
284
|
-
*
|
|
285
|
-
*
|
|
286
|
-
*
|
|
287
|
-
*
|
|
287
|
+
* Fold a session's obligation rows into one record: the legs OR across every
|
|
288
|
+
* row, so a row that saw one leg never erases a leg a later row did not have.
|
|
289
|
+
* `called`/`applied` are written once per skill, so the OR is exact rather
|
|
290
|
+
* than convenient. A torn or duplicated row folds; a malformed one is dropped
|
|
291
|
+
* at normalize, before this sees it.
|
|
288
292
|
*/
|
|
289
293
|
export declare function foldObligationRecords(records: ObligationLegRecord[]): SessionObligation[];
|
|
290
294
|
/**
|
|
@@ -371,6 +375,100 @@ export declare function computeObligationRate(sessions: SessionApplicability[],
|
|
|
371
375
|
export declare function getObligationRate(options?: {
|
|
372
376
|
storePath?: string;
|
|
373
377
|
}): ObligationRate | undefined;
|
|
378
|
+
/**
|
|
379
|
+
* The suggestion channel's pair conversion as published from session-file
|
|
380
|
+
* mining: 95 read-followed pairs out of 506 delivered ones, Wilson 15.6-22.4.
|
|
381
|
+
*
|
|
382
|
+
* It is a measurement constant, not a target: it stands in as the comparison
|
|
383
|
+
* arm only while the same store carries too few suggested pairs of its own to
|
|
384
|
+
* stand on its own (see INFORM_DECISION_MIN_PAIRS). A two-pair store arm that
|
|
385
|
+
* happens to have converted nothing is not a baseline; it is a sample. The
|
|
386
|
+
* moment the store holds the floor of suggested pairs, their own fold answers
|
|
387
|
+
* and this number is not read.
|
|
388
|
+
*/
|
|
389
|
+
export declare const CHANNEL_PUBLISHED_CONVERSION = 0.188;
|
|
390
|
+
/** Wilson 95% bounds for that published figure, as proportions. */
|
|
391
|
+
export declare const CHANNEL_PUBLISHED_INTERVAL: WilsonInterval;
|
|
392
|
+
/**
|
|
393
|
+
* Informs needed before the comparison decides anything. Below this the
|
|
394
|
+
* answer is "undecided": a verdict from a handful of pairs would be a verdict
|
|
395
|
+
* about the sample, and the report's decision rule says so in writing before
|
|
396
|
+
* the first inform lands. The same floor governs the comparison arm: a store
|
|
397
|
+
* carrying fewer suggested pairs than this is not a baseline to beat.
|
|
398
|
+
*/
|
|
399
|
+
export declare const INFORM_DECISION_MIN_PAIRS = 20;
|
|
400
|
+
/** A two-sided interval on a proportion, both ends in 0-1. */
|
|
401
|
+
export interface WilsonInterval {
|
|
402
|
+
lower: number;
|
|
403
|
+
upper: number;
|
|
404
|
+
}
|
|
405
|
+
/**
|
|
406
|
+
* Wilson score interval for k successes in n trials (95% by default). Chosen
|
|
407
|
+
* over the normal approximation because the inform population is small and a
|
|
408
|
+
* small-sample interval is the only one that can say "undecided" honestly.
|
|
409
|
+
* Returns zeros for n = 0. Pure.
|
|
410
|
+
*/
|
|
411
|
+
export declare function wilsonInterval(successes: number, total: number, z?: number): WilsonInterval;
|
|
412
|
+
/** One skill's at-use pairs: informs delivered, and how many a read followed. */
|
|
413
|
+
export interface InformSkillRow {
|
|
414
|
+
skill: string;
|
|
415
|
+
informs: number;
|
|
416
|
+
readFollowed: number;
|
|
417
|
+
}
|
|
418
|
+
/** Where the comparison arm's number came from. */
|
|
419
|
+
export type ChannelBaselineSource = "store" | "published";
|
|
420
|
+
/**
|
|
421
|
+
* The at-use line's numbers beside the suggestion channel's, same store.
|
|
422
|
+
*
|
|
423
|
+
* A pair is (session, skill). An inform pair carries `informed: true`; it
|
|
424
|
+
* converted when that session also carries the `read` leg for the same skill.
|
|
425
|
+
* The read leg is ordered by construction here: a read silences the inform, so
|
|
426
|
+
* a pair that has both legs can only have read after the line landed.
|
|
427
|
+
*/
|
|
428
|
+
export interface InformRate {
|
|
429
|
+
/** Inform pairs in the store. */
|
|
430
|
+
informs: number;
|
|
431
|
+
/** Of those, pairs whose session carries the read leg. */
|
|
432
|
+
readFollowed: number;
|
|
433
|
+
/** readFollowed / informs, 4 decimals; 0 when no inform. */
|
|
434
|
+
conversion: number;
|
|
435
|
+
/** Wilson 95% bounds on `conversion`. */
|
|
436
|
+
ci: WilsonInterval;
|
|
437
|
+
/** Per skill, in first-seen order (only skills with an inform). */
|
|
438
|
+
skills: InformSkillRow[];
|
|
439
|
+
/** The comparison arm: the same fold's suggested pairs. */
|
|
440
|
+
channel: {
|
|
441
|
+
pairs: number;
|
|
442
|
+
readFollowed: number;
|
|
443
|
+
conversion: number;
|
|
444
|
+
ci: WilsonInterval;
|
|
445
|
+
source: ChannelBaselineSource;
|
|
446
|
+
};
|
|
447
|
+
/** conversion - channel.conversion, in percentage points, 2 decimals. */
|
|
448
|
+
gapPoints: number;
|
|
449
|
+
/** False below INFORM_DECISION_MIN_PAIRS: no verdict is derivable. */
|
|
450
|
+
decidable: boolean;
|
|
451
|
+
/** undecided | beats | noise (see the report's pre-registered rule). */
|
|
452
|
+
verdict: "undecided" | "beats" | "noise";
|
|
453
|
+
}
|
|
454
|
+
/**
|
|
455
|
+
* Fold the obligation rows into the at-use rate and the channel arm beside it.
|
|
456
|
+
* Pure.
|
|
457
|
+
*
|
|
458
|
+
* The rule, applied literally: fewer than the floor is undecided; at the floor
|
|
459
|
+
* the inform beats the channel only when its point estimate is above the
|
|
460
|
+
* channel's AND its lower Wilson bound is above it too. Anything else at the
|
|
461
|
+
* floor is noise, which is the falsifier firing rather than a neutral result.
|
|
462
|
+
*/
|
|
463
|
+
export declare function computeInformRate(obligations: SessionObligation[]): InformRate;
|
|
464
|
+
/**
|
|
465
|
+
* The store-wide at-use rate, or undefined when the store carries no inform row
|
|
466
|
+
* at all. Undefined keeps every existing `skill_stats` payload byte-identical
|
|
467
|
+
* for a build or an install that never emitted one.
|
|
468
|
+
*/
|
|
469
|
+
export declare function getInformRate(options?: {
|
|
470
|
+
storePath?: string;
|
|
471
|
+
}): InformRate | undefined;
|
|
374
472
|
/** Adoption numbers for one profile in one month. */
|
|
375
473
|
export interface ProfileAdoption {
|
|
376
474
|
/** Sessions active in the month (records with a turn). */
|