@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.
Files changed (72) hide show
  1. package/dist/agents/skills/orkestrel-harden/scripts/interleave.js +539 -0
  2. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1163 -0
  3. package/dist/bin/main.js +21 -19
  4. package/dist/bin/main.js.map +1 -1
  5. package/dist/host/agents/orchestration.md +13 -7
  6. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -3
  7. package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +1 -1
  8. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +4 -2
  9. package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +2 -2
  10. package/dist/host/agents/skills/orkestrel-harden/SKILL.md +16 -3
  11. package/dist/host/agents/skills/orkestrel-harden/references/bindings.md +18 -12
  12. package/dist/host/agents/skills/orkestrel-harden/references/document.md +1 -0
  13. package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +2 -1
  14. package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +1 -1
  15. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +642 -0
  16. package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +665 -0
  17. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +14 -13
  18. package/dist/host/agents/skills/orkestrel-parallel/references/claude-code.md +13 -13
  19. package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +1 -0
  20. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1433 -0
  21. package/dist/host/agents/skills/orkestrel-publish/SKILL.md +2 -1
  22. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +18 -1
  23. package/dist/host/claude/AGENTS.md +1 -1
  24. package/dist/host/claude/agents/analyst.md +1 -1
  25. package/dist/host/claude/agents/builder.md +1 -1
  26. package/dist/host/claude/agents/distiller.md +2 -1
  27. package/dist/host/claude/agents/grok.md +2 -2
  28. package/dist/host/claude/agents/opus.md +2 -2
  29. package/dist/host/claude/agents/orkestrel.md +30 -30
  30. package/dist/host/claude/agents/reviewer.md +2 -2
  31. package/dist/host/claude/agents/scout.md +2 -1
  32. package/dist/host/claude/agents/verifier.md +1 -1
  33. package/dist/host/claude/rules/campaign.md +12 -11
  34. package/dist/host/claude/rules/documentation.md +1 -0
  35. package/dist/host/claude/rules/patterns.md +14 -0
  36. package/dist/host/claude/rules/quality.md +4 -1
  37. package/dist/host/claude/rules/tests.md +4 -0
  38. package/dist/host/claude/rules/writing.md +1 -1
  39. package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
  40. package/dist/host/codex/agents/analyst.toml +4 -1
  41. package/dist/host/codex/agents/astra.toml +1 -1
  42. package/dist/host/codex/agents/builder.toml +1 -1
  43. package/dist/host/codex/agents/distiller.toml +4 -2
  44. package/dist/host/codex/agents/grok.toml +5 -2
  45. package/dist/host/codex/agents/opus.toml +3 -3
  46. package/dist/host/codex/agents/reviewer.toml +6 -2
  47. package/dist/host/codex/agents/scout.toml +5 -1
  48. package/dist/host/codex/agents/verifier.toml +6 -1
  49. package/dist/host/guides/agent.md +1119 -457
  50. package/dist/host/guides/contract.md +226 -104
  51. package/dist/host/guides/database.md +12 -12
  52. package/dist/host/guides/ndjson.md +94 -21
  53. package/dist/host/guides/ollama.md +22 -18
  54. package/dist/host/guides/probe.md +29 -27
  55. package/dist/host/guides/reason.md +377 -114
  56. package/dist/host/guides/scaffold.md +43 -21
  57. package/dist/host/guides/study.md +538 -450
  58. package/dist/host/guides/tool.md +163 -58
  59. package/dist/host/manifest.json +70 -52
  60. package/dist/src/core/index.cjs +21 -20
  61. package/dist/src/core/index.cjs.map +1 -1
  62. package/dist/src/core/index.d.cts +1 -4
  63. package/dist/src/core/index.d.ts +1 -4
  64. package/dist/src/core/index.js +21 -20
  65. package/dist/src/core/index.js.map +1 -1
  66. package/dist/src/server/index.cjs +87 -8
  67. package/dist/src/server/index.cjs.map +1 -1
  68. package/dist/src/server/index.d.cts +50 -6
  69. package/dist/src/server/index.d.ts +50 -6
  70. package/dist/src/server/index.js +87 -10
  71. package/dist/src/server/index.js.map +1 -1
  72. package/package.json +15 -15
@@ -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. A configured contract validates arguments before its handler runs. A `ToolManager`
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 validates arguments; `parameters` alone remains descriptive. Caller identity
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 }` | Configures an executable tool. |
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 schema conflict or an argument validation failure. |
60
- | `ToolErrorContext` | interface | `{ faults? }` | Carries the structured faults behind an argument validation failure. |
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 [`helpers.ts`](../src/core/helpers.ts).
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 | Kind | Signature | Summary |
82
- | ------------------ | -------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
83
- | `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. |
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 | Summary |
102
- | ------------- | ----- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
103
- | `Tool` | class | `new (options: ToolOptions) => ToolInterface` | Binds an executable tool definition to a handler. |
104
- | `ToolManager` | class | `new (options?: ToolManagerOptions) => ToolManagerInterface` | Represents an insertion-ordered tool registry with per-call error isolation. |
105
- | `ToolError` | class | `new (code: ToolErrorCode, message: string, context?: ToolErrorContext) => ToolError` | Reports a schema conflict or argument validation failure with a machine-readable code. |
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. Without a
113
- contract, the argument record retains its identity too. A contract compiles at construction and
114
- derives the parameter schema through the contract package's projection. The compiled contract
115
- checks arguments before handler entry and supplies its parsed copy to the handler.
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`, and optional `context`. Direct tool execution throws an `ARGUMENTS` error with
135
- the full fault report in `context.faults`; the manager contains it as a message. Use `isToolError`
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 descriptive runtime data, forwarded by reference. Declaring
199
- `required` in that schema tells the caller what to send; it does not validate the payload. Use the
200
- `contract` option when the runtime must validate arguments.
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
- Without a contract, that record is the original input; with a contract, it is the parsed value.
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({ name: 'echo', execute: (args) => args.value }),
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 summary replaces the advertised
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 registered tool's contract, when configured, validates the arguments during execution.
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. An unknown name becomes `tool not found: <name>`; a synchronous throw and an
290
- asynchronous rejection are both contained; an `Error` contributes its `message`, and any other
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`; an undefined
347
- projection leaves parameters absent. Supplying `contract` and `parameters` together throws a
348
- `ToolError` with code `SCHEMA`.
349
-
350
- The contract's `explain` method reports parse faults before the handler runs. It accepts coercible
351
- values, such as a numeric string for a number. After a clean report, `Tool.execute` forwards
352
- `contract.parse(args)`: the owned, normalized copy in the schema's types, with undeclared keys
353
- dropped. A handler cannot rely on undeclared input keys being present. Without a contract, the
354
- raw argument record is forwarded unchanged. A parse fault throws `ToolError` with code
355
- `ARGUMENTS`. The message names the first fault's path and reason, then its expected and received
356
- values when the fault carries them; a constraint fault also names its constraint and limit when
357
- present. Array paths join with `.`; string paths stay unchanged. A root array path is empty, so
358
- its message starts with `: `. The error's `context.faults` holds the full report. A `variant` fault
359
- carries `variants`, appended as `; variants <n>`; a `oneOf` fault carries `matched`, appended as
360
- `; matched <n>`. A missing field carries expected alone. Contract construction errors from the
361
- dependency propagate unchanged. If parsing returns a value that isn't a record after a clean
362
- explanation, execution throws `ToolError` with code `ARGUMENTS` and message
363
- `Arguments did not parse`, without `context`, before handler entry.
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?.[0]?.reason // 'type'
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`; it carries the message rather
396
- than the error instance or fault report. `ToolError` extends `Error`, exposes its readonly `code`
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: (args) => args.value }))
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, argument and context identity, contract validation, error diagnostics, return values, and direct error propagation.
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