experimental-ash 0.26.0 → 0.28.0

package/dist/src/runtime/connections/principal.js

@@ -1,106 +1 @@
-/**
- * Principal resolution for connections.
- *
- * This module is the one place the runtime bridges session-layer
- * vocabulary (`"service" | "user" | "runtime" | "unknown"`) to the
- * connection-layer vocabulary (`"app" | "user"`) that connection
- * authors see. Every runtime call site that needs a
- * {@link ConnectionPrincipal} routes through
- * {@link resolveConnectionPrincipal}, and every cache lookup keyed
- * by principal routes through {@link principalKey}.
- */
-import { contextStorage } from "#context/container.js";
-import { AuthKey } from "#context/keys.js";
-import { ConnectionAuthorizationFailedError } from "#public/connections/errors.js";
-import { lookupConnectionPrincipalOverride } from "#runtime/connections/principal-context.js";
-/**
- * Stable string key identifying one principal within a connection's
- * per-principal token cache.
- *
- * - `{ type: "app" }` → `"app"`. Shared across all sessions.
- * - `{ type: "user", issuer, id }` → `"user:${issuer}:${id}"`. The
- *   issuer prefix prevents collisions when the same `id` across
- *   identity providers (for example Slack `U123` vs Google `U123`)
- *   would otherwise alias to the same cache slot.
- */
-export function principalKey(principal) {
-    if (principal.type === "app") {
-        return "app";
-    }
-    return `user:${principal.issuer}:${principal.id}`;
-}
-/**
- * Resolves the {@link ConnectionPrincipal} for one connection.
- *
- * Single entry point for principal resolution — every runtime
- * call site that needs a {@link ConnectionPrincipal} (wrapped tool
- * execution, `startAuthorization` step, `mcp-client` header
- * resolution) routes through here so the decision tree lives in
- * exactly one place.
- *
- * Resolution order:
- *
- * 1. If a context is active and some scope installed a transient
- *    override for `connectionName` via
- *    {@link withConnectionPrincipalOverride}, use it verbatim.
- *    Overrides exist so an in-flight retry can continue to see the
- *    principal that started the flow, even when the current
- *    session auth has rotated (for example during an OAuth
- *    webhook resume).
- * 2. For `authorization.principalType === "app"`, return
- *    `{ type: "app" }` regardless of the session. App-scoped
- *    connections share one credential across all callers and can
- *    be resolved with or without an active context.
- * 3. For `authorization.principalType === "user"`, project the
- *    current caller's {@link SessionAuthContext} (read directly from
- *    the durable {@link AuthKey} seed) into a user principal. A
- *    missing context, an unauthenticated caller, or a non-`"user"`
- *    current principal all fail fast with
- *    `reason: "principal_required"` — no amount of retrying will
- *    recover a misconfigured route, so the runtime does not treat
- *    it as retryable.
- *
- *    {@link AuthKey} is used instead of the derived `SessionKey`
- *    so resolution works in both `runStep` scopes (where
- *    `sessionProvider` has populated `SessionKey`) and durable
- *    `"use step"` boundaries where only the seed keys survive
- *    context serialization. The two are equivalent inside a step
- *    because `sessionProvider` projects `AuthKey` into
- *    `session.auth.current`.
- *
- * `ctx` defaults to {@link contextStorage.getStore}. Pass it
- * explicitly when the caller already has a context handle (for
- * example inside a durable step that deserialized its own
- * {@link AshContext}) to avoid a redundant ALS lookup.
- *
- * The caller is responsible for passing a matching
- * {@link AuthorizationDefinition}. This helper does not validate
- * the definition shape beyond reading `principalType`.
- */
-export function resolveConnectionPrincipal(connectionName, authorization, ctx = contextStorage.getStore()) {
-    const override = lookupConnectionPrincipalOverride(ctx, connectionName);
-    if (override !== undefined) {
-        return override;
-    }
-    if (authorization.principalType === "app") {
-        return { type: "app" };
-    }
-    const current = ctx?.get(AuthKey);
-    if (current === null || current === undefined || current.principalType !== "user") {
-        throw new ConnectionAuthorizationFailedError(connectionName, {
-            message: ctx === undefined
-                ? `Connection "${connectionName}" declares principalType "user" ` +
-                    `but was invoked outside an Ash context, so no user principal can be resolved.`
-                : `Connection "${connectionName}" declares principalType "user" ` +
-                    `but the active session has no authenticated user principal.`,
-            reason: "principal_required",
-            retryable: false,
-        });
-    }
-    return {
-        attributes: current.attributes,
-        id: current.principalId,
-        issuer: current.issuer ?? current.authenticator,
-        type: "user",
-    };
-}
+import{contextStorage}from"#context/container.js";import{AuthKey}from"#context/keys.js";import{ConnectionAuthorizationFailedError}from"#public/connections/errors.js";import{lookupConnectionPrincipalOverride}from"#runtime/connections/principal-context.js";function principalKey(e){return e.type===`app`?`app`:`user:${e.issuer}:${e.id}`}function resolveConnectionPrincipal(t,n,r=contextStorage.getStore()){let i=lookupConnectionPrincipalOverride(r,t);if(i!==void 0)return i;if(n.principalType===`app`)return{type:`app`};let a=r?.get(AuthKey);if(a==null||a.principalType!==`user`)throw new ConnectionAuthorizationFailedError(t,{message:r===void 0?`Connection "${t}" declares principalType "user" but was invoked outside an Ash context, so no user principal can be resolved.`:`Connection "${t}" declares principalType "user" but the active session has no authenticated user principal.`,reason:`principal_required`,retryable:!1});return{attributes:a.attributes,id:a.principalId,issuer:a.issuer??a.authenticator,type:`user`}}export{principalKey,resolveConnectionPrincipal};

package/dist/src/runtime/connections/registry.js

@@ -1,61 +1 @@
-import { McpConnectionClient } from "#runtime/connections/mcp-client.js";
-/**
- * Per-session container mapping connection names to lazily-initialized
- * client wrappers.
- *
- * Currently all connections use MCP, but the registry is protocol-agnostic
- * and will dispatch to the appropriate client type when additional
- * protocols (e.g. OpenAPI) are supported.
- */
-export class ConnectionRegistryImpl {
-    #clients = new Map();
-    #connections;
-    constructor(connections) {
-        this.#connections = connections;
-    }
-    /**
-     * Returns the client for the named connection, creating it on first
-     * access.
-     */
-    getClient(connectionName) {
-        const existing = this.#clients.get(connectionName);
-        if (existing !== undefined) {
-            return existing;
-        }
-        const connection = this.#connections.find((c) => c.connectionName === connectionName);
-        if (connection === undefined) {
-            throw new Error(`Connection "${connectionName}" is not registered.`);
-        }
-        const client = new McpConnectionClient(connection);
-        this.#clients.set(connectionName, client);
-        return client;
-    }
-    /**
-     * Returns the authored approval function for the named connection,
-     * or `undefined` if the connection did not specify one.
-     */
-    getConnectionApproval(connectionName) {
-        const connection = this.#connections.find((c) => c.connectionName === connectionName);
-        return connection?.approval;
-    }
-    /**
-     * Returns all registered connection names.
-     */
-    getConnectionNames() {
-        return this.#connections.map((c) => c.connectionName);
-    }
-    /**
-     * Returns the resolved definitions for all connections.
-     */
-    getConnections() {
-        return this.#connections;
-    }
-    /**
-     * Closes all active client connections.
-     */
-    async dispose() {
-        const closePromises = [...this.#clients.values()].map((client) => client.close());
-        await Promise.allSettled(closePromises);
-        this.#clients.clear();
-    }
-}
+import{McpConnectionClient}from"#runtime/connections/mcp-client.js";var ConnectionRegistryImpl=class{#e=new Map;#t;constructor(e){this.#t=e}getClient(t){let n=this.#e.get(t);if(n!==void 0)return n;let r=this.#t.find(e=>e.connectionName===t);if(r===void 0)throw Error(`Connection "${t}" is not registered.`);let i=new McpConnectionClient(r);return this.#e.set(t,i),i}getConnectionApproval(e){return this.#t.find(t=>t.connectionName===e)?.approval}getConnectionNames(){return this.#t.map(e=>e.connectionName)}getConnections(){return this.#t}async dispose(){let e=[...this.#e.values()].map(e=>e.close());await Promise.allSettled(e),this.#e.clear()}};export{ConnectionRegistryImpl};

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

@@ -1,41 +1 @@
-/**
- * Protocol-agnostic interfaces for the connection system.
- *
- * Framework tools (`connection_search`) and the context provider
- * depend only on these interfaces, not on any
- * protocol-specific implementation such as MCP.
- */
-/**
- * Defines an interactive authorization strategy with type-safe state
- * flowing from {@link InteractiveAuthorizationDefinition.startAuthorization}
- * to {@link InteractiveAuthorizationDefinition.completeAuthorization}.
- *
- * Defaults `principalType` to `"user"` (the only valid value for
- * interactive authorization in v1).
- *
- * @example
- * ```ts
- * defineInteractiveAuthorization({
- *   getToken: async ({ principal }) => ({ token: cached }),
- *   startAuthorization: async ({ principal, callbackUrl }) => ({
- *     challenge: { url: `https://idp.example/auth?redirect=${callbackUrl}` },
- *     state: { verifier: pkceVerifier },
- *   }),
- *   completeAuthorization: async ({ principal, state, request }) => {
- *     // state is typed as { verifier: string }
- *     const token = await exchange(state.verifier, request);
- *     return { token };
- *   },
- * })
- * ```
- */
-export function defineInteractiveAuthorization(definition) {
-    return { ...definition, principalType: "user" };
-}
-/**
- * Returns whether an authorization definition supports the framework-owned
- * interactive OAuth flow.
- */
-export function supportsInteractiveAuthorization(authorization) {
-    return authorization?.startAuthorization !== undefined;
-}
+function defineInteractiveAuthorization(e){return{...e,principalType:`user`}}function supportsInteractiveAuthorization(e){return e?.startAuthorization!==void 0}export{defineInteractiveAuthorization,supportsInteractiveAuthorization};

package/dist/src/runtime/connections/validate-authorization.js

@@ -1,92 +1 @@
-/**
- * Structural validation for authored connection auth definitions. Returns
- * `undefined` on success or a context-free error fragment for the caller to
- * prefix.
- */
-/**
- * Validates that authored `auth` conforms to the connection auth contract.
- *
- * Returns `undefined` on success; otherwise a descriptive message
- * fragment starting with `The "<fieldName>"...` that the caller is expected
- * to prefix with its own context.
- */
-export function validateAuthorizationSpec(authorization, fieldName = "auth") {
-    if (authorization === null || typeof authorization !== "object") {
-        return `The "${fieldName}" field must be an object with a "getToken" method.`;
-    }
-    const auth = authorization;
-    if (typeof auth.getToken !== "function") {
-        return `The "${fieldName}.getToken" field must be a function returning Promise<{ token }>.`;
-    }
-    const hasStart = auth.startAuthorization !== undefined;
-    const hasComplete = auth.completeAuthorization !== undefined;
-    if (!hasStart && !hasComplete && auth.principalType !== undefined) {
-        if (auth.principalType !== "app" && auth.principalType !== "user") {
-            return `The "${fieldName}.principalType" field must be "app" or "user".`;
-        }
-    }
-    if (hasStart !== hasComplete) {
-        return `The "${fieldName}" field must provide either both "startAuthorization" and "completeAuthorization" (interactive OAuth) or neither (getToken-only). Got only "${hasStart ? "startAuthorization" : "completeAuthorization"}".`;
-    }
-    if (hasStart && typeof auth.startAuthorization !== "function") {
-        return `The "${fieldName}.startAuthorization" field must be a function when provided.`;
-    }
-    if (hasComplete && typeof auth.completeAuthorization !== "function") {
-        return `The "${fieldName}.completeAuthorization" field must be a function when provided.`;
-    }
-    if (hasStart && auth.principalType !== "user") {
-        return `Interactive authorization (startAuthorization + completeAuthorization) is restricted to "principalType": "user" in v1. See D10 of research/connections/connection-principal-model.md for the rationale.`;
-    }
-    return undefined;
-}
-/**
- * Validates and normalizes an authored auth definition into the runtime shape.
- *
- * `getToken`-only auth defaults to `principalType: "app"` so static tokens and
- * custom bearer-token fetchers do not need extra boilerplate.
- */
-export function normalizeAuthorizationSpec(authorization, prefix, fieldName = "auth") {
-    const message = validateAuthorizationSpec(authorization, fieldName);
-    if (message !== undefined) {
-        throw new Error(`${prefix} ${message}`);
-    }
-    const auth = authorization;
-    const vercelConnect = extractVercelConnectMarker(auth.vercelConnect);
-    if (auth.startAuthorization !== undefined && auth.completeAuthorization !== undefined) {
-        const interactive = {
-            completeAuthorization: auth.completeAuthorization,
-            getToken: auth.getToken,
-            principalType: "user",
-            startAuthorization: auth.startAuthorization,
-        };
-        return vercelConnect === undefined ? interactive : { ...interactive, vercelConnect };
-    }
-    const nonInteractive = {
-        getToken: auth.getToken,
-        principalType: (auth.principalType ??
-            "app"),
-    };
-    return vercelConnect === undefined ? nonInteractive : { ...nonInteractive, vercelConnect };
-}
-/**
- * Reads the optional `vercelConnect: { connector: string }` marker
- * attached by `@vercel/connect/ash`'s `connect()` helper. Returns the
- * parsed marker when present and well-formed, otherwise `undefined`.
- *
- * The marker is opaque to the runtime — it exists so downstream tooling
- * (eg. the Ash compiler / Vercel dashboard) can attribute the auth
- * back to a Vercel Connect connector without inspecting `getToken`'s
- * closure state. Validation is lenient (a malformed marker is dropped,
- * not thrown) so a misbehaving auth provider can't fail an otherwise-
- * valid connection.
- */
-function extractVercelConnectMarker(value) {
-    if (value === null || typeof value !== "object") {
-        return undefined;
-    }
-    const connector = value.connector;
-    if (typeof connector !== "string" || connector.length === 0) {
-        return undefined;
-    }
-    return { connector };
-}
+function validateAuthorizationSpec(e,t=`auth`){if(typeof e!=`object`||!e)return`The "${t}" field must be an object with a "getToken" method.`;let n=e;if(typeof n.getToken!=`function`)return`The "${t}.getToken" field must be a function returning Promise<{ token }>.`;let r=n.startAuthorization!==void 0,i=n.completeAuthorization!==void 0;if(!r&&!i&&n.principalType!==void 0&&n.principalType!==`app`&&n.principalType!==`user`)return`The "${t}.principalType" field must be "app" or "user".`;if(r!==i)return`The "${t}" field must provide either both "startAuthorization" and "completeAuthorization" (interactive OAuth) or neither (getToken-only). Got only "${r?`startAuthorization`:`completeAuthorization`}".`;if(r&&typeof n.startAuthorization!=`function`)return`The "${t}.startAuthorization" field must be a function when provided.`;if(i&&typeof n.completeAuthorization!=`function`)return`The "${t}.completeAuthorization" field must be a function when provided.`;if(r&&n.principalType!==`user`)return`Interactive authorization (startAuthorization + completeAuthorization) is restricted to "principalType": "user" in v1. See D10 of research/connections/connection-principal-model.md for the rationale.`}function normalizeAuthorizationSpec(e,t,n=`auth`){let r=validateAuthorizationSpec(e,n);if(r!==void 0)throw Error(`${t} ${r}`);let i=e,a=extractVercelConnectMarker(i.vercelConnect);if(i.startAuthorization!==void 0&&i.completeAuthorization!==void 0){let e={completeAuthorization:i.completeAuthorization,getToken:i.getToken,principalType:`user`,startAuthorization:i.startAuthorization};return a===void 0?e:{...e,vercelConnect:a}}let o={getToken:i.getToken,principalType:i.principalType??`app`};return a===void 0?o:{...o,vercelConnect:a}}function extractVercelConnectMarker(e){if(typeof e!=`object`||!e)return;let t=e.connector;if(!(typeof t!=`string`||t.length===0))return{connector:t}}export{normalizeAuthorizationSpec,validateAuthorizationSpec};

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

@@ -1,38 +1 @@
-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();
-    const compiled = ashChannel({ auth });
-    const result = [];
-    for (const route of compiled.routes) {
-        result.push({
-            name: ASH_CHANNEL_NAME,
-            method: route.method.toUpperCase(),
-            urlPath: route.path,
-            fetch: async (req, ctx) => route.handler(req, ctx),
-            handler: route.handler,
-            adapter: compiled.adapter,
-            logicalPath: `framework://channels/${route.path}`,
-            sourceId: `ash:framework:${route.method.toLowerCase()}-${route.path}`,
-            sourceKind: "module",
-        });
-    }
-    result.push(...getConnectionCallbackChannelDefinitions(), ...getSessionCallbackChannelDefinitions());
-    return result;
-}
-export function getAllFrameworkChannelNames() {
-    return new Set([
-        ASH_CHANNEL_NAME,
-        ...getConnectionCallbackChannelNames(),
-        ...getSessionCallbackChannelNames(),
-    ]);
-}
-function resolveFrameworkAshAuth() {
-    if (process.env.VERCEL) {
-        return vercelOidc();
-    }
-    return none();
-}
+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";var ASH_CHANNEL_NAME=`ash`;function getFrameworkChannelDefinitions(){let e=ashChannel({auth:resolveFrameworkAshAuth()}),t=[];for(let n of e.routes)t.push({name:ASH_CHANNEL_NAME,method:n.method.toUpperCase(),urlPath:n.path,fetch:async(e,t)=>n.handler(e,t),handler:n.handler,adapter:e.adapter,logicalPath:`framework://channels/${n.path}`,sourceId:`ash:framework:${n.method.toLowerCase()}-${n.path}`,sourceKind:`module`});return t.push(...getConnectionCallbackChannelDefinitions(),...getSessionCallbackChannelDefinitions()),t}function getAllFrameworkChannelNames(){return new Set([ASH_CHANNEL_NAME,...getConnectionCallbackChannelNames(),...getSessionCallbackChannelNames()])}function resolveFrameworkAshAuth(){return process.env.VERCEL?vercelOidc():none()}export{getAllFrameworkChannelNames,getFrameworkChannelDefinitions};

package/dist/src/runtime/framework-tools/ask-question.js

@@ -1,30 +1 @@
-import { z } from "#compiled/zod/index.js";
-import { inputRequestSchema } from "#runtime/input/types.js";
-/**
- * Stable model-visible name for the framework question tool.
- */
-export const ASK_QUESTION_TOOL_NAME = "ask_question";
-const askQuestionToolInputSchema = inputRequestSchema.omit({
-    action: true,
-    display: true,
-    requestId: true,
-});
-const { $schema: _jsonSchemaVersion, ...askQuestionInputSchema } = z.toJSONSchema(askQuestionToolInputSchema);
-/**
- * Shared input schema used by the framework `ask_question` tool.
- */
-export const ASK_QUESTION_INPUT_SCHEMA = askQuestionInputSchema;
-/**
- * Root-only framework tool that lets the agent request structured user input.
- *
- * This is a client-side tool (as indicated by it not having an `execute` method). It requires user input
- * and therefore cannot be autonomously executed by the runtime.
- */
-export const ASK_QUESTION_TOOL_DEFINITION = {
-    description: "Ask the user a question and wait for their response before continuing. Use this when you need clarification or a choice from the user.",
-    inputSchema: ASK_QUESTION_INPUT_SCHEMA,
-    logicalPath: "ash:framework/ask-question",
-    name: ASK_QUESTION_TOOL_NAME,
-    sourceId: "ash:ask-question-tool",
-    sourceKind: "module",
-};
+import{z}from"#compiled/zod/index.js";import{inputRequestSchema}from"#runtime/input/types.js";var ASK_QUESTION_TOOL_NAME=`ask_question`,askQuestionToolInputSchema=inputRequestSchema.omit({action:!0,display:!0,requestId:!0}),{$schema:_jsonSchemaVersion,...askQuestionInputSchema}=z.toJSONSchema(askQuestionToolInputSchema),ASK_QUESTION_INPUT_SCHEMA=askQuestionInputSchema,ASK_QUESTION_TOOL_DEFINITION={description:`Ask the user a question and wait for their response before continuing. Use this when you need clarification or a choice from the user.`,inputSchema:ASK_QUESTION_INPUT_SCHEMA,logicalPath:`ash:framework/ask-question`,name:ASK_QUESTION_TOOL_NAME,sourceId:`ash:ask-question-tool`,sourceKind:`module`};export{ASK_QUESTION_INPUT_SCHEMA,ASK_QUESTION_TOOL_DEFINITION,ASK_QUESTION_TOOL_NAME};

package/dist/src/runtime/framework-tools/bash.js

@@ -1,40 +1 @@
-import { executeBashOnSandbox } from "#execution/sandbox/bash-tool.js";
-/**
- * Shared input schema used by the framework `bash` tool and any author tool
- * constructed via {@link defineBashTool}.
- *
- * Exported so the public `defineBashTool` factory and the framework
- * `BASH_TOOL_DEFINITION` use the exact same schema object — keeping model
- * input contracts in sync without duplication.
- */
-export const BASH_INPUT_SCHEMA = {
-    additionalProperties: false,
-    properties: {
-        command: {
-            description: "The shell command to execute.",
-            type: "string",
-        },
-    },
-    required: ["command"],
-    type: "object",
-};
-/**
- * Framework-owned executors stay statically imported so hosted server bundles
- * can trace and rewrite them into deployable output chunks.
- *
- * These modules are only used by the Nitro-hosted runtime path. Their deeper
- * sandbox dependencies remain lazily loaded inside the execution layer, so the
- * top-level import here does not force those backends to initialize eagerly.
- */
-async function executeBash(input) {
-    return executeBashOnSandbox(input);
-}
-export const BASH_TOOL_DEFINITION = {
-    description: "Execute a shell command in the shared workspace environment.",
-    execute: executeBash,
-    inputSchema: BASH_INPUT_SCHEMA,
-    logicalPath: "ash:framework/bash",
-    name: "bash",
-    sourceId: "ash:bash-tool",
-    sourceKind: "module",
-};
+import{executeBashOnSandbox}from"#execution/sandbox/bash-tool.js";var BASH_INPUT_SCHEMA={additionalProperties:!1,properties:{command:{description:`The shell command to execute.`,type:`string`}},required:[`command`],type:`object`};async function executeBash(e){return executeBashOnSandbox(e)}var BASH_TOOL_DEFINITION={description:`Execute a shell command in the shared workspace environment.`,execute:executeBash,inputSchema:BASH_INPUT_SCHEMA,logicalPath:`ash:framework/bash`,name:`bash`,sourceId:`ash:bash-tool`,sourceKind:`module`};export{BASH_INPUT_SCHEMA,BASH_TOOL_DEFINITION};

package/dist/src/runtime/framework-tools/connection-search.js

@@ -1,224 +1 @@
-import { loadContext } from "#context/container.js";
-import { ContextKey } from "#context/key.js";
-import { createLogger } from "#internal/logging.js";
-import { isConnectionAuthorizationFailedError, isConnectionAuthorizationRequiredError, } from "#public/connections/errors.js";
-import { supportsInteractiveAuthorization, } from "#runtime/connections/types.js";
-import { qualifiedConnectionToolName } from "#runtime/framework-tools/connection-tools.js";
-import { appendPendingConnectionToolCalls, CONNECTION_AUTHORIZATION_PLACEHOLDER, PendingConnectionToolCallsKey, } from "#runtime/framework-tools/pending-connection-tool-calls.js";
-const logger = createLogger("framework.connection-search");
-/**
- * Context key for the per-session connection registry.
- *
- * Created as a derived key (no codec) because the registry holds live
- * client instances that cannot be serialized across step boundaries.
- * The `connectionProvider` reconstructs it each step.
- */
-export const ConnectionRegistryKey = new ContextKey("ash.connectionRegistry");
-/**
- * Durable context key for discovered connection tools.
- *
- * Written by `connection_search` after fetching tool metadata.
- * Read by `resolveDiscoveredConnectionTools` at the start of each
- * step to inject discovered tools into the ToolSet.
- */
-export const DiscoveredConnectionToolsKey = new ContextKey("ash.discoveredConnectionTools");
-/**
- * Framework-provided `connection_search` tool.
- */
-export const CONNECTION_SEARCH_TOOL_DEFINITION = {
-    description: "Search for tools across your connections. " +
-        "Discovered tools become directly callable by their qualified name " +
-        "(e.g. linear__list_issues) in your next response.",
-    execute: async (input, options) => {
-        const toolCallId = typeof options === "object" && options !== null && "toolCallId" in options
-            ? options.toolCallId
-            : undefined;
-        return executeConnectionSearch(input, {
-            toolCallId: typeof toolCallId === "string" ? toolCallId : undefined,
-        });
-    },
-    inputSchema: {
-        additionalProperties: false,
-        properties: {
-            connection: {
-                description: "Optional: limit search to a specific connection name.",
-                type: "string",
-            },
-            limit: {
-                description: "Max results to return. Default 10.",
-                type: "number",
-            },
-            keywords: {
-                description: "Search keywords and expanded aliases. Distill intent into keywords; avoid stop words like 'a', 'the', 'in'.",
-                type: "string",
-            },
-        },
-        required: ["keywords"],
-        type: "object",
-    },
-    logicalPath: "ash:framework/connection-search",
-    name: "connection_search",
-    onCompact({ ctx }) {
-        ctx.set(DiscoveredConnectionToolsKey, { byConnection: {} });
-        ctx.set(PendingConnectionToolCallsKey, []);
-        return {};
-    },
-    sourceId: "ash:connection-search-tool",
-    sourceKind: "module",
-};
-export async function executeConnectionSearch(input, meta) {
-    const ctx = loadContext();
-    const registry = ctx.get(ConnectionRegistryKey);
-    if (registry === undefined) {
-        return [];
-    }
-    const limit = input.limit ?? 10;
-    const queryTokens = tokenize(input.keywords);
-    const results = [];
-    const failedConnections = [];
-    const targetConnections = input.connection !== undefined && input.connection !== ""
-        ? registry.getConnections().filter((c) => c.connectionName === input.connection)
-        : registry.getConnections();
-    // Merge any previously discovered tools so we accumulate across
-    // multiple search calls rather than replacing.
-    const previouslyDiscovered = ctx.get(DiscoveredConnectionToolsKey);
-    const discoveredByConnection = {
-        ...previouslyDiscovered?.byConnection,
-    };
-    const authRequiredConnections = [];
-    for (const conn of targetConnections) {
-        let tools;
-        try {
-            const client = registry.getClient(conn.connectionName);
-            tools = await client.getToolMetadata();
-        }
-        catch (err) {
-            if (isConnectionAuthorizationRequiredError(err)) {
-                authRequiredConnections.push(conn.connectionName);
-                failedConnections.push({
-                    connection: conn.connectionName,
-                    description: conn.description,
-                    needsAuthorization: true,
-                });
-                continue;
-            }
-            if (isConnectionAuthorizationFailedError(err)) {
-                logger.warn("connection authorization failed", {
-                    connection: conn.connectionName,
-                    reason: err.reason,
-                    retryable: err.retryable,
-                    error: err,
-                });
-                failedConnections.push({
-                    connection: conn.connectionName,
-                    description: conn.description,
-                    error: `Authorization failed for ${conn.connectionName}: ${err.message}`,
-                });
-                continue;
-            }
-            // Anything that isn't `Required` or `Failed` is unclassified —
-            // most often a misconfiguration on the upstream provider (e.g. an
-            // OAuth bridge returning a 4xx for a project that hasn't been
-            // linked) rather than the connection's HTTP server being
-            // unreachable. Log so the developer running `ash dev` sees the
-            // underlying cause; the model only gets the truncated message.
-            const message = err instanceof Error ? err.message : "unknown error";
-            logger.warn("failed to load connection tools", {
-                connection: conn.connectionName,
-                error: err instanceof Error ? err : new Error(message),
-            });
-            failedConnections.push({
-                connection: conn.connectionName,
-                description: conn.description,
-                error: `Failed to load tools for "${conn.connectionName}": ${message}`,
-            });
-            continue;
-        }
-        // Record all tools from this connection as discovered.
-        discoveredByConnection[conn.connectionName] = tools;
-        for (const tool of tools) {
-            const score = scoreMatch(queryTokens, tool);
-            if (score > 0) {
-                results.push({
-                    item: {
-                        connection: conn.connectionName,
-                        description: tool.description,
-                        inputSchema: tool.inputSchema,
-                        qualifiedName: qualifiedConnectionToolName(conn.connectionName, tool.name),
-                        tool: tool.name,
-                    },
-                    score,
-                });
-            }
-        }
-    }
-    // Persist discovered tools so they materialize as first-class
-    // AI SDK tools on the next step.
-    ctx.set(DiscoveredConnectionToolsKey, { byConnection: discoveredByConnection });
-    const interactiveConnectionNames = authRequiredConnections.filter((name) => isInteractive(registry, name));
-    // Suspend the entire tool call when at least one auth-required
-    // connection has the full interactive-OAuth surface. The
-    // connection-discover retry re-runs this search after tokens land,
-    // and its result is spliced over the placeholder in history. See
-    // packages/ash/src/runtime/framework-tools/pending-connection-tool-calls.ts.
-    if (interactiveConnectionNames.length > 0 && meta?.toolCallId !== undefined) {
-        const existing = ctx.get(PendingConnectionToolCallsKey);
-        ctx.set(PendingConnectionToolCallsKey, appendPendingConnectionToolCalls(existing, [
-            {
-                args: input,
-                connectionNames: interactiveConnectionNames,
-                kind: "connection-discover",
-                toolCallId: meta.toolCallId,
-                toolName: "connection_search",
-            },
-        ]));
-        return CONNECTION_AUTHORIZATION_PLACEHOLDER;
-    }
-    results.sort((a, b) => b.score - a.score);
-    const matched = results.slice(0, limit).map((r) => r.item);
-    if (matched.length > 0) {
-        return [...matched, ...failedConnections];
-    }
-    // No keyword matches — return connection summaries so the model
-    // knows which connections exist even when the query is vague.
-    const summaries = targetConnections.map((c) => {
-        const failed = failedConnections.find((f) => f.connection === c.connectionName);
-        if (failed)
-            return failed;
-        return {
-            connection: c.connectionName,
-            description: c.description,
-        };
-    });
-    return summaries;
-}
-export function tokenize(text) {
-    return text
-        .toLowerCase()
-        .split(/[\s_\-./]+/)
-        .filter((t) => t.length > 1);
-}
-export function scoreMatch(queryTokens, tool) {
-    const nameTokens = tokenize(tool.name);
-    const descTokens = tokenize(tool.description);
-    let score = 0;
-    for (const qt of queryTokens) {
-        for (const nt of nameTokens) {
-            if (nt.includes(qt) || qt.includes(nt)) {
-                score += 3;
-            }
-        }
-        for (const dt of descTokens) {
-            if (dt.includes(qt) || qt.includes(dt)) {
-                score += 1;
-            }
-        }
-    }
-    return score;
-}
-function isInteractive(registry, connectionName) {
-    if (registry === undefined)
-        return false;
-    const def = registry.getConnections().find((c) => c.connectionName === connectionName);
-    return supportsInteractiveAuthorization(def?.authorization);
-}
+import{createLogger}from"#internal/logging.js";import{loadContext}from"#context/container.js";import{ContextKey}from"#context/key.js";import{CONNECTION_AUTHORIZATION_PLACEHOLDER,PendingConnectionToolCallsKey,appendPendingConnectionToolCalls}from"#runtime/framework-tools/pending-connection-tool-calls.js";import{isConnectionAuthorizationFailedError,isConnectionAuthorizationRequiredError}from"#public/connections/errors.js";import{qualifiedConnectionToolName}from"#runtime/framework-tools/connection-tools.js";import{supportsInteractiveAuthorization}from"#runtime/connections/types.js";var logger=createLogger(`framework.connection-search`),ConnectionRegistryKey=new ContextKey(`ash.connectionRegistry`),DiscoveredConnectionToolsKey=new ContextKey(`ash.discoveredConnectionTools`),CONNECTION_SEARCH_TOOL_DEFINITION={description:`Search for tools across your connections. Discovered tools become directly callable by their qualified name (e.g. linear__list_issues) in your next response.`,execute:async(e,t)=>{let n=typeof t==`object`&&t&&`toolCallId`in t?t.toolCallId:void 0;return executeConnectionSearch(e,{toolCallId:typeof n==`string`?n:void 0})},inputSchema:{additionalProperties:!1,properties:{connection:{description:`Optional: limit search to a specific connection name.`,type:`string`},limit:{description:`Max results to return. Default 10.`,type:`number`},keywords:{description:`Search keywords and expanded aliases. Distill intent into keywords; avoid stop words like 'a', 'the', 'in'.`,type:`string`}},required:[`keywords`],type:`object`},logicalPath:`ash:framework/connection-search`,name:`connection_search`,onCompact({ctx:e}){return e.set(DiscoveredConnectionToolsKey,{byConnection:{}}),e.set(PendingConnectionToolCallsKey,[]),{}},sourceId:`ash:connection-search-tool`,sourceKind:`module`};async function executeConnectionSearch(e,n){let a=loadContext(),o=a.get(ConnectionRegistryKey);if(o===void 0)return[];let s=e.limit??10,c=tokenize(e.keywords),l=[],u=[],d=e.connection!==void 0&&e.connection!==``?o.getConnections().filter(t=>t.connectionName===e.connection):o.getConnections(),f={...a.get(DiscoveredConnectionToolsKey)?.byConnection},p=[];for(let e of d){let t;try{t=await o.getClient(e.connectionName).getToolMetadata()}catch(t){if(isConnectionAuthorizationRequiredError(t)){p.push(e.connectionName),u.push({connection:e.connectionName,description:e.description,needsAuthorization:!0});continue}if(isConnectionAuthorizationFailedError(t)){logger.warn(`connection authorization failed`,{connection:e.connectionName,reason:t.reason,retryable:t.retryable,error:t}),u.push({connection:e.connectionName,description:e.description,error:`Authorization failed for ${e.connectionName}: ${t.message}`});continue}let n=t instanceof Error?t.message:`unknown error`;logger.warn(`failed to load connection tools`,{connection:e.connectionName,error:t instanceof Error?t:Error(n)}),u.push({connection:e.connectionName,description:e.description,error:`Failed to load tools for "${e.connectionName}": ${n}`});continue}f[e.connectionName]=t;for(let n of t){let t=scoreMatch(c,n);t>0&&l.push({item:{connection:e.connectionName,description:n.description,inputSchema:n.inputSchema,qualifiedName:qualifiedConnectionToolName(e.connectionName,n.name),tool:n.name},score:t})}}a.set(DiscoveredConnectionToolsKey,{byConnection:f});let m=p.filter(e=>isInteractive(o,e));if(m.length>0&&n?.toolCallId!==void 0){let t=a.get(PendingConnectionToolCallsKey);return a.set(PendingConnectionToolCallsKey,appendPendingConnectionToolCalls(t,[{args:e,connectionNames:m,kind:`connection-discover`,toolCallId:n.toolCallId,toolName:`connection_search`}])),CONNECTION_AUTHORIZATION_PLACEHOLDER}l.sort((e,t)=>t.score-e.score);let h=l.slice(0,s).map(e=>e.item);return h.length>0?[...h,...u]:d.map(e=>u.find(t=>t.connection===e.connectionName)||{connection:e.connectionName,description:e.description})}function tokenize(e){return e.toLowerCase().split(/[\s_\-./]+/).filter(e=>e.length>1)}function scoreMatch(e,t){let n=tokenize(t.name),r=tokenize(t.description),i=0;for(let t of e){for(let e of n)(e.includes(t)||t.includes(e))&&(i+=3);for(let e of r)(e.includes(t)||t.includes(e))&&(i+=1)}return i}function isInteractive(e,t){return e===void 0?!1:supportsInteractiveAuthorization(e.getConnections().find(e=>e.connectionName===t)?.authorization)}export{CONNECTION_SEARCH_TOOL_DEFINITION,ConnectionRegistryKey,DiscoveredConnectionToolsKey,executeConnectionSearch,scoreMatch,tokenize};