The Open Framework for Building Agents
feat(eve): expose step messages on ToolContext (#4038)
Matan Kushnered2c04bc4d1a
diff --git a/.changeset/tool-context-messages.md b/.changeset/tool-context-messages.mdnew file mode 100644index 000000000..ead9f856c--- /dev/null+++ b/.changeset/tool-context-messages.md@@ -0,0 +1,5 @@+---+"eve": patch+---++`ToolContext` now exposes `messages`, the model input for the step that requested the call, so tools can evaluate the conversation that led to them without recording it separately. It matches the `ctx.messages` dynamic resolvers receive at `step.started`.diff --git a/docs/tools/overview.mdx b/docs/tools/overview.mdxindex 775da88f5..3493eb1c0 100644--- a/docs/tools/overview.mdx+++ b/docs/tools/overview.mdx@@ -179,6 +179,7 @@ examples.- `ctx.session`: session metadata, turn, auth, parent lineage.- `ctx.callId`: the id of the current tool call, carried by the call's [stream events](/docs/concepts/sessions-runs-and-streaming) and approval context.- `ctx.toolName`: the final runtime name the model called, including any namespace qualification.+- `ctx.messages`: the model input for the step that requested this call, the same messages a `step.started` [dynamic resolver](/docs/guides/dynamic-capabilities) reads.- `ctx.abortSignal`: aborts when the active turn is cancelled. Pass it to cancellation-aware work; sandbox sessions from `ctx.getSandbox()` are already bound to it.- `ctx.getSandbox()`: the live [sandbox](/docs/sandbox) handle.diff --git a/e2e/fixtures/agent-tools/agent/agent.ts b/e2e/fixtures/agent-tools/agent/agent.tsindex 1f571c46c..71e9541ae 100644--- a/e2e/fixtures/agent-tools/agent/agent.ts+++ b/e2e/fixtures/agent-tools/agent/agent.ts@@ -10,6 +10,13 @@ const base = e2eAgentConfig({}return "Callback identity checked.";}+ if (request.lastUserMessage?.includes("`context_messages`")) {+ const roles = request.messages.map((message) => message.role);+ if (roles.lastIndexOf("tool") <= roles.lastIndexOf("user")) {+ return { toolCalls: [{ name: "context_messages", input: {} }] };+ }+ return "Context messages checked.";+ }if (request.lastUserMessage?.includes("`schema_validate`")) {const roles = request.messages.map((message) => message.role);if (roles.lastIndexOf("tool") <= roles.lastIndexOf("user")) {diff --git a/e2e/fixtures/agent-tools/agent/tools/context_messages.ts b/e2e/fixtures/agent-tools/agent/tools/context_messages.tsnew file mode 100644index 000000000..a066b92ee--- /dev/null+++ b/e2e/fixtures/agent-tools/agent/tools/context_messages.ts@@ -0,0 +1,19 @@+import { defineTool } from "eve/tools";+import { z } from "zod";++export default defineTool({+ description:+ "Returns the message count and latest user text visible to this tool call. " ++ "Only call when the user explicitly asks to check context messages.",+ inputSchema: z.object({}),+ execute(_input, ctx) {+ const lastUser = [...ctx.messages].reverse().find((message) => message.role === "user");+ const lastUserText =+ typeof lastUser?.content === "string"+ ? lastUser.content+ : (lastUser?.content+ .flatMap((part) => (part.type === "text" ? [part.text] : []))+ .join("\n") ?? null);+ return { lastUserText, messageCount: ctx.messages.length };+ },+});diff --git a/e2e/fixtures/agent-tools/evals/context-messages.eval.ts b/e2e/fixtures/agent-tools/evals/context-messages.eval.tsnew file mode 100644index 000000000..f1557b3b0--- /dev/null+++ b/e2e/fixtures/agent-tools/evals/context-messages.eval.ts@@ -0,0 +1,55 @@+import { defineEval } from "eve/evals";+import { satisfies } from "eve/evals/expect";++// An authored tool reads the step's model input from ctx.messages: it includes+// the message that led to the call and accumulates across turns.+export default defineEval({+ description: "Authored tools see the step's messages, including the current turn's input.",+ async test(t) {+ const first = await t.send(+ "Call the `context_messages` tool to check what it can see about the first request.",+ );+ first.expectOk();+ const firstOutput = first.requireToolCall("context_messages").output;++ const second = await first.session.send(+ "Call the `context_messages` tool again for the follow-up about the blue invoice.",+ );+ second.expectOk();+ const secondOutput = second.requireToolCall("context_messages").output;++ t.check(+ secondOutput,+ satisfies(+ (value) => readLastUserText(value)?.includes("blue invoice") === true,+ "the tool sees the message that requested the call",+ ),+ );+ t.check(+ [firstOutput, secondOutput],+ satisfies(([firstValue, secondValue]: readonly unknown[]) => {+ const firstCount = readMessageCount(firstValue);+ const secondCount = readMessageCount(secondValue);+ return (+ firstCount !== undefined &&+ secondCount !== undefined &&+ firstCount >= 1 &&+ secondCount > firstCount+ );+ }, "message count increases across turns"),+ );+ t.succeeded();+ },+});++function readMessageCount(value: unknown): number | undefined {+ if (typeof value !== "object" || value === null) return undefined;+ const count = (value as { messageCount?: unknown }).messageCount;+ return typeof count === "number" ? count : undefined;+}++function readLastUserText(value: unknown): string | undefined {+ if (typeof value !== "object" || value === null) return undefined;+ const text = (value as { lastUserText?: unknown }).lastUserText;+ return typeof text === "string" ? text : undefined;+}diff --git a/packages/eve/extension-contracts/compatibility/dynamicTool/v61.ts b/packages/eve/extension-contracts/compatibility/dynamicTool/v61.tsnew file mode 100644index 000000000..40b3a7b61--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/dynamicTool/v61.ts@@ -0,0 +1,13 @@+import { defineDynamic, defineTool } from "#public/tools/index.js";++// Epoch 61 tool contexts had no `messages`; it is additive.+export default defineDynamic({+ events: {+ "turn.started": (_event, ctx) =>+ defineTool({+ description: "Return the active session identifier.",+ inputSchema: { type: "object", properties: {} },+ execute: (_input, toolCtx) => ({ callId: toolCtx.callId, sessionId: ctx.session.id }),+ }),+ },+});diff --git a/packages/eve/extension-contracts/compatibility/tool/v64.ts b/packages/eve/extension-contracts/compatibility/tool/v64.tsnew file mode 100644index 000000000..1576388af--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/tool/v64.ts@@ -0,0 +1,12 @@+import { z } from "zod";+import { defineTool } from "#public/tools/index.js";++// Epoch 64 tool contexts had no `messages`. Compiled epoch 64 tools read only+// the context members they knew about; `messages` is additive.+export default defineTool({+ description: "Look up the status of an order.",+ inputSchema: z.object({ orderId: z.string() }),+ execute({ orderId }, ctx) {+ return { callId: ctx.callId, orderId, sessionId: ctx.session.id };+ },+});diff --git a/packages/eve/extension-contracts/reports/dynamicTool/v62.json b/packages/eve/extension-contracts/reports/dynamicTool/v62.jsonnew file mode 100644index 000000000..c2004679b--- /dev/null+++ b/packages/eve/extension-contracts/reports/dynamicTool/v62.json@@ -0,0 +1,16 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "dynamicTool",+ "epoch": 62,+ "sha256": "b4e8128b40ebd6d35ea51e04fde5b5a1c3d0b35fc7c98c0c15f5a56cf9b4f119",+ "exports": [+ "DynamicToolEntry",+ "DynamicToolEvents",+ "DynamicToolResult",+ "DynamicToolSet",+ "auto",+ "defineDurableCallback",+ "defineDurableSchema",+ "defineDynamic"+ ]+}diff --git a/packages/eve/extension-contracts/reports/tool/v65.json b/packages/eve/extension-contracts/reports/tool/v65.jsonnew file mode 100644index 000000000..550b82344--- /dev/null+++ b/packages/eve/extension-contracts/reports/tool/v65.json@@ -0,0 +1,28 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "tool",+ "epoch": 65,+ "sha256": "126b47dc49f70f811b6cb8b17675f1c700972c18e0884c8560ff64209c445cb6",+ "exports": [+ "AgentRouterInput",+ "AgentRouterTool",+ "WorkflowStepToolContext",+ "WorkflowTool",+ "WorkflowToolDefinition",+ "WorkflowToolInput",+ "WorkflowToolOptions",+ "agentRouter",+ "defaultWebSearch",+ "defineTool",+ "defineWorkflowTool",+ "disableTool",+ "evaluate",+ "isDisabledToolSentinel",+ "isWebSearchToolDefinition",+ "toolOutput",+ "toolOutputPart",+ "toolResultFrom",+ "webSearch",+ "workflow"+ ]+}diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.tsindex 10d84c699..a4887f657 100644--- a/packages/eve/src/compiler/extension-compatibility.ts+++ b/packages/eve/src/compiler/extension-compatibility.ts@@ -22,8 +22,10 @@ interface ExtensionCapabilityContract {const EXTENSION_CAPABILITY_CONTRACTS = {extension: { current: 1, supported: [1], dropped: {} },tool: {- current: 64,- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 29, 30, 31, 32, 34, 35, 54, 55, 63, 64],+ current: 65,+ supported: [+ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 29, 30, 31, 32, 34, 35, 54, 55, 63, 64, 65,+ ],dropped: {14: "TaskExec.delegated was removed; migrate to workflow-backed background tools",15: "TaskExec replaces stageEffect with send",@@ -69,10 +71,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},dynamicTool: {- current: 61,+ current: 62,supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 31, 32, 33, 52, 54,- 60, 61,+ 60, 61, 62,],dropped: {21: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",diff --git a/packages/eve/src/execution/tool-auth.ts b/packages/eve/src/execution/tool-auth.tsindex 18bedbc35..2f72e47b4 100644--- a/packages/eve/src/execution/tool-auth.ts+++ b/packages/eve/src/execution/tool-auth.ts@@ -16,6 +16,7 @@ export function createToolExecuteWithAuth<TInput>(input: ToolExecuteWithAuthInpuconst auth = createAuthorizationContext({ scope: input.scope });const ctx: ToolContext = {...buildBaseToolContext({ options, toolName: input.scope }),+ messages: options.messages,getToken: auth.getToken,requireAuth: auth.requireAuth,};diff --git a/packages/eve/src/execution/tools/workflow/ask.ts b/packages/eve/src/execution/tools/workflow/ask.tsindex 1d72e747b..8ab4b4b9d 100644--- a/packages/eve/src/execution/tools/workflow/ask.ts+++ b/packages/eve/src/execution/tools/workflow/ask.ts@@ -46,7 +46,7 @@ type WorkflowToolRunContextCarrier = {};export function attachWorkflowToolRunContext(- ctx: ToolContext,+ ctx: Pick<ToolContext, "abortSignal">,context: WorkflowToolRunContext,): void {Object.defineProperty(ctx, WORKFLOW_TOOL_RUN_CONTEXT, {@@ -56,7 +56,7 @@ export function attachWorkflowToolRunContext(}function readWorkflowToolRunContext(- ctx: ToolContext,+ ctx: Pick<ToolContext, "abortSignal">,helper: "agent" | "ask",): WorkflowToolRunContext {const context = (ctx as WorkflowToolRunContextCarrier | undefined)?.[WORKFLOW_TOOL_RUN_CONTEXT];@@ -176,7 +176,7 @@ export class WorkflowToolRunAsks {* the session withdrew it before it accepted a person's answer.*/export function ask(- ctx: ToolContext,+ ctx: Pick<ToolContext, "abortSignal">,request: ToolInputRequest,options: ToolInputRequestOptions = {},): Promise<ToolInputResponse> {diff --git a/packages/eve/src/execution/tools/workflow/body.ts b/packages/eve/src/execution/tools/workflow/body.tsindex 9458a73a0..db468036e 100644--- a/packages/eve/src/execution/tools/workflow/body.ts+++ b/packages/eve/src/execution/tools/workflow/body.ts@@ -74,7 +74,8 @@ export interface StartedWorkflowBody {readonly usage: RunUsageTally;}-type WorkflowCallContext = ToolContext & WorkflowToolContext;+// Workflow bodies replay deterministically, so they never receive model messages.+type WorkflowCallContext = Omit<ToolContext, "messages"> & WorkflowToolContext;/** What an `execute` call a steering message stopped settles with when its body rejects. */const INTERRUPTED_OUTPUT = { interrupted: true } as const;@@ -244,7 +245,10 @@ export function createSharedContext(input: WorkflowBodyInput,agent: (name: string) => AgentSession,askPerson: WorkflowSharedContext["ask"],-): Omit<ToolContext & WorkflowSharedContext, "abortSignal" | "agents" | "callId" | "session"> {+): Omit<+ ToolContext & WorkflowSharedContext,+ "abortSignal" | "agents" | "callId" | "messages" | "session"+> {const unavailable = (member: string, hint: string): never => {throw new Error(`ctx.${member} is not available inside a workflow tool; ${hint}. Tool "${input.toolName}" runs as a durable workflow body, which only replays deterministic code.`,diff --git a/packages/eve/src/execution/tools/workflow/serve.ts b/packages/eve/src/execution/tools/workflow/serve.tsindex a4ef02308..1116a82f9 100644--- a/packages/eve/src/execution/tools/workflow/serve.ts+++ b/packages/eve/src/execution/tools/workflow/serve.ts@@ -37,7 +37,7 @@ import type {WorkflowSharedContext,} from "#tools/workflow-definition.js";-type ServeContext = ToolContext & WorkflowServeContext<JsonValue>;+type ServeContext = Omit<ToolContext, "messages"> & WorkflowServeContext<JsonValue>;type ServeEntryPoint = (receive: WorkflowServeReceive<JsonValue>,diff --git a/packages/eve/src/harness/tools.test.ts b/packages/eve/src/harness/tools.test.tsindex fb37db931..87cba5f58 100644--- a/packages/eve/src/harness/tools.test.ts+++ b/packages/eve/src/harness/tools.test.ts@@ -64,6 +64,7 @@ async function resolveApproval(async function executeSdkTool(input: {readonly abortSignal?: AbortSignal;+ readonly messages?: ToolExecuteOptions["messages"];readonly tool: unknown;readonly toolCallId?: string;readonly toolInput?: unknown;@@ -79,7 +80,7 @@ async function executeSdkTool(input: {expect(execute).toBeTypeOf("function");return await execute!(input.toolInput ?? {}, {abortSignal: input.abortSignal,- messages: [],+ messages: input.messages ?? [],toolCallId: input.toolCallId ?? "call_1",});}@@ -289,6 +290,44 @@ describe("buildToolSet", () => {expect(receivedCallId).toBe("call_observe");});+ it("passes the AI SDK step messages to the authored tool context", async () => {+ let receivedMessages: ToolContext["messages"] | undefined;+ const tools: HarnessToolMap = new Map<string, HarnessToolDefinition>([+ [+ "observe_messages",+ {+ description: "Observe the step messages.",+ execute: createToolExecuteWithAuth({+ execute(_input, ctx) {+ receivedMessages = (ctx as ToolContext).messages;+ return { ok: true };+ },+ scope: "observe_messages",+ }),+ inputSchema: jsonSchema({ type: "object" }),+ name: "observe_messages",+ },+ ],+ ]);+ const ctx = new ContextContainer();+ ctx.set(SessionKey, {+ auth: { current: null, initiator: null },+ sessionId: "session-1",+ turn: { id: "turn-1", sequence: 0 },+ });+ const messages: ToolExecuteOptions["messages"] = [+ { content: "Can I talk to a person?", role: "user" },+ { content: "Let me check.", role: "assistant" },+ ];++ const result = buildToolSet({ tools });+ await contextStorage.run(ctx, () =>+ executeSdkTool({ messages, tool: result.observe_messages }),+ );++ expect(receivedMessages).toEqual(messages);+ });+it("passes through the input schema to the SDK tool", () => {const schema = {properties: { city: { type: "string" } },diff --git a/packages/eve/src/tools/definition.ts b/packages/eve/src/tools/definition.tsindex 97eabbb75..123844633 100644--- a/packages/eve/src/tools/definition.ts+++ b/packages/eve/src/tools/definition.ts@@ -1,4 +1,4 @@-import type { ToolExecutionOptions } from "ai";+import type { ModelMessage, ToolExecutionOptions } from "ai";import type {StandardJSONSchemaV1,StandardSchemaV1,@@ -189,6 +189,15 @@ export type ToolContext = SessionContext & {* the tool's {@link ApprovalContext}.*/readonly toolName: string;+ /**+ * Messages sent to the model for the step that requested this call, oldest+ * first — the same model input a `step.started` dynamic resolver reads from+ * `ctx.messages`. Excludes system instructions and the assistant response+ * that contains this call. Includes eve-authored context messages, such as+ * request context and recalled memory, and reflects history projection and+ * compaction.+ */+ readonly messages: readonly ModelMessage[];/*** Resolves the bearer token for an inline provider. This accepts the same* auth shapes as a connection's `auth` field, including `connect("...")`