@orkestrel/scaffold 0.0.123 → 0.0.125

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 (51) hide show
  1. package/dist/agents/skills/orkestrel-publish/scripts/steps.js +523 -0
  2. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +70 -11
  3. package/dist/bin/main.js +18 -18
  4. package/dist/bin/main.js.map +1 -1
  5. package/dist/host/agents/orchestration.md +5 -1
  6. package/dist/host/agents/platforms/windows.md +9 -1
  7. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +1 -1
  8. package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +1 -0
  9. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +30 -2
  10. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -0
  11. package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +5 -1
  12. package/dist/host/agents/skills/orkestrel-publish/SKILL.md +1 -0
  13. package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
  14. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +23 -6
  15. package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +654 -0
  16. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +79 -14
  17. package/dist/host/claude/agents/orkestrel.md +45 -45
  18. package/dist/host/claude/rules/patterns.md +1 -1
  19. package/dist/host/claude/rules/portability.md +2 -0
  20. package/dist/host/claude/rules/quality.md +3 -1
  21. package/dist/host/claude/rules/tests.md +3 -1
  22. package/dist/host/guides/agent.md +349 -244
  23. package/dist/host/guides/brief.md +52 -48
  24. package/dist/host/guides/browser.md +2 -2
  25. package/dist/host/guides/contract.md +226 -104
  26. package/dist/host/guides/database.md +12 -12
  27. package/dist/host/guides/interpret.md +531 -155
  28. package/dist/host/guides/mcp.md +183 -61
  29. package/dist/host/guides/ndjson.md +47 -34
  30. package/dist/host/guides/ollama.md +123 -66
  31. package/dist/host/guides/program.md +117 -39
  32. package/dist/host/guides/qualifier.md +110 -59
  33. package/dist/host/guides/rater.md +85 -32
  34. package/dist/host/guides/reason.md +377 -114
  35. package/dist/host/guides/scaffold.md +20 -12
  36. package/dist/host/guides/study.md +580 -483
  37. package/dist/host/guides/tool.md +163 -58
  38. package/dist/host/guides/toolbox.md +159 -80
  39. package/dist/host/guides/workflow.md +44 -25
  40. package/dist/host/manifest.json +41 -35
  41. package/dist/src/core/index.cjs +17 -17
  42. package/dist/src/core/index.cjs.map +1 -1
  43. package/dist/src/core/index.js +17 -17
  44. package/dist/src/core/index.js.map +1 -1
  45. package/dist/src/server/index.cjs +23 -11
  46. package/dist/src/server/index.cjs.map +1 -1
  47. package/dist/src/server/index.d.cts +10 -6
  48. package/dist/src/server/index.d.ts +10 -6
  49. package/dist/src/server/index.js +23 -11
  50. package/dist/src/server/index.js.map +1 -1
  51. package/package.json +17 -17
@@ -290,8 +290,9 @@ claim this server does not implement the revision it does implement.
290
290
  its errors in band, byte-identically to what a `2025-06-18` client already expects. A
291
291
  modern result maps to real statuses: `202` for a notification, `400` for `-32020` /
292
292
  `-32021` / `-32022` / `-32602`, `404` for `-32601`, and `200` otherwise. A
293
- transport-level failure — malformed JSON or a body that is not a JSON-RPC request — is
294
- `400` under both eras, because no era was ever established. See
293
+ transport-level failure — malformed JSON or an invalid request body — is
294
+ `400` under both eras, because no era was ever established. A response or a malformed
295
+ notification is accepted with `202` and no body, using the same classification as `handle`. See
295
296
  [Route a request by era and build a modern result](#route-a-request-by-era-and-build-a-modern-result)
296
297
  for the inferers this rides on.
297
298
 
@@ -305,7 +306,17 @@ import { createMCPServer } from '@orkestrel/mcp'
305
306
  import { createTool, createToolManager } from '@orkestrel/tool'
306
307
 
307
308
  const tools = createToolManager()
308
- tools.add(createTool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }))
309
+ tools.add(
310
+ createTool({
311
+ name: 'add',
312
+ parameters: {
313
+ type: 'object',
314
+ properties: { x: { type: 'number' }, y: { type: 'number' } },
315
+ required: ['x', 'y'],
316
+ },
317
+ execute: (a) => Number(a.x) + Number(a.y),
318
+ }),
319
+ )
309
320
 
310
321
  const server = createMCPServer({ identity: { name: 'calculator', version: '1.0.0' }, tools })
311
322
  server.emitter.on('request', (method, id, era) => log(method, id, era))
@@ -314,12 +325,12 @@ server.emitter.on('request', (method, id, era) => log(method, id, era))
314
325
  const reply = await server.handle(
315
326
  '{"jsonrpc":"2.0","method":"tools/list","id":1,"params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}',
316
327
  )
317
- // reply → '{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"add","inputSchema":{"type":"object"}}]}}'
328
+ // reply → '{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"add","inputSchema":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"]}}]}}'
318
329
 
319
330
  const out = await server.handle(
320
331
  '{"jsonrpc":"2.0","method":"tools/call","id":2,"params":{"name":"add","arguments":{"x":2,"y":5},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}',
321
332
  )
322
- // out → '…"result":{"content":[{"type":"text","text":"7"}],"structuredContent":7}}'
333
+ // out → '…"result":{"content":[{"type":"text","text":"7"}],"resultType":"complete",…}}'
323
334
  ```
324
335
 
325
336
  `dispatch` is the typed core; `handle` wraps it with the `JSON.parse` ↔
@@ -330,11 +341,18 @@ graph. A call with no `id` is a **notification** — a type of its own, handled
330
341
  (the `request` event still fires) but yielding no response (`dispatch` resolves
331
342
  `undefined`, `handle` returns `undefined`), whatever its method. The error
332
343
  envelopes carry `id: null` for the id they could not read, as JSON-RPC 2.0 § 5
333
- requires. Tool errors
344
+ requires, and a malformed request's `-32600` carries the id it could read. A stray response and
345
+ a malformed notification are not answered, and reach the `error` event. Tool errors
334
346
  are not protocol errors: the `ToolManager` (`@orkestrel/tool`) isolates a
335
347
  thrown tool into a `success: false` result, which `tools/call` maps to an
336
348
  `isError: true` tool result carrying its `error` text — so the server wraps
337
- no tool-domain failure as a protocol error. A rejected execution provider or
349
+ no tool-domain failure as a protocol error. An unknown tool is one: `tools/call` answers
350
+ `-32602` with `Unknown tool:`, the name, and at most `REFUSAL_LIST_LIMIT` of the available names,
351
+ before any input policy or `execution` port runs. A refused argument record is one of those
352
+ failures: the specification, revision 2025-11-25, Tools § Error Handling, reports input
353
+ validation in a tool result so a model can correct and retry, and the text `Tool` refuses with
354
+ says what to send. An in-process caller reads the same report from a `ToolError`'s
355
+ `context.faults`. A rejected execution provider or
338
356
  malformed runtime result instead becomes a detail-free `-32603` response, and the
339
357
  value that was caught is reported on the server's `error` event — the one place it
340
358
  is legible, and never the wire.
@@ -363,8 +381,8 @@ invalid input carries `id: null`.
363
381
  **A JSON-RPC result is any value, and an MCP result is an object.** The `result` member of
364
382
  `@orkestrel/jsonrpc`'s `JSONRPCResultResponse` type is `unknown`, so narrow it with
365
383
  `isMCPResult` or `isMCPLegacyResult` before reading it. `HTTPClientTransport` delivers an
366
- `application/json` reply whose `result` is a primitive, and `MCPClient` reports that reply on
367
- `error` as a malformed message. When a legacy peer answers a correlated request with a primitive
384
+ `application/json` reply whose `result` is a primitive, and `MCPClient` rejects the request it
385
+ answers with an `MCPError`, and reports one that answers no pending request on `error`. When a legacy peer answers a correlated request with a primitive
368
386
  `result`, `MCPLegacyClientTransport` answers that request with a `-32603` error response.
369
387
 
370
388
  ```ts
@@ -641,6 +659,7 @@ result shape for them. See
641
659
  | `MCP_SENTINEL_SUFFIX` | const | `"?="` | Names the closing marker of the Base64 sentinel a standard MCP header value travels in. |
642
660
  | `MCP_PARAM_PREFIX` | const | `"Mcp-Param-"` | Names the request-header prefix an `x-mcp-header` annotation projects a tool argument onto. |
643
661
  | `MCP_HEADER_ANNOTATION` | const | `"x-mcp-header"` | Identifies the tool-schema annotation key naming the header one parameter projects into. |
662
+ | `MCP_LIST_PAGES` | const | `64` | Bounds the `tools/list` pages a client reads into one listing. |
644
663
  | `MCP_LOOKUP_PAGES` | const | `8` | Bounds the `tools/list` pages one modern `tools/call` walks to reach its own annotations. |
645
664
  | `MCP_HEADER_MISMATCH` | const | `-32020` | Names the MCP reserved error for required HTTP metadata that does not match the request body. |
646
665
  | `MCP_MISSING_CAPABILITY` | const | `-32021` | Names the MCP reserved error for an operation needing a client capability that was not declared. |
@@ -749,10 +768,10 @@ result shape for them. See
749
768
  | `buildToolDescriptors` | function | `(manager: ToolManagerInterface) => readonly MCPToolDescriptor[]` | Maps a `ToolManagerInterface`'s definitions to MCP `tools/list` descriptors — renaming `parameters` to the wire's `inputSchema`. |
750
769
  | `toolAnnotationsToMCP` | function | `(annotations: ToolAnnotations) => MCPToolAnnotations` | Projects domain tool annotations onto MCP wire hints without inventing defaults. |
751
770
  | `mcpAnnotationsToTool` | function | `(annotations: MCPToolAnnotations) => ToolAnnotations` | Projects MCP wire hints onto domain tool annotations without inventing defaults. |
752
- | `buildToolCall` | function | `(request: JSONRPCRequest, args?: Readonly<Record<string, unknown>>) => ToolCall \| undefined` | Builds the canonical Tool call for one validated MCP `tools/call` request. |
771
+ | `buildToolCall` | function | `(request: JSONRPCRequest, args: Readonly<Record<string, unknown>>) => ToolCall \| undefined` | Builds the canonical Tool call for one validated MCP `tools/call` request. |
753
772
  | `buildProgressNotification` | function | `(token: string \| number, progress: MCPProgress) => JSONRPCNotification` | Builds one official progress notification for the original request stream. |
754
773
  | `buildCancelledNotification` | function | `(id: JSONRPCId, reason?: string) => JSONRPCNotification` | Builds one official cancellation notification for a request already sent. |
755
- | `buildCallOutcome` | function | `(name: string, result: unknown) => MCPCallOutcome` | Narrows one `tools/call` answer to the arm the peer chose. |
774
+ | `buildCallOutcome` | function | `(name: string, result: unknown, output?: ContractInterface<unknown>) => MCPCallOutcome` | Narrows one `tools/call` answer to the arm the peer chose. |
756
775
  | `extractContentText` | function | `(result: unknown) => string` | Concatenates an MCP tool-call result's text content blocks into one string. |
757
776
  | `matchesResultType` | function | `(method: string, resultType: unknown) => boolean` | Determines whether one method may answer with a given modern `resultType`. |
758
777
  | `snapshotJSON` | function | `(value: unknown, limits: MCPJSONLimitOptions) => readonly [value: JSONValue, text: string] \| undefined` | Snapshots one bounded exact JSON value together with its canonical wire serialization. The returned value is an owned, deeply frozen graph reconstructed from the canonical text; the frozen tuple shares no mutable structure with the input. Invalid exact-JSON shapes, hostile reflection, serialization failures, and values outside the byte, key, or depth limits return `undefined`. |
@@ -774,6 +793,12 @@ result shape for them. See
774
793
  | `decodeBoundedMessage` | function | `(message: string, limits: MCPJSONLimitOptions) => JSONRPCMessage \| undefined` | Decodes one raw inbound message within an explicit bound — the decode a binder performs before it hands the string on. |
775
794
  | `deliverMessage` | function | `(emitter: EmitterInterface<MCPMessageTransportEventMap>, text: string, fault: string) => void` | Decodes one inbound frame and delivers it onto a transport emitter as `message` or `error`. |
776
795
  | `readCancelledId` | function | `(message: JSONRPCMessage) => JSONRPCId \| undefined` | Reads the request id an inbound `notifications/cancelled` names — the inverse of `buildCancelledNotification`. |
796
+ | `readToolPage` | function | `(result: unknown) => MCPToolPage` | Reads one `tools/list` answer as a page of tools, refusing a listing it cannot read. |
797
+ | `extractMessageId` | function | `(value: unknown) => JSONRPCId \| undefined` | Extracts the JSON-RPC id one unread message carries, when it carries a valid one. |
798
+ | `extractInvalidRequestId` | function | `(value: unknown) => JSONRPCId \| null \| undefined` | Extracts the id a `-32600` answer to one parsed value that is not an invocation goes under. |
799
+ | `buildParseFault` | function | `(message: string) => MCPError` | Builds the transport fault for one inbound frame that is not JSON, which answers under `null`. |
800
+ | `buildInboundAnswer` | function | `(fault: unknown) => JSONRPCErrorResponse \| undefined` | Builds the JSON-RPC error a server transport writes for one fault its carrier reported. |
801
+ | `buildInboundFault` | function | `(value: unknown, fault: string) => MCPError` | Builds the transport fault for one inbound value that is not the message its receiver takes. |
777
802
  | `decodeSentinel` | function | `(value: string) => string \| undefined` | Reads the value one standard MCP request header carries, decoding the Base64 sentinel. |
778
803
  | `encodeSentinel` | function | `(value: string) => string` | Builds the wire form one standard MCP request header value must travel as. |
779
804
  | `isFieldToken` | function | `(value: unknown) => value is string` | Determines whether a value is one RFC 9110 field token. |
@@ -832,7 +857,7 @@ isMCPToolAnnotations({ readOnlyHint: false }) // true
832
857
  | `MCPBlobResource` | interface | `{ uri, mimeType?, _meta?, blob }` | Represents embedded base64-encoded resource contents. |
833
858
  | `MCPEmbeddedResource` | interface | `{ type, resource, annotations?, _meta? }` | Represents an MCP content block carrying embedded text or blob resource contents. |
834
859
  | `MCPContent` | type | `MCPTextContent \| MCPImageContent \| MCPAudioContent \| MCPResourceLink \| MCPEmbeddedResource` | Represents one exact dated-schema tool content block. |
835
- | `MCPUnstampedCallResult` | type | `{ readonly content: readonly MCPContent[]; readonly structuredContent?: JSONValue; readonly isError?: boolean; readonly _meta?: MCPResultMetaObject; }` | Represents a `tools/call` result before the modern stamp — the executed tool's output as `content` blocks, with `isError` flagging a tool failure. |
860
+ | `MCPUnstampedCallResult` | type | `{ readonly content: readonly MCPContent[]; readonly structuredContent?: Readonly<Record<string, JSONValue>>; readonly isError?: boolean; readonly _meta?: MCPResultMetaObject; }` | Represents a `tools/call` result before the modern stamp — the executed tool's output as `content` blocks, with `isError` flagging a tool failure. |
836
861
  | `MCPCallResult` | type | `MCPUnstampedCallResult & { readonly resultType: 'complete'; }` | Represents a required complete modern `tools/call` result. |
837
862
  | `MCPPaginationParams` | interface | `{ cursor? }` | Represents the cursor parameters shared by every paginated modern list method. |
838
863
  | `MCPPaginationResult` | interface | `{ nextCursor? }` | Represents the cursor result fields shared by every paginated modern list method. |
@@ -909,6 +934,8 @@ isMCPToolAnnotations({ readOnlyHint: false }) // true
909
934
  | `MCPListResult` | type | `{ readonly tools: readonly MCPToolDescriptor[]; readonly resultType: 'complete'; readonly ttlMs: number; readonly cacheScope: 'public' \| 'private'; readonly _meta?: MCPResultMetaObject; }` | Represents the MCP `tools/list` result — tool descriptors plus optional modern result stamps. |
910
935
  | `MCPToolAnnotations` | interface | `{ title?, readOnlyHint?, destructiveHint?, idempotentHint?, openWorldHint? }` | Describes tool hints using the MCP 2026-07-28 specification's wire field names. |
911
936
  | `MCPToolDescriptor` | interface | `{ name, title?, description?, inputSchema, annotations? }` | Represents one entry of the MCP `tools/list` result with its display metadata and JSON-Schema input. |
937
+ | `MCPListedTool` | type | `Readonly<Record<string, unknown>> & Pick<MCPToolDescriptor, 'name' \| 'inputSchema'>` | Holds one `tools/list` entry past the members a client refuses a listing without. |
938
+ | `MCPToolPage` | interface | `{ tools, nextCursor? }` | Holds one `tools/list` page a client has read. |
912
939
  | `MCPHeaderPrimitive` | type | `'boolean' \| 'integer' \| 'string'` | Names the JSON Schema types an `x-mcp-header` annotation may sit on. |
913
940
  | `MCPHeaderParameter` | interface | `{ name, path, primitive }` | Represents one `x-mcp-header` projection a tool's `inputSchema` declares. |
914
941
  | `MCPIdentity` | type | `MCPMetaObject & { readonly name: string; readonly version: string; readonly title?: string; readonly description?: string; readonly websiteUrl?: string; readonly icons?: readonly MCPIcon[]; }` | Represents the complete dated identity of an MCP server or client. |
@@ -1048,9 +1075,12 @@ so `caller` stays an HTTP-face seam.
1048
1075
  request body through `mcp.dispatch`. For a streamed response,
1049
1076
  `MCPDispatchOptions.signal` composes the fetch-standard request signal with
1050
1077
  response-stream cancellation; the optional session middleware preserves the request
1051
- signal when it rebuilds a buffered POST. A malformed JSON body, or a parsed value
1052
- that is not a JSON-RPC request, is an HTTP `400` carrying a JSON-RPC error
1053
- body (`-32700` / `-32600`, with `id: null`). Legacy dispatch results retain uniform
1078
+ signal when it rebuilds a buffered POST. A malformed JSON body or an invalid request
1079
+ is an HTTP `400` carrying a JSON-RPC error body (`-32700` / `-32600`). The error
1080
+ carries `id: null` unless a malformed request has a readable id. An object with neither
1081
+ invocation nor response members, including `{}`, receives `-32600` under `null`.
1082
+ A response or a malformed notification receives HTTP `202` with no body, matching
1083
+ the silence of `handle` and stdio. Legacy dispatch results retain uniform
1054
1084
  HTTP `200` with in-band errors. Modern responses use `202` for notifications,
1055
1085
  `400` for `-32020` / `-32021` / `-32022` / `-32602`, `404` for `-32601`, and
1056
1086
  `200` otherwise. A unary reply is framed as one `@orkestrel/server` `createStream`
@@ -2156,7 +2186,8 @@ The `tasks` data member is the stable Tasks extension's client half — see
2156
2186
  `tools()` returns a snapshot. The wire preserves `title`, the advertised `description`,
2157
2187
  `inputSchema` (wrapped as `parameters`), and the mapped `annotations`. The server maps
2158
2188
  `pure` to `readOnlyHint` and `consequential` to `destructiveHint`; the client applies the
2159
- inverse projection. For a schema-less tool, the wire adds `inputSchema: { type: 'object' }`.
2189
+ inverse projection. A tool that declares nothing advertises the closed empty object
2190
+ `CLOSED_PARAMETERS` from `@orkestrel/tool`, so a call that sends it a key is refused.
2160
2191
  `untrusted` has no MCP counterpart. Unmapped hints remain absent from
2161
2192
  the wrapped tool, and omitted hints receive no invented defaults. These hints do not authorize
2162
2193
  execution. The wire loses `summary` as a separate field and, when a summary was authored,
@@ -2165,6 +2196,36 @@ The wrapped tool forwards `context.signal` into `call`, so agent-side abort reac
2165
2196
  remote request. Refresh snapshots explicitly between agent runs; see
2166
2197
  [Refresh the tools an agent holds](#refresh-the-tools-an-agent-holds).
2167
2198
 
2199
+ **A listing is complete or refused.** `tools()` follows `nextCursor` for up to `MCP_LIST_PAGES`
2200
+ pages and throws an `MCPError` when an answer is not an object, `tools` is not an array, an entry
2201
+ lacks a non-empty `name` with no surrounding space or a record `inputSchema`, a present
2202
+ `outputSchema` is not a record, a `nextCursor` is neither a string nor `null`, a cursor repeats, or
2203
+ a cursor is present on the last page it reads, because a cut listing would read as complete. A
2204
+ `null` or empty cursor reads as the end of the listing. The refusal names the entry's index.
2205
+
2206
+ **A wrapped tool enforces the remote `inputSchema` before it calls.** The schema enters through the
2207
+ lenient `schemaToShape` conversion on the wrapped tool's first `execute`, which widens what it
2208
+ cannot read and never narrows, so the remote server stays the authority on what remains. A
2209
+ refusal throws a `ToolError` with code `ARGUMENTS` and writes nothing to the transport.
2210
+
2211
+ **A tool's own error always reaches the caller.** `isError: true` throws `MCPToolError` before any
2212
+ block is validated, carrying the text of whichever blocks read, or a bare string `content`, because
2213
+ that message is what a model corrects from.
2214
+
2215
+ **A complete answer must be readable.** On a success, `call` throws an `MCPError` for a non-boolean
2216
+ `isError`, a `content` that is not a list of valid blocks, and a result carrying neither `content`
2217
+ nor an object `structuredContent`. `content: []` reads as a value of `undefined`. The specification,
2218
+ revision 2025-11-25, defines `structuredContent` as a JSON object, so `MCPServer` sets it only for a
2219
+ record value, the text carrying every other value, and `call` reads any other value there as absent
2220
+ and falls back to the text, because refusing it would lose a real answer from a sloppy server.
2221
+
2222
+ **A declared `outputSchema` binds the answer.** After `tools()` has read this connection's listing,
2223
+ a tool declaring an `outputSchema` must answer an object `structuredContent` the `is` guard of that
2224
+ schema's lenient conversion accepts. A miss throws an `MCPError` whose `context.faults` holds the
2225
+ audit, and its message says when the result carried no `structuredContent` object at all. A failure owes no value, so `isError: true` still throws
2226
+ `MCPToolError`. A `call` made before any listing knows no schema and checks none, and a new
2227
+ connection starts with none.
2228
+
2168
2229
  **Every session-bound request refuses at once while the client holds no connection.** `call`,
2169
2230
  `tools`, each `tasks/*` method reached through `client.tasks`, and a `listen` stream all carry
2170
2231
  the same refusal, because they all issue through one correlated-request door. A client that has
@@ -2640,10 +2701,13 @@ The `adopt` method excludes a tool carrying `annotations.debugging: true` unless
2640
2701
  `adopt({ debug: true })`. A false or omitted hint leaves the tool included either way;
2641
2702
  the `origins` option continues to filter which registrations the registry returns.
2642
2703
 
2643
- **An adopted tool validates nothing.** It advertises the foreign `inputSchema` as its
2644
- `parameters` and forwards the arguments it is given. Compiling that schema into a contract
2645
- would let one page's unreadable or hostile schema refuse the whole `adopt` call, and the
2646
- arguments reach a handler in another document that has to validate them anyway.
2704
+ **An adopted tool enforces the foreign schema.** It advertises the foreign `inputSchema` as its
2705
+ `parameters` and enforces it through the lenient `schemaToShape` conversion on its first `execute`,
2706
+ so a schema record it cannot read refuses that tool's calls rather than the whole `adopt` call. A
2707
+ foreign tool with no `inputSchema` declares nothing and takes nothing. A tool no local `Tool` can be
2708
+ built from, a non-record `inputSchema` or a name with surrounding space, rejects the whole `adopt`
2709
+ call with a `ToolError`. The handler in the other document stays the authority on whatever the
2710
+ conversion widens.
2647
2711
 
2648
2712
  The bridge exposes these methods.
2649
2713
 
@@ -2736,10 +2800,25 @@ tools.add(
2736
2800
  createTool({
2737
2801
  name: 'search',
2738
2802
  description: 'Search the docs',
2803
+ parameters: {
2804
+ type: 'object',
2805
+ properties: { query: { type: 'string' } },
2806
+ required: ['query'],
2807
+ },
2739
2808
  execute: (a) => find(String(a.query)),
2740
2809
  }),
2741
2810
  )
2742
- tools.add(createTool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }))
2811
+ tools.add(
2812
+ createTool({
2813
+ name: 'add',
2814
+ parameters: {
2815
+ type: 'object',
2816
+ properties: { x: { type: 'number' }, y: { type: 'number' } },
2817
+ required: ['x', 'y'],
2818
+ },
2819
+ execute: (a) => Number(a.x) + Number(a.y),
2820
+ }),
2821
+ )
2743
2822
 
2744
2823
  const server = createMCPServer({ identity: { name: 'docs', version: '1.0.0' }, tools })
2745
2824
  server.emitter.on('request', (method, id) => log(method, id))
@@ -2754,7 +2833,7 @@ for await (const message of transport) {
2754
2833
  const listed = await server.handle(
2755
2834
  '{"jsonrpc":"2.0","method":"tools/list","id":1,"params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}',
2756
2835
  )
2757
- // listed → '{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"search","inputSchema":{"type":"object"},"description":"Search the docs"},{"name":"add","inputSchema":{"type":"object"}}],"resultType":"complete","ttlMs":60000,"cacheScope":"private","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"docs","version":"1.0.0"}}}}'
2836
+ // listed → '{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"search","inputSchema":{"type":"object","properties":{"query":{"type":"string"}},"required":["query"]},"description":"Search the docs"},{"name":"add","inputSchema":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"]}}],"resultType":"complete","ttlMs":60000,"cacheScope":"private","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"docs","version":"1.0.0"}}}}'
2758
2837
  ```
2759
2838
 
2760
2839
  ### Refresh the tools an agent holds
@@ -3144,7 +3223,17 @@ import { createScopeServer } from '@orkestrel/mcp/browser'
3144
3223
  import { createTool, createToolManager } from '@orkestrel/tool'
3145
3224
 
3146
3225
  const tools = createToolManager()
3147
- tools.add(createTool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }))
3226
+ tools.add(
3227
+ createTool({
3228
+ name: 'add',
3229
+ parameters: {
3230
+ type: 'object',
3231
+ properties: { x: { type: 'number' }, y: { type: 'number' } },
3232
+ required: ['x', 'y'],
3233
+ },
3234
+ execute: (a) => Number(a.x) + Number(a.y),
3235
+ }),
3236
+ )
3148
3237
  const worker = createScopeServer({ tools, name: 'worker-mcp', version: '1.0.0' })
3149
3238
  // ... on teardown:
3150
3239
  worker.stop()
@@ -3205,7 +3294,17 @@ const scope = {
3205
3294
  }
3206
3295
 
3207
3296
  const tools = createToolManager()
3208
- tools.add(createTool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }))
3297
+ tools.add(
3298
+ createTool({
3299
+ name: 'add',
3300
+ parameters: {
3301
+ type: 'object',
3302
+ properties: { x: { type: 'number' }, y: { type: 'number' } },
3303
+ required: ['x', 'y'],
3304
+ },
3305
+ execute: (a) => Number(a.x) + Number(a.y),
3306
+ }),
3307
+ )
3209
3308
  const worker = createScopeServer({ tools, name: 'worker-mcp', version: '1.0.0' }, scope)
3210
3309
 
3211
3310
  const { port1, port2 } = new MessageChannel()
@@ -3219,7 +3318,7 @@ port2.postMessage(
3219
3318
  '{"jsonrpc":"2.0","method":"tools/list","id":1,"params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}',
3220
3319
  )
3221
3320
 
3222
- log(await reply) // '{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"add","inputSchema":{"type":"object"}}]}}'
3321
+ log(await reply) // '{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"add","inputSchema":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"]}}]}}'
3223
3322
  worker.stop() // unbinds every binding, closes every accepted MessagePort
3224
3323
  ```
3225
3324
 
@@ -3884,12 +3983,12 @@ digesting, or execution. Whichever it is, one reference then reaches the argumen
3884
3983
  the input selector, the canonical `ToolCall`, and the executor — no step re-snapshots, so no
3885
3984
  step can be looking at a different value from another.
3886
3985
 
3887
- That record is shared and frozen, which is worth knowing before it surprises you: a tool
3888
- that writes to its own `arguments` now throws, and because the registry isolates a thrown tool
3889
- into a `success: false` result, the client sees an ordinary `isError: true` tool result with
3890
- no protocol change to point at. Refusing a mutation of server-owned input is a tool-domain
3891
- failure rather than a protocol fault, so that is where it is reported. A tool that needs a
3892
- mutable bag copies first: `const working = { ...args }`.
3986
+ A `Tool` hands its handler `contract.parse(args)`, an owned copy, so only a tool built with
3987
+ `strict: false` sees that record. It is shared and frozen, which is worth knowing before it
3988
+ surprises you: a raw tool that writes to its own `arguments` throws, and the client sees an
3989
+ ordinary `isError: true` tool result with no protocol change to point at. Refusing a mutation of
3990
+ server-owned input is a tool-domain failure rather than a protocol fault, so that is where it is
3991
+ reported. A raw tool that needs a mutable bag copies first: `const working = { ...args }`.
3893
3992
 
3894
3993
  The reporter exists only when `_meta.progressToken` is a string or integer.
3895
3994
  `report` requires a bounded payload with finite, strictly increasing values and awaits
@@ -3935,7 +4034,7 @@ const server = createMCPServer({
3935
4034
  { type: 'text', text: 'Preview' },
3936
4035
  { type: 'image', data: 'iVBORw0KGgo=', mimeType: 'image/png' },
3937
4036
  ],
3938
- structuredContent: ['preview', 1],
4037
+ structuredContent: { slides: 1 },
3939
4038
  }
3940
4039
  },
3941
4040
  })
@@ -3992,12 +4091,15 @@ import {
3992
4091
 
3993
4092
  const limits = { bytes: 4096, keys: 64, depth: 16 }
3994
4093
  const parameters = { prompt: 'owl' }
3995
- const call = buildToolCall({
3996
- jsonrpc: '2.0',
3997
- id: 1,
3998
- method: 'tools/call',
3999
- params: { name: 'render', arguments: parameters },
4000
- })
4094
+ const call = buildToolCall(
4095
+ {
4096
+ jsonrpc: '2.0',
4097
+ id: 1,
4098
+ method: 'tools/call',
4099
+ params: { name: 'render', arguments: parameters },
4100
+ },
4101
+ parameters,
4102
+ )
4001
4103
  const canonical = serializeJSON(parameters, limits)
4002
4104
  const digest = await digestJSON(parameters, limits)
4003
4105
  const notification = buildProgressNotification('render-1', { progress: 1, total: 2 })
@@ -4120,7 +4222,7 @@ import { createMCPContinuation } from '@orkestrel/mcp/server'
4120
4222
  import { createTool, createToolManager } from '@orkestrel/tool'
4121
4223
 
4122
4224
  const tools = createToolManager()
4123
- tools.add(createTool({ name: 'reply', execute: (input) => input }))
4225
+ tools.add(createTool({ name: 'reply', parameters: { type: 'object' }, execute: (input) => input }))
4124
4226
 
4125
4227
  const server = createMCPServer({
4126
4228
  identity: { name: 'supervisor', version: '1.0.0' },
@@ -4386,7 +4488,7 @@ import {
4386
4488
  import { createTool, createToolManager } from '@orkestrel/tool'
4387
4489
 
4388
4490
  const tools = createToolManager()
4389
- tools.add(createTool({ name: 'render', execute: (input) => input }))
4491
+ tools.add(createTool({ name: 'render', parameters: { type: 'object' }, execute: (input) => input }))
4390
4492
 
4391
4493
  const server = createMCPServer({
4392
4494
  identity: { name: 'supervisor', version: '1.0.0' },
@@ -4655,7 +4757,17 @@ serverSide.connect(clientSide)
4655
4757
  clientSide.connect(serverSide)
4656
4758
 
4657
4759
  const tools = createToolManager()
4658
- tools.add(createTool({ name: 'add', execute: (a) => Number(a.x) + Number(a.y) }))
4760
+ tools.add(
4761
+ createTool({
4762
+ name: 'add',
4763
+ parameters: {
4764
+ type: 'object',
4765
+ properties: { x: { type: 'number' }, y: { type: 'number' } },
4766
+ required: ['x', 'y'],
4767
+ },
4768
+ execute: (a) => Number(a.x) + Number(a.y),
4769
+ }),
4770
+ )
4659
4771
  const server = createMCPServer({ identity: { name: 'calculator', version: '1.0.0' }, tools })
4660
4772
  bindServer(server, serverSide)
4661
4773
 
@@ -4984,7 +5096,7 @@ consumer can plan around it instead of discovering it.
4984
5096
  | A built-in resource or prompt store | The `resources` / `prompts` / `completion` capabilities ship as ports, exactly as tools and durable tasks do. What backs one — a workspace, a database, a template registry, a plain object — is the host's decision, and a default store here would be product policy wearing a framework's clothes. |
4985
5097
  | Server-initiated `elicitation/create` requests | 2026-07-28 removes server-initiated requests entirely. Input requests survive only inside a modern `tools/call` `input_required` result — see [Ask the client for input during the call in hand](#ask-the-client-for-input-during-the-call-in-hand). |
4986
5098
  | Durable task or session storage | Task state outlives the request that created it and this package owns no persistence. The store arrives injected as `MCPTaskOptions.tasks`, exactly as `ToolManagerInterface` does — the extension's protocol ships here, its durability does not. |
4987
- | `outputSchema` on tool descriptors | `ToolResult.value` (`@orkestrel/tool`) is `unknown`; the contract that owns the value owns its schema. `structuredContent` is produced without one, which no clause gates. |
5099
+ | `outputSchema` on this server's tool descriptors | `ToolResult.value` (`@orkestrel/tool`) is `unknown`; the contract that owns the value owns its schema. `structuredContent` is produced without one, which no clause gates. `MCPClient` does enforce one a remote server declares. |
4988
5100
  | Icons (2025-11-25) | Installed `@orkestrel/tool` definitions carry no icon field, so an MCP-only wrapper would have no originating consumer. |
4989
5101
  | Withholding a consumer's own invalidly annotated tool from `tools/list` | The annotation is read and enforced on both sides; see [Protocol](#protocol) for the rules. The exclusion MUST binds an HTTP client, and this package's client transports honour it. A server that also dropped the definition would hide a consumer's tool from every peer over a mistake in one property, so this one serves it, recognizes no `Mcp-Param-*` name for it, and lets each conformant client exclude it. |
4990
5102
  | `_meta['io.modelcontextprotocol/logLevel']` | The deprecated canonical value is validated as request metadata, but no consumer opts a request into server log emission. |
@@ -5556,25 +5668,26 @@ the exact statement:
5556
5668
  client asking to `initialize` at `'2026-07-28'` is asking to negotiate a
5557
5669
  revision that defines no negotiation, and the client decides what to do with
5558
5670
  the legacy answer it gets. `ping` → `{}`. `tools/list` → `{ tools }`, each tool a
5559
- `MCPToolDescriptor` (its `parameters` renamed to `inputSchema`,
5560
- defaulting to `{ type: 'object' }`). `tools/call` → the executed
5671
+ `MCPToolDescriptor` (its `parameters` renamed to `inputSchema`, a tool
5672
+ that declares none advertising the closed empty object). `tools/call` → the executed
5561
5673
  tool's `MCPCallResult`.
5562
5674
  5. **Tool errors are tool results, not protocol errors.** `tools/call` reads
5563
5675
  `params.name` (a string) + `params.arguments` (a record; the modern path defaults an
5564
5676
  absent one to the shared frozen `EMPTY_MCP_ARGUMENTS`),
5565
5677
  narrowed with `@orkestrel/contract`'s guards (no `as`); a missing /
5566
- non-string `name` → a `-32602` invalid-params error. Otherwise it runs
5678
+ non-string `name` → a `-32602` invalid-params error, and so does a name `tools.tool(name)` does
5679
+ not hold, naming the tool and the available names. Otherwise it runs
5567
5680
  `tools.execute(call, context)` under the modern and legacy wire eras. The call carries
5568
5681
  `{ id, name, arguments }`; the context carries the request's `signal` and the optional
5569
5682
  `caller` from `options.caller`, omitted when absent. The tool body receives that context.
5570
5683
  Because the `ToolManager`
5571
- (`@orkestrel/tool`) already isolates a thrown tool (and an unknown name)
5572
- into a `success: false` result, the server adds no try/catch: that branch's
5684
+ (`@orkestrel/tool`) already isolates a thrown tool and a refused argument
5685
+ record into a `success: false` result, the server adds no try/catch: that branch's
5573
5686
  `error` maps to `{ content: [{ type: 'text', text: <error> }], isError: true }`;
5574
5687
  a valued `success: true` branch maps to `{ content: [{ type: 'text', text:
5575
- JSON.stringify(value) }], structuredContent: value }`, carrying the value unchanged
5576
- alongside the backwards-compatible text. A value-less success retains the required
5577
- empty text block and omits `structuredContent`.
5688
+ JSON.stringify(value) }] }`, and a record value also travels unchanged as
5689
+ `structuredContent` alongside the backwards-compatible text. A value-less success retains the
5690
+ required empty text block and omits `structuredContent`.
5578
5691
  6. **One modern seam, subscriptions included, and `-32601` for anything off it.**
5579
5692
  `server/discover`, `tools/list`, `tools/call`, and `subscriptions/listen` are registered on `server.methods` at
5580
5693
  construction — unconditionally, because they need no consumer port — and
@@ -5618,8 +5731,11 @@ the exact statement:
5618
5731
  metadata, and duplicated text/structured representations—is bounded before serialization; and
5619
5732
  built-in subscription admission is capped until each stream's `finally` releases it.
5620
5733
  Metadata/state failures use `-32602`; content/capacity failures use `-32603`. A
5621
- parsed value that is not a valid invocation (a response, or any non-message)
5622
- → a serialized `-32600` (Invalid Request) response with `id: null`. The
5734
+ batch, any other non-object, or a `method` beside an `id` that is not valid
5735
+ → a serialized `-32600` (Invalid Request) response with `id: null`, and a malformed request
5736
+ carrying a valid id answers under that id. A response, malformed or not, and a malformed
5737
+ notification answer `undefined` and reach the `error` event, because JSON-RPC gives no
5738
+ response to a response and a notification waits on nothing. The
5623
5739
  raw-string parse is the only `try`/`catch`; the guards (`parseJSONRPCMessage`
5624
5740
  over `@orkestrel/jsonrpc`'s `isJSONRPCMessage`) are total and never throw.
5625
5741
  8. **Total wire guards.** `isBoundedString` / `isBoundedJSON` / `isMCPResult` /
@@ -5770,12 +5886,15 @@ the exact statement:
5770
5886
  exact open server-capability shapes and exact metadata before returning, rejects malformed
5771
5887
  known fields or extension identifiers/values, and snapshots accepted capability/metadata
5772
5888
  records with the installed exact JSON clone primitive so transport-owned objects cannot drift.
5773
- `tools()` runs `tools/list` and wraps each descriptor as a
5774
- local `ToolInterface` — `name` narrowed (`isString`), `inputSchema` mapped
5889
+ `tools()` runs `tools/list` through `nextCursor` up to `MCP_LIST_PAGES` pages, refuses a page
5890
+ or a listing it cannot read as complete with an `MCPError`, and wraps each descriptor as a
5891
+ local `ToolInterface` — `inputSchema` mapped
5775
5892
  back to `parameters` (the inverse of the `parameters` → `inputSchema` rename, no `as`),
5776
5893
  `execute` bound to `call(name, …)`. `call(name, args)` runs `tools/call`,
5777
- concatenates the result's `text` content blocks and throws an `Error` carrying the text when
5778
- `isError === true`, else `JSON.parse`s the text (raw-string fallback;
5894
+ concatenates the result's `text` content blocks and throws an `Error` carrying
5895
+ the text when `isError === true`, refuses a success it cannot read, else takes an object
5896
+ `structuredContent`, checked against the listing's
5897
+ `outputSchema` when the tool declares one, or `JSON.parse`s the text (raw-string fallback;
5779
5898
  empty → `undefined`); so a remote tool failure throws locally and an
5780
5899
  agent's `ToolManager` isolates it into a `success: false` result exactly
5781
5900
  like a local throw. `disconnect()` rejects every pending request, clears
@@ -5897,8 +6016,10 @@ the exact statement:
5897
6016
  and sends unmasked frames), wraps it in a `WebSocketServerTransport`, and
5898
6017
  pumps — each inbound `JSONRPCMessage` that `@orkestrel/jsonrpc`'s `isJSONRPCRequest` guard accepts runs
5899
6018
  through `mcp.dispatch`, a defined response written back as a frame (a
5900
- notification → `dispatch` `undefined` → nothing sent); a non-request
5901
- message is ignored; a `dispatch` / `send` fault surfaces on `mcp.emitter`'s
6019
+ notification → `dispatch` `undefined` → nothing sent); invalid JSON or an invalid request
6020
+ is answered with `-32700` or `-32600`, and a stray response or a malformed notification is
6021
+ not answered; a transport,
6022
+ `dispatch`, or `send` fault surfaces on `mcp.emitter`'s
5902
6023
  `error` event rather than escaping the async listener, and a peer whose
5903
6024
  disconnect fires this transport's `close` is aborted by `bindServer` before
5904
6025
  any response is written, so that disconnect costs no frame and raises no
@@ -6026,9 +6147,10 @@ the exact statement:
6026
6147
  `process.stdout`) in a `StdioServerTransport` and pumps: each inbound
6027
6148
  `@orkestrel/jsonrpc` `JSONRPCMessage` value that is a request runs through `mcp.dispatch`, a defined
6028
6149
  response written back as a newline-terminated line after the output completion
6029
- callback confirms it (a notification writes nothing); a non-request message is ignored; a
6030
- `dispatch` / `send` fault
6031
- surfaces on the transport's `error` event. `stop()` unbinds that pump and
6150
+ callback confirms it (a notification writes nothing); invalid JSON or an invalid request is
6151
+ answered with `-32700` or `-32600`, and a stray response or a malformed notification is not
6152
+ answered; a transport, `dispatch`, or
6153
+ `send` fault surfaces on `mcp.emitter`'s `error` event. `stop()` unbinds that pump and
6032
6154
  closes the transport, which removes the listeners `start()` put on
6033
6155
  `input` and `output`, rejects every pending send, preserves the caller's flowing or
6034
6156
  non-flowing state and listeners,