pi-braid 0.42.0 → 0.43.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. package/CHANGELOG.md +1077 -0
  2. package/README.md +61 -228
  3. package/TOOLS.md +12 -14
  4. package/build-info.json +4 -4
  5. package/dist/extensions/cognitive/metacognition/handlers/think.js +9 -0
  6. package/dist/extensions/core/polyfill/index.d.ts +3 -4
  7. package/dist/extensions/core/polyfill/index.js +34 -131
  8. package/dist/extensions/core/skills-tool/index.js +47 -26
  9. package/dist/extensions/enforcement/handlers/register-agent-end-api-error.js +13 -0
  10. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +8 -3
  11. package/dist/extensions/enforcement/session-health.d.ts +52 -4
  12. package/dist/extensions/enforcement/session-health.js +75 -5
  13. package/dist/extensions/enforcement/whisper.js +15 -1
  14. package/dist/extensions/heartbeat/heartbeat-scheduler/index.d.ts +17 -0
  15. package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +40 -78
  16. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +2 -1
  17. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +26 -28
  18. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.d.ts +62 -31
  19. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.js +130 -55
  20. package/dist/extensions/manifest.js +6 -0
  21. package/dist/extensions/memory/context-lifecycle/index.js +11 -10
  22. package/dist/extensions/memory/context-manager/analysis.d.ts +2 -0
  23. package/dist/extensions/memory/context-manager/analysis.js +6 -2
  24. package/dist/extensions/memory/context-manager/handlers/compaction-retry.js +3 -3
  25. package/dist/extensions/memory/context-manager/handlers/events.js +13 -1
  26. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +10 -14
  27. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +62 -88
  28. package/dist/extensions/self/path-miss/detect.d.ts +30 -0
  29. package/dist/extensions/self/path-miss/detect.js +67 -0
  30. package/dist/extensions/self/path-miss/index.d.ts +33 -0
  31. package/dist/extensions/self/path-miss/index.js +118 -0
  32. package/dist/extensions/self/watchdog/engine.d.ts +8 -1
  33. package/dist/extensions/self/watchdog/engine.js +25 -2
  34. package/dist/extensions/self/watchdog/index.js +14 -1
  35. package/dist/lib/ai/llm-call.js +23 -0
  36. package/dist/lib/ai/model-resolver.d.ts +11 -10
  37. package/dist/lib/ai/model-resolver.js +16 -19
  38. package/dist/lib/ai/presend-budget.d.ts +68 -0
  39. package/dist/lib/ai/presend-budget.js +83 -0
  40. package/dist/lib/config/braid-settings.d.ts +38 -0
  41. package/dist/lib/config/braid-settings.js +84 -0
  42. package/dist/lib/config/per-tool-settings.d.ts +4 -4
  43. package/dist/lib/config/per-tool-settings.js +4 -4
  44. package/dist/lib/core/event-names.d.ts +1 -0
  45. package/dist/lib/core/event-names.js +1 -0
  46. package/dist/lib/detection/context-tiers.d.ts +18 -5
  47. package/dist/lib/detection/context-tiers.js +51 -33
  48. package/dist/lib/detection/context-usage.d.ts +62 -1
  49. package/dist/lib/detection/context-usage.js +158 -1
  50. package/dist/lib/errors/llm-error.d.ts +14 -0
  51. package/dist/lib/errors/llm-error.js +44 -1
  52. package/dist/lib/state/global-state.d.ts +4 -8
  53. package/dist/lib/state/global-state.js +11 -28
  54. package/dist/lib/telemetry/context-heartbeat.d.ts +9 -0
  55. package/dist/lib/telemetry/context-heartbeat.js +18 -8
  56. package/dist/lib/utils/argument-report.d.ts +41 -0
  57. package/dist/lib/utils/argument-report.js +95 -0
  58. package/dist/lib/utils/wake-gate.d.ts +6 -0
  59. package/dist/lib/utils/wake-gate.js +52 -4
  60. package/docs/SETUP.md +7 -6
  61. package/package.json +11 -13
  62. package/src/extensions/cognitive/metacognition/handlers/think.ts +9 -0
  63. package/src/extensions/core/polyfill/index.ts +29 -157
  64. package/src/extensions/core/skills-tool/index.ts +60 -37
  65. package/src/extensions/enforcement/AGENTS.md +38 -1
  66. package/src/extensions/enforcement/handlers/register-agent-end-api-error.ts +13 -0
  67. package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +8 -2
  68. package/src/extensions/enforcement/session-health.ts +94 -5
  69. package/src/extensions/enforcement/whisper.ts +15 -1
  70. package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +53 -80
  71. package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +34 -43
  72. package/src/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.ts +154 -52
  73. package/src/extensions/manifest.ts +6 -0
  74. package/src/extensions/memory/AGENTS.md +37 -38
  75. package/src/extensions/memory/context-lifecycle/index.ts +11 -10
  76. package/src/extensions/memory/context-manager/analysis.ts +8 -1
  77. package/src/extensions/memory/context-manager/handlers/compaction-retry.ts +3 -3
  78. package/src/extensions/memory/context-manager/handlers/events.ts +18 -1
  79. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +81 -115
  80. package/src/extensions/scheduling/timer/AGENTS.md +14 -4
  81. package/src/extensions/self/AGENTS.md +2 -1
  82. package/src/extensions/self/path-miss/AGENTS.md +39 -0
  83. package/src/extensions/self/path-miss/detect.ts +78 -0
  84. package/src/extensions/self/path-miss/index.ts +135 -0
  85. package/src/extensions/self/watchdog/AGENTS.md +36 -18
  86. package/src/extensions/self/watchdog/engine.ts +30 -2
  87. package/src/extensions/self/watchdog/index.ts +13 -1
  88. package/src/lib/ai/AGENTS.md +2 -0
  89. package/src/lib/ai/llm-call.ts +30 -0
  90. package/src/lib/ai/model-resolver.ts +16 -19
  91. package/src/lib/ai/presend-budget.ts +117 -0
  92. package/src/lib/config/braid-settings.ts +125 -0
  93. package/src/lib/config/per-tool-settings.ts +4 -4
  94. package/src/lib/core/event-names.ts +1 -0
  95. package/src/lib/detection/context-tiers.ts +52 -41
  96. package/src/lib/detection/context-usage.ts +211 -2
  97. package/src/lib/errors/llm-error.ts +55 -1
  98. package/src/lib/state/global-state.ts +11 -29
  99. package/src/lib/telemetry/context-heartbeat.ts +27 -7
  100. package/src/lib/utils/AGENTS.md +1 -0
  101. package/src/lib/utils/argument-report.ts +105 -0
  102. package/src/lib/utils/wake-gate.ts +59 -4
@@ -40,7 +40,7 @@ import { pushRssSample, assessSustainedRssGrowth, RSS_RING_CAP } from "./rss-tel
40
40
  import { getRssBootTelemetry, setRssBootBaseline } from "../state/global-state.js";
41
41
  import { getExtensionState, hasExtensionState, safeSessionManagerTyped, } from "../state/extension-state.js";
42
42
  import { getContextUsage } from "../detection/context-tiers.js";
43
- import { measureLiveUsage } from "../detection/context-usage.js";
43
+ import { measureLiveUsage, describeUsage } from "../detection/context-usage.js";
44
44
  const log = createLogger("context-heartbeat");
45
45
  /** Sink directory (created on first append; see header note). */
46
46
  export function heartbeatTelemetryDir() {
@@ -389,20 +389,30 @@ export function collectAndEmitContextHeartbeat(ctx, opts = {}) {
389
389
  export function getSelfStateSample(ctx) {
390
390
  const sample = {
391
391
  contextTokens: null,
392
+ contextPercent: null,
393
+ contextProvenance: null,
392
394
  cacheHitShare: null,
393
395
  nearDupCount: null,
394
396
  tpsEma: null,
395
397
  hygieneActs: null,
396
398
  };
397
399
  try {
398
- // Context tokens: live read (compaction-aware session-tree measure),
399
- // not the last-tick snapshot — a summary rendered right after a slide
400
- // must not report the pre-slide size. Falls back to the duck-typed
401
- // accessor when the session tree is unavailable.
400
+ // Context size: live read (compaction-aware session-tree measure), not the
401
+ // last-tick snapshot - a summary rendered right after a slide must not
402
+ // report the pre-slide size.
403
+ //
404
+ // One instrument, and it is this one. Size, percent and provenance come
405
+ // from a single reading here; the provider accessor answers a different
406
+ // question over a different tree (session projection vs branch), and a
407
+ // delivery that prints both is two ages of one fact. When this meter has
408
+ // no reading, the line says n/a rather than borrowing a second opinion:
409
+ // the reader cannot act on a number whose instrument it cannot name.
402
410
  const live = measureLiveUsage(ctx);
403
- const usage = live ?? getContextUsage(ctx);
404
- if (usage && typeof usage.tokens === "number")
405
- sample.contextTokens = usage.tokens;
411
+ if (live) {
412
+ sample.contextTokens = live.tokens;
413
+ sample.contextPercent = live.percent;
414
+ sample.contextProvenance = describeUsage(live);
415
+ }
406
416
  }
407
417
  catch {
408
418
  /* keep null */
@@ -0,0 +1,41 @@
1
+ /**
2
+ * Tool-argument refusal text.
3
+ *
4
+ * pi validates a tool call against its schema and reports the failure in
5
+ * schema terms: an out-of-list value says "must be equal to one of the allowed
6
+ * values", a missing required field says "must have required properties
7
+ * decision". Neither names the values, so the model that guessed one learns
8
+ * nothing it can act on and guesses again.
9
+ *
10
+ * The accepted values, and the sentence explaining a required field, are
11
+ * already in the schema. This module reads them from there at the moment the
12
+ * refusal is built: no list is written twice, so no copy can drift from the
13
+ * one the validator enforces.
14
+ *
15
+ * Seat: a tool's `prepareArguments`. pi calls it first, inside the same
16
+ * guarded block as its own schema validation, so a throw here is what the
17
+ * model reads — and the schema stays exactly as strict as it was. The checks
18
+ * below are equivalences, not relaxations: a call refused here is one pi would
19
+ * have refused too, only with a message the model can use.
20
+ *
21
+ * Scope is the top level of the argument object. A nested list is left to pi
22
+ * rather than described from a guess about its parent.
23
+ */
24
+ /**
25
+ * The values a schema node accepts, read from the node.
26
+ *
27
+ * A single-valued node (`const`, which is what `Type.Literal` builds) yields
28
+ * one value; an `enum` yields its list; a union of those yields all of them.
29
+ * A node that constrains nothing yields no values, and the caller then leaves
30
+ * the message to pi.
31
+ */
32
+ export declare function acceptedValues(node: unknown): string[];
33
+ /**
34
+ * Throw the refusal a model can act on, when this module can say more than the
35
+ * validator does. Returns silently otherwise, leaving pi's own message intact.
36
+ *
37
+ * `schema` is the same object the tool declares as its `parameters`, and
38
+ * `args` the arguments the call carried.
39
+ */
40
+ export declare function checkArgumentValues(toolName: string, schema: unknown, args: unknown): void;
41
+ //# sourceMappingURL=argument-report.d.ts.map
@@ -0,0 +1,95 @@
1
+ /**
2
+ * Tool-argument refusal text.
3
+ *
4
+ * pi validates a tool call against its schema and reports the failure in
5
+ * schema terms: an out-of-list value says "must be equal to one of the allowed
6
+ * values", a missing required field says "must have required properties
7
+ * decision". Neither names the values, so the model that guessed one learns
8
+ * nothing it can act on and guesses again.
9
+ *
10
+ * The accepted values, and the sentence explaining a required field, are
11
+ * already in the schema. This module reads them from there at the moment the
12
+ * refusal is built: no list is written twice, so no copy can drift from the
13
+ * one the validator enforces.
14
+ *
15
+ * Seat: a tool's `prepareArguments`. pi calls it first, inside the same
16
+ * guarded block as its own schema validation, so a throw here is what the
17
+ * model reads — and the schema stays exactly as strict as it was. The checks
18
+ * below are equivalences, not relaxations: a call refused here is one pi would
19
+ * have refused too, only with a message the model can use.
20
+ *
21
+ * Scope is the top level of the argument object. A nested list is left to pi
22
+ * rather than described from a guess about its parent.
23
+ */
24
+ function nodeOf(value) {
25
+ return value && typeof value === "object" ? value : undefined;
26
+ }
27
+ /**
28
+ * The values a schema node accepts, read from the node.
29
+ *
30
+ * A single-valued node (`const`, which is what `Type.Literal` builds) yields
31
+ * one value; an `enum` yields its list; a union of those yields all of them.
32
+ * A node that constrains nothing yields no values, and the caller then leaves
33
+ * the message to pi.
34
+ */
35
+ export function acceptedValues(node) {
36
+ const schema = nodeOf(node);
37
+ if (!schema)
38
+ return [];
39
+ if (typeof schema.const === "string")
40
+ return [schema.const];
41
+ if (Array.isArray(schema.enum) && schema.enum.every((v) => typeof v === "string")) {
42
+ return [...new Set(schema.enum)];
43
+ }
44
+ const branches = Array.isArray(schema.anyOf)
45
+ ? schema.anyOf
46
+ : Array.isArray(schema.oneOf)
47
+ ? schema.oneOf
48
+ : undefined;
49
+ if (!branches)
50
+ return [];
51
+ return [...new Set(branches.flatMap((branch) => acceptedValues(branch)))];
52
+ }
53
+ function quoted(value) {
54
+ return JSON.stringify(value);
55
+ }
56
+ /**
57
+ * Throw the refusal a model can act on, when this module can say more than the
58
+ * validator does. Returns silently otherwise, leaving pi's own message intact.
59
+ *
60
+ * `schema` is the same object the tool declares as its `parameters`, and
61
+ * `args` the arguments the call carried.
62
+ */
63
+ export function checkArgumentValues(toolName, schema, args) {
64
+ const root = nodeOf(schema);
65
+ const properties = nodeOf(root?.properties);
66
+ const input = nodeOf(args);
67
+ if (!root || !properties || !input)
68
+ return;
69
+ // A required field with a stated purpose: say both, once.
70
+ if (Array.isArray(root.required)) {
71
+ for (const key of root.required) {
72
+ if (typeof key !== "string")
73
+ continue;
74
+ const value = input[key];
75
+ if (value !== undefined && value !== null)
76
+ continue;
77
+ const purpose = nodeOf(properties[key])?.description;
78
+ if (typeof purpose !== "string" || purpose.length === 0)
79
+ continue;
80
+ throw new Error(`${toolName}: ${key} is required (${purpose})`);
81
+ }
82
+ }
83
+ // A value outside its declared list: name the list.
84
+ for (const [key, raw] of Object.entries(input)) {
85
+ if (typeof raw !== "string")
86
+ continue;
87
+ const values = acceptedValues(properties[key]);
88
+ if (values.length === 0 || values.includes(raw))
89
+ continue;
90
+ throw new Error(`${toolName}: ${key} ${quoted(raw)} is not accepted. Accepted: ${values
91
+ .map(quoted)
92
+ .join(", ")}`);
93
+ }
94
+ }
95
+ //# sourceMappingURL=argument-report.js.map
@@ -105,6 +105,12 @@
105
105
  */
106
106
  export declare function isAgentBusy(): boolean;
107
107
  export declare const RUN_REGION_MAX_MS = 120000;
108
+ /** Record that the last turn failed on request shape (a context-length refusal). */
109
+ export declare function noteRequestShapeFailure(detail: string): void;
110
+ /** The recorded request-shape failure, or null. */
111
+ export declare function requestShapeFailure(): string | null;
112
+ /** Clear the record (a request that fits went through, or a new session). */
113
+ export declare function clearRequestShapeFailure(): void;
108
114
  /** Whether a triggerTurn send should be gated (pre-flight tail in progress). */
109
115
  export declare function isRunRegionActive(): boolean;
110
116
  /** Test hook: reset module state between fixtures (also cancels the fail-safe). */
@@ -140,6 +140,26 @@ export const RUN_REGION_MAX_MS = 120_000;
140
140
  let _failSafeHandle = null;
141
141
  // Test hook: override the fail-safe bound (null restores the default).
142
142
  let _failSafeMsOverride = null;
143
+ /**
144
+ * Why the last turn could not be sent at all, when the reason is the SHAPE of
145
+ * the request rather than the state of the provider. A context-length refusal
146
+ * is permanent for a given context: every later turn carrying the same payload
147
+ * is refused the same way, so an ungated wake that starts one is not a retry,
148
+ * it is the same failure under a fresh request id.
149
+ */
150
+ let _requestShapeFailure = null;
151
+ /** Record that the last turn failed on request shape (a context-length refusal). */
152
+ export function noteRequestShapeFailure(detail) {
153
+ _requestShapeFailure = detail;
154
+ }
155
+ /** The recorded request-shape failure, or null. */
156
+ export function requestShapeFailure() {
157
+ return _requestShapeFailure;
158
+ }
159
+ /** Clear the record (a request that fits went through, or a new session). */
160
+ export function clearRequestShapeFailure() {
161
+ _requestShapeFailure = null;
162
+ }
143
163
  function failSafeMs() {
144
164
  return _failSafeMsOverride ?? RUN_REGION_MAX_MS;
145
165
  }
@@ -153,16 +173,42 @@ function clearFailSafe() {
153
173
  function armRunRegion() {
154
174
  _runRegionActive = true;
155
175
  clearFailSafe();
176
+ scheduleFailSafe();
177
+ // Do not keep the process alive for a stuck gate.
178
+ unrefFailSafe();
179
+ }
180
+ /** Let the process exit while a fail-safe window is pending. */
181
+ function unrefFailSafe() {
182
+ const handle = _failSafeHandle;
183
+ if (typeof handle?.unref === "function")
184
+ handle.unref();
185
+ }
186
+ /**
187
+ * One fail-safe window. Normally the gate opens here: a gate stuck closed by a
188
+ * pre-flight abort rewrites every wake into a queued steer that never starts a
189
+ * turn, which is its own failure.
190
+ *
191
+ * The exception is a recorded request-shape failure. There, opening the gate
192
+ * buys no safety - it starts the same doomed request again, and again. So the
193
+ * gate stays closed and the window re-arms: wakes keep arriving as steers into
194
+ * the session (the shape that reads them when a run does start) without
195
+ * starting one.
196
+ */
197
+ function scheduleFailSafe() {
156
198
  _failSafeHandle = setTimeout(() => {
157
199
  _failSafeHandle = null;
200
+ if (_requestShapeFailure) {
201
+ log.warn(`[wake-gate] fail-safe: keeping triggerTurn wakes gated - the last turn was refused on ` +
202
+ `request shape (context length), so the request it would start cannot succeed. ` +
203
+ `Remedy: compact the session. Detail: ${_requestShapeFailure}`);
204
+ scheduleFailSafe();
205
+ unrefFailSafe();
206
+ return;
207
+ }
158
208
  _runRegionActive = false;
159
209
  log.warn(`[wake-gate] fail-safe: run region auto-cleared after ${failSafeMs()}ms without a release event ` +
160
210
  `(pre-flight abort?) — triggerTurn wakes ungated again`);
161
211
  }, failSafeMs());
162
- // Do not keep the process alive for a stuck gate.
163
- if (typeof _failSafeHandle?.unref === "function") {
164
- _failSafeHandle.unref();
165
- }
166
212
  }
167
213
  /** Release the gate and cancel the fail-safe timer. */
168
214
  function releaseRunRegion() {
@@ -178,6 +224,7 @@ export function resetWakeGateForTests() {
178
224
  releaseRunRegion();
179
225
  _lastAgentCtx = null;
180
226
  _failSafeMsOverride = null;
227
+ _requestShapeFailure = null;
181
228
  }
182
229
  /** Test hook: shorten/extend the fail-safe bound (null restores the default). */
183
230
  export function _setWakeGateFailSafeMsForTests(ms) {
@@ -231,6 +278,7 @@ export function registerWakeGate(pi) {
231
278
  });
232
279
  pi.on(SESSION_SHUTDOWN, () => {
233
280
  releaseRunRegion();
281
+ _requestShapeFailure = null; // a new session starts without a shape verdict
234
282
  _lastAgentCtx = null; // no live session after shutdown: fail open until the next capture
235
283
  });
236
284
  }
package/docs/SETUP.md CHANGED
@@ -37,9 +37,9 @@ workspace manifest); if this table and `engines` ever disagree, trust
37
37
  from npm needs no checkout at all.
38
38
 
39
39
  **How the pi version resolves.** braid declares the `@earendil-works/pi-*`
40
- packages as peer dependencies with unconstrained (`*`) ranges. npm resolves
41
- peers at install time: against a compatible pi installation already in your
42
- tree when one exists, otherwise by auto-installing the current release. The
40
+ packages as peer dependencies in the `^1.2.0` range. npm resolves peers at
41
+ install time: against a compatible pi installation already in your tree when one
42
+ exists, otherwise by auto-installing a release that satisfies the range. The
43
43
  result is pinned in `package-lock.json`, so braid runs against whatever pi
44
44
  version your install resolved to rather than pinning its own;
45
45
  `npm ls @earendil-works/pi-coding-agent` shows what you got.
@@ -306,6 +306,7 @@ The user-global file always exists; the project one is optional and belongs to p
306
306
  | `braid.enforcement.nudgeConfigs.<type>` | object | built-in per-type defaults | Per-nudge-type overrides with leaf shape `braid.enforcement.nudgeConfigs.<type>.<key>`; accepted fields are `baseCooldownMs` (number), `escalateAfter` (number), and `deduplicate` (boolean). Types: `validation`, `recordFailure`, `malformed`, `memory`, `scratchpad`, `context`, `sessionSignals`. Invalid entries are logged and dropped. |
307
307
  | `braid.memory.writeGate` | object | gate ON, 20-min cooldown, `enforce` | Review-before-write gate on episode writes; `mode: "warn"` logs decisions and writes anyway; `sites` opts individual writers out. |
308
308
  | `braid.timers.maxWakeAttempts` | integer 1..10 | `3` | Redelivery cap for a failed timer wake before it is dropped with a visible notice. |
309
+ | `braid.session.routeBreaker` | object | ON, 3 failures, 1h floor | Route-failure latch: after `threshold` provider failures of any class except a context-window overflow or an abort since the session's last successful call, self-started turns park - timer wakes, watchdog escalations and explicitly-waking whispers are delivered non-waking, the content still reaches the session and the out-of-band line still fires. Released by a successful provider call, a clean wake turn, a route change, an owner recovery or a session start; while open it still releases one turn per `floorMs`. `enabled: false` makes it inert. |
309
310
  | `braid.timers.wakeAlert` | object | ON, `outcomeTimeouts: 2` | Dead-wake page: repeated outcome timeouts / exhausted redeliveries feed the watchdog's wake-delivery condition, which pages the owner out of band (telegram) once per episode plus one recovery line. `mode: "off"` disables the feed (delivery itself is unchanged); `outcomeTimeouts` is an integer 2..10 (1 would page on every normal long turn). |
310
311
  | `braid.context.contextLimitTokens` | positive number | provider context window | The window every surface computes with (usage math, density, fallbacks, pi-core threshold compaction and overflow detection, TUI footer). A CEILING: min(contextLimitTokens, true window) when known, else the cap; re-plumbed on session start and /reload and never widens a smaller true window. The provider catalog keeps the true size. |
311
312
  | `braid.context.toolResultSizeCap` | object | ON, 262144 chars | Capture-time cap: oversized tool results are flushed to disk and replaced by a stub. |
@@ -480,14 +481,14 @@ If the failure persists, open an issue with the full error from `npm run build`.
480
481
 
481
482
  ### TypeScript errors after upgrade
482
483
 
483
- braid declares `@earendil-works/pi-*` as peer dependencies with unconstrained
484
- (`*`) ranges, resolved at install time (see [Prerequisites](#prerequisites)).
484
+ braid declares `@earendil-works/pi-*` as peer dependencies in the `^1.2.0`
485
+ range, resolved at install time (see [Prerequisites](#prerequisites)).
485
486
  Make sure the pi packages are in this repo's dependency tree:
486
487
 
487
488
  ```bash
488
489
  ls node_modules/@earendil-works/ 2>/dev/null
489
490
  # If empty, the pi packages aren't in this repo's dependency tree.
490
- # Run `npm install` (npm auto-installs unconstrained peer dependencies),
491
+ # Run `npm install` (npm auto-installs peer dependencies inside the range),
491
492
  # or run pi from outside this repo.
492
493
  ```
493
494
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.42.0",
4
- "description": "Metacognitive extension suite for pi-coding-agent: enforcement, memory, reasoning, self-improvement, and structured cognitive signals.",
3
+ "version": "0.43.0",
4
+ "description": "Adds memory, plan tracking, and completion checks to the pi coding agent, so long sessions keep their context and stop claiming unfinished work.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
7
7
  "types": "./dist/index.d.ts",
@@ -23,6 +23,7 @@
23
23
  "LICENSE",
24
24
  "AGENTS.md",
25
25
  "CONTRIBUTING.md",
26
+ "CHANGELOG.md",
26
27
  "TOOLS.md",
27
28
  "build-info.json"
28
29
  ],
@@ -66,8 +67,8 @@
66
67
  "release:local": "node scripts/publish-local.mjs",
67
68
  "publish:local": "node scripts/publish-local.mjs",
68
69
  "dev:link": "npm link && cd ~/.pi/agent/local-packages && npm link pi-braid",
69
- "prepack": "npm run build && node scripts/pack-provenance.mjs write",
70
- "postpack": "node scripts/pack-provenance.mjs remove"
70
+ "prepack": "npm run build && node scripts/stage-changelog.mjs write && node scripts/pack-provenance.mjs write",
71
+ "postpack": "node scripts/pack-provenance.mjs remove && node scripts/stage-changelog.mjs remove"
71
72
  },
72
73
  "devDependencies": {
73
74
  "@eslint/js": "10.0.1",
@@ -88,16 +89,13 @@
88
89
  },
89
90
  "keywords": [
90
91
  "pi-package",
91
- "pi",
92
- "pi-extension",
93
92
  "pi-coding-agent",
94
- "llm-agent",
95
- "cognitive-systems",
96
- "enforcement",
97
- "planning",
98
- "metacognition",
99
- "self-improvement",
100
- "memory-management"
93
+ "pi-extension",
94
+ "coding-agent",
95
+ "agent-memory",
96
+ "context-management",
97
+ "subagents",
98
+ "skills"
101
99
  ],
102
100
  "author": "kifirkin",
103
101
  "license": "MIT",
@@ -16,6 +16,7 @@ import {
16
16
  DEPTH_LEVELS,
17
17
  } from "./think-budget.js";
18
18
  import { criticGate } from "../../../../lib/ai/critic-gate.js";
19
+ import { checkArgumentValues } from "../../../../lib/utils/argument-report.js";
19
20
  import { getExtensionState } from "../../../../lib/state/extension-state.js";
20
21
  import { createLogger } from "../../../../lib/core/logger.js";
21
22
 
@@ -213,6 +214,14 @@ export function createThinkTool(): ToolDefinition<any, any, any> {
213
214
  description: "Think deeply with structured reasoning before making high-stakes decisions.",
214
215
  promptSnippet: "Think deeply with structured reasoning before decisions",
215
216
  parameters: thinkSchema,
217
+ // pi validates arguments before `execute` is reached, and its own refusal
218
+ // for a guessed enum or a missing field names neither. This hook runs
219
+ // first, inside the same guarded block, and refuses with the values the
220
+ // schema above already declares.
221
+ prepareArguments: (args: unknown) => {
222
+ checkArgumentValues("think", thinkSchema, args);
223
+ return args;
224
+ },
216
225
  execute: async (
217
226
  _toolCallId: string,
218
227
  params: any,