experimental-ash 0.25.0 → 0.25.2

package/dist/src/execution/workflow-steps.js

@@ -4,21 +4,22 @@ import { dispatchStreamEventHooks, runHookLifecycleStep } from "#context/hook-li
 import { AuthKey, BundleKey, CapabilitiesKey, ChannelKey, ContinuationTokenKey, InitiatorAuthKey, ModeKey, } from "#context/keys.js";
 import { runStep } from "#context/run-step.js";
 import { deserializeContext, serializeContext } from "#context/serialize.js";
-import { getHarnessEmissionState, isHarnessBetweenTurns } from "#harness/emission.js";
+import { isHarnessBetweenTurns } from "#harness/emission.js";
 import { coalesceTurnInputs } from "#harness/messages.js";
 import { upsertProxyInputRequests } from "#harness/proxy-input-requests.js";
 import { getPendingRuntimeActionBatch, recordPendingSubagentChildToken, } from "#harness/runtime-actions.js";
 import { createLogger, formatError } from "#internal/logging.js";
 import { createSessionFailedEvent, createSubagentCalledEvent, encodeMessageStreamEvent, timestampHandleMessageStreamEvent, } from "#protocol/message.js";
-import { drainPendingConnectionAuthorizations, PendingConnectionAuthorizationsKey, } from "#runtime/framework-tools/connection-search.js";
 import { PendingConnectionToolCallsKey, } from "#runtime/framework-tools/pending-connection-tool-calls.js";
 import { getCompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-cache.js";
 import { createExecutionNodeStep } from "#execution/node-step.js";
+import { resolveRemoteAgentForAction, startRemoteAgentSession, } from "#execution/remote-agent-dispatch.js";
 import { emitProxiedInputRequest, routeDeliverPayload } from "#execution/subagent-hitl-proxy.js";
 import { createSession, refreshSessionFromTurnAgent } from "#execution/session.js";
 import { buildSubagentRunInput } from "#execution/subagent-tool.js";
 import { turnWorkflow } from "#execution/turn-workflow.js";
 import { createWorkflowRuntime, startWorkflowPreferLatest, workflowEntryReference, } from "#execution/workflow-runtime.js";
+import { toErrorMessage } from "#shared/errors.js";
 /**
  * Runs one atomic harness step inside a durable `"use step"` boundary.
  */
@@ -100,13 +101,7 @@ export async function turnStep(input) {
                 mode,
                 node: bundle.graph.root,
             });
-            const result = await step(refreshedSession, stepInput);
-            await drainPendingConnectionAuthorizations({
-                ctx,
-                emit,
-                state: getHarnessEmissionState(result.session),
-            });
-            return result;
+            return step(refreshedSession, stepInput);
         };
         // Lifecycle hooks fire only at the start of a new turn — when the
         // workflow has freshly delivered input and the harness is between
@@ -142,13 +137,11 @@ export async function turnStep(input) {
     // serialized context; the resolve step clears them after
     // successful retry.
     const pendingToolCalls = ctx.get(PendingConnectionToolCallsKey) ?? [];
-    const pendingAuths = ctx.get(PendingConnectionAuthorizationsKey) ?? [];
-    if (pendingToolCalls.length > 0 && pendingAuths.length > 0) {
+    if (pendingToolCalls.length > 0) {
         writer.releaseLock();
         return {
             action: "await-authorization",
             pendingToolCalls,
-            pendingAuths,
             serializedContext: nextSerializedContext,
             session: stepResult.session,
         };
@@ -210,7 +203,7 @@ export async function dispatchPendingRuntimeActionsStep(input) {
     "use step";
     const batch = getPendingRuntimeActionBatch(input.session);
     if (batch === undefined || batch.actions.length === 0) {
-        return input.session;
+        return { results: [], session: input.session };
     }
     const ctx = await deserializeContext(input.serializedContext);
     const bundle = ctx.require(BundleKey);
@@ -221,36 +214,73 @@ export async function dispatchPendingRuntimeActionsStep(input) {
     const writer = input.parentWritable.getWriter();
     const adapterCtx = buildAdapterContext(adapter, ctx);
     let nextSession = input.session;
+    const results = [];
     try {
         for (const action of batch.actions) {
-            if (action.kind !== "subagent-call") {
-                throw new Error(`Unsupported runtime action kind "${action.kind}" in workflow runtime.`);
+            let childSessionId;
+            let name;
+            let remote;
+            let toolName;
+            switch (action.kind) {
+                case "subagent-call": {
+                    const childRuntime = createWorkflowRuntime({
+                        compiledArtifactsSource: bundle.compiledArtifactsSource,
+                        nodeId: action.nodeId,
+                    });
+                    const { childContinuationToken, runInput } = buildSubagentRunInput({
+                        action,
+                        auth,
+                        batchEvent: batch.event,
+                        capabilities,
+                        initiatorAuth,
+                        session: input.session,
+                    });
+                    const handle = await childRuntime.run(runInput);
+                    nextSession = recordPendingSubagentChildToken({
+                        callId: action.callId,
+                        childContinuationToken,
+                        session: nextSession,
+                    });
+                    childSessionId = handle.sessionId;
+                    name = action.name;
+                    toolName = action.subagentName;
+                    break;
+                }
+                case "remote-agent-call": {
+                    let resolvedRemote;
+                    try {
+                        resolvedRemote = resolveRemoteAgentForAction({
+                            nodeId: action.nodeId,
+                            remoteAgentName: action.remoteAgentName,
+                            registry: bundle.subagentRegistry.subagentsByNodeId,
+                        });
+                        childSessionId = await startRemoteAgentSession({
+                            action,
+                            callbackBaseUrl: input.callbackBaseUrl,
+                            remote: resolvedRemote,
+                            session: input.session,
+                        });
+                    }
+                    catch (error) {
+                        results.push(createRemoteAgentStartFailureResult({ action, error }));
+                        continue;
+                    }
+                    name = action.name;
+                    remote = { url: resolvedRemote.url };
+                    toolName = action.remoteAgentName;
+                    break;
+                }
+                default:
+                    throw new Error(`Unsupported runtime action kind "${action.kind}" in workflow runtime.`);
             }
-            const childRuntime = createWorkflowRuntime({
-                compiledArtifactsSource: bundle.compiledArtifactsSource,
-                nodeId: action.nodeId,
-            });
-            const { childContinuationToken, runInput } = buildSubagentRunInput({
-                action,
-                auth,
-                batchEvent: batch.event,
-                capabilities,
-                initiatorAuth,
-                session: input.session,
-            });
-            const handle = await childRuntime.run(runInput);
-            nextSession = recordPendingSubagentChildToken({
-                callId: action.callId,
-                childContinuationToken,
-                session: nextSession,
-            });
             const parentEvent = await callAdapterEventHandler(adapter, createSubagentCalledEvent({
                 callId: action.callId,
-                childSessionId: handle.sessionId,
-                name: action.name,
+                childSessionId,
+                name,
+                remote,
                 sequence: batch.event.sequence,
                 sessionId: input.session.sessionId,
-                toolName: action.subagentName,
+                toolName,
                 turnId: batch.event.turnId,
                 workflowId: workflowEntryReference.workflowId,
             }), adapterCtx);
@@ -260,7 +290,19 @@ export async function dispatchPendingRuntimeActionsStep(input) {
     finally {
         writer.releaseLock();
     }
-    return nextSession;
+    return { results, session: nextSession };
+}
+function createRemoteAgentStartFailureResult(input) {
+    return {
+        callId: input.action.callId,
+        isError: true,
+        kind: "subagent-result",
+        output: {
+            code: "REMOTE_AGENT_START_FAILED",
+            message: toErrorMessage(input.error),
+        },
+        subagentName: input.action.remoteAgentName,
+    };
 }
 const log = createLogger("execution.workflow-entry");
 /**

package/dist/src/harness/execute-tool.d.ts

@@ -6,9 +6,10 @@ import type { NeedsApprovalContext } from "#public/definitions/tool.js";
  * These tools are surfaced to the model without a local `execute` function.
  * The harness records the tool call and the runtime executes it later.
  */
-type HarnessRuntimeActionDefinition = {
-    readonly kind: "subagent-call";
+export type HarnessRuntimeActionDefinition = {
+    readonly kind: "remote-agent-call" | "subagent-call";
     readonly nodeId: string;
+    readonly remoteAgentName?: string;
     readonly subagentName: string;
 };
 /**
@@ -24,4 +25,3 @@ export interface HarnessToolDefinition {
     readonly runtimeAction?: HarnessRuntimeActionDefinition;
     readonly toModelOutput?: (output: unknown) => unknown;
 }
-export {};

package/dist/src/harness/runtime-actions.d.ts

@@ -86,6 +86,7 @@ type RuntimeActionAccumulatorItem<TDeliver> = {
 export declare function accumulateRuntimeActionResults<TDeliver>(input: {
     readonly bufferedDeliveries: TDeliver[];
     readonly getNext: () => Promise<RuntimeActionAccumulatorItem<TDeliver> | null>;
+    readonly initialResults?: readonly RuntimeActionResult[];
     readonly session: HarnessSession;
 }): Promise<RuntimeActionResult[] | null>;
 /**

package/dist/src/harness/runtime-actions.js

@@ -65,7 +65,13 @@ export function recordPendingSubagentChildToken(input) {
  */
 export async function accumulateRuntimeActionResults(input) {
     const batch = getPendingRuntimeActionBatch(input.session);
-    const buffered = [];
+    const buffered = [...(input.initialResults ?? [])];
+    if (batch !== undefined && buffered.length > 0) {
+        const ready = resolveRuntimeActionResultsForBatch({ batch, results: buffered });
+        if (ready !== undefined) {
+            return ready;
+        }
+    }
     while (true) {
         const item = await input.getNext();
         if (item === null) {
@@ -249,6 +255,17 @@ export function createRuntimeActionRequestFromToolCall(input) {
             subagentName: definition.runtimeAction.subagentName,
         };
     }
+    if (definition?.runtimeAction?.kind === "remote-agent-call") {
+        return {
+            callId: input.toolCall.toolCallId,
+            description: definition.description,
+            input: resolveToolCallInputObject(input.toolCall.input),
+            kind: "remote-agent-call",
+            name: definition.name,
+            nodeId: definition.runtimeAction.nodeId,
+            remoteAgentName: definition.runtimeAction.remoteAgentName ?? definition.name,
+        };
+    }
     return {
         callId: input.toolCall.toolCallId,
         input: resolveToolCallInputObject(input.toolCall.input),

package/dist/src/internal/application/package.js

@@ -6,7 +6,7 @@ import { ASH_PACKAGE_NAME } from "#internal/package-name.js";
 let cachedPackageInfo;
 // The package build stamps the published version into `dist` so bundled
 // deployments can still report package metadata without resolving package.json.
-const BUNDLED_FALLBACK_PACKAGE_VERSION = "0.25.0";
+const BUNDLED_FALLBACK_PACKAGE_VERSION = "0.25.2";
 const BUNDLED_FALLBACK_PACKAGE_VERSION_PLACEHOLDER = "__ASH_PACKAGE_VERSION_PLACEHOLDER__";
 const WORKFLOW_MODULE_ALIASES = {
     "workflow/api": "src/compiled/@workflow/core/runtime.js",

package/dist/src/protocol/message.d.ts

@@ -180,6 +180,9 @@ export interface SubagentCalledStreamEvent {
         sessionId: string;
         sequence: number;
         name: string;
+        remote?: {
+            url: string;
+        };
         toolName: string;
         turnId: string;
         workflowId: string;
@@ -579,6 +582,9 @@ export declare function createSubagentCalledEvent(input: {
     readonly sessionId: string;
     readonly sequence: number;
     readonly name: string;
+    readonly remote?: {
+        readonly url: string;
+    };
     readonly toolName: string;
     readonly turnId: string;
     readonly workflowId: string;

package/dist/src/protocol/message.js

@@ -200,6 +200,7 @@ export function createSubagentCalledEvent(input) {
             sessionId: input.sessionId,
             sequence: input.sequence,
             name: input.name,
+            remote: input.remote,
             toolName: input.toolName,
             turnId: input.turnId,
             workflowId: input.workflowId,

package/dist/src/protocol/routes.d.ts

@@ -45,6 +45,13 @@ export declare const ASH_MESSAGE_STREAM_ROUTE_PATTERN = "/ash/v1/session/:sessio
  * exactly what the IdP needs to do.
  */
 export declare const ASH_CONNECTION_CALLBACK_ROUTE_PATTERN = "/ash/v1/connections/:name/callback/:token";
+/**
+ * Stable framework-owned route pattern for terminal session callbacks.
+ *
+ * The `:token` segment is an unguessable workflow hook capability. The route
+ * is unauthenticated by design and resumes the matching parked runtime action.
+ */
+export declare const ASH_CALLBACK_ROUTE_PATTERN = "/ash/v1/callback/:token";
 /**
  * Creates the stable framework-owned message stream route path for one session.
  */
@@ -64,3 +71,7 @@ export declare function createAshContinueSessionRoutePath(sessionId: string): st
  * `resumeHook(token, payload)`.
  */
 export declare function createAshConnectionCallbackRoutePath(name: string, token: string): string;
+/**
+ * Creates the stable framework-owned terminal callback route path.
+ */
+export declare function createAshCallbackRoutePath(token: string): string;

package/dist/src/protocol/routes.js

@@ -45,6 +45,13 @@ export const ASH_MESSAGE_STREAM_ROUTE_PATTERN = `${ASH_ROUTE_PREFIX}/session/:se
  * exactly what the IdP needs to do.
  */
 export const ASH_CONNECTION_CALLBACK_ROUTE_PATTERN = `${ASH_ROUTE_PREFIX}/connections/:name/callback/:token`;
+/**
+ * Stable framework-owned route pattern for terminal session callbacks.
+ *
+ * The `:token` segment is an unguessable workflow hook capability. The route
+ * is unauthenticated by design and resumes the matching parked runtime action.
+ */
+export const ASH_CALLBACK_ROUTE_PATTERN = `${ASH_ROUTE_PREFIX}/callback/:token`;
 /**
  * Creates the stable framework-owned message stream route path for one session.
  */
@@ -70,3 +77,9 @@ export function createAshContinueSessionRoutePath(sessionId) {
 export function createAshConnectionCallbackRoutePath(name, token) {
     return `${ASH_ROUTE_PREFIX}/connections/${encodeURIComponent(name)}/callback/${encodeURIComponent(token)}`;
 }
+/**
+ * Creates the stable framework-owned terminal callback route path.
+ */
+export function createAshCallbackRoutePath(token) {
+    return `${ASH_ROUTE_PREFIX}/callback/${encodeURIComponent(token)}`;
+}

package/dist/src/public/channels/ash.js

@@ -1,4 +1,5 @@
 import {} from "ai";
+import { parseSessionCallback } from "#channel/session-callback.js";
 import { ASH_MESSAGE_STREAM_CONTENT_TYPE, ASH_MESSAGE_STREAM_FORMAT, ASH_MESSAGE_STREAM_VERSION, ASH_SESSION_ID_HEADER, ASH_STREAM_FORMAT_HEADER, ASH_STREAM_VERSION_HEADER, } from "#protocol/message.js";
 import { isInputResponse } from "#runtime/input/types.js";
 import { createUnauthorizedResponse } from "#public/channels/auth.js";
@@ -33,7 +34,9 @@ export function ashChannel(input) {
                 const token = `ash:${crypto.randomUUID()}`;
                 const session = await send(createSendPayload(body), {
                     auth: sessionAuth,
+                    callback: body.callback,
                     continuationToken: token,
+                    mode: body.mode,
                 });
                 return Response.json({
                     continuationToken: session.continuationToken,
@@ -143,10 +146,16 @@ function parseCreateBody(payload) {
     const modelContext = parseClientContextField(payload.clientContext);
     if (modelContext instanceof Response)
         return modelContext;
+    const callback = parseCallbackField(payload.callback);
+    if (callback instanceof Response)
+        return callback;
+    const mode = parseModeField(payload.mode);
+    if (mode instanceof Response)
+        return mode;
     if (message === undefined) {
         return Response.json({ error: "Missing or empty 'message' field.", ok: false }, { status: 400 });
     }
-    return { message, modelContext };
+    return { callback, message, mode, modelContext };
 }
 function parseContinueBody(payload) {
     const continuationToken = typeof payload.continuationToken === "string" && payload.continuationToken.length > 0
@@ -178,6 +187,21 @@ function createSendPayload(body) {
     }
     return { message: body.message, modelContext: body.modelContext };
 }
+function parseCallbackField(value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = parseSessionCallback(value);
+    if (parsed.ok)
+        return parsed.callback;
+    return Response.json({ error: parsed.message, ok: false }, { status: 400 });
+}
+function parseModeField(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === "conversation" || value === "task")
+        return value;
+    return Response.json({ error: "Expected 'mode' to be either 'conversation' or 'task'.", ok: false }, { status: 400 });
+}
 function parseMessageField(value) {
     if (value === undefined)
         return undefined;

package/dist/src/runtime/actions/keys.js

@@ -6,6 +6,8 @@ export function getRuntimeActionRequestKey(action) {
     switch (action.kind) {
         case "load-skill":
             return `runtime-action:${action.kind}:${action.callId}`;
+        case "remote-agent-call":
+            return `subagent-call:${action.remoteAgentName}:${action.callId}`;
         case "subagent-call":
             return `subagent-call:${action.subagentName}:${action.callId}`;
         case "tool-call":

package/dist/src/runtime/actions/types.d.ts

@@ -30,6 +30,23 @@ declare const runtimeSubagentCallActionRequestSchema: z.ZodObject<{
     nodeId: z.ZodString;
     subagentName: z.ZodString;
 }, z.core.$strict>;
+/**
+ * Runtime-owned remote-agent-call request surfaced by a harness and executed
+ * later by workflow-backed runtime code.
+ */
+export type RuntimeRemoteAgentCallActionRequest = z.infer<typeof runtimeRemoteAgentCallActionRequestSchema>;
+/**
+ * Zod schema for one runtime-owned remote-agent-call action request.
+ */
+export declare const runtimeRemoteAgentCallActionRequestSchema: z.ZodObject<{
+    callId: z.ZodString;
+    description: z.ZodString;
+    input: z.ZodType<import("../../shared/json.js").JsonObject, unknown, z.core.$ZodTypeInternals<import("../../shared/json.js").JsonObject, unknown>>;
+    kind: z.ZodLiteral<"remote-agent-call">;
+    name: z.ZodString;
+    nodeId: z.ZodString;
+    remoteAgentName: z.ZodString;
+}, z.core.$strict>;
 /**
  * Runtime-owned action request surfaced by a harness.
  *
@@ -51,7 +68,36 @@ declare const runtimeLoadSkillActionRequestSchema: z.ZodObject<{
  * Harness-native capabilities such as `bash` do not cross the harness boundary
  * as runtime actions. Only runtime-executed requests use this taxonomy.
  */
-export type RuntimeActionRequest = RuntimeLoadSkillActionRequest | RuntimeSubagentCallActionRequest | RuntimeToolCallActionRequest;
+export type RuntimeActionRequest = RuntimeLoadSkillActionRequest | RuntimeRemoteAgentCallActionRequest | RuntimeSubagentCallActionRequest | RuntimeToolCallActionRequest;
+/**
+ * Zod schema for one runtime action request.
+ */
+export declare const runtimeActionRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    callId: z.ZodString;
+    input: z.ZodType<import("../../shared/json.js").JsonObject, unknown, z.core.$ZodTypeInternals<import("../../shared/json.js").JsonObject, unknown>>;
+    kind: z.ZodLiteral<"load-skill">;
+}, z.core.$strict>, z.ZodObject<{
+    callId: z.ZodString;
+    description: z.ZodString;
+    input: z.ZodType<import("../../shared/json.js").JsonObject, unknown, z.core.$ZodTypeInternals<import("../../shared/json.js").JsonObject, unknown>>;
+    kind: z.ZodLiteral<"remote-agent-call">;
+    name: z.ZodString;
+    nodeId: z.ZodString;
+    remoteAgentName: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    callId: z.ZodString;
+    description: z.ZodString;
+    input: z.ZodType<import("../../shared/json.js").JsonObject, unknown, z.core.$ZodTypeInternals<import("../../shared/json.js").JsonObject, unknown>>;
+    kind: z.ZodLiteral<"subagent-call">;
+    name: z.ZodString;
+    nodeId: z.ZodString;
+    subagentName: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    callId: z.ZodString;
+    input: z.ZodType<import("../../shared/json.js").JsonObject, unknown, z.core.$ZodTypeInternals<import("../../shared/json.js").JsonObject, unknown>>;
+    kind: z.ZodLiteral<"tool-call">;
+    toolName: z.ZodString;
+}, z.core.$strict>], "kind">;
 /**
  * Runtime-owned authored tool-result projected back into a harness resume call.
  */

package/dist/src/runtime/actions/types.js

@@ -25,6 +25,20 @@ const runtimeSubagentCallActionRequestSchema = z
     subagentName: z.string(),
 })
     .strict();
+/**
+ * Zod schema for one runtime-owned remote-agent-call action request.
+ */
+export const runtimeRemoteAgentCallActionRequestSchema = z
+    .object({
+    callId: z.string(),
+    description: z.string(),
+    input: jsonObjectSchema,
+    kind: z.literal("remote-agent-call"),
+    name: z.string(),
+    nodeId: z.string(),
+    remoteAgentName: z.string(),
+})
+    .strict();
 /**
  * Zod schema for one runtime-owned load-skill action request.
  */
@@ -35,6 +49,15 @@ const runtimeLoadSkillActionRequestSchema = z
     kind: z.literal("load-skill"),
 })
     .strict();
+/**
+ * Zod schema for one runtime action request.
+ */
+export const runtimeActionRequestSchema = z.discriminatedUnion("kind", [
+    runtimeLoadSkillActionRequestSchema,
+    runtimeRemoteAgentCallActionRequestSchema,
+    runtimeSubagentCallActionRequestSchema,
+    runtimeToolCallActionRequestSchema,
+]);
 /**
  * Zod schema for one runtime-owned authored tool-result action result.
  */

package/dist/src/runtime/connections/callback-route.d.ts

@@ -29,7 +29,7 @@ import type { ResolvedChannelDefinition } from "#runtime/types.js";
  * channel. The trailing method segment (`get` or `post`) keeps each
  * `(method, urlPath)` pair distinct in the channel registry.
  */
-export declare const HTTP_CONNECTION_CALLBACK_CHANNEL_NAME_PREFIX = ".well-known/ash/v1/connections/callback";
+export declare const HTTP_CONNECTION_CALLBACK_CHANNEL_NAME_PREFIX = "ash/v1/connections/callback";
 /**
  * Returns the framework-shipped channel definitions that mount the
  * connection callback route at {@link ASH_CONNECTION_CALLBACK_ROUTE_PATTERN}.

package/dist/src/runtime/connections/callback-route.js

@@ -30,7 +30,7 @@ import { buildAuthorizationCompletePage } from "#runtime/connections/authorizati
  * channel. The trailing method segment (`get` or `post`) keeps each
  * `(method, urlPath)` pair distinct in the channel registry.
  */
-export const HTTP_CONNECTION_CALLBACK_CHANNEL_NAME_PREFIX = ".well-known/ash/v1/connections/callback";
+export const HTTP_CONNECTION_CALLBACK_CHANNEL_NAME_PREFIX = "ash/v1/connections/callback";
 /**
  * HTTP methods accepted by the connection callback route.
  *

package/dist/src/runtime/connections/mcp-client.d.ts

@@ -13,8 +13,7 @@ export declare class McpConnectionClient implements ConnectionClient {
     constructor(connection: ResolvedConnectionDefinition);
     /**
      * Connects to the MCP server, trying Streamable HTTP first and
-     * falling back to SSE if the server returns a 404 (indicating it
-     * only supports the older SSE transport).
+     * falling back to SSE for transport-compatibility failures.
      *
      * Concurrent callers share the same connection promise to avoid
      * duplicate connections.

package/dist/src/runtime/connections/mcp-client.js

@@ -2,6 +2,7 @@ import { createMCPClient } from "#compiled/@ai-sdk/mcp/index.js";
 import { contextStorage } from "#context/container.js";
 import { readCachedToken, writeCachedToken } from "#runtime/connections/authorization-tokens.js";
 import { principalKey, resolveConnectionPrincipal } from "#runtime/connections/principal.js";
+import { isObject } from "#shared/guards.js";
 /**
  * Wraps one `MCPClient` from `@ai-sdk/mcp` for a single connection.
  *
@@ -19,8 +20,7 @@ export class McpConnectionClient {
     }
     /**
      * Connects to the MCP server, trying Streamable HTTP first and
-     * falling back to SSE if the server returns a 404 (indicating it
-     * only supports the older SSE transport).
+     * falling back to SSE for transport-compatibility failures.
      *
      * Concurrent callers share the same connection promise to avoid
      * duplicate connections.
@@ -50,7 +50,10 @@ export class McpConnectionClient {
                 transport: { type: "http", url, headers },
             });
         }
-        catch {
+        catch (error) {
+            if (!isMcpHttpFallbackRetryableError(error)) {
+                throw error;
+            }
             return await createMCPClient({
                 transport: { type: "sse", url, headers },
             });
@@ -137,6 +140,69 @@ export class McpConnectionClient {
         this.#tools = undefined;
     }
 }
+/**
+ * Decides whether an error thrown while creating a streamable HTTP MCP
+ * client should trigger a fallback attempt against the legacy SSE
+ * transport.
+ *
+ * Per the MCP backwards-compatibility rules, clients should fall back
+ * to SSE when the streamable HTTP probe returns `400 Bad Request`,
+ * `404 Not Found`, or `405 Method Not Allowed`. All other failures
+ * (auth errors, network errors, server errors) should propagate so the
+ * caller sees the real problem instead of a misleading SSE failure.
+ *
+ * See: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#backwards-compatibility
+ */
+function isMcpHttpFallbackRetryableError(error) {
+    const status = readHttpStatus(error);
+    return status === 400 || status === 404 || status === 405;
+}
+function readHttpStatus(error) {
+    for (const candidate of walkErrorChain(error)) {
+        if (!isObject(candidate)) {
+            continue;
+        }
+        const status = readStatusField(candidate);
+        if (status !== undefined) {
+            return status;
+        }
+        const response = candidate.response;
+        if (isObject(response)) {
+            const responseStatus = readStatusField(response);
+            if (responseStatus !== undefined) {
+                return responseStatus;
+            }
+        }
+        if (typeof candidate.message === "string") {
+            const match = /\bHTTP\s+(\d{3})\b/u.exec(candidate.message);
+            if (match?.[1] !== undefined) {
+                return Number(match[1]);
+            }
+        }
+    }
+    return undefined;
+}
+function readStatusField(value) {
+    if (typeof value.status === "number") {
+        return value.status;
+    }
+    if (typeof value.statusCode === "number") {
+        return value.statusCode;
+    }
+    return undefined;
+}
+function* walkErrorChain(error) {
+    let current = error;
+    const seen = new Set();
+    while (current !== undefined && current !== null && !seen.has(current)) {
+        seen.add(current);
+        yield current;
+        if (!isObject(current) || !("cause" in current)) {
+            return;
+        }
+        current = current.cause;
+    }
+}
 /**
  * Returns `true` when a tool name passes the configured filter.
  */

package/dist/src/runtime/framework-channels/index.js

@@ -1,6 +1,7 @@
 import { none, vercelOidc } from "#public/channels/auth.js";
 import { ashChannel } from "#public/channels/ash.js";
 import { getConnectionCallbackChannelDefinitions, getConnectionCallbackChannelNames, } from "#runtime/connections/callback-route.js";
+import { getSessionCallbackChannelDefinitions, getSessionCallbackChannelNames, } from "#runtime/session-callback-route.js";
 const ASH_CHANNEL_NAME = "ash";
 export function getFrameworkChannelDefinitions() {
     const auth = resolveFrameworkAshAuth();
@@ -19,11 +20,15 @@ export function getFrameworkChannelDefinitions() {
             sourceKind: "module",
         });
     }
-    result.push(...getConnectionCallbackChannelDefinitions());
+    result.push(...getConnectionCallbackChannelDefinitions(), ...getSessionCallbackChannelDefinitions());
     return result;
 }
 export function getAllFrameworkChannelNames() {
-    return new Set([ASH_CHANNEL_NAME, ...getConnectionCallbackChannelNames()]);
+    return new Set([
+        ASH_CHANNEL_NAME,
+        ...getConnectionCallbackChannelNames(),
+        ...getSessionCallbackChannelNames(),
+    ]);
 }
 function resolveFrameworkAshAuth() {
     if (process.env.VERCEL) {