The Open Framework for Building Agents
fix(eve): restore legacy session history (#3303)
Chad Hietalafb6750fdaddb
diff --git a/.changeset/restore-legacy-message-history.md b/.changeset/restore-legacy-message-history.mdnew file mode 100644index 000000000..8f5342c5b--- /dev/null+++ b/.changeset/restore-legacy-message-history.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Resume sessions whose history predates user-message provenance instead of failing with a missing-kind error. Existing unclassified messages retain their content and are marked `legacy.unknown`, without treating unknown framework input as a new human request after compaction.diff --git a/docs/guides/instrumentation.md b/docs/guides/instrumentation.mdindex d8a0da99c..5ff98c1ea 100644--- a/docs/guides/instrumentation.md+++ b/docs/guides/instrumentation.md@@ -154,6 +154,15 @@ Every memory span includes `gen_ai.operation.name` and `gen_ai.memory.store.id`.`gen_ai.memory.records` contains recalled record content only when `recordInputs` is enabled. eve classifies recalled records as input content because they become part of the model context. eve does not set `gen_ai.memory.query.text` because a memory provider receives structured conversation messages, not a standalone search-query string. The `agent.memory.slot` and `agent.memory.phase` attributes identify the eve slot and lifecycle boundary without adding either to the span name.+Messages in `gen_ai.input.messages` include a `kind` for user-role entries.+New human input uses `user`; framework-authored input uses namespaced kinds+such as `context.instruction` and `execution.background_task`. When resuming+history saved before eve 0.54, entries without a kind use `legacy.unknown`:+the old format did not reliably distinguish human input from framework input.+Their content and metadata remain unchanged, and already classified entries+retain their kind. Unknown legacy entries are not replayed as the latest human+request after compaction.+## Agent trace contractThe provider layout and zero-config local tracing emit the following spans.diff --git a/packages/eve/extension-contracts/compatibility/dynamicTool/v33.ts b/packages/eve/extension-contracts/compatibility/dynamicTool/v33.tsnew file mode 100644index 000000000..0552088f0--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/dynamicTool/v33.ts@@ -0,0 +1,20 @@+import { z } from "zod";++import { defineDynamic, defineTool } from "#public/tools/index.js";++export default defineDynamic({+ events: {+ "session.started": () =>+ defineTool({+ description: "Report deployment progress.",+ inputSchema: z.object({ service: z.string() }),+ outputSchema: z.object({ url: z.string() }),+ label: {+ complete: ({ service }, { url }) => `Deployed ${service} to ${url}`,+ delta: ({ service }) => `Deploying ${service}`,+ start: ({ service }) => `Deploy ${service}`,+ },+ execute: async ({ service }) => ({ url: `https://${service}.example.com` }),+ }),+ },+});diff --git a/packages/eve/extension-contracts/compatibility/tool/v35.ts b/packages/eve/extension-contracts/compatibility/tool/v35.tsnew file mode 100644index 000000000..75ca1333d--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/tool/v35.ts@@ -0,0 +1,16 @@+import { z } from "zod";++import { defineTool } from "#public/tools/index.js";++export default defineTool({+ description: "Report the active session.",+ inputSchema: z.object({}),+ outputSchema: z.object({+ sessionId: z.string(),+ turnId: z.string(),+ }),+ execute: (_input, ctx) => ({+ sessionId: ctx.session.id,+ turnId: ctx.session.turn.id,+ }),+});diff --git a/packages/eve/extension-contracts/reports/dynamicTool/v34.json b/packages/eve/extension-contracts/reports/dynamicTool/v34.jsonnew file mode 100644index 000000000..9bc16055d--- /dev/null+++ b/packages/eve/extension-contracts/reports/dynamicTool/v34.json@@ -0,0 +1,14 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "dynamicTool",+ "epoch": 34,+ "sha256": "e2e152e53aeb768fbed4f9c39ed4a19b8df8c2544ae408d32025657edeeaa434",+ "exports": [+ "DynamicToolEntry",+ "DynamicToolEvents",+ "DynamicToolResult",+ "DynamicToolSet",+ "defineDurableCallback",+ "defineDynamic"+ ]+}diff --git a/packages/eve/extension-contracts/reports/tool/v36.json b/packages/eve/extension-contracts/reports/tool/v36.jsonnew file mode 100644index 000000000..6c5dae1bf--- /dev/null+++ b/packages/eve/extension-contracts/reports/tool/v36.json@@ -0,0 +1,20 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "tool",+ "epoch": 36,+ "sha256": "1b9eb09a8e95b4fc87fffe07154a7c7ade72151a8480b86d7c3fd93ecb58dd17",+ "exports": [+ "defaultWebSearch",+ "defineTool",+ "defineWorkflowTool",+ "disableTool",+ "experimental_workflow",+ "isDisabledToolSentinel",+ "isExperimentalWorkflowToolDefinition",+ "isWebSearchToolDefinition",+ "toolOutput",+ "toolOutputPart",+ "toolResultFrom",+ "webSearch"+ ]+}diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.tsindex f918b885c..44bb87e44 100644--- a/packages/eve/src/compiler/extension-compatibility.ts+++ b/packages/eve/src/compiler/extension-compatibility.ts@@ -22,8 +22,8 @@ interface ExtensionCapabilityContract {const EXTENSION_CAPABILITY_CONTRACTS = {extension: { current: 1, supported: [1], dropped: {} },tool: {- current: 35,- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 28, 29, 30, 31, 32, 34, 35],+ current: 36,+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 28, 29, 30, 31, 32, 34, 35, 36],dropped: {14: "TaskExec.delegated was removed; migrate to workflow-backed background tools",15: "TaskExec replaces stageEffect with send",@@ -43,10 +43,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},dynamicTool: {- current: 33,+ current: 34,supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 28, 29, 30, 31, 32,- 33,+ 33, 34,],dropped: {21: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",diff --git a/packages/eve/src/execution/durable-session-migrations/snapshot.ts b/packages/eve/src/execution/durable-session-migrations/snapshot.tsindex 64313e99c..7e7513779 100644--- a/packages/eve/src/execution/durable-session-migrations/snapshot.ts+++ b/packages/eve/src/execution/durable-session-migrations/snapshot.ts@@ -14,8 +14,11 @@* 4. Append the migration to {@link snapshotMigrations}.* 5. Cover it in `snapshot.test.ts`.*/+import type { ModelMessage } from "ai";+import type { DurableSessionSnapshot } from "#execution/durable-session-store.js";import { DURABLE_SESSION_VERSION } from "#execution/durable-session-store.js";+import { validateHarnessModelMessages } from "#harness/messages.js";import { runMigrationChain, type VersionMigration } from "./chain.js";@@ -30,10 +33,22 @@ const snapshotMigrations: readonly VersionMigration[] = [];* {@link DURABLE_SESSION_VERSION}. Pure; safe to call inline.*/export function migrateDurableSessionSnapshot(value: unknown): DurableSessionSnapshot {- return runMigrationChain<DurableSessionSnapshot>({+ const snapshot = runMigrationChain<DurableSessionSnapshot>({label: "durable session snapshot",migrations: snapshotMigrations,targetVersion: DURABLE_SESSION_VERSION,value,});++ // Pre-0.54 history used user-role messages for both human and framework input.+ // Keep v1 so a pinned older driver can still forward the updated snapshot.+ const history = snapshot.session.history.map((message: ModelMessage) =>+ message.role === "user" && !("kind" in message)+ ? { ...message, kind: "legacy.unknown" as const }+ : message,+ );+ return {+ ...snapshot,+ session: { ...snapshot.session, history: validateHarnessModelMessages(history) },+ };}diff --git a/packages/eve/src/execution/durable-session-store.test.ts b/packages/eve/src/execution/durable-session-store.test.tsindex e84d8108a..3e063f9bb 100644--- a/packages/eve/src/execution/durable-session-store.test.ts+++ b/packages/eve/src/execution/durable-session-store.test.ts@@ -202,15 +202,40 @@ describe("durable-session-store cross-version contract", () => {expect(getRunMock).not.toHaveBeenCalled();});+ it("classifies unmarked legacy history in an embedded snapshot", async () => {+ const session = buildSession({+ continuationToken: "http:test",+ sessionId: "wrun_embedded_legacy",+ });+ const state = createDurableSessionState({ session });+ const legacySnapshot = {+ ...state.snapshot,+ session: {+ ...state.snapshot!.session,+ history: [{ content: "Retained before eve 0.54.", role: "user" }],+ },+ } as DurableSessionSnapshot;++ const durableSession = await readDurableSession({ ...state, snapshot: legacySnapshot });++ expect(durableSession.history).toEqual([+ { content: "Retained before eve 0.54.", kind: "legacy.unknown", role: "user" },+ ]);+ expect(getRunMock).not.toHaveBeenCalled();+ });+it("cancels the legacy tail read after loading one durable session snapshot", async () => {const session = buildSession({continuationToken: "http:test",sessionId: "wrun_tail_cancel",});- const snapshot: DurableSessionSnapshot = {- session: projectToDurableSession(session),+ const snapshot = {+ session: {+ ...projectToDurableSession(session),+ history: [{ content: "Retained before eve 0.54.", role: "user" }],+ },version: DURABLE_SESSION_VERSION,- };+ } as DurableSessionSnapshot;const cancel = vi.fn();const stream = new ReadableStream<DurableSessionSnapshot>({cancel,@@ -223,7 +248,10 @@ describe("durable-session-store cross-version contract", () => {const durableSession = await readDurableSession(projectSessionState({ session }));- expect(durableSession).toEqual(snapshot.session);+ expect(durableSession).toEqual({+ ...snapshot.session,+ history: [{ content: "Retained before eve 0.54.", kind: "legacy.unknown", role: "user" }],+ });expect(getRunMock).toHaveBeenCalledWith("wrun_tail_cancel");expect(getReadable).toHaveBeenCalledWith({namespace: "eve.session",diff --git a/packages/eve/src/execution/legacy-session-history.integration.test.ts b/packages/eve/src/execution/legacy-session-history.integration.test.tsnew file mode 100644index 000000000..2608168f5--- /dev/null+++ b/packages/eve/src/execution/legacy-session-history.integration.test.ts@@ -0,0 +1,84 @@+import { describe, expect, it } from "vitest";++import { migrateDurableSessionSnapshot } from "#execution/durable-session-migrations/snapshot.js";+import {+ createDurableSessionState,+ type DurableSessionSnapshot,+ readDurableSession,+} from "#execution/durable-session-store.js";+import {+ createSession,+ hydrateDurableSession,+ projectToDurableSession,+} from "#execution/session.js";+import { validateHarnessModelMessages } from "#harness/messages.js";+import { genAiInputMessagesAttribute } from "#tracing/agent-otel-content.js";++const turnAgent = {+ id: "test-agent",+ instructions: ["Be concise."],+ model: { id: "test-model" },+ tools: [],+ workspaceSpec: { rootEntries: [] },+};++describe("pre-0.54 durable history", () => {+ it("restores old user and framework messages without inventing provenance", async () => {+ const attachment = new URL("https://example.com/report.pdf");+ const history = [+ { content: "Please summarize the report.", role: "user" },+ { content: "A background task completed.", role: "user" },+ {+ content: [{ data: attachment, mediaType: "application/pdf", type: "file" }],+ legacyField: "retained",+ metadata: { retained: true },+ role: "user",+ },+ { content: "Here is the summary.", role: "assistant" },+ { content: "Be concise.", kind: "context.instruction", role: "user" },+ ];+ const initial = createSession({+ continuationToken: "test-token",+ sessionId: "test-session",+ turnAgent,+ });+ const state = createDurableSessionState({ session: initial });+ const legacySnapshot = {+ ...state.snapshot,+ retained: "snapshot field",+ session: { ...projectToDurableSession(initial), history },+ } as DurableSessionSnapshot;++ const durable = await readDurableSession({ ...state, snapshot: legacySnapshot });+ const resumed = hydrateDurableSession({ durable, turnAgent });++ expect(resumed.history).toEqual([+ ...history.slice(0, 3).map((message) => ({ ...message, kind: "legacy.unknown" })),+ ...history.slice(3),+ ]);+ expect(history[0]).not.toHaveProperty("kind");+ expect(genAiInputMessagesAttribute(resumed.history)).toContain('"kind":"legacy.unknown"');++ const saved = createDurableSessionState({ session: resumed });+ expect(saved.version).toBe(state.version);+ expect(saved.snapshot?.version).toBe(state.snapshot?.version);+ expect(await readDurableSession(saved)).toEqual(durable);++ const migrated = migrateDurableSessionSnapshot(legacySnapshot);+ expect(migrated).toHaveProperty("retained", "snapshot field");+ });++ it("does not repair malformed explicit kinds or relax new-message validation", () => {+ expect(() => validateHarnessModelMessages([{ content: "New input", role: "user" }])).toThrow(+ "Expected every user-role model message to have a kind.",+ );+ expect(() =>+ migrateDurableSessionSnapshot({+ session: {+ history: [{ content: "Old input", kind: "invalid", role: "user" }],+ },+ version: 1,+ }),+ ).toThrow("Expected every user-role model message to have a kind.");+ });+});diff --git a/packages/eve/src/harness/compaction.test.ts b/packages/eve/src/harness/compaction.test.tsindex 118312ce1..d00cce7f2 100644--- a/packages/eve/src/harness/compaction.test.ts+++ b/packages/eve/src/harness/compaction.test.ts@@ -786,6 +786,22 @@ describe("compactMessages: summarization fallback", () => {expect(result.at(-1)).toEqual(task);});+ it("does not replay unknown legacy provenance as the user's latest request", async () => {+ const task = user("Summarize the report.");+ const legacy = {+ content: "A background task completed.",+ kind: "legacy.unknown",+ role: "user",+ } as const;+ const [call, resultMsg] = toolExchange({ callId: "call-1", payloadChars: 100 });+ const { result } = await compact(+ [user("old notes ".repeat(4_000)), task, legacy, call, resultMsg],+ { recentWindowSize: 2, threshold: 2_048 },+ );++ expect(result.at(-1)).toEqual(task);+ });+it("makes room for the original task before keeping a large tool-result tail", async () => {const task = user("Keep these requirements. ".repeat(25));const [call, resultMsg] = toolExchange({ callId: "call-1", payloadChars: 600 });diff --git a/packages/eve/src/harness/compaction.ts b/packages/eve/src/harness/compaction.tsindex fbf7cea54..4a0116692 100644--- a/packages/eve/src/harness/compaction.ts+++ b/packages/eve/src/harness/compaction.ts@@ -9,7 +9,11 @@ import {stubContentOutputFileParts,TRANSCRIPT_PAYLOAD_LIMIT,} from "#harness/compaction-prompt.js";-import { createFrameworkUserMessage, isFrameworkUserMessage } from "#harness/messages.js";+import {+ createFrameworkUserMessage,+ isFrameworkUserMessage,+ isUserModelMessage,+} from "#harness/messages.js";import { estimateTokens } from "#harness/token-estimate.js";import type { RuntimeModelReference } from "#runtime/agent/bootstrap.js";import type { CompactionConfig, ToolLoopHarnessConfig } from "#harness/types.js";@@ -383,7 +387,10 @@ function findLastRealUserMessage(conversation: readonly ModelMessage[]): ModelMeif (message?.role !== "user" || typeof message.content !== "string") {continue;}- if (isFrameworkUserMessage(message)) {+ if (+ isFrameworkUserMessage(message) ||+ (isUserModelMessage(message) && message.kind === "legacy.unknown")+ ) {continue;}return message;diff --git a/packages/eve/src/harness/messages.test.ts b/packages/eve/src/harness/messages.test.tsindex bb9d8a055..cc1b10d03 100644--- a/packages/eve/src/harness/messages.test.ts+++ b/packages/eve/src/harness/messages.test.ts@@ -326,6 +326,18 @@ describe("createFrameworkUserMessage", () => {expect(isFrameworkUserMessage(message)).toBe(false);});+ it("recognizes unknown legacy provenance without treating it as framework-authored", () => {+ const message = {+ content: "A retained pre-0.54 message",+ kind: "legacy.unknown",+ role: "user",+ } as const;++ expect(isUserMessageKind(message.kind)).toBe(true);+ expect(isUserModelMessage(message)).toBe(true);+ expect(isFrameworkUserMessage(message)).toBe(false);+ });+it("rejects unclassified user messages before history retention", () => {expect(() =>validateHarnessModelMessages([{ content: "A user message", role: "user" }]),diff --git a/packages/eve/src/harness/messages.ts b/packages/eve/src/harness/messages.tsindex adc53600e..cf07eac54 100644--- a/packages/eve/src/harness/messages.ts+++ b/packages/eve/src/harness/messages.ts@@ -21,7 +21,7 @@ export type FrameworkMessageKind =| "execution.retry";/** Semantic classification for every user-role message in model history. */-export type UserMessageKind = "user" | FrameworkMessageKind;+export type UserMessageKind = "user" | "legacy.unknown" | FrameworkMessageKind;/** A user-role message that is safe to retain in framework model history. */export type UserModelMessage = Extract<ModelMessage, { readonly role: "user" }> & {@@ -69,7 +69,7 @@ export function createFrameworkUserMessage(/** True when a value is a recognized classification for a user-role message. */export function isUserMessageKind(value: unknown): value is UserMessageKind {- return value === "user" || isFrameworkMessageKind(value);+ return value === "user" || value === "legacy.unknown" || isFrameworkMessageKind(value);}/** True when a user-role model message has the required semantic classification. */@@ -81,7 +81,7 @@ export function isUserModelMessage(message: ModelMessage): message is UserModelM/** True when a user-role message was authored by the framework. */export function isFrameworkUserMessage(message: ModelMessage): message is FrameworkUserMessage {- return isUserModelMessage(message) && message.kind !== "user";+ return isUserModelMessage(message) && isFrameworkMessageKind(message.kind);}/** Validates that every user-role message is classified before history retains it. */