effect 4.0.3 → 4.0.4

package/src/ai/McpServer.ts

@@ -104,8 +104,19 @@ interface QueuedServerNotification {
 const internalState = new WeakMap<object, {
   readonly core: McpCore.McpCore
   readonly notifications: Queue.Dequeue<QueuedServerNotification>
-  readonly notificationDelivery: { consumers: number; listChangeRevision: number }
+  readonly notificationDelivery: { consumers: number; listChangeRevision: number; requestEndpoints: number }
 }>()
+
+// Request-scoped HTTP servers deliver a request's own notifications through
+// that request's server instead of the shared notification queue.
+const RequestNotificationQueue = Context.Reference<Queue.Queue<QueuedServerNotification> | undefined>(
+  "effect/ai/McpServer/RequestNotificationQueue",
+  { defaultValue: () => undefined }
+)
+// Progress and logs belong to the request that emitted them.
+const isRequestNotification = (notification: McpCore.ServerNotification) =>
+  notification._tag === "Progress" || notification._tag === "LoggingMessage"
+
 type ServerExtensions = NonNullable<ServerCapabilities["extensions"]>
 type ServerNotificationRequest<
   R extends Rpc.Any = RpcGroup.Rpcs<typeof BroadcastServerNotificationRpcs>
@@ -322,7 +333,10 @@ export class McpServer extends Context.Service<McpServer, {
       readonly annotations: Context.Context<never>
     }> = []
     const notificationsQueue = yield* Queue.make<QueuedServerNotification>()
-    const notificationDelivery = { consumers: 0, listChangeRevision: 0 }
+    const notificationDelivery = { consumers: 0, listChangeRevision: 0, requestEndpoints: 0 }
+    // With only request-scoped endpoints, no long-lived server ever takes from the shared queue.
+    const withoutSharedConsumer = () =>
+      notificationDelivery.consumers === 0 && notificationDelivery.requestEndpoints > 0
     const pendingListChanges = new Map<string, QueuedServerNotification>()
     const dispatcher = (yield* Scheduler).makeDispatcher()
     const notifications = yield* RpcClient.makeNoSerialization(BroadcastServerNotificationRpcs, {
@@ -344,6 +358,26 @@ export class McpServer extends Context.Service<McpServer, {
               requestContext: Context.getOrUndefined(fiber.context, McpRequestContext),
               requestHeaders: Context.getOrUndefined(fiber.context, HttpServerRequest.HttpServerRequest)?.headers
             }
+            // write resumes the caller synchronously, so defer it until delivery completes.
+            const acknowledge = Effect.suspend(() =>
+              notifications.write({
+                clientId: 0,
+                requestId: message.id,
+                _tag: "Exit",
+                exit: Exit.void
+              })
+            )
+            // A request-scoped endpoint delivers its request's own progress and logs on that request's response.
+            const requestQueue = Context.get(fiber.context, RequestNotificationQueue)
+            if (
+              requestQueue !== undefined && queued.requestContext !== undefined && isRequestNotification(notification)
+            ) {
+              Queue.offerUnsafe(requestQueue, queued)
+              return Effect.andThen(Deferred.await(delivered), acknowledge)
+            }
+            if (withoutSharedConsumer()) {
+              return acknowledge
+            }
             let enqueued = false
             if (message.tag.includes("list_changed")) {
               const revision = ++notificationDelivery.listChangeRevision
@@ -364,15 +398,6 @@ export class McpServer extends Context.Service<McpServer, {
               enqueued = true
               Queue.offerUnsafe(notificationsQueue, queued)
             }
-            // write resumes the caller synchronously, so defer it until delivery completes.
-            const acknowledge = Effect.suspend(() =>
-              notifications.write({
-                clientId: 0,
-                requestId: message.id,
-                _tag: "Exit",
-                exit: Exit.void
-              })
-            )
             return enqueued && queued.requestContext !== undefined && notificationDelivery.consumers > 0
               ? Effect.andThen(Deferred.await(delivered), acknowledge)
               : acknowledge
@@ -383,7 +408,7 @@ export class McpServer extends Context.Service<McpServer, {
     const service = McpServer.of({
       notifications: notifications.client,
       notifyElicitationComplete: ({ clientId, elicitationId }) =>
-        Deferred.make<void>().pipe(
+        withoutSharedConsumer() ? Effect.void : Deferred.make<void>().pipe(
           Effect.flatMap((delivered) =>
             Queue.offer(notificationsQueue, {
               notification: McpCore.ServerNotification.ElicitationComplete({ elicitationId }),
@@ -727,7 +752,11 @@ const runWithRuntime = Effect.fnUntraced(function*(
     readonly allowSubscriptions?: boolean | undefined
   },
   runtime: McpRuntime.ServerRuntimeShape,
-  transport: "custom" | "http" | "stdio"
+  transport: "custom" | "http" | "stdio",
+  requestScoped?: {
+    readonly notifications: Queue.Dequeue<QueuedServerNotification>
+    readonly handlers: Context.Context<never>
+  }
 ) {
   const protocol = yield* RpcServer.Protocol
   const server = yield* McpServer
@@ -817,7 +846,7 @@ const runWithRuntime = Effect.fnUntraced(function*(
     })
   let writeFromClient!: (clientId: number, message: RpcMessage.FromClientEncoded) => Effect.Effect<void>
   const { core, notificationDelivery, notifications } = internalState.get(server)!
-  const handlers = yield* runtime.installHandlers({
+  const handlers = requestScoped?.handlers ?? (yield* runtime.installHandlers({
     core,
     subscribeServerNotifications: PubSub.subscribe(serverNotifications),
     getListChangeRevision: () => notificationDelivery.listChangeRevision,
@@ -831,7 +860,7 @@ const runWithRuntime = Effect.fnUntraced(function*(
     }),
     defaultLogLevel,
     serverInfo: options
-  })
+  }))
 
   const clients = yield* RcMap.make({
     lookup: Effect.fnUntraced(function*(key: McpClientKey) {
@@ -1252,17 +1281,19 @@ const runWithRuntime = Effect.fnUntraced(function*(
     })
   }
 
-  yield* Effect.acquireRelease(
-    Effect.sync(() => {
-      notificationDelivery.consumers++
-    }),
-    () =>
+  if (requestScoped === undefined) {
+    yield* Effect.acquireRelease(
       Effect.sync(() => {
-        notificationDelivery.consumers--
-      })
-  )
+        notificationDelivery.consumers++
+      }),
+      () =>
+        Effect.sync(() => {
+          notificationDelivery.consumers--
+        })
+    )
+  }
   const notificationTails = new Map<number, Deferred.Deferred<void>>()
-  yield* Queue.take(notifications).pipe(
+  yield* Queue.take(requestScoped?.notifications ?? notifications).pipe(
     Effect.flatMap(Effect.fnUntraced(function*(queued) {
       const { delivered, listChangeRevision, notification, targetClientId, requestContext, requestHeaders } = queued
       if (McpProtocolInternal.isSubscriptionServerNotification(notification)) {
@@ -1276,7 +1307,7 @@ const runWithRuntime = Effect.fnUntraced(function*(
           runtime.disconnect(clientId)
         }
       }
-      const requestNotification = notification._tag === "LoggingMessage" || notification._tag === "Progress"
+      const requestNotification = isRequestNotification(notification)
       const deliveryClientIds = requestNotification && requestContext !== undefined
         ? [requestContext.clientId]
         : targetClientId === undefined
@@ -1594,11 +1625,20 @@ const mcpStdioSerialization = (
  * Method not found. Request-scoped progress and logs, legacy protocols, and
  * default subscription behavior are unchanged.
  *
+ * The layer runs one long-lived MCP server that every POST shares. For
+ * serverless hosts where execution must belong to each request, use
+ * `layerHttpRequestScoped` instead.
+ *
  * `layerHttp` always implements the single-endpoint Streamable HTTP topology.
  * Using `v2024_11_05` here is a custom compatibility transport for that
  * revision's schema. It does not implement the historical two-endpoint
  * HTTP+SSE transport, GET SSE, event resumption, or session expiry.
  *
+ * **Gotchas**
+ *
+ * This layer starts a scoped server fiber. For sharing it across Cloudflare
+ * Workers requests, see `HttpRouter.toWebHandler` for setup and limitations.
+ *
  * @see {@link layerStdio} for exposing the server over stdio
  * @see {@link layer} for the base MCP server layer without a transport protocol
  *
@@ -1628,6 +1668,105 @@ export const layerHttp = (options: {
   )
 }
 
+/**
+ * Registers a request-scoped Streamable HTTP MCP endpoint at `options.path`.
+ *
+ * **When to use**
+ *
+ * Use when serving on serverless hosts such as Cloudflare Workers, where execution must
+ * belong to the HTTP request rather than a shared long-lived server.
+ *
+ * **Details**
+ *
+ * Each POST runs its own server in the request scope, with no background
+ * fiber, timer, or queue consumer left after the response body completes.
+ * Only sessionless protocols such as `v2026_07_28` are accepted. Tools,
+ * resources, prompts, completions, multi round-trip input requests, and the
+ * request's own progress and log notifications are supported. Legacy reverse
+ * requests through `McpServer.elicit` are not available.
+ *
+ * Discovery advertises `listChanged: false`, `subscriptions/listen` returns
+ * Method not found, and DELETE returns `405`. Request-scoped clients receive
+ * no broadcast notifications such as list changes. Those still reach clients
+ * of a `layerHttp` endpoint sharing the same `McpServer`, and are dropped when
+ * no such endpoint exists. Use `layerHttp` on a long-lived host for sessions,
+ * subscriptions, or legacy reverse requests.
+ *
+ * HTTP admission, origin checks, and JSON-RPC errors follow `layerHttp`.
+ * Configuring a sessionful protocol through an untyped caller fails layer
+ * construction with `IllegalArgumentError`.
+ *
+ * @see {@link layerHttp} for the long-lived HTTP transport and HTTP admission policy
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export const layerHttpRequestScoped = (options: {
+  readonly name: string
+  readonly version: string
+  readonly instructions?: string | undefined
+  readonly description?: string | undefined
+  readonly websiteUrl?: string | undefined
+  readonly icons?: ReadonlyArray<McpSchema.Icon> | undefined
+  readonly path: HttpRouter.PathInput
+  readonly protocols: Arr.NonEmptyReadonlyArray<
+    McpProtocol.ProtocolAdapter<McpProtocol.ProtocolVersion, McpProtocol.StatelessRuntimeDescriptor>
+  >
+  readonly extensions?: ServerExtensions | undefined
+  readonly allowedOrigins?: ReadonlyArray<string> | undefined
+}): Layer.Layer<McpServer | McpServerClient, Cause.IllegalArgumentError, HttpRouter.HttpRouter> =>
+  Layer.effectDiscard(Effect.gen(function*() {
+    const runtime = yield* McpRuntime.ServerRuntime
+    const stateful = runtime.protocols.find((protocol) => protocol.runtime._tag === "Stateful")
+    if (stateful !== undefined) {
+      return yield* new Cause.IllegalArgumentError(
+        `McpServer.layerHttpRequestScoped does not support the sessionful MCP protocol ${stateful.protocolVersion}`
+      )
+    }
+    const server = yield* McpServer
+    const { core, notificationDelivery } = internalState.get(server)!
+    // Subscriptions are disabled, so handlers hold no per-request state and
+    // read registrations from the shared core on every call. Request services
+    // still take precedence over the layer context captured here.
+    const handlers = yield* (runtime.installHandlers({
+      core,
+      subscribeServerNotifications: Effect.die("Subscriptions are disabled for request-scoped MCP servers"),
+      getListChangeRevision: () => notificationDelivery.listChangeRevision,
+      defaultLogLevel: yield* CurrentLogLevel,
+      serverInfo: options
+    }) as Effect.Effect<Context.Context<never>>)
+    yield* Effect.acquireRelease(
+      Effect.sync(() => {
+        notificationDelivery.requestEndpoints++
+      }),
+      () =>
+        Effect.sync(() => {
+          notificationDelivery.requestEndpoints--
+        })
+    )
+    // Each POST runs its own RPC server in the request scope, so no fiber,
+    // timer, or queue consumer outlives the request that created it.
+    yield* addMcpHttpRoutes(
+      options,
+      Effect.gen(function*() {
+        const { httpEffect, protocol } = yield* RpcServer.makeProtocolWithHttpEffect().pipe(
+          Effect.provideService(RpcSerialization.RpcSerialization, mcpHttpSerialization)
+        )
+        const notifications = yield* Queue.make<QueuedServerNotification>()
+        yield* runWithRuntime(options, runtime, "http", { notifications, handlers }).pipe(
+          Effect.provideService(RpcServer.Protocol, protocol),
+          Effect.provideService(McpServer, server),
+          Effect.forkScoped({ startImmediately: true })
+        )
+        return yield* Effect.provideService(httpEffect, RequestNotificationQueue, notifications)
+      })
+    )
+  })).pipe(
+    Layer.provideMerge(McpServer.layer),
+    Layer.provide(McpRuntime.layer(options.protocols))
+  )
+
 const layerMcpProtocolHttp = (options: {
   readonly path: HttpRouter.PathInput
   readonly allowedOrigins?: ReadonlyArray<string> | undefined
@@ -1638,81 +1777,96 @@ const layerMcpProtocolHttp = (options: {
   McpRuntime.ServerRuntime | HttpRouter.HttpRouter
 > =>
   Layer.effect(RpcServer.Protocol)(Effect.gen(function*() {
-    const runtime = yield* McpRuntime.ServerRuntime
     const { httpEffect, protocol } = yield* RpcServer.makeProtocolWithHttpEffect().pipe(
       Effect.provideService(RpcSerialization.RpcSerialization, mcpHttpSerialization)
     )
-    const router = yield* HttpRouter.HttpRouter
-    const allowSessionTermination = options.allowSessionTermination === true &&
-      runtime.protocols.some((protocol) => protocol.runtime._tag === "Stateful")
-    const forbidden = Effect.succeed(HttpServerResponse.empty({ status: 403 }))
-    const withAllowedOrigin = (
-      handler: (request: HttpServerRequest.HttpServerRequest) => Effect.Effect<HttpServerResponse.HttpServerResponse>
-    ) =>
-    (request: HttpServerRequest.HttpServerRequest) =>
-      isAllowedMcpOrigin(request, options.allowedOrigins) ? handler(request) : forbidden
-    const methodNotAllowedResponse = Effect.succeed(HttpServerResponse.empty({
-      status: 405,
-      headers: { allow: allowSessionTermination ? "POST, DELETE" : "POST" }
-    }))
-    const methodNotAllowed = withAllowedOrigin(() => methodNotAllowedResponse)
-    for (const method of ["GET", "PUT", "PATCH", "OPTIONS"] as const) {
-      yield* router.add(method, options.path, methodNotAllowed)
+    yield* addMcpHttpRoutes(options, httpEffect)
+    return protocol
+  }))
+
+const addMcpHttpRoutes = Effect.fnUntraced(function*(
+  options: {
+    readonly path: HttpRouter.PathInput
+    readonly allowedOrigins?: ReadonlyArray<string> | undefined
+    readonly allowSessionTermination?: boolean | undefined
+  },
+  httpEffect: Effect.Effect<
+    HttpServerResponse.HttpServerResponse,
+    never,
+    Scope.Scope | HttpServerRequest.HttpServerRequest
+  >
+) {
+  const runtime = yield* McpRuntime.ServerRuntime
+  const router = yield* HttpRouter.HttpRouter
+  const allowSessionTermination = options.allowSessionTermination === true &&
+    runtime.protocols.some((protocol) => protocol.runtime._tag === "Stateful")
+  const forbidden = Effect.succeed(HttpServerResponse.empty({ status: 403 }))
+  const withAllowedOrigin = (
+    handler: (request: HttpServerRequest.HttpServerRequest) => Effect.Effect<HttpServerResponse.HttpServerResponse>
+  ) =>
+  (request: HttpServerRequest.HttpServerRequest) =>
+    isAllowedMcpOrigin(request, options.allowedOrigins) ? handler(request) : forbidden
+  const methodNotAllowedResponse = Effect.succeed(HttpServerResponse.empty({
+    status: 405,
+    headers: { allow: allowSessionTermination ? "POST, DELETE" : "POST" }
+  }))
+  const methodNotAllowed = withAllowedOrigin(() => methodNotAllowedResponse)
+  for (const method of ["GET", "PUT", "PATCH", "OPTIONS"] as const) {
+    yield* router.add(method, options.path, methodNotAllowed)
+  }
+  yield* router.add(
+    "DELETE",
+    options.path,
+    allowSessionTermination
+      ? withAllowedOrigin((request) => runtime.terminateHttpSession(request.headers))
+      : methodNotAllowed
+  )
+  yield* router.add("POST", options.path, (request) => {
+    if (!isAllowedMcpOrigin(request, options.allowedOrigins)) {
+      return Effect.succeed(HttpServerResponse.empty({ status: 403 }))
     }
-    yield* router.add(
-      "DELETE",
-      options.path,
-      allowSessionTermination
-        ? withAllowedOrigin((request) => runtime.terminateHttpSession(request.headers))
-        : methodNotAllowed
-    )
-    yield* router.add("POST", options.path, (request) => {
-      if (!isAllowedMcpOrigin(request, options.allowedOrigins)) {
-        return Effect.succeed(HttpServerResponse.empty({ status: 403 }))
-      }
-      if (mcpMediaTypes(request.headers["content-type"])[0] !== "application/json") {
-        return Effect.succeed(HttpServerResponse.empty({ status: 415 }))
+    if (mcpMediaTypes(request.headers["content-type"])[0] !== "application/json") {
+      return Effect.succeed(HttpServerResponse.empty({ status: 415 }))
+    }
+    const accepted = mcpMediaTypes(request.headers["accept"])
+    if (!accepted.includes("application/json") || !accepted.includes("text/event-stream")) {
+      return Effect.succeed(HttpServerResponse.empty({ status: 406 }))
+    }
+    return Effect.gen(function*() {
+      const parsed = yield* Effect.result(
+        Effect.flatMap(request.text, Schema.decodeEffect(Schema.UnknownFromJsonString))
+      )
+      const admission = runtime.admitHttp(request.headers, parsed)
+      if (admission._tag === "Rejected") {
+        return admission.response
       }
-      const accepted = mcpMediaTypes(request.headers["accept"])
-      if (!accepted.includes("application/json") || !accepted.includes("text/event-stream")) {
-        return Effect.succeed(HttpServerResponse.empty({ status: 406 }))
+      const toResponse = (response: HttpServerResponse.HttpServerResponse) => {
+        // Completed responses may already contain notifications followed by the result.
+        const hasMultipleMessages = response.body._tag === "Uint8Array" &&
+          response.body.body.subarray(0, -1).includes(10)
+        return admission.isSubscription || response.body._tag === "Stream" || hasMultipleMessages
+          ? toServerSentEvents(response, admission.isSubscription)
+          : response
       }
-      return Effect.gen(function*() {
-        const parsed = yield* Effect.result(
-          Effect.flatMap(request.text, Schema.decodeEffect(Schema.UnknownFromJsonString))
+      if (admission.acknowledge) {
+        return yield* Effect.catchCause(
+          Effect.map(httpEffect, toResponse),
+          () => Effect.succeed(HttpServerResponse.empty({ status: 202 }))
         )
-        const admission = runtime.admitHttp(request.headers, parsed)
-        if (admission._tag === "Rejected") {
-          return admission.response
-        }
-        const toResponse = (response: HttpServerResponse.HttpServerResponse) => {
-          // Completed responses may already contain notifications followed by the result.
-          const hasMultipleMessages = response.body._tag === "Uint8Array" &&
-            response.body.body.subarray(0, -1).includes(10)
-          return admission.isSubscription || response.body._tag === "Stream" || hasMultipleMessages
-            ? toServerSentEvents(response, admission.isSubscription)
-            : response
-        }
-        if (admission.acknowledge) {
-          return yield* Effect.catchCause(
-            Effect.map(httpEffect, toResponse),
-            () => Effect.succeed(HttpServerResponse.empty({ status: 202 }))
-          )
+      }
+      return yield* Effect.flatMap(httpEffect, (response) => {
+        if (response.body._tag !== "Uint8Array" || response.body.body.length > 0) {
+          return Effect.succeed(toResponse(response))
         }
-        return yield* Effect.flatMap(httpEffect, (response) => {
-          if (response.body._tag !== "Uint8Array" || response.body.body.length > 0) {
-            return Effect.succeed(toResponse(response))
-          }
-          // Only fully cancelled request POSTs may return an empty SSE response.
-          // https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#sending-messages-to-the-server
-          return httpPostResponses.get(request)?.expected === 0
-            ? Effect.succeed(HttpServerResponse.stream(Stream.empty, { contentType: "text/event-stream" }))
-            : Effect.die(new Error("MCP request ended without writing its response"))
-        })
+        // Only fully cancelled request POSTs may return an empty SSE response.
+        // https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#sending-messages-to-the-server
+        return httpPostResponses.get(request)?.expected === 0
+          ? Effect.succeed(HttpServerResponse.stream(Stream.empty, { contentType: "text/event-stream" }))
+          : Effect.die(new Error("MCP request ended without writing its response"))
       })
     })
-    return protocol
-  }))
+  })
+})
 
 const mcpHttpSerialization: RpcSerialization.RpcSerialization["Service"] = (() => {
   const serialization = mcpJsonRpcSerialization()

package/src/ai/Prompt.ts

@@ -2159,11 +2159,11 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
     return empty
   }
 
-  const assistantParts: Array<AssistantMessagePart> = []
+  const assistantParts: Array<AssistantMessagePart | undefined> = []
   const toolParts: Array<ToolMessagePart> = []
 
-  const activeTextDeltas = new Map<string, { text: string; options: ProviderOptions }>()
-  const activeReasoningDeltas = new Map<string, { text: string; options: ProviderOptions }>()
+  const activeTextDeltas = new Map<string, { index: number; text: string; options: ProviderOptions }>()
+  const activeReasoningDeltas = new Map<string, { index: number; text: string; options: ProviderOptions }>()
 
   for (const part of parts) {
     switch (part.type) {
@@ -2175,7 +2175,8 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
 
       // Text Parts (streaming)
       case "text-start": {
-        activeTextDeltas.set(part.id, { text: "", options: part.metadata })
+        activeTextDeltas.set(part.id, { index: assistantParts.length, text: "", options: part.metadata })
+        assistantParts.push(undefined)
         break
       }
       case "text-delta": {
@@ -2190,7 +2191,8 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
         if (activeTextDeltas.has(part.id)) {
           const active = activeTextDeltas.get(part.id)!
           active.options = mergeOptions(active.options, part.metadata)
-          assistantParts.push(makePart("text", active))
+          assistantParts[active.index] = makePart("text", { text: active.text, options: active.options })
+          activeTextDeltas.delete(part.id)
         }
         break
       }
@@ -2203,7 +2205,8 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
 
       // Reasoning Parts (streaming)
       case "reasoning-start": {
-        activeReasoningDeltas.set(part.id, { text: "", options: part.metadata })
+        activeReasoningDeltas.set(part.id, { index: assistantParts.length, text: "", options: part.metadata })
+        assistantParts.push(undefined)
         break
       }
       case "reasoning-delta": {
@@ -2218,7 +2221,8 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
         if (activeReasoningDeltas.has(part.id)) {
           const active = activeReasoningDeltas.get(part.id)!
           active.options = mergeOptions(active.options, part.metadata)
-          assistantParts.push(makePart("reasoning", active))
+          assistantParts[active.index] = makePart("reasoning", { text: active.text, options: active.options })
+          activeReasoningDeltas.delete(part.id)
         }
         break
       }
@@ -2272,14 +2276,24 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
     }
   }
 
-  if (assistantParts.length === 0 && toolParts.length === 0) {
+  // Keep partial text from unended blocks. Unended reasoning is dropped since it
+  // may lack the signature or encrypted content providers require for replay.
+  for (const active of activeTextDeltas.values()) {
+    if (active.text.length > 0) {
+      assistantParts[active.index] = makePart("text", { text: active.text, options: active.options })
+    }
+  }
+
+  const assistantContent = assistantParts.filter((part) => part !== undefined)
+
+  if (assistantContent.length === 0 && toolParts.length === 0) {
     return empty
   }
 
   const messages: Array<Message> = []
 
-  if (assistantParts.length > 0) {
-    messages.push(makeMessage("assistant", { content: assistantParts }))
+  if (assistantContent.length > 0) {
+    messages.push(makeMessage("assistant", { content: assistantContent }))
   }
 
   if (toolParts.length > 0) {

package/src/ai/Response.ts

@@ -441,16 +441,19 @@ export const StreamPart = <T extends Toolkit.Any | Toolkit.WithHandler<any>>(
 export type ToolCallParts<
   Tools extends Record<string, Tool.Any>,
   ParametersMode extends ToolParametersMode = "decoded"
-> = ToolCallPartForName<Tools, ParametersMode, keyof Tools>
+> = ParametersMode extends "deferred" ?
+  ToolCallPartForName<Tools, "opaque", keyof Tools> | ToolCallPart<string, unknown>
+  : ToolCallPartForName<Tools, ParametersMode, keyof Tools>
 
 /**
- * Controls whether tool parameters are decoded, encoded, or opaque.
+ * Controls tool parameter decoding. `"deferred"` allows undeclared tool names
+ * with opaque parameters, leaving validation to the caller.
  *
  * @stability unstable
  * @category utility types
  * @since 4.0.0
  */
-export type ToolParametersMode = "decoded" | "encoded" | "opaque"
+export type ToolParametersMode = "decoded" | "encoded" | "opaque" | "deferred"
 
 type ToolCallPartForName<
   Tools extends Record<string, Tool.Any>,

package/src/cluster/ClusterWorkflowEngine.ts

@@ -291,10 +291,7 @@ export const make = Effect.gen(function*() {
       id: ""
     })
 
-    const maybeSuspended = Option.filter(
-      maybeReply,
-      (reply) => reply.exit._tag === "Success" && reply.exit.value._tag === "Suspended"
-    )
+    const maybeSuspended = Option.filter(maybeReply, isSuspendedReply)
 
     if (Option.isNone(maybeSuspended)) return
     if (
@@ -328,10 +325,14 @@ export const make = Effect.gen(function*() {
     yield* sharding.reset(requestId.value)
   }, Effect.scoped)
 
-  // A child or deferred may complete while a run is still unwinding. Subscribe
-  // to the run's reply before reading storage so the wake cannot fall between
-  // the run's last read and its suspended reply.
-  const waitForRunReply = Effect.fnUntraced(function*(workflow: Workflow.Any, request: Entity.Request<any>) {
+  // Subscribe to the run's next reply before reading storage, so a reply
+  // cannot fall between the read and the subscription. Returns `true` when the
+  // stored reply already settles the wait, `false` when a new reply arrived.
+  const awaitRunReply = Effect.fnUntraced(function*(
+    workflow: Workflow.Any,
+    request: Envelope.Request<any>,
+    isSettled: (reply: WithExitEncoded<Workflow.ResultEncoded<any, any>>) => boolean
+  ) {
     const waiter = yield* storage.registerReplyHandler(
       new Message.OutgoingRequest<any>({
         envelope: request,
@@ -343,12 +344,45 @@ export const make = Effect.gen(function*() {
       })
     ).pipe(Effect.forkScoped({ startImmediately: true }))
     const reply = yield* replyForRequestId(request.requestId)
-    if (Option.isSome(reply)) return
-    yield* Fiber.join(waiter).pipe(
+    if (Option.isSome(reply) && isSettled(reply.value)) return true
+    yield* Fiber.join(waiter)
+    return false
+  }, Effect.scoped)
+
+  // A child or deferred may complete while a run is still unwinding. Wait for
+  // the run's reply so the wake cannot fall between the run's last read and
+  // its suspended reply.
+  const waitForRunReply = (workflow: Workflow.Any, request: Entity.Request<any>) =>
+    awaitRunReply(workflow, request, () => true).pipe(
+      Effect.asVoid,
       Effect.catchTag("EntityNotAssignedToRunner", () => ClusterAbandon.interrupt),
       Effect.catchCause((cause) => ClusterAbandon.isCause(cause) ? ClusterAbandon.interrupt : Effect.failCause(cause))
     )
-  }, Effect.scoped)
+
+  // Wake an external caller once its run publishes a reply other than
+  // `Suspended`. Replies are only observed on the runner that saves them, so
+  // callers on other runners, and any failure here, leave delivery to the
+  // caller's retry schedule.
+  const awaitComplete = (workflow: Workflow.Any, executionId: string) =>
+    Effect.gen(function*() {
+      const address = entityAddressFor({ workflow, entityType: `Workflow/${workflow._tag}`, executionId })
+      if (!sharding.hasShardId(address.shardId)) return yield* Effect.never
+      const requestId = yield* storage.requestIdForPrimaryKey({ address, tag: "run", id: "" })
+      if (Option.isNone(requestId)) return yield* Effect.never
+      const request = Envelope.makeRequest<any>({
+        requestId: requestId.value,
+        address,
+        tag: "run",
+        payload: {},
+        headers: Headers.empty
+      })
+      // A replay that suspends again re-arms the wait, so it does not spend a
+      // step of the caller's retry schedule.
+      let settled = false
+      while (!settled) {
+        settled = yield* awaitRunReply(workflow, request, (reply) => !isSuspendedReply(reply))
+      }
+    }).pipe(Effect.catchCause(() => Effect.never))
 
   const interrupt = Effect.fnUntraced(
     function*(workflow: Workflow.Any, executionId: string) {
@@ -367,7 +401,7 @@ export const make = Effect.gen(function*() {
 
       const nonSuspendedReply = Option.filter(
         reply,
-        (reply) => reply.exit._tag !== "Success" || reply.exit.value._tag !== "Suspended"
+        (reply) => !isSuspendedReply(reply)
       )
       if (Option.isSome(nonSuspendedReply)) {
         return Option.none()
@@ -617,6 +651,8 @@ export const make = Effect.gen(function*() {
 
     resume: (workflow, executionId) => ensureSuccess(resume(workflow, executionId)),
 
+    awaitComplete,
+
     activityExecute: Effect.fnUntraced(
       function*(activity, attempt) {
         const services = yield* Effect.context<WorkflowEngine.WorkflowInstance>()
@@ -809,6 +845,9 @@ const DeferredRpc = Rpc.make("deferred", {
   .annotate(ClusterSchema.Persisted, true)
   .annotate(ClusterSchema.Uninterruptible, true)
 
+const isSuspendedReply = (reply: WithExitEncoded<Workflow.ResultEncoded<any, any>>) =>
+  reply.exit._tag === "Success" && reply.exit.value._tag === "Suspended"
+
 const decodeDeferredWithExit = Schema.decodeSync(Schema.toCodecJson(Reply.WithExit.schema(DeferredRpc)))
 
 const ResumeRpc = Rpc.make("resume", {