experimental-ash 0.25.1 → 0.26.0

package/dist/src/public/channels/discord/verify.js

@@ -0,0 +1,72 @@
+/**
+ * Discord inbound-interaction verification.
+ *
+ * Discord signs interaction webhooks with Ed25519. The signed payload is
+ * the `X-Signature-Timestamp` header concatenated with the exact raw
+ * request body string.
+ */
+import { createPublicKey, verify } from "node:crypto";
+import { createLogger } from "#internal/logging.js";
+const log = createLogger("discord.verify");
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+/** Resolves a Discord public key, falling back to `DISCORD_PUBLIC_KEY`. */
+export async function resolveDiscordPublicKey(publicKey) {
+    const source = publicKey ?? process.env.DISCORD_PUBLIC_KEY;
+    if (!source)
+        throw new Error("DISCORD_PUBLIC_KEY is required.");
+    return typeof source === "function" ? await source() : source;
+}
+/**
+ * Verifies an inbound Discord interaction request and returns the raw body.
+ *
+ * Throws when no public key/verifier is configured, required signature
+ * headers are missing, timestamp checks fail, or the signature check fails.
+ */
+export async function verifyDiscordRequest(request, options) {
+    const body = await request.text();
+    if (options.webhookVerifier !== undefined) {
+        const result = await options.webhookVerifier(request, body);
+        if (!result) {
+            throw new Error("discordChannel: inbound webhook verifier rejected the request.");
+        }
+        return typeof result === "string" ? result : body;
+    }
+    const publicKey = await resolveDiscordPublicKey(options.publicKey);
+    const signature = request.headers.get("x-signature-ed25519") ?? "";
+    const timestamp = request.headers.get("x-signature-timestamp") ?? "";
+    if (!signature || !timestamp) {
+        throw new Error("discordChannel: inbound request missing Discord signature headers.");
+    }
+    const timestampSeconds = Number(timestamp);
+    if (!Number.isFinite(timestampSeconds)) {
+        throw new Error("discordChannel: inbound request has malformed timestamp.");
+    }
+    const maxSkew = options.maxSkewSeconds ?? 60 * 5;
+    const now = Math.floor(Date.now() / 1000);
+    if (Math.abs(now - timestampSeconds) > maxSkew) {
+        throw new Error("discordChannel: inbound request timestamp outside allowed skew.");
+    }
+    if (!verifyDiscordSignature({ body, publicKey, signature, timestamp })) {
+        throw new Error("discordChannel: inbound request signature mismatch.");
+    }
+    return body;
+}
+/** Verifies one Discord Ed25519 signature. */
+export function verifyDiscordSignature(input) {
+    try {
+        const publicKeyBytes = Buffer.from(input.publicKey, "hex");
+        const signatureBytes = Buffer.from(input.signature, "hex");
+        if (publicKeyBytes.length !== 32 || signatureBytes.length !== 64)
+            return false;
+        const key = createPublicKey({
+            format: "der",
+            key: Buffer.concat([ED25519_SPKI_PREFIX, publicKeyBytes]),
+            type: "spki",
+        });
+        return verify(null, Buffer.from(`${input.timestamp}${input.body}`), key, signatureBytes);
+    }
+    catch (error) {
+        log.debug("Discord signature verification threw", { error });
+        return false;
+    }
+}

package/dist/src/public/channels/discord/verifyInbound.d.ts

@@ -0,0 +1,6 @@
+import type { DiscordChannelCredentials } from "#public/channels/discord/discordChannel.js";
+/**
+ * Verifies an inbound Discord request and returns its raw body, or
+ * `null` when verification fails.
+ */
+export declare function verifyDiscordInbound(req: Request, credentials: DiscordChannelCredentials | undefined): Promise<string | null>;

package/dist/src/public/channels/discord/verifyInbound.js

@@ -0,0 +1,19 @@
+import { createLogger } from "#internal/logging.js";
+import { verifyDiscordRequest } from "#public/channels/discord/verify.js";
+const log = createLogger("discord.channel");
+/**
+ * Verifies an inbound Discord request and returns its raw body, or
+ * `null` when verification fails.
+ */
+export async function verifyDiscordInbound(req, credentials) {
+    try {
+        return await verifyDiscordRequest(req, {
+            publicKey: credentials?.webhookVerifier ? undefined : credentials?.publicKey,
+            webhookVerifier: credentials?.webhookVerifier,
+        });
+    }
+    catch (error) {
+        log.warn("discord inbound verification failed", { error });
+        return null;
+    }
+}

package/dist/src/public/channels/slack/constants.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Default route that `slackChannel({})` mounts on. The scaffold's slack
+ * setup (`vercel connect attach --trigger-path ...`) must point at this
+ * exact path or Connect-forwarded Slack events 404 against the Ash
+ * framework router.
+ */
+export declare const SLACK_CHANNEL_DEFAULT_ROUTE = "/ash/v1/slack";

package/dist/src/public/channels/slack/constants.js

@@ -0,0 +1,7 @@
+/**
+ * Default route that `slackChannel({})` mounts on. The scaffold's slack
+ * setup (`vercel connect attach --trigger-path ...`) must point at this
+ * exact path or Connect-forwarded Slack events 404 against the Ash
+ * framework router.
+ */
+export const SLACK_CHANNEL_DEFAULT_ROUTE = "/ash/v1/slack";

package/dist/src/public/channels/slack/slackChannel.js

@@ -3,6 +3,7 @@ import { buildSlackBinding, slackContinuationToken, } from "#public/channels/sla
 import { buildSlackTurnMessage, collectInboundFileParts, createSlackFetchFile, } from "#public/channels/slack/attachments.js";
 import { defaultEvents, defaultInputRequestedHandler, defaultOnAppMention, defaultOnDirectMessage, } from "#public/channels/slack/defaults.js";
 import { parseAppMentionEvent, parseDirectMessageEvent, prependSlackContext, } from "#public/channels/slack/inbound.js";
+import { SLACK_CHANNEL_DEFAULT_ROUTE } from "#public/channels/slack/constants.js";
 import { handleInteractionPost } from "#public/channels/slack/interactions.js";
 import { mergeUploadPolicy, } from "#public/channels/upload-policy.js";
 import { verifySlackRequest } from "#public/channels/slack/verify.js";
@@ -58,7 +59,7 @@ export function slackChannel(config = {}) {
             return rebuildSlackContext(state, session, config.credentials);
         },
         routes: [
-            POST(config.route ?? "/ash/v1/slack", async (req, { send, waitUntil }) => {
+            POST(config.route ?? SLACK_CHANNEL_DEFAULT_ROUTE, async (req, { send, waitUntil }) => {
                 const body = await verifyInbound(req, config.credentials);
                 if (body === null)
                     return new Response("unauthorized", { status: 401 });

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.26.0",
   "bin": {
     "ash": "./bin/ash.js",
     "experimental-ash": "./bin/ash.js"
@@ -146,6 +146,11 @@
       "import": "./dist/src/public/channels/slack/index.js",
       "default": "./dist/src/public/channels/slack/index.js"
     },
+    "./channels/discord": {
+      "types": "./dist/src/public/channels/discord/index.d.ts",
+      "import": "./dist/src/public/channels/discord/index.js",
+      "default": "./dist/src/public/channels/discord/index.js"
+    },
     "./channels/twilio": {
       "types": "./dist/src/public/channels/twilio/index.d.ts",
       "import": "./dist/src/public/channels/twilio/index.js",
@@ -192,7 +197,8 @@
     "react-test-renderer": "19.2.6",
     "turndown": "7.2.4",
     "zod": "4.4.3",
-    "zod-validation-error": "5.0.0"
+    "zod-validation-error": "5.0.0",
+    "@vercel/ash-scaffold": "0.0.0"
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.0.0",
@@ -220,7 +226,7 @@
   },
   "scripts": {
     "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
-    "build": "pnpm run build:js && node ./scripts/copy-static-assets.mjs",
+    "build": "pnpm run build:js && node ./scripts/copy-docs.mjs && node ./scripts/stamp-version-tokens.mjs",
     "build:compiled": "node ./scripts/vendor-compiled.mjs",
     "build:js": "pnpm run build:compiled && pnpm run clean && tsgo -p tsconfig.build.json && node ./scripts/copy-compiled-assets.mjs && node ./scripts/bundle-js.mjs",
     "build:types": "pnpm run build:compiled && tsgo -p tsconfig.build.json --emitDeclarationOnly",