Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
index 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 contract
The 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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[]): ModelMe
if (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.ts
index 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.ts
index 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. */