pi-braid 0.40.1 → 0.40.3

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 (105) hide show
  1. package/CONTRIBUTING.md +27 -3
  2. package/README.md +13 -13
  3. package/TOOLS.md +27 -3
  4. package/build-info.json +9 -0
  5. package/dist/extensions/cognitive/metacognition/handlers/claim-verification.js +7 -1
  6. package/dist/extensions/cognitive/metacognition/handlers/finalize.js +20 -0
  7. package/dist/extensions/cognitive/metacognition/handlers/hypothesize.d.ts +9 -0
  8. package/dist/extensions/cognitive/metacognition/handlers/hypothesize.js +13 -1
  9. package/dist/extensions/cognitive/metacognition/handlers/verify.js +35 -4
  10. package/dist/extensions/cognitive/topic-drift/index.js +19 -2
  11. package/dist/extensions/core/prompt-builder/inspect.js +9 -3
  12. package/dist/extensions/core/prompt-builder/top-level-extensions.d.ts +6 -5
  13. package/dist/extensions/core/prompt-builder/top-level-extensions.js +64 -29
  14. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.d.ts +1 -1
  15. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.js +1 -1
  16. package/dist/extensions/enforcement/handlers/turn-end-handler.js +1 -1
  17. package/dist/extensions/enforcement/self-state-claims.d.ts +1 -1
  18. package/dist/extensions/enforcement/self-state-claims.js +3 -2
  19. package/dist/extensions/manifest.js +2 -2
  20. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.d.ts +22 -5
  21. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.js +43 -11
  22. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +174 -50
  23. package/dist/extensions/memory/context-manager/handlers/tools/context-inspect.js +7 -1
  24. package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.js +4 -1
  25. package/dist/extensions/memory/memory-agent-bridge/explore-paths.d.ts +2 -24
  26. package/dist/extensions/memory/memory-agent-bridge/explore-paths.js +33 -2
  27. package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.js +16 -0
  28. package/dist/extensions/memory/memory-agent-bridge/memory-tool.js +21 -9
  29. package/dist/extensions/memory/scratchpad/format.js +8 -2
  30. package/dist/extensions/memory/scratchpad/index.js +11 -2
  31. package/dist/extensions/memory/session-recall/index.js +19 -6
  32. package/dist/extensions/memory/three-memory-stores/episodes.d.ts +1 -1
  33. package/dist/extensions/memory/three-memory-stores/episodes.js +2 -2
  34. package/dist/extensions/orchestrator/index.js +73 -8
  35. package/dist/extensions/scheduling/timer/index.js +9 -1
  36. package/dist/extensions/self/error-tracking/index.js +8 -1
  37. package/dist/extensions/self/health-maintenance/handlers/session-health-tool.js +9 -2
  38. package/dist/extensions/self/health-maintenance/index.js +112 -9
  39. package/dist/lib/config/braid-settings.d.ts +21 -0
  40. package/dist/lib/config/braid-settings.js +36 -0
  41. package/dist/lib/constants/session-thresholds.d.ts +2 -3
  42. package/dist/lib/constants/session-thresholds.js +2 -3
  43. package/dist/lib/enforcement/turn-dedup.d.ts +2 -2
  44. package/dist/lib/enforcement/turn-dedup.js +2 -2
  45. package/dist/lib/harness/index.d.ts +1 -1
  46. package/dist/lib/harness/index.js +1 -1
  47. package/dist/lib/harness/types.d.ts +1 -1
  48. package/dist/lib/harness/types.js +1 -1
  49. package/dist/lib/orchestrator/index.d.ts +2 -2
  50. package/dist/lib/orchestrator/index.js +1 -1
  51. package/dist/lib/orchestrator/workers.d.ts +184 -2
  52. package/dist/lib/orchestrator/workers.js +521 -6
  53. package/dist/lib/utils/injection-tracker.js +1 -1
  54. package/docs/CONTEXT-POLICY.md +13 -5
  55. package/docs/LOCAL_DEV.md +31 -5
  56. package/docs/ROADMAP.md +10 -7
  57. package/docs/SETUP.md +3 -2
  58. package/package.json +11 -8
  59. package/skills/braid-reference/SKILL.md +23 -23
  60. package/skills/release-pipeline/SKILL.md +46 -37
  61. package/skills/subagent-orchestration/SKILL.md +51 -1
  62. package/src/extensions/cognitive/metacognition/handlers/claim-verification.ts +8 -1
  63. package/src/extensions/cognitive/metacognition/handlers/finalize.ts +21 -0
  64. package/src/extensions/cognitive/metacognition/handlers/hypothesize.ts +14 -1
  65. package/src/extensions/cognitive/metacognition/handlers/verify.ts +39 -5
  66. package/src/extensions/cognitive/topic-drift/index.ts +20 -2
  67. package/src/extensions/core/prompt-builder/AGENTS.md +1 -1
  68. package/src/extensions/core/prompt-builder/inspect.ts +10 -3
  69. package/src/extensions/core/prompt-builder/top-level-extensions.ts +68 -29
  70. package/src/extensions/enforcement/AGENTS.md +25 -19
  71. package/src/extensions/enforcement/handlers/register-tool-result-formatting.ts +1 -1
  72. package/src/extensions/enforcement/handlers/turn-end-handler.ts +1 -1
  73. package/src/extensions/enforcement/self-state-claims.ts +3 -2
  74. package/src/extensions/heartbeat/heartbeat-scheduler/AGENTS.md +6 -3
  75. package/src/extensions/manifest.ts +2 -2
  76. package/src/extensions/memory/AGENTS.md +13 -5
  77. package/src/extensions/memory/context-manager/handlers/tool-batch-boundary.ts +45 -11
  78. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +202 -60
  79. package/src/extensions/memory/context-manager/handlers/tools/context-inspect.ts +8 -1
  80. package/src/extensions/memory/context-manager/handlers/tools/context-navigate.ts +4 -1
  81. package/src/extensions/memory/memory-agent-bridge/explore-paths.ts +37 -3
  82. package/src/extensions/memory/memory-agent-bridge/memory-store-tool.ts +16 -0
  83. package/src/extensions/memory/memory-agent-bridge/memory-tool.ts +22 -9
  84. package/src/extensions/memory/scratchpad/format.ts +8 -2
  85. package/src/extensions/memory/scratchpad/index.ts +12 -2
  86. package/src/extensions/memory/session-recall/index.ts +20 -8
  87. package/src/extensions/memory/three-memory-stores/episodes.ts +2 -2
  88. package/src/extensions/orchestrator/index.ts +100 -11
  89. package/src/extensions/scheduling/timer/AGENTS.md +7 -0
  90. package/src/extensions/scheduling/timer/index.ts +10 -1
  91. package/src/extensions/self/error-tracking/index.ts +9 -1
  92. package/src/extensions/self/health-maintenance/handlers/session-health-tool.ts +10 -2
  93. package/src/extensions/self/health-maintenance/index.ts +143 -14
  94. package/src/extensions/self/watchdog/AGENTS.md +1 -0
  95. package/src/lib/AGENTS.md +21 -21
  96. package/src/lib/config/braid-settings.ts +74 -0
  97. package/src/lib/constants/session-thresholds.ts +2 -3
  98. package/src/lib/enforcement/turn-dedup.ts +2 -2
  99. package/src/lib/harness/AGENTS.md +1 -1
  100. package/src/lib/harness/index.ts +1 -1
  101. package/src/lib/harness/types.ts +1 -1
  102. package/src/lib/orchestrator/index.ts +26 -0
  103. package/src/lib/orchestrator/workers.ts +705 -7
  104. package/src/lib/utils/AGENTS.md +1 -1
  105. package/src/lib/utils/injection-tracker.ts +1 -1
package/CONTRIBUTING.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  # Contributing to pi-braid
4
4
 
5
- Thanks for your interest. This file is for **braid contributors** - people working on braid itself. If you only want to _use_ braid, see [`README.md`](README.md) and [`docs/SETUP.md`](docs/SETUP.md).
5
+ Thanks for your interest. This file is for **braid contributors** - people working on braid itself. If you only want to _use_ braid, install the published package with `pi install npm:pi-braid` (one command, no clone, no build) and start from [`README.md`](README.md) and [`docs/SETUP.md`](docs/SETUP.md); everything below is the checkout flow a contributor needs.
6
6
 
7
7
  ---
8
8
 
@@ -281,14 +281,38 @@ Check the output for:
281
281
 
282
282
  ### 5. Tag and publish
283
283
 
284
+ After the manifest bumps, run `npm install` at the root so
285
+ `package-lock.json` follows them: the workflow installs with `npm ci` from that
286
+ lockfile, and `npm ci` refuses a lockfile whose resolved inventory no longer
287
+ satisfies the manifests, not one that disagrees with a manifest's own version
288
+ field. A version-only bump therefore passes whether or not the lockfile was
289
+ refreshed: keeping the two in step is convention, not a gate.
290
+
284
291
  ```bash
292
+ npm install # sync package-lock.json with the bumps
285
293
  git add -A
286
294
  git commit -m "chore: release vX.Y.Z"
287
- git tag vX.Y.Z
295
+ npm run ci:check # includes release:check; must pass at HEAD
296
+ git tag -a "v$(node -p "require('./packages/core/package.json').version")" -m "release" # release tag: the workflow publishes this name
297
+ node packages/core/scripts/tag-prerelease.mjs <package> # iteration tag (v<version>-main.N): never publishes
288
298
  git push origin main --tags
289
- npm publish
290
299
  ```
291
300
 
301
+ Pushing the release tag (`v<core version>`) runs `.github/workflows/publish.yml`,
302
+ which publishes every package whose manifest version is not yet on the registry
303
+ through npm trusted publishing (OIDC). No npm token is involved. Sibling tags
304
+ (`<workspace>-v<version>`) do not trigger the workflow; to publish a single
305
+ package, dispatch the workflow from `main` with `only=<package>`, never from an
306
+ iteration tag: a dispatch bypasses the job condition and can publish sibling
307
+ packages.
308
+
309
+ Two tag roles, both keeping core's bare `v<version>` and a sibling's workspace
310
+ name (`telegram-v0.1.4`, `providers-v1.0.5`): the release tag above is the one
311
+ the workflow publishes, and `tag-prerelease.mjs` creates the iteration tag
312
+ (`v<version>-main.N` on `main`) that names the tree a package was packed from
313
+ and never publishes. Both schemes and the per-line namespaces are recorded at
314
+ the top of `CHANGELOG.md`.
315
+
292
316
  ### 6. Post-publish
293
317
 
294
318
  - Verify the package appears on npmjs.com
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
6
  [![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue.svg)](https://www.typescriptlang.org/)
7
- [![pi-coding-agent ≥ 1.2.0](https://img.shields.io/badge/pi--coding--agent-%E2%89%A51.2.0-blueviolet)](https://github.com/earendil-works/pi)
7
+ [![pi-coding-agent ^1.2.0](https://img.shields.io/badge/pi--coding--agent-%5E1.2.0-blueviolet)](https://github.com/earendil-works/pi)
8
8
 
9
9
  Honest self-aware agent with a metacognitive suite and extras on top of [pi-coding-agent](https://github.com/earendil-works/pi). The suite adds enforcement, memory, reasoning, self-improvement, and structured cognitive signals on top of the pi agent session.
10
10
 
@@ -132,7 +132,7 @@ pi loads extensions from a `packages` entry in `<cwd>/.pi/settings.json` (projec
132
132
  ```
133
133
 
134
134
  This package is the **core** workspace. The monorepo also contains four
135
- sibling packages (see [`../../README.md`](https://github.com/kifirkin/pi-braid/blob/main/README.md) for the full map):
135
+ sibling packages (see the root [`README.md`](https://github.com/kifirkin/pi-braid/blob/main/README.md) for the full map):
136
136
 
137
137
  | Package | Role |
138
138
  | ------------- | -------------------------------------------------------------------- |
@@ -225,7 +225,7 @@ skills in the system prompt's `<available_skills>` block; the agent opens a
225
225
 
226
226
  The catalog table (one row per skill, with its verdict and one-line
227
227
  description, covering both tiers) lives in
228
- **[`../skills/README.md`](https://github.com/kifirkin/pi-braid/blob/main/packages/skills/README.md)**, and
228
+ **[`packages/skills/README.md`](https://github.com/kifirkin/pi-braid/blob/main/packages/skills/README.md)**, and
229
229
  `find packages/core/skills -name SKILL.md | wc -l` counts the core set at any
230
230
  time (`find packages/skills/skills -name SKILL.md | wc -l` counts the pack).
231
231
 
@@ -233,16 +233,16 @@ time (`find packages/skills/skills -name SKILL.md | wc -l` counts the pack).
233
233
 
234
234
  ## Documentation
235
235
 
236
- | Doc | For |
237
- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
238
- | [`docs/BEGINNERS.md`](docs/BEGINNERS.md) | **First walkthrough**: install → how agents use braid → first extension |
239
- | [`docs/SETUP.md`](docs/SETUP.md) | **Full setup reference**, install paths, troubleshooting |
240
- | [`docs/ROADMAP.md`](docs/ROADMAP.md) | Active roadmap + shipped milestones + open themes |
241
- | [`README.md`](README.md) | This overview |
242
- | [`AGENTS.md`](AGENTS.md) | Repository structure, DOX contract, conventions |
243
- | [`CONTRIBUTING.md`](CONTRIBUTING.md) | Development setup, code style, PR workflow, release |
244
- | [`docs/HISTORY.md`](docs/HISTORY.md) | Consolidated project history, archived roadmap, research |
245
- | [`../../CHANGELOG.md`](https://github.com/kifirkin/pi-braid/blob/main/CHANGELOG.md) | Release notes (curated) |
236
+ | Doc | For |
237
+ | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
238
+ | [`docs/BEGINNERS.md`](docs/BEGINNERS.md) | **First walkthrough**: install → how agents use braid → first extension |
239
+ | [`docs/SETUP.md`](docs/SETUP.md) | **Full setup reference**, install paths, troubleshooting |
240
+ | [`docs/ROADMAP.md`](docs/ROADMAP.md) | Active roadmap + shipped milestones + open themes |
241
+ | [`README.md`](README.md) | This overview |
242
+ | [`AGENTS.md`](AGENTS.md) | Repository structure, DOX contract, conventions |
243
+ | [`CONTRIBUTING.md`](CONTRIBUTING.md) | Development setup, code style, PR workflow, release |
244
+ | [`docs/HISTORY.md`](docs/HISTORY.md) | Consolidated project history, archived roadmap, research |
245
+ | [`CHANGELOG.md`](https://github.com/kifirkin/pi-braid/blob/main/CHANGELOG.md) | Release notes (curated) |
246
246
 
247
247
  ---
248
248
 
package/TOOLS.md CHANGED
@@ -34,9 +34,10 @@ fails until the other catches up.
34
34
 
35
35
  ## Enablement reference
36
36
 
37
- Braid extension loading is resolved by `src/loader/loader.ts` (`resolveEnabledExtensions`, loader.ts:193-263)
38
- with priority: runtime subagent API → `~/.pi/agent/settings.json` `braid.modules` → `BRAID_MODULES`
39
- env var → manifest defaults (`src/extensions/manifest.ts`). Always-on extensions (`alwaysOn: true`)
37
+ Braid extension loading is resolved by `src/loader/loader.ts` (`resolveEnabledExtensions`, loader.ts:327)
38
+ with priority: runtime overrides (`/modules-*`) → `braid.modules` from two sources, the later
39
+ winning per id (`~/.pi/agent/settings.json`, then braid's own module-overrides store where those
40
+ toggles persist) → `BRAID_MODULES` env var → manifest defaults (`src/extensions/manifest.ts`). Always-on extensions (`alwaysOn: true`)
40
41
  can never be disabled; opt-in extensions (`disabledByDefault: true`) only load when explicitly enabled.
41
42
  Standalone packages (contrib, npm) load through pi's own package extension mechanism and keep their own
42
43
  enablement (see appendix).
@@ -81,6 +82,28 @@ enablement (see appendix).
81
82
 
82
83
  <!-- TOOLS-CATALOG-END -->
83
84
 
85
+ ## Command catalog
86
+
87
+ Extension commands the tool catalog does not cover: slash commands registered by
88
+ the core and contrib extensions and named in no other document. A command with
89
+ a home beside its extension is not repeated here - `/watchdog-status` lives in
90
+ the watchdog `AGENTS.md`, the `/modules-*` family in `SETUP.md`.
91
+
92
+ | Command | Registered by | What it does |
93
+ | --------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
94
+ | `/analytics` | analytics (heartbeat module) | Show tool analytics for the current session. |
95
+ | `/analytics:all` | analytics (heartbeat module) | Show tool analytics across all historical sessions. |
96
+ | `/analytics:ab` | analytics (heartbeat module) | Show A/B experiment results across variants. |
97
+ | `/context-stats` | context-manager (memory module) | Show context pruning statistics. |
98
+ | `/rate-cancel` | rate-limiter (contrib) | Cancel the rate limiter wait and reset its state. |
99
+ | `/tool-status` | tool-config (contrib) | Show current tool configuration. |
100
+ | `/browser-start` | browser (contrib) | Spawn Chrome with remote debugging; `--profile` syncs cookies and logins. |
101
+ | `/browser-connect` | browser (contrib) | Connect to Chrome at :9222 (auto-starts if not running). |
102
+ | `/browser-disconnect` | browser (contrib) | Disconnect from the browser session. |
103
+ | `/utility-model` | polyfill (core) | Set or show the utility model for classification tasks; accepts one model or an ordered list (comma-separated), tried in order until the provider layer reports a route usable. |
104
+ | `/vision-model` | polyfill (core) | Set or show the vision model (every entry must accept image input); deprecated - image analysis falls back to the utility list's first image-capable model, and the command is removed next release. |
105
+ | `/max-power-model` | polyfill (core) | Deprecated alias of `/utility-model`: the max-power role merged into the utility role; set/show/clear operate on the canonical utility setting, and the alias is removed next release. |
106
+
84
107
  ## Appendix: standalone packages surfaced into the braid prompt
85
108
 
86
109
  The braid prompt surfaces every tool the loaded packages and pi-core provide via
@@ -123,6 +146,7 @@ Tool families it registers:
123
146
  - **repl** - execute JavaScript code with context (RLM mode for chunk/search/map/reduce).
124
147
  - **sleep** - block agent execution for a duration (do not use bash `sleep`).
125
148
  - **system-monitor** - CPU/memory/disk/top-process metrics for performance troubleshooting.
149
+ - **network-monitor** - `tunnel_status` / `tunnel_reconnect` (plus the pinned `v2raytun_status` / `v2raytun_reconnect` aliases): probe a macOS tunnel client (`v2raytun`, `happ`, `incy`) and reconnect it through its own toggle mechanism. Off with `braid.contrib.networkMonitor: false`, tunable with an object.
126
150
  - **path-security / rate-limiter / tool-config** - guard/plumbing extensions; no LLM-facing tools.
127
151
 
128
152
  ### pi-web-access (npm package)
@@ -0,0 +1,9 @@
1
+ {
2
+ "name": "pi-braid",
3
+ "version": "0.40.3",
4
+ "sha": "3f07ed16880eec5fea0c69493fff5cf59ac0cbf0",
5
+ "shaShort": "3f07ed1",
6
+ "branch": "detached",
7
+ "dirty": false,
8
+ "packedAt": "2026-10-20T11:41:36.856Z"
9
+ }
@@ -19,6 +19,10 @@ import { classify } from "../../../../lib/ai/text-classifier.js";
19
19
  import { CRITICS } from "../../../../lib/ai/critic-registry.js";
20
20
  import { consolidatedClaimCritique } from "../../../../lib/ai/consolidated-claim-critic.js";
21
21
  const log = createLogger("metacognition:claim-verification");
22
+ /** A blank string is "not provided": a client that emits every schema key sends "" for the unused ones. */
23
+ function optionalString(v) {
24
+ return typeof v === "string" && v.trim().length > 0 ? v : undefined;
25
+ }
22
26
  function truncate(text, maxLen) {
23
27
  return text.length > maxLen ? text.slice(0, maxLen) + "..." : text;
24
28
  }
@@ -116,7 +120,9 @@ export function createVerifyClaimTool() {
116
120
  if (!p.claim || !Array.isArray(p.context)) {
117
121
  throw new Error("verify_claim requires 'claim' (string) and 'context' (string array)");
118
122
  }
119
- const claimId = p.claimId ?? `claim-${Date.now()}`;
123
+ // A blank claimId is no id: it would become the tracking key of every
124
+ // such call for the rest of the session.
125
+ const claimId = optionalString(p.claimId) ?? `claim-${Date.now()}`;
120
126
  const issues = [];
121
127
  // PRIMARY PATH: consolidated single-LLM-call
122
128
  let consolidatedUsed = false;
@@ -453,6 +453,26 @@ finalize(completed=true, summary="Fixed the bug", tasksRemaining=["write tests"]
453
453
  details: { finalized: false, blocked: true, error: "missing_params" },
454
454
  };
455
455
  }
456
+ // A blank summary names nothing. The `=== undefined` check above lets it
457
+ // through, and the summary lands in the memory episode, the session label
458
+ // and the deliverables manifest -- an unfindable task recorded as done.
459
+ if (typeof params.summary !== "string" || params.summary.trim().length === 0) {
460
+ return {
461
+ content: [
462
+ {
463
+ type: "text",
464
+ text: `**FINALIZE REQUIRES A SUMMARY**
465
+
466
+ finalize was called with summary ${JSON.stringify(params.summary ?? null)}, which names nothing to record.
467
+ Provide the summary text: what was accomplished, or what is still open with completed: false.
468
+
469
+ Example:
470
+ finalize(completed=true, summary="Fixed the parser offset clamp", tasksRemaining=["add fixture"])`,
471
+ },
472
+ ],
473
+ details: { finalized: false, blocked: true, error: "missing_summary" },
474
+ };
475
+ }
456
476
  // Pre-flight check: verify must have passed
457
477
  if (_ctx && !params.completed) {
458
478
  const lastVerification = getLastVerification(_ctx);
@@ -15,5 +15,14 @@ import type { LlmCallOptions } from "../../../../lib/ai/llm-call.js";
15
15
  * runtime and clamps per model, so "off" is safe for every provider.
16
16
  */
17
17
  export declare function emptyResponseRetryOptions(lastError: string): LlmCallOptions | null;
18
+ /**
19
+ * The hypothesis count a call asks for. Argument validation converts a blank
20
+ * string to 0 for `Type.Optional(Type.Number())` and the converted value passes,
21
+ * so a handler cannot tell a blank from a typed 0; a prompt asking the model for
22
+ * zero hypotheses is never a usable request, so a non-positive or non-finite
23
+ * value is read as absent and the documented default (3) applies. Exported pure
24
+ * for the fixture, like emptyResponseRetryOptions above.
25
+ */
26
+ export declare function resolveMaxHypotheses(value: unknown): number;
18
27
  export declare function createHypothesizeTool(): ToolDefinition<any, any, any>;
19
28
  //# sourceMappingURL=hypothesize.d.ts.map
@@ -45,6 +45,17 @@ export function emptyResponseRetryOptions(lastError) {
45
45
  return null;
46
46
  return { temperature: 0.3, maxTokens: 4000, reasoning: "off" };
47
47
  }
48
+ /**
49
+ * The hypothesis count a call asks for. Argument validation converts a blank
50
+ * string to 0 for `Type.Optional(Type.Number())` and the converted value passes,
51
+ * so a handler cannot tell a blank from a typed 0; a prompt asking the model for
52
+ * zero hypotheses is never a usable request, so a non-positive or non-finite
53
+ * value is read as absent and the documented default (3) applies. Exported pure
54
+ * for the fixture, like emptyResponseRetryOptions above.
55
+ */
56
+ export function resolveMaxHypotheses(value) {
57
+ return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 3;
58
+ }
48
59
  const FORMAT_OPTIONS = ["ranked", "tree", "list"];
49
60
  const hypothesizeSchema = Type.Object({
50
61
  problem: Type.String({ description: "The problem or issue to generate hypotheses about" }),
@@ -100,7 +111,8 @@ export function createHypothesizeTool() {
100
111
  description: "Generate root-cause hypotheses when a first fix attempt fails, using fresh-eyes debugging analysis.",
101
112
  parameters: hypothesizeSchema,
102
113
  execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
103
- const { problem, evidence, maxHypotheses = 3, format = "ranked", verificationPlan } = params;
114
+ const { problem, evidence, format = "ranked", verificationPlan } = params;
115
+ const maxHypotheses = resolveMaxHypotheses(params.maxHypotheses);
104
116
  if (!ctx?.model) {
105
117
  throw new Error(`hypothesize: no model available for session model analysis. ` +
106
118
  `Problem: "${problem.slice(0, 50)}..." | Evidence: "${evidence.slice(0, 50)}..."`);
@@ -49,6 +49,21 @@ const DEFAULT_CRITERIA = {
49
49
  "Completeness (all parts addressed)",
50
50
  ],
51
51
  };
52
+ /** A blank string is "not provided": clients that emit every schema key send "" for the unused ones. */
53
+ function optionalString(v) {
54
+ return typeof v === "string" && v.trim().length > 0 ? v : undefined;
55
+ }
56
+ /**
57
+ * Drop blank criteria entries before use. A list left empty names nothing
58
+ * usable, so the target's defaults stand in: the LLM tier must never receive
59
+ * an empty rubric.
60
+ */
61
+ function resolveCriteria(provided, target) {
62
+ const cleaned = Array.isArray(provided)
63
+ ? provided.filter((c) => typeof c === "string" && c.trim().length > 0)
64
+ : [];
65
+ return cleaned.length > 0 ? cleaned : DEFAULT_CRITERIA[target];
66
+ }
52
67
  /** Auto-detect the most recent code/reasoning/plan from session messages. */
53
68
  function autoDetectTarget(ctx) {
54
69
  // Use getBranch() - getCurrentSession() does not exist on SessionManager
@@ -227,15 +242,29 @@ export function createVerifyTool() {
227
242
  const startMs = Date.now();
228
243
  const target = p.target ?? "result";
229
244
  const depth = p.depth ?? "standard";
230
- const criteria = p.criteria ?? DEFAULT_CRITERIA[target];
231
- const confidenceThreshold = p.confidenceThreshold ?? 0.5;
232
- const text = p.targetText ?? autoDetectTarget(ctx)?.text;
245
+ const criteria = resolveCriteria(p.criteria, target);
246
+ // A blank selector arrives as 0, and a value outside (0,1] can never
247
+ // gate a 0-1 confidence: both are "not provided", and the documented
248
+ // default is 0.5. The default is documented, so this substitutes -
249
+ // it never refuses the call.
250
+ const rawThreshold = p.confidenceThreshold;
251
+ const confidenceThreshold = typeof rawThreshold === "number" &&
252
+ Number.isFinite(rawThreshold) &&
253
+ rawThreshold > 0 &&
254
+ rawThreshold <= 1
255
+ ? rawThreshold
256
+ : 0.5;
257
+ // A blank targetText is "not provided" too: the documented path
258
+ // auto-detects from recent context. Only when that finds nothing does
259
+ // the tool refuse, and the refusal names auto-detection as what ran.
260
+ const providedText = optionalString(p.targetText);
261
+ const text = providedText ?? autoDetectTarget(ctx)?.text;
233
262
  if (!text) {
234
263
  return {
235
264
  content: [
236
265
  {
237
266
  type: "text",
238
- text: "[verify] Could not auto-detect target text from recent context. Provide targetText explicitly.",
267
+ text: "[verify] Auto-detection ran over recent context and found no target text. Provide targetText explicitly.",
239
268
  },
240
269
  ],
241
270
  details: { passed: false, reason: "no-text" },
@@ -311,6 +340,8 @@ export function createVerifyTool() {
311
340
  suggestions: result.suggestions,
312
341
  target: result.target,
313
342
  checksRun: result.checksRun,
343
+ confidenceThreshold,
344
+ criteria,
314
345
  verificationMs: result.verificationMs,
315
346
  blockedFinalize: !passed,
316
347
  },
@@ -21,6 +21,10 @@ import { consolidatedTopicCritique } from "../../../lib/detection/consolidated-t
21
21
  import { sendTrackedMessage } from "../../../lib/utils/injection-tracker.js";
22
22
  import { BRAID_INJECTED, BRAID_SOURCE } from "../../../lib/constants/injection-details.js";
23
23
  const log = createLogger("topic-drift");
24
+ /** A blank string is "not provided": a client that emits every schema key sends "" for the unused ones. */
25
+ function optionalString(v) {
26
+ return typeof v === "string" && v.trim().length > 0 ? v : undefined;
27
+ }
24
28
  const DRIFT_THRESHOLD = 0.5;
25
29
  // ANCHOR_TURNS_BEFORE_RESET comes from lib/constants/session-thresholds.ts —
26
30
  // the single source of truth.
@@ -263,7 +267,20 @@ export default function topicDriftExtension(pi) {
263
267
  switch (params?.action) {
264
268
  case "check": {
265
269
  const state = getExtensionState(ctx, "topic-drift", createDriftState);
266
- const output = params.output ?? "";
270
+ const output = optionalString(params.output);
271
+ if (output === undefined) {
272
+ // "" would be measured as an empty response and answered
273
+ // "No topic drift" -- a pass for a check that never ran.
274
+ return {
275
+ content: [
276
+ {
277
+ type: "text",
278
+ text: `topic_drift action=check requires a non-empty 'output': the response text to test against the anchored request.`,
279
+ },
280
+ ],
281
+ details: { error: "missing_output", action: "check" },
282
+ };
283
+ }
267
284
  let drifted = false;
268
285
  let similarity = 1.0;
269
286
  let missingAnchors = [];
@@ -313,7 +330,7 @@ export default function topicDriftExtension(pi) {
313
330
  }
314
331
  case "reset": {
315
332
  const state = getExtensionState(ctx, "topic-drift", createDriftState);
316
- const request = params.newRequest ?? state.originalRequest;
333
+ const request = optionalString(params.newRequest) ?? state.originalRequest;
317
334
  resetAnchors(state, request);
318
335
  return {
319
336
  content: [
@@ -21,7 +21,7 @@ const inspectSchema = Type.Object({
21
21
  default: true,
22
22
  })),
23
23
  truncate: Type.Optional(Type.Number({
24
- description: "Max characters (0 = no limit, default 5000); applied after tool/skill exclusion.",
24
+ description: "Max characters before truncation (default 5000); applied after tool/skill exclusion. A blank or non-positive value applies the default.",
25
25
  default: 5000,
26
26
  })),
27
27
  match: Type.Optional(Type.String({
@@ -81,7 +81,13 @@ export function createPromptInspectTool() {
81
81
  execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => {
82
82
  const showTools = params.includeTools ?? true;
83
83
  const showSkills = params.includeSkills ?? true;
84
- const maxLen = params.truncate ?? 5000;
84
+ // Argument validation converts a blank truncate to 0, and the
85
+ // description used to define 0 as "no limit" - so a blank flipped the
86
+ // tool into dumping the whole assembled prompt. A deliberate 0 is
87
+ // indistinguishable from a blank after conversion, so the documented
88
+ // default wins and the old no-limit mode is no longer reachable through
89
+ // this selector (use `match` to read the full prompt).
90
+ const maxLen = typeof params.truncate === "number" && params.truncate > 0 ? params.truncate : 5000;
85
91
  if (!ctx) {
86
92
  return {
87
93
  content: [{ type: "text", text: "Prompt inspect requires a valid context." }],
@@ -158,7 +164,7 @@ export function createPromptInspectTool() {
158
164
  }
159
165
  else {
160
166
  // Apply truncation only when no match filter is active
161
- if (maxLen > 0 && body.length > maxLen) {
167
+ if (body.length > maxLen) {
162
168
  didTruncate = true;
163
169
  body =
164
170
  body.slice(0, maxLen - 80) +
@@ -4,9 +4,10 @@
4
4
  * Discovers pi extension PACKAGES (package.json with a `pi` field)
5
5
  * from the settings `packages` field — never a walk over cwd/siblings.
6
6
  * Sources in pi-core precedence: project (<cwd>/.pi/settings.json)
7
- * then user (~/.pi/agent/settings.json); project scope wins for the
8
- * same identity. Entries: absolute local path, `npm:` (via `npm root
9
- * -g`), or `git:` (best-effort skip), tagged project / user-global.
7
+ * then user (<agentDir>/settings.json); project scope wins for the
8
+ * same identity. Entries: absolute local path, `npm:` (pi's managed
9
+ * install tree first, then the global npm root), or `git:`
10
+ * (best-effort skip), tagged project / user-global.
10
11
  * Best-effort: unreadable or missing packages are silently skipped —
11
12
  * no "failed to resolve" noise in the prompt.
12
13
  */
@@ -34,8 +35,8 @@ export interface TopLevelExtension {
34
35
  *
35
36
  * Settings-file paths:
36
37
  * - project: `<cwd>/.pi/settings.json`
37
- * - user-global: read from `PI_CODING_AGENT_DIR` env override,
38
- * falling back to `~/.pi/agent/settings.json`.
38
+ * - user-global: `<agentDir>/settings.json`, where the agent dir is
39
+ * `PI_CODING_AGENT_DIR` when set, else `~/.pi/agent`.
39
40
  */
40
41
  export declare function discoverTopLevelExtensions(cwd?: string, options?: {
41
42
  projectSettingsPath?: string;
@@ -4,9 +4,10 @@
4
4
  * Discovers pi extension PACKAGES (package.json with a `pi` field)
5
5
  * from the settings `packages` field — never a walk over cwd/siblings.
6
6
  * Sources in pi-core precedence: project (<cwd>/.pi/settings.json)
7
- * then user (~/.pi/agent/settings.json); project scope wins for the
8
- * same identity. Entries: absolute local path, `npm:` (via `npm root
9
- * -g`), or `git:` (best-effort skip), tagged project / user-global.
7
+ * then user (<agentDir>/settings.json); project scope wins for the
8
+ * same identity. Entries: absolute local path, `npm:` (pi's managed
9
+ * install tree first, then the global npm root), or `git:`
10
+ * (best-effort skip), tagged project / user-global.
10
11
  * Best-effort: unreadable or missing packages are silently skipped —
11
12
  * no "failed to resolve" noise in the prompt.
12
13
  */
@@ -102,8 +103,9 @@ function basename(p) {
102
103
  * source is unsupported or cannot be located on disk.
103
104
  *
104
105
  * Supported shapes:
105
- * - `npm:<spec>` (e.g. `npm:pi-web-access`) -- looks in the global
106
- * npm root (`npm root -g`), under each scoped directory.
106
+ * - `npm:<spec>` (e.g. `npm:pi-web-access`) -- looks in pi's
107
+ * managed install tree, then the global npm root, under each
108
+ * scoped directory.
107
109
  * - absolute local path (starts with `/`) -- used as-is.
108
110
  * - relative local path -- resolved relative to `cwd`.
109
111
  */
@@ -111,7 +113,7 @@ function resolveEntryToPackage(source, scope, cwd) {
111
113
  const trimmed = source.trim();
112
114
  if (!trimmed)
113
115
  return null;
114
- // npm:<spec> -- find in global node_modules.
116
+ // npm:<spec> -- find in the managed install tree, then global node_modules.
115
117
  if (trimmed.startsWith("npm:")) {
116
118
  const spec = trimmed.slice("npm:".length).trim();
117
119
  const at = spec.lastIndexOf("@");
@@ -158,35 +160,69 @@ function expandHome(p) {
158
160
  return p;
159
161
  }
160
162
  /**
161
- * Locate a globally-installed npm package by name. Walks the
162
- * scope directories under the global npm root (`npm root -g`).
163
- * Optional `version` filters to a directory whose `package.json`
164
- * version matches; if absent, the first matching directory wins.
163
+ * Resolve pi's agent directory. `PI_CODING_AGENT_DIR` relocates the whole
164
+ * agent home when set and non-empty; otherwise the default is `~/.pi/agent`.
165
+ * Both the user-global settings file and the managed npm install tree live
166
+ * under this one directory, so they are resolved from this one function.
167
+ */
168
+ function resolveAgentDir() {
169
+ const override = process.env.PI_CODING_AGENT_DIR?.trim();
170
+ if (override)
171
+ return expandHome(override);
172
+ return join(process.env.HOME ?? "~", ".pi", "agent");
173
+ }
174
+ /**
175
+ * Locate an installed npm package by name, searching pi's managed install
176
+ * tree before the global npm root. Managed first because that is where pi
177
+ * installs a settings-declared `npm:` entry (`<agentDir>/npm/node_modules`)
178
+ * and it consults a legacy global install only when the managed copy is
179
+ * absent -- so the managed copy is the one pi actually loads. The global
180
+ * root stays as that same fallback, for packages installed by hand.
165
181
  *
166
- * Returns the absolute directory path, or null if not found.
182
+ * Optional `version` filters to a directory whose `package.json` version
183
+ * matches; if absent, the first matching directory wins. Returns the
184
+ * absolute directory path, or null if not found in any root.
167
185
  */
168
186
  function findNpmPackageDir(name, version) {
187
+ for (const root of getNpmSearchRoots()) {
188
+ const dir = findPackageInNpmRoot(root, name, version);
189
+ if (dir)
190
+ return dir;
191
+ }
192
+ return null;
193
+ }
194
+ /** The npm roots searched for an `npm:` entry, in precedence order. */
195
+ function getNpmSearchRoots() {
196
+ const roots = [join(resolveAgentDir(), "npm", "node_modules")];
169
197
  const globalRoot = getGlobalNpmRoot();
170
- if (!globalRoot)
171
- return null;
172
- if (!existsSync(globalRoot))
198
+ if (globalRoot)
199
+ roots.push(globalRoot);
200
+ return roots;
201
+ }
202
+ /**
203
+ * Find the package directory for `name` inside one npm root.
204
+ *
205
+ * Scoped package: @scope/name -> look directly under `<root>/@scope/name`.
206
+ * Unscoped: scan the root's own directories for a package.json whose `name`
207
+ * matches -- npm installs both flat and nested layouts. A directory with no
208
+ * readable package.json is skipped, never fatal.
209
+ */
210
+ function findPackageInNpmRoot(root, name, version) {
211
+ if (!existsSync(root))
173
212
  return null;
174
- // Scoped package: @scope/name -> look under globalRoot/@scope/name.
175
213
  if (name.startsWith("@")) {
176
- const dir = join(globalRoot, name);
214
+ const dir = join(root, name);
177
215
  return packageDirMatches(dir, version) ? dir : null;
178
216
  }
179
- // Unscoped: scan globalRoot itself for a directory whose
180
- // package.json `name` matches. npm installs both flat and nested layouts.
181
217
  let entries;
182
218
  try {
183
- entries = readdirSync(globalRoot);
219
+ entries = readdirSync(root);
184
220
  }
185
221
  catch {
186
222
  return null;
187
223
  }
188
224
  for (const entry of entries) {
189
- const dir = join(globalRoot, entry);
225
+ const dir = join(root, entry);
190
226
  let isDir;
191
227
  try {
192
228
  isDir = statSync(dir).isDirectory();
@@ -228,10 +264,11 @@ function packageDirMatches(dir, expectedVersion, expectedName) {
228
264
  }
229
265
  /**
230
266
  * Resolve the global npm root via `npm root -g`. Returns null if
231
- * the command fails or produces no output. Cached after first
232
- * successful call so the (slow) `npm root -g` invocation runs at
233
- * most once per process -- the value never changes inside one
234
- * pi session.
267
+ * the command fails or produces no output. This is the fallback root
268
+ * only -- pi's managed install tree is searched first (see
269
+ * `findNpmPackageDir`). Cached after first successful call so the
270
+ * (slow) `npm root -g` invocation runs at most once per process --
271
+ * the value never changes inside one pi session.
235
272
  *
236
273
  * Implemented as an IIFE-wrapped closure so the cache `let`
237
274
  * stays function-scoped (the project's no-module-level-let
@@ -267,14 +304,12 @@ const getGlobalNpmRoot = (() => {
267
304
  *
268
305
  * Settings-file paths:
269
306
  * - project: `<cwd>/.pi/settings.json`
270
- * - user-global: read from `PI_CODING_AGENT_DIR` env override,
271
- * falling back to `~/.pi/agent/settings.json`.
307
+ * - user-global: `<agentDir>/settings.json`, where the agent dir is
308
+ * `PI_CODING_AGENT_DIR` when set, else `~/.pi/agent`.
272
309
  */
273
310
  export function discoverTopLevelExtensions(cwd = process.cwd(), options) {
274
311
  const projectPath = options?.projectSettingsPath ?? join(cwd, ".pi", "settings.json");
275
- const userPath = options?.userSettingsPath ??
276
- process.env.PI_CODING_AGENT_DIR ??
277
- join(process.env.HOME ?? "~", ".pi", "agent", "settings.json");
312
+ const userPath = options?.userSettingsPath ?? join(resolveAgentDir(), "settings.json");
278
313
  const seen = new Set();
279
314
  const out = [];
280
315
  const add = (pkg, source) => {
@@ -1,5 +1,5 @@
1
1
  /**
2
- * register-tool-result-formatting — Structured Output Catalyst (MI-3)
2
+ * register-tool-result-formatting — Structured Output Catalyst
3
3
  *
4
4
  * Wraps tool outputs for read/grep/find/ls in a consistent structured format
5
5
  * to improve transformer processing. Uses the tool_result event's middleware
@@ -1,5 +1,5 @@
1
1
  /**
2
- * register-tool-result-formatting — Structured Output Catalyst (MI-3)
2
+ * register-tool-result-formatting — Structured Output Catalyst
3
3
  *
4
4
  * Wraps tool outputs for read/grep/find/ls in a consistent structured format
5
5
  * to improve transformer processing. Uses the tool_result event's middleware
@@ -146,7 +146,7 @@ export async function dispatchTurnEndLoop(pi, event, ctx) {
146
146
  }
147
147
  const memoryUpdated = actualTools.some((t) => ["memory_store", "memory"].includes(t));
148
148
  // Truth-seeking trigger: verify_claim/conflict_qa usage
149
- // MI-2: When the agent uses verification tools, briefly surface TRUTH-SEEKING
149
+ // When the agent uses verification tools, briefly surface TRUTH-SEEKING
150
150
  // mode explicitly, confirming the correct epistemic stance.
151
151
  const truthTools = actualTools.filter((t) => ["verify_claim", "conflict_qa"].includes(t));
152
152
  if (truthTools.length > 0) {
@@ -25,7 +25,7 @@
25
25
  * probe here: it inspects session context state, and this claim class is
26
26
  * channel liveness/delivery/progress, not context state.
27
27
  */
28
- export declare const SELF_STATE_PROBE_TOOLS: readonly ["session_health", "health_maintenance", "v2raytun_status", "telegram_send"];
28
+ export declare const SELF_STATE_PROBE_TOOLS: readonly ["session_health", "health_maintenance", "tunnel_status", "v2raytun_status", "telegram_send"];
29
29
  /**
30
30
  * Prompt-section cap for listed claims, with an explicit suppressed-count
31
31
  * line beyond it (same never-silent-truncation pattern as task-evidence.ts).