pi-braid 0.43.28 → 0.43.29
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 +24 -0
- package/build-info.json +4 -4
- package/dist/extensions/enforcement/handlers/open-intents.d.ts +64 -0
- package/dist/extensions/enforcement/handlers/open-intents.js +183 -0
- package/dist/extensions/enforcement/handlers/register-session-start-discoverability.js +8 -8
- package/docs/LOCAL_DEV.md +1 -1
- package/package.json +1 -1
- package/src/extensions/enforcement/handlers/AGENTS.md +21 -20
- package/src/extensions/enforcement/handlers/open-intents.ts +223 -0
- package/src/extensions/enforcement/handlers/register-session-start-discoverability.ts +8 -9
package/CHANGELOG.md
CHANGED
|
@@ -96,6 +96,30 @@ record; the tag scheme above applies unchanged.
|
|
|
96
96
|
note that a clean disable releases it, because a refusal an operator cannot act on
|
|
97
97
|
is a support ticket.
|
|
98
98
|
|
|
99
|
+
## Core — 0.43.29 (2026-11-06: the journal pointer names the intent that is still open)
|
|
100
|
+
|
|
101
|
+
- **A line count cannot tell a pending install from forty closed outcomes.** The
|
|
102
|
+
session-start pointer was built from the number of journal lines, so a project
|
|
103
|
+
holding a handoff printed the same sentence as a project holding a finished
|
|
104
|
+
week. It now reads the journal, selects the entries whose `kind` is `intent`
|
|
105
|
+
and whose `status` is `open`, and names up to three of them with their age in
|
|
106
|
+
hours, `+N more open` beyond that, under a 480-character ceiling: the intent
|
|
107
|
+
whose `expires_at` has passed is printed as `EXPIRED` with the same age, and
|
|
108
|
+
the sentence asks for what ending it takes.
|
|
109
|
+
|
|
110
|
+
- **Nothing open means nothing new, and a broken line is not a crash.** With no
|
|
111
|
+
open intent the pointer is byte-identical to the sentence the old code
|
|
112
|
+
produced, which the fixture asserts in full rather than by substring. A line
|
|
113
|
+
that is not JSON, an entry without `kind`, and an unparseable `expires_at` are
|
|
114
|
+
skipped, so a hand-edited journal still yields the count.
|
|
115
|
+
|
|
116
|
+
- **Measured on a journal that already had handoffs waiting.** Against this
|
|
117
|
+
machine's own project journal the pointer printed three intents 72 hours old,
|
|
118
|
+
which is the class of thing the old sentence hid. Twelve fixtures cover the
|
|
119
|
+
named, expired, overflowing, closed-only and malformed cases; the planted
|
|
120
|
+
revert disables the selection and eight of them redden; the core chain reports
|
|
121
|
+
343 fixtures passed and placement reports 0 hits with 269 excluded.
|
|
122
|
+
|
|
99
123
|
## Core — 0.43.28 (2026-11-06: the queue is read from the registry, not remembered by the seat)
|
|
100
124
|
|
|
101
125
|
- **A registry that records what a worker does but not where it sits in a queue
|
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.29",
|
|
4
|
+
"sha": "25a90502b8016505c7e7af5be4b9cff9d1577e6c",
|
|
5
|
+
"shaShort": "25a90502",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-11-
|
|
8
|
+
"packedAt": "2026-11-06T12:50:48.597Z"
|
|
9
9
|
}
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What the session-start journal pointer says about work still open.
|
|
3
|
+
*
|
|
4
|
+
* The pointer used to be built from a line count alone, so a journal holding a
|
|
5
|
+
* pending install and a journal holding forty closed outcomes printed the same
|
|
6
|
+
* sentence: the seat beginning the day could not tell that something was
|
|
7
|
+
* waiting for it. Naming the open intents costs a sentence in the first prompt
|
|
8
|
+
* of every session, so the whole text keeps a fixed ceiling and gives up detail
|
|
9
|
+
* in a fixed order instead of growing with the journal.
|
|
10
|
+
*
|
|
11
|
+
* Reading is line-level: an entry counts when its `kind` is `intent` and its
|
|
12
|
+
* `status` is `open`. The digest printer derives a subject's status across
|
|
13
|
+
* supersession chains and stays the authority on the full program, so a name
|
|
14
|
+
* here can be an intent a later line retired; against this project's journal
|
|
15
|
+
* when the pointer was written, five of the seven open-status intents were
|
|
16
|
+
* already retired that way. The trade is deliberate and the digest is where a
|
|
17
|
+
* seat confirms what is live: naming work already closed costs a line of
|
|
18
|
+
* attention, while hiding an install nobody was told about is the failure this
|
|
19
|
+
* pointer exists to repair. Honoring the journal's own `supersedes` edges is
|
|
20
|
+
* what would narrow it, and that is one line of selection, not one of wording.
|
|
21
|
+
*/
|
|
22
|
+
/** Ceiling for the whole pointer text. A line delivered into every session is
|
|
23
|
+
* paid for by every turn that follows it, so the cost is per session, not per
|
|
24
|
+
* journal entry. */
|
|
25
|
+
export declare const JOURNAL_PRIOR_BUDGET = 480;
|
|
26
|
+
/** What the pointer needs from the handler: the line count it always printed,
|
|
27
|
+
* and the path it names. */
|
|
28
|
+
export interface JournalPointerFacts {
|
|
29
|
+
count: number;
|
|
30
|
+
journalFile: string;
|
|
31
|
+
}
|
|
32
|
+
/** One intent whose `status` says `open`. */
|
|
33
|
+
export interface OpenIntent {
|
|
34
|
+
subject: string;
|
|
35
|
+
/** Whole hours since the entry's own `at`; null when that stamp is unusable,
|
|
36
|
+
* which is reported as no age rather than as a guess. */
|
|
37
|
+
ageHours: number | null;
|
|
38
|
+
/** The entry's `expires_at`, kept only when it parses. A broken stamp is a
|
|
39
|
+
* missing detail, never a reason to hide the intent behind it. */
|
|
40
|
+
expiresAt: string | null;
|
|
41
|
+
expired: boolean;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* The journal lines that name open work.
|
|
45
|
+
*
|
|
46
|
+
* Anything unreadable is skipped: a line that is not JSON, a value that is not
|
|
47
|
+
* an object, an entry without a usable `subject`, and an `expires_at` that does
|
|
48
|
+
* not parse (the stamp is dropped, the intent is not). A journal is written by
|
|
49
|
+
* a different process and edited by hand, so a reader that throws on the first
|
|
50
|
+
* malformed line would take the whole session-start bundle down with it.
|
|
51
|
+
*/
|
|
52
|
+
export declare function selectOpenIntents(journalText: string, now: Date): OpenIntent[];
|
|
53
|
+
/**
|
|
54
|
+
* The journal pointer, complete: the sentence this step has always printed,
|
|
55
|
+
* extended with what is open.
|
|
56
|
+
*
|
|
57
|
+
* With nothing open the result is the original text byte for byte. With work
|
|
58
|
+
* open the count-and-path sentence is kept and the digest printer is restated
|
|
59
|
+
* in its short form: with a 91-character journal path the long form plus one
|
|
60
|
+
* expired intent is 527 characters against the 480 ceiling, and the sentence
|
|
61
|
+
* that motivates reading the journal is the one with room to yield.
|
|
62
|
+
*/
|
|
63
|
+
export declare function journalPriorText(facts: JournalPointerFacts, journalText: string, now: Date): string;
|
|
64
|
+
//# sourceMappingURL=open-intents.d.ts.map
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What the session-start journal pointer says about work still open.
|
|
3
|
+
*
|
|
4
|
+
* The pointer used to be built from a line count alone, so a journal holding a
|
|
5
|
+
* pending install and a journal holding forty closed outcomes printed the same
|
|
6
|
+
* sentence: the seat beginning the day could not tell that something was
|
|
7
|
+
* waiting for it. Naming the open intents costs a sentence in the first prompt
|
|
8
|
+
* of every session, so the whole text keeps a fixed ceiling and gives up detail
|
|
9
|
+
* in a fixed order instead of growing with the journal.
|
|
10
|
+
*
|
|
11
|
+
* Reading is line-level: an entry counts when its `kind` is `intent` and its
|
|
12
|
+
* `status` is `open`. The digest printer derives a subject's status across
|
|
13
|
+
* supersession chains and stays the authority on the full program, so a name
|
|
14
|
+
* here can be an intent a later line retired; against this project's journal
|
|
15
|
+
* when the pointer was written, five of the seven open-status intents were
|
|
16
|
+
* already retired that way. The trade is deliberate and the digest is where a
|
|
17
|
+
* seat confirms what is live: naming work already closed costs a line of
|
|
18
|
+
* attention, while hiding an install nobody was told about is the failure this
|
|
19
|
+
* pointer exists to repair. Honoring the journal's own `supersedes` edges is
|
|
20
|
+
* what would narrow it, and that is one line of selection, not one of wording.
|
|
21
|
+
*/
|
|
22
|
+
/** Ceiling for the whole pointer text. A line delivered into every session is
|
|
23
|
+
* paid for by every turn that follows it, so the cost is per session, not per
|
|
24
|
+
* journal entry. */
|
|
25
|
+
export const JOURNAL_PRIOR_BUDGET = 480;
|
|
26
|
+
/** Named intents in the text; the rest are counted. Three subjects are about as
|
|
27
|
+
* many as a reader can carry into the work they were about to start. */
|
|
28
|
+
const NAMED_INTENT_LIMIT = 3;
|
|
29
|
+
/** Longest subject rendered. The journal writer admits slugs up to 64
|
|
30
|
+
* characters, so one hostile line would otherwise spend the budget alone. */
|
|
31
|
+
const SUBJECT_LIMIT = 32;
|
|
32
|
+
const HOUR_MS = 3_600_000;
|
|
33
|
+
const DIGEST_COMMAND = "packages/core/scripts/check-journal.mjs --digest";
|
|
34
|
+
/** The closing sentence of the pointer when nothing is open. Shown to every
|
|
35
|
+
* session, so it keeps its exact words. */
|
|
36
|
+
const DIGEST_POINTER = `Read the open program before acting (digest printer: ${DIGEST_COMMAND}), so a decision gets superseded, not rediscovered.`;
|
|
37
|
+
/** The same printer, said shorter: naming what is open already answers the
|
|
38
|
+
* question the long form motivates, and the room it frees is what pays for
|
|
39
|
+
* the names. */
|
|
40
|
+
const DIGEST_POINTER_SHORT = `Full program: ${DIGEST_COMMAND}.`;
|
|
41
|
+
const CLOSE_SINGLE = "Run the install it names, or close it with the reason it will not run.";
|
|
42
|
+
const CLOSE_PLURAL = "Run the install each names, or close it with the reason it will not run.";
|
|
43
|
+
/**
|
|
44
|
+
* The journal lines that name open work.
|
|
45
|
+
*
|
|
46
|
+
* Anything unreadable is skipped: a line that is not JSON, a value that is not
|
|
47
|
+
* an object, an entry without a usable `subject`, and an `expires_at` that does
|
|
48
|
+
* not parse (the stamp is dropped, the intent is not). A journal is written by
|
|
49
|
+
* a different process and edited by hand, so a reader that throws on the first
|
|
50
|
+
* malformed line would take the whole session-start bundle down with it.
|
|
51
|
+
*/
|
|
52
|
+
export function selectOpenIntents(journalText, now) {
|
|
53
|
+
const open = [];
|
|
54
|
+
for (const line of journalText.split("\n")) {
|
|
55
|
+
if (!line.trim())
|
|
56
|
+
continue;
|
|
57
|
+
const entry = parseEntry(line);
|
|
58
|
+
if (!entry)
|
|
59
|
+
continue;
|
|
60
|
+
if (entry.kind !== "intent" || entry.status !== "open")
|
|
61
|
+
continue;
|
|
62
|
+
const subject = typeof entry.subject === "string" ? entry.subject.trim() : "";
|
|
63
|
+
if (!subject)
|
|
64
|
+
continue;
|
|
65
|
+
const writtenAt = typeof entry.at === "string" ? Date.parse(entry.at) : Number.NaN;
|
|
66
|
+
const expiresAt = typeof entry.expires_at === "string" ? Date.parse(entry.expires_at) : Number.NaN;
|
|
67
|
+
open.push({
|
|
68
|
+
subject,
|
|
69
|
+
ageHours: Number.isNaN(writtenAt)
|
|
70
|
+
? null
|
|
71
|
+
: Math.max(0, Math.floor((now.getTime() - writtenAt) / HOUR_MS)),
|
|
72
|
+
expiresAt: Number.isNaN(expiresAt) ? null : entry.expires_at,
|
|
73
|
+
expired: !Number.isNaN(expiresAt) && expiresAt < now.getTime(),
|
|
74
|
+
});
|
|
75
|
+
}
|
|
76
|
+
// The intent whose window already closed is the one a reader has to act on,
|
|
77
|
+
// so it is named before the rest; journal order stands inside each group.
|
|
78
|
+
return [...open.filter((intent) => intent.expired), ...open.filter((intent) => !intent.expired)];
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* The journal pointer, complete: the sentence this step has always printed,
|
|
82
|
+
* extended with what is open.
|
|
83
|
+
*
|
|
84
|
+
* With nothing open the result is the original text byte for byte. With work
|
|
85
|
+
* open the count-and-path sentence is kept and the digest printer is restated
|
|
86
|
+
* in its short form: with a 91-character journal path the long form plus one
|
|
87
|
+
* expired intent is 527 characters against the 480 ceiling, and the sentence
|
|
88
|
+
* that motivates reading the journal is the one with room to yield.
|
|
89
|
+
*/
|
|
90
|
+
export function journalPriorText(facts, journalText, now) {
|
|
91
|
+
const intro = journalIntro(facts);
|
|
92
|
+
const open = selectOpenIntents(journalText, now);
|
|
93
|
+
if (open.length === 0)
|
|
94
|
+
return `${intro} ${DIGEST_POINTER}`;
|
|
95
|
+
// Detail is given up in order of what a reader needs it for: the name of a
|
|
96
|
+
// waiting install, then the moment its window closes, then the standing
|
|
97
|
+
// pointer to the full program, then the count alone. Dropping the names to
|
|
98
|
+
// keep the pointer would save the cheaper fact and hide the dearer one.
|
|
99
|
+
const ladder = [
|
|
100
|
+
`${intro} ${describeOpen(open, "stamped")} ${DIGEST_POINTER_SHORT}`,
|
|
101
|
+
`${intro} ${describeOpen(open, "plain")} ${DIGEST_POINTER_SHORT}`,
|
|
102
|
+
`${intro} ${describeOpen(open, "stamped")}`,
|
|
103
|
+
`${intro} ${describeOpen(open, "plain")}`,
|
|
104
|
+
`${intro} ${countedSentence(open)} ${DIGEST_POINTER_SHORT}`,
|
|
105
|
+
`${intro} ${countedSentence(open)}`,
|
|
106
|
+
`${intro} ${open.length} open intent${open.length === 1 ? "" : "s"}.`,
|
|
107
|
+
];
|
|
108
|
+
// Richest description that fits. The last rung is printed rather than
|
|
109
|
+
// dropped when nothing fits: a journal path long enough to spend the ceiling
|
|
110
|
+
// alone is a reason to say less, never a reason to leave a pending install
|
|
111
|
+
// unmentioned.
|
|
112
|
+
return ladder.find((text) => text.length < JOURNAL_PRIOR_BUDGET) ?? ladder[ladder.length - 1];
|
|
113
|
+
}
|
|
114
|
+
function journalIntro({ count, journalFile }) {
|
|
115
|
+
return (`The project journal holds ${count} entr${count === 1 ? "y" : "ies"} at ${journalFile} -- ` +
|
|
116
|
+
`what earlier seats decided and why, readable without their sessions.`);
|
|
117
|
+
}
|
|
118
|
+
function describeOpen(open, detail) {
|
|
119
|
+
if (detail === "counted")
|
|
120
|
+
return countedSentence(open);
|
|
121
|
+
const withStamp = detail === "stamped";
|
|
122
|
+
return open.length === 1 ? singleSentence(open[0], withStamp) : listSentence(open, withStamp);
|
|
123
|
+
}
|
|
124
|
+
/** One open intent reads as a sentence: a list of one is a fragment, and the
|
|
125
|
+
* instruction that follows it addresses a single install. */
|
|
126
|
+
function singleSentence(intent, withStamp) {
|
|
127
|
+
const opening = intent.expired
|
|
128
|
+
? "One intent is still open and EXPIRED"
|
|
129
|
+
: "One intent is still open";
|
|
130
|
+
return `${opening}: ${named(intent)}${roundStamp(intent, withStamp)}. ${CLOSE_SINGLE}`;
|
|
131
|
+
}
|
|
132
|
+
function listSentence(open, withStamp) {
|
|
133
|
+
const items = open.slice(0, NAMED_INTENT_LIMIT).map((intent) => listItem(intent, withStamp));
|
|
134
|
+
const rest = open.length - Math.min(open.length, NAMED_INTENT_LIMIT);
|
|
135
|
+
const more = rest > 0 ? `; +${rest} more open` : "";
|
|
136
|
+
return `Open intents: ${items.join("; ")}${more}. ${CLOSE_PLURAL}`;
|
|
137
|
+
}
|
|
138
|
+
/** The expired marker stays in the lean form: it is the fact a reader acts on,
|
|
139
|
+
* while the exact moment is one the digest can restate. */
|
|
140
|
+
function listItem(intent, withStamp) {
|
|
141
|
+
const expired = intent.expired ? ", EXPIRED" : "";
|
|
142
|
+
if (!withStamp || intent.expiresAt === null)
|
|
143
|
+
return `${named(intent)}${expired}`;
|
|
144
|
+
return intent.expired
|
|
145
|
+
? `${named(intent)}, EXPIRED (expires_at ${intent.expiresAt})`
|
|
146
|
+
: `${named(intent)}, expires ${intent.expiresAt}`;
|
|
147
|
+
}
|
|
148
|
+
/** In the single sentence the opening clause already carries the EXPIRED word,
|
|
149
|
+
* so this adds the moment alone. */
|
|
150
|
+
function roundStamp(intent, withStamp) {
|
|
151
|
+
if (!withStamp || intent.expiresAt === null)
|
|
152
|
+
return "";
|
|
153
|
+
return intent.expired ? ` (expires_at ${intent.expiresAt})` : ` (expires ${intent.expiresAt})`;
|
|
154
|
+
}
|
|
155
|
+
function countedSentence(open) {
|
|
156
|
+
const expired = open.filter((intent) => intent.expired).length;
|
|
157
|
+
const ages = open
|
|
158
|
+
.map((intent) => intent.ageHours)
|
|
159
|
+
.filter((hours) => hours !== null);
|
|
160
|
+
const oldest = ages.length > 0 ? `, oldest ${Math.max(...ages)}h old` : "";
|
|
161
|
+
const lapsed = expired > 0 ? `, ${expired} EXPIRED` : "";
|
|
162
|
+
const count = `${open.length} open intent${open.length === 1 ? "" : "s"} in this journal`;
|
|
163
|
+
return `${count}${oldest}${lapsed}. ${open.length === 1 ? CLOSE_SINGLE : CLOSE_PLURAL}`;
|
|
164
|
+
}
|
|
165
|
+
function named(intent) {
|
|
166
|
+
const age = intent.ageHours === null ? "" : ` ${intent.ageHours}h old`;
|
|
167
|
+
return `"${clipSubject(intent.subject)}"${age}`;
|
|
168
|
+
}
|
|
169
|
+
function clipSubject(subject) {
|
|
170
|
+
return subject.length <= SUBJECT_LIMIT ? subject : `${subject.slice(0, SUBJECT_LIMIT - 1)}…`;
|
|
171
|
+
}
|
|
172
|
+
function parseEntry(line) {
|
|
173
|
+
try {
|
|
174
|
+
const value = JSON.parse(line);
|
|
175
|
+
if (value === null || typeof value !== "object" || Array.isArray(value))
|
|
176
|
+
return null;
|
|
177
|
+
return value;
|
|
178
|
+
}
|
|
179
|
+
catch {
|
|
180
|
+
return null;
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
//# sourceMappingURL=open-intents.js.map
|
|
@@ -36,6 +36,7 @@ import { isProjectSignalShown, markProjectSignalShown, reconstructShownSignalsFr
|
|
|
36
36
|
import { episodesFilePath, semanticMemoryFilePath, AGENT, braidDir, journalFilePath, tagsSlugFromCwd, } from "../../../lib/config/braid-paths.js";
|
|
37
37
|
import { projectSlugFromCwd } from "../../memory/scratchpad/persistence.js";
|
|
38
38
|
import { readResumeScratchpadState } from "../resume-state.js";
|
|
39
|
+
import { journalPriorText } from "./open-intents.js";
|
|
39
40
|
const log = createLogger("enforcement:session-start-discoverability");
|
|
40
41
|
/**
|
|
41
42
|
* Register the SESSION_START discoverability handler.
|
|
@@ -201,21 +202,20 @@ export function registerSessionStartDiscoverability(pi) {
|
|
|
201
202
|
// 7. The owner-input journal. The path comes from the constant the
|
|
202
203
|
// writer appends through, never a hand-built shape: two spellings for
|
|
203
204
|
// one file is how the scratchpad pointer armed itself against a file
|
|
204
|
-
// nothing writes (see step 1).
|
|
205
|
+
// nothing writes (see step 1). The text is composed in `open-intents`,
|
|
206
|
+
// which also names the intents whose status says open: a journal holding
|
|
207
|
+
// a pending install printed the same count sentence as one holding forty
|
|
208
|
+
// closed outcomes, so the seat could not see that work was waiting.
|
|
205
209
|
try {
|
|
206
210
|
const slug = projectSlugFromCwd(cwd);
|
|
207
211
|
const journalFile = journalFilePath(slug);
|
|
208
212
|
if (existsSync(journalFile)) {
|
|
209
|
-
const
|
|
210
|
-
|
|
211
|
-
.filter((line) => line.trim()).length;
|
|
213
|
+
const journalText = readFileSync(journalFile, "utf-8");
|
|
214
|
+
const count = journalText.split("\n").filter((line) => line.trim()).length;
|
|
212
215
|
if (count > 0) {
|
|
213
216
|
signals.push({
|
|
214
217
|
type: "journal_prior",
|
|
215
|
-
text:
|
|
216
|
-
`what earlier seats decided and why, readable without their sessions. ` +
|
|
217
|
-
`Read the open program before acting (digest printer: packages/core/scripts/check-journal.mjs --digest), ` +
|
|
218
|
-
`so a decision gets superseded, not rediscovered.`,
|
|
218
|
+
text: journalPriorText({ count, journalFile }, journalText, new Date()),
|
|
219
219
|
});
|
|
220
220
|
}
|
|
221
221
|
}
|
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 - 109 of the core suite's 343 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/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.43.
|
|
3
|
+
"version": "0.43.29",
|
|
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",
|
|
@@ -22,20 +22,20 @@ in a pipeline." It's the broadest use of the term in the codebase.
|
|
|
22
22
|
These are the entry points for enforcement. They register with pi core
|
|
23
23
|
and delegate to the actual enforcement logic.
|
|
24
24
|
|
|
25
|
-
| File | Event
|
|
26
|
-
| ------------------------------------------- |
|
|
27
|
-
| `register-session-start.ts` | `session_start`
|
|
28
|
-
| `register-session-start-discoverability.ts` | `session_start` (Background phase, via `registerSessionStartHandler`) - surfaces disk-backed prior state (scratchpad, memory, sessions, resume file, tags) before the first turn. Per-signal dedup with per-project disk persistence.
|
|
29
|
-
| `register-session-compact.ts` | `session_compact`
|
|
30
|
-
| `register-session-shutdown.ts` | `session_shutdown`
|
|
31
|
-
| `register-session-shutdown-resumption.ts` | (read by discoverability handler) - resume file creation on shutdown.
|
|
32
|
-
| `register-input-handler.ts` | `input`
|
|
33
|
-
| `register-message-end.ts` | `message_end`
|
|
34
|
-
| `register-tool-call.ts` | `tool_call`
|
|
35
|
-
| `register-tool-result.ts` | `tool_execution_end`
|
|
36
|
-
| `register-agent-end-api-error.ts` | `agent_end` (classifies a terminal assistant API error into guidance)
|
|
37
|
-
| `register-post-cycle-hygiene.ts` | `turn_end` (priority 1 - auto-tag + inspect + advise on text-only yield after work)
|
|
38
|
-
| `register-adherence-meter.ts` | `session_start` (Background - counts `enforcement_violation` events per session), `turn_end` (priority 40 - escalates a rule repeating past K to the owner, bounded), `session_shutdown` (writes the owner report). Owner-facing only: never sends a tracked message and never registers a tool.
|
|
25
|
+
| File | Event |
|
|
26
|
+
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
27
|
+
| `register-session-start.ts` | `session_start` |
|
|
28
|
+
| `register-session-start-discoverability.ts` | `session_start` (Background phase, via `registerSessionStartHandler`) - surfaces disk-backed prior state (scratchpad, memory, sessions, resume file, tags, journal) before the first turn. Per-signal dedup with per-project disk persistence; the journal pointer is exempt and carries what is open. |
|
|
29
|
+
| `register-session-compact.ts` | `session_compact` |
|
|
30
|
+
| `register-session-shutdown.ts` | `session_shutdown` |
|
|
31
|
+
| `register-session-shutdown-resumption.ts` | (read by discoverability handler) - resume file creation on shutdown. |
|
|
32
|
+
| `register-input-handler.ts` | `input` |
|
|
33
|
+
| `register-message-end.ts` | `message_end` |
|
|
34
|
+
| `register-tool-call.ts` | `tool_call` |
|
|
35
|
+
| `register-tool-result.ts` | `tool_execution_end` |
|
|
36
|
+
| `register-agent-end-api-error.ts` | `agent_end` (classifies a terminal assistant API error into guidance) |
|
|
37
|
+
| `register-post-cycle-hygiene.ts` | `turn_end` (priority 1 - auto-tag + inspect + advise on text-only yield after work) |
|
|
38
|
+
| `register-adherence-meter.ts` | `session_start` (Background - counts `enforcement_violation` events per session), `turn_end` (priority 40 - escalates a rule repeating past K to the owner, bounded), `session_shutdown` (writes the owner report). Owner-facing only: never sends a tracked message and never registers a tool. |
|
|
39
39
|
|
|
40
40
|
### Orchestrators (not `register-*`, but invoked at turn end)
|
|
41
41
|
|
|
@@ -48,12 +48,13 @@ and delegate to the actual enforcement logic.
|
|
|
48
48
|
|
|
49
49
|
### Other utilities
|
|
50
50
|
|
|
51
|
-
| File | Purpose
|
|
52
|
-
| ------------------ |
|
|
53
|
-
| `tool-tracker.ts` | Per-tool-call tracking. 137L.
|
|
54
|
-
| `orphan-chains.ts` | Detects orphan tool call chains. 59L.
|
|
55
|
-
| `blocking.ts` | Tool call blocking logic. 79L.
|
|
56
|
-
| `probe-handler.ts` | Lightweight probe for LLM calls. 158L.
|
|
51
|
+
| File | Purpose |
|
|
52
|
+
| ------------------ | ------------------------------------------------------------------------------------------------------------------- |
|
|
53
|
+
| `tool-tracker.ts` | Per-tool-call tracking. 137L. |
|
|
54
|
+
| `orphan-chains.ts` | Detects orphan tool call chains. 59L. |
|
|
55
|
+
| `blocking.ts` | Tool call blocking logic. 79L. |
|
|
56
|
+
| `probe-handler.ts` | Lightweight probe for LLM calls. 158L. |
|
|
57
|
+
| `open-intents.ts` | Composes the session-start journal pointer and names the intents whose status is open, under a fixed ceiling. 215L. |
|
|
57
58
|
|
|
58
59
|
### Analysis pipeline
|
|
59
60
|
|
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What the session-start journal pointer says about work still open.
|
|
3
|
+
*
|
|
4
|
+
* The pointer used to be built from a line count alone, so a journal holding a
|
|
5
|
+
* pending install and a journal holding forty closed outcomes printed the same
|
|
6
|
+
* sentence: the seat beginning the day could not tell that something was
|
|
7
|
+
* waiting for it. Naming the open intents costs a sentence in the first prompt
|
|
8
|
+
* of every session, so the whole text keeps a fixed ceiling and gives up detail
|
|
9
|
+
* in a fixed order instead of growing with the journal.
|
|
10
|
+
*
|
|
11
|
+
* Reading is line-level: an entry counts when its `kind` is `intent` and its
|
|
12
|
+
* `status` is `open`. The digest printer derives a subject's status across
|
|
13
|
+
* supersession chains and stays the authority on the full program, so a name
|
|
14
|
+
* here can be an intent a later line retired; against this project's journal
|
|
15
|
+
* when the pointer was written, five of the seven open-status intents were
|
|
16
|
+
* already retired that way. The trade is deliberate and the digest is where a
|
|
17
|
+
* seat confirms what is live: naming work already closed costs a line of
|
|
18
|
+
* attention, while hiding an install nobody was told about is the failure this
|
|
19
|
+
* pointer exists to repair. Honoring the journal's own `supersedes` edges is
|
|
20
|
+
* what would narrow it, and that is one line of selection, not one of wording.
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
/** Ceiling for the whole pointer text. A line delivered into every session is
|
|
24
|
+
* paid for by every turn that follows it, so the cost is per session, not per
|
|
25
|
+
* journal entry. */
|
|
26
|
+
export const JOURNAL_PRIOR_BUDGET = 480;
|
|
27
|
+
|
|
28
|
+
/** Named intents in the text; the rest are counted. Three subjects are about as
|
|
29
|
+
* many as a reader can carry into the work they were about to start. */
|
|
30
|
+
const NAMED_INTENT_LIMIT = 3;
|
|
31
|
+
|
|
32
|
+
/** Longest subject rendered. The journal writer admits slugs up to 64
|
|
33
|
+
* characters, so one hostile line would otherwise spend the budget alone. */
|
|
34
|
+
const SUBJECT_LIMIT = 32;
|
|
35
|
+
|
|
36
|
+
const HOUR_MS = 3_600_000;
|
|
37
|
+
|
|
38
|
+
const DIGEST_COMMAND = "packages/core/scripts/check-journal.mjs --digest";
|
|
39
|
+
|
|
40
|
+
/** The closing sentence of the pointer when nothing is open. Shown to every
|
|
41
|
+
* session, so it keeps its exact words. */
|
|
42
|
+
const DIGEST_POINTER = `Read the open program before acting (digest printer: ${DIGEST_COMMAND}), so a decision gets superseded, not rediscovered.`;
|
|
43
|
+
|
|
44
|
+
/** The same printer, said shorter: naming what is open already answers the
|
|
45
|
+
* question the long form motivates, and the room it frees is what pays for
|
|
46
|
+
* the names. */
|
|
47
|
+
const DIGEST_POINTER_SHORT = `Full program: ${DIGEST_COMMAND}.`;
|
|
48
|
+
|
|
49
|
+
const CLOSE_SINGLE = "Run the install it names, or close it with the reason it will not run.";
|
|
50
|
+
const CLOSE_PLURAL = "Run the install each names, or close it with the reason it will not run.";
|
|
51
|
+
|
|
52
|
+
/** What the pointer needs from the handler: the line count it always printed,
|
|
53
|
+
* and the path it names. */
|
|
54
|
+
export interface JournalPointerFacts {
|
|
55
|
+
count: number;
|
|
56
|
+
journalFile: string;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** One intent whose `status` says `open`. */
|
|
60
|
+
export interface OpenIntent {
|
|
61
|
+
subject: string;
|
|
62
|
+
/** Whole hours since the entry's own `at`; null when that stamp is unusable,
|
|
63
|
+
* which is reported as no age rather than as a guess. */
|
|
64
|
+
ageHours: number | null;
|
|
65
|
+
/** The entry's `expires_at`, kept only when it parses. A broken stamp is a
|
|
66
|
+
* missing detail, never a reason to hide the intent behind it. */
|
|
67
|
+
expiresAt: string | null;
|
|
68
|
+
expired: boolean;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* The journal lines that name open work.
|
|
73
|
+
*
|
|
74
|
+
* Anything unreadable is skipped: a line that is not JSON, a value that is not
|
|
75
|
+
* an object, an entry without a usable `subject`, and an `expires_at` that does
|
|
76
|
+
* not parse (the stamp is dropped, the intent is not). A journal is written by
|
|
77
|
+
* a different process and edited by hand, so a reader that throws on the first
|
|
78
|
+
* malformed line would take the whole session-start bundle down with it.
|
|
79
|
+
*/
|
|
80
|
+
export function selectOpenIntents(journalText: string, now: Date): OpenIntent[] {
|
|
81
|
+
const open: OpenIntent[] = [];
|
|
82
|
+
for (const line of journalText.split("\n")) {
|
|
83
|
+
if (!line.trim()) continue;
|
|
84
|
+
const entry = parseEntry(line);
|
|
85
|
+
if (!entry) continue;
|
|
86
|
+
if (entry.kind !== "intent" || entry.status !== "open") continue;
|
|
87
|
+
const subject = typeof entry.subject === "string" ? entry.subject.trim() : "";
|
|
88
|
+
if (!subject) continue;
|
|
89
|
+
|
|
90
|
+
const writtenAt = typeof entry.at === "string" ? Date.parse(entry.at) : Number.NaN;
|
|
91
|
+
const expiresAt =
|
|
92
|
+
typeof entry.expires_at === "string" ? Date.parse(entry.expires_at) : Number.NaN;
|
|
93
|
+
|
|
94
|
+
open.push({
|
|
95
|
+
subject,
|
|
96
|
+
ageHours: Number.isNaN(writtenAt)
|
|
97
|
+
? null
|
|
98
|
+
: Math.max(0, Math.floor((now.getTime() - writtenAt) / HOUR_MS)),
|
|
99
|
+
expiresAt: Number.isNaN(expiresAt) ? null : (entry.expires_at as string),
|
|
100
|
+
expired: !Number.isNaN(expiresAt) && expiresAt < now.getTime(),
|
|
101
|
+
});
|
|
102
|
+
}
|
|
103
|
+
// The intent whose window already closed is the one a reader has to act on,
|
|
104
|
+
// so it is named before the rest; journal order stands inside each group.
|
|
105
|
+
return [...open.filter((intent) => intent.expired), ...open.filter((intent) => !intent.expired)];
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* The journal pointer, complete: the sentence this step has always printed,
|
|
110
|
+
* extended with what is open.
|
|
111
|
+
*
|
|
112
|
+
* With nothing open the result is the original text byte for byte. With work
|
|
113
|
+
* open the count-and-path sentence is kept and the digest printer is restated
|
|
114
|
+
* in its short form: with a 91-character journal path the long form plus one
|
|
115
|
+
* expired intent is 527 characters against the 480 ceiling, and the sentence
|
|
116
|
+
* that motivates reading the journal is the one with room to yield.
|
|
117
|
+
*/
|
|
118
|
+
export function journalPriorText(
|
|
119
|
+
facts: JournalPointerFacts,
|
|
120
|
+
journalText: string,
|
|
121
|
+
now: Date,
|
|
122
|
+
): string {
|
|
123
|
+
const intro = journalIntro(facts);
|
|
124
|
+
const open = selectOpenIntents(journalText, now);
|
|
125
|
+
if (open.length === 0) return `${intro} ${DIGEST_POINTER}`;
|
|
126
|
+
|
|
127
|
+
// Detail is given up in order of what a reader needs it for: the name of a
|
|
128
|
+
// waiting install, then the moment its window closes, then the standing
|
|
129
|
+
// pointer to the full program, then the count alone. Dropping the names to
|
|
130
|
+
// keep the pointer would save the cheaper fact and hide the dearer one.
|
|
131
|
+
const ladder = [
|
|
132
|
+
`${intro} ${describeOpen(open, "stamped")} ${DIGEST_POINTER_SHORT}`,
|
|
133
|
+
`${intro} ${describeOpen(open, "plain")} ${DIGEST_POINTER_SHORT}`,
|
|
134
|
+
`${intro} ${describeOpen(open, "stamped")}`,
|
|
135
|
+
`${intro} ${describeOpen(open, "plain")}`,
|
|
136
|
+
`${intro} ${countedSentence(open)} ${DIGEST_POINTER_SHORT}`,
|
|
137
|
+
`${intro} ${countedSentence(open)}`,
|
|
138
|
+
`${intro} ${open.length} open intent${open.length === 1 ? "" : "s"}.`,
|
|
139
|
+
];
|
|
140
|
+
// Richest description that fits. The last rung is printed rather than
|
|
141
|
+
// dropped when nothing fits: a journal path long enough to spend the ceiling
|
|
142
|
+
// alone is a reason to say less, never a reason to leave a pending install
|
|
143
|
+
// unmentioned.
|
|
144
|
+
return ladder.find((text) => text.length < JOURNAL_PRIOR_BUDGET) ?? ladder[ladder.length - 1];
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
function journalIntro({ count, journalFile }: JournalPointerFacts): string {
|
|
148
|
+
return (
|
|
149
|
+
`The project journal holds ${count} entr${count === 1 ? "y" : "ies"} at ${journalFile} -- ` +
|
|
150
|
+
`what earlier seats decided and why, readable without their sessions.`
|
|
151
|
+
);
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
type Detail = "stamped" | "plain" | "counted";
|
|
155
|
+
|
|
156
|
+
function describeOpen(open: OpenIntent[], detail: Detail): string {
|
|
157
|
+
if (detail === "counted") return countedSentence(open);
|
|
158
|
+
const withStamp = detail === "stamped";
|
|
159
|
+
return open.length === 1 ? singleSentence(open[0], withStamp) : listSentence(open, withStamp);
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/** One open intent reads as a sentence: a list of one is a fragment, and the
|
|
163
|
+
* instruction that follows it addresses a single install. */
|
|
164
|
+
function singleSentence(intent: OpenIntent, withStamp: boolean): string {
|
|
165
|
+
const opening = intent.expired
|
|
166
|
+
? "One intent is still open and EXPIRED"
|
|
167
|
+
: "One intent is still open";
|
|
168
|
+
return `${opening}: ${named(intent)}${roundStamp(intent, withStamp)}. ${CLOSE_SINGLE}`;
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
function listSentence(open: OpenIntent[], withStamp: boolean): string {
|
|
172
|
+
const items = open.slice(0, NAMED_INTENT_LIMIT).map((intent) => listItem(intent, withStamp));
|
|
173
|
+
const rest = open.length - Math.min(open.length, NAMED_INTENT_LIMIT);
|
|
174
|
+
const more = rest > 0 ? `; +${rest} more open` : "";
|
|
175
|
+
return `Open intents: ${items.join("; ")}${more}. ${CLOSE_PLURAL}`;
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
/** The expired marker stays in the lean form: it is the fact a reader acts on,
|
|
179
|
+
* while the exact moment is one the digest can restate. */
|
|
180
|
+
function listItem(intent: OpenIntent, withStamp: boolean): string {
|
|
181
|
+
const expired = intent.expired ? ", EXPIRED" : "";
|
|
182
|
+
if (!withStamp || intent.expiresAt === null) return `${named(intent)}${expired}`;
|
|
183
|
+
return intent.expired
|
|
184
|
+
? `${named(intent)}, EXPIRED (expires_at ${intent.expiresAt})`
|
|
185
|
+
: `${named(intent)}, expires ${intent.expiresAt}`;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/** In the single sentence the opening clause already carries the EXPIRED word,
|
|
189
|
+
* so this adds the moment alone. */
|
|
190
|
+
function roundStamp(intent: OpenIntent, withStamp: boolean): string {
|
|
191
|
+
if (!withStamp || intent.expiresAt === null) return "";
|
|
192
|
+
return intent.expired ? ` (expires_at ${intent.expiresAt})` : ` (expires ${intent.expiresAt})`;
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
function countedSentence(open: OpenIntent[]): string {
|
|
196
|
+
const expired = open.filter((intent) => intent.expired).length;
|
|
197
|
+
const ages = open
|
|
198
|
+
.map((intent) => intent.ageHours)
|
|
199
|
+
.filter((hours): hours is number => hours !== null);
|
|
200
|
+
const oldest = ages.length > 0 ? `, oldest ${Math.max(...ages)}h old` : "";
|
|
201
|
+
const lapsed = expired > 0 ? `, ${expired} EXPIRED` : "";
|
|
202
|
+
const count = `${open.length} open intent${open.length === 1 ? "" : "s"} in this journal`;
|
|
203
|
+
return `${count}${oldest}${lapsed}. ${open.length === 1 ? CLOSE_SINGLE : CLOSE_PLURAL}`;
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
function named(intent: OpenIntent): string {
|
|
207
|
+
const age = intent.ageHours === null ? "" : ` ${intent.ageHours}h old`;
|
|
208
|
+
return `"${clipSubject(intent.subject)}"${age}`;
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
function clipSubject(subject: string): string {
|
|
212
|
+
return subject.length <= SUBJECT_LIMIT ? subject : `${subject.slice(0, SUBJECT_LIMIT - 1)}…`;
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
function parseEntry(line: string): Record<string, unknown> | null {
|
|
216
|
+
try {
|
|
217
|
+
const value: unknown = JSON.parse(line);
|
|
218
|
+
if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
|
|
219
|
+
return value as Record<string, unknown>;
|
|
220
|
+
} catch {
|
|
221
|
+
return null;
|
|
222
|
+
}
|
|
223
|
+
}
|
|
@@ -53,6 +53,7 @@ import {
|
|
|
53
53
|
} from "../../../lib/config/braid-paths.js";
|
|
54
54
|
import { projectSlugFromCwd } from "../../memory/scratchpad/persistence.js";
|
|
55
55
|
import { readResumeScratchpadState } from "../resume-state.js";
|
|
56
|
+
import { journalPriorText } from "./open-intents.js";
|
|
56
57
|
|
|
57
58
|
const log = createLogger("enforcement:session-start-discoverability");
|
|
58
59
|
|
|
@@ -225,22 +226,20 @@ export function registerSessionStartDiscoverability(pi: ExtensionAPI): void {
|
|
|
225
226
|
// 7. The owner-input journal. The path comes from the constant the
|
|
226
227
|
// writer appends through, never a hand-built shape: two spellings for
|
|
227
228
|
// one file is how the scratchpad pointer armed itself against a file
|
|
228
|
-
// nothing writes (see step 1).
|
|
229
|
+
// nothing writes (see step 1). The text is composed in `open-intents`,
|
|
230
|
+
// which also names the intents whose status says open: a journal holding
|
|
231
|
+
// a pending install printed the same count sentence as one holding forty
|
|
232
|
+
// closed outcomes, so the seat could not see that work was waiting.
|
|
229
233
|
try {
|
|
230
234
|
const slug = projectSlugFromCwd(cwd);
|
|
231
235
|
const journalFile = journalFilePath(slug);
|
|
232
236
|
if (existsSync(journalFile)) {
|
|
233
|
-
const
|
|
234
|
-
|
|
235
|
-
.filter((line) => line.trim()).length;
|
|
237
|
+
const journalText = readFileSync(journalFile, "utf-8");
|
|
238
|
+
const count = journalText.split("\n").filter((line) => line.trim()).length;
|
|
236
239
|
if (count > 0) {
|
|
237
240
|
signals.push({
|
|
238
241
|
type: "journal_prior",
|
|
239
|
-
text:
|
|
240
|
-
`The project journal holds ${count} entr${count === 1 ? "y" : "ies"} at ${journalFile} -- ` +
|
|
241
|
-
`what earlier seats decided and why, readable without their sessions. ` +
|
|
242
|
-
`Read the open program before acting (digest printer: packages/core/scripts/check-journal.mjs --digest), ` +
|
|
243
|
-
`so a decision gets superseded, not rediscovered.`,
|
|
242
|
+
text: journalPriorText({ count, journalFile }, journalText, new Date()),
|
|
244
243
|
});
|
|
245
244
|
}
|
|
246
245
|
}
|