stitchkit 0.103.13 → 0.104.1

package/llms/tools.2.txt

@@ -13,6 +13,65 @@ Parts of this slice:
 # Guide: MCP & agents  (docs/guide/mcp-and-agents.md)  (continued)
 ==============================================================================
 
+## Proxying a remote API — `implementRemote`
+
+`implement` binds a contract to local handlers. `implementRemote` binds it to a
+remote HTTP API instead — every handler forwards the call to a deployed server
+through the contract's typed client:
+
+```ts
+import { createHttpClient } from 'stitchkit'
+import { implementRemote } from 'stitchkit/remote'
+import { createStdioMcpServer } from 'stitchkit/tools/mcp'
+
+const http = createHttpClient({
+  baseUrl: 'https://api.example.com',
+  headers: () => ({ Authorization: `Bearer ${apiKey}` }),
+})
+
+const stdio = await createStdioMcpServer({
+  serverInfo: { name: 'my-app', version: '1.0.0' },
+  auth: null,
+  services: contracts.map((c) => implementRemote(c, http)),
+})
+
+// During graceful shutdown:
+await stdio.close()
+```
+
+This is how you ship a thin **local** MCP server for an API that already runs in
+the cloud: the local process owns only the transport and any filesystem-facing
+native tools, while every contract tool proxies to the remote API. One contract,
+no duplicated business logic.
+
+`implementRemote(contract, http, { transformArgs })` takes an optional
+`transformArgs` hook that rewrites a call's arguments before they are forwarded
+— e.g. to upload a local file referenced in the args and swap in its URL.
+
+The call's signal reaches the existing typed HTTP client's request options, for endpoints
+with or without arguments. An already cancelled call, including cancellation while an async
+argument transform runs, dispatches no request. Bind your process signal to `createCli` or
+`createCliInvoker`; `REQUEST_ABORTED` is a safe nonretryable failure with CLI exit130.
+Cooperative origins observe `ctx.signal` and release resources when their work ends. An
+origin or provider ignoring cancellation may continue after the local wait stops.
+
+An explicit `AppError.retryable` boolean also survives this remote hop. `false` on502 and
+`true` on409 remain the application's recommendation through HTTP, CLI, MCP and AI tools.
+Absent metadata keeps the previous defaults and does not alter HTTP transport retries.
+
+## Structured output
+
+When a contract endpoint or runtime tool declares `output`, its MCP tool
+registers that exact schema as `outputSchema` and returns the validated value as
+`structuredContent` alongside a JSON text block. Every JSON root type is kept
+unchanged: object, array, string, number, boolean and `null`. Stitchkit does not
+wrap non-object values in `{ result }`; protocol-era adaptation belongs to the
+official SDK.
+
+A tool without an output contract advertises no `outputSchema` and returns no
+invented structured value. Its successful MCP result has an empty `content`
+list.
+
 ## A different answer for tools — `withToolView`
 
 An admin page wants the full record; a model wants a card. Every byte of a

package/llms/tools.3.txt

@@ -278,6 +278,7 @@ Advanced building blocks — the shared machinery the mounts are built on.
 | `TransportSummary` | _type_ | `{ contractServices, runtimeTools, totals, sources }` from `summarizeTransports` |
 | `TransportCounts` | _type_ | per-transport counts (`{ HTTP, MCP, AGENT, CLI }`) |
 | `ToolSurfaceDefinition` | _type_ | shared object-shaped `{ services?, runtimeTools? }` introspection surface |
+| `ToolSurfaceProjection` | _type_ | one readonly services/runtime container shared by full and MCP-only surfaces; executable mounts specialize the runtime definition without pulling in another adapter's peers |
 | `ToolManifestConfig` | _type_ | mixed surface plus required model-facing `transport` and presentation options |
 | `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments |
 | `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions into conservative object joins; scalar collisions retain provable types, object/array collisions retain structural alternatives, and field descriptions retain discriminator labels plus availability/requiredness hints; the projection never executes validation |

package/llms/tools.txt

@@ -147,13 +147,20 @@ get the view's defaults and projected answer, which is what `collectTools` and
 
 ## MCP — `createMcpHandler`
 
+An MCP-only server imports `stitchkit/tools/mcp` and installs
+`stitchkit`, `zod` and `@modelcontextprotocol/server`. The leaf's runtime and strict
+NodeNext declarations require no `ai`. It exports the existing HTTP/stdio server,
+schema policy, catalog and resource helpers; their implementation and security are shared
+with the full `stitchkit/tools` barrel. Use that full barrel when the application also
+needs its AI SDK features.
+
 `createMcpHandler` builds a complete stateless Streamable-HTTP MCP endpoint on
 the official TypeScript SDK v2 server package. It owns server creation,
 protocol-era negotiation and shutdown; application code does not import the SDK
 to mount a normal endpoint.
 
 ```ts
-import { createMcpHandler, createMcpHttpRoute } from 'stitchkit/tools'
+import { createMcpHandler, createMcpHttpRoute } from 'stitchkit/tools/mcp'
 import { createServer } from 'stitchkit/server'
 
 const mcp = createMcpHandler({
@@ -287,7 +294,7 @@ Every advertised tool and every tool result therefore carries the fingerprint of
 the catalog it came from:
 
 ```ts
-import { readMcpCatalogStamp } from 'stitchkit/tools';
+import { readMcpCatalogStamp } from 'stitchkit/tools/mcp';
 
 const listed = await client.listTools();
 let known = readMcpCatalogStamp(listed.tools[0]?._meta); // { digest, tools }
@@ -792,7 +799,7 @@ If you already run an `McpServer` from the SDK, `mountMcp` adds contract tools
 to it instead of owning the lifecycle:
 
 ```ts
-import { mountMcp } from 'stitchkit/tools'
+import { mountMcp } from 'stitchkit/tools/mcp'
 
 mountMcp(mcpServer, [usersService], { context: { source: 'mcp' } })
 ```
@@ -808,7 +815,7 @@ client (Claude Desktop, Claude Code, Cursor, Codex), on the user's machine, so
 it can reach the local filesystem.
 
 ```ts
-import { bindStdioProcessSignals, createStdioMcpServer } from 'stitchkit/tools'
+import { bindStdioProcessSignals, createStdioMcpServer } from 'stitchkit/tools/mcp'
 
 const stdio = await createStdioMcpServer({
   serverInfo: { name: 'my-app', version: '1.0.0' },
@@ -953,51 +960,3 @@ successes cannot reset a failing client's backoff.
 > Dynamic Client Registration is an explicit interoperability mode, not the
 > default. Enabling it changes public discovery and adds `/register`; keep it off
 > unless a client that cannot publish CIMD requires it.
-
-## Proxying a remote API — `implementRemote`
-
-`implement` binds a contract to local handlers. `implementRemote` binds it to a
-remote HTTP API instead — every handler forwards the call to a deployed server
-through the contract's typed client:
-
-```ts
-import { createHttpClient } from 'stitchkit'
-import { implementRemote } from 'stitchkit/remote'
-import { createStdioMcpServer } from 'stitchkit/tools'
-
-const http = createHttpClient({
-  baseUrl: 'https://api.example.com',
-  headers: () => ({ Authorization: `Bearer ${apiKey}` }),
-})
-
-const stdio = await createStdioMcpServer({
-  serverInfo: { name: 'my-app', version: '1.0.0' },
-  auth: null,
-  services: contracts.map((c) => implementRemote(c, http)),
-})
-
-// During graceful shutdown:
-await stdio.close()
-```
-
-This is how you ship a thin **local** MCP server for an API that already runs in
-the cloud: the local process owns only the transport and any filesystem-facing
-native tools, while every contract tool proxies to the remote API. One contract,
-no duplicated business logic.
-
-`implementRemote(contract, http, { transformArgs })` takes an optional
-`transformArgs` hook that rewrites a call's arguments before they are forwarded
-— e.g. to upload a local file referenced in the args and swap in its URL.
-
-## Structured output
-
-When a contract endpoint or runtime tool declares `output`, its MCP tool
-registers that exact schema as `outputSchema` and returns the validated value as
-`structuredContent` alongside a JSON text block. Every JSON root type is kept
-unchanged: object, array, string, number, boolean and `null`. Stitchkit does not
-wrap non-object values in `{ result }`; protocol-era adaptation belongs to the
-official SDK.
-
-A tool without an output contract advertises no `outputSchema` and returns no
-invented structured value. Its successful MCP result has an empty `content`
-list.

package/llms/upgrading-0.37.0-0.44.0.txt

@@ -0,0 +1,444 @@
+# Upgrading 0.37.0 → 0.44.0 — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: Guide: Upgrading, 0.37.0 → 0.44.0  (docs/guide/upgrading.md)
+
+==============================================================================
+# Guide: Upgrading, 0.37.0 → 0.44.0  (docs/guide/upgrading.md)
+==============================================================================
+
+## Historical breaking migrations through 0.44.0
+
+HTTP observability now completes inside the framework handler instead of a
+nested fetch wrapper. Configure request and tool sinks explicitly:
+
+```ts
+// before
+const audit = createAuditHook({ write })
+createServer({
+  services,
+  wrapFetch: (handler) => wrapInRequestContext(audit.http(handler)),
+})
+mountAgent(services, { hooks: audit.toolCall })
+
+// after
+const observability = createObservability({
+  request: { write, includePayload: true },
+  tools: { write },
+})
+createServer({ services, observability: observability.request })
+mountAgent(services, { hooks: observability.toolCall })
+```
+
+Body capture changed from always-on for body methods to opt-in. Set
+`includePayload: true` only when the request sink needs the sanitized JSON body.
+There is no `createAuditHook` or `audit.http` compatibility path;
+`wrapInRequestContext` remains only for custom fetch pipelines.
+
+Tool introspection now accepts one object-shaped contract/runtime surface. Stop
+calling the internal contract collector or merging a locally converted runtime
+manifest:
+
+```ts
+// before
+buildToolManifest(services.flatMap((service) => collectTools(service, 'AGENT')))
+listToolNames(services)
+summarizeTransports(services)
+
+// after
+const surface = { services, runtimeTools }
+buildToolManifest({ ...surface, transport: 'AGENT' })
+listToolNames(surface)
+summarizeTransports(surface)
+```
+
+`ToolNameEntry` adds `kind: 'contract' | 'runtime'`. `TransportSummary` is now
+`{ contractServices, runtimeTools, totals, sources }`; replace `services` and
+`perService` reads with the explicit counts and mixed-source breakdown. There
+is no positional overload and no `buildRuntimeToolManifest`: Stitchkit owns the
+combined order, transport filtering, canonical presentation schema and
+cross-origin collision checks.
+
+`defineErrors` now uses one Zod-first definition object and returns constructors
+instead of positional throwers. Add explicit `throw`, move message/details/hint
+into one options object, and declare a details schema when that code carries
+structured context:
+
+```ts
+// before
+const { errors } = defineErrors({ QUOTA_EXCEEDED: 429 })
+errors.QUOTA_EXCEEDED('Try later', { retryAfterSeconds: 30 }, 'Wait')
+
+// after
+const { errors, definitions } = defineErrors({
+  QUOTA_EXCEEDED: {
+    status: 429,
+    details: z.object({ retryAfterSeconds: z.number().positive() }),
+  },
+})
+throw errors.QUOTA_EXCEEDED({
+  message: 'Try later',
+  details: { retryAfterSeconds: 30 },
+  hint: 'Wait',
+})
+```
+
+There is no positional overload. A code without `details` forbids them; use an
+optional object schema when the details object itself is optional. Read status
+and schemas from the frozen `definitions` registry instead of maintaining a
+parallel map.
+
+Managed MCP runtime tools are now declared as immutable data. Move protected
+registrar calls to `runtimeTools`; rename deliberate raw SDK registration to
+`rawTools`. There is no registrar alias:
+
+```ts
+// before — protected
+createMcpHandler({
+  services,
+  nativeTools: ({ registerTool }) => registerTool(preview),
+})
+
+// after — protected and prepared with the rest of the surface
+createMcpHandler({ services, runtimeTools: [preview] })
+
+// before — deliberate raw SDK opt-out
+nativeTools: ({ rawServer }, auth) => mountRaw(rawServer, auth)
+
+// after — still a deliberate raw SDK opt-out
+rawTools: (server, auth) => mountRaw(server, auth)
+```
+
+When identity selects from a bounded set, replace a repeatedly prepared
+`services(auth)` factory with a finite registry:
+
+```ts
+createMcpHandler({
+  surfaces: {
+    admin: { services: allServices, runtimeTools: [preview] },
+    member: { services: memberServices, runtimeTools: [preview] },
+  },
+  selectSurface: (auth) => auth.isAdmin ? 'admin' : 'member',
+})
+```
+
+Keep direct `services(auth)` / `runtimeTools(auth)` only for genuinely
+unbounded definitions; Stitchkit intentionally does not cache arbitrary auth
+values.
+
+Contract success bodies are now determined by the presence of `output`, not by
+the handler's runtime value. A nullable output returns JSON `null` with status
+`200`; `undefined` with a declared output and non-null data without an output
+schema are contract violations:
+
+```ts
+// nullable JSON data: 200 with body `null`
+session: {
+  method: 'GET', path: '/session', desc: 'Current session',
+  output: SessionSchema.nullable(),
+}
+
+// bodyless operation: 204 with no body
+logout: {
+  method: 'POST', path: '/logout', desc: 'End the session',
+}
+```
+
+Add an output schema to every handler that returns data. Omit `output` and
+return nothing for bodyless operations; runtime tools follow the same rule and
+type no-output handlers as `void`.
+
+`createToolInvoker` now separates immutable registry preparation from per-call
+runtime state. Move source/context/lifecycle/hooks/output-strip reporting from
+the factory config to the third invocation argument. Use `invokeOrThrow` when a
+nested operation should preserve the normalized `AppError` instead of returning
+a model-facing failure envelope:
+
+```ts
+// before
+const invoker = createToolInvoker(services, {
+  transport: 'AGENT', context: { identity }, lifecycle, hooks,
+})
+const result = await invoker.invoke(name, args)
+
+// after
+const invoker = createToolInvoker(services, { transport: 'AGENT' })
+const result = await invoker.invoke(name, args, {
+  context: { identity }, lifecycle, hooks,
+})
+const data = await invoker.invokeOrThrow(name, args, {
+  context: { identity }, lifecycle, hooks,
+})
+```
+
+There is no static runtime-config overload: request identity must not be retained
+by a reusable compiled registry.
+
+Entity cache handlers now require the cached list shape and CRUD policies. Move
+`listKey` under `list`, make detail keys event-aware, and state the list-item
+identity/projection explicitly:
+
+```ts
+// before
+createEntityCacheHandlers<Entity>({
+  getId,
+  listKey: ['entities'],
+  detailKey: (id) => ['entities', id],
+})
+
+// after
+createEntityCacheHandlers<Entity, EntityListItem>({
+  getId,
+  getListItemId: (item) => item.id,
+  toListItem: (entity) => ({ id: entity.id, name: entity.name }),
+  list: {
+    key: ['entities'],
+    shape: 'paginated',
+    createAt: 'start',
+    updateMissing: 'skip',
+  },
+  detailKey: (event) => ['entities', event.id],
+})
+```
+
+Choose `array`, `paginated`, `infinite-array` or `infinite-paginated` to match
+the actual cached data. A dynamic `list.key` / `detailKey` receives a
+discriminated event and can derive scoped keys from the created/updated entity
+or deleted payload. Add `compare` only when the backend has a canonical order;
+the framework does not guess it or mutate pagination metadata.
+
+Protected native MCP operations now use the transport-neutral runtime tool
+definition. Return the schema-owned value from the handler and move MCP content
+or metadata into `present.mcp`; `structuredContent` and `isError` are
+framework-owned:
+
+```ts
+// before
+registerTool({ input, output, handler: async () => ({
+  content: [{ type: 'image', data, mimeType: 'image/png' }],
+  structuredContent: { assetId },
+}) })
+
+// after
+const preview = defineRuntimeTool({
+  name: 'render_preview', description, identity, input, output,
+  handler: async () => ({ assetId, data }),
+  present: {
+    mcp: (result) => ({
+      content: [{ type: 'image', data: result.data, mimeType: 'image/png' }],
+    }),
+  },
+})
+runtimeTools: [preview]
+```
+
+The removed `NativeMcp*` types have no aliases. Use `RuntimeToolDefinition`,
+`RuntimeToolIdentity`, `RuntimeToolHandlerContext` and
+`RuntimeMcpPresentation`. The same definition can now be passed to
+`mountAgent(services, { runtimeTools: [preview] })`; add `present.agent` only
+when the model needs rich text/file content instead of the neutral JSON result.
+
+Trailing wildcards must be named consistently across the path and params schema:
+
+```ts
+// before
+path: '/app/:slug/*'
+params: z.object({ slug: z.string(), '*': z.string() })
+ctx.params['*']
+api.app({ slug: 'foo', '*': 'a/b' })
+
+// after
+path: '/app/:slug/*filePath'
+params: z.object({ slug: z.string(), filePath: z.string() })
+ctx.params.filePath
+api.app({ slug: 'foo', filePath: 'a/b' })
+```
+
+Bare wildcards have no compatibility alias; raw routes use the same named form.
+
+### Expected-401 matchers
+
+`HttpClientConfig.authEndpoints` is removed. Replace manual path prefixes with
+the operations whose 401 response is expected:
+
+```ts
+// before
+createHttpClient({ baseUrl, authEndpoints: ['/api/auth/'] })
+
+// after
+createHttpClient({
+  baseUrl,
+  suppressUnauthorizedFor: contractEndpointMatchers(authContract, ['login', 'verify']),
+})
+```
+
+There is no implicit `/auth/` suppression. Omit `suppressUnauthorizedFor` when
+every 401 should emit the global `unauthorized` event.
+
+## The 0.37 migration
+
+Tool presentation is no longer an executable Zod parser. Replace the removed
+flatten helpers with the JSON Schema compiler, and choose the explicit
+`MountableTool` surface when using the advanced collection API:
+
+```ts
+// before
+const flat = flattenUnionsDeep(zodSchema)
+mountable.schema
+
+// after
+const flat = flattenToolJsonSchema(
+  z.toJSONSchema(zodSchema, { target: 'draft-07', io: 'input' }),
+)
+mountable.presentationSchema // model/MCP/manifest JSON Schema
+mountable.argumentSchema     // executable CLI argument adapter only
+```
+
+Contract and native handlers keep their original Zod schemas; MCP and agent SDK
+adapters now forward raw arguments so defaults, coercions, refinements and
+transforms execute exactly once inside Stitchkit. There are no compatibility
+exports for `flattenDiscriminatedUnion`, `flattenUnionsDeep` or
+`MountableTool.schema`. → ADR 0050
+
+Tool-call hooks now take one options object. Migrate all three callbacks; there
+are no positional overloads:
+
+```ts
+// before
+beforeToolCall: (toolName, args, context, endpoint) => {}
+afterToolCall: (toolName, args, result, durationMs, context, endpoint, error) => {}
+onToolError: (toolName, error, context, endpoint) => {}
+
+// after
+beforeToolCall: ({ toolName, args, context, endpoint }) => {}
+afterToolCall: ({ toolName, args, result, durationMs, context, endpoint, error }) => {}
+onToolError: ({ toolName, error, context, endpoint }) => {}
+```
+
+### MCP schema validation
+
+The standalone validator now takes one object and live MCP configs carry the
+same rules under `schemaValidation`. Migrate every positional call and every
+`onIncompatibleSchema` field; there is no old-shape overload:
+
+```ts
+// before
+validateMcpSchemas(services, 'throw', logger, { requireTypedProperties: true })
+createMcpHandler({ services, onIncompatibleSchema: 'throw' })
+
+// after
+validateMcpSchemas({ services, policy: 'throw', logger, requireTypedProperties: true })
+createMcpHandler({ services, schemaValidation: { policy: 'throw' } })
+```
+
+Put `extend` and `flattenUnionInput` beside `services`, not inside
+`schemaValidation`. The handler applies the profile to the exact prepared schema
+it advertises. Add `requirePortableFormats: true` when every custom JSON Schema
+format must be rejected before a client sees it.
+
+Native MCP registration also changed shape in 0.37. Move protected tools to the
+framework registrar; keep an SDK-raw tool only by naming the opt-out:
+
+```ts
+// before
+nativeTools: (server, auth) => server.registerTool(name, config, handler)
+
+// after — lifecycle, hooks and schema policy apply
+nativeTools: ({ registerTool }, auth) => registerTool({
+  name, description, identity, input, output, handler,
+})
+
+// after — intentionally raw
+nativeTools: ({ rawServer }, auth) => rawServer.registerTool(name, config, handler)
+```
+
+If a tool hook annotated `endpoint` as `MethodDef`, remove that annotation or
+use `OperationIdentity`: native operations have service/action/scope/method but
+no HTTP path.
+
+### Node-facing server types
+
+`stitchkit/server` remains Bun-concrete: an explicitly annotated `RawRoute`
+still receives `BunServer`. `stitchkit/node` no longer drags Bun declarations
+into a Node project. Its raw routes default the host server to `unknown`, and
+its Socket.IO handle exposes only Node capabilities:
+
+```ts
+// before — Node entry still leaked Bun-only fields and ambient types
+const route: RawRoute = { handler: (_req, ctx) => ctx.server?.upgrade(...) }
+const socket = await createSocketIOServer(config)
+socket.websocket
+
+// after — name a custom embedding host only when one exists
+const route: RawRoute<MyHostServer> = {
+  handler: (_req, ctx) => useHost(ctx.server),
+}
+const socket = await createSocketIOServer(config)
+socket.io
+socket.attach(nodeHttpServer)
+```
+
+Node consumers can remove `@types/bun` unless another dependency independently
+requires it.
+
+### Managed server shutdown
+
+`createServer()` and `serveNode()` now return the same structural managed
+lifecycle. Replace every direct runtime stop and parallel Socket.IO close:
+
+```ts
+// before — split ownership
+const socket = await createSocketIOServer(config)
+const server = createServer({
+  services,
+  websocket: socket.websocket,
+  rawRoutes: [socket.route],
+})
+server.stop()
+await socket.io.close()
+
+// after — one owner and one total deadline
+const socket = await createSocketIOServer(config)
+const server = createServer({ services, socket })
+const result = await server.shutdown({ gracePeriodMs: 30_000 })
+```
+
+On Node, keep the same `socket` field and replace `handle.close()` with
+`handle.shutdown()`. Runtime-specific diagnostics move under `handle.runtime`;
+do not use it as a second shutdown path. Standalone CLI/tools that create a
+Socket.IO handle without an HTTP server call `await socket.close()`.
+
+If Bun Socket.IO shares the port with a raw lane, keep the explicit composition
+but let the server mount the Socket.IO route:
+
+```ts
+createServer({
+  services,
+  socket,
+  websocket: composeWebSocketHandlers([
+    webSocketLane({ match: isRaw, handlers: rawHandlers }),
+    socketIoLane(socket.websocket),
+  ]),
+  rawRoutes: [rawUpgradeRoute],
+})
+```
+
+Move native Bun `routes` entries to `rawRoutes`. Native routes run before the
+Fetch handler and therefore cannot participate in admission or drain. Wire
+`SIGTERM`/`SIGINT` in the application; the first signal starts `shutdown()`, and
+a later signal may abort the same controller. Close MCP, databases and queues
+after the server result—those resources remain application-owned.
+
+Move a handshake policy from the Node-only callback shape inside
+`serverOptions` to the runtime-neutral top-level policy. It receives a Web
+`Request`, may be async, and returns whether to admit the handshake:
+
+```ts
+// before
+serverOptions: { allowRequest: (request, done) => done(null, allowed(request)) }
+
+// after
+allowRequest: (request) => allowed(request)
+```