npm - experimental-ash - Versions diffs - 0.26.0 → 0.28.0 - Mend

experimental-ash 0.26.0 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (787) hide show

package/dist/src/runtime/connections/authorization-complete-page.js CHANGED Viewed

@@ -1,15 +1,4 @@
-/**
- * Renders the static HTML landing page that the user's browser sees
- * after an OAuth IdP redirects back to the framework's connection
- * callback route.
- *
- * The framework would otherwise respond with an empty `202 Accepted`
- * body, which looks broken. This helper is intentionally self-contained:
- * no external assets, no script, so it renders identically regardless
- * of where the runtime serves the callback from.
- */
-export function buildAuthorizationCompletePage() {
-    const html = `<!doctype html>
+function buildAuthorizationCompletePage(){return new Response(`<!doctype html>
 <html lang="en">
   <head>
     <meta charset="utf-8" />
@@ -61,12 +50,4 @@ export function buildAuthorizationCompletePage() {
       <p>You can close this tab and return to your app.</p>
     </main>
   </body>
-</html>`;
-    return new Response(html, {
-        headers: {
-            "cache-control": "no-store",
-            "content-type": "text/html; charset=utf-8",
-        },
-        status: 200,
-    });
-}
+</html>`,{headers:{"cache-control":`no-store`,"content-type":`text/html; charset=utf-8`},status:200})}export{buildAuthorizationCompletePage};

package/dist/src/runtime/connections/authorization-tokens.js CHANGED Viewed

@@ -1,66 +1 @@
-/**
- * Per-step cache of resolved connection authorization tokens.
- *
- * Keyed by `(connectionName, principalKey)` so two users on the same
- * session never share a user-scoped token. Stored as a virtual
- * context value and wiped between workflow steps, so bearer tokens
- * are never serialized into the durable step payload. Cross-step
- * reuse is delegated to the upstream authorization provider (for
- * example Connect's server-side cache), which owns the refresh grant.
- *
- * TODO(ash): once a server-derivable session key is available, promote
- * this back to durable context via an AEAD codec so cross-step reuse
- * is possible without exposing plaintext bearers in the WDK payload.
- */
-import { ContextKey } from "#context/key.js";
-/**
- * Virtual context key mapping connection name to a per-principal
- * {@link TokenResult} cache.
- *
- * The principal sub-key is produced by
- * {@link principalKey} so identical string keys (for example
- * `"user:${issuer}:${id}"`) collide only when the resolved principal
- * genuinely matches.
- */
-export const ConnectionAuthorizationTokensKey = new ContextKey("ash.connectionAuthorizationTokens");
-/**
- * Returns the cached {@link TokenResult} for
- * `(connectionName, principalKey)` when the entry is still valid
- * (not expired). Expired entries are treated as a cache miss so
- * callers re-run the authorization flow.
- */
-export function readCachedToken(ctx, connectionName, principalKey) {
-    const entry = ctx.get(ConnectionAuthorizationTokensKey)?.[connectionName]?.[principalKey];
-    if (entry === undefined)
-        return undefined;
-    if (entry.expiresAt !== undefined && entry.expiresAt <= Date.now()) {
-        return undefined;
-    }
-    return entry;
-}
-/**
- * Persists a freshly resolved {@link TokenResult} on the cache under
- * `(connectionName, principalKey)`. Existing entries for other
- * principals on the same connection are left in place.
- *
- * Writes to the virtual context slot so the bearer is never serialized
- * into the durable step payload. See the module docblock.
- */
-export function writeCachedToken(ctx, connectionName, principalKey, token) {
-    const existing = ctx.get(ConnectionAuthorizationTokensKey) ?? {};
-    const perConnection = existing[connectionName] ?? {};
-    asContainer(ctx).setVirtualContext(ConnectionAuthorizationTokensKey, {
-        ...existing,
-        [connectionName]: { ...perConnection, [principalKey]: token },
-    });
-}
-/**
- * Runtime installs `ContextContainer` as the concrete `AshContext`;
- * we reach through the interface here because `setVirtualContext` is
- * intentionally runtime-only and not exposed on the public
- * {@link AshContext} surface. Mirrors the pattern in
- * `principal-context.ts`.
- */
-function asContainer(ctx) {
-    return ctx;
-}
+import{ContextKey}from"#context/key.js";var ConnectionAuthorizationTokensKey=new ContextKey(`ash.connectionAuthorizationTokens`);function readCachedToken(e,t,n){let r=e.get(ConnectionAuthorizationTokensKey)?.[t]?.[n];if(r!==void 0&&!(r.expiresAt!==void 0&&r.expiresAt<=Date.now()))return r}function writeCachedToken(e,t,n,r){let i=e.get(ConnectionAuthorizationTokensKey)??{},a=i[t]??{};asContainer(e).setVirtualContext(ConnectionAuthorizationTokensKey,{...i,[t]:{...a,[n]:r}})}function asContainer(e){return e}export{ConnectionAuthorizationTokensKey,readCachedToken,writeCachedToken};

package/dist/src/runtime/connections/callback-route.js CHANGED Viewed

@@ -1,139 +1 @@
-/**
- * Framework-shipped callback route used by in-turn interactive
- * connection authorization.
- *
- * The route at {@link ASH_CONNECTION_CALLBACK_ROUTE_PATTERN} is the
- * redirect target the workflow body hands to the IdP via
- * `startAuthorization`. When the IdP redirects the user's browser back
- * with the OAuth `code`/`state` (or whatever payload the protocol
- * carries), this handler:
- *
- * 1. Projects the inbound request into a JSON-serializable
- *    {@link AuthorizationCallbackRequest} (the same shape
- *    `completeAuthorization` already accepts).
- * 2. Calls `resumeHook(token, payload)` to wake the suspended workflow.
- * 3. Renders the standard "Authorization complete" landing page so the
- *    user sees a friendly UI instead of an empty `202 Accepted`.
- *
- * Owning this route in the framework - instead of routing the IdP at the
- * workflow runtime's raw `/.well-known/workflow/v1/webhook/:token` -
- * keeps the public surface namespaced under Ash and lets the framework
- * decide delivery policy (auth, throttling, logging) for connection
- * callbacks without leaking generic workflow primitives to the public
- * internet.
- */
-import { resumeHook } from "#compiled/@workflow/core/runtime.js";
-import { ASH_CONNECTION_CALLBACK_ROUTE_PATTERN } from "#protocol/routes.js";
-import { buildAuthorizationCompletePage } from "#runtime/connections/authorization-complete-page.js";
-/**
- * Logical name prefix of the framework-shipped connection callback
- * channel. The trailing method segment (`get` or `post`) keeps each
- * `(method, urlPath)` pair distinct in the channel registry.
- */
-export const HTTP_CONNECTION_CALLBACK_CHANNEL_NAME_PREFIX = "ash/v1/connections/callback";
-/**
- * HTTP methods accepted by the connection callback route.
- *
- * Most OAuth IdPs redirect back over `GET` (authorization code in the
- * query string). Some `form_post` response modes deliver the callback
- * over `POST` instead, so the framework registers both. Both
- * methods route through the same handler.
- */
-const HANDLED_METHODS = ["GET", "POST"];
-/**
- * Returns the framework-shipped channel definitions that mount the
- * connection callback route at {@link ASH_CONNECTION_CALLBACK_ROUTE_PATTERN}.
- *
- * Returns one definition per accepted HTTP method (see
- * {@link HANDLED_METHODS}). The framework channel resolver mounts each
- * `(method, urlPath)` pair as a separate Nitro route; sharing one URL
- * pattern across multiple methods is not supported by the channel
- * model.
- */
-export function getConnectionCallbackChannelDefinitions() {
-    return HANDLED_METHODS.map((method) => buildCallbackChannelDefinition(method));
-}
-/**
- * Returns the set of logical channel names registered by the connection
- * callback route. Used by `getAllFrameworkChannelNames` so authors who
- * `disableRoute()` one of these names get a useful diagnostic instead
- * of a silent no-op.
- */
-export function getConnectionCallbackChannelNames() {
-    return new Set(HANDLED_METHODS.map(channelNameForMethod));
-}
-function buildCallbackChannelDefinition(method) {
-    const name = channelNameForMethod(method);
-    return {
-        name,
-        method,
-        urlPath: ASH_CONNECTION_CALLBACK_ROUTE_PATTERN,
-        fetch: handleConnectionCallbackRequest,
-        logicalPath: `framework://channels/${name}`,
-        sourceId: `ash:framework:connection-callback-${method.toLowerCase()}`,
-        sourceKind: "module",
-    };
-}
-function channelNameForMethod(method) {
-    return `${HTTP_CONNECTION_CALLBACK_CHANNEL_NAME_PREFIX}/${method.toLowerCase()}`;
-}
-/**
- * Inbound handler for the connection callback route. Exported for test
- * coverage; the framework channel resolver wires it into Nitro via
- * {@link getConnectionCallbackChannelDefinitions}.
- */
-export async function handleConnectionCallbackRequest(request, ctx) {
-    const name = ctx.params.name;
-    const token = ctx.params.token;
-    if (typeof name !== "string" || name.length === 0) {
-        return Response.json({ error: "Missing connection name.", ok: false }, { status: 400 });
-    }
-    if (typeof token !== "string" || token.length === 0) {
-        return Response.json({ error: "Missing callback token.", ok: false }, { status: 400 });
-    }
-    // `resumeHook` consumes the body if we hand it the live `Request`,
-    // so project the request into the JSON-serializable shape that
-    // matches what `completeAuthorization` expects.
-    const callback = await projectAuthorizationCallback(request);
-    try {
-        await resumeHook(token, callback);
-    }
-    catch {
-        // The most likely failure here is "no hook is currently registered
-        // for this token", e.g. the workflow already completed,
-        // disposed the hook, or the user replayed an expired callback URL.
-        // Surface a 404 rather than a 500 so IdP-side retries don't loop
-        // and operator dashboards don't page on a benign "user clicked
-        // stale link" event.
-        return Response.json({ error: "Connection callback not pending.", ok: false }, { status: 404 });
-    }
-    return buildAuthorizationCompletePage();
-}
-/**
- * Projects the live callback `Request` into the JSON-serializable
- * {@link AuthorizationCallbackRequest} shape used as the hook payload.
- * Body text is captured for non-GET/HEAD methods; reading the body here
- * consumes it on the source request, but the framework no longer reads
- * the request after dispatching to `resumeHook`.
- */
-async function projectAuthorizationCallback(request) {
-    const headers = {};
-    request.headers.forEach((value, key) => {
-        headers[key] = value;
-    });
-    let body = "";
-    if (request.method !== "GET" && request.method !== "HEAD") {
-        try {
-            body = await request.text();
-        }
-        catch {
-            body = "";
-        }
-    }
-    return {
-        body,
-        headers,
-        method: request.method,
-        url: request.url,
-    };
-}
+import{ASH_CONNECTION_CALLBACK_ROUTE_PATTERN}from"#protocol/routes.js";import{resumeHook}from"#compiled/@workflow/core/runtime.js";import{buildAuthorizationCompletePage}from"#runtime/connections/authorization-complete-page.js";var HTTP_CONNECTION_CALLBACK_CHANNEL_NAME_PREFIX=`ash/v1/connections/callback`,HANDLED_METHODS=[`GET`,`POST`];function getConnectionCallbackChannelDefinitions(){return HANDLED_METHODS.map(e=>buildCallbackChannelDefinition(e))}function getConnectionCallbackChannelNames(){return new Set(HANDLED_METHODS.map(channelNameForMethod))}function buildCallbackChannelDefinition(t){let n=channelNameForMethod(t);return{name:n,method:t,urlPath:ASH_CONNECTION_CALLBACK_ROUTE_PATTERN,fetch:handleConnectionCallbackRequest,logicalPath:`framework://channels/${n}`,sourceId:`ash:framework:connection-callback-${t.toLowerCase()}`,sourceKind:`module`}}function channelNameForMethod(e){return`${HTTP_CONNECTION_CALLBACK_CHANNEL_NAME_PREFIX}/${e.toLowerCase()}`}async function handleConnectionCallbackRequest(e,r){let i=r.params.name,a=r.params.token;if(typeof i!=`string`||i.length===0)return Response.json({error:`Missing connection name.`,ok:!1},{status:400});if(typeof a!=`string`||a.length===0)return Response.json({error:`Missing callback token.`,ok:!1},{status:400});let o=await projectAuthorizationCallback(e);try{await resumeHook(a,o)}catch{return Response.json({error:`Connection callback not pending.`,ok:!1},{status:404})}return buildAuthorizationCompletePage()}async function projectAuthorizationCallback(e){let t={};e.headers.forEach((e,n)=>{t[n]=e});let n=``;if(e.method!==`GET`&&e.method!==`HEAD`)try{n=await e.text()}catch{n=``}return{body:n,headers:t,method:e.method,url:e.url}}export{HTTP_CONNECTION_CALLBACK_CHANNEL_NAME_PREFIX,getConnectionCallbackChannelDefinitions,getConnectionCallbackChannelNames,handleConnectionCallbackRequest};

package/dist/src/runtime/connections/mcp-client.js CHANGED Viewed

@@ -1,307 +1 @@
-import { createMCPClient } from "#compiled/@ai-sdk/mcp/index.js";
-import { contextStorage } from "#context/container.js";
-import { readCachedToken, writeCachedToken } from "#runtime/connections/authorization-tokens.js";
-import { principalKey, resolveConnectionPrincipal } from "#runtime/connections/principal.js";
-import { isObject } from "#shared/guards.js";
-/**
- * Wraps one `MCPClient` from `@ai-sdk/mcp` for a single connection.
- *
- * Created lazily per-connection per-session. Caches tool metadata after
- * the first `getToolMetadata()` call.
- */
-export class McpConnectionClient {
-    #clientPromise;
-    #client;
-    #toolsPromise;
-    #tools;
-    #connection;
-    constructor(connection) {
-        this.#connection = connection;
-    }
-    /**
-     * Connects to the MCP server, trying Streamable HTTP first and
-     * falling back to SSE for transport-compatibility failures.
-     *
-     * Concurrent callers share the same connection promise to avoid
-     * duplicate connections.
-     */
-    async connect() {
-        if (this.#client !== undefined) {
-            return this.#client;
-        }
-        if (this.#clientPromise !== undefined) {
-            return this.#clientPromise;
-        }
-        this.#clientPromise = this.#createClient();
-        try {
-            this.#client = await this.#clientPromise;
-            return this.#client;
-        }
-        catch (error) {
-            this.#clientPromise = undefined;
-            throw error;
-        }
-    }
-    async #createClient() {
-        const headers = await resolveHeaders(this.#connection);
-        const url = this.#connection.url;
-        try {
-            return await createMCPClient({
-                transport: { type: "http", url, headers },
-            });
-        }
-        catch (error) {
-            if (!isMcpHttpFallbackRetryableError(error)) {
-                throw error;
-            }
-            return await createMCPClient({
-                transport: { type: "sse", url, headers },
-            });
-        }
-    }
-    /**
-     * Returns cached tool metadata for all tools this connection exposes,
-     * after applying any configured tool filter.
-     *
-     * The first call fetches tools from the server via `listTools()` and
-     * creates the AI SDK tool set in parallel. Subsequent calls return
-     * the cached result. Concurrent callers share the same in-flight
-     * promise.
-     */
-    async getToolMetadata() {
-        const cache = await this.#ensureTools();
-        return cache.metadata;
-    }
-    /**
-     * Returns the AI SDK `ToolSet` produced by `@ai-sdk/mcp`'s
-     * `toolsFromDefinitions()`. Each entry is a full SDK `Tool` with
-     * `inputSchema`, `description`, and `execute` already set.
-     */
-    async getTools() {
-        const cache = await this.#ensureTools();
-        return cache.tools;
-    }
-    /**
-     * Executes a named tool through the AI SDK's tool executor, which
-     * handles the JSON-RPC `tools/call` internally.
-     */
-    async executeTool(toolName, args) {
-        const { tools } = await this.#ensureTools();
-        const sdkTool = tools[toolName];
-        if (sdkTool?.execute === undefined) {
-            throw new Error(`Tool "${toolName}" not found in connection "${this.#connection.connectionName}".`);
-        }
-        return sdkTool.execute(args, {});
-    }
-    async #ensureTools() {
-        if (this.#tools !== undefined) {
-            return this.#tools;
-        }
-        if (this.#toolsPromise !== undefined) {
-            return this.#toolsPromise;
-        }
-        this.#toolsPromise = this.#fetchTools();
-        try {
-            this.#tools = await this.#toolsPromise;
-            return this.#tools;
-        }
-        catch (error) {
-            this.#toolsPromise = undefined;
-            throw error;
-        }
-    }
-    async #fetchTools() {
-        const client = await this.connect();
-        const listResult = await client.listTools();
-        const filter = this.#connection.tools;
-        const filteredTools = filter !== undefined
-            ? listResult.tools.filter((t) => passesToolFilter(t.name, filter))
-            : listResult.tools;
-        // `toolsFromDefinitions` returns `McpToolSet<"automatic">`, whose
-        // elements are `Tool<unknown, CallToolResult>`. The AI SDK's
-        // `ToolSet` constraint only admits `Tool<any | never, any | never>`,
-        // so a single-hop cast is required — the runtime shape is identical.
-        const tools = client.toolsFromDefinitions({ tools: filteredTools });
-        const metadata = filteredTools.map((t) => ({
-            annotations: t.annotations,
-            description: t.description ?? "",
-            inputSchema: (t.inputSchema ?? {}),
-            name: t.name,
-        }));
-        return { metadata, tools };
-    }
-    async close() {
-        if (this.#client !== undefined) {
-            await this.#client.close();
-            this.#client = undefined;
-        }
-        this.#clientPromise = undefined;
-        this.#toolsPromise = undefined;
-        this.#tools = undefined;
-    }
-}
-/**
- * Decides whether an error thrown while creating a streamable HTTP MCP
- * client should trigger a fallback attempt against the legacy SSE
- * transport.
- *
- * Per the MCP backwards-compatibility rules, clients should fall back
- * to SSE when the streamable HTTP probe returns `400 Bad Request`,
- * `404 Not Found`, or `405 Method Not Allowed`. All other failures
- * (auth errors, network errors, server errors) should propagate so the
- * caller sees the real problem instead of a misleading SSE failure.
- *
- * See: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#backwards-compatibility
- */
-function isMcpHttpFallbackRetryableError(error) {
-    const status = readHttpStatus(error);
-    return status === 400 || status === 404 || status === 405;
-}
-function readHttpStatus(error) {
-    for (const candidate of walkErrorChain(error)) {
-        if (!isObject(candidate)) {
-            continue;
-        }
-        const status = readStatusField(candidate);
-        if (status !== undefined) {
-            return status;
-        }
-        const response = candidate.response;
-        if (isObject(response)) {
-            const responseStatus = readStatusField(response);
-            if (responseStatus !== undefined) {
-                return responseStatus;
-            }
-        }
-        if (typeof candidate.message === "string") {
-            const match = /\bHTTP\s+(\d{3})\b/u.exec(candidate.message);
-            if (match?.[1] !== undefined) {
-                return Number(match[1]);
-            }
-        }
-    }
-    return undefined;
-}
-function readStatusField(value) {
-    if (typeof value.status === "number") {
-        return value.status;
-    }
-    if (typeof value.statusCode === "number") {
-        return value.statusCode;
-    }
-    return undefined;
-}
-function* walkErrorChain(error) {
-    let current = error;
-    const seen = new Set();
-    while (current !== undefined && current !== null && !seen.has(current)) {
-        seen.add(current);
-        yield current;
-        if (!isObject(current) || !("cause" in current)) {
-            return;
-        }
-        current = current.cause;
-    }
-}
-/**
- * Returns `true` when a tool name passes the configured filter.
- */
-export function passesToolFilter(toolName, filter) {
-    if (filter === undefined) {
-        return true;
-    }
-    if ("allow" in filter) {
-        return filter.allow.includes(toolName);
-    }
-    return !filter.block.includes(toolName);
-}
-/**
- * Merges `authorization` (Bearer token) and `headers` into one
- * flat `Record<string, string>` for the transport layer.
- *
- * Resolves the {@link ConnectionPrincipal} from the active session
- * (or an orchestrator-installed override) and invokes
- * `authorization.getToken({ principal })` to produce the bearer.
- * `getToken` may throw {@link ConnectionAuthorizationRequiredError};
- * callers (`connection_search`, wrapped connection tools) catch it
- * and it propagates as-is from here.
- */
-export async function resolveHeaders(connection) {
-    const merged = {};
-    if (connection.authorization !== undefined) {
-        const result = await resolveToken(connection);
-        merged.Authorization = `Bearer ${result.token}`;
-    }
-    if (connection.headers !== undefined) {
-        const resolved = await resolveHeadersDefinition(connection.headers);
-        for (const [key, value] of Object.entries(resolved)) {
-            if (connection.authorization !== undefined && key.toLowerCase() === "authorization") {
-                throw new Error(`Connection "${connection.connectionName}" headers must not include an "Authorization" key when "authorization" is also provided.`);
-            }
-            merged[key] = value;
-        }
-    }
-    return merged;
-}
-/**
- * Resolves a connection's bearer token, consulting the per-session
- * authorization-token cache before invoking the authored `getToken`.
- *
- * Returning a cached token lets interactive-OAuth flows that have
- * completed their webhook dance stay authorized for the rest of the
- * session without re-hitting the IdP (whose initial `getToken` would
- * still throw `Required` until the grant propagates).
- *
- * The cache is keyed by `(connectionName, principalKey(principal))`
- * so concurrent users on one session never alias onto each other's
- * bearer. Principal resolution is delegated to
- * {@link resolveConnectionPrincipal}, which is the single source of
- * truth for the "app vs user, override vs session, context vs no
- * context" decision tree. Outside a runtime scope the cache is
- * unavailable, but `getToken` still runs with a framework-resolved
- * principal so ad-hoc CLI and unit-test use of `"app"`-typed
- * connections keeps working; `"user"`-typed connections without a
- * context fail fast with `reason: "principal_required"`.
- */
-async function resolveToken(connection) {
-    if (connection.authorization === undefined) {
-        throw new Error(`Connection "${connection.connectionName}" does not define authorization.`);
-    }
-    // Reading `contextStorage.getStore()` directly keeps this the only
-    // place in the runtime that tolerates a missing context; authored
-    // code must use `loadContext()` so misuse fails loudly.
-    const ctx = contextStorage.getStore();
-    const principal = resolveConnectionPrincipal(connection.connectionName, connection.authorization, ctx);
-    const authContext = { url: connection.url };
-    if (ctx === undefined) {
-        // No context → no per-session cache. Still invoke the authored
-        // `getToken` so `"app"`-typed connections resolve normally for
-        // ad-hoc use; `"user"`-typed connections will already have
-        // thrown above inside `resolveConnectionPrincipal`.
-        return await connection.authorization.getToken({ principal, connection: authContext });
-    }
-    const key = principalKey(principal);
-    const cached = readCachedToken(ctx, connection.connectionName, key);
-    if (cached !== undefined)
-        return cached;
-    const result = await connection.authorization.getToken({ principal, connection: authContext });
-    writeCachedToken(ctx, connection.connectionName, key, result);
-    return result;
-}
-async function resolveHeadersDefinition(headers) {
-    if (typeof headers === "function") {
-        return await headers();
-    }
-    const result = {};
-    const entries = Object.entries(headers);
-    for (const [key, value] of entries) {
-        result[key] = await resolveHeaderValue(value);
-    }
-    return result;
-}
-async function resolveHeaderValue(value) {
-    if (typeof value === "function") {
-        return await value();
-    }
-    return await value;
-}
+import{isObject}from"#shared/guards.js";import{contextStorage}from"#context/container.js";import{readCachedToken,writeCachedToken}from"#runtime/connections/authorization-tokens.js";import{principalKey,resolveConnectionPrincipal}from"#runtime/connections/principal.js";import{createMCPClient}from"#compiled/@ai-sdk/mcp/index.js";var McpConnectionClient=class{#e;#t;#n;#r;#i;constructor(e){this.#i=e}async connect(){if(this.#t!==void 0)return this.#t;if(this.#e!==void 0)return this.#e;this.#e=this.#a();try{return this.#t=await this.#e,this.#t}catch(e){throw this.#e=void 0,e}}async#a(){let e=await resolveHeaders(this.#i),t=this.#i.url;try{return await createMCPClient({transport:{type:`http`,url:t,headers:e}})}catch(n){if(!isMcpHttpFallbackRetryableError(n))throw n;return await createMCPClient({transport:{type:`sse`,url:t,headers:e}})}}async getToolMetadata(){return(await this.#o()).metadata}async getTools(){return(await this.#o()).tools}async executeTool(e,t){let{tools:n}=await this.#o(),r=n[e];if(r?.execute===void 0)throw Error(`Tool "${e}" not found in connection "${this.#i.connectionName}".`);return r.execute(t,{})}async#o(){if(this.#r!==void 0)return this.#r;if(this.#n!==void 0)return this.#n;this.#n=this.#s();try{return this.#r=await this.#n,this.#r}catch(e){throw this.#n=void 0,e}}async#s(){let e=await this.connect(),t=await e.listTools(),n=this.#i.tools,r=n===void 0?t.tools:t.tools.filter(e=>passesToolFilter(e.name,n)),i=e.toolsFromDefinitions({tools:r});return{metadata:r.map(e=>({annotations:e.annotations,description:e.description??``,inputSchema:e.inputSchema??{},name:e.name})),tools:i}}async close(){this.#t!==void 0&&(await this.#t.close(),this.#t=void 0),this.#e=void 0,this.#n=void 0,this.#r=void 0}};function isMcpHttpFallbackRetryableError(e){let t=readHttpStatus(e);return t===400||t===404||t===405}function readHttpStatus(t){for(let n of walkErrorChain(t)){if(!isObject(n))continue;let t=readStatusField(n);if(t!==void 0)return t;let r=n.response;if(isObject(r)){let e=readStatusField(r);if(e!==void 0)return e}if(typeof n.message==`string`){let e=/\bHTTP\s+(\d{3})\b/u.exec(n.message);if(e?.[1]!==void 0)return Number(e[1])}}}function readStatusField(e){if(typeof e.status==`number`)return e.status;if(typeof e.statusCode==`number`)return e.statusCode}function*walkErrorChain(t){let n=t,r=new Set;for(;n!=null&&!r.has(n);){if(r.add(n),yield n,!isObject(n)||!(`cause`in n))return;n=n.cause}}function passesToolFilter(e,t){return t===void 0?!0:`allow`in t?t.allow.includes(e):!t.block.includes(e)}async function resolveHeaders(e){let t={};if(e.authorization!==void 0&&(t.Authorization=`Bearer ${(await resolveToken(e)).token}`),e.headers!==void 0){let n=await resolveHeadersDefinition(e.headers);for(let[r,i]of Object.entries(n)){if(e.authorization!==void 0&&r.toLowerCase()===`authorization`)throw Error(`Connection "${e.connectionName}" headers must not include an "Authorization" key when "authorization" is also provided.`);t[r]=i}}return t}async function resolveToken(e){if(e.authorization===void 0)throw Error(`Connection "${e.connectionName}" does not define authorization.`);let a=contextStorage.getStore(),o=resolveConnectionPrincipal(e.connectionName,e.authorization,a),s={url:e.url};if(a===void 0)return await e.authorization.getToken({principal:o,connection:s});let c=principalKey(o),l=readCachedToken(a,e.connectionName,c);if(l!==void 0)return l;let u=await e.authorization.getToken({principal:o,connection:s});return writeCachedToken(a,e.connectionName,c,u),u}async function resolveHeadersDefinition(e){if(typeof e==`function`)return await e();let t={},n=Object.entries(e);for(let[e,r]of n)t[e]=await resolveHeaderValue(r);return t}async function resolveHeaderValue(e){return typeof e==`function`?await e():await e}export{McpConnectionClient,passesToolFilter,resolveHeaders};

package/dist/src/runtime/connections/principal-context.js CHANGED Viewed

@@ -1,111 +1 @@
-/**
- * Lexically scoped override for the connection principal resolver.
- *
- * `ConnectionPrincipalOverrideStackKey` lets one scope (currently the
- * interactive-OAuth orchestrator) carry an already-resolved
- * {@link ConnectionPrincipal} across a retry that may temporarily
- * run under a different `SessionAuthContext` — for example, the
- * step that resumes from an OAuth webhook sees the unauthenticated
- * callback request as the current caller, not the user who started
- * the turn. Rather than teaching
- * {@link resolveConnectionPrincipal} about every possible
- * restoration quirk, the orchestrator pushes an override frame,
- * runs the retry, and the resolver picks it up.
- *
- * The value is a stack of frames rather than a single map so the
- * push/pop lifecycle is race-safe under concurrent entry within the
- * same ALS scope. Each `withConnectionPrincipalOverride` call owns
- * exactly one frame (identified by object identity) and removes
- * that specific frame on exit regardless of what other frames were
- * pushed or popped while its body was awaited. A naive
- * capture-previous / restore-on-finally pattern would race: if two
- * concurrent calls entered this helper in the same container, both
- * would capture the same `previous`, the last writer would win, and
- * the `finally` blocks would non-deterministically restore to
- * whichever state each happened to observe.
- *
- * Cross-session isolation is handled one layer up by the process
- * `AsyncLocalStorage` in `context/container.ts` — every request runs
- * inside its own `ContextContainer`, so frames never leak between
- * sessions regardless of the in-container stack. The stack only has
- * to handle same-scope concurrency.
- *
- * The key is stored as a **virtual** context value and is never
- * serialized across step boundaries — the durable record is the
- * principal journaled into the step state itself. See D6b in
- * `research/connections/connection-principal-model.md` for the
- * full rationale.
- */
-import { ContextKey } from "#context/key.js";
-/**
- * Context key carrying the stack of in-flight principal override
- * frames. Pushed onto by {@link withConnectionPrincipalOverride};
- * read by {@link lookupConnectionPrincipalOverride}.
- *
- * The stack is ordered oldest-first; callers that want shadowing
- * semantics (inner scopes take precedence over outer) walk the
- * stack from the end backwards.
- */
-export const ConnectionPrincipalOverrideStackKey = new ContextKey("ash.connection-principal-override-stack");
-/**
- * Returns the principal override that should apply to `connectionName`
- * in the current scope, or `undefined` if no scope has pushed one.
- *
- * Walks the override stack from most-recently-pushed to least, so an
- * inner `withConnectionPrincipalOverride` shadows outer frames for
- * the same connection. Returns the override verbatim — callers are
- * responsible for deciding whether to use it in place of a
- * session-derived principal.
- */
-export function lookupConnectionPrincipalOverride(ctx, connectionName) {
-    const stack = ctx?.get(ConnectionPrincipalOverrideStackKey);
-    if (stack === undefined) {
-        return undefined;
-    }
-    for (let i = stack.length - 1; i >= 0; i--) {
-        const frame = stack[i];
-        if (frame === undefined) {
-            continue;
-        }
-        const hit = frame.overrides[connectionName];
-        if (hit !== undefined) {
-            return hit;
-        }
-    }
-    return undefined;
-}
-/**
- * Runs `fn` with the given per-connection principal overrides
- * active on `ctx`.
- *
- * Pushes a new frame onto the override stack on entry and removes
- * that specific frame (by object identity) on exit. Outer frames
- * remain visible to the resolver via
- * {@link lookupConnectionPrincipalOverride}, which walks the stack
- * top-to-bottom so overrides from nested scopes shadow the same
- * connection name in an outer scope.
- *
- * Takes `ctx` as an explicit argument rather than reading from
- * `AsyncLocalStorage`: the helper has to reach `setVirtualContext`,
- * which is intentionally only on the concrete {@link ContextContainer}
- * and not on the public `AshContext` surface. Passing the container
- * in directly keeps the type honest and lets callers thread the
- * already-in-scope container through without an implicit ALS lookup.
- *
- * Safe under concurrent entry on a single container: each call owns
- * exactly one frame and removes it by identity rather than by
- * position, so two racing callers cannot corrupt each other's view
- * of the stack.
- */
-export async function withConnectionPrincipalOverride(ctx, overrides, fn) {
-    const frame = { overrides };
-    const before = ctx.get(ConnectionPrincipalOverrideStackKey) ?? [];
-    ctx.setVirtualContext(ConnectionPrincipalOverrideStackKey, [...before, frame]);
-    try {
-        return await fn();
-    }
-    finally {
-        const current = ctx.get(ConnectionPrincipalOverrideStackKey) ?? [];
-        ctx.setVirtualContext(ConnectionPrincipalOverrideStackKey, current.filter((f) => f !== frame));
-    }
-}
+import{ContextKey}from"#context/key.js";var ConnectionPrincipalOverrideStackKey=new ContextKey(`ash.connection-principal-override-stack`);function lookupConnectionPrincipalOverride(e,n){let r=e?.get(ConnectionPrincipalOverrideStackKey);if(r!==void 0)for(let e=r.length-1;e>=0;e--){let t=r[e];if(t===void 0)continue;let i=t.overrides[n];if(i!==void 0)return i}}async function withConnectionPrincipalOverride(e,n,r){let i={overrides:n},a=e.get(ConnectionPrincipalOverrideStackKey)??[];e.setVirtualContext(ConnectionPrincipalOverrideStackKey,[...a,i]);try{return await r()}finally{let n=e.get(ConnectionPrincipalOverrideStackKey)??[];e.setVirtualContext(ConnectionPrincipalOverrideStackKey,n.filter(e=>e!==i))}}export{ConnectionPrincipalOverrideStackKey,lookupConnectionPrincipalOverride,withConnectionPrincipalOverride};