experimental-ash 0.22.0 → 0.22.2

package/dist/src/internal/nitro/host/build-application.js

@@ -1,10 +1,11 @@
 import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { build as buildNitro, copyPublicAssets, prepare, prerender } from "nitro/builder";
 import { resolvePackageRoot } from "#internal/application/package.js";
 import { prepareAshVersionedCacheDirectory, writeAshVersionedCacheMetadata, } from "#internal/application/cache-metadata.js";
 import { resolveNitroSurfaceOutputDirectory } from "#internal/application/paths.js";
 import { WorkflowBundleBuilder } from "#internal/workflow-bundle/builder.js";
+import { normalizeAshVercelFunctionOutput } from "#internal/workflow-bundle/vercel-workflow-output.js";
 import { createApplicationNitro } from "#internal/nitro/host/create-application-nitro.js";
 import { emitVercelAgentSummary } from "#internal/nitro/host/build-vercel-agent-summary.js";
 import { prepareApplicationHost } from "#internal/nitro/host/prepare-application-host.js";
@@ -12,6 +13,67 @@ import { runVercelBuildPrewarm } from "#internal/nitro/host/vercel-build-prewarm
 function trimTrailingSlash(path) {
     return path.replace(/[\\/]+$/, "");
 }
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeEntrypoint(rootDir, entrypoint) {
+    if (typeof entrypoint !== "string" || entrypoint.trim().length === 0) {
+        return null;
+    }
+    return resolve(rootDir, entrypoint);
+}
+function resolveNextAshServicePrefix(input) {
+    if (!isRecord(input.config) || !isRecord(input.config.experimentalServices)) {
+        return undefined;
+    }
+    let hasNextService = false;
+    let servicePrefix;
+    for (const service of Object.values(input.config.experimentalServices)) {
+        if (!isRecord(service)) {
+            continue;
+        }
+        if (service.framework === "nextjs") {
+            hasNextService = true;
+            continue;
+        }
+        if (service.framework !== "ash") {
+            continue;
+        }
+        const ashEntrypoint = normalizeEntrypoint(input.configRoot, service.entrypoint);
+        const routePrefix = typeof service.routePrefix === "string" ? service.routePrefix.trim() : "";
+        if (ashEntrypoint === input.appRoot && routePrefix.length > 0 && routePrefix !== "/") {
+            servicePrefix = routePrefix;
+        }
+    }
+    return hasNextService ? servicePrefix : undefined;
+}
+async function resolveNextAshServicePrefixForVercelFunctionOutput(appRoot) {
+    let currentDir = appRoot;
+    while (true) {
+        try {
+            const configPath = join(currentDir, "vercel.json");
+            const config = JSON.parse(await readFile(configPath, "utf8"));
+            const servicePrefix = resolveNextAshServicePrefix({
+                appRoot,
+                configRoot: currentDir,
+                config,
+            });
+            if (servicePrefix !== undefined) {
+                return servicePrefix;
+            }
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+                throw error;
+            }
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir) {
+            return undefined;
+        }
+        currentDir = parentDir;
+    }
+}
 async function readVercelServerRuntime(outputDir) {
     try {
         const config = JSON.parse(await readFile(join(outputDir, "functions", "__server.func", ".vc-config.json"), "utf8"));
@@ -99,6 +161,10 @@ export async function buildApplication(rootDir) {
             outputDir: outputDirectory,
             workflowBuildDir: preparedHost.workflowBuildDir,
         });
+        const servicePrefix = await resolveNextAshServicePrefixForVercelFunctionOutput(preparedHost.appRoot);
+        if (servicePrefix !== undefined) {
+            await normalizeAshVercelFunctionOutput(outputDirectory, { servicePrefix });
+        }
         await emitVercelAgentSummary({
             manifest: preparedHost.compileResult.manifest,
             appRoot: preparedHost.appRoot,

package/dist/src/internal/workflow-bundle/ash-service-route-output.d.ts

@@ -0,0 +1,4 @@
+export declare const ASH_SHARED_SERVER_FUNCTION_PATH = "ash/__server.func";
+export declare function isAshVercelFunctionPath(path: string): boolean;
+export declare function normalizeAshVercelRoutes(routes: readonly unknown[], servicePrefix: string | undefined): unknown[];
+export declare function applyAshServiceRoutePrefixWrapper(functionPath: string, servicePrefix: string): Promise<void>;

package/dist/src/internal/workflow-bundle/ash-service-route-output.js

@@ -0,0 +1,134 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export const ASH_SHARED_SERVER_FUNCTION_PATH = "ash/__server.func";
+const ASH_SHARED_SERVER_ROUTE_DESTINATION = "/ash/__server";
+const ASH_SERVICE_ROUTE_PREFIX_WRAPPER = "index.__ash_service_route_prefix.mjs";
+const ASH_VERCEL_FUNCTION_PREFIXES = ["ash/", ".well-known/workflow/"];
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function isAshVercelFunctionPath(path) {
+    return ASH_VERCEL_FUNCTION_PREFIXES.some((prefix) => path.startsWith(prefix));
+}
+export function normalizeAshVercelRoutes(routes, servicePrefix) {
+    return routes
+        .filter(isAshVercelRoute)
+        .map((route) => normalizeAshVercelRoute(route, servicePrefix));
+}
+function isAshVercelRoute(route) {
+    if (!isRecord(route)) {
+        return true;
+    }
+    if ("handle" in route) {
+        return true;
+    }
+    const src = typeof route.src === "string" ? route.src : "";
+    const dest = typeof route.dest === "string" ? route.dest : "";
+    return isAshVercelRoutePath(src) || isAshVercelRoutePath(dest);
+}
+function isAshVercelRoutePath(path) {
+    return path.includes("/ash/v1") || path.includes("/.well-known/workflow/");
+}
+function isAshProtocolRoutePath(path) {
+    return path.includes("/ash/v1");
+}
+function normalizeAshVercelRoute(route, servicePrefix) {
+    if (!isRecord(route) || "handle" in route || typeof route.src !== "string") {
+        return route;
+    }
+    const shouldUseSharedServerFunction = isAshProtocolRoutePath(route.src) ||
+        (typeof route.dest === "string" && isAshProtocolRoutePath(route.dest));
+    const nextRoute = {
+        ...route,
+        src: prefixAshVercelRoutePath(route.src, servicePrefix),
+    };
+    if (shouldUseSharedServerFunction) {
+        nextRoute.dest = ASH_SHARED_SERVER_ROUTE_DESTINATION;
+    }
+    return nextRoute;
+}
+function prefixAshVercelRoutePath(path, servicePrefix) {
+    if (servicePrefix === undefined ||
+        servicePrefix === "/" ||
+        !isAshVercelRoutePath(path) ||
+        path.includes(servicePrefix)) {
+        return path;
+    }
+    const normalizedPrefix = servicePrefix.endsWith("/") ? servicePrefix.slice(0, -1) : servicePrefix;
+    const escapedPrefix = normalizedPrefix.replaceAll("/", "\\/");
+    if (path.includes(escapedPrefix)) {
+        return path;
+    }
+    if (path.startsWith("^(?:/")) {
+        return `^(?:${normalizedPrefix}${path.slice(4)}`;
+    }
+    if (path.startsWith("^/")) {
+        return `^${normalizedPrefix}${path.slice(1)}`;
+    }
+    if (path.startsWith("/")) {
+        return `${normalizedPrefix}${path}`;
+    }
+    return path;
+}
+export async function applyAshServiceRoutePrefixWrapper(functionPath, servicePrefix) {
+    const configPath = join(functionPath, ".vc-config.json");
+    const wrapperPath = join(functionPath, ASH_SERVICE_ROUTE_PREFIX_WRAPPER);
+    const rawConfig = JSON.parse(await readFile(configPath, "utf8"));
+    const config = isRecord(rawConfig) ? rawConfig : {};
+    await writeFile(wrapperPath, createAshServiceRoutePrefixWrapper(servicePrefix));
+    await writeFile(configPath, `${JSON.stringify({
+        ...config,
+        handler: ASH_SERVICE_ROUTE_PREFIX_WRAPPER,
+    }, null, 2)}\n`);
+}
+function createAshServiceRoutePrefixWrapper(servicePrefix) {
+    return `
+import { Server } from "node:http";
+
+const SERVICE_PREFIX = ${JSON.stringify(normalizeServiceRoutePrefix(servicePrefix))};
+const PATCH_SYMBOL = Symbol.for("ash.service.route-prefix-strip.patch");
+
+function stripServiceRoutePrefix(requestUrl) {
+  if (typeof requestUrl !== "string" || requestUrl === "*") {
+    return requestUrl;
+  }
+
+  const queryIndex = requestUrl.indexOf("?");
+  const rawPath = queryIndex === -1 ? requestUrl : requestUrl.slice(0, queryIndex);
+  const query = queryIndex === -1 ? "" : requestUrl.slice(queryIndex);
+  const path = rawPath.startsWith("/") ? rawPath : \`/\${rawPath}\`;
+
+  if (path === SERVICE_PREFIX) {
+    return \`/\${query}\`;
+  }
+
+  if (path.startsWith(\`\${SERVICE_PREFIX}/\`)) {
+    return path.slice(SERVICE_PREFIX.length) + query;
+  }
+
+  return path + query;
+}
+
+if (!globalThis[PATCH_SYMBOL]) {
+  globalThis[PATCH_SYMBOL] = true;
+  const originalEmit = Server.prototype.emit;
+  Server.prototype.emit = function patchedEmit(event, request, ...args) {
+    if (event === "request" && request && typeof request.url === "string") {
+      request.url = stripServiceRoutePrefix(request.url);
+    }
+
+    return originalEmit.call(this, event, request, ...args);
+  };
+}
+
+const originalModule = await import("./index.mjs");
+const entrypoint = originalModule?.default ?? originalModule;
+
+export default entrypoint;
+`.trimStart();
+}
+function normalizeServiceRoutePrefix(servicePrefix) {
+    const prefixed = servicePrefix.startsWith("/") ? servicePrefix : `/${servicePrefix}`;
+    const normalized = prefixed.replace(/\/+$/, "");
+    return normalized.length === 0 ? "/" : normalized;
+}

package/dist/src/internal/workflow-bundle/vercel-workflow-output.d.ts

@@ -26,6 +26,23 @@ export declare function copyNitroFunctionDirectory(input: {
     sourcePath: string;
     targetPath: string;
 }): Promise<void>;
+/**
+ * Keeps only Ash-owned Vercel function output and rewrites Ash route function
+ * symlinks to a shared Ash-owned server function.
+ *
+ * Nitro emits generic app routes such as `index.func -> ./__server.func` for
+ * Ash's standalone landing page. In a multi-service Next.js deployment those
+ * root aliases collide with Next's own functions. The Next integration only
+ * proxies Ash's `/ash/v1/**` transport routes, so Vercel output should expose
+ * those route functions and workflow trigger functions, not Ash's root page.
+ *
+ * Nitro also dedupes every route function through `__server.func`. Preserve
+ * that model by copying the shared target once into the Ash-owned tree and
+ * repointing Ash route aliases at it before pruning the root target.
+ */
+export declare function normalizeAshVercelFunctionOutput(outputDir: string, options?: {
+    readonly servicePrefix?: string;
+}): Promise<void>;
 /**
  * Bundles one package-owned workflow handler into a standalone Vercel function
  * directory without inheriting Nitro's hosted server chunks.

package/dist/src/internal/workflow-bundle/vercel-workflow-output.js

@@ -1,6 +1,7 @@
-import { cp, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { cp, mkdir, readdir, readFile, realpath, rename, rm, symlink, writeFile, } from "node:fs/promises";
 import { basename, dirname, extname, join, relative } from "node:path";
 import { buildWithNitroRolldown, getSingleRolldownChunk, } from "#internal/bundler/nitro-rolldown.js";
+import { applyAshServiceRoutePrefixWrapper, ASH_SHARED_SERVER_FUNCTION_PATH, isAshVercelFunctionPath, normalizeAshVercelRoutes, } from "#internal/workflow-bundle/ash-service-route-output.js";
 // just-bash exposes native optional codecs for xz/zstd support. Those packages
 // are feature-gated at runtime and should stay external so workflow step
 // bundles do not try to inline platform-specific `.node` artifacts.
@@ -63,6 +64,145 @@ export async function copyNitroFunctionDirectory(input) {
         recursive: true,
     });
 }
+/**
+ * Keeps only Ash-owned Vercel function output and rewrites Ash route function
+ * symlinks to a shared Ash-owned server function.
+ *
+ * Nitro emits generic app routes such as `index.func -> ./__server.func` for
+ * Ash's standalone landing page. In a multi-service Next.js deployment those
+ * root aliases collide with Next's own functions. The Next integration only
+ * proxies Ash's `/ash/v1/**` transport routes, so Vercel output should expose
+ * those route functions and workflow trigger functions, not Ash's root page.
+ *
+ * Nitro also dedupes every route function through `__server.func`. Preserve
+ * that model by copying the shared target once into the Ash-owned tree and
+ * repointing Ash route aliases at it before pruning the root target.
+ */
+export async function normalizeAshVercelFunctionOutput(outputDir, options = {}) {
+    const functionsDir = join(outputDir, "functions");
+    const sharedFunctionPath = await prepareSharedAshServerFunction(functionsDir);
+    if (sharedFunctionPath !== null) {
+        if (options.servicePrefix !== undefined) {
+            await applyAshServiceRoutePrefixWrapper(sharedFunctionPath, options.servicePrefix);
+        }
+        await repointAshFunctionSymlinksInDirectory(functionsDir, sharedFunctionPath);
+    }
+    await pruneNonAshFunctionEntries(functionsDir, functionsDir);
+    await pruneNonAshVercelRoutes(outputDir, options.servicePrefix);
+}
+async function prepareSharedAshServerFunction(functionsDir) {
+    const rootServerFunctionPath = join(functionsDir, "__server.func");
+    const sharedFunctionPath = join(functionsDir, ASH_SHARED_SERVER_FUNCTION_PATH);
+    let sourcePath;
+    try {
+        sourcePath = await realpath(rootServerFunctionPath);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+    const stagingPath = `${sharedFunctionPath}.ash-staging`;
+    await mkdir(dirname(sharedFunctionPath), {
+        recursive: true,
+    });
+    await rm(stagingPath, {
+        force: true,
+        recursive: true,
+    });
+    await cp(sourcePath, stagingPath, {
+        dereference: true,
+        recursive: true,
+    });
+    await rm(sharedFunctionPath, {
+        force: true,
+        recursive: true,
+    });
+    await rename(stagingPath, sharedFunctionPath);
+    return sharedFunctionPath;
+}
+async function repointAshFunctionSymlinksInDirectory(directoryPath, sharedFunctionPath, functionsDir = directoryPath) {
+    let entries;
+    try {
+        entries = await readdir(directoryPath, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return;
+        }
+        throw error;
+    }
+    await Promise.all(entries.map(async (entry) => {
+        const entryPath = join(directoryPath, entry.name);
+        const relativeFunctionPath = normalizeVercelOutputPath(relative(functionsDir, entryPath));
+        if (entry.isSymbolicLink()) {
+            if (entry.name.endsWith(".func") && isAshVercelFunctionPath(relativeFunctionPath)) {
+                await repointFunctionSymlink(entryPath, sharedFunctionPath);
+            }
+            return;
+        }
+        if (entry.isDirectory() && !entry.name.endsWith(".func")) {
+            await repointAshFunctionSymlinksInDirectory(entryPath, sharedFunctionPath, functionsDir);
+        }
+    }));
+}
+async function repointFunctionSymlink(functionPath, sharedFunctionPath) {
+    await rm(functionPath, {
+        force: true,
+        recursive: true,
+    });
+    await symlink(normalizeVercelOutputPath(relative(dirname(functionPath), sharedFunctionPath)), functionPath, "dir");
+}
+async function pruneNonAshFunctionEntries(functionsDir, directoryPath) {
+    let entries;
+    try {
+        entries = await readdir(directoryPath, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return;
+        }
+        throw error;
+    }
+    await Promise.all(entries.map(async (entry) => {
+        const entryPath = join(directoryPath, entry.name);
+        const relativeFunctionPath = normalizeVercelOutputPath(relative(functionsDir, entryPath));
+        if (entry.name.endsWith(".func")) {
+            if (!isAshVercelFunctionPath(relativeFunctionPath)) {
+                await rm(entryPath, {
+                    force: true,
+                    recursive: true,
+                });
+            }
+            return;
+        }
+        if (entry.isDirectory()) {
+            await pruneNonAshFunctionEntries(functionsDir, entryPath);
+        }
+    }));
+}
+async function pruneNonAshVercelRoutes(outputDir, servicePrefix) {
+    const configPath = join(outputDir, "config.json");
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(configPath, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return;
+        }
+        throw error;
+    }
+    if (!isRecord(parsed) || !Array.isArray(parsed.routes)) {
+        return;
+    }
+    parsed.routes = normalizeAshVercelRoutes(parsed.routes, servicePrefix);
+    await writeFile(configPath, `${JSON.stringify(parsed, null, 2)}\n`);
+}
+function normalizeVercelOutputPath(path) {
+    return path.replaceAll("\\", "/");
+}
 /**
  * Bundles one package-owned workflow handler into a standalone Vercel function
  * directory without inheriting Nitro's hosted server chunks.

package/dist/src/public/definitions/connections/mcp.js

@@ -1,4 +1,5 @@
 import { normalizeAuthorizationSpec } from "#runtime/connections/validate-authorization.js";
+import { stampDefinitionKey } from "#public/tool-result-narrowing.js";
 /**
  * Defines an MCP client connection.
  *
@@ -14,5 +15,6 @@ export function defineMcpClientConnection(definition) {
     if (definition.auth !== undefined) {
         definition.auth = normalizeAuthorizationSpec(definition.auth, "defineMcpClientConnection:");
     }
+    stampDefinitionKey(definition, `connection:${definition.url}`);
     return definition;
 }

package/dist/src/public/definitions/tool.js

@@ -1,4 +1,6 @@
+import { stampDefinitionKey } from "#public/tool-result-narrowing.js";
 export function defineTool(definition) {
+    stampDefinitionKey(definition, `tool:${definition.description}`);
     return definition;
 }
 /**

package/dist/src/public/next/index.js

@@ -83,10 +83,15 @@ async function resolveExistingRewrites(rewrites) {
 }
 function mergeRewriteRules(existing, ashRules) {
     if (existing === undefined) {
-        return ashRules;
+        return {
+            beforeFiles: ashRules,
+        };
     }
     if (!isRewriteSections(existing)) {
-        return [...ashRules, ...existing];
+        return {
+            afterFiles: existing,
+            beforeFiles: ashRules,
+        };
     }
     return {
         ...existing,

package/dist/src/public/sandbox/backends/vercel.d.ts

@@ -8,6 +8,13 @@ import type { VercelSandboxBootstrapUseOptions, VercelSandboxCreateOptions, Verc
  * (template at prewarm, session at first-time create). On resume
  * (`Sandbox.get`), no create happens, so opts are not re-applied.
  *
+ * `opts.source`, if supplied, is used only on the template create —
+ * the author's snapshot, git revision, or tarball becomes the base
+ * layer of the template. Bootstrap, seed files, and framework setup
+ * still run on top, and every session derives from the resulting
+ * Ash-owned snapshot. `source` is stripped from session creates so the
+ * framework's snapshot always wins.
+ *
  * `bootstrap({ use })` applies its options to the template via
  * `sandbox.update(...)`; those settings persist into the snapshot.
  * `onSession({ use })` applies its options to the live session via the

package/dist/src/public/sandbox/backends/vercel.js

@@ -7,6 +7,13 @@ import { createVercelSandboxBackend } from "#execution/sandbox/bindings/vercel.j
  * (template at prewarm, session at first-time create). On resume
  * (`Sandbox.get`), no create happens, so opts are not re-applied.
  *
+ * `opts.source`, if supplied, is used only on the template create —
+ * the author's snapshot, git revision, or tarball becomes the base
+ * layer of the template. Bootstrap, seed files, and framework setup
+ * still run on top, and every session derives from the resulting
+ * Ash-owned snapshot. `source` is stripped from session creates so the
+ * framework's snapshot always wins.
+ *
  * `bootstrap({ use })` applies its options to the template via
  * `sandbox.update(...)`; those settings persist into the snapshot.
  * `onSession({ use })` applies its options to the live session via the

package/dist/src/public/sandbox/vercel-sandbox.d.ts

@@ -6,11 +6,21 @@ import type { Sandbox as SdkSandbox, SandboxUpdateParams } from "#compiled/@verc
  * session-create). Skipped on resume (`Sandbox.get`) since no create
  * happens there.
  *
- * Framework-injected fields (`name`, `persistent`, `source`, `signal`)
- * are excluded — the framework owns those and overrides any author-
- * supplied values.
+ * Framework-injected fields (`name`, `persistent`, `signal`) are
+ * excluded — the framework owns those and overrides any author-supplied
+ * values.
+ *
+ * `source` is honored only on the template create at prewarm time, so
+ * an author-supplied snapshot, git revision, or tarball becomes the
+ * base layer for the template. Bootstrap, seed files, and framework
+ * setup (workspace dir, ripgrep) all run on top, and the resulting
+ * framework-owned snapshot is what every later session derives from —
+ * so `source` is stripped from the session-create path. Ash does not
+ * detect external snapshot changes; to pick up a rebuilt external
+ * snapshot, force a template rebuild (e.g. by changing the sandbox
+ * definition so its template key changes).
  */
-export type VercelSandboxCreateOptions = Omit<NonNullable<Parameters<typeof SdkSandbox.create>[0]>, "name" | "persistent" | "source" | "signal">;
+export type VercelSandboxCreateOptions = Omit<NonNullable<Parameters<typeof SdkSandbox.create>[0]>, "name" | "persistent" | "signal">;
 /**
  * Options accepted by the Vercel backend's `bootstrap({ use })` hook.
  * Aliases the Vercel SDK's `SandboxUpdateParams` because bootstrap

package/dist/src/public/tool-result-narrowing.d.ts

@@ -39,14 +39,17 @@ export type DefinitionSourceEntry = {
     readonly name: string;
 };
 /**
- * Stamps the path-derived runtime name onto an authored definition
- * object as a non-enumerable symbol property.
- *
- * Called by the resolution pipeline (`resolveToolDefinition`,
- * `resolveConnectionDefinition`) so {@link toolResultFrom} can read
- * the name back without a separate lookup structure.
+ * Stamps a stable content-derived key on the definition so it can be
+ * identified across module instances. Called by `defineTool` and
+ * `defineMcpClientConnection` at definition time.
+ */
+export declare function stampDefinitionKey(definition: object, key: string): void;
+/**
+ * Registers a definition key → source entry mapping in the global
+ * registry. Called by the resolution pipeline after loading the
+ * authored module.
  */
-export declare function stampDefinitionSource(definition: object, entry: DefinitionSourceEntry): void;
+export declare function registerDefinitionSource(key: string, entry: DefinitionSourceEntry): void;
 /**
  * Overloaded signature for {@link toolResultFrom}.
  */

package/dist/src/public/tool-result-narrowing.js

@@ -1,21 +1,47 @@
-const DEFINITION_SOURCE = Symbol("ash.definitionSource");
 /**
- * Stamps the path-derived runtime name onto an authored definition
- * object as a non-enumerable symbol property.
- *
- * Called by the resolution pipeline (`resolveToolDefinition`,
- * `resolveConnectionDefinition`) so {@link toolResultFrom} can read
- * the name back without a separate lookup structure.
+ * Cross-instance symbol for reading the stable definition key stamped
+ * by `defineTool` / `defineMcpClientConnection`. `Symbol.for` ensures
+ * both the resolution pipeline's module copy and the user's import
+ * share the same property key.
+ */
+const DEFINITION_KEY = Symbol.for("experimental-ash.definition-source-key");
+/**
+ * Global registry mapping definition keys to their resolved runtime
+ * names. Rooted on `globalThis` via `Symbol.for` so every module
+ * copy shares one registry — same pattern as `context/key.ts`
+ * (`KEY_REGISTRY_GLOBAL_KEY`).
+ */
+const REGISTRY_SYMBOL = Symbol.for("experimental-ash.definition-source-registry");
+const registryContainer = globalThis;
+if (registryContainer[REGISTRY_SYMBOL] === undefined) {
+    registryContainer[REGISTRY_SYMBOL] = new Map();
+}
+const definitionSourceRegistry = registryContainer[REGISTRY_SYMBOL];
+/**
+ * Stamps a stable content-derived key on the definition so it can be
+ * identified across module instances. Called by `defineTool` and
+ * `defineMcpClientConnection` at definition time.
  */
-export function stampDefinitionSource(definition, entry) {
-    Object.defineProperty(definition, DEFINITION_SOURCE, { value: entry });
+export function stampDefinitionKey(definition, key) {
+    Object.defineProperty(definition, DEFINITION_KEY, { value: key });
 }
-function readDefinitionSource(definition) {
-    if (DEFINITION_SOURCE in definition) {
-        return definition[DEFINITION_SOURCE];
+/**
+ * Reads the stable key from a definition, or `undefined` if unstamped.
+ */
+function readDefinitionKey(definition) {
+    if (DEFINITION_KEY in definition) {
+        return definition[DEFINITION_KEY];
     }
     return undefined;
 }
+/**
+ * Registers a definition key → source entry mapping in the global
+ * registry. Called by the resolution pipeline after loading the
+ * authored module.
+ */
+export function registerDefinitionSource(key, entry) {
+    definitionSourceRegistry.set(key, entry);
+}
 const CONNECTION_TOOL_SEPARATOR = "__";
 /**
  * Narrows a {@link RuntimeActionResult} to a typed tool or connection
@@ -34,7 +60,10 @@ function toolResultFromImpl(result, source) {
         return undefined;
     if (result.isError === true)
         return undefined;
-    const entry = readDefinitionSource(source);
+    const key = readDefinitionKey(source);
+    if (key === undefined)
+        return undefined;
+    const entry = definitionSourceRegistry.get(key);
     if (entry === undefined)
         return undefined;
     if (entry.kind === "tool") {

package/dist/src/runtime/resolve-connection.js

@@ -1,5 +1,5 @@
 import { expectObjectRecord } from "#internal/authored-module.js";
-import { stampDefinitionSource } from "#public/tool-result-narrowing.js";
+import { registerDefinitionSource } from "#public/tool-result-narrowing.js";
 import { toErrorMessage } from "#shared/errors.js";
 import { normalizeAuthorizationSpec } from "#runtime/connections/validate-authorization.js";
 import { loadResolvedModuleExport, ResolveAgentError } from "#runtime/resolve-helpers.js";
@@ -23,7 +23,10 @@ export async function resolveConnectionDefinition(definition, moduleMap, nodeId)
             nodeId,
         });
         const resolvedRecord = expectObjectRecord(resolvedExportValue, `Expected the connection export "${definition.exportName ?? "default"}" from "${definition.logicalPath}" to return an object.`);
-        stampDefinitionSource(resolvedRecord, { kind: "connection", name: definition.connectionName });
+        registerDefinitionSource(`connection:${resolvedRecord.url}`, {
+            kind: "connection",
+            name: definition.connectionName,
+        });
         const hasAuth = resolvedRecord.auth !== undefined;
         const hasHeaders = resolvedRecord.headers !== undefined;
         const result = {

package/dist/src/runtime/resolve-tool.js

@@ -1,5 +1,5 @@
 import { expectFunction, expectObjectRecord } from "#internal/authored-module.js";
-import { stampDefinitionSource } from "#public/tool-result-narrowing.js";
+import { registerDefinitionSource } from "#public/tool-result-narrowing.js";
 import { toErrorMessage } from "#shared/errors.js";
 import { loadResolvedModuleExport, ResolveAgentError } from "#runtime/resolve-helpers.js";
 /**
@@ -21,7 +21,10 @@ export async function resolveToolDefinition(definition, moduleMap, nodeId) {
             nodeId,
         });
         const resolvedRecord = expectObjectRecord(resolvedExportValue, describe(definition, "to return an object"));
-        stampDefinitionSource(resolvedRecord, { kind: "tool", name: definition.name });
+        registerDefinitionSource(`tool:${resolvedRecord.description}`, {
+            kind: "tool",
+            name: definition.name,
+        });
         const execute = expectFunction(resolvedRecord.execute, describe(definition, "to provide an execute function"));
         return {
             description: definition.description,

package/package.json

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