pi-braid 0.42.0 → 0.42.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +1006 -0
- package/build-info.json +4 -4
- package/dist/extensions/cognitive/metacognition/handlers/think.js +9 -0
- package/dist/extensions/core/skills-tool/index.js +47 -26
- package/dist/extensions/manifest.js +6 -0
- package/dist/extensions/self/path-miss/detect.d.ts +30 -0
- package/dist/extensions/self/path-miss/detect.js +67 -0
- package/dist/extensions/self/path-miss/index.d.ts +33 -0
- package/dist/extensions/self/path-miss/index.js +118 -0
- package/dist/lib/core/event-names.d.ts +1 -0
- package/dist/lib/core/event-names.js +1 -0
- package/dist/lib/utils/argument-report.d.ts +41 -0
- package/dist/lib/utils/argument-report.js +95 -0
- package/package.json +4 -3
- package/src/extensions/cognitive/metacognition/handlers/think.ts +9 -0
- package/src/extensions/core/skills-tool/index.ts +60 -37
- package/src/extensions/manifest.ts +6 -0
- package/src/extensions/self/AGENTS.md +2 -1
- package/src/extensions/self/path-miss/AGENTS.md +39 -0
- package/src/extensions/self/path-miss/detect.ts +78 -0
- package/src/extensions/self/path-miss/index.ts +135 -0
- package/src/lib/core/event-names.ts +1 -0
- package/src/lib/utils/AGENTS.md +1 -0
- package/src/lib/utils/argument-report.ts +105 -0
package/build-info.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.42.
|
|
4
|
-
"sha": "
|
|
5
|
-
"shaShort": "
|
|
3
|
+
"version": "0.42.1",
|
|
4
|
+
"sha": "b16fdbb3b1f434c2807942412b899a9ca674cfe2",
|
|
5
|
+
"shaShort": "b16fdbb",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-10-
|
|
8
|
+
"packedAt": "2026-10-27T11:16:21.651Z"
|
|
9
9
|
}
|
|
@@ -5,6 +5,7 @@ import { Type } from "typebox";
|
|
|
5
5
|
import { resolveUtilityModel, tryModelChain } from "../../../../lib/ai/model-resolver.js";
|
|
6
6
|
import { estimateComplexity, complexityToDepth, getBudget, getCalibrationStats, computeCalibrationError, THINK_TYPES, DEFAULT_THINK_TYPE, DEPTH_LEVELS, } from "./think-budget.js";
|
|
7
7
|
import { criticGate } from "../../../../lib/ai/critic-gate.js";
|
|
8
|
+
import { checkArgumentValues } from "../../../../lib/utils/argument-report.js";
|
|
8
9
|
import { getExtensionState } from "../../../../lib/state/extension-state.js";
|
|
9
10
|
import { createLogger } from "../../../../lib/core/logger.js";
|
|
10
11
|
const log = createLogger("metacognition");
|
|
@@ -128,6 +129,14 @@ export function createThinkTool() {
|
|
|
128
129
|
description: "Think deeply with structured reasoning before making high-stakes decisions.",
|
|
129
130
|
promptSnippet: "Think deeply with structured reasoning before decisions",
|
|
130
131
|
parameters: thinkSchema,
|
|
132
|
+
// pi validates arguments before `execute` is reached, and its own refusal
|
|
133
|
+
// for a guessed enum or a missing field names neither. This hook runs
|
|
134
|
+
// first, inside the same guarded block, and refuses with the values the
|
|
135
|
+
// schema above already declares.
|
|
136
|
+
prepareArguments: (args) => {
|
|
137
|
+
checkArgumentValues("think", thinkSchema, args);
|
|
138
|
+
return args;
|
|
139
|
+
},
|
|
131
140
|
execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
|
|
132
141
|
const observation = params.observation ?? params.decision ?? "";
|
|
133
142
|
const decision = params.decision ?? "";
|
|
@@ -38,6 +38,7 @@ import { registerAutoInject, updateSkillCache, getSkillStats, getDurableSkillSta
|
|
|
38
38
|
import { readSkillTriggerEntries } from "./skill-triggers.js";
|
|
39
39
|
import { clampSectionsMax, DEFAULT_SECTIONS_MAX, SECTIONS_MAX_LIMIT, readSkillReach, } from "./reach.js";
|
|
40
40
|
import { getMonthlyAdoptionRollup } from "./session-records.js";
|
|
41
|
+
import { checkArgumentValues } from "../../../lib/utils/argument-report.js";
|
|
41
42
|
const log = createLogger("skills-tool");
|
|
42
43
|
let cachedSkills = [];
|
|
43
44
|
/**
|
|
@@ -166,38 +167,58 @@ function rowOf(row) {
|
|
|
166
167
|
return { score: row.score, reason: row.reason ?? "description" };
|
|
167
168
|
}
|
|
168
169
|
// Extension factory:
|
|
170
|
+
/**
|
|
171
|
+
* `list_skills` arguments: one action, one page of the catalog.
|
|
172
|
+
*
|
|
173
|
+
* The action is named here rather than inferred, because a pager call and a
|
|
174
|
+
* full-catalog call are the same call and the schema is what the model reads
|
|
175
|
+
* before choosing. The tool fills it when the call omits it (`prepareArguments`
|
|
176
|
+
* below), so a bare pager call behaves as the listing it obviously is while an
|
|
177
|
+
* unknown action is still refused.
|
|
178
|
+
*/
|
|
179
|
+
const listSkillsSchema = Type.Object({
|
|
180
|
+
action: Type.Literal("list", {
|
|
181
|
+
description: "list = paginated catalog with per-skill reach (reachable, lines, bytes, chars, estTokens, sectionCount, sections)",
|
|
182
|
+
}),
|
|
183
|
+
page: Type.Optional(Type.Number({
|
|
184
|
+
minimum: 1,
|
|
185
|
+
default: 1,
|
|
186
|
+
description: "Page number for list (1-based)",
|
|
187
|
+
})),
|
|
188
|
+
pageSize: Type.Optional(Type.Number({
|
|
189
|
+
minimum: 1,
|
|
190
|
+
maximum: 50,
|
|
191
|
+
default: 10,
|
|
192
|
+
description: "Entries per page for list",
|
|
193
|
+
})),
|
|
194
|
+
sectionsMax: Type.Optional(Type.Number({
|
|
195
|
+
minimum: 0,
|
|
196
|
+
maximum: SECTIONS_MAX_LIMIT,
|
|
197
|
+
default: DEFAULT_SECTIONS_MAX,
|
|
198
|
+
description: "Headings reported per skill; 0 omits the section list and keeps sectionCount",
|
|
199
|
+
})),
|
|
200
|
+
rank: Type.Optional(Type.Union([Type.Literal("relevance"), Type.Literal("catalog")], {
|
|
201
|
+
default: "relevance",
|
|
202
|
+
description: "relevance (default) = order by fit to the current task; catalog = the plain catalog order, with no ranking fields",
|
|
203
|
+
})),
|
|
204
|
+
});
|
|
169
205
|
export default function skillsToolExtension(pi) {
|
|
170
206
|
registerAutoInject(pi);
|
|
171
207
|
pi.registerTool({
|
|
172
208
|
name: "list_skills",
|
|
173
209
|
label: "List Skills",
|
|
174
210
|
description: "Discover skills on demand: paginated catalog (name, filePath, description, source) plus each skill's reach (reachable, lines, bytes, chars, estTokens, sectionCount, section headings with line numbers), so the price of a read is visible before the read. Rows are ordered by relevance to the current task; a row with match evidence carries relevance {score, reason}, and the response carries ranking {tier, basis, policy}. Pass rank: 'catalog' for the plain catalog order. `read` a SKILL.md to load it.",
|
|
175
|
-
parameters:
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
maximum: 50,
|
|
187
|
-
default: 10,
|
|
188
|
-
description: "Entries per page for list",
|
|
189
|
-
})),
|
|
190
|
-
sectionsMax: Type.Optional(Type.Number({
|
|
191
|
-
minimum: 0,
|
|
192
|
-
maximum: SECTIONS_MAX_LIMIT,
|
|
193
|
-
default: DEFAULT_SECTIONS_MAX,
|
|
194
|
-
description: "Headings reported per skill; 0 omits the section list and keeps sectionCount",
|
|
195
|
-
})),
|
|
196
|
-
rank: Type.Optional(Type.Union([Type.Literal("relevance"), Type.Literal("catalog")], {
|
|
197
|
-
default: "relevance",
|
|
198
|
-
description: "relevance (default) = order by fit to the current task; catalog = the plain catalog order, with no ranking fields",
|
|
199
|
-
})),
|
|
200
|
-
}),
|
|
211
|
+
parameters: listSkillsSchema,
|
|
212
|
+
// Paging without an action is a listing call: fill the action the call
|
|
213
|
+
// implies before pi validates, and refuse a guessed value with the accepted
|
|
214
|
+
// one named. The schema above stays the only description of the contract.
|
|
215
|
+
prepareArguments: (args) => {
|
|
216
|
+
const prepared = args && typeof args === "object" && args.action == null
|
|
217
|
+
? { ...args, action: "list" }
|
|
218
|
+
: args;
|
|
219
|
+
checkArgumentValues("list_skills", listSkillsSchema, prepared);
|
|
220
|
+
return prepared;
|
|
221
|
+
},
|
|
201
222
|
execute: async (_id, params, signal, _onUpdate, ctx) => {
|
|
202
223
|
const page = params.page ?? 1;
|
|
203
224
|
const pageSize = params.pageSize ?? 10;
|
|
@@ -39,6 +39,7 @@ import errorCaptureFn from "./self/error-tracking/index.js";
|
|
|
39
39
|
import watchdogFn from "./self/watchdog/index.js";
|
|
40
40
|
import autoRecoveryFn from "./self/auto-recovery/index.js";
|
|
41
41
|
import latentActivatorFn from "./self/latent-activator/index.js";
|
|
42
|
+
import pathMissFn from "./self/path-miss/index.js";
|
|
42
43
|
// enforcement (turn pipeline: handlers, detection, substate)
|
|
43
44
|
import enforcementFn from "./enforcement/index.js";
|
|
44
45
|
// heartbeat (proactive background services: scheduler, analytics)
|
|
@@ -189,6 +190,11 @@ export const MANIFEST = [
|
|
|
189
190
|
fn: latentActivatorFn,
|
|
190
191
|
desc: "Latent behavior activator",
|
|
191
192
|
},
|
|
193
|
+
{
|
|
194
|
+
id: "path-miss",
|
|
195
|
+
fn: pathMissFn,
|
|
196
|
+
desc: "Path-miss steer — name the listing that answers a missing path",
|
|
197
|
+
},
|
|
192
198
|
// Watchdog (default-ON — liveness/stall state machine)
|
|
193
199
|
// Default-ON per TG-HEARTBEAT-WATCHDOG-DESIGN.md ("default ON, NO new env
|
|
194
200
|
// vars"); override via `broker.watchdog` in the one settings path that
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Recognition of a missing-path tool failure, and the path it names.
|
|
3
|
+
*
|
|
4
|
+
* The shapes below are the ones the tools actually emit on this platform,
|
|
5
|
+
* measured rather than invented:
|
|
6
|
+
*
|
|
7
|
+
* read ENOENT: no such file or directory, access '/x/y.ts'
|
|
8
|
+
* edit Could not edit file: /x/y.ts. Error code: ENOENT.
|
|
9
|
+
* bash ls: /x/y: No such file or directory
|
|
10
|
+
* bash /bin/bash: line 0: cd: /x/y: No such file or directory
|
|
11
|
+
*
|
|
12
|
+
* Two of those carry a usable path in the call and the rest only in the text,
|
|
13
|
+
* so the call wins when it has one: a path the model asked for is the path the
|
|
14
|
+
* whisper should name, even when the tool's own wording echoes it loosely.
|
|
15
|
+
*
|
|
16
|
+
* Only a missing path is a path miss. A permission error, an unreadable file
|
|
17
|
+
* or a failed assertion is a different failure with a different next move, and
|
|
18
|
+
* steering toward `ls` there would cost a call without teaching anything.
|
|
19
|
+
*/
|
|
20
|
+
export interface PathMiss {
|
|
21
|
+
/** The tool whose call missed. */
|
|
22
|
+
tool: string;
|
|
23
|
+
/** The path that was not there, as the tool or the call reported it. */
|
|
24
|
+
path: string;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* The path a failed call missed, or null when this result is not a path miss.
|
|
28
|
+
*/
|
|
29
|
+
export declare function detectPathMiss(toolName: string, input: unknown, text: string): PathMiss | null;
|
|
30
|
+
//# sourceMappingURL=detect.d.ts.map
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Recognition of a missing-path tool failure, and the path it names.
|
|
3
|
+
*
|
|
4
|
+
* The shapes below are the ones the tools actually emit on this platform,
|
|
5
|
+
* measured rather than invented:
|
|
6
|
+
*
|
|
7
|
+
* read ENOENT: no such file or directory, access '/x/y.ts'
|
|
8
|
+
* edit Could not edit file: /x/y.ts. Error code: ENOENT.
|
|
9
|
+
* bash ls: /x/y: No such file or directory
|
|
10
|
+
* bash /bin/bash: line 0: cd: /x/y: No such file or directory
|
|
11
|
+
*
|
|
12
|
+
* Two of those carry a usable path in the call and the rest only in the text,
|
|
13
|
+
* so the call wins when it has one: a path the model asked for is the path the
|
|
14
|
+
* whisper should name, even when the tool's own wording echoes it loosely.
|
|
15
|
+
*
|
|
16
|
+
* Only a missing path is a path miss. A permission error, an unreadable file
|
|
17
|
+
* or a failed assertion is a different failure with a different next move, and
|
|
18
|
+
* steering toward `ls` there would cost a call without teaching anything.
|
|
19
|
+
*/
|
|
20
|
+
/** Tools whose failure can mean "the path was a guess". */
|
|
21
|
+
const PATH_BEARING_TOOLS = new Set(["read", "edit", "write", "bash"]);
|
|
22
|
+
/** The two spellings of "this path is not there" the tools emit. */
|
|
23
|
+
const MISSING_PATH = /ENOENT|no such file or directory/i;
|
|
24
|
+
/** A path quoted by a Node error: `ENOENT: ..., access '/x/y'`. */
|
|
25
|
+
const QUOTED_AFTER_SYSCALL = /\b(?:access|open|stat|lstat|scandir|opendir|unlink|readlink)\s+'([^']+)'/;
|
|
26
|
+
/** A shell builtin naming the directory it could not enter. */
|
|
27
|
+
const BASH_CD_TARGET = /(?:^|[:\s])cd:\s+(.+?):\s*no such file/i;
|
|
28
|
+
/** A program naming the operand it could not find: `ls: /x/y: No such file`. */
|
|
29
|
+
const PROGRAM_OPERAND = /([^\s:]+):\s*no such file or directory/i;
|
|
30
|
+
/** A bare errno (`ENOENT`), not a path. */
|
|
31
|
+
const ERRNO_ONLY = /^[A-Z][A-Z0-9_]*$/;
|
|
32
|
+
/** The path the call itself asked for, when the tool takes one. */
|
|
33
|
+
function pathFromCall(input) {
|
|
34
|
+
if (!input || typeof input !== "object")
|
|
35
|
+
return undefined;
|
|
36
|
+
const path = input.path;
|
|
37
|
+
return typeof path === "string" && path.length > 0 ? path : undefined;
|
|
38
|
+
}
|
|
39
|
+
/** The path an error message names, when the call did not carry one. */
|
|
40
|
+
function pathFromText(text) {
|
|
41
|
+
const candidates = [
|
|
42
|
+
QUOTED_AFTER_SYSCALL.exec(text)?.[1],
|
|
43
|
+
BASH_CD_TARGET.exec(text)?.[1],
|
|
44
|
+
PROGRAM_OPERAND.exec(text)?.[1],
|
|
45
|
+
];
|
|
46
|
+
for (const candidate of candidates) {
|
|
47
|
+
const path = candidate?.trim();
|
|
48
|
+
if (!path || ERRNO_ONLY.test(path))
|
|
49
|
+
continue;
|
|
50
|
+
return path;
|
|
51
|
+
}
|
|
52
|
+
return undefined;
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* The path a failed call missed, or null when this result is not a path miss.
|
|
56
|
+
*/
|
|
57
|
+
export function detectPathMiss(toolName, input, text) {
|
|
58
|
+
if (!PATH_BEARING_TOOLS.has(toolName))
|
|
59
|
+
return null;
|
|
60
|
+
if (!text || !MISSING_PATH.test(text))
|
|
61
|
+
return null;
|
|
62
|
+
const path = pathFromCall(input) ?? pathFromText(text);
|
|
63
|
+
if (!path)
|
|
64
|
+
return null;
|
|
65
|
+
return { tool: toolName, path };
|
|
66
|
+
}
|
|
67
|
+
//# sourceMappingURL=detect.js.map
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Path-miss steer — the tool failure that says what would have worked.
|
|
3
|
+
*
|
|
4
|
+
* A turn that guesses paths spends calls discovering a layout a listing would
|
|
5
|
+
* have named. The failure itself is the one moment the cheaper move is
|
|
6
|
+
* obvious, so it is where the line belongs: one steer per turn, the path that
|
|
7
|
+
* missed, and the three instruments that answer it (`ls`, `find`,
|
|
8
|
+
* `explore_paths`).
|
|
9
|
+
*
|
|
10
|
+
* Delivery is the standard whisper funnel (`sendTrackedMessage`), so this
|
|
11
|
+
* emitter inherits the envelope, the flood cap and the live-steer resolution
|
|
12
|
+
* every other whisper uses. The event is pi's existing `tool_result`, the only
|
|
13
|
+
* seat that carries both the failure text and the arguments the call made —
|
|
14
|
+
* the call's own `path` is more reliable than parsing the error wording.
|
|
15
|
+
*
|
|
16
|
+
* Budget: one line per turn, at most one line per path per session. A path
|
|
17
|
+
* already steered is not steered again, because a repeat tells the agent
|
|
18
|
+
* nothing it was not told, and the second occurrence usually means the agent
|
|
19
|
+
* chose to proceed rather than that it failed to read.
|
|
20
|
+
*/
|
|
21
|
+
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
22
|
+
/**
|
|
23
|
+
* One line: the path, and the cheaper moves next to it.
|
|
24
|
+
*
|
|
25
|
+
* The parent is named when the path has one, because `ls` needs an operand and
|
|
26
|
+
* a model that guessed a leaf usually had the parent wrong too — listing the
|
|
27
|
+
* parent is what tells it which of the two it got wrong.
|
|
28
|
+
*/
|
|
29
|
+
export declare function pathMissLine(path: string): string;
|
|
30
|
+
/** Test hook: forget every steered path and the current turn's budget. */
|
|
31
|
+
export declare function _resetForTests(): void;
|
|
32
|
+
export default function pathMissExtension(pi: ExtensionAPI): void;
|
|
33
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Path-miss steer — the tool failure that says what would have worked.
|
|
3
|
+
*
|
|
4
|
+
* A turn that guesses paths spends calls discovering a layout a listing would
|
|
5
|
+
* have named. The failure itself is the one moment the cheaper move is
|
|
6
|
+
* obvious, so it is where the line belongs: one steer per turn, the path that
|
|
7
|
+
* missed, and the three instruments that answer it (`ls`, `find`,
|
|
8
|
+
* `explore_paths`).
|
|
9
|
+
*
|
|
10
|
+
* Delivery is the standard whisper funnel (`sendTrackedMessage`), so this
|
|
11
|
+
* emitter inherits the envelope, the flood cap and the live-steer resolution
|
|
12
|
+
* every other whisper uses. The event is pi's existing `tool_result`, the only
|
|
13
|
+
* seat that carries both the failure text and the arguments the call made —
|
|
14
|
+
* the call's own `path` is more reliable than parsing the error wording.
|
|
15
|
+
*
|
|
16
|
+
* Budget: one line per turn, at most one line per path per session. A path
|
|
17
|
+
* already steered is not steered again, because a repeat tells the agent
|
|
18
|
+
* nothing it was not told, and the second occurrence usually means the agent
|
|
19
|
+
* chose to proceed rather than that it failed to read.
|
|
20
|
+
*/
|
|
21
|
+
import { dirname } from "node:path";
|
|
22
|
+
import { createLogger } from "../../../lib/core/logger.js";
|
|
23
|
+
import { INPUT, TOOL_RESULT } from "../../../lib/core/event-names.js";
|
|
24
|
+
import { sendTrackedMessage } from "../../../lib/utils/injection-tracker.js";
|
|
25
|
+
import { detectPathMiss } from "./detect.js";
|
|
26
|
+
const log = createLogger("path-miss");
|
|
27
|
+
/**
|
|
28
|
+
* Sessions whose steered paths are remembered. A session id is stable for the
|
|
29
|
+
* life of a session and a long-lived process can host more than one, so the
|
|
30
|
+
* map is bounded rather than trusted to stay small.
|
|
31
|
+
*/
|
|
32
|
+
const MAX_TRACKED_SESSIONS = 16;
|
|
33
|
+
/** Paths already steered, per session. */
|
|
34
|
+
const steeredPaths = new Map();
|
|
35
|
+
/** Turn-scoped: the first path miss of a turn is the one worth a line. */
|
|
36
|
+
let steeredThisTurn = false;
|
|
37
|
+
function sessionKey(ctx) {
|
|
38
|
+
const manager = ctx?.sessionManager;
|
|
39
|
+
return manager?.getSessionId?.() ?? manager?.getSessionFile?.() ?? "unknown";
|
|
40
|
+
}
|
|
41
|
+
function remember(session, path) {
|
|
42
|
+
const paths = steeredPaths.get(session) ?? new Set();
|
|
43
|
+
paths.add(path);
|
|
44
|
+
steeredPaths.set(session, paths);
|
|
45
|
+
if (steeredPaths.size > MAX_TRACKED_SESSIONS) {
|
|
46
|
+
// Insertion order: the oldest session is the first key.
|
|
47
|
+
const oldest = steeredPaths.keys().next().value;
|
|
48
|
+
if (oldest !== undefined && oldest !== session)
|
|
49
|
+
steeredPaths.delete(oldest);
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
function alreadySteered(session, path) {
|
|
53
|
+
return steeredPaths.get(session)?.has(path) ?? false;
|
|
54
|
+
}
|
|
55
|
+
/** The error text of a tool result, with any non-text parts ignored. */
|
|
56
|
+
function resultText(content) {
|
|
57
|
+
if (typeof content === "string")
|
|
58
|
+
return content;
|
|
59
|
+
if (!Array.isArray(content))
|
|
60
|
+
return "";
|
|
61
|
+
return content
|
|
62
|
+
.map((part) => part && typeof part === "object" && typeof part.text === "string"
|
|
63
|
+
? part.text
|
|
64
|
+
: "")
|
|
65
|
+
.join("\n");
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* One line: the path, and the cheaper moves next to it.
|
|
69
|
+
*
|
|
70
|
+
* The parent is named when the path has one, because `ls` needs an operand and
|
|
71
|
+
* a model that guessed a leaf usually had the parent wrong too — listing the
|
|
72
|
+
* parent is what tells it which of the two it got wrong.
|
|
73
|
+
*/
|
|
74
|
+
export function pathMissLine(path) {
|
|
75
|
+
const parent = dirname(path);
|
|
76
|
+
const listing = parent && parent !== "." && parent !== "/" ? `ls ${parent}` : "ls on its parent";
|
|
77
|
+
return `path miss: ${path} — ${listing} names the layout in one call; find and explore_paths when the parent is unknown too`;
|
|
78
|
+
}
|
|
79
|
+
/** Test hook: forget every steered path and the current turn's budget. */
|
|
80
|
+
export function _resetForTests() {
|
|
81
|
+
steeredPaths.clear();
|
|
82
|
+
steeredThisTurn = false;
|
|
83
|
+
}
|
|
84
|
+
export default function pathMissExtension(pi) {
|
|
85
|
+
// The same turn boundary the whisper family uses: a new user input opens a
|
|
86
|
+
// new turn, and a turn that has already been steered is done.
|
|
87
|
+
pi.on(INPUT, () => {
|
|
88
|
+
steeredThisTurn = false;
|
|
89
|
+
});
|
|
90
|
+
pi.on(TOOL_RESULT, (event, ctx) => {
|
|
91
|
+
if (steeredThisTurn)
|
|
92
|
+
return;
|
|
93
|
+
if (!event?.isError)
|
|
94
|
+
return;
|
|
95
|
+
const miss = detectPathMiss(event.toolName, event.input, resultText(event.content));
|
|
96
|
+
if (!miss)
|
|
97
|
+
return;
|
|
98
|
+
const session = sessionKey(ctx);
|
|
99
|
+
if (alreadySteered(session, miss.path))
|
|
100
|
+
return;
|
|
101
|
+
steeredThisTurn = true;
|
|
102
|
+
const delivered = sendTrackedMessage(pi, {
|
|
103
|
+
customType: "path-miss",
|
|
104
|
+
content: [{ type: "text", text: pathMissLine(miss.path) }],
|
|
105
|
+
display: true,
|
|
106
|
+
}, { delivery: "live" }, { type: "enforcement", source: "path-miss/steer" });
|
|
107
|
+
// A suppressed send must not spend the path's budget: the line did not
|
|
108
|
+
// arrive, so the next turn is still the first place the agent can read it.
|
|
109
|
+
if (!delivered) {
|
|
110
|
+
steeredThisTurn = false;
|
|
111
|
+
log.debug(`[path-miss] suppressed by the whisper funnel: ${miss.path}`);
|
|
112
|
+
return;
|
|
113
|
+
}
|
|
114
|
+
remember(session, miss.path);
|
|
115
|
+
log.debug(`[path-miss] steered ${miss.path} (${miss.tool})`);
|
|
116
|
+
});
|
|
117
|
+
}
|
|
118
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -17,6 +17,7 @@ export declare const MESSAGE_START: "message_start";
|
|
|
17
17
|
export declare const MESSAGE_END: "message_end";
|
|
18
18
|
export declare const TOOL_EXECUTION_START: "tool_execution_start";
|
|
19
19
|
export declare const TOOL_EXECUTION_END: "tool_execution_end";
|
|
20
|
+
export declare const TOOL_RESULT: "tool_result";
|
|
20
21
|
export declare const AGENT_SETTLED: "agent_settled";
|
|
21
22
|
export declare const INPUT: "input";
|
|
22
23
|
export declare const RESOURCES_DISCOVER: "resources_discover";
|
|
@@ -19,6 +19,7 @@ export const MESSAGE_START = "message_start";
|
|
|
19
19
|
export const MESSAGE_END = "message_end";
|
|
20
20
|
export const TOOL_EXECUTION_START = "tool_execution_start";
|
|
21
21
|
export const TOOL_EXECUTION_END = "tool_execution_end";
|
|
22
|
+
export const TOOL_RESULT = "tool_result";
|
|
22
23
|
export const AGENT_SETTLED = "agent_settled";
|
|
23
24
|
// ── Extension Communication ─────────────────────────────────────────────────
|
|
24
25
|
export const INPUT = "input";
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Tool-argument refusal text.
|
|
3
|
+
*
|
|
4
|
+
* pi validates a tool call against its schema and reports the failure in
|
|
5
|
+
* schema terms: an out-of-list value says "must be equal to one of the allowed
|
|
6
|
+
* values", a missing required field says "must have required properties
|
|
7
|
+
* decision". Neither names the values, so the model that guessed one learns
|
|
8
|
+
* nothing it can act on and guesses again.
|
|
9
|
+
*
|
|
10
|
+
* The accepted values, and the sentence explaining a required field, are
|
|
11
|
+
* already in the schema. This module reads them from there at the moment the
|
|
12
|
+
* refusal is built: no list is written twice, so no copy can drift from the
|
|
13
|
+
* one the validator enforces.
|
|
14
|
+
*
|
|
15
|
+
* Seat: a tool's `prepareArguments`. pi calls it first, inside the same
|
|
16
|
+
* guarded block as its own schema validation, so a throw here is what the
|
|
17
|
+
* model reads — and the schema stays exactly as strict as it was. The checks
|
|
18
|
+
* below are equivalences, not relaxations: a call refused here is one pi would
|
|
19
|
+
* have refused too, only with a message the model can use.
|
|
20
|
+
*
|
|
21
|
+
* Scope is the top level of the argument object. A nested list is left to pi
|
|
22
|
+
* rather than described from a guess about its parent.
|
|
23
|
+
*/
|
|
24
|
+
/**
|
|
25
|
+
* The values a schema node accepts, read from the node.
|
|
26
|
+
*
|
|
27
|
+
* A single-valued node (`const`, which is what `Type.Literal` builds) yields
|
|
28
|
+
* one value; an `enum` yields its list; a union of those yields all of them.
|
|
29
|
+
* A node that constrains nothing yields no values, and the caller then leaves
|
|
30
|
+
* the message to pi.
|
|
31
|
+
*/
|
|
32
|
+
export declare function acceptedValues(node: unknown): string[];
|
|
33
|
+
/**
|
|
34
|
+
* Throw the refusal a model can act on, when this module can say more than the
|
|
35
|
+
* validator does. Returns silently otherwise, leaving pi's own message intact.
|
|
36
|
+
*
|
|
37
|
+
* `schema` is the same object the tool declares as its `parameters`, and
|
|
38
|
+
* `args` the arguments the call carried.
|
|
39
|
+
*/
|
|
40
|
+
export declare function checkArgumentValues(toolName: string, schema: unknown, args: unknown): void;
|
|
41
|
+
//# sourceMappingURL=argument-report.d.ts.map
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Tool-argument refusal text.
|
|
3
|
+
*
|
|
4
|
+
* pi validates a tool call against its schema and reports the failure in
|
|
5
|
+
* schema terms: an out-of-list value says "must be equal to one of the allowed
|
|
6
|
+
* values", a missing required field says "must have required properties
|
|
7
|
+
* decision". Neither names the values, so the model that guessed one learns
|
|
8
|
+
* nothing it can act on and guesses again.
|
|
9
|
+
*
|
|
10
|
+
* The accepted values, and the sentence explaining a required field, are
|
|
11
|
+
* already in the schema. This module reads them from there at the moment the
|
|
12
|
+
* refusal is built: no list is written twice, so no copy can drift from the
|
|
13
|
+
* one the validator enforces.
|
|
14
|
+
*
|
|
15
|
+
* Seat: a tool's `prepareArguments`. pi calls it first, inside the same
|
|
16
|
+
* guarded block as its own schema validation, so a throw here is what the
|
|
17
|
+
* model reads — and the schema stays exactly as strict as it was. The checks
|
|
18
|
+
* below are equivalences, not relaxations: a call refused here is one pi would
|
|
19
|
+
* have refused too, only with a message the model can use.
|
|
20
|
+
*
|
|
21
|
+
* Scope is the top level of the argument object. A nested list is left to pi
|
|
22
|
+
* rather than described from a guess about its parent.
|
|
23
|
+
*/
|
|
24
|
+
function nodeOf(value) {
|
|
25
|
+
return value && typeof value === "object" ? value : undefined;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* The values a schema node accepts, read from the node.
|
|
29
|
+
*
|
|
30
|
+
* A single-valued node (`const`, which is what `Type.Literal` builds) yields
|
|
31
|
+
* one value; an `enum` yields its list; a union of those yields all of them.
|
|
32
|
+
* A node that constrains nothing yields no values, and the caller then leaves
|
|
33
|
+
* the message to pi.
|
|
34
|
+
*/
|
|
35
|
+
export function acceptedValues(node) {
|
|
36
|
+
const schema = nodeOf(node);
|
|
37
|
+
if (!schema)
|
|
38
|
+
return [];
|
|
39
|
+
if (typeof schema.const === "string")
|
|
40
|
+
return [schema.const];
|
|
41
|
+
if (Array.isArray(schema.enum) && schema.enum.every((v) => typeof v === "string")) {
|
|
42
|
+
return [...new Set(schema.enum)];
|
|
43
|
+
}
|
|
44
|
+
const branches = Array.isArray(schema.anyOf)
|
|
45
|
+
? schema.anyOf
|
|
46
|
+
: Array.isArray(schema.oneOf)
|
|
47
|
+
? schema.oneOf
|
|
48
|
+
: undefined;
|
|
49
|
+
if (!branches)
|
|
50
|
+
return [];
|
|
51
|
+
return [...new Set(branches.flatMap((branch) => acceptedValues(branch)))];
|
|
52
|
+
}
|
|
53
|
+
function quoted(value) {
|
|
54
|
+
return JSON.stringify(value);
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Throw the refusal a model can act on, when this module can say more than the
|
|
58
|
+
* validator does. Returns silently otherwise, leaving pi's own message intact.
|
|
59
|
+
*
|
|
60
|
+
* `schema` is the same object the tool declares as its `parameters`, and
|
|
61
|
+
* `args` the arguments the call carried.
|
|
62
|
+
*/
|
|
63
|
+
export function checkArgumentValues(toolName, schema, args) {
|
|
64
|
+
const root = nodeOf(schema);
|
|
65
|
+
const properties = nodeOf(root?.properties);
|
|
66
|
+
const input = nodeOf(args);
|
|
67
|
+
if (!root || !properties || !input)
|
|
68
|
+
return;
|
|
69
|
+
// A required field with a stated purpose: say both, once.
|
|
70
|
+
if (Array.isArray(root.required)) {
|
|
71
|
+
for (const key of root.required) {
|
|
72
|
+
if (typeof key !== "string")
|
|
73
|
+
continue;
|
|
74
|
+
const value = input[key];
|
|
75
|
+
if (value !== undefined && value !== null)
|
|
76
|
+
continue;
|
|
77
|
+
const purpose = nodeOf(properties[key])?.description;
|
|
78
|
+
if (typeof purpose !== "string" || purpose.length === 0)
|
|
79
|
+
continue;
|
|
80
|
+
throw new Error(`${toolName}: ${key} is required (${purpose})`);
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
// A value outside its declared list: name the list.
|
|
84
|
+
for (const [key, raw] of Object.entries(input)) {
|
|
85
|
+
if (typeof raw !== "string")
|
|
86
|
+
continue;
|
|
87
|
+
const values = acceptedValues(properties[key]);
|
|
88
|
+
if (values.length === 0 || values.includes(raw))
|
|
89
|
+
continue;
|
|
90
|
+
throw new Error(`${toolName}: ${key} ${quoted(raw)} is not accepted. Accepted: ${values
|
|
91
|
+
.map(quoted)
|
|
92
|
+
.join(", ")}`);
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
//# sourceMappingURL=argument-report.js.map
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.42.
|
|
3
|
+
"version": "0.42.1",
|
|
4
4
|
"description": "Metacognitive extension suite for pi-coding-agent: enforcement, memory, reasoning, self-improvement, and structured cognitive signals.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -23,6 +23,7 @@
|
|
|
23
23
|
"LICENSE",
|
|
24
24
|
"AGENTS.md",
|
|
25
25
|
"CONTRIBUTING.md",
|
|
26
|
+
"CHANGELOG.md",
|
|
26
27
|
"TOOLS.md",
|
|
27
28
|
"build-info.json"
|
|
28
29
|
],
|
|
@@ -66,8 +67,8 @@
|
|
|
66
67
|
"release:local": "node scripts/publish-local.mjs",
|
|
67
68
|
"publish:local": "node scripts/publish-local.mjs",
|
|
68
69
|
"dev:link": "npm link && cd ~/.pi/agent/local-packages && npm link pi-braid",
|
|
69
|
-
"prepack": "npm run build && node scripts/pack-provenance.mjs write",
|
|
70
|
-
"postpack": "node scripts/pack-provenance.mjs remove"
|
|
70
|
+
"prepack": "npm run build && node scripts/stage-changelog.mjs write && node scripts/pack-provenance.mjs write",
|
|
71
|
+
"postpack": "node scripts/pack-provenance.mjs remove && node scripts/stage-changelog.mjs remove"
|
|
71
72
|
},
|
|
72
73
|
"devDependencies": {
|
|
73
74
|
"@eslint/js": "10.0.1",
|
|
@@ -16,6 +16,7 @@ import {
|
|
|
16
16
|
DEPTH_LEVELS,
|
|
17
17
|
} from "./think-budget.js";
|
|
18
18
|
import { criticGate } from "../../../../lib/ai/critic-gate.js";
|
|
19
|
+
import { checkArgumentValues } from "../../../../lib/utils/argument-report.js";
|
|
19
20
|
import { getExtensionState } from "../../../../lib/state/extension-state.js";
|
|
20
21
|
import { createLogger } from "../../../../lib/core/logger.js";
|
|
21
22
|
|
|
@@ -213,6 +214,14 @@ export function createThinkTool(): ToolDefinition<any, any, any> {
|
|
|
213
214
|
description: "Think deeply with structured reasoning before making high-stakes decisions.",
|
|
214
215
|
promptSnippet: "Think deeply with structured reasoning before decisions",
|
|
215
216
|
parameters: thinkSchema,
|
|
217
|
+
// pi validates arguments before `execute` is reached, and its own refusal
|
|
218
|
+
// for a guessed enum or a missing field names neither. This hook runs
|
|
219
|
+
// first, inside the same guarded block, and refuses with the values the
|
|
220
|
+
// schema above already declares.
|
|
221
|
+
prepareArguments: (args: unknown) => {
|
|
222
|
+
checkArgumentValues("think", thinkSchema, args);
|
|
223
|
+
return args;
|
|
224
|
+
},
|
|
216
225
|
execute: async (
|
|
217
226
|
_toolCallId: string,
|
|
218
227
|
params: any,
|