pi-braid 0.41.2 → 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/prompt-builder/index.js +10 -11
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +17 -2
- package/dist/extensions/core/skills-tool/auto-inject.js +100 -24
- package/dist/extensions/core/skills-tool/index.js +47 -26
- package/dist/extensions/core/skills-tool/loading-guidance.d.ts +149 -28
- package/dist/extensions/core/skills-tool/loading-guidance.js +257 -29
- 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/AGENTS.md +8 -6
- package/src/extensions/core/prompt-builder/AGENTS.md +2 -2
- package/src/extensions/core/prompt-builder/index.ts +10 -14
- package/src/extensions/core/skills-tool/auto-inject.ts +138 -26
- package/src/extensions/core/skills-tool/index.ts +60 -37
- package/src/extensions/core/skills-tool/loading-guidance.ts +303 -29
- 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/src/lib/utils/AGENTS.md
CHANGED
|
@@ -19,6 +19,7 @@ Misc utilities that don't fit a more specific subdir.
|
|
|
19
19
|
| `error-guard.ts` | Wraps handler errors with logging and recovery. |
|
|
20
20
|
| `async-fs.ts` | Async filesystem primitives (`asyncExists`). Replaces duplicate `existsSync` checks. |
|
|
21
21
|
| `format-tool-result.ts` | Structured Output Catalyst - wraps tool output in consistent TOOL/STATUS/RESULT header format. MDA research (2601.21996) backing. |
|
|
22
|
+
| `argument-report.ts` | Builds the refusal text a tool-argument rejection carries: the accepted values and a required field's stated purpose, both read from the tool's own schema at the moment the message is built (no second copy to drift). Used from a tool's `prepareArguments`, which pi calls before its own validation. |
|
|
22
23
|
|
|
23
24
|
## Local Contracts
|
|
24
25
|
|
|
@@ -0,0 +1,105 @@
|
|
|
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
|
+
/** A schema node, as far as this module needs to read it. */
|
|
26
|
+
interface SchemaNode {
|
|
27
|
+
const?: unknown;
|
|
28
|
+
enum?: unknown;
|
|
29
|
+
anyOf?: unknown;
|
|
30
|
+
oneOf?: unknown;
|
|
31
|
+
description?: unknown;
|
|
32
|
+
properties?: unknown;
|
|
33
|
+
required?: unknown;
|
|
34
|
+
[keyword: string]: unknown;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
function nodeOf(value: unknown): SchemaNode | undefined {
|
|
38
|
+
return value && typeof value === "object" ? (value as SchemaNode) : undefined;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* The values a schema node accepts, read from the node.
|
|
43
|
+
*
|
|
44
|
+
* A single-valued node (`const`, which is what `Type.Literal` builds) yields
|
|
45
|
+
* one value; an `enum` yields its list; a union of those yields all of them.
|
|
46
|
+
* A node that constrains nothing yields no values, and the caller then leaves
|
|
47
|
+
* the message to pi.
|
|
48
|
+
*/
|
|
49
|
+
export function acceptedValues(node: unknown): string[] {
|
|
50
|
+
const schema = nodeOf(node);
|
|
51
|
+
if (!schema) return [];
|
|
52
|
+
if (typeof schema.const === "string") return [schema.const];
|
|
53
|
+
if (Array.isArray(schema.enum) && schema.enum.every((v) => typeof v === "string")) {
|
|
54
|
+
return [...new Set(schema.enum as string[])];
|
|
55
|
+
}
|
|
56
|
+
const branches = Array.isArray(schema.anyOf)
|
|
57
|
+
? schema.anyOf
|
|
58
|
+
: Array.isArray(schema.oneOf)
|
|
59
|
+
? schema.oneOf
|
|
60
|
+
: undefined;
|
|
61
|
+
if (!branches) return [];
|
|
62
|
+
return [...new Set(branches.flatMap((branch) => acceptedValues(branch)))];
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
function quoted(value: string): string {
|
|
66
|
+
return JSON.stringify(value);
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Throw the refusal a model can act on, when this module can say more than the
|
|
71
|
+
* validator does. Returns silently otherwise, leaving pi's own message intact.
|
|
72
|
+
*
|
|
73
|
+
* `schema` is the same object the tool declares as its `parameters`, and
|
|
74
|
+
* `args` the arguments the call carried.
|
|
75
|
+
*/
|
|
76
|
+
export function checkArgumentValues(toolName: string, schema: unknown, args: unknown): void {
|
|
77
|
+
const root = nodeOf(schema);
|
|
78
|
+
const properties = nodeOf(root?.properties);
|
|
79
|
+
const input = nodeOf(args);
|
|
80
|
+
if (!root || !properties || !input) return;
|
|
81
|
+
|
|
82
|
+
// A required field with a stated purpose: say both, once.
|
|
83
|
+
if (Array.isArray(root.required)) {
|
|
84
|
+
for (const key of root.required) {
|
|
85
|
+
if (typeof key !== "string") continue;
|
|
86
|
+
const value = (input as Record<string, unknown>)[key];
|
|
87
|
+
if (value !== undefined && value !== null) continue;
|
|
88
|
+
const purpose = nodeOf(properties[key])?.description;
|
|
89
|
+
if (typeof purpose !== "string" || purpose.length === 0) continue;
|
|
90
|
+
throw new Error(`${toolName}: ${key} is required (${purpose})`);
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
// A value outside its declared list: name the list.
|
|
95
|
+
for (const [key, raw] of Object.entries(input as Record<string, unknown>)) {
|
|
96
|
+
if (typeof raw !== "string") continue;
|
|
97
|
+
const values = acceptedValues(properties[key]);
|
|
98
|
+
if (values.length === 0 || values.includes(raw)) continue;
|
|
99
|
+
throw new Error(
|
|
100
|
+
`${toolName}: ${key} ${quoted(raw)} is not accepted. Accepted: ${values
|
|
101
|
+
.map(quoted)
|
|
102
|
+
.join(", ")}`,
|
|
103
|
+
);
|
|
104
|
+
}
|
|
105
|
+
}
|