experimental-ash 0.20.1 → 0.22.0

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

@@ -0,0 +1,150 @@
+import { isAbsolute, resolve } from "node:path";
+import { ASH_ROUTE_PREFIX } from "#protocol/routes.js";
+import { resolveAshDestinationPrefix } from "./server.js";
+import { ensureAshVercelJson } from "./vercel-json.js";
+/**
+ * Private route namespace used when a Vercel deployment hosts Ash as a
+ * separate experimental service behind the Next.js app.
+ */
+export const ASH_NEXT_SERVICE_PREFIX = "/_ash_internal/ash";
+const ASH_NEXT_PRODUCTION_ORIGIN_ENV = "ASH_NEXT_PRODUCTION_ORIGIN";
+const ASH_NEXT_PRODUCTION_PORT_ENV = "ASH_NEXT_PRODUCTION_PORT";
+const DEFAULT_ASH_NEXT_PRODUCTION_PORT = 4274;
+const ASH_PROXY_REWRITE_SOURCES = [`${ASH_ROUTE_PREFIX}/:path+`];
+function resolveApplicationRoot(appPath) {
+    if (appPath === undefined || appPath.length === 0) {
+        return process.cwd();
+    }
+    return isAbsolute(appPath) ? appPath : resolve(process.cwd(), appPath);
+}
+function normalizeRoutePrefix(prefix) {
+    const prefixed = prefix.startsWith("/") ? prefix : `/${prefix}`;
+    const normalized = prefixed.replace(/\/+$/, "");
+    if (normalized.length === 0) {
+        throw new Error("Ash Next.js service prefix cannot resolve to the root route.");
+    }
+    return normalized;
+}
+function joinRoutePrefix(prefix, path) {
+    return `${prefix.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+function normalizeOrigin(origin) {
+    return new URL(origin.trim()).origin;
+}
+function hasUrlScheme(value) {
+    return /^[a-z][a-z\d+.-]*:/i.test(value);
+}
+function resolveVercelDeploymentOrigin() {
+    const deploymentUrl = process.env.VERCEL_URL;
+    if (deploymentUrl === undefined || deploymentUrl.trim().length === 0) {
+        return undefined;
+    }
+    return normalizeOrigin(hasUrlScheme(deploymentUrl) ? deploymentUrl : `https://${deploymentUrl}`);
+}
+function readLocalProductionPort() {
+    const configuredPort = process.env[ASH_NEXT_PRODUCTION_PORT_ENV];
+    if (configuredPort === undefined || configuredPort.trim().length === 0) {
+        return DEFAULT_ASH_NEXT_PRODUCTION_PORT;
+    }
+    const port = Number.parseInt(configuredPort, 10);
+    if (String(port) !== configuredPort.trim() || port < 1 || port > 65_535) {
+        throw new Error(`${ASH_NEXT_PRODUCTION_PORT_ENV} must be an integer between 1 and 65535.`);
+    }
+    return port;
+}
+function resolveProductionDestination(servicePrefix) {
+    const configuredOrigin = process.env[ASH_NEXT_PRODUCTION_ORIGIN_ENV];
+    if (configuredOrigin !== undefined && configuredOrigin.trim().length > 0) {
+        return {
+            destinationPrefix: joinRoutePrefix(normalizeOrigin(configuredOrigin), servicePrefix),
+        };
+    }
+    const vercelOrigin = resolveVercelDeploymentOrigin();
+    if (vercelOrigin !== undefined) {
+        return {
+            destinationPrefix: joinRoutePrefix(vercelOrigin, servicePrefix),
+        };
+    }
+    const localServerOrigin = `http://127.0.0.1:${String(readLocalProductionPort())}`;
+    return {
+        destinationPrefix: localServerOrigin,
+        localServerOrigin,
+    };
+}
+function createAshRewriteRules(destinationPrefix) {
+    return ASH_PROXY_REWRITE_SOURCES.map((source) => ({
+        basePath: false,
+        destination: joinRoutePrefix(destinationPrefix, source),
+        source,
+    }));
+}
+async function resolveExistingRewrites(rewrites) {
+    return await rewrites?.();
+}
+function mergeRewriteRules(existing, ashRules) {
+    if (existing === undefined) {
+        return ashRules;
+    }
+    if (!isRewriteSections(existing)) {
+        return [...ashRules, ...existing];
+    }
+    return {
+        ...existing,
+        beforeFiles: [...ashRules, ...(existing.beforeFiles ?? [])],
+    };
+}
+function isRewriteSections(rewrites) {
+    return !Array.isArray(rewrites);
+}
+async function resolveNextConfig(configOrFunction, phase, context) {
+    return typeof configOrFunction === "function"
+        ? await configOrFunction(phase, context)
+        : configOrFunction;
+}
+/**
+ * Wraps a Next.js config so same-origin Ash endpoints proxy to a separate Ash
+ * service.
+ *
+ * In development, `withAsh` starts `ash dev --no-repl --port 0` for the Ash
+ * app and rewrites Ash protocol endpoints to that local URL. In production on
+ * Vercel, it rewrites to the private Ash service prefix configured in
+ * `vercel.json` using the deployment origin from `VERCEL_URL`. Outside Vercel
+ * production, it serves an existing `.output/server/index.mjs` Ash build on a
+ * stable local port when present; otherwise set `ASH_NEXT_PRODUCTION_ORIGIN` to
+ * the origin that serves the Ash service namespace.
+ */
+export function withAsh(configOrFunction, options = {}) {
+    const nextRoot = process.cwd();
+    const appRoot = resolveApplicationRoot(options.ashRoot);
+    const servicePrefixInput = normalizeRoutePrefix(options.servicePrefix ?? ASH_NEXT_SERVICE_PREFIX);
+    const shouldConfigureVercelJson = options.configureVercelJson !== false;
+    return async function ashNextConfig(phase, context) {
+        const nextConfig = await resolveNextConfig(configOrFunction, phase, context);
+        const existingRewrites = nextConfig.rewrites;
+        const configuredVercel = shouldConfigureVercelJson
+            ? await ensureAshVercelJson({
+                appRoot,
+                nextRoot,
+                servicePrefix: servicePrefixInput,
+            })
+            : {
+                servicePrefix: servicePrefixInput,
+            };
+        const productionDestination = resolveProductionDestination(configuredVercel.servicePrefix);
+        return {
+            ...nextConfig,
+            async rewrites() {
+                const [existing, destinationPrefix] = await Promise.all([
+                    resolveExistingRewrites(existingRewrites),
+                    resolveAshDestinationPrefix({
+                        appRoot,
+                        phase,
+                        productionDestinationPrefix: productionDestination.destinationPrefix,
+                        productionServerOrigin: productionDestination.localServerOrigin,
+                    }),
+                ]);
+                return mergeRewriteRules(existing, createAshRewriteRules(destinationPrefix));
+            },
+        };
+    };
+}

package/dist/src/public/next/server.d.ts

@@ -0,0 +1,6 @@
+export declare function resolveAshDestinationPrefix(input: {
+    readonly appRoot: string;
+    readonly phase: string;
+    readonly productionDestinationPrefix: string;
+    readonly productionServerOrigin?: string;
+}): Promise<string>;

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

@@ -0,0 +1,348 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, open, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { resolvePackageRoot } from "#internal/application/package.js";
+import { ASH_ROUTE_PREFIX } from "#protocol/routes.js";
+const ASH_BASE_URL_ENV = "ASH_BASE_URL";
+const DEFAULT_SERVER_READY_TIMEOUT_MS = 30_000;
+const DEV_SERVER_REGISTRY_TIMEOUT_MS = 30_000;
+const DEV_SERVER_REGISTRY_POLL_MS = 100;
+const DEV_SERVER_STALE_LOCK_MS = 30_000;
+const ASH_CACHE_DIRECTORY_NAME = ".ash";
+const ASH_NEXT_DEV_SERVER_FILE_NAME = "next-dev-server.json";
+const ASH_NEXT_DEV_SERVER_LOCK_FILE_NAME = "next-dev-server.lock";
+const LOCAL_SERVER_URL_PATTERN = /https?:\/\/(?:\[[^\]\s]+\]|[^\s/:[\]]+)(?::\d+)?/;
+const NEXT_PHASE_PRODUCTION_BUILD = "phase-production-build";
+const globalStateSymbol = Symbol.for("experimental-ash.next.state");
+function getGlobalState() {
+    const globalWithState = globalThis;
+    globalWithState[globalStateSymbol] ??= {
+        servers: new Map(),
+    };
+    return globalWithState[globalStateSymbol];
+}
+function joinRoutePrefix(prefix, path) {
+    return `${prefix.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+function normalizeOrigin(origin) {
+    return new URL(origin).origin;
+}
+function readAshBaseUrlEnvironment() {
+    const configuredUrl = process.env[ASH_BASE_URL_ENV];
+    if (configuredUrl === undefined || configuredUrl.trim().length === 0) {
+        return undefined;
+    }
+    return normalizeOrigin(configuredUrl);
+}
+function isNodeErrorWithCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+function delay(ms) {
+    return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function resolveAshCacheDirectory(appRoot) {
+    return join(appRoot, ASH_CACHE_DIRECTORY_NAME);
+}
+function resolveAshDevServerRegistryPath(appRoot) {
+    return join(resolveAshCacheDirectory(appRoot), ASH_NEXT_DEV_SERVER_FILE_NAME);
+}
+function resolveAshDevServerLockPath(appRoot) {
+    return join(resolveAshCacheDirectory(appRoot), ASH_NEXT_DEV_SERVER_LOCK_FILE_NAME);
+}
+function normalizeDevServerRegistry(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    if (typeof value.appRoot !== "string" ||
+        typeof value.origin !== "string" ||
+        typeof value.updatedAt !== "string") {
+        return undefined;
+    }
+    if (value.pid !== null && typeof value.pid !== "number") {
+        return undefined;
+    }
+    try {
+        return {
+            appRoot: value.appRoot,
+            origin: normalizeOrigin(value.origin),
+            pid: value.pid,
+            updatedAt: value.updatedAt,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+async function isAshServerHealthy(origin) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+        controller.abort();
+    }, 1_000);
+    try {
+        const response = await fetch(joinRoutePrefix(origin, `${ASH_ROUTE_PREFIX}/health`), {
+            signal: controller.signal,
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function readUsableAshDevServerRegistry(appRoot) {
+    try {
+        const registry = normalizeDevServerRegistry(JSON.parse(await readFile(resolveAshDevServerRegistryPath(appRoot), "utf8")));
+        if (registry === undefined || registry.appRoot !== appRoot) {
+            return undefined;
+        }
+        if (!(await isAshServerHealthy(registry.origin))) {
+            return undefined;
+        }
+        process.env[ASH_BASE_URL_ENV] = registry.origin;
+        return registry.origin;
+    }
+    catch (error) {
+        if (isNodeErrorWithCode(error, "ENOENT")) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function writeAshDevServerRegistry(appRoot, handle) {
+    await mkdir(resolveAshCacheDirectory(appRoot), {
+        recursive: true,
+    });
+    await writeFile(resolveAshDevServerRegistryPath(appRoot), `${JSON.stringify({
+        appRoot,
+        origin: handle.origin,
+        pid: handle.process?.pid ?? null,
+        updatedAt: new Date().toISOString(),
+    }, null, 2)}\n`);
+}
+async function removeStaleAshDevServerLock(lockPath) {
+    try {
+        const lockStat = await stat(lockPath);
+        if (Date.now() - lockStat.mtimeMs > DEV_SERVER_STALE_LOCK_MS) {
+            await rm(lockPath, {
+                force: true,
+            });
+        }
+    }
+    catch (error) {
+        if (!isNodeErrorWithCode(error, "ENOENT")) {
+            throw error;
+        }
+    }
+}
+async function acquireAshDevServerLock(appRoot) {
+    const cacheDirectory = resolveAshCacheDirectory(appRoot);
+    const lockPath = resolveAshDevServerLockPath(appRoot);
+    const deadline = Date.now() + DEV_SERVER_REGISTRY_TIMEOUT_MS;
+    await mkdir(cacheDirectory, {
+        recursive: true,
+    });
+    while (true) {
+        try {
+            const lockFile = await open(lockPath, "wx");
+            await lockFile.writeFile(`${String(process.pid)}\n`);
+            await lockFile.close();
+            return async () => {
+                await rm(lockPath, {
+                    force: true,
+                });
+            };
+        }
+        catch (error) {
+            if (!isNodeErrorWithCode(error, "EEXIST")) {
+                throw error;
+            }
+            const registeredOrigin = await readUsableAshDevServerRegistry(appRoot);
+            if (registeredOrigin !== undefined) {
+                return async () => { };
+            }
+            await removeStaleAshDevServerLock(lockPath);
+            if (Date.now() > deadline) {
+                throw new Error(`Timed out after ${DEV_SERVER_REGISTRY_TIMEOUT_MS}ms waiting for another Next.js process to start Ash.`);
+            }
+            await delay(DEV_SERVER_REGISTRY_POLL_MS);
+        }
+    }
+}
+function createAshBinaryPath() {
+    return join(resolvePackageRoot(), "bin", "ash.js");
+}
+function normalizeParsedOrigin(urlText) {
+    const url = new URL(urlText);
+    return url.origin;
+}
+function startServerProcess(input) {
+    return new Promise((resolvePromise, reject) => {
+        const child = spawn(input.command, input.args, {
+            cwd: input.cwd,
+            env: {
+                ...process.env,
+                ...input.env,
+            },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const timeout = setTimeout(() => {
+            child.kill();
+            reject(new Error(`Timed out after ${input.timeoutMs ?? DEFAULT_SERVER_READY_TIMEOUT_MS}ms waiting for Ash to print its server URL.`));
+        }, input.timeoutMs ?? DEFAULT_SERVER_READY_TIMEOUT_MS);
+        const cleanup = () => {
+            clearTimeout(timeout);
+            child.off("error", handleError);
+            child.off("exit", handleEarlyExit);
+        };
+        const handleError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const handleEarlyExit = (code, signal) => {
+            cleanup();
+            reject(new Error(`Ash server process exited before printing its server URL (code ${String(code)}, signal ${String(signal)}).`));
+        };
+        const handleOutput = (chunk) => {
+            const match = LOCAL_SERVER_URL_PATTERN.exec(chunk.toString("utf8"));
+            if (match === null) {
+                return;
+            }
+            cleanup();
+            resolvePromise({
+                origin: normalizeParsedOrigin(match[0]),
+                process: child,
+            });
+        };
+        const handleStdout = (chunk) => {
+            process.stdout.write(chunk);
+            handleOutput(chunk);
+        };
+        const handleStderr = (chunk) => {
+            process.stderr.write(chunk);
+            handleOutput(chunk);
+        };
+        child.once("error", handleError);
+        child.once("exit", handleEarlyExit);
+        child.stdout.on("data", handleStdout);
+        child.stderr.on("data", handleStderr);
+    });
+}
+function installProcessShutdown(handle) {
+    const childProcess = handle.process;
+    if (childProcess === undefined) {
+        return handle;
+    }
+    const close = () => {
+        if (!childProcess.killed) {
+            childProcess.kill();
+        }
+    };
+    process.once("beforeExit", close);
+    process.once("exit", close);
+    return handle;
+}
+function startAshDevServer(appRoot) {
+    return startServerProcess({
+        args: [createAshBinaryPath(), "dev", "--no-repl", "--port", "0"],
+        command: process.execPath,
+        cwd: appRoot,
+    }).then((handle) => {
+        process.env[ASH_BASE_URL_ENV] = handle.origin;
+        return installProcessShutdown(handle);
+    });
+}
+function startAshProductionServer(input) {
+    const parsedOrigin = new URL(input.origin);
+    const port = parsedOrigin.port;
+    const serverEntry = join(input.appRoot, ".output", "server", "index.mjs");
+    if (!existsSync(serverEntry)) {
+        return undefined;
+    }
+    return startServerProcess({
+        args: [serverEntry],
+        command: process.execPath,
+        cwd: input.appRoot,
+        env: {
+            HOST: parsedOrigin.hostname,
+            NITRO_HOST: parsedOrigin.hostname,
+            NITRO_PORT: port,
+            PORT: port,
+        },
+    }).then(installProcessShutdown);
+}
+async function resolveSharedAshDevServer(appRoot) {
+    const registeredOrigin = await readUsableAshDevServerRegistry(appRoot);
+    if (registeredOrigin !== undefined) {
+        return {
+            origin: registeredOrigin,
+        };
+    }
+    const releaseLock = await acquireAshDevServerLock(appRoot);
+    try {
+        const lockedRegisteredOrigin = await readUsableAshDevServerRegistry(appRoot);
+        if (lockedRegisteredOrigin !== undefined) {
+            return {
+                origin: lockedRegisteredOrigin,
+            };
+        }
+        const handle = await startAshDevServer(appRoot);
+        await writeAshDevServerRegistry(appRoot, handle);
+        return handle;
+    }
+    finally {
+        await releaseLock();
+    }
+}
+export async function resolveAshDestinationPrefix(input) {
+    const state = getGlobalState();
+    if (process.env.NODE_ENV === "production") {
+        if (input.phase === NEXT_PHASE_PRODUCTION_BUILD) {
+            return input.productionDestinationPrefix;
+        }
+        const key = `production:${input.appRoot}`;
+        let productionServer = state.servers.get(key);
+        if (productionServer === undefined) {
+            productionServer =
+                process.env.VERCEL || input.productionServerOrigin === undefined
+                    ? undefined
+                    : startAshProductionServer({
+                        appRoot: input.appRoot,
+                        origin: input.productionServerOrigin,
+                    });
+            if (productionServer !== undefined) {
+                productionServer = productionServer.catch((error) => {
+                    state.servers.delete(key);
+                    throw error;
+                });
+                state.servers.set(key, productionServer);
+            }
+        }
+        if (productionServer !== undefined) {
+            return (await productionServer).origin;
+        }
+        return input.productionDestinationPrefix;
+    }
+    const configuredAshBaseUrl = readAshBaseUrlEnvironment();
+    if (configuredAshBaseUrl !== undefined) {
+        return configuredAshBaseUrl;
+    }
+    if (process.env.NODE_ENV !== "development") {
+        return input.productionDestinationPrefix;
+    }
+    const key = `dev:${input.appRoot}`;
+    let server = state.servers.get(key);
+    if (server === undefined) {
+        server = resolveSharedAshDevServer(input.appRoot).catch((error) => {
+            state.servers.delete(key);
+            throw error;
+        });
+        state.servers.set(key, server);
+    }
+    return (await server).origin;
+}

package/dist/src/public/next/vercel-json.d.ts

@@ -0,0 +1,8 @@
+export interface EnsureVercelJsonResult {
+    readonly servicePrefix: string;
+}
+export declare function ensureAshVercelJson(input: {
+    readonly appRoot: string;
+    readonly nextRoot: string;
+    readonly servicePrefix: string;
+}): Promise<EnsureVercelJsonResult>;

package/dist/src/public/next/vercel-json.js

@@ -0,0 +1,76 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+const VERCEL_JSON_FILE_NAME = "vercel.json";
+const VERCEL_JSON_SCHEMA = "https://openapi.vercel.sh/vercel.json";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function resolveRelativeEntrypoint(fromRoot, toRoot) {
+    const relativePath = relative(fromRoot, toRoot);
+    if (relativePath.length === 0) {
+        return ".";
+    }
+    return relativePath.replaceAll("\\", "/");
+}
+function normalizeVercelJsonConfig(value) {
+    if (!isRecord(value)) {
+        throw new Error(`${VERCEL_JSON_FILE_NAME} must contain a JSON object.`);
+    }
+    const experimentalServices = value.experimentalServices;
+    if (experimentalServices !== undefined && !isRecord(experimentalServices)) {
+        throw new Error(`${VERCEL_JSON_FILE_NAME} experimentalServices must be a JSON object.`);
+    }
+    return value;
+}
+async function readVercelJsonConfig(path) {
+    try {
+        return normalizeVercelJsonConfig(JSON.parse(await readFile(path, "utf8")));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return {};
+        }
+        throw error;
+    }
+}
+function findServiceByFramework(services, framework) {
+    return Object.values(services).find((service) => service.framework === framework);
+}
+export async function ensureAshVercelJson(input) {
+    const vercelJsonPath = join(input.nextRoot, VERCEL_JSON_FILE_NAME);
+    const existingConfig = await readVercelJsonConfig(vercelJsonPath);
+    const nextEntrypoint = ".";
+    const ashEntrypoint = resolveRelativeEntrypoint(input.nextRoot, input.appRoot);
+    const existingServices = existingConfig.experimentalServices ?? {};
+    const configuredAshService = findServiceByFramework(existingServices, "ash");
+    const configuredNextService = findServiceByFramework(existingServices, "nextjs");
+    const servicePrefix = configuredAshService?.routePrefix ?? input.servicePrefix;
+    const experimentalServices = {
+        ...existingServices,
+    };
+    if (configuredNextService === undefined) {
+        experimentalServices.web = {
+            entrypoint: nextEntrypoint,
+            framework: "nextjs",
+            routePrefix: "/",
+        };
+    }
+    if (configuredAshService === undefined) {
+        experimentalServices.ash = {
+            entrypoint: ashEntrypoint,
+            framework: "ash",
+            routePrefix: servicePrefix,
+        };
+    }
+    const vercelConfig = {
+        ...existingConfig,
+        $schema: existingConfig.$schema ?? VERCEL_JSON_SCHEMA,
+        experimentalServices,
+    };
+    if (JSON.stringify(existingConfig) !== JSON.stringify(vercelConfig)) {
+        await writeFile(vercelJsonPath, `${JSON.stringify(vercelConfig, null, 2)}\n`);
+    }
+    return {
+        servicePrefix,
+    };
+}

package/dist/src/public/skills/index.d.ts

@@ -3,4 +3,4 @@
  */
 export { getSkill } from "#context/accessors.js";
 export type { SkillFile, SkillHandle } from "#execution/skills/types.js";
-export { defineSkill, type SkillDefinition } from "#public/definitions/skill.js";
+export { defineSkill, type NamedSkillDefinition, type SkillDefinition, type SkillFileContent, type SkillPackageDefinition, } from "#public/definitions/skill.js";

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

@@ -2,4 +2,4 @@
  * Skill authoring helpers and runtime accessors.
  */
 export { getSkill } from "#context/accessors.js";
-export { defineSkill } from "#public/definitions/skill.js";
+export { defineSkill, } from "#public/definitions/skill.js";

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

@@ -0,0 +1,68 @@
+import type { RuntimeActionResult } from "#runtime/actions/types.js";
+import type { McpClientConnectionDefinition } from "#public/definitions/connections/mcp.js";
+import type { ToolDefinition } from "#public/definitions/tool.js";
+/**
+ * Narrowed tool result returned by {@link toolResultFrom} when the
+ * action result matches an authored {@link ToolDefinition}.
+ *
+ * `TOutput` is inferred from the tool definition's `execute` return type.
+ */
+export interface MatchedToolResult<TOutput> {
+    readonly callId: string;
+    readonly output: TOutput;
+    readonly toolName: string;
+}
+/**
+ * Narrowed tool result returned by {@link toolResultFrom} when the
+ * action result matches an MCP connection.
+ *
+ * `output` stays `unknown` because MCP tool schemas are remote.
+ * `connectionToolName` is the unqualified MCP tool name (e.g.
+ * `"list_issues"`) while `toolName` is the full qualified name
+ * (e.g. `"linear__list_issues"`).
+ */
+export interface MatchedConnectionResult {
+    readonly callId: string;
+    readonly connectionToolName: string;
+    readonly output: unknown;
+    readonly toolName: string;
+}
+/**
+ * Discriminated source entry stamped on authored definitions during
+ * agent resolution via {@link stampDefinitionSource}.
+ */
+export type DefinitionSourceEntry = {
+    readonly kind: "connection";
+    readonly name: string;
+} | {
+    readonly kind: "tool";
+    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.
+ */
+export declare function stampDefinitionSource(definition: object, entry: DefinitionSourceEntry): void;
+/**
+ * Overloaded signature for {@link toolResultFrom}.
+ */
+export interface ToolResultFromFn {
+    <TInput, TOutput>(result: RuntimeActionResult, tool: ToolDefinition<TInput, TOutput>): MatchedToolResult<TOutput> | undefined;
+    (result: RuntimeActionResult, connection: McpClientConnectionDefinition): MatchedConnectionResult | undefined;
+}
+/**
+ * Narrows a {@link RuntimeActionResult} to a typed tool or connection
+ * result by matching against an authored definition object.
+ *
+ * Pass a `ToolDefinition` to get a typed `output`; pass a
+ * `McpClientConnectionDefinition` to match any tool from that
+ * connection (`output` stays `unknown`).
+ *
+ * Returns `undefined` when the result doesn't match, or when
+ * `isError` is `true`.
+ */
+export declare const toolResultFrom: ToolResultFromFn;