agents 0.20.1 → 0.22.0

package/dist/agent-routing.d.ts

@@ -0,0 +1,14 @@
+import {
+  a as routeAgentRequest,
+  i as getAgentByName,
+  n as AgentOptions,
+  r as RoutingRetryOptions,
+  t as AgentGetOptions
+} from "./agent-routing-CnkaHb-v.js";
+export {
+  AgentGetOptions,
+  AgentOptions,
+  RoutingRetryOptions,
+  getAgentByName,
+  routeAgentRequest
+};

package/dist/agent-routing.js

@@ -0,0 +1,187 @@
+import { camelCaseToKebabCase } from "./utils.js";
+//#region src/agent-routing.ts
+const namespaceMapCache = /* @__PURE__ */ new WeakMap();
+const bindingNameCache = /* @__PURE__ */ new WeakMap();
+const DEFAULT_ROUTING_RETRY_OPTIONS = {
+	maxAttempts: 3,
+	baseDelayMs: 100,
+	maxDelayMs: 800
+};
+function durableObjectGetOptions(options) {
+	return options?.locationHint ? { locationHint: options.locationHint } : void 0;
+}
+function validatePositiveInteger(value, name) {
+	if (!Number.isFinite(value) || value < 1) throw new Error(`${name} must be >= 1`);
+	if (!Number.isInteger(value)) throw new Error(`${name} must be an integer`);
+}
+function validatePositiveNumber(value, name) {
+	if (!Number.isFinite(value) || value <= 0) throw new Error(`${name} must be > 0`);
+}
+function resolveRoutingRetryOptions(options) {
+	if (options === false) return null;
+	const resolved = {
+		maxAttempts: options?.maxAttempts ?? DEFAULT_ROUTING_RETRY_OPTIONS.maxAttempts,
+		baseDelayMs: options?.baseDelayMs ?? DEFAULT_ROUTING_RETRY_OPTIONS.baseDelayMs,
+		maxDelayMs: options?.maxDelayMs ?? DEFAULT_ROUTING_RETRY_OPTIONS.maxDelayMs,
+		onRetry: options?.onRetry
+	};
+	validatePositiveInteger(resolved.maxAttempts, "routingRetry.maxAttempts");
+	validatePositiveNumber(resolved.baseDelayMs, "routingRetry.baseDelayMs");
+	validatePositiveNumber(resolved.maxDelayMs, "routingRetry.maxDelayMs");
+	if (resolved.baseDelayMs > resolved.maxDelayMs) throw new Error("routingRetry.baseDelayMs must be <= maxDelayMs");
+	return resolved;
+}
+function isRetryableDurableObjectError(error) {
+	if (typeof error !== "object" || error === null) return false;
+	const typed = error;
+	return typed.retryable === true && typed.overloaded !== true;
+}
+function routingRetryDelayMs(attempt, options) {
+	const upperBoundMs = Math.min(options.maxDelayMs, options.baseDelayMs * 2 ** (attempt - 1));
+	return Math.floor(Math.random() * upperBoundMs);
+}
+async function retryDurableObjectOperation(operation, context, retryOptions) {
+	const resolved = resolveRoutingRetryOptions(retryOptions);
+	if (!resolved) return await operation();
+	let attempt = 1;
+	while (true) try {
+		return await operation();
+	} catch (error) {
+		const nextAttempt = attempt + 1;
+		if (nextAttempt > resolved.maxAttempts || !isRetryableDurableObjectError(error)) throw error;
+		const delayMs = routingRetryDelayMs(attempt, resolved);
+		try {
+			await resolved.onRetry?.({
+				error,
+				attempt,
+				maxAttempts: resolved.maxAttempts,
+				delayMs,
+				name: context.name,
+				className: context.className
+			});
+		} catch (callbackError) {
+			console.warn("Durable Object routing retry callback failed:", callbackError);
+		}
+		await new Promise((resolve) => setTimeout(resolve, delayMs));
+		attempt = nextAttempt;
+	}
+}
+function encodeLifecycleProps(props) {
+	const bytes = new TextEncoder().encode(JSON.stringify(props));
+	let binary = "";
+	for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+	return btoa(binary);
+}
+function mutableRequest(request) {
+	return new Request(request);
+}
+function cloneRequestForFetch(request) {
+	return request.clone();
+}
+function resolveCorsHeaders(cors) {
+	if (cors === true) return {
+		"Access-Control-Allow-Origin": "*",
+		"Access-Control-Allow-Methods": "GET, POST, HEAD, OPTIONS",
+		"Access-Control-Allow-Headers": "*",
+		"Access-Control-Max-Age": "86400"
+	};
+	if (cors && typeof cors === "object") {
+		const headers = new Headers(cors);
+		const record = {};
+		headers.forEach((value, key) => {
+			record[key] = value;
+		});
+		return record;
+	}
+	return null;
+}
+/**
+* Route `/agents/:binding/:name` HTTP and WebSocket requests to a named
+* Durable Object. The target may extend `Agent` or compose `Lifecycle`
+* directly into a plain `DurableObject`.
+*
+* @param request - Incoming Worker request.
+* @param env - Worker environment containing Durable Object bindings.
+* @param options - Routing options.
+* @returns The matched response, or `null` when the path does not match.
+*/
+async function routeAgentRequest(request, env, options) {
+	const environment = env;
+	if (!namespaceMapCache.has(environment)) {
+		const namespaceMap = {};
+		const bindingNames = {};
+		for (const [key, value] of Object.entries(environment)) if (value && typeof value === "object" && "idFromName" in value && typeof value.idFromName === "function") {
+			const kebab = camelCaseToKebabCase(key);
+			namespaceMap[kebab] = value;
+			bindingNames[kebab] = key;
+		}
+		namespaceMapCache.set(environment, namespaceMap);
+		bindingNameCache.set(environment, bindingNames);
+	}
+	const map = namespaceMapCache.get(environment);
+	const bindingNames = bindingNameCache.get(environment);
+	const prefixParts = (options?.prefix || "agents").split("/");
+	const parts = new URL(request.url).pathname.split("/").filter(Boolean);
+	if (!prefixParts.every((part, index) => parts[index] === part) || parts.length < prefixParts.length + 2) return null;
+	const namespaceName = parts[prefixParts.length];
+	const name = parts[prefixParts.length + 1];
+	if (!name || !namespaceName) return null;
+	const boundNamespace = map[namespaceName];
+	if (!boundNamespace) {
+		console.error(`The URL ${request.url} with namespace "${namespaceName}" and name "${name}" does not match any Durable Object binding.`);
+		return new Response("Invalid request", { status: 400 });
+	}
+	const corsHeaders = resolveCorsHeaders(options?.cors);
+	const isWebSocket = request.headers.get("Upgrade")?.toLowerCase() === "websocket";
+	const withCorsHeaders = (response) => {
+		if (!corsHeaders || isWebSocket) return response;
+		const nextResponse = new Response(response.body, response);
+		for (const [key, value] of Object.entries(corsHeaders)) nextResponse.headers.set(key, value);
+		return nextResponse;
+	};
+	if (request.method === "OPTIONS" && corsHeaders) return new Response(null, { headers: corsHeaders });
+	const namespace = options?.jurisdiction ? boundNamespace.jurisdiction(options.jurisdiction) : boundNamespace;
+	const id = namespace.idFromName(name);
+	const getOptions = durableObjectGetOptions(options);
+	request = mutableRequest(request);
+	const className = bindingNames[namespaceName];
+	const route = {
+		className,
+		name
+	};
+	if (isWebSocket) {
+		const requestOrResponse = await options?.onBeforeConnect?.(request, route);
+		if (requestOrResponse instanceof Request) request = mutableRequest(requestOrResponse);
+		else if (requestOrResponse instanceof Response) return requestOrResponse;
+	} else {
+		const requestOrResponse = await options?.onBeforeRequest?.(request, route);
+		if (requestOrResponse instanceof Request) request = mutableRequest(requestOrResponse);
+		else if (requestOrResponse instanceof Response) return withCorsHeaders(requestOrResponse);
+	}
+	if (options?.props !== void 0) request.headers.set("x-agents-lifecycle-props", encodeLifecycleProps(options.props));
+	const response = await retryDurableObjectOperation(() => namespace.get(id, getOptions).fetch(cloneRequestForFetch(request)), {
+		name,
+		className
+	}, options?.routingRetry);
+	return isWebSocket ? response : withCorsHeaders(response);
+}
+/**
+* Get a named Agent stub after its lifecycle startup has completed.
+*
+* @param namespace - Agent Durable Object namespace.
+* @param name - Agent instance name.
+* @param options - Placement, startup properties, and retry options.
+* @returns The initialized Agent stub.
+*/
+async function getAgentByName(namespace, name, options) {
+	const target = options?.jurisdiction ? namespace.jurisdiction(options.jurisdiction) : namespace;
+	const id = target.idFromName(name);
+	const stub = target.get(id, durableObjectGetOptions(options));
+	const lifecycleStub = stub;
+	await retryDurableObjectOperation(() => lifecycleStub.__unsafe_ensureInitialized(options?.props), { name }, options?.routingRetry);
+	return stub;
+}
+//#endregion
+export { getAgentByName, routeAgentRequest };
+
+//# sourceMappingURL=agent-routing.js.map

package/dist/agent-routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-routing.js","names":[],"sources":["../src/agent-routing.ts"],"sourcesContent":["import type { Agent } from \"./index\";\nimport { camelCaseToKebabCase } from \"./utils\";\n\nconst namespaceMapCache = new WeakMap<\n  object,\n  Record<string, DurableObjectNamespace>\n>();\nconst bindingNameCache = new WeakMap<object, Record<string, string>>();\n\nconst DEFAULT_ROUTING_RETRY_OPTIONS = {\n  maxAttempts: 3,\n  baseDelayMs: 100,\n  maxDelayMs: 800\n};\n\ninterface RoutingRetryEvent {\n  error: unknown;\n  attempt: number;\n  maxAttempts: number;\n  delayMs: number;\n  name: string;\n  className?: string;\n}\n\n/** Retry policy for Agent routing infrastructure failures. */\nexport interface RoutingRetryOptions {\n  /** Max number of attempts, including the first. Default: 3. */\n  maxAttempts?: number;\n  /** Base delay in milliseconds for exponential backoff. Default: 100. */\n  baseDelayMs?: number;\n  /** Maximum delay in milliseconds. Default: 800. */\n  maxDelayMs?: number;\n  /** Optional callback invoked before each retry delay. */\n  onRetry?: (event: RoutingRetryEvent) => void | Promise<void>;\n}\n\ninterface AgentRouteMatch<Env = Cloudflare.Env> {\n  /** The Durable Object environment binding name. */\n  className: Extract<keyof Env, string>;\n  /** The named Durable Object instance extracted from the URL. */\n  name: string;\n}\n\ninterface AgentRouteOptions<\n  Env = Cloudflare.Env,\n  Props extends Record<string, unknown> = Record<string, unknown>\n> {\n  /** URL prefix before the binding and instance name. Default: `agents`. */\n  prefix?: string;\n  jurisdiction?: DurableObjectJurisdiction;\n  locationHint?: DurableObjectLocationHint;\n  /** Properties supplied before lifecycle startup. */\n  props?: Props;\n  /**\n   * Whether to enable CORS for matched routes.\n   *\n   * When `true`, uses default permissive CORS headers:\n   * - Access-Control-Allow-Origin: *\n   * - Access-Control-Allow-Methods: GET, POST, HEAD, OPTIONS\n   * - Access-Control-Allow-Headers: *\n   * - Access-Control-Max-Age: 86400\n   *\n   * For credentialed requests, pass explicit headers with a specific origin.\n   * When set to a `HeadersInit` value, uses those as the CORS headers instead.\n   * CORS preflight requests are handled automatically for matched routes.\n   */\n  cors?: boolean | HeadersInit;\n  /**\n   * Retry transient Durable Object infrastructure errors thrown while routing.\n   * Enabled by default; pass `false` to disable.\n   */\n  routingRetry?: false | RoutingRetryOptions;\n  onBeforeConnect?: (\n    request: Request,\n    route: AgentRouteMatch<Env>\n  ) => Response | Request | void | Promise<Response | Request | void>;\n  onBeforeRequest?: (\n    request: Request,\n    route: AgentRouteMatch<Env>\n  ) =>\n    | Response\n    | Request\n    | void\n    | Promise<Response | Request | undefined | void>;\n}\n\n/** Configuration options for {@link routeAgentRequest}. */\nexport type AgentOptions<Env> = AgentRouteOptions<Env>;\n\n/** Options for resolving and starting a named Agent. */\nexport type AgentGetOptions<\n  Env,\n  Props extends Record<string, unknown> = Record<string, unknown>\n> = Pick<\n  AgentRouteOptions<Env, Props>,\n  \"jurisdiction\" | \"locationHint\" | \"props\" | \"routingRetry\"\n>;\n\ninterface ResolvedRoutingRetryOptions extends Required<\n  Omit<RoutingRetryOptions, \"onRetry\">\n> {\n  onRetry?: RoutingRetryOptions[\"onRetry\"];\n}\n\ninterface RoutingRetryContext {\n  name: string;\n  className?: string;\n}\n\nfunction durableObjectGetOptions(\n  options: { locationHint?: DurableObjectLocationHint } | undefined\n) {\n  return options?.locationHint\n    ? { locationHint: options.locationHint }\n    : undefined;\n}\n\nfunction validatePositiveInteger(value: number, name: string): void {\n  if (!Number.isFinite(value) || value < 1) {\n    throw new Error(`${name} must be >= 1`);\n  }\n  if (!Number.isInteger(value)) {\n    throw new Error(`${name} must be an integer`);\n  }\n}\n\nfunction validatePositiveNumber(value: number, name: string): void {\n  if (!Number.isFinite(value) || value <= 0) {\n    throw new Error(`${name} must be > 0`);\n  }\n}\n\nfunction resolveRoutingRetryOptions(\n  options: false | RoutingRetryOptions | undefined\n): ResolvedRoutingRetryOptions | null {\n  if (options === false) return null;\n\n  const resolved = {\n    maxAttempts:\n      options?.maxAttempts ?? DEFAULT_ROUTING_RETRY_OPTIONS.maxAttempts,\n    baseDelayMs:\n      options?.baseDelayMs ?? DEFAULT_ROUTING_RETRY_OPTIONS.baseDelayMs,\n    maxDelayMs: options?.maxDelayMs ?? DEFAULT_ROUTING_RETRY_OPTIONS.maxDelayMs,\n    onRetry: options?.onRetry\n  };\n\n  validatePositiveInteger(resolved.maxAttempts, \"routingRetry.maxAttempts\");\n  validatePositiveNumber(resolved.baseDelayMs, \"routingRetry.baseDelayMs\");\n  validatePositiveNumber(resolved.maxDelayMs, \"routingRetry.maxDelayMs\");\n  if (resolved.baseDelayMs > resolved.maxDelayMs) {\n    throw new Error(\"routingRetry.baseDelayMs must be <= maxDelayMs\");\n  }\n\n  return resolved;\n}\n\nfunction isRetryableDurableObjectError(error: unknown): boolean {\n  if (typeof error !== \"object\" || error === null) return false;\n  // SAFETY: Cloudflare's retryable and overloaded error flags are optional\n  // runtime properties not represented on the base Error type.\n  const typed = error as { retryable?: boolean; overloaded?: boolean };\n  return typed.retryable === true && typed.overloaded !== true;\n}\n\nfunction routingRetryDelayMs(\n  attempt: number,\n  options: ResolvedRoutingRetryOptions\n): number {\n  const upperBoundMs = Math.min(\n    options.maxDelayMs,\n    options.baseDelayMs * 2 ** (attempt - 1)\n  );\n  return Math.floor(Math.random() * upperBoundMs);\n}\n\nasync function retryDurableObjectOperation<T>(\n  operation: () => Promise<T>,\n  context: RoutingRetryContext,\n  retryOptions: false | RoutingRetryOptions | undefined\n): Promise<T> {\n  const resolved = resolveRoutingRetryOptions(retryOptions);\n  if (!resolved) return await operation();\n\n  let attempt = 1;\n  while (true) {\n    try {\n      return await operation();\n    } catch (error) {\n      const nextAttempt = attempt + 1;\n      if (\n        nextAttempt > resolved.maxAttempts ||\n        !isRetryableDurableObjectError(error)\n      ) {\n        throw error;\n      }\n\n      const delayMs = routingRetryDelayMs(attempt, resolved);\n      try {\n        await resolved.onRetry?.({\n          error,\n          attempt,\n          maxAttempts: resolved.maxAttempts,\n          delayMs,\n          name: context.name,\n          className: context.className\n        });\n      } catch (callbackError) {\n        console.warn(\n          \"Durable Object routing retry callback failed:\",\n          callbackError\n        );\n      }\n      await new Promise((resolve) => setTimeout(resolve, delayMs));\n      attempt = nextAttempt;\n    }\n  }\n}\n\nfunction encodeLifecycleProps(props: unknown): string {\n  const bytes = new TextEncoder().encode(JSON.stringify(props));\n  let binary = \"\";\n  for (let i = 0; i < bytes.length; i++) {\n    binary += String.fromCharCode(bytes[i]);\n  }\n  return btoa(binary);\n}\n\nfunction mutableRequest(request: Request): Request {\n  return new Request(request);\n}\n\nfunction cloneRequestForFetch(request: Request): Request {\n  // SAFETY: Workers Types v5 preserves an unconstrained `cf` generic from\n  // clone(). Cloning does not change the runtime Request representation.\n  return request.clone() as Request;\n}\n\nfunction resolveCorsHeaders(\n  cors: boolean | HeadersInit | undefined\n): Record<string, string> | null {\n  if (cors === true) {\n    return {\n      \"Access-Control-Allow-Origin\": \"*\",\n      \"Access-Control-Allow-Methods\": \"GET, POST, HEAD, OPTIONS\",\n      \"Access-Control-Allow-Headers\": \"*\",\n      \"Access-Control-Max-Age\": \"86400\"\n    };\n  }\n  if (cors && typeof cors === \"object\") {\n    const headers = new Headers(cors);\n    const record: Record<string, string> = {};\n    headers.forEach((value, key) => {\n      record[key] = value;\n    });\n    return record;\n  }\n  return null;\n}\n\n/**\n * Route `/agents/:binding/:name` HTTP and WebSocket requests to a named\n * Durable Object. The target may extend `Agent` or compose `Lifecycle`\n * directly into a plain `DurableObject`.\n *\n * @param request - Incoming Worker request.\n * @param env - Worker environment containing Durable Object bindings.\n * @param options - Routing options.\n * @returns The matched response, or `null` when the path does not match.\n */\nexport async function routeAgentRequest<Env>(\n  request: Request,\n  env: Env,\n  options?: AgentOptions<Env>\n): Promise<Response | null> {\n  // SAFETY: Worker environments are object records. The unconstrained Env\n  // generic is retained for compatibility with the previously published API.\n  const environment = env as object;\n  if (!namespaceMapCache.has(environment)) {\n    const namespaceMap: Record<string, DurableObjectNamespace> = {};\n    const bindingNames: Record<string, string> = {};\n    for (const [key, value] of Object.entries(environment)) {\n      if (\n        value &&\n        typeof value === \"object\" &&\n        \"idFromName\" in value &&\n        typeof value.idFromName === \"function\"\n      ) {\n        const kebab = camelCaseToKebabCase(key);\n        // SAFETY: The structural idFromName check above identifies a Durable\n        // Object namespace at the Worker environment boundary.\n        namespaceMap[kebab] = value as DurableObjectNamespace;\n        bindingNames[kebab] = key;\n      }\n    }\n    namespaceMapCache.set(environment, namespaceMap);\n    bindingNameCache.set(environment, bindingNames);\n  }\n\n  const map = namespaceMapCache.get(environment) as Record<\n    string,\n    DurableObjectNamespace\n  >;\n  const bindingNames = bindingNameCache.get(environment) as Record<\n    string,\n    string\n  >;\n  const prefixParts = (options?.prefix || \"agents\").split(\"/\");\n  const parts = new URL(request.url).pathname.split(\"/\").filter(Boolean);\n  const prefixMatches = prefixParts.every(\n    (part, index) => parts[index] === part\n  );\n  if (!prefixMatches || parts.length < prefixParts.length + 2) return null;\n\n  const namespaceName = parts[prefixParts.length];\n  const name = parts[prefixParts.length + 1];\n  if (!name || !namespaceName) return null;\n\n  const boundNamespace = map[namespaceName];\n  if (!boundNamespace) {\n    console.error(\n      `The URL ${request.url} with namespace \"${namespaceName}\" and name \"${name}\" does not match any Durable Object binding.`\n    );\n    return new Response(\"Invalid request\", { status: 400 });\n  }\n\n  const corsHeaders = resolveCorsHeaders(options?.cors);\n  const isWebSocket =\n    request.headers.get(\"Upgrade\")?.toLowerCase() === \"websocket\";\n  const withCorsHeaders = (response: Response): Response => {\n    if (!corsHeaders || isWebSocket) return response;\n    const nextResponse = new Response(response.body, response);\n    for (const [key, value] of Object.entries(corsHeaders)) {\n      nextResponse.headers.set(key, value);\n    }\n    return nextResponse;\n  };\n\n  if (request.method === \"OPTIONS\" && corsHeaders) {\n    return new Response(null, { headers: corsHeaders });\n  }\n\n  const namespace = options?.jurisdiction\n    ? boundNamespace.jurisdiction(options.jurisdiction)\n    : boundNamespace;\n  const id = namespace.idFromName(name);\n  const getOptions = durableObjectGetOptions(options);\n  request = mutableRequest(request);\n\n  // SAFETY: binding names come directly from Object.entries(env), so they are\n  // string keys of Env.\n  const className = bindingNames[namespaceName] as Extract<keyof Env, string>;\n  const route: AgentRouteMatch<Env> = { className, name };\n\n  if (isWebSocket) {\n    const requestOrResponse = await options?.onBeforeConnect?.(request, route);\n    if (requestOrResponse instanceof Request) {\n      request = mutableRequest(requestOrResponse);\n    } else if (requestOrResponse instanceof Response) {\n      return requestOrResponse;\n    }\n  } else {\n    const requestOrResponse = await options?.onBeforeRequest?.(request, route);\n    if (requestOrResponse instanceof Request) {\n      request = mutableRequest(requestOrResponse);\n    } else if (requestOrResponse instanceof Response) {\n      return withCorsHeaders(requestOrResponse);\n    }\n  }\n\n  if (options?.props !== undefined) {\n    request.headers.set(\n      \"x-agents-lifecycle-props\",\n      encodeLifecycleProps(options.props)\n    );\n  }\n\n  const response = await retryDurableObjectOperation(\n    () => namespace.get(id, getOptions).fetch(cloneRequestForFetch(request)),\n    { name, className },\n    options?.routingRetry\n  );\n  return isWebSocket ? response : withCorsHeaders(response);\n}\n\n/**\n * Get a named Agent stub after its lifecycle startup has completed.\n *\n * @param namespace - Agent Durable Object namespace.\n * @param name - Agent instance name.\n * @param options - Placement, startup properties, and retry options.\n * @returns The initialized Agent stub.\n */\nexport async function getAgentByName<\n  Env extends Cloudflare.Env = Cloudflare.Env,\n  T extends Agent<Env> = Agent<Env>,\n  Props extends Record<string, unknown> = Record<string, unknown>\n>(\n  namespace: DurableObjectNamespace<T>,\n  name: string,\n  options?: AgentGetOptions<Env, Props>\n): Promise<DurableObjectStub<T>> {\n  const target = options?.jurisdiction\n    ? namespace.jurisdiction(options.jurisdiction)\n    : namespace;\n  const id = target.idFromName(name);\n  const stub = target.get(id, durableObjectGetOptions(options));\n\n  // SAFETY: Agent exposes this internal initializer specifically for native\n  // RPC calls, which bypass the lifecycle-installed fetch handler.\n  const lifecycleStub = stub as unknown as {\n    __unsafe_ensureInitialized(props?: Props): Promise<void>;\n  };\n  await retryDurableObjectOperation(\n    () => lifecycleStub.__unsafe_ensureInitialized(options?.props),\n    { name },\n    options?.routingRetry\n  );\n\n  return stub;\n}\n"],"mappings":"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"}

package/dist/agent-tool-types.d.ts

@@ -1,30 +1,30 @@
 import {
-  C as DetachedRunAgentToolResult,
-  S as DetachedAgentToolConfig,
-  T as RunAgentToolResult,
-  _ as AgentToolRunState,
-  a as AgentToolEvent,
-  b as AgentToolTerminalStatus,
-  c as AgentToolFailure,
-  d as AgentToolMilestone,
-  f as AgentToolProgress,
-  g as AgentToolRunPart,
-  h as AgentToolRunInspection,
-  i as AgentToolDisplayMetadata,
-  l as AgentToolInterruptedReason,
-  m as AgentToolRunInfo,
-  n as AGENT_TOOL_PROGRESS_PART,
-  o as AgentToolEventMessage,
-  p as AgentToolProgressSnapshot,
-  r as AgentToolChildAdapter,
-  s as AgentToolEventState,
-  t as AGENT_TOOL_MILESTONE_PART,
-  u as AgentToolLifecycleResult,
-  v as AgentToolRunStatus,
-  w as RunAgentToolOptions,
-  x as ChatCapableAgentClass,
-  y as AgentToolStoredChunk
-} from "./agent-tool-types-BC-WFlsz.js";
+  $ as AgentToolRunPart,
+  B as AgentToolChildAdapter,
+  G as AgentToolFailure,
+  H as AgentToolEvent,
+  J as AgentToolMilestone,
+  K as AgentToolInterruptedReason,
+  Q as AgentToolRunInspection,
+  R as AGENT_TOOL_MILESTONE_PART,
+  U as AgentToolEventMessage,
+  V as AgentToolDisplayMetadata,
+  W as AgentToolEventState,
+  X as AgentToolProgressSnapshot,
+  Y as AgentToolProgress,
+  Z as AgentToolRunInfo,
+  at as DetachedAgentToolConfig,
+  ct as RunAgentToolResult,
+  et as AgentToolRunState,
+  it as ChatCapableAgentClass,
+  nt as AgentToolStoredChunk,
+  ot as DetachedRunAgentToolResult,
+  q as AgentToolLifecycleResult,
+  rt as AgentToolTerminalStatus,
+  st as RunAgentToolOptions,
+  tt as AgentToolRunStatus,
+  z as AGENT_TOOL_PROGRESS_PART
+} from "./agent-routing-CnkaHb-v.js";
 export {
   AGENT_TOOL_MILESTONE_PART,
   AGENT_TOOL_PROGRESS_PART,

package/dist/{agent-tools-DeHe9Xov.d.ts → agent-tools-C0XJqWzB.d.ts}

@@ -1,10 +1,10 @@
 import {
-  f as AgentToolProgress,
-  g as AgentToolRunPart,
-  o as AgentToolEventMessage,
-  s as AgentToolEventState,
-  y as AgentToolStoredChunk
-} from "./agent-tool-types-BC-WFlsz.js";
+  $ as AgentToolRunPart,
+  U as AgentToolEventMessage,
+  W as AgentToolEventState,
+  Y as AgentToolProgress,
+  nt as AgentToolStoredChunk
+} from "./agent-routing-CnkaHb-v.js";
 
 //#region src/chat/agent-tools.d.ts
 type AgentToolProgressEmitResult = "emitted" | "coalesced" | "inactive";
@@ -130,4 +130,4 @@ export {
   interceptAgentToolBroadcast as s,
   AgentToolBroadcastHooks as t
 };
-//# sourceMappingURL=agent-tools-DeHe9Xov.d.ts.map
+//# sourceMappingURL=agent-tools-C0XJqWzB.d.ts.map

package/dist/agent-tools.d.ts

@@ -1,46 +1,62 @@
 import {
-  C as DetachedRunAgentToolResult,
-  S as DetachedAgentToolConfig,
-  T as RunAgentToolResult,
-  _ as AgentToolRunState,
-  a as AgentToolEvent,
-  b as AgentToolTerminalStatus,
-  c as AgentToolFailure,
-  g as AgentToolRunPart,
-  h as AgentToolRunInspection,
-  i as AgentToolDisplayMetadata,
-  l as AgentToolInterruptedReason,
-  m as AgentToolRunInfo,
-  o as AgentToolEventMessage,
-  r as AgentToolChildAdapter,
-  s as AgentToolEventState,
-  u as AgentToolLifecycleResult,
-  v as AgentToolRunStatus,
-  w as RunAgentToolOptions,
-  x as ChatCapableAgentClass,
-  y as AgentToolStoredChunk
-} from "./agent-tool-types-BC-WFlsz.js";
-import { Tool } from "ai";
+  $ as AgentToolRunPart,
+  B as AgentToolChildAdapter,
+  G as AgentToolFailure,
+  H as AgentToolEvent,
+  K as AgentToolInterruptedReason,
+  Q as AgentToolRunInspection,
+  U as AgentToolEventMessage,
+  V as AgentToolDisplayMetadata,
+  W as AgentToolEventState,
+  Z as AgentToolRunInfo,
+  at as DetachedAgentToolConfig,
+  ct as RunAgentToolResult,
+  et as AgentToolRunState,
+  it as ChatCapableAgentClass,
+  nt as AgentToolStoredChunk,
+  ot as DetachedRunAgentToolResult,
+  q as AgentToolLifecycleResult,
+  rt as AgentToolTerminalStatus,
+  st as RunAgentToolOptions,
+  tt as AgentToolRunStatus
+} from "./agent-routing-CnkaHb-v.js";
+import { FlexibleSchema, InferSchema, Tool } from "ai";
 
 //#region src/agent-tools.d.ts
-type SchemaLike<T = unknown> = {
-  parse(value: unknown): T;
+type ParseSchema<Output = unknown> = {
+  parse(value: unknown): Output;
 };
-type AgentToolFactoryOptions<Output = unknown> = {
+type AgentToolOutputSchema<Output> =
+  | FlexibleSchema<Output>
+  | ParseSchema<Output>;
+type AgentToolFactoryOptions<Output = unknown, Input = unknown> = {
   description: string;
-  inputSchema: unknown;
-  outputSchema?: SchemaLike<Output>;
+  inputSchema: FlexibleSchema<Input>;
+  outputSchema?: AgentToolOutputSchema<Output>;
   displayName?: string;
   icon?: string;
   display?: AgentToolDisplayMetadata;
 };
+type InferredAgentToolFactoryOptions<
+  InputSchema extends FlexibleSchema,
+  Output
+> = Omit<AgentToolFactoryOptions<Output>, "inputSchema"> & {
+  inputSchema: InputSchema;
+};
 /**
  * Create an AI SDK tool that dispatches a chat-capable sub-agent through
  * `Agent.runAgentTool`.
  */
+declare function agentTool<
+  InputSchema extends FlexibleSchema,
+  Output = unknown
+>(
+  cls: ChatCapableAgentClass,
+  options: InferredAgentToolFactoryOptions<InputSchema, Output>
+): Tool<InferSchema<InputSchema>, string | Output | AgentToolFailure>;
 declare function agentTool<Input = unknown, Output = unknown>(
   cls: ChatCapableAgentClass,
-  options: AgentToolFactoryOptions<Output>
+  options: AgentToolFactoryOptions<Output, Input>
 ): Tool<Input, string | Output | AgentToolFailure>;
 //#endregion
 export {

package/dist/agent-tools.js

@@ -1,6 +1,19 @@
-import { __DO_NOT_USE_WILL_BREAK__agentContext } from "./internal_context.js";
-import { tool } from "ai";
+import { t as __DO_NOT_USE_WILL_BREAK__agentContext } from "./current-agent-DhoDkSnH.js";
+import "./internal_context.js";
+import { asSchema, tool } from "ai";
 //#region src/agent-tools.ts
+/**
+* Preserve the existing Zod-style `.parse()` output-schema contract while
+* extending validation to the other formats supported by AI SDK FlexibleSchema.
+*/
+async function validateOutput(schema, value) {
+	if (typeof schema === "object" && schema !== null && "parse" in schema && typeof schema.parse === "function") return schema.parse(value);
+	const validate = asSchema(schema).validate;
+	if (!validate) throw new Error("agentTool outputSchema must provide runtime validation");
+	const result = await validate(value);
+	if (!result.success) throw result.error;
+	return result.value;
+}
 function currentAgentToolRunner() {
 	const agent = __DO_NOT_USE_WILL_BREAK__agentContext.getStore()?.agent;
 	if (agent === null || typeof agent !== "object" || typeof agent.runAgentTool !== "function") throw new Error("agentTool() can only run inside an Agent turn. Use it from getTools() on an Agent subclass.");
@@ -16,10 +29,6 @@ function failure(status, error, retryable, extra) {
 		...extra?.childStillRunning !== void 0 ? { childStillRunning: extra.childStillRunning } : {}
 	};
 }
-/**
-* Create an AI SDK tool that dispatches a chat-capable sub-agent through
-* `Agent.runAgentTool`.
-*/
 function agentTool(cls, options) {
 	return tool({
 		description: options.description,
@@ -41,7 +50,7 @@ function agentTool(cls, options) {
 			if (result.status === "completed") {
 				if (options.outputSchema) {
 					if (result.output === void 0) return failure("error", "agent tool completed without structured output required by outputSchema", false);
-					return options.outputSchema.parse(result.output);
+					return validateOutput(options.outputSchema, result.output);
 				}
 				return result.summary ?? "";
 			}

package/dist/agent-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-tools.js","names":["agentContext","createTool"],"sources":["../src/agent-tools.ts"],"sourcesContent":["import { tool, type Tool } from \"ai\";\nimport { __DO_NOT_USE_WILL_BREAK__agentContext as agentContext } from \"./internal_context\";\nimport type {\n  ChatCapableAgentClass,\n  RunAgentToolOptions,\n  RunAgentToolResult,\n  AgentToolDisplayMetadata,\n  AgentToolFailure\n} from \"./agent-tool-types\";\n\ntype SchemaLike<T = unknown> = {\n  parse(value: unknown): T;\n};\n\ntype AgentToolFactoryOptions<Output = unknown> = {\n  description: string;\n  inputSchema: unknown;\n  outputSchema?: SchemaLike<Output>;\n  displayName?: string;\n  icon?: string;\n  display?: AgentToolDisplayMetadata;\n};\n\ntype ToolExecutionOptions = {\n  toolCallId?: string;\n  abortSignal?: AbortSignal;\n};\n\ntype AgentToolRunner = {\n  runAgentTool<Input, Output>(\n    cls: ChatCapableAgentClass,\n    options: RunAgentToolOptions<Input>\n  ): Promise<RunAgentToolResult<Output>>;\n};\n\nfunction currentAgentToolRunner(): AgentToolRunner {\n  const agent = agentContext.getStore()?.agent;\n  if (\n    agent === null ||\n    typeof agent !== \"object\" ||\n    typeof (agent as { runAgentTool?: unknown }).runAgentTool !== \"function\"\n  ) {\n    throw new Error(\n      \"agentTool() can only run inside an Agent turn. Use it from getTools() on an Agent subclass.\"\n    );\n  }\n  return agent as AgentToolRunner;\n}\n\nfunction failure(\n  status: AgentToolFailure[\"status\"],\n  error: string,\n  retryable: boolean,\n  extra?: Pick<AgentToolFailure, \"reason\" | \"childStillRunning\">\n): AgentToolFailure {\n  return {\n    ok: false,\n    status,\n    error,\n    retryable,\n    ...(extra?.reason !== undefined ? { reason: extra.reason } : {}),\n    ...(extra?.childStillRunning !== undefined\n      ? { childStillRunning: extra.childStillRunning }\n      : {})\n  };\n}\n\n/**\n * Create an AI SDK tool that dispatches a chat-capable sub-agent through\n * `Agent.runAgentTool`.\n */\nexport function agentTool<Input = unknown, Output = unknown>(\n  cls: ChatCapableAgentClass,\n  options: AgentToolFactoryOptions<Output>\n): Tool<Input, string | Output | AgentToolFailure> {\n  const createTool = tool as unknown as <I, O>(config: {\n    description: string;\n    inputSchema: unknown;\n    execute: (input: I, options?: ToolExecutionOptions) => Promise<O>;\n  }) => Tool<I, O>;\n\n  return createTool<Input, string | Output | AgentToolFailure>({\n    description: options.description,\n    inputSchema: options.inputSchema,\n    execute: async (input: Input, executeOptions?: ToolExecutionOptions) => {\n      const display: AgentToolDisplayMetadata | undefined =\n        options.displayName || options.icon || options.display\n          ? {\n              ...options.display,\n              ...(options.displayName ? { name: options.displayName } : {}),\n              ...(options.icon ? { icon: options.icon } : {})\n            }\n          : undefined;\n\n      // Derive a STABLE runId from the tool call id (#1630). A tool call's id is\n      // preserved in the transcript, so when a parent turn is re-run by chat\n      // recovery after a deploy / eviction, the same `agentTool()` call resolves\n      // to the same runId — turning the re-issue into a duplicate that\n      // `runAgentTool` re-attaches to the still-running child, instead of a\n      // fresh `nanoid` that spawns a brand-new child and re-runs already-\n      // completed work (\"the agent went all the way back\"). Falls back to a\n      // fresh id only when there is no tool call id (rare; preserves prior\n      // behavior).\n      const runId = executeOptions?.toolCallId\n        ? `agent-tool:${executeOptions.toolCallId}`\n        : undefined;\n\n      const result = await currentAgentToolRunner().runAgentTool<Input, Output>(\n        cls,\n        {\n          input,\n          runId,\n          parentToolCallId: executeOptions?.toolCallId,\n          signal: executeOptions?.abortSignal,\n          display\n        }\n      );\n\n      if (result.status === \"completed\") {\n        if (options.outputSchema) {\n          if (result.output === undefined) {\n            return failure(\n              \"error\",\n              \"agent tool completed without structured output required by outputSchema\",\n              false\n            );\n          }\n          return options.outputSchema.parse(result.output);\n        }\n        return result.summary ?? \"\";\n      }\n\n      if (result.status === \"aborted\") {\n        // Intentional cancellation (parent/user stopped the run) — not retryable.\n        return failure(\n          \"aborted\",\n          result.error ?? \"agent tool run was cancelled\",\n          false\n        );\n      }\n      if (result.status === \"interrupted\") {\n        // The child was reset/superseded by a deploy or parent recovery before\n        // it reached a logical outcome. Re-dispatching the run can succeed, so\n        // surface it as retryable rather than a terminal failure the parent\n        // would report to the user as final. `retryable` is intentionally COARSE\n        // (always true for `interrupted`); callers that want to distinguish a\n        // self-healing child from an exhausted one branch on `reason` /\n        // `childStillRunning` instead.\n        return failure(\n          \"interrupted\",\n          result.error ??\n            \"agent tool run was interrupted before it finished; it can be retried\",\n          true,\n          { reason: result.reason, childStillRunning: result.childStillRunning }\n        );\n      }\n      return failure(\"error\", result.error ?? \"agent tool run failed\", false);\n    }\n  });\n}\n\nexport type { AgentToolFactoryOptions };\nexport type {\n  AgentToolChildAdapter,\n  AgentToolDisplayMetadata,\n  AgentToolEvent,\n  AgentToolEventMessage,\n  AgentToolEventState,\n  AgentToolFailure,\n  AgentToolInterruptedReason,\n  AgentToolLifecycleResult,\n  AgentToolRunInfo,\n  AgentToolRunInspection,\n  AgentToolRunPart,\n  AgentToolRunState,\n  AgentToolRunStatus,\n  AgentToolStoredChunk,\n  AgentToolTerminalStatus,\n  ChatCapableAgentClass,\n  DetachedAgentToolConfig,\n  DetachedRunAgentToolResult,\n  RunAgentToolOptions,\n  RunAgentToolResult\n} from \"./agent-tool-types\";\n"],"mappings":";;;AAmCA,SAAS,yBAA0C;CACjD,MAAM,QAAQA,sCAAa,SAAS,CAAC,EAAE;CACvC,IACE,UAAU,QACV,OAAO,UAAU,YACjB,OAAQ,MAAqC,iBAAiB,YAE9D,MAAM,IAAI,MACR,6FACF;CAEF,OAAO;AACT;AAEA,SAAS,QACP,QACA,OACA,WACA,OACkB;CAClB,OAAO;EACL,IAAI;EACJ;EACA;EACA;EACA,GAAI,OAAO,WAAW,KAAA,IAAY,EAAE,QAAQ,MAAM,OAAO,IAAI,CAAC;EAC9D,GAAI,OAAO,sBAAsB,KAAA,IAC7B,EAAE,mBAAmB,MAAM,kBAAkB,IAC7C,CAAC;CACP;AACF;;;;;AAMA,SAAgB,UACd,KACA,SACiD;CAOjD,OAAOC,KAAsD;EAC3D,aAAa,QAAQ;EACrB,aAAa,QAAQ;EACrB,SAAS,OAAO,OAAc,mBAA0C;GACtE,MAAM,UACJ,QAAQ,eAAe,QAAQ,QAAQ,QAAQ,UAC3C;IACE,GAAG,QAAQ;IACX,GAAI,QAAQ,cAAc,EAAE,MAAM,QAAQ,YAAY,IAAI,CAAC;IAC3D,GAAI,QAAQ,OAAO,EAAE,MAAM,QAAQ,KAAK,IAAI,CAAC;GAC/C,IACA,KAAA;GAWN,MAAM,QAAQ,gBAAgB,aAC1B,cAAc,eAAe,eAC7B,KAAA;GAEJ,MAAM,SAAS,MAAM,uBAAuB,CAAC,CAAC,aAC5C,KACA;IACE;IACA;IACA,kBAAkB,gBAAgB;IAClC,QAAQ,gBAAgB;IACxB;GACF,CACF;GAEA,IAAI,OAAO,WAAW,aAAa;IACjC,IAAI,QAAQ,cAAc;KACxB,IAAI,OAAO,WAAW,KAAA,GACpB,OAAO,QACL,SACA,2EACA,KACF;KAEF,OAAO,QAAQ,aAAa,MAAM,OAAO,MAAM;IACjD;IACA,OAAO,OAAO,WAAW;GAC3B;GAEA,IAAI,OAAO,WAAW,WAEpB,OAAO,QACL,WACA,OAAO,SAAS,gCAChB,KACF;GAEF,IAAI,OAAO,WAAW,eAQpB,OAAO,QACL,eACA,OAAO,SACL,wEACF,MACA;IAAE,QAAQ,OAAO;IAAQ,mBAAmB,OAAO;GAAkB,CACvE;GAEF,OAAO,QAAQ,SAAS,OAAO,SAAS,yBAAyB,KAAK;EACxE;CACF,CAAC;AACH"}
+{"version":3,"file":"agent-tools.js","names":["agentContext","createTool"],"sources":["../src/agent-tools.ts"],"sourcesContent":["import {\n  asSchema,\n  tool,\n  type FlexibleSchema,\n  type InferSchema,\n  type Tool\n} from \"ai\";\nimport { __DO_NOT_USE_WILL_BREAK__agentContext as agentContext } from \"./internal_context\";\nimport type {\n  ChatCapableAgentClass,\n  RunAgentToolOptions,\n  RunAgentToolResult,\n  AgentToolDisplayMetadata,\n  AgentToolFailure\n} from \"./agent-tool-types\";\n\ntype ParseSchema<Output = unknown> = {\n  parse(value: unknown): Output;\n};\n\ntype AgentToolOutputSchema<Output> =\n  | FlexibleSchema<Output>\n  | ParseSchema<Output>;\n\ntype AgentToolFactoryOptions<Output = unknown, Input = unknown> = {\n  description: string;\n  inputSchema: FlexibleSchema<Input>;\n  outputSchema?: AgentToolOutputSchema<Output>;\n  displayName?: string;\n  icon?: string;\n  display?: AgentToolDisplayMetadata;\n};\n\n// Capture the concrete schema type so the overload below can derive its input\n// with InferSchema. AgentToolFactoryOptions remains available for callers that\n// explicitly supply agentTool<Input, Output>() type arguments.\ntype InferredAgentToolFactoryOptions<\n  InputSchema extends FlexibleSchema,\n  Output\n> = Omit<AgentToolFactoryOptions<Output>, \"inputSchema\"> & {\n  inputSchema: InputSchema;\n};\n\ntype ToolExecutionOptions = {\n  toolCallId?: string;\n  abortSignal?: AbortSignal;\n};\n\ntype AgentToolRunner = {\n  runAgentTool<Input, Output>(\n    cls: ChatCapableAgentClass,\n    options: RunAgentToolOptions<Input>\n  ): Promise<RunAgentToolResult<Output>>;\n};\n\n/**\n * Preserve the existing Zod-style `.parse()` output-schema contract while\n * extending validation to the other formats supported by AI SDK FlexibleSchema.\n */\nasync function validateOutput<Output>(\n  schema: AgentToolOutputSchema<Output>,\n  value: unknown\n): Promise<Output> {\n  if (\n    typeof schema === \"object\" &&\n    schema !== null &&\n    \"parse\" in schema &&\n    typeof schema.parse === \"function\"\n  ) {\n    return schema.parse(value);\n  }\n\n  const validate = asSchema(schema as FlexibleSchema<Output>).validate;\n  if (!validate) {\n    throw new Error(\"agentTool outputSchema must provide runtime validation\");\n  }\n\n  const result = await validate(value);\n  if (!result.success) throw result.error;\n  return result.value;\n}\n\nfunction currentAgentToolRunner(): AgentToolRunner {\n  const agent = agentContext.getStore()?.agent;\n  if (\n    agent === null ||\n    typeof agent !== \"object\" ||\n    typeof (agent as { runAgentTool?: unknown }).runAgentTool !== \"function\"\n  ) {\n    throw new Error(\n      \"agentTool() can only run inside an Agent turn. Use it from getTools() on an Agent subclass.\"\n    );\n  }\n  return agent as AgentToolRunner;\n}\n\nfunction failure(\n  status: AgentToolFailure[\"status\"],\n  error: string,\n  retryable: boolean,\n  extra?: Pick<AgentToolFailure, \"reason\" | \"childStillRunning\">\n): AgentToolFailure {\n  return {\n    ok: false,\n    status,\n    error,\n    retryable,\n    ...(extra?.reason !== undefined ? { reason: extra.reason } : {}),\n    ...(extra?.childStillRunning !== undefined\n      ? { childStillRunning: extra.childStillRunning }\n      : {})\n  };\n}\n\n/**\n * Create an AI SDK tool that dispatches a chat-capable sub-agent through\n * `Agent.runAgentTool`.\n */\nexport function agentTool<InputSchema extends FlexibleSchema, Output = unknown>(\n  cls: ChatCapableAgentClass,\n  options: InferredAgentToolFactoryOptions<InputSchema, Output>\n): Tool<InferSchema<InputSchema>, string | Output | AgentToolFailure>;\n// Preserve existing callers that explicitly provide agentTool<Input, Output>().\nexport function agentTool<Input = unknown, Output = unknown>(\n  cls: ChatCapableAgentClass,\n  options: AgentToolFactoryOptions<Output, Input>\n): Tool<Input, string | Output | AgentToolFailure>;\nexport function agentTool<Input = unknown, Output = unknown>(\n  cls: ChatCapableAgentClass,\n  options: AgentToolFactoryOptions<Output, Input>\n): Tool<Input, string | Output | AgentToolFailure> {\n  const createTool = tool as unknown as <I, O>(config: {\n    description: string;\n    inputSchema: unknown;\n    execute: (input: I, options?: ToolExecutionOptions) => Promise<O>;\n  }) => Tool<I, O>;\n\n  return createTool<Input, string | Output | AgentToolFailure>({\n    description: options.description,\n    inputSchema: options.inputSchema,\n    execute: async (input: Input, executeOptions?: ToolExecutionOptions) => {\n      const display: AgentToolDisplayMetadata | undefined =\n        options.displayName || options.icon || options.display\n          ? {\n              ...options.display,\n              ...(options.displayName ? { name: options.displayName } : {}),\n              ...(options.icon ? { icon: options.icon } : {})\n            }\n          : undefined;\n\n      // Derive a STABLE runId from the tool call id (#1630). A tool call's id is\n      // preserved in the transcript, so when a parent turn is re-run by chat\n      // recovery after a deploy / eviction, the same `agentTool()` call resolves\n      // to the same runId — turning the re-issue into a duplicate that\n      // `runAgentTool` re-attaches to the still-running child, instead of a\n      // fresh `nanoid` that spawns a brand-new child and re-runs already-\n      // completed work (\"the agent went all the way back\"). Falls back to a\n      // fresh id only when there is no tool call id (rare; preserves prior\n      // behavior).\n      const runId = executeOptions?.toolCallId\n        ? `agent-tool:${executeOptions.toolCallId}`\n        : undefined;\n\n      const result = await currentAgentToolRunner().runAgentTool<Input, Output>(\n        cls,\n        {\n          input,\n          runId,\n          parentToolCallId: executeOptions?.toolCallId,\n          signal: executeOptions?.abortSignal,\n          display\n        }\n      );\n\n      if (result.status === \"completed\") {\n        if (options.outputSchema) {\n          if (result.output === undefined) {\n            return failure(\n              \"error\",\n              \"agent tool completed without structured output required by outputSchema\",\n              false\n            );\n          }\n          return validateOutput(options.outputSchema, result.output);\n        }\n        return result.summary ?? \"\";\n      }\n\n      if (result.status === \"aborted\") {\n        // Intentional cancellation (parent/user stopped the run) — not retryable.\n        return failure(\n          \"aborted\",\n          result.error ?? \"agent tool run was cancelled\",\n          false\n        );\n      }\n      if (result.status === \"interrupted\") {\n        // The child was reset/superseded by a deploy or parent recovery before\n        // it reached a logical outcome. Re-dispatching the run can succeed, so\n        // surface it as retryable rather than a terminal failure the parent\n        // would report to the user as final. `retryable` is intentionally COARSE\n        // (always true for `interrupted`); callers that want to distinguish a\n        // self-healing child from an exhausted one branch on `reason` /\n        // `childStillRunning` instead.\n        return failure(\n          \"interrupted\",\n          result.error ??\n            \"agent tool run was interrupted before it finished; it can be retried\",\n          true,\n          { reason: result.reason, childStillRunning: result.childStillRunning }\n        );\n      }\n      return failure(\"error\", result.error ?? \"agent tool run failed\", false);\n    }\n  });\n}\n\nexport type { AgentToolFactoryOptions };\nexport type {\n  AgentToolChildAdapter,\n  AgentToolDisplayMetadata,\n  AgentToolEvent,\n  AgentToolEventMessage,\n  AgentToolEventState,\n  AgentToolFailure,\n  AgentToolInterruptedReason,\n  AgentToolLifecycleResult,\n  AgentToolRunInfo,\n  AgentToolRunInspection,\n  AgentToolRunPart,\n  AgentToolRunState,\n  AgentToolRunStatus,\n  AgentToolStoredChunk,\n  AgentToolTerminalStatus,\n  ChatCapableAgentClass,\n  DetachedAgentToolConfig,\n  DetachedRunAgentToolResult,\n  RunAgentToolOptions,\n  RunAgentToolResult\n} from \"./agent-tool-types\";\n"],"mappings":";;;;;;;;AA2DA,eAAe,eACb,QACA,OACiB;CACjB,IACE,OAAO,WAAW,YAClB,WAAW,QACX,WAAW,UACX,OAAO,OAAO,UAAU,YAExB,OAAO,OAAO,MAAM,KAAK;CAG3B,MAAM,WAAW,SAAS,MAAgC,CAAC,CAAC;CAC5D,IAAI,CAAC,UACH,MAAM,IAAI,MAAM,wDAAwD;CAG1E,MAAM,SAAS,MAAM,SAAS,KAAK;CACnC,IAAI,CAAC,OAAO,SAAS,MAAM,OAAO;CAClC,OAAO,OAAO;AAChB;AAEA,SAAS,yBAA0C;CACjD,MAAM,QAAQA,sCAAa,SAAS,CAAC,EAAE;CACvC,IACE,UAAU,QACV,OAAO,UAAU,YACjB,OAAQ,MAAqC,iBAAiB,YAE9D,MAAM,IAAI,MACR,6FACF;CAEF,OAAO;AACT;AAEA,SAAS,QACP,QACA,OACA,WACA,OACkB;CAClB,OAAO;EACL,IAAI;EACJ;EACA;EACA;EACA,GAAI,OAAO,WAAW,KAAA,IAAY,EAAE,QAAQ,MAAM,OAAO,IAAI,CAAC;EAC9D,GAAI,OAAO,sBAAsB,KAAA,IAC7B,EAAE,mBAAmB,MAAM,kBAAkB,IAC7C,CAAC;CACP;AACF;AAeA,SAAgB,UACd,KACA,SACiD;CAOjD,OAAOC,KAAsD;EAC3D,aAAa,QAAQ;EACrB,aAAa,QAAQ;EACrB,SAAS,OAAO,OAAc,mBAA0C;GACtE,MAAM,UACJ,QAAQ,eAAe,QAAQ,QAAQ,QAAQ,UAC3C;IACE,GAAG,QAAQ;IACX,GAAI,QAAQ,cAAc,EAAE,MAAM,QAAQ,YAAY,IAAI,CAAC;IAC3D,GAAI,QAAQ,OAAO,EAAE,MAAM,QAAQ,KAAK,IAAI,CAAC;GAC/C,IACA,KAAA;GAWN,MAAM,QAAQ,gBAAgB,aAC1B,cAAc,eAAe,eAC7B,KAAA;GAEJ,MAAM,SAAS,MAAM,uBAAuB,CAAC,CAAC,aAC5C,KACA;IACE;IACA;IACA,kBAAkB,gBAAgB;IAClC,QAAQ,gBAAgB;IACxB;GACF,CACF;GAEA,IAAI,OAAO,WAAW,aAAa;IACjC,IAAI,QAAQ,cAAc;KACxB,IAAI,OAAO,WAAW,KAAA,GACpB,OAAO,QACL,SACA,2EACA,KACF;KAEF,OAAO,eAAe,QAAQ,cAAc,OAAO,MAAM;IAC3D;IACA,OAAO,OAAO,WAAW;GAC3B;GAEA,IAAI,OAAO,WAAW,WAEpB,OAAO,QACL,WACA,OAAO,SAAS,gCAChB,KACF;GAEF,IAAI,OAAO,WAAW,eAQpB,OAAO,QACL,eACA,OAAO,SACL,wEACF,MACA;IAAE,QAAQ,OAAO;IAAQ,mBAAmB,OAAO;GAAkB,CACvE;GAEF,OAAO,QAAQ,SAAS,OAAO,SAAS,yBAAyB,KAAK;EACxE;CACF,CAAC;AACH"}

package/dist/browser/ai.d.ts

@@ -5,7 +5,7 @@ import {
   t as BrowserConnector,
   v as QuickActionBinding,
   y as QuickActionCommonOptions
-} from "../connector-v2M1zlZp.js";
+} from "../connector-CkQD4MK3.js";
 import { ToolSet } from "ai";
 import { CodemodeRuntimeHandle } from "@cloudflare/codemode";
 
@@ -80,8 +80,10 @@ interface CreateBrowserToolsOptions {
    * `browser_execute` tool.
    *
    * Enabled by default whenever a Browser Run `browser` binding is available
-   * (they share it). Pass an object to configure them, or `false` to disable.
-   * The Quick Action binding defaults to `browser`; override it via
+   * (they share it), except when `session.browser` selects Kitesurf because
+   * the binding RPC cannot select that engine. Pass `true` or an object to
+   * explicitly add Chromium Quick Actions alongside Kitesurf, or `false` to
+   * disable them. The Quick Action binding defaults to `browser`; override it via
    * `quickActions.browser`. When only `cdpUrl` is set (no binding), the
    * defaults are skipped silently — pass `quickActions: { browser }` to force
    * them.