Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.mdx
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
index 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.ts
index 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: ToolExecuteWithAuthInpu
const 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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("...")`