experimental-ash 0.42.0 → 0.44.0

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

@@ -1,4 +1,5 @@
-import type { PublicToolInputSchema } from "#shared/tool-definition.js";
+import type { ModelMessage } from "ai";
+import type { PublicToolInputSchema, ToolModelOutput } from "#shared/tool-definition.js";
 import type { SessionContext } from "#public/definitions/callback-context.js";
 import type { SessionAuth } from "#context/keys.js";
 import type { HandleMessageStreamEvent } from "#protocol/message.js";
@@ -11,14 +12,14 @@ type ToolContext = SessionContext;
 export type DynamicToolEventName = Extract<HandleMessageStreamEvent["type"], "session.started" | "turn.started" | "step.started">;
 export declare const ALLOWED_DYNAMIC_TOOL_EVENTS: ReadonlySet<string>;
 /**
- * Context passed to a dynamic tool resolver's event handler.
+ * Context passed to a dynamic resolver's event handler (tools and skills).
  *
  * Provides read-only access to session identity, auth, and channel
  * metadata. State access is not exposed here — resolvers read state
  * through `defineState` handles or via the session context available
  * inside tool `execute` functions.
  */
-export interface DynamicToolResolveContext {
+export interface DynamicResolveContext {
     readonly session: {
         readonly id: string;
         readonly auth: SessionAuth;
@@ -27,108 +28,82 @@ export interface DynamicToolResolveContext {
         readonly kind?: string;
         readonly continuationToken?: string;
     };
-    /**
-     * Compiler-injected durable cache for resolver I/O results.
-     *
-     * First call (per session): executes `fn`, stores the serializable
-     * result durably, returns it.
-     * Replay (subsequent workflow steps): returns the cached result
-     * without calling `fn`.
-     *
-     * The cached value must be JSON-serializable. Non-serializable
-     * values cause a runtime error on first cache write.
-     *
-     * @internal Injected by the `ash:dynamic-tool-await-cache` bundler
-     * transform. Not intended for direct author use.
-     */
-    __cache<T>(key: string, fn: () => T | Promise<T>): Promise<T>;
+    readonly messages: readonly ModelMessage[];
 }
 /**
  * A single tool entry within a resolved dynamic tool set.
  *
- * Identity comes from the entry's Record key — there is no `name`
- * field. For `defineTools`, the runtime tool name is always
- * `slug__key`. For `defineTool`, it is the file slug alone.
+ * Identity comes from context: when the resolver handler returns a
+ * single entry, the tool is named after the file slug. When the
+ * handler returns a `Record<string, DynamicToolEntry>`, each entry
+ * is named `slug__key`.
  *
  * `TInput` defaults to `Record<string, unknown>` but is inferred
- * automatically when `inputSchema` is a Standard Schema (e.g. Zod):
- *
- * ```ts
- * {
- *   inputSchema: z.object({ city: z.string() }),
- *   async execute(input) { return fetchWeather(input.city); },
- * }
- * ```
- *
- * When `inputSchema` is a plain JSON object, annotate `execute`
- * explicitly:
- *
- * ```ts
- * {
- *   inputSchema: { type: "object", properties: { city: { type: "string" } } },
- *   async execute(input: { city: string }) { return fetchWeather(input.city); },
- * }
- * ```
+ * automatically when `inputSchema` is a Standard Schema (e.g. Zod)
+ * via the `defineTool` wrapper.
  */
-export interface DynamicToolEntry<TInput = Record<string, unknown>, TOutput = unknown> {
-    /** @internal Stamp set by `tool()` — raw object literals are rejected. */
-    readonly __brand: "ash:tool";
+export interface DynamicToolEntry<TInput = Record<string, unknown>, TOutput = any> {
     readonly description: string;
     readonly inputSchema: PublicToolInputSchema<TInput>;
     execute(input: TInput, ctx: ToolContext): TOutput | Promise<TOutput>;
+    readonly toModelOutput?: (output: TOutput) => ToolModelOutput | Promise<ToolModelOutput>;
 }
 /**
  * A resolved tool set: keys are entry identifiers, values are tool
- * entries produced by the {@link tool} helper. Uses `any` for the
- * type params so entries with different schemas are assignable to
- * the same Record — `tool()` captures the per-entry types before
+ * entries produced by {@link defineTool}. Uses `any` for the type
+ * params so entries with different schemas are assignable to the
+ * same Record — `defineTool()` captures the per-entry types before
  * they reach this widened container.
  */
 export type DynamicToolSet = Readonly<Record<string, DynamicToolEntry<any, any>>>;
 /**
- * Event handler map for dynamic tool definitions. Each key is a
- * supported event name; each value is a resolver function that
- * receives the stream event and resolve context, and returns a
- * record of tool entries or `null`.
- *
- * The handler return type is `DynamicToolSet` — using
- * `DynamicToolEntry<any, any>` so per-entry Zod schemas infer
- * their own `execute(input)` type without being widened.
+ * Return type for a `defineDynamic` event handler. Each handler can
+ * return a single tool entry (named after the file slug), a map of
+ * entries (named `slug__key`), or `null` to produce no tools.
+ */
+export type DynamicToolResult = DynamicToolEntry<any, any> | DynamicToolSet | null;
+/**
+ * Event handler map for `defineDynamic`. Each key is a supported
+ * event name; each value is a resolver function that receives the
+ * stream event and resolve context, and returns a single tool entry,
+ * a record of tool entries, or `null`.
  */
 export type DynamicToolEvents = {
-    readonly [K in DynamicToolEventName]?: (event: unknown, ctx: DynamicToolResolveContext) => DynamicToolSet | null | Promise<DynamicToolSet | null>;
+    readonly [K in DynamicToolEventName]?: (event: unknown, ctx: DynamicResolveContext) => DynamicToolResult | Promise<DynamicToolResult>;
 };
 /**
- * Event handler map for a singular dynamic tool. Each handler returns
- * a single tool entry or `null`.
+ * Base event handler map accepted by `defineDynamic`. Intentionally
+ * wide — the slot directory (tools/ vs skills/) determines what the
+ * handlers must return, validated at runtime by the respective
+ * resolver. This type exists so `defineDynamic` can accept both
+ * tool-returning and skill-returning handlers.
  */
-export type DynamicSingleToolEvents = {
-    readonly [K in DynamicToolEventName]?: (event: unknown, ctx: DynamicToolResolveContext) => DynamicToolEntry | null | Promise<DynamicToolEntry | null>;
+export type DynamicEvents = {
+    readonly [K in DynamicToolEventName]?: (event: unknown, ctx: DynamicResolveContext) => unknown | Promise<unknown>;
 };
 /**
- * Marker discriminator for a `defineTools({ events })` export.
+ * Marker discriminator for a `defineDynamic({ events })` export.
  */
-export declare const DYNAMIC_TOOLS_SENTINEL_KIND: "ash:dynamic-tools";
+export declare const DYNAMIC_SENTINEL_KIND: "ash:dynamic";
 /**
- * Marker discriminator for a `defineTool({ events })` export.
+ * Runtime shape of a `defineDynamic({ events })` export, stamped
+ * with a sentinel kind so the compiler/normalizer can detect it.
  */
-export declare const DYNAMIC_TOOL_SENTINEL_KIND: "ash:dynamic-tool";
+export interface DynamicSentinel {
+    readonly kind: typeof DYNAMIC_SENTINEL_KIND;
+    readonly events: DynamicEvents;
+}
+export declare function isDynamicSentinel(value: unknown): value is DynamicSentinel;
 /**
- * Runtime shape of a `defineTools({ events })` export, stamped with a
- * sentinel kind so the compiler/normalizer can detect it.
+ * Symbol-based brand stamped by `defineTool` on every entry. Invisible
+ * in IntelliSense but checked at runtime to enforce the wrapper and
+ * to distinguish a single entry from a map of entries.
  */
-export interface DynamicToolsSentinel {
-    readonly kind: typeof DYNAMIC_TOOLS_SENTINEL_KIND;
-    readonly events: DynamicToolEvents;
-}
+export declare const TOOL_BRAND: unique symbol;
 /**
- * Runtime shape of a `defineTool({ events })` export, stamped with a
- * sentinel kind so the compiler/normalizer can detect it.
+ * Returns true if `value` was stamped by `defineTool` (has the brand
+ * symbol). Used to detect single entry vs map of entries, and to
+ * validate that entries are properly wrapped.
  */
-export interface DynamicToolSentinel {
-    readonly kind: typeof DYNAMIC_TOOL_SENTINEL_KIND;
-    readonly events: DynamicSingleToolEvents;
-}
-export declare function isDynamicToolsSentinel(value: unknown): value is DynamicToolsSentinel;
-export declare function isDynamicToolSentinel(value: unknown): value is DynamicToolSentinel;
+export declare function isBrandedToolEntry(value: unknown): boolean;
 export {};

package/dist/src/shared/dynamic-tool-definition.js

@@ -1 +1 @@
-const ALLOWED_DYNAMIC_TOOL_EVENTS=new Set([`session.started`,`turn.started`,`step.started`]),DYNAMIC_TOOLS_SENTINEL_KIND=`ash:dynamic-tools`,DYNAMIC_TOOL_SENTINEL_KIND=`ash:dynamic-tool`;function isDynamicToolsSentinel(e){return typeof e==`object`&&!!e&&e.kind===`ash:dynamic-tools`}function isDynamicToolSentinel(e){return typeof e==`object`&&!!e&&e.kind===`ash:dynamic-tool`}export{ALLOWED_DYNAMIC_TOOL_EVENTS,DYNAMIC_TOOLS_SENTINEL_KIND,DYNAMIC_TOOL_SENTINEL_KIND,isDynamicToolSentinel,isDynamicToolsSentinel};
+const ALLOWED_DYNAMIC_TOOL_EVENTS=new Set([`session.started`,`turn.started`,`step.started`]),DYNAMIC_SENTINEL_KIND=`ash:dynamic`;function isDynamicSentinel(e){return typeof e==`object`&&!!e&&e.kind===`ash:dynamic`}const TOOL_BRAND=Symbol.for(`ash:tool-brand`);function isBrandedToolEntry(e){return typeof e==`object`&&!!e&&e[TOOL_BRAND]===!0}export{ALLOWED_DYNAMIC_TOOL_EVENTS,DYNAMIC_SENTINEL_KIND,TOOL_BRAND,isBrandedToolEntry,isDynamicSentinel};

package/dist/src/shared/guards.d.ts

@@ -29,3 +29,17 @@ export declare function isObject(value: unknown): value is Record<string, unknow
  * meaningful value by display or correlation logic.
  */
 export declare function isNonEmptyString(value: unknown): value is string;
+/**
+ * Returns `true` when `value` is a thenable — an object with a `then`
+ * function. Used to reject async instrumentation metadata projectors
+ * that accidentally return a Promise instead of a plain record.
+ */
+export declare function isThenable(value: unknown): value is PromiseLike<unknown>;
+/**
+ * Returns `true` when `value` is a plain object record — `{}`,
+ * `Object.create(null)`, or an object whose prototype is
+ * `Object.prototype`. Class instances, `Map`, `Date`, and other
+ * exotic objects are excluded even though `isObject` would accept
+ * them.
+ */
+export declare function isPlainRecord(value: unknown): value is Record<string, unknown>;

package/dist/src/shared/guards.js

@@ -1 +1 @@
-function isObject(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function isNonEmptyString(e){return typeof e==`string`&&e.length>0}export{isNonEmptyString,isObject};
+function isObject(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function isNonEmptyString(e){return typeof e==`string`&&e.length>0}function isThenable(e){return isObject(e)&&typeof e.then==`function`}function isPlainRecord(e){if(!isObject(e))return!1;let t=Object.getPrototypeOf(e);return t===Object.prototype||t===null}export{isNonEmptyString,isObject,isPlainRecord,isThenable};

package/dist/src/shared/sandbox-network-policy.d.ts

@@ -0,0 +1,23 @@
+import type { NetworkPolicy } from "#compiled/@vercel/sandbox/index.js";
+/**
+ * Firewall network policy applied to a live sandbox session.
+ *
+ * Ash-owned alias of the backend network-policy shape. Use it to restrict
+ * egress (`"deny-all"`, an allow-list) or to broker credentials onto
+ * outgoing requests — a per-domain `transform` injects headers at the
+ * firewall so secrets never enter the sandbox process:
+ *
+ * ```ts
+ * const sandbox = await ctx.getSandbox();
+ * await sandbox.setNetworkPolicy({
+ *   allow: {
+ *     "github.com": [{ transform: [{ headers: { authorization: "Basic …" } }] }],
+ *     "*": [],
+ *   },
+ * });
+ * ```
+ *
+ * The local backend rejects `setNetworkPolicy`: just-bash cannot update its
+ * network policy at run time and runs no binaries to govern.
+ */
+export type SandboxNetworkPolicy = NetworkPolicy;

package/dist/src/shared/sandbox-network-policy.js

@@ -0,0 +1 @@
+export{};

package/dist/src/shared/sandbox-session.d.ts

@@ -1,4 +1,5 @@
 import type { Experimental_Sandbox as AiSdkSandbox } from "ai";
+import type { SandboxNetworkPolicy } from "#shared/sandbox-network-policy.js";
 /**
  * Options for running one command in a sandbox. Shape mirrors the AI
  * SDK {@link AiSdkSandbox} `run` argument so authored code that targets
@@ -83,6 +84,20 @@ export interface SandboxSession extends Pick<AiSdkSandbox, "run" | "spawn" | "re
      * The read and write methods already apply this internally.
      */
     resolvePath(path: string): string;
+    /**
+     * Applies a firewall network policy to this live sandbox at run time —
+     * for changing the policy *during* a turn (e.g. brokering a credential
+     * resolved mid-turn, or tightening egress after fetching data). A
+     * per-domain `transform` injects headers at the firewall so secrets
+     * never enter the sandbox process. The policy takes effect from the time
+     * the call resolves, so await it before the egress you want governed.
+     *
+     * When the policy is known at session start, prefer configuring it up
+     * front in the sandbox backend factory or `onSession`'s `use()`. The
+     * local backend rejects this call: just-bash cannot update its network
+     * policy at run time and runs no binaries to govern.
+     */
+    setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;
 }
 /**
  * Internal sandbox session, used to construct the public {@link SandboxSession}.

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

@@ -4,8 +4,8 @@
  */
 export type SkillFileContent = string | Uint8Array;
 /**
- * Public skill package content shared by TypeScript-authored skills and
- * runtime hook contributions.
+ * Public skill package content for authored skills and dynamic skill
+ * resolvers.
  */
 export interface SkillPackageDefinition {
     readonly description: string;
@@ -15,8 +15,9 @@ export interface SkillPackageDefinition {
     readonly files?: Readonly<Record<string, SkillFileContent>>;
 }
 /**
- * Runtime-contributed skill package. Hook-created skills do not have an
- * authored file path, so they carry their name explicitly.
+ * Skill package with an explicit name. Used by compiled skill entries
+ * (where the name is path-derived) and by dynamic skill resolvers
+ * (where the name is qualified from the resolver slug + entry key).
  */
 export interface NamedSkillDefinition extends SkillPackageDefinition {
     readonly name: string;

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.42.0",
+  "version": "0.44.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};