experimental-ash 0.41.0 → 0.43.0

package/dist/src/shared/tool-definition.d.ts

@@ -35,4 +35,16 @@ export interface InternalToolDefinitionWithExecuteFn<TInput = unknown, TOutput =
 export interface PublicToolDefinitionWithExecuteFn<TInput = unknown, TOutput = unknown> extends PublicToolDefinition<TInput> {
     execute: ToolExecuteFn<TInput, TOutput>;
 }
+/**
+ * Ash-owned shape for the model-facing tool result produced by
+ * `toModelOutput`. Structurally compatible with the AI SDK's
+ * `ToolResultOutput` so the harness can forward it without conversion.
+ */
+export type ToolModelOutput = {
+    readonly type: "text";
+    readonly value: string;
+} | {
+    readonly type: "json";
+    readonly value: unknown;
+};
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-ash",
-  "version": "0.41.0",
+  "version": "0.43.0",
   "bin": {
     "ash": "./bin/ash.js",
     "experimental-ash": "./bin/ash.js"
@@ -191,6 +191,7 @@
     "@vercel/sandbox": "2.0.1",
     "@workflow/core": "5.0.0-beta.10",
     "@workflow/errors": "5.0.0-beta.6",
+    "@workflow/world": "5.0.0-beta.5",
     "@workflow/world-local": "5.0.0-beta.11",
     "ai": "7.0.0-canary.159",
     "autoevals": "0.0.132",

package/dist/src/runtime/framework-tools/connection-search.d.ts

@@ -1,57 +0,0 @@
-import { ContextKey } from "#context/key.js";
-import { type AuthorizationSignal } from "#harness/authorization.js";
-import { type ConnectionRegistry, type ConnectionToolMetadata } from "#runtime/connections/types.js";
-import type { ResolvedToolDefinition } from "#runtime/types.js";
-import { type CodeModeConnectionAuthContext } from "#runtime/framework-tools/code-mode-connection-auth.js";
-/**
- * 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 declare const ConnectionRegistryKey: ContextKey<ConnectionRegistry>;
-/**
- * Durable state tracking which connection tools have been discovered
- * via `connection_search`.
- *
- * Maps connection name → tool metadata. Persists across step
- * boundaries so the tool-building code can register discovered tools
- * as first-class AI SDK tools on subsequent steps.
- */
-export interface DiscoveredConnectionToolsState {
-    readonly byConnection: Readonly<Record<string, readonly ConnectionToolMetadata[]>>;
-}
-/**
- * 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 declare const DiscoveredConnectionToolsKey: ContextKey<DiscoveredConnectionToolsState>;
-interface ConnectionSearchInput {
-    readonly connection?: string;
-    readonly keywords: string;
-    readonly limit?: number;
-}
-interface ConnectionSearchResultItem {
-    readonly connection: string;
-    readonly description: string;
-    readonly error?: string;
-    readonly inputSchema?: Record<string, unknown>;
-    readonly needsAuthorization?: boolean;
-    readonly tool?: string;
-    readonly qualifiedName?: string;
-}
-/**
- * Framework-provided `connection_search` tool.
- */
-export declare const CONNECTION_SEARCH_TOOL_DEFINITION: ResolvedToolDefinition;
-export declare function executeConnectionSearch(input: ConnectionSearchInput, meta?: {
-    readonly codeMode?: boolean;
-    readonly codeModeInterrupt?: CodeModeConnectionAuthContext;
-}): Promise<ConnectionSearchResultItem[] | AuthorizationSignal>;
-export declare function tokenize(text: string): string[];
-export declare function scoreMatch(queryTokens: string[], tool: ConnectionToolMetadata): number;
-export {};

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

@@ -1 +0,0 @@
-import{createLogger}from"#internal/logging.js";import{loadContext}from"#context/container.js";import{ContextKey}from"#context/key.js";import{loadCodeModeModule}from"#shared/code-mode.js";import{getAuthorizationResult,getHookUrl,requestAuthorization}from"#harness/authorization.js";import{CODE_MODE_CONNECTION_AUTH_INTERRUPT_KIND,isCodeModeToolExecutionOptions,readCodeModeConnectionAuthContext,toCodeModeConnectionAuthArgs}from"#runtime/framework-tools/code-mode-connection-auth.js";import{qualifiedConnectionToolName}from"#runtime/framework-tools/connection-tools.js";import{principalKey,resolveConnectionPrincipal}from"#runtime/connections/principal.js";import{supportsInteractiveAuthorization}from"#runtime/connections/types.js";import{isConnectionAuthorizationFailedError,isConnectionAuthorizationRequiredError}from"#public/connections/errors.js";import{writeCachedToken}from"#runtime/connections/authorization-tokens.js";const 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)=>executeConnectionSearch(e,{codeMode:isCodeModeToolExecutionOptions(t),codeModeInterrupt:readCodeModeConnectionAuthContext(t)}),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(){return loadContext().set(DiscoveredConnectionToolsKey,{byConnection:{}}),{}},sourceId:`ash:connection-search-tool`,sourceKind:`module`};async function executeConnectionSearch(e,n){let i=loadContext(),c=i.get(ConnectionRegistryKey);if(c===void 0)return[];await completePendingAuthorizations(c);let l=e.limit??10,u=tokenize(e.keywords),d=[],f=[],p=e.connection!==void 0&&e.connection!==``?c.getConnections().filter(t=>t.connectionName===e.connection):c.getConnections(),m={...i.get(DiscoveredConnectionToolsKey)?.byConnection},h=[];for(let t of p){if(n?.codeModeInterrupt?.resolution.status===`failed`&&n.codeModeInterrupt.payload.connectionName===t.connectionName){let{resolution:e}=n.codeModeInterrupt;f.push({connection:t.connectionName,description:t.description,error:e.reason,needsAuthorization:e.retryable});continue}let i;try{i=await c.getClient(t.connectionName).getToolMetadata()}catch(i){if(isConnectionAuthorizationRequiredError(i)){let i=resolveInteractiveAuth(c,t.connectionName);if(i&&n?.codeMode===!0){let{requestCodeModeInterrupt:n}=await loadCodeModeModule();n({args:toCodeModeConnectionAuthArgs(e),connectionName:t.connectionName,kind:CODE_MODE_CONNECTION_AUTH_INTERRUPT_KIND,toolName:`connection_search`})}if(i){let e=getHookUrl(t.connectionName);if(e){let n=resolveConnectionPrincipal(t.connectionName,i);try{let{challenge:r,state:a}=await i.startAuthorization({callbackUrl:e,connection:{url:t.url??``},principal:n});h.push({name:t.connectionName,challenge:r,hookUrl:e,state:a})}catch(e){logger.warn(`startAuthorization failed`,{connection:t.connectionName,error:e instanceof Error?e:Error(String(e))})}}}f.push({connection:t.connectionName,description:t.description,needsAuthorization:!0});continue}if(isConnectionAuthorizationFailedError(i)){logger.warn(`connection authorization failed`,{connection:t.connectionName,reason:i.reason,retryable:i.retryable,error:i}),f.push({connection:t.connectionName,description:t.description,error:`Authorization failed for ${t.connectionName}: ${i.message}`});continue}let o=i instanceof Error?i.message:`unknown error`;logger.warn(`failed to load connection tools`,{connection:t.connectionName,error:i instanceof Error?i:Error(o)}),f.push({connection:t.connectionName,description:t.description,error:`Failed to load tools for "${t.connectionName}": ${o}`});continue}m[t.connectionName]=i;for(let e of i){let n=scoreMatch(u,e);n>0&&d.push({item:{connection:t.connectionName,description:e.description,inputSchema:e.inputSchema,qualifiedName:qualifiedConnectionToolName(t.connectionName,e.name),tool:e.name},score:n})}}if(i.set(DiscoveredConnectionToolsKey,{byConnection:m}),h.length>0)return requestAuthorization(h);d.sort((e,t)=>t.score-e.score);let g=d.slice(0,l).map(e=>e.item);return g.length>0?[...g,...f]:p.map(e=>f.find(t=>t.connection===e.connectionName)||{connection:e.connectionName,description:e.description})}async function completePendingAuthorizations(e){let n=loadContext();for(let t of e.getConnections()){let r=getAuthorizationResult(t.connectionName);if(!r)continue;let a=resolveInteractiveAuth(e,t.connectionName);if(!a)continue;let o=resolveConnectionPrincipal(t.connectionName,a),s=await a.completeAuthorization({callbackUrl:r.hookUrl,connection:{url:t.url??``},principal:o,request:r.callback,state:r.state});writeCachedToken(n,t.connectionName,principalKey(o),s)}}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 resolveInteractiveAuth(e,t){let n=e.getConnections().find(e=>e.connectionName===t);if(n?.authorization&&supportsInteractiveAuthorization(n.authorization))return n.authorization}export{CONNECTION_SEARCH_TOOL_DEFINITION,ConnectionRegistryKey,DiscoveredConnectionToolsKey,executeConnectionSearch,scoreMatch,tokenize};

package/dist/src/runtime/framework-tools/connection-tools.d.ts

@@ -1,55 +0,0 @@
-import { type ToolSet } from "ai";
-import { type ConnectionRegistry } from "#runtime/connections/types.js";
-import type { ResolvedConnectionDefinition } from "#runtime/types.js";
-import { type DiscoveredConnectionToolsState } from "#runtime/framework-tools/connection-search.js";
-/**
- * Builds the qualified tool name for a connection tool.
- *
- * Uses double-underscore as the separator because it is safe in
- * tool-name schemas and unlikely to appear in authored tool names.
- */
-export declare function qualifiedConnectionToolName(connectionName: string, toolName: string): string;
-/**
- * Builds AI SDK tools for every connection tool that has been
- * discovered via a prior `connection_search` call.
- */
-export declare function resolveConnectionToolsFromState(registry: ConnectionRegistry, discovered: DiscoveredConnectionToolsState, input: {
-    readonly approvedTools?: ReadonlySet<string>;
-    readonly authMode?: "code-mode" | "direct";
-    readonly codeModeMetadataOnlyConnectionNames?: ReadonlySet<string>;
-    readonly existingToolNames?: ReadonlySet<string>;
-}): Promise<ToolSet>;
-/**
- * AI SDK tool-execute function shape. Captured locally so we can wrap
- * the `execute` returned by `@ai-sdk/mcp`'s `toolsFromDefinitions()`
- * without taking a direct dependency on the SDK's internal types.
- */
-type ToolExecuteFn = (args: unknown, options: unknown) => Promise<unknown>;
-/**
- * Wraps one connection tool's `execute` for nested code-mode execution.
- *
- * Interactive auth pauses the outer `code_mode` tool with a generic
- * interruption instead of writing a top-level placeholder result. The
- * durable workflow completes OAuth, then code mode replays the same
- * sandbox program and re-enters this nested host tool with
- * `options.codeModeInterrupt` populated.
- */
-export declare function wrapCodeModeConnectionToolExecute(params: {
-    readonly connectionDefinition: ResolvedConnectionDefinition | undefined;
-    readonly connectionName: string;
-    readonly originalExecute: ToolExecuteFn | undefined;
-    readonly toolName: string;
-}): ToolExecuteFn | undefined;
-/**
- * Wraps one connection tool's `execute` to handle interactive auth.
- * On auth error, starts authorization and returns an
- * `AuthorizationSignal`. On re-execution after callback, completes
- * auth, caches the token, and falls through to normal execute.
- */
-export declare function wrapConnectionToolExecute(params: {
-    readonly connectionDefinition: ResolvedConnectionDefinition | undefined;
-    readonly connectionName: string;
-    readonly originalExecute: ToolExecuteFn | undefined;
-    readonly toolName: string;
-}): ToolExecuteFn | undefined;
-export {};

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

@@ -1 +0,0 @@
-import{isObject}from"#shared/guards.js";import{loadContext}from"#context/container.js";import{jsonSchema}from"ai";import"#runtime/framework-tools/connection-search.js";import{loadCodeModeModule}from"#shared/code-mode.js";import{getAuthorizationResult,getHookUrl,requestAuthorization}from"#harness/authorization.js";import{CODE_MODE_CONNECTION_AUTH_INTERRUPT_KIND,toCodeModeConnectionAuthArgs}from"#runtime/framework-tools/code-mode-connection-auth.js";import{principalKey,resolveConnectionPrincipal}from"#runtime/connections/principal.js";import{supportsInteractiveAuthorization}from"#runtime/connections/types.js";import{isConnectionAuthorizationRequiredError}from"#public/connections/errors.js";import{writeCachedToken}from"#runtime/connections/authorization-tokens.js";function qualifiedConnectionToolName(e,t){return`${e}__${t}`}async function resolveConnectionToolsFromState(t,n,r){let i={};for(let[a,o]of Object.entries(n.byConnection)){let n=r.authMode===`code-mode`&&r.codeModeMetadataOnlyConnectionNames?.has(a)===!0,s=n?void 0:await t.getClient(a).getTools(),c=t.getConnectionApproval(a);for(let l of o){let o=qualifiedConnectionToolName(a,l.name);if(r.existingToolNames?.has(o))continue;let u=s?.[l.name]??(n?createMetadataOnlyTool(l,o):void 0);if(u===void 0)continue;let d=!n&&c!==void 0?async t=>c({approvedTools:r.approvedTools??new Set,toolInput:isObject(t)?t:void 0,toolName:o}):void 0,f=t.getConnections().find(e=>e.connectionName===a),p=u.execute,m=r.authMode===`code-mode`?wrapCodeModeConnectionToolExecute({connectionDefinition:f,connectionName:a,originalExecute:p,toolName:l.name}):wrapConnectionToolExecute({connectionDefinition:f,connectionName:a,originalExecute:p,toolName:l.name});i[o]={...u,execute:m,needsApproval:d}}}return i}function createMetadataOnlyTool(e,t){return{description:e.description,execute:async()=>{throw Error(`Connection tool "${t}" cannot execute without authorization.`)},inputSchema:jsonSchema(e.inputSchema)}}function wrapCodeModeConnectionToolExecute(e){let{connectionDefinition:n,connectionName:a,originalExecute:o,toolName:m}=e;if(o===void 0)return;let h=n?.authorization&&supportsInteractiveAuthorization(n.authorization)?n.authorization:void 0,g=n?.url??``;return async(e,n)=>{if(h){let e=getAuthorizationResult(a);if(e){let n=loadContext(),r=resolveConnectionPrincipal(a,h),i=await h.completeAuthorization({callbackUrl:e.hookUrl,connection:{url:g},principal:r,request:e.callback,state:e.state});writeCachedToken(n,a,principalKey(r),i)}}try{return await o(e,n)}catch(t){if(!isConnectionAuthorizationRequiredError(t)||!h)throw t;let{requestCodeModeInterrupt:n}=await loadCodeModeModule();n({args:toCodeModeConnectionAuthArgs(e),connectionName:a,kind:CODE_MODE_CONNECTION_AUTH_INTERRUPT_KIND,toolName:m})}}}function wrapConnectionToolExecute(e){let{connectionDefinition:n,connectionName:r,originalExecute:s}=e;if(s===void 0)return;let c=n?.authorization&&supportsInteractiveAuthorization(n.authorization)?n.authorization:void 0,m=n?.url??``;return async(e,n)=>{if(c){let e=getAuthorizationResult(r);if(e){let n=loadContext(),i=resolveConnectionPrincipal(r,c),a=await c.completeAuthorization({callbackUrl:e.hookUrl,connection:{url:m},principal:i,request:e.callback,state:e.state});writeCachedToken(n,r,principalKey(i),a)}}try{return await s(e,n)}catch(e){if(!isConnectionAuthorizationRequiredError(e)||!c)throw e;let t=getHookUrl(r);if(!t)throw e;let n=resolveConnectionPrincipal(r,c),{challenge:i,state:s}=await c.startAuthorization({callbackUrl:t,connection:{url:m},principal:n});return requestAuthorization([{name:r,challenge:i,hookUrl:t,state:s}])}}}export{qualifiedConnectionToolName,resolveConnectionToolsFromState,wrapCodeModeConnectionToolExecute,wrapConnectionToolExecute};