@orkestrel/scaffold 0.0.122 → 0.0.124
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/dist/agents/skills/orkestrel-harden/scripts/interleave.js +539 -0
- package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1163 -0
- package/dist/bin/main.js +21 -19
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +13 -7
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -3
- package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +1 -1
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +4 -2
- package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +2 -2
- package/dist/host/agents/skills/orkestrel-harden/SKILL.md +16 -3
- package/dist/host/agents/skills/orkestrel-harden/references/bindings.md +18 -12
- package/dist/host/agents/skills/orkestrel-harden/references/document.md +1 -0
- package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +2 -1
- package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +1 -1
- package/dist/host/agents/skills/orkestrel-harden/references/methods.md +642 -0
- package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +665 -0
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +14 -13
- package/dist/host/agents/skills/orkestrel-parallel/references/claude-code.md +13 -13
- package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +1 -0
- package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1433 -0
- package/dist/host/agents/skills/orkestrel-publish/SKILL.md +2 -1
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +18 -1
- package/dist/host/claude/AGENTS.md +1 -1
- package/dist/host/claude/agents/analyst.md +1 -1
- package/dist/host/claude/agents/builder.md +1 -1
- package/dist/host/claude/agents/distiller.md +2 -1
- package/dist/host/claude/agents/grok.md +2 -2
- package/dist/host/claude/agents/opus.md +2 -2
- package/dist/host/claude/agents/orkestrel.md +30 -30
- package/dist/host/claude/agents/reviewer.md +2 -2
- package/dist/host/claude/agents/scout.md +2 -1
- package/dist/host/claude/agents/verifier.md +1 -1
- package/dist/host/claude/rules/campaign.md +12 -11
- package/dist/host/claude/rules/documentation.md +1 -0
- package/dist/host/claude/rules/patterns.md +14 -0
- package/dist/host/claude/rules/quality.md +4 -1
- package/dist/host/claude/rules/tests.md +4 -0
- package/dist/host/claude/rules/writing.md +1 -1
- package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/codex/agents/analyst.toml +4 -1
- package/dist/host/codex/agents/astra.toml +1 -1
- package/dist/host/codex/agents/builder.toml +1 -1
- package/dist/host/codex/agents/distiller.toml +4 -2
- package/dist/host/codex/agents/grok.toml +5 -2
- package/dist/host/codex/agents/opus.toml +3 -3
- package/dist/host/codex/agents/reviewer.toml +6 -2
- package/dist/host/codex/agents/scout.toml +5 -1
- package/dist/host/codex/agents/verifier.toml +6 -1
- package/dist/host/guides/agent.md +1119 -457
- package/dist/host/guides/contract.md +226 -104
- package/dist/host/guides/database.md +12 -12
- package/dist/host/guides/ndjson.md +94 -21
- package/dist/host/guides/ollama.md +22 -18
- package/dist/host/guides/probe.md +29 -27
- package/dist/host/guides/reason.md +377 -114
- package/dist/host/guides/scaffold.md +43 -21
- package/dist/host/guides/study.md +538 -450
- package/dist/host/guides/tool.md +163 -58
- package/dist/host/manifest.json +70 -52
- package/dist/src/core/index.cjs +21 -20
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +1 -4
- package/dist/src/core/index.d.ts +1 -4
- package/dist/src/core/index.js +21 -20
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +87 -8
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +50 -6
- package/dist/src/server/index.d.ts +50 -6
- package/dist/src/server/index.js +87 -10
- package/dist/src/server/index.js.map +1 -1
- package/package.json +15 -15
package/dist/host/guides/tool.md
CHANGED
|
@@ -11,7 +11,7 @@ call whose shape is data, so whoever calls it can discover it, present it, and i
|
|
|
11
11
|
knowing anything about the code behind it.
|
|
12
12
|
|
|
13
13
|
`Tool` and `ToolManager` carry the runtime. A `Tool` is inert — a definition plus a handler, with
|
|
14
|
-
no lifecycle.
|
|
14
|
+
no lifecycle. Every call passes its door before the handler runs. A `ToolManager`
|
|
15
15
|
is the live surface a caller holds: it hands `definitions()` outward, takes a `ToolCall` back, and
|
|
16
16
|
answers with a `ToolResult`, a result rather than a throw for a call whose members are plain
|
|
17
17
|
values. Tools stay in the map by name in insertion order. Everything else in this module is the
|
|
@@ -26,7 +26,8 @@ capability to a remote client, a backend dispatching a named operation. `@orkest
|
|
|
26
26
|
|
|
27
27
|
**Mechanism only.** This runtime advertises, dispatches, and contains failure. It transports
|
|
28
28
|
nothing, authorizes no call, and ships no concrete tools. A `contract` derives the advertised
|
|
29
|
-
parameter schema and
|
|
29
|
+
parameter schema, `parameters` is advertised verbatim, and the door enforces either on every call;
|
|
30
|
+
a tool with neither takes no arguments, and `strict: false` forwards a call unchecked. Caller identity
|
|
30
31
|
in the execution context is consumer-asserted and forwarded without verification. Each trust
|
|
31
32
|
decision belongs to the invoking consumer, to a policy layer, or to the tool itself. Progress
|
|
32
33
|
reporting belongs there too: it is a property of the invoking consumer's execution context, one
|
|
@@ -48,7 +49,7 @@ optional field the caller did not supply is absent from the value.
|
|
|
48
49
|
| `ToolCall` | interface | `{ id, name, arguments }` | Describes one request to run a named tool. |
|
|
49
50
|
| `ToolSuccess` | interface | `{ id, name }` | Reports the successful outcome of executing a `ToolCall`. |
|
|
50
51
|
| `ToolFailure` | interface | `{ id, name }` | Reports the failed outcome of executing a `ToolCall`. |
|
|
51
|
-
| `ToolOptions` | interface | `{ name, title?, description?, summary?, parameters?, contract?, annotations?, execute }`
|
|
52
|
+
| `ToolOptions` | interface | `{ name, title?, description?, summary?, parameters?, contract?, strict?, annotations?, execute }` | Configures an executable tool. |
|
|
52
53
|
| `ToolInterface` | interface | `{ summary?, execute() }` | Represents an executable tool: its advertised definition plus its local handler. |
|
|
53
54
|
| `ToolManagerInterface` | interface | `{ count, emitter, add(), tool(), tools(), definitions(), execute(), remove(), clear(), destroy() }` | Represents a registry of executable tools with per-call error isolation. |
|
|
54
55
|
| `ToolManagerEventMap` | type | `{ readonly add: readonly [tool: ToolInterface]; readonly remove: readonly [tool: ToolInterface]; readonly clear: readonly [tools: readonly ToolInterface[]]; }` | Names the events a tool registry publishes. |
|
|
@@ -56,8 +57,8 @@ optional field the caller did not supply is absent from the value.
|
|
|
56
57
|
| `ToolResult` | type | `ToolSuccess \| ToolFailure` | Represents the outcome of executing a `ToolCall`. |
|
|
57
58
|
| `ToolContext` | interface | `{ signal, caller? }` | Carries the signal and consumer-asserted identity for an execution. |
|
|
58
59
|
| `ToolAnnotations` | interface | `{ pure?, untrusted?, consequential? }` | Describes the observable effects and content of a tool. |
|
|
59
|
-
| `ToolErrorCode` | type | `'SCHEMA' \| 'ARGUMENTS'` | Identifies a
|
|
60
|
-
| `ToolErrorContext` | interface | `{ faults? }` | Carries the structured faults behind an argument
|
|
60
|
+
| `ToolErrorCode` | type | `'SCHEMA' \| 'ARGUMENTS'` | Identifies a refused tool declaration or refused call arguments. |
|
|
61
|
+
| `ToolErrorContext` | interface | `{ faults? }` | Carries the structured faults behind an argument refusal. |
|
|
61
62
|
|
|
62
63
|
`ToolInterface` and `ToolManagerInterface` list every member they declare or inherit. The
|
|
63
64
|
call-signature members of each are documented under [Methods](#methods); the readonly `count` of
|
|
@@ -66,6 +67,16 @@ method row. Its readonly `emitter` publishes `add`, `remove`, and `clear` with t
|
|
|
66
67
|
declared by `ToolManagerEventMap`. The `ToolManagerOptions` fields supply initial `on` hooks
|
|
67
68
|
and an `error` handler for listener throws.
|
|
68
69
|
|
|
70
|
+
### Constants
|
|
71
|
+
|
|
72
|
+
The schemas a tool advertises when it declares none, and the bounds of a refusal, from
|
|
73
|
+
[`constants.ts`](../src/core/constants.ts).
|
|
74
|
+
|
|
75
|
+
| Name | Kind | Signature | Summary |
|
|
76
|
+
| ------------------- | ----- | ----------------------------------- | --------------------------------------------------------------------------------------------- |
|
|
77
|
+
| `CLOSED_PARAMETERS` | const | `Readonly<Record<string, unknown>>` | Holds the schema a tool that declares nothing advertises and enforces: a closed empty object. |
|
|
78
|
+
| `OPEN_PARAMETERS` | const | `Readonly<Record<string, unknown>>` | Holds the schema a raw tool that declares nothing advertises: an open object. |
|
|
79
|
+
|
|
69
80
|
### Validators
|
|
70
81
|
|
|
71
82
|
The call-envelope guard, from [`validators.ts`](../src/core/validators.ts).
|
|
@@ -76,11 +87,15 @@ The call-envelope guard, from [`validators.ts`](../src/core/validators.ts).
|
|
|
76
87
|
|
|
77
88
|
### Helpers
|
|
78
89
|
|
|
79
|
-
The advertised-definition projection, from
|
|
90
|
+
The advertised-definition projection, the door's report and its text, and the read of a call, from
|
|
91
|
+
[`helpers.ts`](../src/core/helpers.ts).
|
|
80
92
|
|
|
81
|
-
| Name
|
|
82
|
-
|
|
|
83
|
-
| `toolToDefinition`
|
|
93
|
+
| Name | Kind | Signature | Summary |
|
|
94
|
+
| -------------------- | -------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
95
|
+
| `toolToDefinition` | function | `(tool: ToolInterface) => ToolDefinition` | Projects a tool onto the plain definition advertised to a caller, advertising an authored `summary` in place of the full description and carrying `parameters` and `annotations` by reference. |
|
|
96
|
+
| `parametersToSchema` | function | `(parameters: Readonly<Record<string, unknown>>) => Readonly<Record<string, unknown>>` | Projects a `parameters` record onto the schema its door compiles, reading a root with `properties` and no `type` as an object, because a tool's arguments are always a record. |
|
|
97
|
+
| `readCall` | function | `(call: unknown) => Readonly<Record<string, unknown>>` | Reads a call's `id`, `name`, and `arguments` once into a plain record, so a guard and every later step see the same values. |
|
|
98
|
+
| `buildCallRefusal` | function | `(call: unknown) => ToolFailure` | Builds the failure a registry answers with for a value that is not a `ToolCall`, carrying each of its `id` and `name` that is a string and leaving the other empty. |
|
|
84
99
|
|
|
85
100
|
### Factories
|
|
86
101
|
|
|
@@ -98,21 +113,23 @@ The implementing classes, from [`Tool.ts`](../src/core/tools/Tool.ts) and
|
|
|
98
113
|
[`ToolManager.ts`](../src/core/tools/ToolManager.ts) — each documented in full under its own
|
|
99
114
|
heading following this table.
|
|
100
115
|
|
|
101
|
-
| Name | Kind | Signature
|
|
102
|
-
| ------------- | ----- |
|
|
103
|
-
| `Tool` | class | `new (options: ToolOptions) => ToolInterface`
|
|
104
|
-
| `ToolManager` | class | `new (options?: ToolManagerOptions) => ToolManagerInterface`
|
|
105
|
-
| `ToolError` | class | `new (code: ToolErrorCode, message: string, context?: ToolErrorContext) => ToolError` | Reports a
|
|
116
|
+
| Name | Kind | Signature | Summary |
|
|
117
|
+
| ------------- | ----- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
|
118
|
+
| `Tool` | class | `new (options: ToolOptions) => ToolInterface` | Binds an executable tool definition to a handler. |
|
|
119
|
+
| `ToolManager` | class | `new (options?: ToolManagerOptions) => ToolManagerInterface` | Represents an insertion-ordered tool registry with per-call error isolation. |
|
|
120
|
+
| `ToolError` | class | `new (code: ToolErrorCode, message: string, context?: ToolErrorContext, options?: ErrorOptions) => ToolError` | Reports a refused tool declaration or refused call arguments with a machine-readable code. |
|
|
106
121
|
|
|
107
122
|
### `Tool`
|
|
108
123
|
|
|
109
124
|
The implementing class of `ToolInterface`, from [`Tool.ts`](../src/core/tools/Tool.ts). It
|
|
110
125
|
copies the fields it was given — omitting each optional one that was not supplied — and keeps
|
|
111
126
|
the handler in a private field, so a tool's advertised shape cannot drift from what it executes.
|
|
112
|
-
An explicit parameter schema and the execution context are forwarded by reference.
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
127
|
+
An explicit parameter schema and the execution context are forwarded by reference. A contract
|
|
128
|
+
compiles at construction and derives the parameter schema through the contract package's
|
|
129
|
+
projection; a `parameters` record compiles on the first `execute`. Either way the door checks
|
|
130
|
+
arguments before handler entry and supplies what `parse` returns to the handler. Under `strict: false`
|
|
131
|
+
the argument record retains its identity. `name` must be a non-empty trimmed string, or the
|
|
132
|
+
constructor throws code `SCHEMA`.
|
|
116
133
|
`Tool` deliberately does not catch: a handler that throws throws, and per-call isolation belongs
|
|
117
134
|
to the registry that dispatched it. See [`## Methods`](#methods) for its public call surface.
|
|
118
135
|
|
|
@@ -131,8 +148,9 @@ The guard recognizes self-branded errors across package copies and subclasses,
|
|
|
131
148
|
validates the declared code and optional fault report, and refuses transparent proxies.
|
|
132
149
|
|
|
133
150
|
The error class from [`errors.ts`](../src/core/errors.ts) extends `Error`. Its constructor takes
|
|
134
|
-
`code`, `message`,
|
|
135
|
-
the full fault report in `context.faults`; the manager
|
|
151
|
+
`code`, `message`, optional `context`, and optional error `options` for a `cause`. Direct tool
|
|
152
|
+
execution throws an `ARGUMENTS` error with the full fault report in `context.faults`; the manager
|
|
153
|
+
contains it as a message. Use `isToolError`
|
|
136
154
|
to narrow a caught value. See [Contract validation and errors](#contract-validation-and-errors)
|
|
137
155
|
for an executed example.
|
|
138
156
|
|
|
@@ -195,12 +213,16 @@ const add = createTool({
|
|
|
195
213
|
`new Tool({ … })` builds the same thing; reach for `createTool` where a call site must not name
|
|
196
214
|
a class.
|
|
197
215
|
|
|
198
|
-
An explicit `parameters` schema is
|
|
199
|
-
`required`
|
|
200
|
-
|
|
216
|
+
An explicit `parameters` schema is advertised by reference, and the same schema is enforced:
|
|
217
|
+
declaring `required` tells the caller what to send, and the door refuses a call that omits it. See
|
|
218
|
+
[Contract validation and errors](#contract-validation-and-errors) for what the door does and for the
|
|
219
|
+
`strict: false` opt-out. A tool that declares neither `contract` nor `parameters` takes no
|
|
220
|
+
arguments: it advertises and enforces `CLOSED_PARAMETERS`, and a call that sends a key is told what the
|
|
221
|
+
tool's author must supply.
|
|
201
222
|
|
|
202
223
|
A handler receives a `Readonly<Record<string, unknown>>` and a required `ToolContext`.
|
|
203
|
-
|
|
224
|
+
The record is what `parse` returns, or the original input under `strict: false`; see
|
|
225
|
+
[Contract validation and errors](#contract-validation-and-errors) for what that means for a handler.
|
|
204
226
|
The context holds an `AbortSignal` and optional unverified caller identity. Handlers may omit
|
|
205
227
|
unused parameters from their declaration. Every invocation still supplies the arguments and the
|
|
206
228
|
context. A direct `tool.execute(args, context)` call must provide the context; the manager creates
|
|
@@ -216,12 +238,17 @@ A registry is a working set, not a global. Build one per caller, fill it with th
|
|
|
216
238
|
caller is allowed to reach, and hand out its definitions:
|
|
217
239
|
|
|
218
240
|
```ts
|
|
241
|
+
import { objectShape, stringShape } from '@orkestrel/contract'
|
|
219
242
|
import { Tool, createToolManager } from '@orkestrel/tool'
|
|
220
243
|
|
|
221
244
|
const tools = createToolManager()
|
|
222
245
|
tools.add(add) // the tool defined earlier
|
|
223
246
|
tools.add([
|
|
224
|
-
new Tool({
|
|
247
|
+
new Tool({
|
|
248
|
+
name: 'echo',
|
|
249
|
+
contract: objectShape({ value: stringShape() }),
|
|
250
|
+
execute: (args) => args.value,
|
|
251
|
+
}),
|
|
225
252
|
new Tool({ name: 'now', description: 'Current epoch milliseconds.', execute: () => Date.now() }),
|
|
226
253
|
])
|
|
227
254
|
|
|
@@ -241,8 +268,8 @@ Remove a name and add it again and it lands at the end, because the name is genu
|
|
|
241
268
|
map. In a batch, later entries win over earlier ones with the same name.
|
|
242
269
|
|
|
243
270
|
`definitions()` projects fresh plain objects on every call: `name`, followed by present `title`,
|
|
244
|
-
`description`, `parameters`, and `annotations` fields. A
|
|
245
|
-
description. The schema and annotations retain their original identities. Nothing that arrives on
|
|
271
|
+
`description`, `parameters`, and `annotations` fields. A `Tool` always has `parameters`. A summary
|
|
272
|
+
replaces the advertised description. The schema and annotations retain their original identities. Nothing that arrives on
|
|
246
273
|
a definition is a live handle on the registry — advertising cannot be used to reach the handlers.
|
|
247
274
|
|
|
248
275
|
## Calls and results
|
|
@@ -278,7 +305,9 @@ const batch = await tools.execute([
|
|
|
278
305
|
|
|
279
306
|
`isToolCall` validates the envelope only: the `id`, the `name`, and that `arguments` is a plain
|
|
280
307
|
record. The guard ignores extra fields without reading them. A call carries no execution context.
|
|
281
|
-
The
|
|
308
|
+
The registry reads a call's `id`, `name`, and `arguments` once, applies the same guard to that read,
|
|
309
|
+
and hands the registered tool's door what it read, so an accessor cannot show the guard one value and
|
|
310
|
+
the handler another. The door validates the arguments during execution.
|
|
282
311
|
|
|
283
312
|
Execution context travels as a separate argument. This package adds neither the signal nor caller
|
|
284
313
|
identity to definitions, schemas, calls, or results. A handler can explicitly return a context
|
|
@@ -286,8 +315,10 @@ member as its own value. The context and caller identity reach the handler uncha
|
|
|
286
315
|
|
|
287
316
|
Execution always resolves for a call whose members are plain values; a call whose `id` or `name`
|
|
288
317
|
accessor throws when read makes `execute` reject, because no correlated result can be built
|
|
289
|
-
without them.
|
|
290
|
-
|
|
318
|
+
without them. A value failing `isToolCall` becomes a failure reading `malformed call` before any
|
|
319
|
+
tool is reached, its `id` and `name` empty where it held no string for them; a throwing `arguments`
|
|
320
|
+
accessor reads as absent, so it lands here too. An unknown name becomes
|
|
321
|
+
`tool not found: <name>`; a synchronous throw and an asynchronous rejection are both contained; an `Error` contributes its `message`, and any other
|
|
291
322
|
thrown value is converted with `String`; a value whose conversion itself throws — a hostile
|
|
292
323
|
`toString`, a throwing `message` getter, a null-prototype object — becomes the fixed message
|
|
293
324
|
`Unknown thrown value`. Success and failure never mix in one result: a successful call carries
|
|
@@ -343,24 +374,95 @@ that handler and contains its throws as usual; an abort does not force a running
|
|
|
343
374
|
## Contract validation and errors
|
|
344
375
|
|
|
345
376
|
A contract compiles at construction. Its schema projects to `parameters` through
|
|
346
|
-
`schemaToParameters(createContract(shape).schema)` from `@orkestrel/contract
|
|
347
|
-
|
|
348
|
-
`
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
`
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
377
|
+
`schemaToParameters(createContract(shape).schema)` from `@orkestrel/contract`. Construction errors
|
|
378
|
+
from the dependency propagate unchanged, so an owned declaration fails early. A `parameters` record
|
|
379
|
+
is advertised verbatim and compiles through the lenient `schemaToShape` on the first `execute`,
|
|
380
|
+
memoized on the instance, so building many tools compiles nothing until a call. That is the one read
|
|
381
|
+
of the record: mutating it after the first call leaves the door behind what `definitions()`
|
|
382
|
+
advertises, so treat it as frozen. The conversion widens every keyword it cannot express, so the door
|
|
383
|
+
refuses a subset of what the schema itself refuses and never more. A conversion failure, which only a
|
|
384
|
+
schema that cannot be read produces, throws `ToolError` with code `SCHEMA` from `execute`, with the
|
|
385
|
+
failure as its `cause`; a JSON-parsed schema never throws. `parameters` that is not a plain record,
|
|
386
|
+
and `contract` and `parameters` together, throw code `SCHEMA` at construction.
|
|
387
|
+
|
|
388
|
+
Every call passes the door before the handler, in this order:
|
|
389
|
+
|
|
390
|
+
1. Each top-level argument is read once into a copy, and a read that throws refuses. Every later step
|
|
391
|
+
reads that copy.
|
|
392
|
+
2. A value `is` accepts goes straight to `parse`, because `audit` is empty if and only if `is` holds.
|
|
393
|
+
3. A fault from `explain` refuses. `explain` runs only where `parse` returns nothing, because it is
|
|
394
|
+
empty exactly when `parse` is defined.
|
|
395
|
+
4. An `extra` fault from `audit` refuses. A shape declared open with
|
|
396
|
+
`objectShape(properties, { additionalProperties: true })`, or a schema whose `additionalProperties`
|
|
397
|
+
is absent or `true`, is the one way to admit an undeclared key.
|
|
398
|
+
5. An `audit` report at `FAULT_LIMIT` refuses, because its cap can hide an undeclared key.
|
|
399
|
+
6. A `variant` or `oneOf` fault from `audit` refuses, because a union parses by declaration order, so
|
|
400
|
+
a coercion through one is not a repair.
|
|
401
|
+
7. `contract.parse` gives the handler its arguments.
|
|
402
|
+
|
|
403
|
+
A nested accessor is read by each step that runs, which on a valid record is `is` and `parse`. A value
|
|
404
|
+
that changes between them cannot reach the handler invalid, because every defined `parse` result
|
|
405
|
+
satisfies `is`, and one that stops parsing refuses.
|
|
406
|
+
|
|
407
|
+
The handler receives what `parse` returns. That is a fresh null-prototype record at each declared
|
|
408
|
+
object, so read its keys directly, with `Object.keys`, or with `in`: `String(args)` and
|
|
409
|
+
`args.hasOwnProperty()` throw on it. An open object's undeclared keys and any node the shape leaves
|
|
410
|
+
raw stay by reference. So `{ type: 'object' }` gives a null-prototype copy of the top level with nested
|
|
411
|
+
values by reference, and `parameters: {}` or a root `$ref` gives a plain top-level copy with nested
|
|
412
|
+
values by reference.
|
|
413
|
+
|
|
414
|
+
The shared lossless admission helper from `@orkestrel/contract` accepts `'30'` as `30`, `'true'`
|
|
415
|
+
as `true`, and a finite number as its string. It refuses `'30.0'`, which changes the supplied text.
|
|
416
|
+
The handler receives the admitted value without another parse. The argument snapshot remains
|
|
417
|
+
in this package, and a union may retain that snapshot or its nested values by identity.
|
|
418
|
+
`anyOf: [T, { type: 'null' }]` and `type: [T, 'null']` convert to a nullable rather than a union, so `'5'` reaches the handler
|
|
419
|
+
of an `Optional[int]` as `5`, and a refusal there names the inner fault. A `parameters` root with
|
|
420
|
+
`properties` and no `type` compiles as `{ type: 'object', ...parameters }` and stays advertised verbatim,
|
|
421
|
+
because a tool's arguments are always a record. A nested node with `properties` and no `type` keeps its
|
|
422
|
+
conversion to a union, because a nested value can hold a non-object, so a coercion through it refuses
|
|
423
|
+
as `variant` at that path and the faults under that path are left out. Declare `type: 'object'` on a
|
|
424
|
+
nested node to get the repair and the inner fault.
|
|
425
|
+
|
|
426
|
+
A schema `default` never refuses a call, and `parse` fills it only where the lenient conversion carries
|
|
427
|
+
it: a primitive or literal default on an optional key of a closed object with no union ancestor. See
|
|
428
|
+
the `schemaToShape` section of [`contract.md`](contract.md) for that rule. Everywhere else the key stays
|
|
429
|
+
absent, including under a schema that leaves `additionalProperties` out, so a handler must supply its
|
|
430
|
+
own fallback for an absent key unless the schema closes the object.
|
|
431
|
+
|
|
432
|
+
A refusal throws `ToolError` with code `ARGUMENTS`. The message holds one line per fault: its path
|
|
433
|
+
and reason, then its expected and received values when the fault carries them; a constraint fault
|
|
434
|
+
also names its constraint and limit when present. A missing field carries expected alone. Each line
|
|
435
|
+
says what to send where the schema says so:
|
|
436
|
+
|
|
437
|
+
- An `extra` line lists the keys declared at that path, at most 12 of them.
|
|
438
|
+
- A line on a literal names its candidates, at most 12 of them.
|
|
439
|
+
- A `variant` or `oneOf` line says that the value matches none of the declared forms, or several where
|
|
440
|
+
exactly one must match, and that it must be sent exactly as the schema declares. It summarizes each
|
|
441
|
+
form, such as `{"city": string} or {"zip": number}`, with required keys first and optional keys marked
|
|
442
|
+
`?`. It names at most 12 forms, each in at most 160 UTF-16 code units characters.
|
|
443
|
+
- An `extra` line at the root of a tool that declares no arguments tells the author to supply `contract`
|
|
444
|
+
or `parameters`, or `strict: false`, because writing a handler before its schema is the ordinary first
|
|
445
|
+
use.
|
|
446
|
+
|
|
447
|
+
Where a `variant` or `oneOf` fault covers a path, every fault under that path is left out, because
|
|
448
|
+
those come from the walk of one arm and can call a key undeclared that another arm declares. The
|
|
449
|
+
summary of each form takes their place, so no one form's faults read as if they held for all of them.
|
|
450
|
+
|
|
451
|
+
Array paths join with `.`. A segment that is not a plain identifier is JSON-encoded and length-capped,
|
|
452
|
+
because a key the caller sent is untrusted text. A path of more than four segments past 120 characters
|
|
453
|
+
keeps its first segment and its last three. A root array path is empty, so its line starts with `: `.
|
|
454
|
+
|
|
455
|
+
The whole message stays within 2048 UTF-16 code units, because it goes back to a model whose
|
|
456
|
+
context window can be 2048 tokens and an over-window request refuses. It reserves room for omitted-fault and cap notices and a schema-derived send summary. Tool-specific
|
|
457
|
+
correction and author guidance share that budget. The error's
|
|
458
|
+
`context.faults` holds every fault up to `FAULT_LIMIT`, whatever the message shows. If parsing returns
|
|
459
|
+
a value that isn't a record after a clean report, execution throws code `ARGUMENTS`, without `context`,
|
|
460
|
+
before handler entry.
|
|
461
|
+
|
|
462
|
+
`strict: false` is the raw passthrough for a tool that validates for itself: nothing is compiled for
|
|
463
|
+
arguments, the raw record reaches the handler by identity, and the advertised schema stays as it was
|
|
464
|
+
given. A `contract` still derives the advertised schema, and a tool that declares neither advertises
|
|
465
|
+
`OPEN_PARAMETERS`.
|
|
364
466
|
|
|
365
467
|
Use the guard to narrow an error at the direct execution boundary:
|
|
366
468
|
|
|
@@ -377,14 +479,14 @@ const tool = createTool({
|
|
|
377
479
|
const context = { signal: new AbortController().signal }
|
|
378
480
|
tool.execute({ amount: 3 }, context) // 3
|
|
379
481
|
try {
|
|
380
|
-
tool.execute({ amount: 'invalid' }, context)
|
|
482
|
+
tool.execute({ amount: 'invalid', extra: 1 }, context)
|
|
381
483
|
} catch (error) {
|
|
382
484
|
if (!isToolError(error)) throw error
|
|
383
485
|
const code: ToolErrorCode = error.code
|
|
384
486
|
code // 'ARGUMENTS'
|
|
385
487
|
const details: ToolErrorContext | undefined = error.context
|
|
386
|
-
details?.faults?.[
|
|
387
|
-
error.message // 'amount: type; expected number; received "invalid"'
|
|
488
|
+
details?.faults?.[1]?.reason // 'extra'
|
|
489
|
+
error.message // 'amount: type; expected number; received "invalid"\nextra: extra; this key is not declared, remove it or use a declared key: amount\nsend {"amount": number}'
|
|
388
490
|
}
|
|
389
491
|
const conflict = new ToolError('SCHEMA', 'Choose contract or parameters')
|
|
390
492
|
conflict.code // 'SCHEMA'
|
|
@@ -392,8 +494,9 @@ isToolError(conflict) // true
|
|
|
392
494
|
isToolError(new Error('Unrelated')) // false
|
|
393
495
|
```
|
|
394
496
|
|
|
395
|
-
The manager contains this same argument refusal as a `ToolFailure
|
|
396
|
-
|
|
497
|
+
The manager contains this same argument refusal as a `ToolFailure`, and a `SCHEMA` failure from
|
|
498
|
+
`execute` the same way, naming the tool in its message; each carries the message rather than the
|
|
499
|
+
error instance or fault report. `ToolError` extends `Error`, exposes its readonly `code`
|
|
397
500
|
and optional readonly `context`, and inherits the standard error methods.
|
|
398
501
|
|
|
399
502
|
## Advertising title and annotations
|
|
@@ -407,6 +510,7 @@ Project the advertising fields while keeping the detailed description on the too
|
|
|
407
510
|
|
|
408
511
|
```ts
|
|
409
512
|
import type { ToolAnnotations } from '@orkestrel/tool'
|
|
513
|
+
import { objectShape, stringShape } from '@orkestrel/contract'
|
|
410
514
|
import { createTool, toolToDefinition } from '@orkestrel/tool'
|
|
411
515
|
|
|
412
516
|
const annotations: ToolAnnotations = { pure: true, untrusted: false, consequential: false }
|
|
@@ -415,6 +519,7 @@ const tool = createTool({
|
|
|
415
519
|
title: 'Echo',
|
|
416
520
|
description: 'Return the supplied value unchanged.',
|
|
417
521
|
summary: 'Echo a value.',
|
|
522
|
+
contract: objectShape({ value: stringShape() }),
|
|
418
523
|
annotations,
|
|
419
524
|
execute: (args) => args.value,
|
|
420
525
|
})
|
|
@@ -454,7 +559,7 @@ const tools = createToolManager({
|
|
|
454
559
|
clear: () => events.push('clear'),
|
|
455
560
|
},
|
|
456
561
|
})
|
|
457
|
-
tools.add(createTool({ name: 'echo', execute: (
|
|
562
|
+
tools.add(createTool({ name: 'echo', execute: () => 'original' }))
|
|
458
563
|
tools.add(createTool({ name: 'echo', execute: () => 'replacement' }))
|
|
459
564
|
tools.remove('echo')
|
|
460
565
|
tools.clear()
|
|
@@ -492,12 +597,12 @@ registers here unchanged.
|
|
|
492
597
|
## Tests
|
|
493
598
|
|
|
494
599
|
- [`guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` bijection, the `ToolInterface` ↔ `Tool` and `ToolManagerInterface` ↔ `ToolManager` method bijections, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `Anatomy of a tool` fence against the `@example` block of that title (pinned so the titled pair cannot be retired silently), and the README pitch against this guide's tagline. It also runs the flagship fences, including `Observe registry changes`, and asserts the values their comments claim against byte-equal transcriptions.
|
|
495
|
-
- [`Tool.test.ts`](../tests/src/core/tools/Tool.test.ts) — definition binding, optional-field omission,
|
|
496
|
-
- [`ToolManager.test.ts`](../tests/src/core/tools/ToolManager.test.ts) — insertion order, overwrite and removal lifecycle, definition projection, cancellation, context sharing, and isolated single and batch execution. Event proofs cover registration before `add`, ordered batch additions, the installed replacement during `remove`, `remove` before replacement `add`, synchronous replacement re-entry, a third instance a removal listener installs during a replacement, deletion before `remove`, silent missing names, ordered batch removals, populated and empty `clear` snapshots by identity, emitter destruction after clearing, an empty registry after teardown listeners re-add a tool, sibling delivery during mid-emission destruction, silent additions after destruction, and execution without registry events.
|
|
600
|
+
- [`Tool.test.ts`](../tests/src/core/tools/Tool.test.ts) — definition binding, optional-field omission, name and `parameters` refusal, context identity, the door over contracts, schemas, and undeclared tools, schema value and default-placement tables the door must never refuse, first-call compilation and the one read of a schema, the one read of each top-level argument, what a handler receives at each kind of node, the refusal text and its bound, the `strict: false` passthrough, error diagnostics, return values, and direct error propagation.
|
|
601
|
+
- [`ToolManager.test.ts`](../tests/src/core/tools/ToolManager.test.ts) — insertion order, overwrite and removal lifecycle, definition projection, malformed calls, cancellation, context sharing, and isolated single and batch execution. Event proofs cover registration before `add`, ordered batch additions, the installed replacement during `remove`, `remove` before replacement `add`, synchronous replacement re-entry, a third instance a removal listener installs during a replacement, deletion before `remove`, silent missing names, ordered batch removals, populated and empty `clear` snapshots by identity, emitter destruction after clearing, an empty registry after teardown listeners re-add a tool, sibling delivery during mid-emission destruction, silent additions after destruction, and execution without registry events.
|
|
497
602
|
- [`factories.test.ts`](../tests/src/core/factories.test.ts) — factory construction, working instances, initial registry hooks in publication order, sibling listener isolation, and listener-error forwarding.
|
|
498
|
-
- [`helpers.test.ts`](../tests/src/core/helpers.test.ts) — definition projection: summary preference, omitted optional keys, projected key order, schema identity, title and annotations forwarding, and a fresh object per call.
|
|
603
|
+
- [`helpers.test.ts`](../tests/src/core/helpers.test.ts) — definition projection: summary preference, omitted optional keys, projected key order, schema identity, title and annotations forwarding, and a fresh object per call; the door's report over parse faults, undeclared keys, unions, faults a union covers, the guard's fast path, and the fault limit; the walk of a path through a schema; the rendered path, list, and form; each refusal line and the bound on the whole text; the read of a call; and the malformed-call failure.
|
|
499
604
|
- [`validators.test.ts`](../tests/src/core/validators.test.ts) — tool-call envelope boundaries: incomplete calls, wrong field types, and non-record arguments.
|
|
500
|
-
- [`errors.test.ts`](../tests/src/core/errors.test.ts) — `isToolError` recognition, unrelated-value rejection, and hostile prototype containment.
|
|
605
|
+
- [`errors.test.ts`](../tests/src/core/errors.test.ts) — `isToolError` recognition, an `extra` fault in a report, the `cause` option, unrelated-value rejection, and hostile prototype containment.
|
|
501
606
|
|
|
502
607
|
## See also
|
|
503
608
|
|