experimental-ash 0.25.1 → 0.25.2

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) {

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

@@ -0,0 +1,6 @@
+import type { RouteContext } from "#public/definitions/channel.js";
+import type { ResolvedChannelDefinition } from "#runtime/types.js";
+export declare const HTTP_SESSION_CALLBACK_CHANNEL_NAME_PREFIX = "ash/v1/callback";
+export declare function getSessionCallbackChannelDefinitions(): readonly ResolvedChannelDefinition[];
+export declare function getSessionCallbackChannelNames(): ReadonlySet<string>;
+export declare function handleSessionCallbackRequest(request: Request, ctx: RouteContext): Promise<Response>;

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

@@ -0,0 +1,87 @@
+import { resumeHook } from "#compiled/@workflow/core/runtime.js";
+import { ASH_CALLBACK_ROUTE_PATTERN } from "#protocol/routes.js";
+export const HTTP_SESSION_CALLBACK_CHANNEL_NAME_PREFIX = "ash/v1/callback";
+const HANDLED_METHODS = ["POST"];
+export function getSessionCallbackChannelDefinitions() {
+    return HANDLED_METHODS.map((method) => buildCallbackChannelDefinition(method));
+}
+export function getSessionCallbackChannelNames() {
+    return new Set(HANDLED_METHODS.map(channelNameForMethod));
+}
+function buildCallbackChannelDefinition(method) {
+    const name = channelNameForMethod(method);
+    return {
+        name,
+        method,
+        urlPath: ASH_CALLBACK_ROUTE_PATTERN,
+        fetch: handleSessionCallbackRequest,
+        logicalPath: `framework://channels/${name}`,
+        sourceId: `ash:framework:session-callback-${method.toLowerCase()}`,
+        sourceKind: "module",
+    };
+}
+function channelNameForMethod(method) {
+    return `${HTTP_SESSION_CALLBACK_CHANNEL_NAME_PREFIX}/${method.toLowerCase()}`;
+}
+export async function handleSessionCallbackRequest(request, ctx) {
+    const token = ctx.params.token;
+    if (typeof token !== "string" || token.length === 0) {
+        return Response.json({ error: "Missing callback token.", ok: false }, { status: 400 });
+    }
+    let body;
+    try {
+        body = await request.json();
+    }
+    catch {
+        return Response.json({ error: "Invalid JSON body.", ok: false }, { status: 400 });
+    }
+    const result = projectSessionCallbackResult(body);
+    if (result instanceof Response) {
+        return result;
+    }
+    try {
+        await resumeHook(token, {
+            kind: "runtime-action-result",
+            results: [result],
+        });
+    }
+    catch {
+        return Response.json({ error: "Session callback not pending.", ok: false }, { status: 404 });
+    }
+    return Response.json({ ok: true }, { status: 202 });
+}
+function projectSessionCallbackResult(value) {
+    if (value === null || typeof value !== "object") {
+        return Response.json({ error: "Expected a JSON object.", ok: false }, { status: 400 });
+    }
+    const payload = value;
+    if (typeof payload.callId !== "string" || payload.callId.length === 0) {
+        return Response.json({ error: "Missing callback callId.", ok: false }, { status: 400 });
+    }
+    if (typeof payload.subagentName !== "string" || payload.subagentName.length === 0) {
+        return Response.json({ error: "Missing callback subagentName.", ok: false }, { status: 400 });
+    }
+    if (payload.kind === "session.completed") {
+        return {
+            callId: payload.callId,
+            kind: "subagent-result",
+            output: typeof payload.output === "string" ? payload.output : "",
+            subagentName: payload.subagentName,
+        };
+    }
+    if (payload.kind === "session.failed") {
+        return {
+            callId: payload.callId,
+            isError: true,
+            kind: "subagent-result",
+            output: payload.error === undefined
+                ? {
+                    code: "REMOTE_AGENT_FAILED",
+                    message: "Remote agent failed.",
+                }
+                : payload.error,
+            subagentName: payload.subagentName,
+        };
+    }
+    return Response.json({ error: "Unsupported callback kind.", ok: false }, { status: 400 });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-ash",
-  "version": "0.25.1",
+  "version": "0.25.2",
   "bin": {
     "ash": "./bin/ash.js",
     "experimental-ash": "./bin/ash.js"