orpc-fn 0.7.0 → 0.9.0

package/src/live/pub-sub.ts

@@ -63,7 +63,12 @@ export type FilterFn<TInput, TEventData> = (params: {
  * everyone; a function returns false (or throws) to refuse with FORBIDDEN.
  */
 export type AuthFn<TInput, TContext> =
-	| ((params: { input: TInput; ctx: TContext }) => MaybePromise<boolean>)
+	| ((params: {
+			input: TInput
+			context: TContext
+			/** @deprecated Use `context`. */
+			ctx: TContext
+	  }) => MaybePromise<boolean>)
 	| true
 
 export type PublisherConfig = {
@@ -85,8 +90,9 @@ export type PublisherConfig = {
 	 */
 	mirrorChannel?: string
 	/**
-	 * Log publish failures (validation or broker) instead of throwing them, so
-	 * a publish after a committed write cannot fail the request. No retry.
+	 * Log publish failures (validation or broker) at `warn` instead of throwing
+	 * them, so a publish after a committed write cannot fail the request. No
+	 * retry. Default: `createFn({ pubsub: { safePublish } })`, else false.
 	 */
 	safePublish?: boolean
 }
@@ -128,7 +134,11 @@ export type PubSubOptions<
 		/** What gets published. */
 		eventSchema: TEventSchema
 		filterFn?: FilterFn<z.output<TInputSchema>, z.output<TEventSchema>>
-		authFn?: AuthFn<z.output<TInputSchema>, FnContext<TDef, TKey>>
+		/**
+		 * Who may subscribe. Required: `true` says on purpose that anyone who
+		 * passes the procedure builder may.
+		 */
+		authFn: AuthFn<z.output<TInputSchema>, FnContext<TDef, TKey>>
 		/**
 		 * When a slow subscriber's queue overflows (drop-oldest), enqueue this
 		 * marker INSTEAD of the new event so the subscriber resyncs from its
@@ -167,11 +177,24 @@ export type PubSub<
 		context: FnContext<TDef, TKey>
 	}) => string
 	getPublishChannelName: (event: z.output<TEventSchema>) => string
-	/** @deprecated Prefer the separate required-input resolver methods. */
-	getChannelName: (
-		params: Partial<z.output<TInputSchema>> | Partial<z.output<TEventSchema>>,
-		context?: FnContext<TDef, TKey>
-	) => string
+	/**
+	 * Read the bus on the server, without the route, its guards or `authFn`.
+	 * Resolves once subscribed; the events end when `signal` aborts.
+	 */
+	listen: (
+		input: z.output<TInputSchema>,
+		options?: ListenOptions<FnContext<TDef, TKey>>
+	) => Promise<AsyncGenerator<z.output<TEventSchema>, void, unknown>>
+	/** The parsed backlog of the channel an event goes to, oldest first. */
+	readBacklog: (
+		event: Partial<z.output<TEventSchema>>
+	) => Promise<z.output<TEventSchema>[]>
+}
+
+export type ListenOptions<TContext = unknown> = {
+	signal?: AbortSignal
+	/** For a channel resolver that reads the context. */
+	context?: TContext
 }
 
 export type CreatePubSub<TDef extends FnDefinition> = <
@@ -201,6 +224,15 @@ export type Publisher<TEventSchema extends ZodType> = {
 	publish: (data: z.input<TEventSchema>) => Promise<void>
 	publishMany: (items: readonly z.input<TEventSchema>[]) => Promise<void>
 	getChannelName: (params: Partial<z.output<TEventSchema>>) => string
+	/** Read the channel on the server. Resolves once subscribed. */
+	listen: (
+		params: Partial<z.output<TEventSchema>>,
+		options?: Omit<ListenOptions, 'context'>
+	) => Promise<AsyncGenerator<z.output<TEventSchema>, void, unknown>>
+	/** The channel's parsed backlog, oldest first. */
+	readBacklog: (
+		params: Partial<z.output<TEventSchema>>
+	) => Promise<z.output<TEventSchema>[]>
 }
 
 /**
@@ -236,6 +268,14 @@ export type PubSubRuntimeOptions = {
 	namespace?: string
 	/** Close this transport only when its ownership is explicitly transferred. */
 	ownsTransport?: boolean
+	/** Default `safePublish` for every definition of this factory. */
+	safePublish?: boolean
+	/**
+	 * End route streams this long after they opened (plus up to 10% jitter),
+	 * so a client reconnects and its context, and with it its authorization,
+	 * is built again. The client helpers reconnect on their own. Default: never.
+	 */
+	maxStreamAgeMs?: number
 }
 
 /** @internal */
@@ -463,9 +503,12 @@ export type Channel = {
 		context: unknown
 		signal: AbortSignal | undefined
 		recoverGaps?: boolean
+		/** An in-process reader: no `authFn`, no maximum age. */
+		server?: boolean
 	}) => Promise<LiveSubscription>
 	publish: (data: unknown) => Promise<void>
 	publishMany: (items: readonly unknown[]) => Promise<void>
+	readBacklog: (event: Input) => Promise<unknown[]>
 	getChannelName: (params: Input, context?: unknown) => string
 	getSubscriptionChannelName: (params: {
 		input: Input
@@ -512,6 +555,10 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 		options.pubsub?.initializationTimeoutMs ?? 10000,
 		'initializationTimeoutMs'
 	)
+	const maxStreamAge =
+		options.pubsub?.maxStreamAgeMs === undefined
+			? undefined
+			: positiveInteger(options.pubsub.maxStreamAgeMs, 'maxStreamAgeMs')
 	const metric = (event: PubSubMetric) =>
 		safely(() => options.pubsub?.onMetric?.(event))
 	const namespace = options.pubsub?.namespace
@@ -617,15 +664,16 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 				}
 			})
 
+		const safePublish = config.safePublish ?? options.pubsub?.safePublish
 		const guarded = async (
 			operation: 'publish' | 'publishMany',
 			items: readonly unknown[]
 		) => {
-			if (!config.safePublish) return send(operation, items)
+			if (!safePublish) return send(operation, items)
 			try {
 				await send(operation, items)
 			} catch (error) {
-				logger.error('pubsub.publish_failed', {
+				logger.warn('pubsub.publish_failed', {
 					name,
 					...errorAttributes(error)
 				})
@@ -910,7 +958,8 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 			input,
 			context,
 			signal,
-			recoverGaps = false
+			recoverGaps = false,
+			server = false
 		}) => {
 			assertOpen()
 			signal?.throwIfAborted()
@@ -937,10 +986,11 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 
 			try {
 				if (
+					!server &&
 					authFn !== undefined &&
 					authFn !== true &&
 					!(await waitFor(
-						Promise.resolve(authFn({ input, ctx: context })),
+						Promise.resolve(authFn({ input, context, ctx: context })),
 						initializationTimeout,
 						initializing.signal
 					))
@@ -1006,16 +1056,14 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 			let replaying: Array<{ data: unknown; id: string | undefined }> | null =
 				useBacklog ? [] : null
 			let replayGap = false
-			const seen = new Set<string>()
+			// Overlap exists only between the backlog and live events that arrive
+			// while it replays, so ids are recorded only then: at most twice
+			// `maxReplay`, and nothing at all without a backlog.
+			const seen = useBacklog ? new Set<string>() : null
 			const dedupe = (id: string | undefined) => {
-				if (!id) return false
+				if (!id || !seen) return false
 				if (seen.has(id)) return true
-				seen.add(id)
-				if (
-					seen.size >
-					Math.max(maxReplay, maxQueue, channelOptions.backlogSize ?? 50) * 2
-				)
-					seen.delete(seen.values().next().value as string)
+				if (replaying) seen.add(id)
 				return false
 			}
 			const push = (data: unknown, id?: string) => {
@@ -1067,9 +1115,11 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 			// stream finishing, or `close()`. Releases everything at once, even
 			// while the stream is parked or not yet read.
 			let closed = false
+			let ageTimer: ReturnType<typeof setTimeout> | undefined
 			const close = (...error: [] | [unknown]) => {
 				if (closed) return
 				closed = true
+				clearTimeout(ageTimer)
 				initializing.abort(error[0] ?? new Error('Subscription closed'))
 				delivery.close(error[0])
 				activeSubscriberCleanups.delete(stop)
@@ -1097,6 +1147,10 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 			activeSubscriberCleanups.add(stop)
 			signal?.addEventListener('abort', stop)
 			if (signal?.aborted) close()
+			if (maxStreamAge !== undefined && !server && !closed) {
+				ageTimer = setTimeout(stop, maxStreamAge * (1 + Math.random() * 0.1))
+				;(ageTimer as { unref?: () => void }).unref?.()
+			}
 
 			try {
 				await waitFor(local.ready, initializationTimeout, initializing.signal)
@@ -1182,6 +1236,25 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 			getChannelName: getPublishChannel
 		})
 
+		const readBacklog = async (event: Input) => {
+			const channelName = getPublishChannel(event)
+			const events: unknown[] = []
+			for (const raw of await requireTransport().readBacklog(channelName)) {
+				try {
+					events.push(await eventSchema.parseAsync(decodeMessage(raw).value))
+				} catch (error) {
+					metric({
+						type: 'parseError',
+						stage: 'replay',
+						error,
+						name,
+						channel: channelName
+					})
+				}
+			}
+			return events
+		}
+
 		const open: Channel['open'] = (params) => {
 			const task = openInternal(params)
 			pendingOpens.add(task)
@@ -1195,6 +1268,7 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 			open,
 			publish,
 			publishMany,
+			readBacklog,
 			getChannelName,
 			getSubscriptionChannelName: ({ input, context }) =>
 				getChannelName(input, context),
@@ -1212,6 +1286,10 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 		}
 	) {
 		const { name } = pubsubOptions
+		if (pubsubOptions.authFn === undefined)
+			throw new TypeError(
+				`orpc-fn: pub/sub ${name} needs an authFn; pass authFn: true to let every caller of its procedure subscribe`
+			)
 		const channel = createChannel(pubsubOptions)
 
 		const {
@@ -1251,27 +1329,37 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 			}
 		})
 
-		const { publish, publishMany, getChannelName } = channel
 		return {
 			subscribe,
-			publish,
-			publishMany,
-			getChannelName,
+			publish: channel.publish,
+			publishMany: channel.publishMany,
 			getSubscriptionChannelName: channel.getSubscriptionChannelName,
-			getPublishChannelName: channel.getPublishChannelName
+			getPublishChannelName: channel.getPublishChannelName,
+			listen: listener(channel),
+			readBacklog: channel.readBacklog
 		}
 	}
 
 	function createPublisher(publisherOptions: PublisherOptions<ZodType>) {
-		const getChannelName = (params: Input) =>
-			qualify(resolveChannel(publisherOptions.channel, params, undefined, true))
-		const { publish, publishMany } = createChannelPublisher({
-			...publisherOptions,
-			getChannelName
-		})
-		return { publish, publishMany, getChannelName }
+		const channel = createChannel(publisherOptions)
+		return {
+			publish: channel.publish,
+			publishMany: channel.publishMany,
+			getChannelName: channel.getPublishChannelName,
+			listen: (params: Input, listenOptions: { signal?: AbortSignal } = {}) =>
+				listener(channel)(params, listenOptions),
+			readBacklog: channel.readBacklog
+		}
 	}
 
+	const listener =
+		(channel: Channel) =>
+		async (
+			input: Input,
+			{ signal, context }: { signal?: AbortSignal; context?: unknown } = {}
+		) =>
+			(await channel.open({ input, context, signal, server: true })).events
+
 	return {
 		createChannel,
 		shutdown: () => {
@@ -1291,10 +1379,11 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 		/** Open subscriptions of this instance (drain progress, gauges). */
 		activePubSubSubscriberCount: () => activeSubscriberCleanups.size,
 		/** End every open subscription; returns how many were closed. */
-		drainPubSubSubscribers: () => {
+		drainPubSubSubscribers: (drain?: {
+			overMs: number
+		}): number | Promise<number> => {
 			const cleanups = [...activeSubscriberCleanups]
-			activeSubscriberCleanups.clear()
-			for (const cleanup of cleanups) {
+			const run = (cleanup: () => void) => {
 				try {
 					cleanup()
 				} catch (error) {
@@ -1304,7 +1393,23 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 					})
 				}
 			}
-			return cleanups.length
+			if (drain === undefined) {
+				activeSubscriberCleanups.clear()
+				for (const cleanup of cleanups) run(cleanup)
+				return cleanups.length
+			}
+			const { overMs } = drain
+			if (!Number.isFinite(overMs) || overMs < 0)
+				throw new RangeError('orpc-fn: overMs must be finite and nonnegative')
+			const step = overMs / Math.max(1, cleanups.length - 1)
+			return (async () => {
+				for (const [index, cleanup] of cleanups.entries()) {
+					if (index > 0)
+						await new Promise((resolve) => setTimeout(resolve, step))
+					run(cleanup)
+				}
+				return cleanups.length
+			})()
 		}
 	}
 }

package/src/live/redis-bun.ts

@@ -15,6 +15,13 @@ export interface BunRedisClientLike {
 	onclose: ((this: never, error: Error) => void) | null
 }
 
+/**
+ * What the command client must offer: `send`, and `duplicate` unless a
+ * `subscriber` is given. A wrapper with timeouts around Bun's client fits.
+ */
+export type BunRedisCommandClientLike = Pick<BunRedisClientLike, 'send'> &
+	Partial<Pick<BunRedisClientLike, 'duplicate'>>
+
 /**
  * `PubSubTransport` for Bun's built-in `RedisClient`. Subscriptions use a
  * dedicated connection (`client.duplicate()` unless `subscriber` is given)
@@ -24,14 +31,15 @@ export interface BunRedisClientLike {
  * Call `close()` on shutdown to close the subscriber connection it created.
  */
 export function bunRedisTransport(
-	client: BunRedisClientLike,
+	client: BunRedisCommandClientLike,
 	options: { subscriber?: BunRedisClientLike } = {}
 ) {
+	const openSubscriber = subscriberSource(client, options.subscriber)
 	return createRedisTransport({
 		send: (command, args) => client.send(command, args),
 		async connectSubscriber(handlers) {
 			const owned = !options.subscriber
-			const subscriber = options.subscriber ?? (await client.duplicate())
+			const subscriber = await openSubscriber()
 			const dispatch: Listener = (message, channel) =>
 				handlers.onMessage(channel, message)
 			const ours = new Set<string>()
@@ -79,3 +87,16 @@ export function bunRedisTransport(
 		}
 	})
 }
+
+function subscriberSource(
+	client: BunRedisCommandClientLike,
+	given: BunRedisClientLike | undefined
+): () => Promise<BunRedisClientLike> {
+	if (given) return async () => given
+	const { duplicate } = client
+	if (typeof duplicate !== 'function')
+		throw new TypeError(
+			'orpc-fn: bunRedisTransport needs a client with duplicate() or a subscriber'
+		)
+	return () => duplicate.call(client)
+}

package/src/live/scoped-change-bus.ts

@@ -50,6 +50,8 @@ const noInput = z.object({})
  * subscriber in a scope "something changed". Each bus then names only its
  * channel prefix: events go to `${prefix}:${scope}`. Publishing is safe by
  * default (`safePublish: true`), because buses publish after committed writes.
+ * The scope is the access decision (a subscriber hears only its own scope),
+ * so `authFn` defaults to `true`.
  *
  * ```ts
  * const defineChangeBus = defineScopedChangeBus(createPubSub, {
@@ -75,8 +77,14 @@ export function defineScopedChangeBus<TDef extends FnDefinition, TScopeEvent>(
 	>(
 		options: Omit<
 			PubSubOptions<TDef, TInputSchema, TEventSchema, NoInfer<TKey>>,
-			'channel' | 'inputSchema'
+			'channel' | 'inputSchema' | 'authFn'
 		> &
+			Partial<
+				Pick<
+					PubSubOptions<TDef, TInputSchema, TEventSchema, NoInfer<TKey>>,
+					'authFn'
+				>
+			> &
 			GuardOptions<TDef['guards']> &
 			Pick<
 				FnRouteOptions<TDef, TKey, z.output<TInputSchema>>,
@@ -98,6 +106,7 @@ export function defineScopedChangeBus<TDef extends FnDefinition, TScopeEvent>(
 		// signature of createPubSub cannot see.
 		const bus = (createPubSub as (options: object) => object)({
 			safePublish: true,
+			authFn: true,
 			...pubsubOptions,
 			inputSchema: pubsubOptions.inputSchema ?? noInput,
 			channel

package/src/mastra.ts

@@ -8,14 +8,15 @@ import {
 	type ToolSchema
 } from './json-schema.js'
 import { readFnMeta, toToolName } from './meta.js'
+import { type ToolErrorOptions, toolErrorText } from './tool-errors.js'
 import type { ProcedureInput, ProcedureOutput } from './types.js'
 
-export { toToolName }
+export { toToolName, type ToolErrorOptions }
 
-export type CreateMastraToolOptions = {
+export type CreateMastraToolOptions = ToolErrorOptions & {
 	/** Override the tool id (defaults to the sanitized `fn` name). */
 	id?: string
-	/** Override the tool description (defaults to the route summary). */
+	/** Override the tool description (defaults to the route description, else its summary). */
 	description?: string
 	/** Gate execution behind the AI SDK tool-approval flow. */
 	requireApproval?: boolean
@@ -31,6 +32,13 @@ export type CreateMastraToolOptions = {
 	}) => void
 	/** Key holding the oRPC context in Mastra's `RequestContext`. Default 'orpcContext'. */
 	contextKey?: string
+	/**
+	 * Reads the oRPC context from the run's request context, in place of
+	 * `contextKey`. Mastra writes plain request-context values into run
+	 * snapshots and spans, so an app whose context holds a session keeps it
+	 * in a slot that serializes to nothing and reads it here.
+	 */
+	context?: (requestContext: RequestContext) => unknown
 }
 
 /** What the tool takes: the procedure's raw input, or `{}` without a schema. */
@@ -59,6 +67,10 @@ type ObjectInputCheck<TProc> =
  * Mastra checks the input against the procedure's schema (with dates coerced
  * from strings) but passes the raw input on for the procedure to parse;
  * the output is the procedure's parsed result, passed through unchanged.
+ *
+ * A failed call throws an `Error` whose message is what the model reads:
+ * `CODE: message` with validation paths for an expected error, a fixed
+ * sentence for anything else (reported to `onError`).
  */
 export function createMastraTool<TProc extends AnyProcedure>(
 	procedure: TProc & ObjectInputCheck<TProc>,
@@ -110,10 +122,16 @@ export function createMastraTool<TProc extends AnyProcedure>(
 			: {}),
 		execute: async (input, ctx) => {
 			const requestContext = ctx?.requestContext as RequestContext | undefined
-			const context = requestContext?.get(contextKey)
+			const context =
+				requestContext &&
+				(options.context
+					? options.context(requestContext)
+					: requestContext.get(contextKey))
 			if (!context) {
 				throw new Error(
-					`createMastraTool execution requires ${contextKey} in the Mastra request context`
+					options.context
+						? 'createMastraTool execution found no oRPC context through its context option'
+						: `createMastraTool execution requires ${contextKey} in the Mastra request context`
 				)
 			}
 			const startedAt = performance.now()
@@ -138,7 +156,8 @@ export function createMastraTool<TProc extends AnyProcedure>(
 				return result
 			} catch (error) {
 				finish('error')
-				throw error
+				if (ctx?.abortSignal?.aborted) throw error
+				throw new Error(toolErrorText(error, id, options))
 			}
 		}
 	})

package/src/mcp/core.ts

@@ -3,8 +3,10 @@ import {
 	type InferRouterInitialContext,
 	call
 } from '@orpc/server'
+import { formatIssue } from '../issues.js'
 import { isObjectJsonSchema } from '../json-schema.js'
 import { listTools, type McpTool, type ProcedureFilter } from '../mcp.js'
+import { type ToolErrorOptions, toolErrorText } from '../tool-errors.js'
 
 /** Text-only tool result: the shape both MCP SDK majors accept. */
 export type TextToolResult = {
@@ -12,46 +14,60 @@ export type TextToolResult = {
 	isError?: boolean
 }
 
-export type RegisterMcpToolsOptions<R extends AnyRouter, TResult> = {
+/** Which procedures become tools, and their names and hints. */
+export type McpToolSelection = {
 	/** Tool exposure must be an explicit application choice. */
 	filter: ProcedureFilter
+	readOnly?: ProcedureFilter
+	name?: NonNullable<Parameters<typeof listTools>[1]>['name']
+}
+
+/** How a registered tool is called and how its outcome reads. */
+export type McpCallOptions<R extends AnyRouter, TResult> = ToolErrorOptions & {
 	context: (request: {
 		name: string
 		signal: AbortSignal
 	}) => InferRouterInitialContext<R> | Promise<InferRouterInitialContext<R>>
-	readOnly?: ProcedureFilter
-	name?: NonNullable<Parameters<typeof listTools>[1]>['name']
 	formatResult?: (value: unknown, tool: McpTool) => TResult | Promise<TResult>
 }
 
-/** Default protocol result: JSON/text. Provide formatResult for other MCP content. */
-export function formatMcpResult(value: unknown): TextToolResult {
-	const text =
-		typeof value === 'string'
-			? value
-			: (JSON.stringify(value, (_key, item) =>
-					typeof item === 'bigint' ? item.toString() : item
-				) ?? 'null')
-	return { content: [{ type: 'text', text }] }
+export type RegisterMcpToolsOptions<
+	R extends AnyRouter,
+	TResult
+> = McpToolSelection & McpCallOptions<R, TResult>
+
+type ToolDescription = Omit<McpTool['config'], 'inputSchema'> & {
+	name: string
+	inputSchema: Record<string, unknown> & { type: 'object' }
 }
 
-const errorResult = (text: string): TextToolResult => ({
-	content: [{ type: 'text', text }],
-	isError: true
-})
+/** Tools listed and converted once, then registered per server or request. */
+export type PreparedMcpTools<R extends AnyRouter> = {
+	readonly router: R
+	readonly names: readonly string[]
+	readonly tools: readonly McpTool[]
+	/** @internal The `tools/list` answer. */
+	readonly descriptions: readonly ToolDescription[]
+}
 
-/** @internal SDK-independent `tools/list` and `tools/call` behind both adapters. */
-export function createToolHandlers<R extends AnyRouter, TResult>(
+/**
+ * List and convert a router's tools once, for an app that builds an MCP
+ * server per request: `registerPreparedMcpTools(server, prepared, { context })`.
+ */
+export function prepareMcpTools<R extends AnyRouter>(
 	router: R,
-	options: RegisterMcpToolsOptions<R, TResult>
-) {
-	const definitions = listTools(router, {
+	options: McpToolSelection
+): PreparedMcpTools<R> {
+	if (typeof options.filter !== 'function')
+		throw new TypeError(
+			'orpc-fn: MCP tools need a filter; tool exposure is an explicit choice'
+		)
+	const tools = listTools(router, {
 		filter: options.filter,
 		...(options.readOnly ? { readOnly: options.readOnly } : {}),
 		...(options.name ? { name: options.name } : {})
 	})
-	const tools = new Map(definitions.map((tool) => [tool.name, tool]))
-	const descriptions = definitions.map((tool) => {
+	const descriptions = tools.map((tool) => {
 		const inputSchema = tool.config.inputSchema?.[
 			'~standard'
 		].jsonSchema.input() ?? { type: 'object', properties: {} }
@@ -67,8 +83,38 @@ export function createToolHandlers<R extends AnyRouter, TResult>(
 		}
 	})
 	return {
-		names: [...tools.keys()] as readonly string[],
-		list: () => ({ tools: descriptions }),
+		router,
+		names: tools.map((tool) => tool.name),
+		tools,
+		descriptions
+	}
+}
+
+/** Default protocol result: JSON/text. Provide formatResult for other MCP content. */
+export function formatMcpResult(value: unknown): TextToolResult {
+	const text =
+		typeof value === 'string'
+			? value
+			: (JSON.stringify(value, (_key, item) =>
+					typeof item === 'bigint' ? item.toString() : item
+				) ?? 'null')
+	return { content: [{ type: 'text', text }] }
+}
+
+const errorResult = (text: string): TextToolResult => ({
+	content: [{ type: 'text', text }],
+	isError: true
+})
+
+/** @internal SDK-independent `tools/list` and `tools/call` behind both adapters. */
+export function createToolHandlers<R extends AnyRouter, TResult>(
+	prepared: PreparedMcpTools<R>,
+	options: McpCallOptions<R, TResult>
+) {
+	const tools = new Map(prepared.tools.map((tool) => [tool.name, tool]))
+	return {
+		names: prepared.names,
+		list: () => ({ tools: [...prepared.descriptions] }),
 		call: async (
 			name: string,
 			args: Record<string, unknown> | undefined,
@@ -83,7 +129,10 @@ export function createToolHandlers<R extends AnyRouter, TResult>(
 				].validate(args ?? {})
 				if (validation?.issues)
 					return errorResult(
-						validation.issues.map((issue) => issue.message).join('; ')
+						[
+							'BAD_REQUEST: Invalid tool input',
+							...validation.issues.map(formatIssue)
+						].join('\n')
 					)
 				const context = await options.context({ name: tool.name, signal })
 				const result = await call(tool.procedure, validation?.value, {
@@ -93,9 +142,7 @@ export function createToolHandlers<R extends AnyRouter, TResult>(
 				return await (options.formatResult ?? formatMcpResult)(result, tool)
 			} catch (error) {
 				if (signal.aborted) throw error
-				return errorResult(
-					error instanceof Error ? error.message : String(error)
-				)
+				return errorResult(toolErrorText(error, tool.name, options))
 			}
 		}
 	}