@economic/agents 2.10.6 → 2.11.0

package/README.md

@@ -301,6 +301,17 @@ getTools(): ToolSet {
 
 `authorize` returning `false` hides the tool for that request.
 
+Use `approval` when an ordinary tool needs the AI SDK's basic approval gate. The SDK translates it to the upstream `needsApproval` option; `needsApproval` remains supported for backwards compatibility, but do not supply both.
+
+```typescript
+const export_report = tool({
+  description: "Export a report",
+  inputSchema: z.object({ reportId: z.string() }),
+  approval: true,
+  execute: async ({ reportId }) => exportReport(reportId),
+});
+```
+
 ### Tool context
 
 The tool context is the second argument to `execute` — `experimental_context`:
@@ -325,6 +336,72 @@ const call_api = tool({
 
 `ToolContext<RequestContext, UserContext>` is `RequestContext & { _userContext?: UserContext }`. Request context comes from the client (`toolContext` in the hooks); `_userContext` comes from [`getUserContext`](#user-context) when using JWT Authentication (via `getJwtAuthConfig`).
 
+## Actions
+
+Use `action()` instead of `tool()` for operations with side effects. Actions use Cloudflare Think's durable action ledger for idempotent execution, settled-result replay, pending-action handling, recovery, timeouts, cancellation, and structured errors.
+
+The SDK enables approval by default. `approval` may be `true`, `false`, or a predicate; `approvalSummary` and `approvalRisk` provide the metadata shown by an approval UI.
+
+```typescript
+import { action, skill, type ToolContext } from "@economic/agents";
+import { z } from "zod";
+
+interface RequestContext extends Record<string, unknown> {
+  tokens: Record<string, string>;
+}
+
+const deleteInput = z.object({ invoiceId: z.string() });
+
+const deleteInvoice = action<ToolContext<RequestContext>, typeof deleteInput>({
+  description: "Delete a draft invoice",
+  inputSchema: deleteInput,
+
+  // This identifies the business operation across retries. Do not use a
+  // timestamp, random value, or request id.
+  idempotencyKey: ({ input }) => `invoice:${input.invoiceId}:delete`,
+
+  approvalSummary: "Delete draft invoice",
+  approvalRisk: "high",
+
+  execute: async (input, ctx) => {
+    const response = await fetch(`/api/invoices/${input.invoiceId}`, {
+      method: "DELETE",
+      headers: {
+        Authorization: ctx.experimental_context.tokens.Authorization ?? "",
+        // Think uses this key for its ledger. Forward it when the downstream
+        // API also supports idempotency.
+        "Idempotency-Key": ctx.idempotencyKey,
+      },
+      signal: ctx.signal,
+    });
+
+    return { deleted: response.ok };
+  },
+});
+
+export const invoiceSkill = skill({
+  name: "invoices",
+  description: "View and manage invoices.",
+  instructions: "Use delete_draft_invoice only for draft invoices.",
+  actions: {
+    delete_draft_invoice: deleteInvoice,
+  },
+});
+```
+
+An action receives the same tool execution data plus Cloudflare's native action fields:
+
+- `experimental_context` — the typed `ToolContext` supplied to ordinary tools.
+- `toolCallId`, `messages`, and `abortSignal` — the ordinary tool execution fields.
+- `idempotencyKey` — the resolved domain key, or the tool-call fallback when none was declared.
+- `requestId`, `signal`, `agent`, `env`, and `attachReply` — native Think action fields.
+
+`authorize` and `onUnauthorized` behave exactly as they do on `tool()`. Native action options such as `permissions`, `kind`, `timeoutMs`, `approval`, `approvalSummary`, and `approvalRisk` pass through unchanged.
+
+Define an explicit `idempotencyKey` for actions that must deduplicate across recovery retries. Without one, Think falls back to `toolCallId`, which only deduplicates that particular tool call. The action ledger does not make an external API idempotent: forward `ctx.idempotencyKey` to the API, adapting its format if required. If one action performs several writes, derive a stable child key for each write rather than reusing one downstream key.
+
+Cloudflare currently marks Think Actions as experimental, so this SDK surface may evolve with the upstream API.
+
 ## Skills
 
 The SDK supports two skill styles:
@@ -336,7 +413,7 @@ Use skills when a capability should be loaded on demand instead of living in the
 
 ### Code-defined skills
 
-A code-defined skill bundles markdown `instructions` with optional tools. Only `description` sits in the system prompt; the model loads the instructions and tools on demand.
+A code-defined skill bundles markdown `instructions` with optional tools and actions. Only `description` sits in the system prompt; the model loads the instructions, tools, and actions on demand.
 
 ```typescript
 import { skill, tool } from "@economic/agents";
@@ -583,13 +660,14 @@ Imported from `@economic/agents` unless noted.
 
 ### Helpers and types
 
-| Export                                                                   | Description                                                                     |
-| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
-| `tool(def)` / `Tool` / `ToolSet`                                         | Define a tool with an optional `authorize(ctx)` guard.                          |
-| `skill(def)` / `Skill`                                                   | Define a skill (`name`, `description`, `instructions`, `tools?`, `authorize?`). |
-| `ToolContext`                                                            | `RequestContext & { _userContext?: UserContext }`.                              |
-| `AgentEnv`                                                               | The bindings the runtime expects.                                               |
-| `AgentConnectionState` / `AgentConnectionStatus` / `AgentConnectionType` | Connection state shared with the client.                                        |
+| Export                                                                   | Description                                                                |
+| ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| `tool(def)` / `Tool` / `ToolSet`                                         | Define a tool with optional `approval`, `authorize`, and `onUnauthorized`. |
+| `action(def)` / `Action` / `ActionConfig` / `ActionContext`              | Define a ledger-backed action with approval and idempotency support.       |
+| `skill(def)` / `Skill`                                                   | Define a skill with optional `tools`, `actions`, and authorization.        |
+| `ToolContext`                                                            | `RequestContext & { _userContext?: UserContext }`.                         |
+| `AgentEnv`                                                               | The bindings the runtime expects.                                          |
+| `AgentConnectionState` / `AgentConnectionStatus` / `AgentConnectionType` | Connection state shared with the client.                                   |
 
 ### Members
 

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { Agent as Agent$1, AgentOptions, Connection, ConnectionContext, SubAgentClass } from "agents";
-import { ChatResponseResult, PrepareStepContext, Session, Think, ToolCallContext, ToolCallDecision, TurnConfig, TurnContext, skills } from "@cloudflare/think";
-import { JSONValue, LanguageModel, ModelMessage, Tool as Tool$1, UIMessage } from "ai";
+import { Action as Action$1, ActionConfig as ActionConfig$1, ActionContext as ActionContext$1, ChatResponseResult, PrepareStepContext, Session, Think, ToolCallContext, ToolCallDecision, TurnConfig, TurnContext, skills } from "@cloudflare/think";
+import { FlexibleSchema, InferSchema, JSONValue, LanguageModel, ModelMessage, Tool as Tool$1, ToolExecutionOptions, UIMessage } from "ai";
 import { Observability } from "agents/observability";
 import { createCompactFunction } from "agents/experimental/memory/utils";
 import { SkillSource as SkillSource$1 } from "agents/skills";
@@ -110,10 +110,11 @@ interface UnauthorizedToolPolicy<Context extends Record<string, unknown> = Recor
   reason: string | ((ctx?: Context) => string);
 }
 type Tool<Context extends Record<string, unknown> = Record<string, unknown>, INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any> = Tool$1<INPUT, OUTPUT> & {
+  /** SDK-consistent alias for the AI SDK's `needsApproval` option. */approval?: Tool$1<INPUT, OUTPUT>["needsApproval"];
   authorize?: (ctx?: Context) => boolean;
   onUnauthorized?: UnauthorizedToolPolicy<Context>;
 };
-declare function tool<Context extends Record<string, unknown> = Record<string, unknown>, INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any>(tool: Tool<Context, INPUT, OUTPUT>): Tool$1<INPUT, OUTPUT>;
+declare function tool<Context extends Record<string, unknown> = Record<string, unknown>, INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any>(definition: Tool<Context, INPUT, OUTPUT>): Tool$1<INPUT, OUTPUT>;
 //#endregion
 //#region src/server/agents/Agent.d.ts
 /** What the model would see on its next step — returned by {@link Agent.inspectTurn}. */
@@ -125,6 +126,14 @@ interface TurnSnapshot {
   frameworkToolNames: string[];
   messages: ModelMessage[];
 }
+type Authentication<UserContext> = {
+  success: true;
+  userContext?: UserContext;
+} | {
+  success: false;
+  status: 401 | 403 | 500;
+  message: string;
+};
 declare abstract class Agent<RequestContext extends Record<string, unknown> = Record<string, unknown>, UserContext extends Record<string, unknown> = Record<string, unknown>, State = unknown> extends Think<Cloudflare.Env & AgentEnv, State> {
   protected agentType: AgentConnectionType;
   protected clientIp?: string;
@@ -166,6 +175,8 @@ declare abstract class Agent<RequestContext extends Record<string, unknown> = Re
   }>;
   beforeToolCall(ctx: ToolCallContext): Promise<ToolCallDecision | void>;
   getTools(): ToolSet;
+  /** Collects the actions declared by this agent's skills for Think to compile. */
+  getActions(): Promise<Record<string, Action$1>>;
   /**
    * Read-only: what the model would see on its next step for the given history
    * — the assembled system prompt, the skill-gated toolset, and pruned
@@ -215,8 +226,10 @@ declare abstract class Agent<RequestContext extends Record<string, unknown> = Re
    */
   private _withTurnContextFallback;
   private _getLastActivatedSkillName;
+  /** Verifies the request and prepares the same user context for WebSocket and HTTP requests. */
+  protected authenticate(request: Request): Promise<Authentication<UserContext>>;
   /**
-   * Override to enable JWT authentication on WebSocket connections.
+   * Override to enable JWT authentication on WebSocket and HTTP requests.
    * Return the auth config based on the incoming request, or undefined to skip auth.
    * Do not add side effects to this method - return a single JwtAuthConfig from it.
    *
@@ -231,8 +244,8 @@ declare abstract class Agent<RequestContext extends Record<string, unknown> = Re
    * When configured, the exchanged token is passed to {@link getUserContext}
    * and injected into the tool context every turn under
    * `tokens[config.tokenHeader]` — client-sent request-body tokens for that
-   * key are ignored. Renewal is connection-based: a client presenting a new
-   * token reconnects, and the connect flow re-verifies and re-exchanges.
+   * key are ignored. Each authenticated WebSocket connection or HTTP request
+   * re-verifies and re-exchanges the client token.
    *
    * Do not add side effects to this method - return a single config from it,
    * or undefined to disable the exchange.
@@ -323,6 +336,12 @@ declare abstract class ChatAgent<RequestContext extends Record<string, unknown>
   configureSession(session: Session): Session;
   beforeTurn(ctx: TurnContext): Promise<void | TurnConfig>;
   onChatResponse(result: ChatResponseResult): Promise<void>;
+  onRequest(request: Request): Promise<Response>;
+  /**
+   * Runs the turn from the stream's start callback so the response can be
+   * returned immediately and each event reaches the client as it is produced.
+   */
+  private streamMessage;
   /**
    * Submit feedback for a message by its id.
    * @param messageId - The id of the message to give feedback on.
@@ -357,6 +376,8 @@ declare abstract class Assistant<State = unknown> extends Agent$1<Cloudflare.Env
   protected abstract agent: SubAgentClass<ChatAgent>;
   onStart(): void;
   onConnect(connection: Connection, ctx: ConnectionContext): Promise<void>;
+  private authenticate;
+  onRequest(request: Request): Promise<Response>;
   createChat(): Promise<string>;
   deleteChat(id: string): Promise<void>;
   renameChat(id: string, title: string): Promise<void>;
@@ -388,16 +409,36 @@ declare abstract class Assistant<State = unknown> extends Agent$1<Cloudflare.Env
   observability?: Observability;
 }
 //#endregion
+//#region src/server/util/actions.d.ts
+/** Tool execution options plus the additional context supplied by native Think actions. */
+type ActionContext<Context extends Record<string, unknown> = Record<string, unknown>> = Omit<ToolExecutionOptions, "experimental_context"> & ActionContext$1 & {
+  experimental_context: Context; /** The action's resolved domain key, or its tool-call fallback when none was declared. */
+  idempotencyKey: string;
+};
+type ActionConfig<Context extends Record<string, unknown>, InputSchema extends FlexibleSchema, Output = unknown> = Omit<ActionConfig$1<InputSchema, Output>, "execute"> & {
+  authorize?: (ctx?: Context) => boolean;
+  onUnauthorized?: UnauthorizedToolPolicy<Context>;
+  execute(input: InferSchema<InputSchema>, ctx: ActionContext<Context>): Promise<Output> | Output;
+};
+type Action<Context extends Record<string, unknown> = Record<string, unknown>, InputSchema extends FlexibleSchema = FlexibleSchema, Output = unknown> = Action$1<InputSchema, Output> & {
+  authorize?: (ctx?: Context) => boolean;
+  onUnauthorized?: UnauthorizedToolPolicy<Context>;
+};
+/** A native Think action with the SDK's standard authorization policy. */
+declare function action<Context extends Record<string, unknown> = Record<string, unknown>, const InputSchema extends FlexibleSchema = FlexibleSchema, Output = unknown>(definition: ActionConfig<Context, InputSchema, Output>): Action<Context, InputSchema, Output>;
+//#endregion
 //#region src/server/util/skills.d.ts
 interface Skill<Context extends Record<string, unknown> = Record<string, unknown>> {
   name: string;
   description: string;
   instructions: string;
   tools?: Record<string, Tool<Context>>;
+  actions?: Record<string, Action<Context, any, any>>;
   authorize?: (ctx?: Context) => boolean;
 }
 interface SkillSource<Context extends Record<string, unknown> = Record<string, unknown>> extends SkillSource$1 {
   tools?: Record<string, Tool<Context>>;
+  actions?: Record<string, Action<Context, any, any>>;
   authorize?: (ctx?: Context | undefined) => boolean;
 }
 declare function skill<Context extends Record<string, unknown> = Record<string, unknown>>(definition: Skill<Context>): SkillSource<Context>;
@@ -408,4 +449,4 @@ declare function routeAgentRequest<Env>(request: Request, env: Env, options?: Ag
 //#region src/server/index.d.ts
 declare function getCurrentToolContext(): any;
 //#endregion
-export { Agent, type AgentConnectionStatus, type AgentConnectionType, type AgentEnv, Assistant, ChatAgent, type ExchangedToken, type JwtAuthConfig, type Skill, type SkillSource, type TokenExchangeConfig, type TokenExchangeResult, type Tool, type ToolContext, type ToolSet, type TurnSnapshot, type UnauthorizedToolPolicy, createJwtAuthConfig, exchangeToken, getCurrentToolContext, routeAgentRequest, skill, tool };
+export { type Action, type ActionConfig, type ActionContext, Agent, type AgentConnectionStatus, type AgentConnectionType, type AgentEnv, Assistant, ChatAgent, type ExchangedToken, type JwtAuthConfig, type Skill, type SkillSource, type TokenExchangeConfig, type TokenExchangeResult, type Tool, type ToolContext, type ToolSet, type TurnSnapshot, type UnauthorizedToolPolicy, action, createJwtAuthConfig, exchangeToken, getCurrentToolContext, routeAgentRequest, skill, tool };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { Agent as Agent$1, callable, getCurrentAgent, routeAgentRequest as routeAgentRequest$1 } from "agents";
-import { Think, skills } from "@cloudflare/think";
+import { Think, action as action$1, skills } from "@cloudflare/think";
 import { Output, convertToModelMessages, generateText, jsonSchema, pruneMessages, tool as tool$1 } from "ai";
 import { createRemoteJWKSet, decodeJwt, errors, jwtVerify } from "jose";
 import { BasicTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
@@ -243,39 +243,6 @@ function withExchangedToken(body, tokenHeader, accessToken) {
 	};
 }
 /**
-* Connect-time exchange. On failure, signals the client and closes the
-* connection — `unauthorized`/4001 when the session token itself was rejected
-* (only a re-login fixes that), `error`/1011 for identity-server or
-* configuration faults — and returns undefined so the caller abandons the
-* connect.
-*/
-async function exchangeConnectToken(subjectToken, config, connection) {
-	let result;
-	try {
-		result = await exchangeToken(subjectToken, config);
-	} catch (error) {
-		sendConnectionStatus(connection, "error");
-		console.error(`[Agent] Token exchange error - ${error}`);
-		connection.close(1011, "Token exchange failed");
-		return;
-	}
-	if (!result.success) {
-		console.error(`[Agent] Token exchange failed - ${result.message}`);
-		if (result.subjectTokenRejected) {
-			sendConnectionStatus(connection, "unauthorized");
-			connection.close(4001, "Unauthorized");
-		} else {
-			sendConnectionStatus(connection, "error");
-			connection.close(1011, "Token exchange failed");
-		}
-		return;
-	}
-	return {
-		accessToken: result.accessToken,
-		expiresAt: result.expiresAt
-	};
-}
-/**
 * Turn-time injection: returns a body copy with the held token under
 * `tokens[config.tokenHeader]`. When the held token is missing or expired the
 * turn cannot run — only a re-authenticating reconnect delivers a fresh
@@ -294,8 +261,13 @@ function injectExchangedToken(body, config, token, connection) {
 }
 //#endregion
 //#region src/server/util/tools.ts
-function tool(tool) {
-	return tool$1(tool);
+function tool(definition) {
+	const { approval, ...tool } = definition;
+	if (approval !== void 0 && tool.needsApproval !== void 0) throw new Error("tool() accepts either approval or needsApproval, not both");
+	return tool$1({
+		...tool,
+		...approval !== void 0 ? { needsApproval: approval } : {}
+	});
 }
 /**
 * Wrap each tool's `execute` so it falls back to `getFallbackContext()` for
@@ -962,61 +934,16 @@ var Agent = class extends Think {
 		sendConnectionStatus(connection, "connecting");
 		this.clientIp = ctx.request.headers.get("CF-Connecting-IP") ?? ctx.request.headers.get("X-Forwarded-For")?.split(",")[0]?.trim();
 		this.forwardedFor = ctx.request.headers.get("X-Forwarded-For") ?? void 0;
-		const getJwtAuthConfig = this.constructor.getJwtAuthConfig;
-		if (getJwtAuthConfig) {
-			const config = getJwtAuthConfig(this.env);
-			if (config) {
-				let result;
-				try {
-					result = await verifyJwt(ctx.request, config);
-				} catch (error) {
-					sendConnectionStatus(connection, "unauthorized");
-					console.error(`[Agent] JWT verification error - ${error}`);
-					connection.close(4001, "Unauthorized");
-					return;
-				}
-				if (!result.success) {
-					sendConnectionStatus(connection, "unauthorized");
-					console.error(`[Agent] JWT verification error - ${result.message}`);
-					connection.close(result.status === 401 ? 4001 : 4003, result.message);
-					return;
-				}
-				if (!isJwtActorAuthorized(config, result.claims, {
-					durableObjectName: this.name,
-					parentPath: this.parentPath
-				})) {
-					sendConnectionStatus(connection, "unauthorized");
-					console.error("[Agent] Authenticated actor does not own the requested agent", {
-						authenticatedActorId: config.getActorId(result.claims),
-						requiredActorId: getTargetActorId({
-							durableObjectName: this.name,
-							parentPath: this.parentPath
-						}),
-						durableObjectName: this.name
-					});
-					connection.close(4003, "Forbidden");
-					return;
-				}
-				const token = extractTokenFromConnectRequest(ctx.request);
-				let effectiveToken = token;
-				const getTokenExchangeConfig = this.constructor.getTokenExchangeConfig;
-				const exchangeConfig = getTokenExchangeConfig?.(this.env);
-				if (token && exchangeConfig) {
-					const exchanged = await exchangeConnectToken(token, exchangeConfig, connection);
-					if (!exchanged) return;
-					await this._storeExchangedToken(exchanged);
-					effectiveToken = exchanged.accessToken;
-				}
-				if (effectiveToken && this.getUserContext) try {
-					connection.setState({ userContext: await this.getUserContext(effectiveToken) });
-				} catch (error) {
-					const closeCode = getConnectCloseCode(error);
-					sendConnectionStatus(connection, closeCode === 1011 ? "error" : "unauthorized");
-					console.error(`[Agent] getUserContext error - ${error}`);
-					connection.close(closeCode, "Could not establish user context");
-					return;
-				}
-			}
+		const auth = await this.authenticate(ctx.request);
+		if (!auth.success) {
+			const closeCode = auth.status === 401 ? 4001 : auth.status === 403 ? 4003 : 1011;
+			sendConnectionStatus(connection, closeCode === 1011 ? "error" : "unauthorized");
+			connection.close(closeCode, auth.message);
+			return;
+		}
+		if (auth.userContext) {
+			this.userContext = auth.userContext;
+			connection.setState({ userContext: auth.userContext });
 		}
 		sendConnectionStatus(connection, "connected");
 	}
@@ -1031,7 +958,7 @@ var Agent = class extends Think {
 		const connectionState = getCurrentAgent().connection?.state;
 		return {
 			...requestContext,
-			_userContext: connectionState?.userContext
+			_userContext: connectionState?.userContext ?? this.userContext
 		};
 	}
 	/**
@@ -1121,6 +1048,12 @@ var Agent = class extends Think {
 	getTools() {
 		return {};
 	}
+	/** Collects the actions declared by this agent's skills for Think to compile. */
+	async getActions() {
+		const actions = {};
+		for (const skill of await this.getSkills()) Object.assign(actions, skill.actions);
+		return actions;
+	}
 	/**
 	* Read-only: what the model would see on its next step for the given history
 	* — the assembled system prompt, the skill-gated toolset, and pruned
@@ -1151,8 +1084,10 @@ var Agent = class extends Think {
 				...think._skillRegistry?.tools(),
 				...think.mcp?.getAITools?.()
 			};
+			const actionTools = await think._compileActionTools?.() ?? {};
 			const inputTools = {
 				...this.getTools(),
+				...actionTools,
 				...frameworkTools
 			};
 			this._turn.inputTools = inputTools;
@@ -1207,7 +1142,18 @@ var Agent = class extends Think {
 		const unavailableSkillIds = /* @__PURE__ */ new Set();
 		let hasActionTool = false;
 		let hasAuthorizedActionTool = false;
-		const configureTool = (name, tool, trackRestriction = true) => {
+		const skillSources = await this.getSkills();
+		const registeredActions = await this.getActions();
+		const actionsByToolName = /* @__PURE__ */ new Map();
+		const skillActionNames = /* @__PURE__ */ new Set();
+		for (const [registrationName, definition] of Object.entries(registeredActions)) actionsByToolName.set(definition.config.name ?? registrationName, definition);
+		for (const skill of skillSources) for (const [registrationName, definition] of Object.entries(skill.actions ?? {})) skillActionNames.add(definition.config.name ?? registrationName);
+		const configureTool = (name, tool, trackRestriction = true, authorization = tool) => {
+			tool = {
+				...tool,
+				authorize: authorization.authorize,
+				onUnauthorized: authorization.onUnauthorized
+			};
 			const authorized = tool.authorize?.(ctx) !== false;
 			if (tool.needsApproval) {
 				hasActionTool = true;
@@ -1234,11 +1180,18 @@ var Agent = class extends Think {
 			tools[name] = tool;
 			return true;
 		};
-		for (const [name, tool] of Object.entries(inputTools)) if (configureTool(name, tool)) activeTools.push(name);
-		const skillSources = await this.getSkills();
+		for (const [name, tool] of Object.entries(inputTools)) {
+			if (skillActionNames.has(name)) continue;
+			if (configureTool(name, tool, true, actionsByToolName.get(name))) activeTools.push(name);
+		}
 		for (const skill of skillSources) {
 			const skillAuthorized = skill.authorize?.(ctx) !== false;
-			const skillTools = Object.entries(skill.tools ?? {});
+			const skillTools = [...Object.entries(skill.tools ?? {})];
+			for (const [registrationName, definition] of Object.entries(skill.actions ?? {})) {
+				const name = definition.config.name ?? registrationName;
+				const compiled = inputTools[name];
+				if (compiled) skillTools.push([name, compiled]);
+			}
 			let hasVisibleTool = false;
 			for (const [name, tool] of skillTools) {
 				if (!skillAuthorized) {
@@ -1247,13 +1200,14 @@ var Agent = class extends Think {
 					continue;
 				}
 				const needsApproval = tool.needsApproval;
-				const visible = configureTool(name, tool.authorize && needsApproval ? {
+				const preparedTool = tool.authorize && needsApproval ? {
 					...tool,
 					needsApproval: async (input, options) => {
 						if (tool.authorize?.(ctx) === false) return false;
 						return typeof needsApproval === "function" ? needsApproval(input, options) : needsApproval;
 					}
-				} : tool, false);
+				} : tool;
+				const visible = configureTool(name, preparedTool, false, actionsByToolName.get(name) ?? preparedTool);
 				hasVisibleTool ||= visible;
 			}
 			if (skillTools.length > 0 && !hasVisibleTool) unavailableSkillIds.add(skill.id);
@@ -1261,7 +1215,13 @@ var Agent = class extends Think {
 		this._turn.unavailableSkillIds = unavailableSkillIds;
 		const activeSkill = skillSources.find((skill) => skill.id === activeSkillName);
 		if (activeSkill && activeSkill.authorize?.(ctx) !== false) {
-			for (const [name, tool] of Object.entries(activeSkill.tools ?? {})) if (configureTool(name, tool)) activeTools.push(name);
+			const activeSkillTools = [...Object.entries(activeSkill.tools ?? {})];
+			for (const [registrationName, definition] of Object.entries(activeSkill.actions ?? {})) {
+				const name = definition.config.name ?? registrationName;
+				const compiled = inputTools[name];
+				if (compiled) activeSkillTools.push([name, compiled]);
+			}
+			for (const [name, tool] of activeSkillTools) if (configureTool(name, tool, true, actionsByToolName.get(name) ?? tool)) activeTools.push(name);
 		}
 		this._turn.preparedTools = tools;
 		this._turn.unavailableTools = Array.from(unavailableTools, ([name, reason]) => ({
@@ -1324,6 +1284,72 @@ var Agent = class extends Think {
 			}
 		}
 	}
+	/** Verifies the request and prepares the same user context for WebSocket and HTTP requests. */
+	async authenticate(request) {
+		const config = this.constructor.getJwtAuthConfig?.(this.env);
+		if (!config) return { success: true };
+		let result;
+		try {
+			result = await verifyJwt(request, config);
+		} catch (error) {
+			console.error(`[Agent] JWT verification error - ${error}`);
+			return {
+				success: false,
+				status: 401,
+				message: "Unauthorized"
+			};
+		}
+		if (!result.success) return result;
+		if (!isJwtActorAuthorized(config, result.claims, {
+			durableObjectName: this.name,
+			parentPath: this.parentPath
+		})) return {
+			success: false,
+			status: 403,
+			message: "Forbidden"
+		};
+		let token = extractTokenFromConnectRequest(request);
+		const exchangeConfig = this.constructor.getTokenExchangeConfig?.(this.env);
+		if (exchangeConfig) {
+			let exchanged;
+			try {
+				exchanged = await exchangeToken(token, exchangeConfig);
+			} catch (error) {
+				console.error(`[Agent] Token exchange error - ${error}`);
+				return {
+					success: false,
+					status: 500,
+					message: "Token exchange failed"
+				};
+			}
+			if (!exchanged.success) {
+				console.error(`[Agent] Token exchange failed - ${exchanged.message}`);
+				return {
+					success: false,
+					status: exchanged.subjectTokenRejected ? 401 : 500,
+					message: exchanged.subjectTokenRejected ? "Unauthorized" : "Token exchange failed"
+				};
+			}
+			await this._storeExchangedToken(exchanged);
+			token = exchanged.accessToken;
+		}
+		if (!this.getUserContext) return { success: true };
+		try {
+			this.userContext = await this.getUserContext(token);
+			return {
+				success: true,
+				userContext: this.userContext
+			};
+		} catch (error) {
+			console.error(`[Agent] getUserContext error - ${error}`);
+			const closeCode = getConnectCloseCode(error);
+			return {
+				success: false,
+				status: closeCode === 4003 ? 403 : closeCode === 4001 ? 401 : 500,
+				message: "Could not establish user context"
+			};
+		}
+	}
 	/**
 	* The exchanged token for this agent, refreshed on every authenticated
 	* connect. Kept in memory for the hot path and mirrored to DO storage so
@@ -1788,44 +1814,66 @@ var Assistant = class extends Agent$1 {
 		sendAgentType(connection, "assistant");
 		sendSubAgentName(connection, this.agent.name);
 		sendConnectionStatus(connection, "connecting");
-		const getJwtAuthConfig = this.agent.getJwtAuthConfig;
-		if (getJwtAuthConfig) {
-			const config = getJwtAuthConfig(this.env);
-			if (config) {
-				let result;
-				try {
-					result = await verifyJwt(ctx.request, config);
-				} catch (error) {
-					sendConnectionStatus(connection, "unauthorized");
-					console.error(`[Assistant] JWT verification error - ${error}`);
-					connection.close(4001, "Unauthorized");
-					return;
-				}
-				if (!result.success) {
-					sendConnectionStatus(connection, "unauthorized");
-					console.error(`[Assistant] JWT verification error - ${result.message}`);
-					connection.close(result.status === 401 ? 4001 : 4003, result.message);
-					return;
-				}
-				if (!isJwtActorAuthorized(config, result.claims, {
+		const auth = await this.authenticate(ctx.request);
+		if (!auth.success) {
+			sendConnectionStatus(connection, "unauthorized");
+			connection.close(auth.status === 401 ? 4001 : 4003, auth.message);
+			return;
+		}
+		sendConnectionStatus(connection, "connected");
+	}
+	async authenticate(request) {
+		const config = this.agent.getJwtAuthConfig?.(this.env);
+		if (!config) return { success: true };
+		let result;
+		try {
+			result = await verifyJwt(request, config);
+		} catch (error) {
+			console.error(`[Assistant] JWT verification error - ${error}`);
+			return {
+				success: false,
+				status: 401,
+				message: "Unauthorized"
+			};
+		}
+		if (!result.success) return result;
+		if (!isJwtActorAuthorized(config, result.claims, {
+			durableObjectName: this.name,
+			parentPath: this.parentPath
+		})) {
+			console.error("[Assistant] Authenticated actor does not own the requested assistant", {
+				authenticatedActorId: config.getActorId(result.claims),
+				requiredActorId: getTargetActorId({
 					durableObjectName: this.name,
 					parentPath: this.parentPath
-				})) {
-					sendConnectionStatus(connection, "unauthorized");
-					console.error("[Assistant] Authenticated actor does not own the requested assistant", {
-						authenticatedActorId: config.getActorId(result.claims),
-						requiredActorId: getTargetActorId({
-							durableObjectName: this.name,
-							parentPath: this.parentPath
-						}),
-						durableObjectName: this.name
-					});
-					connection.close(4003, "Forbidden");
-					return;
-				}
-			}
+				}),
+				durableObjectName: this.name
+			});
+			return {
+				success: false,
+				status: 403,
+				message: "Forbidden"
+			};
 		}
-		sendConnectionStatus(connection, "connected");
+		return { success: true };
+	}
+	async onRequest(request) {
+		const auth = await this.authenticate(request);
+		if (!auth.success) return Response.json({ error: auth.message }, { status: auth.status });
+		const action = new URL(request.url).pathname.split("/").pop();
+		if (action === "getChats" && request.method === "GET") return Response.json(await this.getChats());
+		if (action === "createChat" && request.method === "POST") return Response.json({ id: await this.createChat() }, { status: 201 });
+		if (action === "deleteChat" && request.method === "POST") {
+			const { id } = await request.json();
+			await this.deleteChat(id);
+			return new Response(null, { status: 204 });
+		}
+		if (action === "renameChat" && request.method === "POST") {
+			const { id, title } = await request.json();
+			await this.renameChat(id, title);
+			return new Response(null, { status: 204 });
+		}
+		return super.onRequest(request);
 	}
 	async createChat() {
 		const id = nanoid();
@@ -2348,6 +2396,65 @@ var ChatAgent = class extends Agent {
 		const parent = await this.getParentAgent();
 		if (parent?.recordChatTurn) await parent.recordChatTurn(this.name, this.messages);
 	}
+	async onRequest(request) {
+		const auth = await this.authenticate(request);
+		if (!auth.success) return Response.json({ error: auth.message }, { status: auth.status });
+		const action = new URL(request.url).pathname.split("/").pop();
+		if (action === "getMessages" && request.method === "GET") return Response.json(await this.getMessages());
+		if (action === "sendMessage" && request.method === "POST") return this.streamMessage(request);
+		if (action === "cancelChat" && request.method === "POST") {
+			const { requestId } = await request.json();
+			this.cancelChat(requestId);
+			return new Response(null, { status: 204 });
+		}
+		return super.onRequest(request);
+	}
+	/**
+	* Runs the turn from the stream's start callback so the response can be
+	* returned immediately and each event reaches the client as it is produced.
+	*/
+	async streamMessage(request) {
+		let message;
+		try {
+			({message} = await request.json());
+		} catch {
+			return Response.json({ error: "Invalid request body" }, { status: 400 });
+		}
+		if (typeof message === "string") message = {
+			id: crypto.randomUUID(),
+			role: "user",
+			parts: [{
+				type: "text",
+				text: message
+			}]
+		};
+		else if (!message || message.role !== "user" || !Array.isArray(message.parts)) return Response.json({ error: "message must be a user message" }, { status: 400 });
+		const encoder = new TextEncoder();
+		const readable = new ReadableStream({ start: async (controller) => {
+			const send = (event, data) => controller.enqueue(encoder.encode(`event: ${event}\ndata: ${data}\n\n`));
+			try {
+				await this.runTurn({
+					mode: "stream",
+					input: message,
+					callback: {
+						onStart: (event) => send("start", JSON.stringify(event)),
+						onEvent: (json) => send("chunk", json),
+						onDone: () => send("done", "{}"),
+						onError: (error) => send("error", JSON.stringify({ error })),
+						onInterrupted: () => send("interrupted", "{}")
+					}
+				});
+			} catch (error) {
+				send("error", JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+			} finally {
+				controller.close();
+			}
+		} });
+		return new Response(readable, { headers: {
+			"Content-Type": "text/event-stream",
+			"Cache-Control": "no-cache"
+		} });
+	}
 	/**
 	* Submit feedback for a message by its id.
 	* @param messageId - The id of the message to give feedback on.
@@ -2382,6 +2489,34 @@ var ChatAgent = class extends Agent {
 	}
 };
 //#endregion
+//#region src/server/util/actions.ts
+/** A native Think action with the SDK's standard authorization policy. */
+function action(definition) {
+	const { authorize, onUnauthorized, execute, ...config } = definition;
+	const descriptor = action$1({
+		...config,
+		approval: config.approval ?? true,
+		execute: async (input, ctx) => {
+			const idempotencyKey = typeof config.idempotencyKey === "function" ? await config.idempotencyKey({
+				input,
+				ctx
+			}) : config.idempotencyKey ?? ctx.toolCallId;
+			return execute(input, {
+				...ctx,
+				messages: [...ctx.messages],
+				abortSignal: ctx.signal,
+				experimental_context: getCurrentAgent().agent._lastBody,
+				idempotencyKey
+			});
+		}
+	});
+	return Object.freeze({
+		...descriptor,
+		authorize,
+		onUnauthorized
+	});
+}
+//#endregion
 //#region src/server/util/skills.ts
 function skill(definition) {
 	if (!definition.name) throw new Error("Skill name is required");
@@ -2405,6 +2540,7 @@ function skill(definition) {
 			};
 		},
 		tools: definition.tools,
+		actions: definition.actions,
 		authorize: definition.authorize
 	};
 }
@@ -2427,4 +2563,4 @@ function getCurrentToolContext() {
 	return getCurrentAgent().agent._lastBody;
 }
 //#endregion
-export { Agent, Assistant, ChatAgent, createJwtAuthConfig, exchangeToken, getCurrentToolContext, routeAgentRequest, skill, tool };
+export { Agent, Assistant, ChatAgent, action, createJwtAuthConfig, exchangeToken, getCurrentToolContext, routeAgentRequest, skill, tool };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "2.10.6",
+  "version": "2.11.0",
   "description": "A starter for creating a TypeScript package.",
   "license": "MIT",
   "files": [