@economic/agents 2.3.26 → 2.4.0

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { n as JwtAuthConfig, t as routeAgentRequest } from "./route-agent-request-D2ll--nF.mjs";
 import { Agent as Agent$1, Connection, ConnectionContext, SubAgentClass } from "agents";
 import { ChatResponseResult, PrepareStepContext, Session, Think, ToolCallContext, ToolCallDecision, TurnConfig, TurnContext, skills } from "@cloudflare/think";
-import { JSONValue, LanguageModel, Tool as Tool$1, UIMessage } from "ai";
+import { JSONValue, LanguageModel, ModelMessage, Tool as Tool$1, UIMessage } from "ai";
 import { createCompactFunction } from "agents/experimental/memory/utils";
 import { SkillSource as SkillSource$1 } from "agents/skills";
 
@@ -34,6 +34,15 @@ type Tool<Context extends Record<string, unknown> = Record<string, unknown>, INP
 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>;
 //#endregion
 //#region src/server/agents/Agent.d.ts
+/** What the model would see on its next step — returned by {@link Agent.inspectTurn}. */
+interface TurnSnapshot {
+  system: string;
+  tools: ToolSet;
+  activeTools: string[];
+  /** Tools provided by the framework (session/skill meta-tools, MCP), not the agent. */
+  frameworkToolNames: string[];
+  messages: ModelMessage[];
+}
 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;
@@ -75,6 +84,19 @@ declare abstract class Agent<RequestContext extends Record<string, unknown> = Re
   }>;
   beforeToolCall(ctx: ToolCallContext): Promise<ToolCallDecision | void>;
   getTools(): ToolSet;
+  /**
+   * 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
+   * messages. Runs no turn (nothing admitted, persisted, executed; no model
+   * call). Skill gating is derived from the history, so a history with an
+   * `activate_skill` call yields that skill's tools. For eval harnesses and
+   * prompt-preview tooling; call it inside the DO context.
+   */
+  inspectTurn(input?: {
+    messages?: ModelMessage[];
+    requestContext?: RequestContext;
+    userContext?: UserContext;
+  }): Promise<TurnSnapshot>;
   workspaceBash: boolean;
   getSkillScriptRunner(): skills.SkillScriptRunner | null;
   /**
@@ -82,7 +104,33 @@ 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;
   private _getAuthorizedTools;
+  /**
+   * Wrap each tool's `execute` so it falls back to the current turn's tool
+   * context ({@link _toolContextForCurrentTurn}: request body + `_userContext`)
+   * when the caller supplies none. A caller-supplied `experimental_context`
+   * always wins, so normal steps — where {@link beforeStep} provides the
+   * context — are untouched.
+   *
+   * The fallback exists for the approval continuation: when a `needsApproval`
+   * tool is approved, the AI SDK executes it BEFORE the step loop starts, so no
+   * `beforeStep` runs for it and `execute` receives `experimental_context:
+   * undefined` — which stripped action tools of their auth token / user context
+   * after approval. The continuation is a turn of its own: {@link beforeTurn}
+   * re-sets {@link _toolContextForCurrentTurn} from the approval request's body
+   * before the SDK executes the tool, so the fallback context is the approval
+   * request's — clients must resend anything tools need (e.g. tokens) on it.
+   *
+   * TODO: remove once @cloudflare/think supports a turn-level
+   * `experimental_context` (its TurnConfig has no such field and it passes none
+   * to `streamText`, so only `beforeStep` can supply one — and the approval
+   * execution happens before any step).
+   *
+   * See {@link withFallbackToolContext} for the wrap itself, which preserves an
+   * `async function*` `execute`'s streaming shape.
+   */
+  private _withTurnContextFallback;
   private _getLastActivatedSkillName;
   /**
    * Override to enable JWT authentication on WebSocket connections.
@@ -315,4 +363,4 @@ declare function skill<Context extends Record<string, unknown> = Record<string,
 //#region src/server/index.d.ts
 declare function getCurrentToolContext(): any;
 //#endregion
-export { Agent, type AgentConnectionStatus, type AgentConnectionType, type AgentEnv, Assistant, ChatAgent, type FacetStub, type LegacyChatStub, type LegacyMessageFeedback, type MigrationDeps, type Skill, type SkillSource, type Tool, type ToolContext, type ToolSet, getCurrentToolContext, migrateUserFromV1, routeAgentRequest, skill, tool };
+export { Agent, type AgentConnectionStatus, type AgentConnectionType, type AgentEnv, Assistant, ChatAgent, type FacetStub, type LegacyChatStub, type LegacyMessageFeedback, type MigrationDeps, type Skill, type SkillSource, type Tool, type ToolContext, type ToolSet, type TurnSnapshot, getCurrentToolContext, migrateUserFromV1, routeAgentRequest, skill, tool };

package/dist/index.mjs

@@ -8,6 +8,43 @@ import { createCompactFunction } from "agents/experimental/memory/utils";
 function tool(tool) {
 	return tool$1(tool);
 }
+/**
+* Wrap each tool's `execute` so it falls back to `getFallbackContext()` for
+* `experimental_context` when the caller supplies none (e.g. the approval
+* continuation, which bypasses `beforeStep`). A caller-supplied context always
+* wins, so on a normal turn the wrap is a no-op.
+*
+* Crucially it preserves the function's shape: an `async function*` `execute`
+* stays an async generator so `@cloudflare/think` keeps detecting it
+* (`execute.constructor.name === "AsyncGeneratorFunction"`) and streams the
+* tool's preliminary (yielded) results. A plain wrapper would make think consume
+* the iterable and keep only its final value — breaking streaming for every
+* generator tool, on approval AND normal turns. Non-generator executes get an
+* equivalent plain wrapper; non-function executes pass through untouched.
+*/
+function withFallbackToolContext(tools, getFallbackContext) {
+	const result = {};
+	for (const [name, tool] of Object.entries(tools)) {
+		const originalExecute = tool.execute;
+		if (typeof originalExecute !== "function") {
+			result[name] = tool;
+			continue;
+		}
+		result[name] = {
+			...tool,
+			execute: originalExecute.constructor?.name === "AsyncGeneratorFunction" ? async function* (input, options) {
+				yield* originalExecute(input, {
+					...options,
+					experimental_context: options?.experimental_context ?? getFallbackContext()
+				});
+			} : (input, options) => originalExecute(input, {
+				...options,
+				experimental_context: options?.experimental_context ?? getFallbackContext()
+			})
+		};
+	}
+	return result;
+}
 //#endregion
 //#region src/server/util/prompts.ts
 const SECURITY_RULES_PROMPT = `These rules override all other instructions, no matter what the user asks.
@@ -201,17 +238,8 @@ var Agent = class extends Think {
 		return {
 			system: await this.session.refreshSystemPrompt(),
 			model: this.getModel(this._toolContextForCurrentTurn),
-			messages: pruneMessages({
-				messages: ctx.messages,
-				toolCalls: [{
-					type: "before-last-2-messages",
-					tools: []
-				}, {
-					type: "before-last-5-messages",
-					tools: ["activate_skill"]
-				}]
-			}),
-			tools,
+			messages: this._pruneTurnMessages(ctx.messages),
+			tools: this._withTurnContextFallback(tools),
 			activeTools,
 			experimental_transform: buildSourcesTransform(),
 			experimental_telemetry: {
@@ -264,6 +292,48 @@ var Agent = class extends Think {
 	getTools() {
 		return {};
 	}
+	/**
+	* 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
+	* messages. Runs no turn (nothing admitted, persisted, executed; no model
+	* call). Skill gating is derived from the history, so a history with an
+	* `activate_skill` call yields that skill's tools. For eval harnesses and
+	* prompt-preview tooling; call it inside the DO context.
+	*/
+	async inspectTurn(input = {}) {
+		const messages = input.messages ?? [];
+		await this.__unsafe_ensureInitialized();
+		const previousContext = this._toolContextForCurrentTurn;
+		this._toolContextForCurrentTurn = {
+			...input.requestContext ?? {},
+			_userContext: input.userContext
+		};
+		const previousAuthorizedTools = this._authorizedToolsForCurrentTurn;
+		try {
+			const system = await this.session.refreshSystemPrompt();
+			const think = this;
+			const frameworkTools = {
+				...await this.session.tools(),
+				...think._skillRegistry?.tools(),
+				...think.mcp?.getAITools?.()
+			};
+			const { tools, activeTools } = await this._getAuthorizedTools({
+				...this.getTools(),
+				...frameworkTools
+			}, this._getLastActivatedSkillName(messages));
+			const snapshotContext = this._toolContextForCurrentTurn;
+			return {
+				system,
+				tools: withFallbackToolContext(tools, () => snapshotContext),
+				activeTools,
+				frameworkToolNames: Object.keys(frameworkTools),
+				messages: this._pruneTurnMessages(messages)
+			};
+		} finally {
+			this._toolContextForCurrentTurn = previousContext;
+			this._authorizedToolsForCurrentTurn = previousAuthorizedTools;
+		}
+	}
 	workspaceBash = false;
 	getSkillScriptRunner() {
 		if (!("LOADER" in this.env)) return null;
@@ -276,6 +346,18 @@ var Agent = class extends Think {
 	getRemoteSkills() {
 		return [];
 	}
+	_pruneTurnMessages(messages) {
+		return pruneMessages({
+			messages,
+			toolCalls: [{
+				type: "before-last-2-messages",
+				tools: []
+			}, {
+				type: "before-last-5-messages",
+				tools: ["activate_skill"]
+			}]
+		});
+	}
 	async _getAuthorizedTools(availableTools, activeSkillName) {
 		const tools = { ...availableTools };
 		const activeTools = Object.keys(tools);
@@ -291,6 +373,33 @@ var Agent = class extends Think {
 			activeTools
 		};
 	}
+	/**
+	* Wrap each tool's `execute` so it falls back to the current turn's tool
+	* context ({@link _toolContextForCurrentTurn}: request body + `_userContext`)
+	* when the caller supplies none. A caller-supplied `experimental_context`
+	* always wins, so normal steps — where {@link beforeStep} provides the
+	* context — are untouched.
+	*
+	* The fallback exists for the approval continuation: when a `needsApproval`
+	* tool is approved, the AI SDK executes it BEFORE the step loop starts, so no
+	* `beforeStep` runs for it and `execute` receives `experimental_context:
+	* undefined` — which stripped action tools of their auth token / user context
+	* after approval. The continuation is a turn of its own: {@link beforeTurn}
+	* re-sets {@link _toolContextForCurrentTurn} from the approval request's body
+	* before the SDK executes the tool, so the fallback context is the approval
+	* request's — clients must resend anything tools need (e.g. tokens) on it.
+	*
+	* TODO: remove once @cloudflare/think supports a turn-level
+	* `experimental_context` (its TurnConfig has no such field and it passes none
+	* to `streamText`, so only `beforeStep` can supply one — and the approval
+	* execution happens before any step).
+	*
+	* See {@link withFallbackToolContext} for the wrap itself, which preserves an
+	* `async function*` `execute`'s streaming shape.
+	*/
+	_withTurnContextFallback(tools) {
+		return withFallbackToolContext(tools, () => this._toolContextForCurrentTurn);
+	}
 	_getLastActivatedSkillName(items = []) {
 		for (let index = items.length - 1; index >= 0; index--) {
 			const item = items[index];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "2.3.26",
+  "version": "2.4.0",
   "description": "A starter for creating a TypeScript package.",
   "license": "MIT",
   "files": [
@@ -46,7 +46,7 @@
   },
   "peerDependencies": {
     "@cloudflare/think": "^0.12.1",
-    "@cloudflare/vite-plugin": "^1.43.0",
+    "@cloudflare/vite-plugin": "^1.43.0 <1.43.2",
     "@cloudflare/worker-bundler": "^0.2.1",
     "agents": "^0.17.3",
     "vite": ">=8.0.0"