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/build-info.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.42.0",
4
- "sha": "3da226d9dabfa6ae49fd9bab96a212e9deeac423",
5
- "shaShort": "3da226d",
3
+ "version": "0.42.1",
4
+ "sha": "b16fdbb3b1f434c2807942412b899a9ca674cfe2",
5
+ "shaShort": "b16fdbb",
6
6
  "branch": "detached",
7
7
  "dirty": false,
8
- "packedAt": "2026-10-25T19:39:54.582Z"
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: Type.Object({
176
- action: Type.Literal("list", {
177
- description: "list = paginated catalog with per-skill reach (reachable, lines, bytes, chars, estTokens, sectionCount, sections)",
178
- }),
179
- page: Type.Optional(Type.Number({
180
- minimum: 1,
181
- default: 1,
182
- description: "Page number for list (1-based)",
183
- })),
184
- pageSize: Type.Optional(Type.Number({
185
- minimum: 1,
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.0",
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,