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.
- package/CONTRIBUTING.md +27 -3
- package/README.md +13 -13
- package/TOOLS.md +27 -3
- package/build-info.json +9 -0
- package/dist/extensions/cognitive/metacognition/handlers/claim-verification.js +7 -1
- package/dist/extensions/cognitive/metacognition/handlers/finalize.js +20 -0
- package/dist/extensions/cognitive/metacognition/handlers/hypothesize.d.ts +9 -0
- package/dist/extensions/cognitive/metacognition/handlers/hypothesize.js +13 -1
- package/dist/extensions/cognitive/metacognition/handlers/verify.js +35 -4
- package/dist/extensions/cognitive/topic-drift/index.js +19 -2
- package/dist/extensions/core/prompt-builder/inspect.js +9 -3
- package/dist/extensions/core/prompt-builder/top-level-extensions.d.ts +6 -5
- package/dist/extensions/core/prompt-builder/top-level-extensions.js +64 -29
- package/dist/extensions/enforcement/handlers/register-tool-result-formatting.d.ts +1 -1
- package/dist/extensions/enforcement/handlers/register-tool-result-formatting.js +1 -1
- package/dist/extensions/enforcement/handlers/turn-end-handler.js +1 -1
- package/dist/extensions/enforcement/self-state-claims.d.ts +1 -1
- package/dist/extensions/enforcement/self-state-claims.js +3 -2
- package/dist/extensions/manifest.js +2 -2
- package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.d.ts +22 -5
- package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.js +43 -11
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +174 -50
- package/dist/extensions/memory/context-manager/handlers/tools/context-inspect.js +7 -1
- package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.js +4 -1
- package/dist/extensions/memory/memory-agent-bridge/explore-paths.d.ts +2 -24
- package/dist/extensions/memory/memory-agent-bridge/explore-paths.js +33 -2
- package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.js +16 -0
- package/dist/extensions/memory/memory-agent-bridge/memory-tool.js +21 -9
- package/dist/extensions/memory/scratchpad/format.js +8 -2
- package/dist/extensions/memory/scratchpad/index.js +11 -2
- package/dist/extensions/memory/session-recall/index.js +19 -6
- package/dist/extensions/memory/three-memory-stores/episodes.d.ts +1 -1
- package/dist/extensions/memory/three-memory-stores/episodes.js +2 -2
- package/dist/extensions/orchestrator/index.js +73 -8
- package/dist/extensions/scheduling/timer/index.js +9 -1
- package/dist/extensions/self/error-tracking/index.js +8 -1
- package/dist/extensions/self/health-maintenance/handlers/session-health-tool.js +9 -2
- package/dist/extensions/self/health-maintenance/index.js +112 -9
- package/dist/lib/config/braid-settings.d.ts +21 -0
- package/dist/lib/config/braid-settings.js +36 -0
- package/dist/lib/constants/session-thresholds.d.ts +2 -3
- package/dist/lib/constants/session-thresholds.js +2 -3
- package/dist/lib/enforcement/turn-dedup.d.ts +2 -2
- package/dist/lib/enforcement/turn-dedup.js +2 -2
- package/dist/lib/harness/index.d.ts +1 -1
- package/dist/lib/harness/index.js +1 -1
- package/dist/lib/harness/types.d.ts +1 -1
- package/dist/lib/harness/types.js +1 -1
- package/dist/lib/orchestrator/index.d.ts +2 -2
- package/dist/lib/orchestrator/index.js +1 -1
- package/dist/lib/orchestrator/workers.d.ts +184 -2
- package/dist/lib/orchestrator/workers.js +521 -6
- package/dist/lib/utils/injection-tracker.js +1 -1
- package/docs/CONTEXT-POLICY.md +13 -5
- package/docs/LOCAL_DEV.md +31 -5
- package/docs/ROADMAP.md +10 -7
- package/docs/SETUP.md +3 -2
- package/package.json +11 -8
- package/skills/braid-reference/SKILL.md +23 -23
- package/skills/release-pipeline/SKILL.md +46 -37
- package/skills/subagent-orchestration/SKILL.md +51 -1
- package/src/extensions/cognitive/metacognition/handlers/claim-verification.ts +8 -1
- package/src/extensions/cognitive/metacognition/handlers/finalize.ts +21 -0
- package/src/extensions/cognitive/metacognition/handlers/hypothesize.ts +14 -1
- package/src/extensions/cognitive/metacognition/handlers/verify.ts +39 -5
- package/src/extensions/cognitive/topic-drift/index.ts +20 -2
- package/src/extensions/core/prompt-builder/AGENTS.md +1 -1
- package/src/extensions/core/prompt-builder/inspect.ts +10 -3
- package/src/extensions/core/prompt-builder/top-level-extensions.ts +68 -29
- package/src/extensions/enforcement/AGENTS.md +25 -19
- package/src/extensions/enforcement/handlers/register-tool-result-formatting.ts +1 -1
- package/src/extensions/enforcement/handlers/turn-end-handler.ts +1 -1
- package/src/extensions/enforcement/self-state-claims.ts +3 -2
- package/src/extensions/heartbeat/heartbeat-scheduler/AGENTS.md +6 -3
- package/src/extensions/manifest.ts +2 -2
- package/src/extensions/memory/AGENTS.md +13 -5
- package/src/extensions/memory/context-manager/handlers/tool-batch-boundary.ts +45 -11
- package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +202 -60
- package/src/extensions/memory/context-manager/handlers/tools/context-inspect.ts +8 -1
- package/src/extensions/memory/context-manager/handlers/tools/context-navigate.ts +4 -1
- package/src/extensions/memory/memory-agent-bridge/explore-paths.ts +37 -3
- package/src/extensions/memory/memory-agent-bridge/memory-store-tool.ts +16 -0
- package/src/extensions/memory/memory-agent-bridge/memory-tool.ts +22 -9
- package/src/extensions/memory/scratchpad/format.ts +8 -2
- package/src/extensions/memory/scratchpad/index.ts +12 -2
- package/src/extensions/memory/session-recall/index.ts +20 -8
- package/src/extensions/memory/three-memory-stores/episodes.ts +2 -2
- package/src/extensions/orchestrator/index.ts +100 -11
- package/src/extensions/scheduling/timer/AGENTS.md +7 -0
- package/src/extensions/scheduling/timer/index.ts +10 -1
- package/src/extensions/self/error-tracking/index.ts +9 -1
- package/src/extensions/self/health-maintenance/handlers/session-health-tool.ts +10 -2
- package/src/extensions/self/health-maintenance/index.ts +143 -14
- package/src/extensions/self/watchdog/AGENTS.md +1 -0
- package/src/lib/AGENTS.md +21 -21
- package/src/lib/config/braid-settings.ts +74 -0
- package/src/lib/constants/session-thresholds.ts +2 -3
- package/src/lib/enforcement/turn-dedup.ts +2 -2
- package/src/lib/harness/AGENTS.md +1 -1
- package/src/lib/harness/index.ts +1 -1
- package/src/lib/harness/types.ts +1 -1
- package/src/lib/orchestrator/index.ts +26 -0
- package/src/lib/orchestrator/workers.ts +705 -7
- package/src/lib/utils/AGENTS.md +1 -1
- 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,
|
|
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
|
-
|
|
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
|
[](https://opensource.org/licenses/MIT)
|
|
6
6
|
[](https://www.typescriptlang.org/)
|
|
7
|
-
[](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 [
|
|
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
|
-
**[
|
|
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
|
|
237
|
-
|
|
|
238
|
-
| [`docs/BEGINNERS.md`](docs/BEGINNERS.md)
|
|
239
|
-
| [`docs/SETUP.md`](docs/SETUP.md)
|
|
240
|
-
| [`docs/ROADMAP.md`](docs/ROADMAP.md)
|
|
241
|
-
| [`README.md`](README.md)
|
|
242
|
-
| [`AGENTS.md`](AGENTS.md)
|
|
243
|
-
| [`CONTRIBUTING.md`](CONTRIBUTING.md)
|
|
244
|
-
| [`docs/HISTORY.md`](docs/HISTORY.md)
|
|
245
|
-
| [
|
|
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:
|
|
38
|
-
with priority: runtime
|
|
39
|
-
|
|
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)
|
package/build-info.json
ADDED
|
@@ -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
|
-
|
|
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,
|
|
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
|
|
231
|
-
|
|
232
|
-
|
|
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]
|
|
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
|
|
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
|
-
|
|
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 (
|
|
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 (
|
|
8
|
-
* same identity. Entries: absolute local path, `npm:` (
|
|
9
|
-
*
|
|
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:
|
|
38
|
-
*
|
|
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 (
|
|
8
|
-
* same identity. Entries: absolute local path, `npm:` (
|
|
9
|
-
*
|
|
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
|
|
106
|
-
*
|
|
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
|
-
*
|
|
162
|
-
*
|
|
163
|
-
*
|
|
164
|
-
*
|
|
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
|
-
*
|
|
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 (
|
|
171
|
-
|
|
172
|
-
|
|
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(
|
|
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(
|
|
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(
|
|
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.
|
|
232
|
-
*
|
|
233
|
-
*
|
|
234
|
-
*
|
|
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:
|
|
271
|
-
*
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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).
|