pi-braid 0.40.1 → 0.40.2

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 (84) 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/hypothesize.d.ts +9 -0
  6. package/dist/extensions/cognitive/metacognition/handlers/hypothesize.js +13 -1
  7. package/dist/extensions/cognitive/metacognition/handlers/verify.js +35 -4
  8. package/dist/extensions/core/prompt-builder/inspect.js +9 -3
  9. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.d.ts +1 -1
  10. package/dist/extensions/enforcement/handlers/register-tool-result-formatting.js +1 -1
  11. package/dist/extensions/enforcement/handlers/turn-end-handler.js +1 -1
  12. package/dist/extensions/enforcement/self-state-claims.d.ts +1 -1
  13. package/dist/extensions/enforcement/self-state-claims.js +3 -2
  14. package/dist/extensions/manifest.js +2 -2
  15. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.d.ts +22 -5
  16. package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.js +43 -11
  17. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +174 -50
  18. package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.js +4 -1
  19. package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.js +16 -0
  20. package/dist/extensions/memory/memory-agent-bridge/memory-tool.js +21 -9
  21. package/dist/extensions/memory/scratchpad/format.js +8 -2
  22. package/dist/extensions/memory/scratchpad/index.js +11 -2
  23. package/dist/extensions/memory/session-recall/index.js +19 -6
  24. package/dist/extensions/memory/three-memory-stores/episodes.d.ts +1 -1
  25. package/dist/extensions/memory/three-memory-stores/episodes.js +2 -2
  26. package/dist/extensions/orchestrator/index.js +73 -8
  27. package/dist/extensions/self/health-maintenance/index.js +112 -9
  28. package/dist/lib/config/braid-settings.d.ts +21 -0
  29. package/dist/lib/config/braid-settings.js +36 -0
  30. package/dist/lib/constants/session-thresholds.d.ts +2 -3
  31. package/dist/lib/constants/session-thresholds.js +2 -3
  32. package/dist/lib/enforcement/turn-dedup.d.ts +2 -2
  33. package/dist/lib/enforcement/turn-dedup.js +2 -2
  34. package/dist/lib/harness/index.d.ts +1 -1
  35. package/dist/lib/harness/index.js +1 -1
  36. package/dist/lib/harness/types.d.ts +1 -1
  37. package/dist/lib/harness/types.js +1 -1
  38. package/dist/lib/orchestrator/index.d.ts +2 -2
  39. package/dist/lib/orchestrator/index.js +1 -1
  40. package/dist/lib/orchestrator/workers.d.ts +184 -2
  41. package/dist/lib/orchestrator/workers.js +521 -6
  42. package/dist/lib/utils/injection-tracker.js +1 -1
  43. package/docs/CONTEXT-POLICY.md +13 -5
  44. package/docs/LOCAL_DEV.md +31 -5
  45. package/docs/ROADMAP.md +10 -7
  46. package/docs/SETUP.md +3 -2
  47. package/package.json +11 -8
  48. package/skills/braid-reference/SKILL.md +23 -23
  49. package/skills/release-pipeline/SKILL.md +46 -37
  50. package/skills/subagent-orchestration/SKILL.md +51 -1
  51. package/src/extensions/cognitive/metacognition/handlers/hypothesize.ts +14 -1
  52. package/src/extensions/cognitive/metacognition/handlers/verify.ts +39 -5
  53. package/src/extensions/core/prompt-builder/inspect.ts +10 -3
  54. package/src/extensions/enforcement/AGENTS.md +25 -19
  55. package/src/extensions/enforcement/handlers/register-tool-result-formatting.ts +1 -1
  56. package/src/extensions/enforcement/handlers/turn-end-handler.ts +1 -1
  57. package/src/extensions/enforcement/self-state-claims.ts +3 -2
  58. package/src/extensions/heartbeat/heartbeat-scheduler/AGENTS.md +6 -3
  59. package/src/extensions/manifest.ts +2 -2
  60. package/src/extensions/memory/AGENTS.md +13 -5
  61. package/src/extensions/memory/context-manager/handlers/tool-batch-boundary.ts +45 -11
  62. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +202 -60
  63. package/src/extensions/memory/context-manager/handlers/tools/context-navigate.ts +4 -1
  64. package/src/extensions/memory/memory-agent-bridge/memory-store-tool.ts +16 -0
  65. package/src/extensions/memory/memory-agent-bridge/memory-tool.ts +22 -9
  66. package/src/extensions/memory/scratchpad/format.ts +8 -2
  67. package/src/extensions/memory/scratchpad/index.ts +12 -2
  68. package/src/extensions/memory/session-recall/index.ts +20 -8
  69. package/src/extensions/memory/three-memory-stores/episodes.ts +2 -2
  70. package/src/extensions/orchestrator/index.ts +100 -11
  71. package/src/extensions/scheduling/timer/AGENTS.md +7 -0
  72. package/src/extensions/self/health-maintenance/index.ts +143 -14
  73. package/src/extensions/self/watchdog/AGENTS.md +1 -0
  74. package/src/lib/AGENTS.md +21 -21
  75. package/src/lib/config/braid-settings.ts +74 -0
  76. package/src/lib/constants/session-thresholds.ts +2 -3
  77. package/src/lib/enforcement/turn-dedup.ts +2 -2
  78. package/src/lib/harness/AGENTS.md +1 -1
  79. package/src/lib/harness/index.ts +1 -1
  80. package/src/lib/harness/types.ts +1 -1
  81. package/src/lib/orchestrator/index.ts +26 -0
  82. package/src/lib/orchestrator/workers.ts +705 -7
  83. package/src/lib/utils/AGENTS.md +1 -1
  84. 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.2",
4
+ "sha": "752d2e6e9b45037a8ebcc17f3d6f90c905b2c71c",
5
+ "shaShort": "752d2e6",
6
+ "branch": "detached",
7
+ "dirty": false,
8
+ "packedAt": "2026-10-19T11:29:08.778Z"
9
+ }
@@ -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,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) +
@@ -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).
@@ -28,6 +28,7 @@
28
28
  export const SELF_STATE_PROBE_TOOLS = [
29
29
  "session_health",
30
30
  "health_maintenance",
31
+ "tunnel_status",
31
32
  "v2raytun_status",
32
33
  "telegram_send",
33
34
  ];
@@ -90,7 +91,7 @@ export const SELF_STATE_PATTERNS = [
90
91
  */
91
92
  const NEGATION_HEDGE = /\b(?:not|no|never|neither|nor|without|cannot|can't|won't|wouldn't|couldn't|shouldn't|isn't|aren't|wasn't|weren't|doesn't|didn't|stopped|stopping|offline|unavailable|unreachable|unverified|uncertain|unconfirmed|unknown|unsure|may|might|could|possibly|probably|presumably|perhaps|unlikely|doubtful|down|dead|crashed|died|flaky)\b/i;
92
93
  /** Probe-tool names that, named in the claim clause itself, exempt it: citing the check ("I ran session_health: healthy") is probe awareness, not an ungrounded assertion. */
93
- const PROBE_NAME = /(?:session_health|health_maintenance|v2raytun_status|telegram_send|telegram_poller)/i;
94
+ const PROBE_NAME = /(?:session_health|health_maintenance|tunnel_status|v2raytun_status|telegram_send|telegram_poller)/i;
94
95
  /**
95
96
  * Does the evidence window contain a probe call? toolsUsed matches by exact
96
97
  * tool name; evidence/log lines match by substring (tool names render inline,
@@ -161,7 +162,7 @@ export function renderSelfStateClaimsSection(claims) {
161
162
  if (claims.length > listed.length) {
162
163
  lines.push(`(${claims.length - listed.length} more matched claim(s) suppressed, cap ${MAX_SELF_STATE_CLAIMS_IN_PROMPT})`);
163
164
  }
164
- lines.push("", "These claims cannot be verified by build or test evidence: they need a decisive in-session probe call (session_health, health_maintenance, v2raytun_status, telegram_send), and the evidence window above shows none.", 'Rule: flag each listed claim as an issue (category "claim") unless TASK EVIDENCE, TOOL EXECUTION LOG, or chunk summaries above show a probe call supporting it. Hedged or negative self-state ("poller not running", "reachability unverified") is honest and must NOT be flagged.');
165
+ lines.push("", "These claims cannot be verified by build or test evidence: they need a decisive in-session probe call (session_health, health_maintenance, tunnel_status, v2raytun_status, telegram_send), and the evidence window above shows none.", 'Rule: flag each listed claim as an issue (category "claim") unless TASK EVIDENCE, TOOL EXECUTION LOG, or chunk summaries above show a probe call supporting it. Hedged or negative self-state ("poller not running", "reachability unverified") is honest and must NOT be flagged.');
165
166
  return lines.join("\n");
166
167
  }
167
168
  //# sourceMappingURL=self-state-claims.js.map
@@ -126,7 +126,7 @@ export const MANIFEST = [
126
126
  id: "session-recall",
127
127
  fn: sessionRecallFn,
128
128
  dependencies: ["three-memory-stores"],
129
- desc: "Session recall tools (session_search, session_query)",
129
+ desc: "Session recall tool (session)",
130
130
  module: "memory",
131
131
  },
132
132
  {
@@ -220,7 +220,7 @@ export const MANIFEST = [
220
220
  fn: errorCaptureFn,
221
221
  disabledByDefault: true,
222
222
  dependencies: ["agent-environment"],
223
- desc: "Error logging tools: error_list, error_get",
223
+ desc: "Error logging tool (error)",
224
224
  },
225
225
  ];
226
226
  const _byId = new Map(MANIFEST.map((e) => [e.id, e]));
@@ -19,6 +19,16 @@
19
19
  * at consumption (the armer may have read the branch before the batch's later
20
20
  * results landed).
21
21
  *
22
+ * A supplied index can land on a non-message entry (`label` from
23
+ * `context_navigate action=tag`, `custom`/`custom_message`, a model or
24
+ * thinking-level change, a context edit, a compaction): those entries carry no
25
+ * provider message, so the kept slice's opening message is the first `message`
26
+ * entry at or after the index. The leading-result check resolves that entry
27
+ * before judging the slice; judging the index itself let a tag placed between
28
+ * an assistant's tool call and its result pass, and the kept slice then opened
29
+ * with a bare tool result ("No tool call found for function call output with
30
+ * call_id ..." from Responses-style endpoints).
31
+ *
22
32
  * The readers take raw session entries (`readonly unknown[]`) because that is
23
33
  * what a live branch is at the boundaries; the shape is narrowed here rather
24
34
  * than asserted at every call site.
@@ -27,21 +37,28 @@
27
37
  export declare const MIN_KEPT_ENTRIES = 1;
28
38
  /**
29
39
  * The structurally invalid shape of a kept slice [candidateIndex..end]:
30
- * either it begins with a tool result (its call fell outside the slice), or it
31
- * contains an assistant whose tool_calls are not fully answered inside it.
32
- * Returns null for a valid slice. Exported for tests and audit surfaces.
40
+ * either its first message is a tool result (its call fell outside the slice),
41
+ * or it contains an assistant whose tool_calls are not fully answered inside
42
+ * it. Non-message entries between the candidate and the first message are
43
+ * stepped over: they are not provider messages, so they neither open the
44
+ * slice nor hide a bare result behind them. Returns null for a valid slice.
45
+ * Exported for tests and audit surfaces.
33
46
  */
34
47
  export declare function findBoundaryViolation(entries: readonly unknown[], candidateIndex: number): {
35
48
  kind: "leading-tool-result" | "unanswered-tool-calls";
36
49
  entryId?: string;
50
+ /** Index of the offending tool-result entry (leading-tool-result). */
51
+ resultIndex?: number;
37
52
  /** Index of the offending assistant entry (unanswered-tool-calls). */
38
53
  assistantIndex?: number;
39
54
  } | null;
40
55
  /**
41
56
  * Snap a candidate first-kept index so the kept slice [result..end] cannot
42
57
  * split a tool batch:
43
- * - a candidate landing mid-batch snaps FORWARD to the first entry after
44
- * the batch's last tool result (parallel calls are one batch of N results);
58
+ * - a candidate landing mid-batch - including on a non-message entry whose
59
+ * first following message is mid-batch - snaps FORWARD to the first entry
60
+ * after the batch's last tool result (parallel calls are one batch of N
61
+ * results);
45
62
  * - when that would keep less than `MIN_KEPT_ENTRIES`, it snaps BACKWARD to
46
63
  * the batch's assistant message instead, keeping the whole batch live;
47
64
  * - a leading result whose call is no longer in the branch (summarized away)
@@ -19,6 +19,16 @@
19
19
  * at consumption (the armer may have read the branch before the batch's later
20
20
  * results landed).
21
21
  *
22
+ * A supplied index can land on a non-message entry (`label` from
23
+ * `context_navigate action=tag`, `custom`/`custom_message`, a model or
24
+ * thinking-level change, a context edit, a compaction): those entries carry no
25
+ * provider message, so the kept slice's opening message is the first `message`
26
+ * entry at or after the index. The leading-result check resolves that entry
27
+ * before judging the slice; judging the index itself let a tag placed between
28
+ * an assistant's tool call and its result pass, and the kept slice then opened
29
+ * with a bare tool result ("No tool call found for function call output with
30
+ * call_id ..." from Responses-style endpoints).
31
+ *
22
32
  * The readers take raw session entries (`readonly unknown[]`) because that is
23
33
  * what a live branch is at the boundaries; the shape is narrowed here rather
24
34
  * than asserted at every call site.
@@ -63,20 +73,39 @@ function toolCallIdsOf(entry) {
63
73
  }
64
74
  return ids;
65
75
  }
76
+ /**
77
+ * Index of the first message entry at or after `fromIndex`; non-message
78
+ * session entries carry no provider message and are stepped over. Equals
79
+ * `entries.length` when no message remains.
80
+ */
81
+ function firstMessageIndex(entries, fromIndex) {
82
+ let i = fromIndex;
83
+ while (i < entries.length && entryOf(entries[i])?.type !== "message")
84
+ i++;
85
+ return i;
86
+ }
66
87
  /**
67
88
  * The structurally invalid shape of a kept slice [candidateIndex..end]:
68
- * either it begins with a tool result (its call fell outside the slice), or it
69
- * contains an assistant whose tool_calls are not fully answered inside it.
70
- * Returns null for a valid slice. Exported for tests and audit surfaces.
89
+ * either its first message is a tool result (its call fell outside the slice),
90
+ * or it contains an assistant whose tool_calls are not fully answered inside
91
+ * it. Non-message entries between the candidate and the first message are
92
+ * stepped over: they are not provider messages, so they neither open the
93
+ * slice nor hide a bare result behind them. Returns null for a valid slice.
94
+ * Exported for tests and audit surfaces.
71
95
  */
72
96
  export function findBoundaryViolation(entries, candidateIndex) {
73
97
  if (!Array.isArray(entries) || candidateIndex < 0 || candidateIndex >= entries.length) {
74
98
  return null;
75
99
  }
76
- if (isToolResultEntry(entryOf(entries[candidateIndex]))) {
77
- return { kind: "leading-tool-result", entryId: entryOf(entries[candidateIndex])?.id };
100
+ const firstMessage = firstMessageIndex(entries, candidateIndex);
101
+ if (isToolResultEntry(entryOf(entries[firstMessage]))) {
102
+ return {
103
+ kind: "leading-tool-result",
104
+ entryId: entryOf(entries[firstMessage])?.id,
105
+ resultIndex: firstMessage,
106
+ };
78
107
  }
79
- for (let i = candidateIndex; i < entries.length; i++) {
108
+ for (let i = firstMessage; i < entries.length; i++) {
80
109
  for (const id of toolCallIdsOf(entryOf(entries[i]))) {
81
110
  let answered = false;
82
111
  for (let j = i + 1; j < entries.length; j++) {
@@ -133,8 +162,10 @@ function firstNonToolResultIndex(entries, fromIndex) {
133
162
  /**
134
163
  * Snap a candidate first-kept index so the kept slice [result..end] cannot
135
164
  * split a tool batch:
136
- * - a candidate landing mid-batch snaps FORWARD to the first entry after
137
- * the batch's last tool result (parallel calls are one batch of N results);
165
+ * - a candidate landing mid-batch - including on a non-message entry whose
166
+ * first following message is mid-batch - snaps FORWARD to the first entry
167
+ * after the batch's last tool result (parallel calls are one batch of N
168
+ * results);
138
169
  * - when that would keep less than `MIN_KEPT_ENTRIES`, it snaps BACKWARD to
139
170
  * the batch's assistant message instead, keeping the whole batch live;
140
171
  * - a leading result whose call is no longer in the branch (summarized away)
@@ -153,12 +184,13 @@ export function snapBoundaryOutsideToolBatch(entries, candidateIndex) {
153
184
  if (!violation)
154
185
  return index;
155
186
  if (violation.kind === "leading-tool-result") {
156
- const owner = findOwningAssistant(entries, index);
187
+ const resultIndex = violation.resultIndex ?? index;
188
+ const owner = findOwningAssistant(entries, resultIndex);
157
189
  if (owner < 0) {
158
190
  // The call is outside the branch: the only valid repair is dropping
159
191
  // the orphaned results.
160
- const after = firstNonToolResultIndex(entries, index);
161
- if (after > index && entries.length - after >= MIN_KEPT_ENTRIES) {
192
+ const after = firstNonToolResultIndex(entries, resultIndex);
193
+ if (after > resultIndex && entries.length - after >= MIN_KEPT_ENTRIES) {
162
194
  index = after;
163
195
  continue;
164
196
  }