@economic/agents 2.10.5 → 2.11.0

package/README.md

@@ -7,7 +7,7 @@ React client: [`@economic/agents-react`](../react/README.md).
 ## The three classes
 
 - **`Agent`** — the core. Runs the agent loop and keeps message history. Drive it over a WebSocket or programmatically (schedule, alarm, RPC). Most agents stop here.
-- **`ChatAgent`** — `Agent` plus chat features: compaction and message feedback.
+- **`ChatAgent`** — `Agent` plus chat features: model-only compaction that preserves the client transcript, and message feedback.
 - **`Assistant`** — per-user shell over `ChatAgent`: create/list/delete chats, titles, summaries, retention.
 
 ```
@@ -188,7 +188,7 @@ You can also drive turns server-side — call `saveMessages` from a schedule or
 
 ## A chat agent
 
-For a chat UI, extend `ChatAgent` instead of `Agent`. It adds compaction and message feedback, and connects to a browser with [`useChat`](../react/README.md#usechat) — no `Assistant` required. The DO name is the chat; address one per user, ticket, or whatever fits.
+For a chat UI, extend `ChatAgent` instead of `Agent`. It adds model-only compaction (the stored/client transcript remains unchanged) and message feedback, and connects to a browser with [`useChat`](../react/README.md#usechat) — no `Assistant` required. The DO name is the chat; address one per user, ticket, or whatever fits.
 
 ```typescript
 import { openai } from "@ai-sdk/openai";
@@ -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";
@@ -578,18 +655,19 @@ Imported from `@economic/agents` unless noted.
 | Export      | Description                                              |
 | ----------- | -------------------------------------------------------- |
 | `Agent`     | Core agent base. Implement `getModel`/`getSystemPrompt`. |
-| `ChatAgent` | `Agent` + compaction and message feedback.               |
+| `ChatAgent` | `Agent` + model-only compaction and message feedback.    |
 | `Assistant` | Per-user manager of `ChatAgent` chats.                   |
 
 ### 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
@@ -186,7 +197,7 @@ declare abstract class Agent<RequestContext extends Record<string, unknown> = Re
    * @returns The remote skills to be loaded from SKILLS_BUCKET.
    */
   protected getRemoteSkills(): string[];
-  private _pruneTurnMessages;
+  protected pruneTurnMessages(messages: ModelMessage[]): ModelMessage[];
   private _getTurnSystemPrompt;
   private _prepareTools;
   /**
@@ -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,11 +1,11 @@
 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";
 import { genericObservability } from "agents/observability";
+import { createCompactFunction, estimateMessageTokens, estimateStringTokens, sanitizeToolPairs, truncateOlderMessages } from "agents/experimental/memory/utils";
 import { nanoid } from "nanoid";
-import { createCompactFunction } from "agents/experimental/memory/utils";
 //#region src/server/features/auth/index.ts
 function createJwtAuthConfig(config) {
 	return config;
@@ -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
 		};
 	}
 	/**
@@ -1058,7 +985,7 @@ var Agent = class extends Think {
 		return {
 			system: this._getTurnSystemPrompt(),
 			model: this.getModel(this._turn.context),
-			messages: this._pruneTurnMessages(ctx.messages),
+			messages: this.pruneTurnMessages(ctx.messages),
 			tools: this._withTurnContextFallback(tools),
 			activeTools,
 			experimental_transform: buildSourcesTransform(),
@@ -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;
@@ -1165,7 +1100,7 @@ var Agent = class extends Think {
 				tools: withFallbackToolContext(tools, () => snapshotContext),
 				activeTools,
 				frameworkToolNames: Object.keys(frameworkTools),
-				messages: this._pruneTurnMessages(messages)
+				messages: this.pruneTurnMessages(messages)
 			};
 		} finally {
 			this._turn = previousTurn;
@@ -1183,7 +1118,7 @@ var Agent = class extends Think {
 	getRemoteSkills() {
 		return [];
 	}
-	_pruneTurnMessages(messages) {
+	pruneTurnMessages(messages) {
 		return pruneMessages({
 			messages,
 			toolCalls: [{
@@ -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();
@@ -1978,15 +2026,130 @@ var Assistant = class extends Agent$1 {
 		agentClass: this.constructor.name
 	}) });
 };
-//#endregion
-//#region src/server/features/messages.ts
-const COMPACTION_TOKEN_THRESHOLD = 1e5;
 const COMPACTION_MAX_OUTPUT_TOKENS = 2e3;
-const createCompactFn = (model) => createCompactFunction({ summarize: (prompt) => generateText({
-	model,
-	prompt,
-	maxOutputTokens: COMPACTION_MAX_OUTPUT_TOKENS
-}).then((result) => result.text) });
+const createCompactFn = (model) => createCompactFunction({
+	protectHead: 2,
+	minTailMessages: 1,
+	summarize: (prompt) => generateText({
+		model,
+		prompt,
+		maxOutputTokens: COMPACTION_MAX_OUTPUT_TOKENS
+	}).then((result) => result.text)
+});
+const MODEL_COMPACTION_MESSAGE_ID = "compaction_model_context";
+/**
+* Model compaction is deliberately stored separately from assistant_messages.
+* The transcript remains exact for clients; only model input uses the summary.
+*/
+function ensureModelCompactionTable(sql) {
+	sql`CREATE TABLE IF NOT EXISTS economic_chat_model_compaction (
+      id                  INTEGER PRIMARY KEY CHECK (id = 1),
+      summary             TEXT NOT NULL,
+      from_message_id     TEXT NOT NULL,
+      to_message_id       TEXT NOT NULL,
+      updated_at          INTEGER NOT NULL
+    )`;
+}
+function getModelCompaction(sql) {
+	const row = sql`SELECT summary, from_message_id, to_message_id
+    FROM economic_chat_model_compaction
+    WHERE id = 1`[0];
+	return row ? {
+		summary: row.summary,
+		fromMessageId: row.from_message_id,
+		toMessageId: row.to_message_id
+	} : null;
+}
+function setModelCompaction(sql, state) {
+	sql`INSERT INTO economic_chat_model_compaction (
+      id, summary, from_message_id, to_message_id, updated_at
+    ) VALUES (
+      1, ${state.summary}, ${state.fromMessageId}, ${state.toMessageId}, ${Date.now()}
+    ) ON CONFLICT (id) DO UPDATE SET
+      summary = excluded.summary,
+      from_message_id = excluded.from_message_id,
+      to_message_id = excluded.to_message_id,
+      updated_at = excluded.updated_at`;
+}
+function clearModelCompaction(sql) {
+	sql`DELETE FROM economic_chat_model_compaction WHERE id = 1`;
+}
+/**
+* Move summaries created by the old Session overlay implementation into the
+* model-only store, then remove the overlays. Session retained the original
+* rows, so removing an overlay restores the exact transcript.
+*/
+function migrateSessionCompaction(sql) {
+	const legacy = sql`SELECT
+      summary, from_message_id, to_message_id
+    FROM assistant_compactions
+    WHERE session_id = ''
+    ORDER BY created_at DESC, rowid DESC
+    LIMIT 1`[0];
+	if (!legacy) return false;
+	if (!getModelCompaction(sql)) setModelCompaction(sql, {
+		summary: legacy.summary,
+		fromMessageId: legacy.from_message_id,
+		toMessageId: legacy.to_message_id
+	});
+	sql`DELETE FROM assistant_compactions WHERE session_id = ''`;
+	return true;
+}
+function applyModelCompaction(messages, state) {
+	const fromIndex = messages.findIndex((message) => message.id === state.fromMessageId);
+	const toIndex = messages.findIndex((message) => message.id === state.toMessageId);
+	if (fromIndex === -1 || toIndex < fromIndex) return null;
+	return [
+		...messages.slice(0, fromIndex),
+		{
+			id: MODEL_COMPACTION_MESSAGE_ID,
+			role: "assistant",
+			parts: [{
+				type: "text",
+				text: state.summary
+			}]
+		},
+		...messages.slice(toIndex + 1)
+	];
+}
+/** Build the compacted projection used only for the next model call. */
+async function prepareModelHistory(messages, existingState, compact, systemPrompt = "") {
+	let state = existingState;
+	let projected = state ? applyModelCompaction(messages, state) : messages;
+	let stateChanged = false;
+	if (!projected) {
+		state = null;
+		projected = messages;
+		stateChanged = true;
+	}
+	if (estimateMessageTokens(projected) + estimateStringTokens(systemPrompt) <= 1e5) return {
+		messages: projected,
+		state,
+		stateChanged
+	};
+	const result = await compact(projected);
+	if (!result) return {
+		messages: projected,
+		state,
+		stateChanged
+	};
+	const nextState = {
+		summary: result.summary,
+		fromMessageId: state?.fromMessageId ?? result.fromMessageId,
+		toMessageId: result.toMessageId
+	};
+	const nextProjection = applyModelCompaction(messages, nextState);
+	if (!nextProjection) return {
+		messages: projected,
+		state,
+		stateChanged
+	};
+	return {
+		messages: nextProjection,
+		state: nextState,
+		stateChanged: true
+	};
+}
 /**
 * Ensures that the feedback table exists.
 * @param sql - The SQL function to use to execute the query.
@@ -2191,14 +2354,38 @@ var ChatAgent = class extends Agent {
 	async onStart() {
 		await super.onStart();
 		ensureFeedbackTableExists(this.sql.bind(this));
+		ensureModelCompactionTable(this.sql.bind(this));
+		if (migrateSessionCompaction(this.sql.bind(this))) await this.syncMessagesFromStorage();
 	}
 	configureSession(session) {
-		return super.configureSession(session).onCompaction(createCompactFn(this.getModel())).compactAfter(COMPACTION_TOKEN_THRESHOLD);
+		return super.configureSession(session);
 	}
 	async beforeTurn(ctx) {
 		const parent = await this.getParentAgent();
 		if (parent?.registerChat) await parent.registerChat(this.name);
-		return super.beforeTurn(ctx);
+		const config = await super.beforeTurn(ctx) ?? {};
+		try {
+			const prepared = await prepareModelHistory(this.messages, getModelCompaction(this.sql.bind(this)), createCompactFn(config.model ?? ctx.model), config.system ?? ctx.system);
+			if (prepared.stateChanged) if (prepared.state) setModelCompaction(this.sql.bind(this), prepared.state);
+			else clearModelCompaction(this.sql.bind(this));
+			if (prepared.state) {
+				const tools = config.tools ? {
+					...ctx.tools,
+					...config.tools
+				} : ctx.tools;
+				const modelMessages = await convertToModelMessages(truncateOlderMessages(sanitizeToolPairs(prepared.messages)), {
+					tools,
+					ignoreIncompleteToolCalls: true
+				});
+				return {
+					...config,
+					messages: this.pruneTurnMessages(modelMessages)
+				};
+			}
+		} catch (error) {
+			console.error("[ChatAgent] Failed to prepare model-only compaction", error);
+		}
+		return config;
 	}
 	async onChatResponse(result) {
 		recordTurnCompletedAnalytics(this.env.AGENTS_ANALYTICS, {
@@ -2209,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.
@@ -2243,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");
@@ -2266,6 +2540,7 @@ function skill(definition) {
 			};
 		},
 		tools: definition.tools,
+		actions: definition.actions,
 		authorize: definition.authorize
 	};
 }
@@ -2288,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.5",
+  "version": "2.11.0",
   "description": "A starter for creating a TypeScript package.",
   "license": "MIT",
   "files": [