Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): add semantic model message kinds (#3155)

Chad Hietalaf60c64b18689
diff --git a/.changeset/brand-synthetic-model-messages.md b/.changeset/brand-synthetic-model-messages.md
new file mode 100644
index 000000000..21ef5ca07
--- /dev/null
+++ b/.changeset/brand-synthetic-model-messages.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Brand every user-role model message in `gen_ai.input.messages`. Real user input is `user`; framework-authored messages use namespaced provenance such as `context.instruction` and `execution.background_task`.
diff --git a/packages/eve/extension-contracts/compatibility/dynamicTool/v32.ts b/packages/eve/extension-contracts/compatibility/dynamicTool/v32.ts
new file mode 100644
index 000000000..0552088f0
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/dynamicTool/v32.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/v34.ts b/packages/eve/extension-contracts/compatibility/tool/v34.ts
new file mode 100644
index 000000000..75ca1333d
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/tool/v34.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/v33.json b/packages/eve/extension-contracts/reports/dynamicTool/v33.json
new file mode 100644
index 000000000..efc66ae0e
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/dynamicTool/v33.json
@@ -0,0 +1,14 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "dynamicTool",
+ "epoch": 33,
+ "sha256": "bc2062ddd2325888d76b1d7d0d7c30bc80a82213a298532e40d280bfe7eb13e8",
+ "exports": [
+ "DynamicToolEntry",
+ "DynamicToolEvents",
+ "DynamicToolResult",
+ "DynamicToolSet",
+ "defineDurableCallback",
+ "defineDynamic"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/tool/v35.json b/packages/eve/extension-contracts/reports/tool/v35.json
new file mode 100644
index 000000000..1c81a9c59
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/tool/v35.json
@@ -0,0 +1,20 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "tool",
+ "epoch": 35,
+ "sha256": "529424f22f7d526261c063d4223ccfe80aea1baf1bd5609c40d2fcb973a56c92",
+ "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 e5be98a34..dbe7fc787 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: 34,
- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 28, 29, 30, 31, 32, 34],
+ current: 35,
+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 28, 29, 30, 31, 32, 34, 35],
dropped: {
14: "TaskExec.delegated was removed; migrate to workflow-backed background tools",
15: "TaskExec replaces stageEffect with send",
@@ -43,9 +43,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
dynamicTool: {
- current: 32,
+ current: 33,
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,
],
dropped: {
21: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
diff --git a/packages/eve/src/context/dynamic-instruction-lifecycle.test.ts b/packages/eve/src/context/dynamic-instruction-lifecycle.test.ts
index f42e36229..87d2cc6b6 100644
--- a/packages/eve/src/context/dynamic-instruction-lifecycle.test.ts
+++ b/packages/eve/src/context/dynamic-instruction-lifecycle.test.ts
@@ -110,7 +110,7 @@ describe("dispatchDynamicInstructionEvent", () => {
expect(buildDynamicInstructionMessages(ctx)).toEqual([]);
expect(drainDynamicInstructionUserMessages(ctx)).toEqual([
- { role: "user", content: "Dynamic user context." },
+ { role: "user", content: "Dynamic user context.", kind: "context.instruction" },
]);
expect([...ctx.entries()].map(([key]) => key.name)).not.toContain(
"eve.pendingDynamicInstructionUserMessages",
@@ -147,8 +147,8 @@ describe("dispatchDynamicInstructionEvent", () => {
expect(snapshots).toEqual([["Static user."], ["Static user.", "Session user."]]);
expect(drainDynamicInstructionUserMessages(ctx)).toEqual([
- { content: "Session user.", role: "user" },
- { content: "Turn user.", role: "user" },
+ { content: "Session user.", role: "user", kind: "context.instruction" },
+ { content: "Turn user.", role: "user", kind: "context.instruction" },
]);
});
@@ -293,7 +293,7 @@ describe("dispatchDynamicInstructionEvent", () => {
});
expect(buildDynamicInstructionMessages(ctx)).toEqual([]);
expect(drainDynamicInstructionUserMessages(ctx)).toEqual([
- { content: "user context", role: "user" },
+ { content: "user context", kind: "context.instruction", role: "user" },
]);
result = "throw";
diff --git a/packages/eve/src/context/dynamic-instruction-lifecycle.ts b/packages/eve/src/context/dynamic-instruction-lifecycle.ts
index 4eb552a8d..59eda5325 100644
--- a/packages/eve/src/context/dynamic-instruction-lifecycle.ts
+++ b/packages/eve/src/context/dynamic-instruction-lifecycle.ts
@@ -17,6 +17,7 @@ import {
TurnDynamicInstructionsKey,
} from "#context/keys.js";
import { buildResolveContext } from "#context/dynamic-resolve-context.js";
+import { createFrameworkUserMessage, type UserModelMessage } from "#harness/messages.js";
const log = createLogger("dynamic-instructions");
@@ -24,7 +25,7 @@ type SlugMessageMap = Record<string, readonly SystemModelMessage[]>;
type LoweredInstruction =
| { readonly role: "system"; readonly message: SystemModelMessage }
- | { readonly role: "user"; readonly message: ModelMessage }
+ | { readonly role: "user"; readonly message: UserModelMessage }
| undefined;
function lowerInstruction(definition: InstructionsDefinition): LoweredInstruction {
@@ -36,7 +37,7 @@ function lowerInstruction(definition: InstructionsDefinition): LoweredInstructio
if (content.length === 0) return undefined;
return normalized.role === "system"
? { role: "system", message: { role: "system", content } }
- : { role: "user", message: { role: "user", content } };
+ : { role: "user", message: createFrameworkUserMessage("context.instruction", content) };
}
function durableKeyForEvent(eventType: string): ContextKey<SlugMessageMap> | undefined {
@@ -72,7 +73,7 @@ export function prepareDynamicInstructionPreamble(
}
/** Drains user-role results and clears the instructions-only virtual context. */
-export function drainDynamicInstructionUserMessages(ctx: AlsContext): ModelMessage[] {
+export function drainDynamicInstructionUserMessages(ctx: AlsContext): UserModelMessage[] {
const messages = [...(ctx.get(PendingDynamicInstructionUserMessagesKey) ?? [])];
ctx.delete(DynamicInstructionResolveMessagesKey);
ctx.delete(PendingDynamicInstructionUserMessagesKey);
diff --git a/packages/eve/src/context/keys.ts b/packages/eve/src/context/keys.ts
index dd0d03632..f199bd723 100644
--- a/packages/eve/src/context/keys.ts
+++ b/packages/eve/src/context/keys.ts
@@ -24,6 +24,7 @@ import {
} from "#execution/wire/session-inbox-contract.js";
import { SESSION_CALLBACK_CONTEXT_KEY_NAME } from "#context/key-names.js";
import type { InstrumentationChannelDeliveryRef } from "#instrumentation/lifecycle.js";
+import type { UserModelMessage } from "#harness/messages.js";
import type { HandleEventFn } from "#harness/types.js";
import type { PersistedDynamicToolMetadata } from "#context/dynamic-tool-metadata.js";
import type { DynamicSubagentAgentConfig } from "#runtime/subagents/dynamic-agent-config.js";
@@ -344,6 +345,6 @@ export const DynamicInstructionResolveMessagesKey = new ContextKey<readonly Mode
);
/** User-role results waiting to be committed immediately after a preamble. */
-export const PendingDynamicInstructionUserMessagesKey = new ContextKey<readonly ModelMessage[]>(
+export const PendingDynamicInstructionUserMessagesKey = new ContextKey<readonly UserModelMessage[]>(
"eve.pendingDynamicInstructionUserMessages",
);
diff --git a/packages/eve/src/context/memory-lifecycle.test.ts b/packages/eve/src/context/memory-lifecycle.test.ts
index 6a9ce8000..92b373d61 100644
--- a/packages/eve/src/context/memory-lifecycle.test.ts
+++ b/packages/eve/src/context/memory-lifecycle.test.ts
@@ -132,8 +132,8 @@ describe("memory lifecycle", () => {
expect(seen).toEqual([[history[0]!], [history[0]!]]);
expect(projected).toEqual([
history[0],
- { content: "alpha memory", role: "user" },
- { content: "bravo memory", role: "user" },
+ { content: "alpha memory", kind: "memory.load", role: "user" },
+ { content: "bravo memory", kind: "memory.load", role: "user" },
input[0],
]);
expect(JSON.stringify(commit.history)).toContain("eve.memory");
@@ -361,7 +361,7 @@ describe("memory lifecycle", () => {
expect(phases).toEqual(["compaction.requested", "compaction.completed"]);
expect(projected).toEqual([
{ content: "ordinary", role: "user" },
- { content: "new profile", role: "user" },
+ { content: "new profile", kind: "memory.load", role: "user" },
]);
expect(drainMemoryCommit(ctx)?.history).toHaveLength(3);
});
diff --git a/packages/eve/src/execution/cancelled-turn-message.test.ts b/packages/eve/src/execution/cancelled-turn-message.test.ts
new file mode 100644
index 000000000..96230b55e
--- /dev/null
+++ b/packages/eve/src/execution/cancelled-turn-message.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+
+import { preserveCancelledTurnMessage } from "#execution/cancelled-turn-message.js";
+import { markFrameworkStepInput } from "#harness/messages.js";
+import type { HarnessSession } from "#harness/types.js";
+
+function session(): HarnessSession {
+ return {
+ agent: {
+ modelReference: { id: "test-model" },
+ system: "You are a test assistant.",
+ tools: [],
+ },
+ compaction: { recentWindowSize: 10, threshold: 100_000 },
+ continuationToken: "http:cancelled-turn-message",
+ history: [],
+ sessionId: "cancelled-turn-message",
+ };
+}
+
+describe("preserveCancelledTurnMessage", () => {
+ it("preserves the framework kind on a cancelled task delivery", async () => {
+ const result = await preserveCancelledTurnMessage(
+ session(),
+ markFrameworkStepInput(
+ { message: "Background task task_1 completed." },
+ "execution.background_task",
+ ),
+ );
+
+ expect(result.history).toEqual([
+ {
+ content: "Background task task_1 completed.",
+ kind: "execution.background_task",
+ role: "user",
+ },
+ ]);
+ });
+
+ it("brands a cancelled real user message as user", async () => {
+ const result = await preserveCancelledTurnMessage(session(), {
+ message: "Cancel this turn.",
+ });
+
+ expect(result.history).toEqual([{ content: "Cancel this turn.", kind: "user", role: "user" }]);
+ });
+});
diff --git a/packages/eve/src/execution/cancelled-turn-message.ts b/packages/eve/src/execution/cancelled-turn-message.ts
index 8fab18c8b..a098ad8e3 100644
--- a/packages/eve/src/execution/cancelled-turn-message.ts
+++ b/packages/eve/src/execution/cancelled-turn-message.ts
@@ -1,5 +1,10 @@
import { stageAttachmentsToSandbox } from "#harness/attachment-staging.js";
-import { normalizeUserContent } from "#harness/messages.js";
+import {
+ createFrameworkUserMessage,
+ createUserMessage,
+ frameworkMessageKindForStepInput,
+ normalizeUserContent,
+} from "#harness/messages.js";
import type { HarnessSession, StepInput } from "#harness/types.js";
export async function preserveCancelledTurnMessage(
@@ -9,5 +14,14 @@ export async function preserveCancelledTurnMessage(
const message = normalizeUserContent(input?.message);
if (message === undefined) return session;
const content = await stageAttachmentsToSandbox(message);
- return { ...session, history: [...session.history, { content, role: "user" }] };
+ const frameworkMessageKind = frameworkMessageKindForStepInput(input);
+ return {
+ ...session,
+ history: [
+ ...session.history,
+ frameworkMessageKind === undefined
+ ? createUserMessage("user", content)
+ : createFrameworkUserMessage(frameworkMessageKind, content),
+ ],
+ };
}
diff --git a/packages/eve/src/execution/compaction.ts b/packages/eve/src/execution/compaction.ts
index 7da2a689a..bcd3a160e 100644
--- a/packages/eve/src/execution/compaction.ts
+++ b/packages/eve/src/execution/compaction.ts
@@ -1,7 +1,6 @@
-import type { ModelMessage } from "ai";
-
import { clearReadFileState } from "#execution/tools/file-state.js";
import { getTodoCompactionMessage } from "#execution/tools/todo.js";
+import type { HarnessModelMessage } from "#harness/messages.js";
/**
* Re-applies framework-owned state preservation after the harness compacts
@@ -15,7 +14,7 @@ import { getTodoCompactionMessage } from "#execution/tools/todo.js";
* Must be called inside the harness step's `AlsContext`; both steps read
* durable context state.
*/
-export function preserveFrameworkStateOnCompaction(): readonly ModelMessage[] {
+export function preserveFrameworkStateOnCompaction(): readonly HarnessModelMessage[] {
clearReadFileState();
const todo = getTodoCompactionMessage();
return todo === undefined ? [] : [todo];
diff --git a/packages/eve/src/execution/durable-session-store.test.ts b/packages/eve/src/execution/durable-session-store.test.ts
index 7d30ccbb0..e84d8108a 100644
--- a/packages/eve/src/execution/durable-session-store.test.ts
+++ b/packages/eve/src/execution/durable-session-store.test.ts
@@ -293,7 +293,7 @@ function buildSession(input: {
threshold: 180_000,
},
continuationToken: input.continuationToken,
- history: [{ content: "hi", role: "user" }],
+ history: [{ content: "hi", kind: "user", role: "user" }],
sessionId: input.sessionId,
};
}
diff --git a/packages/eve/src/execution/durable-session-store.ts b/packages/eve/src/execution/durable-session-store.ts
index 00a4158eb..b2d8925ed 100644
--- a/packages/eve/src/execution/durable-session-store.ts
+++ b/packages/eve/src/execution/durable-session-store.ts
@@ -15,9 +15,8 @@
* preserves unknown POJO fields); shape-breaking changes bump
* `version` and add a migrator.
*/
-import type { ModelMessage } from "ai";
-
import { getHarnessEmissionState, type HarnessEmissionState } from "#harness/emission.js";
+import type { HarnessModelMessage } from "#harness/messages.js";
import { hasProxyInputRequests } from "#harness/proxy-input-requests.js";
import type { HarnessSession, SessionStateMap } from "#harness/types.js";
import { migrateDurableSessionSnapshot } from "#execution/durable-session-migrations/snapshot.js";
@@ -80,7 +79,7 @@ export interface DurableSession {
*/
readonly rootSessionId?: string;
readonly continuationToken: string;
- readonly history: ModelMessage[];
+ readonly history: HarnessModelMessage[];
readonly limits?: HarnessSession["limits"];
readonly outputSchema?: JsonObject;
readonly state?: SessionStateMap;
diff --git a/packages/eve/src/execution/session.test.ts b/packages/eve/src/execution/session.test.ts
index 2a67320b3..67cdda9a7 100644
--- a/packages/eve/src/execution/session.test.ts
+++ b/packages/eve/src/execution/session.test.ts
@@ -130,31 +130,39 @@ describe("createSession", () => {
});
it("copies static user instructions only when creating a fresh session", () => {
- const initialMessages = [{ content: "Pinned tenant policy.", role: "user" as const }];
+ const initialMessages = [
+ { content: "Pinned tenant policy.", kind: "user" as const, role: "user" as const },
+ ];
const session = createSession({
continuationToken: "root-token",
sessionId: "sess-root",
turnAgent: createTestTurnAgent({ initialMessages }),
});
- initialMessages[0] = { content: "mutated", role: "user" };
+ initialMessages[0] = { content: "mutated", kind: "user" as const, role: "user" };
- expect(session.history).toEqual([{ content: "Pinned tenant policy.", role: "user" }]);
+ expect(session.history).toEqual([
+ { content: "Pinned tenant policy.", kind: "user", role: "user" },
+ ]);
const refreshed = refreshSessionFromTurnAgent({
session,
turnAgent: createTestTurnAgent({
- initialMessages: [{ content: "New deployment policy.", role: "user" }],
+ initialMessages: [{ content: "New deployment policy.", kind: "user", role: "user" }],
}),
});
- expect(refreshed.history).toEqual([{ content: "Pinned tenant policy.", role: "user" }]);
+ expect(refreshed.history).toEqual([
+ { content: "Pinned tenant policy.", kind: "user", role: "user" },
+ ]);
const hydrated = hydrateDurableSession({
durable: projectToDurableSession(refreshed),
turnAgent: createTestTurnAgent({
- initialMessages: [{ content: "Another deployment policy.", role: "user" }],
+ initialMessages: [{ content: "Another deployment policy.", kind: "user", role: "user" }],
}),
});
- expect(hydrated.history).toEqual([{ content: "Pinned tenant policy.", role: "user" }]);
+ expect(hydrated.history).toEqual([
+ { content: "Pinned tenant policy.", kind: "user", role: "user" },
+ ]);
});
it("defaults description and inputSchema when null", () => {
@@ -448,7 +456,7 @@ describe("refreshSessionFromTurnAgent", () => {
const refreshed = refreshSessionFromTurnAgent({
session: {
...session,
- history: [{ content: "previous message", role: "user" }],
+ history: [{ content: "previous message", kind: "user", role: "user" }],
},
turnAgent: createTestTurnAgent({
instructions: ["Completely different system prompt."],
@@ -470,7 +478,9 @@ describe("refreshSessionFromTurnAgent", () => {
}),
});
- expect(refreshed.history).toEqual([{ content: "previous message", role: "user" }]);
+ expect(refreshed.history).toEqual([
+ { content: "previous message", kind: "user", role: "user" },
+ ]);
expect(refreshed.agent.compactionModelReference).toEqual({
id: "summary-model",
});
diff --git a/packages/eve/src/execution/session.ts b/packages/eve/src/execution/session.ts
index 9568e79ef..e3457942f 100644
--- a/packages/eve/src/execution/session.ts
+++ b/packages/eve/src/execution/session.ts
@@ -1,5 +1,6 @@
import type { DurableSession } from "#execution/durable-session-store.js";
import { formatAvailableSkillsSection } from "#execution/skills/instructions.js";
+import { validateHarnessModelMessages } from "#harness/messages.js";
import type {
HarnessSession,
SessionAgent,
@@ -281,7 +282,7 @@ export function hydrateDurableSession(input: {
thresholdPercent: input.compactionOverrides?.thresholdPercent,
}),
continuationToken: durable.continuationToken,
- history: durable.history,
+ history: validateHarnessModelMessages(durable.history),
sessionId: durable.sessionId,
};
diff --git a/packages/eve/src/execution/task-model-retry.integration.test.ts b/packages/eve/src/execution/task-model-retry.integration.test.ts
index fa2109cb3..a0d9284c1 100644
--- a/packages/eve/src/execution/task-model-retry.integration.test.ts
+++ b/packages/eve/src/execution/task-model-retry.integration.test.ts
@@ -20,7 +20,7 @@ describe("task model retry integration", () => {
expect(outcome.result.attempt).toBe(2);
expect(outcome.result.output).toBe("Recovered task output.");
expect(outcome.result.historyBeforeModelCall).toEqual([
- { content: "Complete the delegated task.", role: "user" },
+ { content: "Complete the delegated task.", kind: "user", role: "user" },
{ content: "Prior durable work is complete.", role: "assistant" },
]);
expect(outcome.result.history).toContainEqual({
diff --git a/packages/eve/src/execution/tools/todo.test.ts b/packages/eve/src/execution/tools/todo.test.ts
index cf3907eb9..38a14ec7a 100644
--- a/packages/eve/src/execution/tools/todo.test.ts
+++ b/packages/eve/src/execution/tools/todo.test.ts
@@ -10,6 +10,7 @@ import {
type TodoState,
TodoStateKey,
} from "#execution/tools/todo.js";
+import { isFrameworkUserMessage } from "#harness/messages.js";
function runInContext(
fn: () => unknown,
@@ -147,6 +148,8 @@ describe("getTodoCompactionMessage", () => {
});
expect(message).toBeDefined();
+ expect(message === undefined ? false : isFrameworkUserMessage(message)).toBe(true);
+ expect(message).toMatchObject({ kind: "context.state", role: "user" });
const text = String(message?.content ?? "");
expect(text).toContain("[Your task list was preserved");
expect(text).toContain("[x] [high] Fix bug");
diff --git a/packages/eve/src/execution/tools/todo.ts b/packages/eve/src/execution/tools/todo.ts
index 69efa58cd..7183f82fc 100644
--- a/packages/eve/src/execution/tools/todo.ts
+++ b/packages/eve/src/execution/tools/todo.ts
@@ -1,9 +1,9 @@
-import type { ModelMessage } from "ai";
import { z } from "#compiled/zod/index.js";
import { loadContext } from "#context/container.js";
import { ContextKey } from "#context/key.js";
import { TODO_COMPACTION_PRESERVATION_LABEL } from "#harness/compaction-prompt.js";
+import { createFrameworkUserMessage, type UserModelMessage } from "#harness/messages.js";
// ---------------------------------------------------------------------------
// Durable context key
@@ -47,7 +47,7 @@ function formatTodoSummary(state: TodoState): string | undefined {
* compacts message history, so the agent keeps its task list across
* compaction. Returns `undefined` when there is no list to preserve.
*/
-export function getTodoCompactionMessage(): ModelMessage | undefined {
+export function getTodoCompactionMessage(): UserModelMessage | undefined {
const state = loadContext().get(TodoStateKey);
if (
state === undefined ||
@@ -57,7 +57,7 @@ export function getTodoCompactionMessage(): ModelMessage | undefined {
}
const summary = formatTodoSummary(state);
if (summary === undefined) return undefined;
- return { content: summary, role: "user" };
+ return createFrameworkUserMessage("context.state", summary);
}
function formatTodoResult(state: TodoState): object {
diff --git a/packages/eve/src/execution/workflow-steps.test.ts b/packages/eve/src/execution/workflow-steps.test.ts
index a1406ff98..e27c3cde2 100644
--- a/packages/eve/src/execution/workflow-steps.test.ts
+++ b/packages/eve/src/execution/workflow-steps.test.ts
@@ -1492,7 +1492,11 @@ describe("turnStep", () => {
});
it("prepares resumed-session history before dynamic runtime refresh", async () => {
- const hidden = { content: "HIDE_FROM_RUNTIME_REFRESH", role: "user" as const };
+ const hidden = {
+ content: "HIDE_FROM_RUNTIME_REFRESH",
+ kind: "user" as const,
+ role: "user" as const,
+ };
mockIdentityHistoryViewProjector.mockImplementation(({ messages }) =>
messages.filter((message) => message !== hidden),
);
@@ -1541,7 +1545,7 @@ describe("turnStep", () => {
vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue(compiledBundle);
const session = createStubSession({
history: [
- { content: "first", role: "user" },
+ { content: "first", kind: "user", role: "user" },
hidden,
{ content: "second", role: "assistant" },
],
@@ -1592,7 +1596,7 @@ describe("turnStep", () => {
});
const expectedView = [
- { content: "first", role: "user" },
+ { content: "first", kind: "user", role: "user" },
{ content: "second", role: "assistant" },
];
expect(toolHandler.mock.calls[0]?.[1]).toMatchObject({ messages: expectedView });
@@ -1633,7 +1637,9 @@ describe("turnStep", () => {
turnAgent: TestTurnAgent,
} as never;
vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue(compiledBundle);
- installSessionStoreMocks([createStubSession({ history: [{ content: "raw", role: "user" }] })]);
+ installSessionStoreMocks([
+ createStubSession({ history: [{ content: "raw", kind: "user", role: "user" }] }),
+ ]);
mockIdentityHistoryViewProjector.mockImplementation(() => {
throw new Error("projection failed");
});
@@ -1874,7 +1880,7 @@ describe("turnStep", () => {
it("keeps a session-scoped dynamic model selection when the first turn is cancelled", async () => {
const announcement = "Available skills\n- policy: Tenant policy";
const session = createStubSession({
- history: [{ role: "user", content: announcement }],
+ history: [{ role: "user", content: announcement, kind: "user" }],
});
installSessionStoreMocks([session]);
vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue({
@@ -1944,8 +1950,8 @@ describe("turnStep", () => {
});
expect(result.serializedContext).not.toHaveProperty(ThreadKey.name);
expect(result.sessionState.snapshot?.session.history).toEqual([
- { role: "user", content: announcement },
- { content: "thread=unset; user=cancel this turn", role: "user" },
+ { role: "user", content: announcement, kind: "user" },
+ { content: "thread=unset; user=cancel this turn", kind: "user", role: "user" },
]);
});
@@ -1994,6 +2000,7 @@ describe("turnStep", () => {
{ text: "thread=unset; user=look at this", type: "text" },
expect.objectContaining({ filename: "diagram.png", type: "file" }),
],
+ kind: "user",
role: "user",
},
]);
@@ -2434,7 +2441,8 @@ describe("turnStep", () => {
});
});
- it("sets task-delivery provenance only when the runtime supplies owned task state", async () => {
+ it("marks task-owned deliveries even when task state is unavailable", async () => {
+ const observedInputs: unknown[] = [];
const observedTaskDeliveries: unknown[] = [];
const observedActivityRoots: unknown[] = [];
const metadata = { kind: "report-probe", name: "report_probe" } as const;
@@ -2462,7 +2470,8 @@ describe("turnStep", () => {
});
installSessionStoreMocks([session, session, session]);
vi.mocked(createExecutionNodeStep).mockImplementation(() => {
- return async (stepSession): Promise<StepResult> => {
+ return async (stepSession, stepInput): Promise<StepResult> => {
+ observedInputs.push(stepInput);
observedTaskDeliveries.push(contextStorage.getStore()?.get(TurnTaskDeliveryKey));
observedActivityRoots.push(contextStorage.getStore()?.get(ActivityRootTurnIdKey));
return { next: { done: true, output: "ok" }, session: stepSession };
@@ -2506,6 +2515,13 @@ describe("turnStep", () => {
expect(observedTaskDeliveries).toEqual(["settled", "none", "none"]);
expect(observedActivityRoots).toEqual(["turn-parent", "turn-parent", "turn_0"]);
+ expect(observedInputs[0]).toMatchObject({
+ frameworkMessageKind: "execution.background_task",
+ });
+ expect(observedInputs[1]).toMatchObject({
+ frameworkMessageKind: "execution.background_task",
+ });
+ expect(observedInputs[2]).not.toHaveProperty("frameworkMessageKind");
});
it.each(["none", "initiating"] as const)("sets initiating task phase (%s)", async (phase) => {
@@ -3027,7 +3043,11 @@ describe("turnStep", () => {
principal: { type: "app" } as const,
resume: { nonce: "n1" },
};
- const hidden = { content: "HIDE_FROM_AUTH_CONTINUATION", role: "user" as const };
+ const hidden = {
+ content: "HIDE_FROM_AUTH_CONTINUATION",
+ kind: "user" as const,
+ role: "user" as const,
+ };
mockIdentityHistoryViewProjector.mockImplementation(({ messages }) =>
messages.filter((message) => message !== hidden),
);
@@ -3035,7 +3055,7 @@ describe("turnStep", () => {
(_event: unknown, _context: { readonly messages: readonly ModelMessage[] }) => null,
);
const session = createStubSession({
- history: [{ content: "visible", role: "user" }, hidden],
+ history: [{ content: "visible", kind: "user", role: "user" }, hidden],
state: setPendingAuthorization({ retained: "yes" }, { challenges: [challenge] }),
});
installSessionStoreMocks([session]);
@@ -3117,7 +3137,7 @@ describe("turnStep", () => {
expect(instructionHandler).toHaveBeenCalledTimes(2);
for (const call of instructionHandler.mock.calls) {
expect(call[1]).toMatchObject({
- messages: [{ content: "visible", role: "user" }],
+ messages: [{ content: "visible", kind: "user", role: "user" }],
});
}
expect(persistedSession?.history).toContain(hidden);
diff --git a/packages/eve/src/execution/workflow-steps.ts b/packages/eve/src/execution/workflow-steps.ts
index 002d2e033..1dbb8163c 100644
--- a/packages/eve/src/execution/workflow-steps.ts
+++ b/packages/eve/src/execution/workflow-steps.ts
@@ -47,7 +47,7 @@ import { setChannelContext } from "#execution/channel-context.js";
import { observeSessionActivity } from "#execution/session-activity-projection.js";
import { hasPendingInputBatch } from "#harness/input-requests.js";
import { activeTurnId } from "#harness/active-turn-id.js";
-import { coalesceTurnInputs } from "#harness/messages.js";
+import { coalesceTurnInputs, type UserModelMessage } from "#harness/messages.js";
import { getWorkflowTaskCallIds, isWorkflowTaskInterrupt } from "#harness/workflow-task-state.js";
import { getPendingWorkflowInterrupt } from "#harness/workflow-interrupt-state.js";
import type { HandleEventFn, HarnessSession, StepInput, StepResult } from "#harness/types.js";
@@ -76,6 +76,8 @@ import { createDurableSessionState, readDurableSession } from "#execution/durabl
import type { TurnStepInput } from "#execution/durable-session-migrations/turn-workflow.js";
import { buildRuntimeIdentity, createExecutionNodeStep } from "#execution/node-step.js";
import {
+ getBackgroundTaskDelivery,
+ markBackgroundTaskStepInput,
resolveInitiatingTaskContext,
resolveTaskDeliveryContext,
} from "#tasks/delivery-context.js";
@@ -180,7 +182,7 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
if (input.input?.kind === "deliver" && input.input.auth !== undefined) {
ctx.set(AuthKey, input.input.auth ?? null);
}
-
+ const backgroundTaskDelivery = getBackgroundTaskDelivery(input.input);
const initialSession = hydrateDurableSession({
compactionOverrides: {
thresholdPercent: effectiveAgent.thresholdPercent,
@@ -249,7 +251,9 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
: defaultDeliverResult(payload);
if (result !== undefined && result !== null) {
- results.push(result);
+ results.push(
+ backgroundTaskDelivery === undefined ? result : markBackgroundTaskStepInput(result),
+ );
}
}
} catch (error) {
@@ -265,14 +269,10 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
}
let taskRootTurnId: string | undefined;
- if (
- resolved !== undefined &&
- rawInput.input?.kind === "deliver" &&
- rawInput.input.taskDeliveryId !== undefined
- ) {
+ if (resolved !== undefined && backgroundTaskDelivery !== undefined) {
const taskContext = resolveTaskDeliveryContext({
state: durableSession.state,
- taskDeliveryId: rawInput.input.taskDeliveryId,
+ taskDeliveryId: backgroundTaskDelivery.taskDeliveryId,
});
if (taskContext !== undefined) {
ctx.set(TurnTaskDeliveryKey, taskContext.phase);
@@ -525,7 +525,7 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
let emissionState = getHarnessEmissionState(schemaSession.state);
if (isHarnessBetweenTurns(schemaSession)) {
prepareDynamicInstructionPreamble(ctx, history.messages(schemaSession));
- let instructionMessages: readonly import("ai").ModelMessage[] = [];
+ let instructionMessages: readonly UserModelMessage[] = [];
const traceContext = await prepareWorkflowPreambleTrace({
emissionState,
instrumentation,
diff --git a/packages/eve/src/harness/compaction.test.ts b/packages/eve/src/harness/compaction.test.ts
index 51775e82f..118312ce1 100644
--- a/packages/eve/src/harness/compaction.test.ts
+++ b/packages/eve/src/harness/compaction.test.ts
@@ -8,6 +8,7 @@ import {
resolveCompactionModel,
shouldCompact,
} from "#harness/compaction.js";
+import { createFrameworkUserMessage } from "#harness/messages.js";
import { estimateTokens } from "#harness/token-estimate.js";
import type { CompactionConfig } from "#harness/types.js";
@@ -177,7 +178,7 @@ describe("shouldCompact", () => {
const activeInputTokens = getInputTokenCount(messages, compaction);
const promptEnvelopeTokens = estimateTokens([
{ content: COMPACTION_PROMPT_ENVELOPE.system, role: "system" },
- { content: COMPACTION_PROMPT_ENVELOPE.prompt, role: "user" },
+ createFrameworkUserMessage("context.compaction", COMPACTION_PROMPT_ENVELOPE.prompt),
] satisfies ModelMessage[]);
expect(
@@ -270,7 +271,7 @@ describe("resolveCompactionModel", () => {
const ENVELOPE_TOKENS = estimateTokens([
{ content: COMPACTION_PROMPT_ENVELOPE.system, role: "system" },
- { content: COMPACTION_PROMPT_ENVELOPE.prompt, role: "user" },
+ createFrameworkUserMessage("context.compaction", COMPACTION_PROMPT_ENVELOPE.prompt),
] satisfies ModelMessage[]);
const HEURISTICS_FORBIDDEN = Math.floor(ENVELOPE_TOKENS);
const ROOMY = 100_000;
@@ -281,6 +282,10 @@ function user(text: string): ModelMessage {
return { content: text, role: "user" };
}
+function compactionMarker(text: string): ModelMessage {
+ return createFrameworkUserMessage("context.compaction", text);
+}
+
function assistant(text: string): ModelMessage {
return { content: text, role: "assistant" };
}
@@ -319,7 +324,7 @@ function toolExchange(input: {
}
function checkpointHead(text: string): ModelMessage[] {
- return [user(CHECKPOINT_MARKER), assistant(text)];
+ return [compactionMarker(CHECKPOINT_MARKER), assistant(text)];
}
function expectWellFormedCompaction(result: ModelMessage[], threshold: number): void {
@@ -634,7 +639,7 @@ describe("compactMessages: tool-result cap heuristic", () => {
const { result, summarizer } = await compact(messages, { recentWindowSize: 1 });
expect(summarizer).not.toHaveBeenCalled();
- expect(result[0]).toEqual(user(CHECKPOINT_MARKER));
+ expect(result[0]).toEqual(compactionMarker(CHECKPOINT_MARKER));
expect(result[1]).toEqual(assistant("Previous checkpoint"));
});
@@ -724,8 +729,10 @@ describe("compactMessages: summarization fallback", () => {
});
expect(summarizer).toHaveBeenCalledTimes(1);
- expect(summarizer.mock.calls[0]?.[0]?.prompt).toContain("old context to fold away");
- expect(result[0]).toEqual(user(CHECKPOINT_MARKER));
+ expect(summarizer.mock.calls[0]?.[0]?.messages?.[0]?.content).toContain(
+ "old context to fold away",
+ );
+ expect(result[0]).toEqual(compactionMarker(CHECKPOINT_MARKER));
expect(result[1]).toEqual(assistant("Distilled story"));
expect(result.some((m) => m.content === "old context to fold away")).toBe(false);
});
@@ -744,8 +751,8 @@ describe("compactMessages: summarization fallback", () => {
threshold: HEURISTICS_FORBIDDEN,
});
- expect(summarizer.mock.calls[0]?.[0]?.prompt).toContain(previousCheckpoint);
- expect(summarizer.mock.calls[0]?.[0]?.prompt).toContain(markerPast280);
+ expect(summarizer.mock.calls[0]?.[0]?.messages?.[0]?.content).toContain(previousCheckpoint);
+ expect(summarizer.mock.calls[0]?.[0]?.messages?.[0]?.content).toContain(markerPast280);
expect(result.filter((m) => m.content === previousCheckpoint)).toHaveLength(0);
expect(result.filter((m) => m.content === "Updated checkpoint")).toHaveLength(1);
});
@@ -812,7 +819,7 @@ describe("compactMessages: summarization fallback", () => {
// sized to exceed the window-selection reserve, which is what makes the
// verbatim tail overshoot after the summary head is added.
const summary = "s".repeat(2_400);
- const summaryHead = [user(CHECKPOINT_MARKER), assistant(summary)];
+ const summaryHead = [compactionMarker(CHECKPOINT_MARKER), assistant(summary)];
const verbatimSize = estimateTokens([...summaryHead, ...tail]);
const strippedSize = estimateTokens([
...summaryHead,
@@ -848,7 +855,7 @@ describe("compactMessages: summarization fallback", () => {
// The folded-away user prompt is replayed as the live turn, so the model
// resumes against its actual instruction rather than a bare "Continue.".
expect(result).toEqual([
- user(CHECKPOINT_MARKER),
+ compactionMarker(CHECKPOINT_MARKER),
assistant("Summary of the large SQL result"),
user("Find the relevant rows."),
]);
@@ -869,7 +876,7 @@ describe("compactMessages: summarization fallback", () => {
expect(result.at(-1)).toEqual(user("please fix the flaky test"));
});
- it("falls back to a synthetic resumption when the real user prompt survives in the tail", async () => {
+ it("falls back to a framework continuation when the real user prompt survives in the tail", async () => {
const messages = [user("old context"), user("latest question"), assistant("answering")];
const { result } = await compact(messages, {
@@ -879,7 +886,9 @@ describe("compactMessages: summarization fallback", () => {
// "latest question" is already in the kept tail — replaying it would ask
// the model to answer again instead of continuing.
- expect(result.at(-1)).toEqual(user("Continue."));
+ expect(result.at(-1)).toEqual(
+ createFrameworkUserMessage("execution.continuation", "Continue."),
+ );
expect(result.filter((m) => m.content === "latest question")).toHaveLength(1);
});
diff --git a/packages/eve/src/harness/compaction.ts b/packages/eve/src/harness/compaction.ts
index 4e1323b41..fbf7cea54 100644
--- a/packages/eve/src/harness/compaction.ts
+++ b/packages/eve/src/harness/compaction.ts
@@ -7,9 +7,9 @@ import {
createCompactionPrompt,
sliceUtf16Safe,
stubContentOutputFileParts,
- TODO_COMPACTION_PRESERVATION_LABEL,
TRANSCRIPT_PAYLOAD_LIMIT,
} from "#harness/compaction-prompt.js";
+import { createFrameworkUserMessage, isFrameworkUserMessage } 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";
@@ -26,7 +26,7 @@ type ModelMessageContentPart = Exclude<ModelMessage["content"], string>[number];
// itself never grows past threshold + envelope + checkpoint.
const COMPACTION_PROMPT_OVERHEAD_TOKENS = estimateTokens([
{ content: COMPACTION_PROMPT_ENVELOPE.system, role: "system" },
- { content: COMPACTION_PROMPT_ENVELOPE.prompt, role: "user" },
+ createFrameworkUserMessage("context.compaction", COMPACTION_PROMPT_ENVELOPE.prompt),
] satisfies ModelMessage[]);
/**
@@ -135,7 +135,7 @@ function toolResultCapHeuristic(input: CompactionHeuristicInput): CompactionHeur
input.previousCheckpoint === undefined
? []
: [
- { content: COMPACTION_CHECKPOINT_MARKER, role: "user" },
+ createFrameworkUserMessage("context.compaction", COMPACTION_CHECKPOINT_MARKER),
{ content: input.previousCheckpoint, role: "assistant" },
];
const capped = withResumptionGuard(
@@ -239,8 +239,8 @@ export async function compactMessages(
const result = await generateText({
abortSignal,
headers,
+ messages: [createFrameworkUserMessage("context.compaction", summaryPrompt.prompt)],
model,
- prompt: summaryPrompt.prompt,
providerOptions,
system: summaryPrompt.system,
telemetry: telemetry ? { ...telemetry, functionId: "eve.compaction" } : undefined,
@@ -254,7 +254,7 @@ export async function compactMessages(
}
const summaryHead: ModelMessage[] = [
- { content: COMPACTION_CHECKPOINT_MARKER, role: "user" },
+ createFrameworkUserMessage("context.compaction", COMPACTION_CHECKPOINT_MARKER),
{ content: result.text, role: "assistant" },
];
@@ -335,7 +335,7 @@ function capToolResults(messages: readonly ModelMessage[]): ModelMessage[] {
/**
* Providers that don't support assistant prefill reject a request that ends on
* assistant content, so compaction must resume from a user turn. Rather than
- * a contentless synthetic prompt, replay the conversation's last real user
+ * a contentless framework prompt, replay the conversation's last real user
* message when compaction folded it away — the model resumes against its
* actual instruction, with the checkpoint as background. Falls back to
* "Continue." when the last real user message still survives in the kept
@@ -370,14 +370,12 @@ function withResumptionGuard(
...messages,
replay !== undefined && !alreadyKept
? replay
- : { content: COMPACTION_RESUMPTION_MESSAGE, role: "user" },
+ : createFrameworkUserMessage("execution.continuation", COMPACTION_RESUMPTION_MESSAGE),
];
}
/**
- * Latest user message authored by the user rather than synthesized by the
- * framework (resumption prompts, checkpoint markers, and todo preservation
- * messages are all `role: "user"` but carry no user intent).
+ * Latest user message authored by the user rather than the framework.
*/
function findLastRealUserMessage(conversation: readonly ModelMessage[]): ModelMessage | undefined {
for (let index = conversation.length - 1; index >= 0; index -= 1) {
@@ -385,11 +383,7 @@ function findLastRealUserMessage(conversation: readonly ModelMessage[]): ModelMe
if (message?.role !== "user" || typeof message.content !== "string") {
continue;
}
- if (
- message.content === COMPACTION_RESUMPTION_MESSAGE ||
- message.content === COMPACTION_CHECKPOINT_MARKER ||
- message.content.startsWith(TODO_COMPACTION_PRESERVATION_LABEL)
- ) {
+ if (isFrameworkUserMessage(message)) {
continue;
}
return message;
diff --git a/packages/eve/src/harness/coordination.test.ts b/packages/eve/src/harness/coordination.test.ts
index 11b9b04e9..c3ea1a0be 100644
--- a/packages/eve/src/harness/coordination.test.ts
+++ b/packages/eve/src/harness/coordination.test.ts
@@ -258,7 +258,7 @@ function createParkedSession(): HarnessSession {
agent: { modelReference: { id: "test-model" }, system: "", tools: [] },
compaction: { recentWindowSize: 10, threshold: 100_000 },
continuationToken: "http:test-session",
- history: [{ content: "delegate this", role: "user" }],
+ history: [{ content: "delegate this", kind: "user", role: "user" }],
sessionId: "test-session",
};
diff --git a/packages/eve/src/harness/current-messages.test.ts b/packages/eve/src/harness/current-messages.test.ts
index 2aa9c8204..306b917a0 100644
--- a/packages/eve/src/harness/current-messages.test.ts
+++ b/packages/eve/src/harness/current-messages.test.ts
@@ -6,7 +6,7 @@ describe("createCurrentMessages", () => {
it("partitions existing history by role", () => {
const current = createCurrentMessages([
{ role: "system", content: "system" },
- { role: "user", content: "user" },
+ { role: "user", content: "user", kind: "user" },
]);
const directMutationIsRejected = () => {
// @ts-expect-error current-message placement must go through add/addSystem.
@@ -14,7 +14,7 @@ describe("createCurrentMessages", () => {
};
expect(current.systemMessages).toEqual([{ role: "system", content: "system" }]);
- expect(current.nonSystemMessages).toEqual([{ role: "user", content: "user" }]);
+ expect(current.nonSystemMessages).toEqual([{ role: "user", content: "user", kind: "user" }]);
expect(directMutationIsRejected).toBeTypeOf("function");
});
@@ -30,46 +30,46 @@ describe("createCurrentMessages", () => {
it("persists framework context as user messages from the first turn", () => {
const current = createCurrentMessages([]);
- current.add("first");
- current.add("later");
+ current.add("first", "context.instruction");
+ current.add("later", "context.instruction");
expect(current.systemMessages).toEqual([]);
expect(current.nonSystemMessages).toEqual([
- { role: "user", content: "first" },
- { role: "user", content: "later" },
+ { role: "user", content: "first", kind: "context.instruction" },
+ { role: "user", content: "later", kind: "context.instruction" },
]);
expect(current.history).toEqual(current.nonSystemMessages);
});
it("inserts later context before the current turn input", () => {
const currentTurnMessages = [
- { role: "user" as const, content: "channel context" },
- { role: "user" as const, content: "current request" },
+ { role: "user" as const, content: "channel context", kind: "user" as const },
+ { role: "user" as const, content: "current request", kind: "user" as const },
];
const current = createCurrentMessages(
- [{ role: "user", content: "history" }, ...currentTurnMessages],
+ [{ role: "user", content: "history", kind: "user" }, ...currentTurnMessages],
{ currentTurnMessages },
);
- current.add("task state");
- current.add("delivery guidance");
+ current.add("task state", "context.state");
+ current.add("delivery guidance", "context.instruction");
expect(current.nonSystemMessages).toEqual([
- { role: "user", content: "history" },
- { role: "user", content: "task state" },
- { role: "user", content: "delivery guidance" },
- { role: "user", content: "channel context" },
- { role: "user", content: "current request" },
+ { role: "user", content: "history", kind: "user" },
+ { role: "user", content: "task state", kind: "context.state" },
+ { role: "user", content: "delivery guidance", kind: "context.instruction" },
+ { role: "user", content: "channel context", kind: "user" },
+ { role: "user", content: "current request", kind: "user" },
]);
});
it("appends messages without interpreting their text", () => {
const current = createCurrentMessages([
- { role: "user", content: "[Task state]\nuser-authored text" },
+ { role: "user", content: "[Task state]\nuser-authored text", kind: "user" },
]);
- current.add("[Task state]\nworking");
- current.add("[Task state]\nworking");
+ current.add("[Task state]\nworking", "context.state");
+ current.add("[Task state]\nworking", "context.state");
expect(current.history.map((message) => message.content)).toEqual([
"[Task state]\nuser-authored text",
@@ -80,7 +80,7 @@ describe("createCurrentMessages", () => {
it("prepares tracked announcements without advancing the recorded baseline", () => {
const recorded = { taskState: "working" };
- const current = createCurrentMessages([{ role: "user", content: "working" }], {
+ const current = createCurrentMessages([{ role: "user", content: "working", kind: "user" }], {
historyState: recorded,
});
@@ -90,10 +90,10 @@ describe("createCurrentMessages", () => {
expect(recorded).toEqual({ taskState: "working" });
expect(current.historyState).toEqual({ taskState: "completed", availableSkills: "completed" });
- expect(current.history.map((message) => message.content)).toEqual([
- "working",
- "completed",
- "completed",
+ expect(current.history).toEqual([
+ { role: "user", content: "working", kind: "user" },
+ { role: "user", content: "completed", kind: "context.state" },
+ { role: "user", content: "completed", kind: "context.state" },
]);
});
@@ -106,10 +106,10 @@ describe("createCurrentMessages", () => {
});
current.addAnnouncements({ availableSkills: "", taskState: undefined });
- expect(current.history.map((message) => message.content)).toEqual([
- "skills",
- "working",
- "report",
+ expect(current.history).toEqual([
+ { role: "user", content: "skills", kind: "context.state" },
+ { role: "user", content: "working", kind: "context.state" },
+ { role: "user", content: "report", kind: "context.instruction" },
]);
expect(current.historyState).toEqual({
availableSkills: "skills",
@@ -119,22 +119,29 @@ describe("createCurrentMessages", () => {
});
it("persists additions without storing client context or replacing projected history", () => {
- const hidden = { role: "user" as const, content: "hidden by projection" };
- const input = { role: "user" as const, content: "request" };
+ const hidden = {
+ role: "user" as const,
+ content: "hidden by projection",
+ kind: "user" as const,
+ };
+ const input = { role: "user" as const, content: "request", kind: "user" as const };
const current = createCurrentMessages([hidden, input], {
currentTurnMessages: [input],
- projectedMessages: [{ role: "user", content: "ephemeral client context" }, input],
+ projectedMessages: [
+ { role: "user", content: "ephemeral client context", kind: "user" },
+ input,
+ ],
});
- current.add("[Task state]\nworking");
+ current.add("[Task state]\nworking", "context.state");
current.addSystem({ role: "system", content: "turn-scoped instructions" });
expect(current.history).toEqual([
hidden,
- { role: "user", content: "[Task state]\nworking" },
+ { role: "user", content: "[Task state]\nworking", kind: "context.state" },
input,
]);
expect(current.nonSystemMessages).toEqual([
- { role: "user", content: "ephemeral client context" },
- { role: "user", content: "[Task state]\nworking" },
+ { role: "user", content: "ephemeral client context", kind: "user" },
+ { role: "user", content: "[Task state]\nworking", kind: "context.state" },
input,
]);
});
@@ -151,7 +158,7 @@ describe("createCurrentMessages", () => {
],
};
const current = createCurrentMessages([
- { role: "user", content: "history" },
+ { role: "user", content: "history", kind: "user" },
{
role: "assistant",
content: [
@@ -172,7 +179,7 @@ describe("createCurrentMessages", () => {
it("keeps hierarchy-sensitive context in instructions when requested", () => {
const current = createCurrentMessages([]);
- current.add("authoritative", { cacheFriendly: false });
+ current.add("authoritative", "context.instruction", { cacheFriendly: false });
expect(current.systemMessages).toEqual([{ role: "system", content: "authoritative" }]);
expect(current.nonSystemMessages).toEqual([]);
diff --git a/packages/eve/src/harness/current-messages.ts b/packages/eve/src/harness/current-messages.ts
index 9e886cead..addcb3451 100644
--- a/packages/eve/src/harness/current-messages.ts
+++ b/packages/eve/src/harness/current-messages.ts
@@ -1,33 +1,45 @@
import type { ModelMessage, SystemModelMessage } from "ai";
import type { HistoryState } from "#context/keys.js";
+import {
+ createFrameworkUserMessage,
+ type FrameworkMessageKind,
+ type HarnessModelMessage,
+} from "#harness/messages.js";
+
interface AddCurrentMessageOptions {
readonly cacheFriendly?: boolean;
}
interface CurrentMessagesOptions {
readonly historyState?: HistoryState;
- readonly currentTurnMessages?: readonly ModelMessage[];
- readonly projectedMessages?: readonly ModelMessage[];
+ readonly currentTurnMessages?: readonly HarnessModelMessage[];
+ readonly projectedMessages?: readonly HarnessModelMessage[];
}
+const ANNOUNCEMENT_KINDS = {
+ availableSkills: "context.state",
+ deliveryInstruction: "context.instruction",
+ taskState: "context.state",
+} as const satisfies Record<keyof HistoryState, FrameworkMessageKind>;
+
/** Builds the model view and durable history for one step. */
export function createCurrentMessages(
- history: readonly ModelMessage[],
+ history: readonly HarnessModelMessage[],
options: CurrentMessagesOptions = {},
): {
- readonly history: readonly ModelMessage[];
+ readonly history: readonly HarnessModelMessage[];
readonly historyState: HistoryState;
- readonly nonSystemMessages: readonly ModelMessage[];
+ readonly nonSystemMessages: readonly HarnessModelMessage[];
readonly systemMessages: readonly SystemModelMessage[];
- add(message: string, options?: AddCurrentMessageOptions): void;
+ add(message: string, kind: FrameworkMessageKind, options?: AddCurrentMessageOptions): void;
addAnnouncements(announcements: HistoryState): void;
addSystem(messages: SystemModelMessage | readonly SystemModelMessage[]): void;
} {
const durableMessages = [...history];
const historyState = { ...options.historyState };
const systemMessages: SystemModelMessage[] = [];
- const nonSystemMessages: ModelMessage[] = [];
+ const nonSystemMessages: HarnessModelMessage[] = [];
const currentTurnMessages = new Set(options.currentTurnMessages);
let currentTurnInsertionIndex: number | undefined;
@@ -50,9 +62,13 @@ export function createCurrentMessages(
const canAppendUserMessages =
currentTurnInsertionIndex !== undefined || !hasTailApprovalResponse(nonSystemMessages);
- function add(message: string, { cacheFriendly = true }: AddCurrentMessageOptions = {}): boolean {
+ function add(
+ message: string,
+ kind: FrameworkMessageKind,
+ { cacheFriendly = true }: AddCurrentMessageOptions = {},
+ ): boolean {
if (cacheFriendly && canAppendUserMessages) {
- const entry = { role: "user" as const, content: message };
+ const entry = createFrameworkUserMessage(kind, message);
nonSystemMessages.splice(userInsertionIndex, 0, entry);
durableMessages.splice(historyInsertionIndex, 0, entry);
userInsertionIndex += 1;
@@ -70,7 +86,7 @@ export function createCurrentMessages(
const message = announcements[key];
if (message === undefined || message.length === 0 || historyState[key] === message)
continue;
- if (add(message)) historyState[key] = message;
+ if (add(message, ANNOUNCEMENT_KINDS[key])) historyState[key] = message;
}
},
addSystem(messages) {
diff --git a/packages/eve/src/harness/input-requests.test.ts b/packages/eve/src/harness/input-requests.test.ts
index e703e5294..32d6881d4 100644
--- a/packages/eve/src/harness/input-requests.test.ts
+++ b/packages/eve/src/harness/input-requests.test.ts
@@ -34,7 +34,7 @@ function createHarnessSession(): HarnessSession {
threshold: 0.8,
},
continuationToken: "test",
- history: [{ content: "previous", role: "user" }],
+ history: [{ content: "previous", kind: "user", role: "user" }],
sessionId: "sess-test",
};
}
@@ -183,7 +183,7 @@ describe("resolvePendingInput", () => {
});
expect(result.outcome).toBe("unresolved");
- expect(result.messages).toEqual([{ content: "previous", role: "user" }]);
+ expect(result.messages).toEqual([{ content: "previous", kind: "user", role: "user" }]);
expect(hasDeferredStepInput(result.session)).toBe(true);
const deferred = consumeDeferredStepInput({ session: result.session });
@@ -789,7 +789,7 @@ describe("resolvePendingInput", () => {
// The message runs as an ordinary turn; the approval stays answerable.
expect(result.outcome).toBe("continue");
expect(result.rejectedActions).toBeUndefined();
- expect(result.messages).toEqual([{ content: "previous", role: "user" }]);
+ expect(result.messages).toEqual([{ content: "previous", kind: "user", role: "user" }]);
expect(hasDeferredStepInput(result.session)).toBe(false);
expect(getPendingInputRequestIds(result.session.state)).toEqual(new Set(["approval-1"]));
});
@@ -1075,7 +1075,7 @@ describe("pending input batch collection", () => {
expect(getPendingInputRequestIds(answered.session.state)).toEqual(new Set(["approval-1"]));
// Only the answered batch's withheld output is restored.
expect(answered.messages).toEqual([
- { content: "previous", role: "user" },
+ { content: "previous", kind: "user", role: "user" },
batchOutput("call-2", "ask_question"),
{
content: [
@@ -1125,7 +1125,7 @@ describe("pending input batch collection", () => {
expect(first.outcome).toBe("resolved");
expect(first.messages).toEqual([
- { content: "previous", role: "user" },
+ { content: "previous", kind: "user", role: "user" },
batchOutput("call-1", "bash"),
{
content: [
@@ -1263,7 +1263,7 @@ describe("pending input batch collection", () => {
const result = resolvePendingInput({ session, stepInput: { message: "keep going" } });
expect(result.outcome).toBe("continue");
- expect(result.messages).toEqual([{ content: "previous", role: "user" }]);
+ expect(result.messages).toEqual([{ content: "previous", kind: "user", role: "user" }]);
expect(hasDeferredStepInput(result.session)).toBe(false);
expect(getPendingInputRequestIds(result.session.state)).toEqual(
new Set(["approval-1", "question-1"]),
@@ -1330,7 +1330,7 @@ describe("resolvePendingInput with a session-limit continuation batch", () => {
expect(result.limitContinuation).toEqual({ granted: true });
// The prompt is harness-authored — no tool call exists in model history,
// so resolution must not append a tool message.
- expect(result.messages).toEqual([{ content: "previous", role: "user" }]);
+ expect(result.messages).toEqual([{ content: "previous", kind: "user", role: "user" }]);
});
it("resolves a stop answer as not granted", () => {
@@ -1343,7 +1343,7 @@ describe("resolvePendingInput with a session-limit continuation batch", () => {
expect(result.outcome).toBe("resolved");
expect(result.limitContinuation).toEqual({ granted: false });
- expect(result.messages).toEqual([{ content: "previous", role: "user" }]);
+ expect(result.messages).toEqual([{ content: "previous", kind: "user", role: "user" }]);
});
it("keeps the prompt pending and queues a plain follow-up message", () => {
@@ -1354,7 +1354,7 @@ describe("resolvePendingInput with a session-limit continuation batch", () => {
expect(result.outcome).toBe("unresolved");
expect(result.limitContinuation).toBeUndefined();
- expect(result.messages).toEqual([{ content: "previous", role: "user" }]);
+ expect(result.messages).toEqual([{ content: "previous", kind: "user", role: "user" }]);
expect(hasDeferredStepInput(result.session)).toBe(true);
const deferred = consumeDeferredStepInput({ session: result.session });
diff --git a/packages/eve/src/harness/messages.test.ts b/packages/eve/src/harness/messages.test.ts
index 1470cd036..bb9d8a055 100644
--- a/packages/eve/src/harness/messages.test.ts
+++ b/packages/eve/src/harness/messages.test.ts
@@ -3,9 +3,17 @@ import { describe, expect, it } from "vitest";
import {
coalesceDeliveries,
coalesceTurnInputs,
+ createFrameworkUserMessage,
+ createUserMessage,
+ isFrameworkMessageKind,
+ isFrameworkUserMessage,
+ isUserMessageKind,
+ isUserModelMessage,
+ markFrameworkStepInput,
normalizeModelMessages,
normalizeUserContent,
resolveAssistantStepText,
+ validateHarnessModelMessages,
} from "#harness/messages.js";
import type { StepInput } from "#harness/types.js";
import { attachClientContext, readClientContext } from "#internal/client-context.js";
@@ -97,6 +105,29 @@ describe("coalesceTurnInputs", () => {
expect(result).toEqual({ message: "a\n\nb\n\nc" });
});
+ it("preserves a framework kind only when all merged message content shares it", () => {
+ expect(
+ coalesceTurnInputs(
+ markFrameworkStepInput({ message: "first" }, "execution.background_task"),
+ markFrameworkStepInput({ message: "second" }, "execution.background_task"),
+ ),
+ ).toEqual(markFrameworkStepInput({ message: "first\n\nsecond" }, "execution.background_task"));
+ expect(
+ coalesceTurnInputs(
+ markFrameworkStepInput({ message: "first" }, "execution.background_task"),
+ {
+ message: "second",
+ },
+ ),
+ ).toEqual({ message: "first\n\nsecond" });
+ expect(
+ coalesceTurnInputs(
+ markFrameworkStepInput({ message: "first" }, "context.instruction"),
+ markFrameworkStepInput({ message: "second" }, "execution.background_task"),
+ ),
+ ).toEqual({ message: "first\n\nsecond" });
+ });
+
it("merges inputResponses from both payloads", () => {
const result = coalesceTurnInputs(
{ inputResponses: [{ requestId: "r1", optionId: "approve" }] },
@@ -257,6 +288,51 @@ describe("normalizeModelMessages", () => {
});
});
+describe("createFrameworkUserMessage", () => {
+ it.each([
+ "context.instruction",
+ "context.state",
+ "context.compaction",
+ "memory.load",
+ "execution.background_task",
+ "execution.continuation",
+ "execution.retry",
+ ] as const)("recognizes %s as a framework message kind", (kind) => {
+ expect(isFrameworkMessageKind(kind)).toBe(true);
+ });
+
+ it("brands framework-authored user-role messages", () => {
+ const message = createFrameworkUserMessage(
+ "execution.background_task",
+ "Background task task_1 completed.",
+ );
+
+ expect(message).toEqual({
+ content: "Background task task_1 completed.",
+ kind: "execution.background_task",
+ role: "user",
+ });
+ expect(isFrameworkUserMessage(message)).toBe(true);
+ expect(isFrameworkUserMessage({ content: "A user message", role: "user" })).toBe(false);
+ expect(isFrameworkMessageKind("synthetic")).toBe(false);
+ });
+
+ it("brands real user messages with the user kind", () => {
+ const message = createUserMessage("user", "A user message");
+
+ expect(message).toEqual({ content: "A user message", kind: "user", role: "user" });
+ expect(isUserMessageKind("user")).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" }]),
+ ).toThrow("Expected every user-role model message to have a kind.");
+ });
+});
+
describe("resolveAssistantStepText", () => {
it("extracts text from a string-content assistant message", () => {
const messages: ModelMessage[] = [{ content: "Hello!", role: "assistant" }];
diff --git a/packages/eve/src/harness/messages.ts b/packages/eve/src/harness/messages.ts
index f154d0394..adc53600e 100644
--- a/packages/eve/src/harness/messages.ts
+++ b/packages/eve/src/harness/messages.ts
@@ -10,6 +10,128 @@ import type { InputResponse } from "#shared/input.js";
import type { StepInput } from "#harness/types.js";
import { attachClientContext, readClientContext } from "#internal/client-context.js";
+/** Reason a framework-authored user-role message was added to model history. */
+export type FrameworkMessageKind =
+ | "context.instruction"
+ | "context.state"
+ | "context.compaction"
+ | "memory.load"
+ | "execution.background_task"
+ | "execution.continuation"
+ | "execution.retry";
+
+/** Semantic classification for every user-role message in model history. */
+export type UserMessageKind = "user" | FrameworkMessageKind;
+
+/** A user-role message that is safe to retain in framework model history. */
+export type UserModelMessage = Extract<ModelMessage, { readonly role: "user" }> & {
+ readonly kind: UserMessageKind;
+ readonly metadata?: Record<string, unknown>;
+};
+
+/** Model message shape retained in framework history. */
+export type HarnessModelMessage =
+ | Exclude<ModelMessage, { readonly role: "user" }>
+ | UserModelMessage;
+
+type FrameworkUserMessage = UserModelMessage & {
+ readonly kind: FrameworkMessageKind;
+};
+
+/** Builds a classified user-role message for model history. */
+export function createUserMessage(
+ kind: FrameworkMessageKind,
+ content: UserContent,
+ metadata?: Record<string, unknown>,
+): FrameworkUserMessage;
+export function createUserMessage(
+ kind: "user",
+ content: UserContent,
+ metadata?: Record<string, unknown>,
+): UserModelMessage;
+export function createUserMessage(
+ kind: UserMessageKind,
+ content: UserContent,
+ metadata?: Record<string, unknown>,
+): UserModelMessage {
+ const message: UserModelMessage = { content, kind, role: "user" };
+ return metadata === undefined ? message : { ...message, metadata };
+}
+
+/** Builds a framework-authored user-role message for model history. */
+export function createFrameworkUserMessage(
+ kind: FrameworkMessageKind,
+ content: UserContent,
+ metadata?: Record<string, unknown>,
+): FrameworkUserMessage {
+ return createUserMessage(kind, content, metadata);
+}
+
+/** 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);
+}
+
+/** True when a user-role model message has the required semantic classification. */
+export function isUserModelMessage(message: ModelMessage): message is UserModelMessage {
+ if (message.role !== "user") return false;
+ const { kind } = message as ModelMessage & { readonly kind?: unknown };
+ return isUserMessageKind(kind);
+}
+
+/** 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";
+}
+
+/** Validates that every user-role message is classified before history retains it. */
+export function validateHarnessModelMessages(
+ messages: readonly ModelMessage[],
+): HarnessModelMessage[] {
+ const validated: HarnessModelMessage[] = [];
+ for (const message of messages) {
+ if (message.role !== "user") {
+ validated.push(message);
+ continue;
+ }
+ if (!isUserModelMessage(message)) {
+ throw new TypeError("Expected every user-role model message to have a kind.");
+ }
+ validated.push(message);
+ }
+ return validated;
+}
+
+export function isFrameworkMessageKind(value: unknown): value is FrameworkMessageKind {
+ return (
+ value === "context.instruction" ||
+ value === "context.state" ||
+ value === "context.compaction" ||
+ value === "memory.load" ||
+ value === "execution.background_task" ||
+ value === "execution.continuation" ||
+ value === "execution.retry"
+ );
+}
+
+type FrameworkStepInput = StepInput & {
+ readonly frameworkMessageKind?: FrameworkMessageKind;
+};
+
+/** Marks an execution-owned delivery so its model message retains provenance. */
+export function markFrameworkStepInput(input: StepInput, kind: FrameworkMessageKind): StepInput {
+ return { ...input, frameworkMessageKind: kind } as FrameworkStepInput;
+}
+
+/** Returns the framework reason for an execution-owned user message, when present. */
+export function frameworkMessageKindForStepInput(
+ input: StepInput | undefined,
+): FrameworkMessageKind | undefined {
+ if (input === undefined) return undefined;
+ const { frameworkMessageKind } = input as FrameworkStepInput;
+ return isFrameworkMessageKind(frameworkMessageKind) ? frameworkMessageKind : undefined;
+}
+
/**
* Merges two {@link StepInput} values into one.
*
@@ -30,6 +152,7 @@ export function coalesceTurnInputs(a: StepInput, b: StepInput): StepInput {
a: a.context,
b: b.context,
});
+ const frameworkMessageKind = coalesceFrameworkMessageKind({ a, b });
const ephemeralContext = coalesceContext({
a: readClientContext(a),
b: readClientContext(b),
@@ -59,7 +182,12 @@ export function coalesceTurnInputs(a: StepInput, b: StepInput): StepInput {
result.outputSchema = outputSchema;
}
- return attachClientContext(result, ephemeralContext);
+ return attachClientContext(
+ frameworkMessageKind === undefined
+ ? result
+ : markFrameworkStepInput(result, frameworkMessageKind),
+ ephemeralContext,
+ );
}
/**
@@ -184,6 +312,17 @@ function coalesceContext(input: {
return [...a, ...b];
}
+function coalesceFrameworkMessageKind(input: {
+ readonly a: StepInput;
+ readonly b: StepInput;
+}): FrameworkMessageKind | undefined {
+ const a = frameworkMessageKindForStepInput(input.a);
+ const b = frameworkMessageKindForStepInput(input.b);
+ if (input.a.message === undefined) return b;
+ if (input.b.message === undefined) return a;
+ return a === b ? a : undefined;
+}
+
/**
* Merges two optional turn messages into one after removing blank content.
*/
diff --git a/packages/eve/src/harness/session-limit-enforcement.ts b/packages/eve/src/harness/session-limit-enforcement.ts
index 2212c7b9e..289ece1da 100644
--- a/packages/eve/src/harness/session-limit-enforcement.ts
+++ b/packages/eve/src/harness/session-limit-enforcement.ts
@@ -11,8 +11,6 @@
* prompt (sessions that can reach a human) or fails it (task-mode sessions
* without HITL — nobody can answer the prompt).
*/
-import type { ModelMessage } from "ai";
-
import { createInputRequestedEvent } from "#protocol/message.js";
import {
emitFailedStep,
@@ -21,6 +19,7 @@ import {
type HarnessEmissionState,
} from "#harness/emission.js";
import { appendPendingInputBatch } from "#harness/input-requests.js";
+import type { HarnessModelMessage } from "#harness/messages.js";
import { createSessionLimitContinuationRequest } from "#harness/session-limit-continuation.js";
import { SessionLimitDeclinedError } from "#harness/turn-cancellation.js";
import {
@@ -102,7 +101,7 @@ export async function applySessionLimitContinuation(
* `SESSION_TOKEN_LIMIT_REACHED`.
*/
export async function enforceSessionUsageLimit(
- input: SessionLimitPolicyInput & { readonly messages: readonly ModelMessage[] },
+ input: SessionLimitPolicyInput & { readonly messages: readonly HarnessModelMessage[] },
): Promise<StepResult | null> {
const violation = getSessionUsageLimitViolation(input.session);
if (violation === null) {
@@ -134,7 +133,7 @@ async function parkOnSessionUsageLimit(input: {
readonly config: ToolLoopHarnessConfig;
readonly emit: NonNullable<ToolLoopHarnessConfig["handleEvent"]>;
readonly emissionState: HarnessEmissionState;
- readonly messages: readonly ModelMessage[];
+ readonly messages: readonly HarnessModelMessage[];
readonly session: HarnessSession;
readonly violation: SessionUsageLimitViolation;
}): Promise<StepResult> {
diff --git a/packages/eve/src/harness/tool-loop-compaction-accounting.test.ts b/packages/eve/src/harness/tool-loop-compaction-accounting.test.ts
index 10b9a4471..262e860d1 100644
--- a/packages/eve/src/harness/tool-loop-compaction-accounting.test.ts
+++ b/packages/eve/src/harness/tool-loop-compaction-accounting.test.ts
@@ -2,6 +2,7 @@ import { generateText, jsonSchema, type LanguageModel, ToolLoopAgent } from "ai"
import { afterEach, describe, expect, it, vi } from "vitest";
import { appendPendingInputBatch } from "#harness/input-requests.js";
+import { validateHarnessModelMessages } from "#harness/messages.js";
import { createToolLoopHarness } from "#harness/tool-loop.js";
import type { HarnessSession, StepFn, StepNext, ToolLoopHarnessConfig } from "#harness/types.js";
import {
@@ -173,8 +174,8 @@ describe("tool-loop structured compaction accounting", () => {
createTestSession({
compaction: { recentWindowSize: 0, threshold: 100 },
history: [
- ...recalled.history,
- { content: `ordinary ${"conversation ".repeat(100)}`, role: "user" },
+ ...validateHarnessModelMessages(recalled.history),
+ { content: `ordinary ${"conversation ".repeat(100)}`, kind: "user", role: "user" },
],
state: recalled.state,
}),
@@ -182,9 +183,9 @@ describe("tool-loop structured compaction accounting", () => {
);
expect(vi.mocked(generateText)).toHaveBeenCalledOnce();
- expect(vi.mocked(generateText).mock.calls[0]?.[0].prompt).not.toContain(
- "PRIVATE_MEMORY_SENTINEL",
- );
+ const prompt = vi.mocked(generateText).mock.calls[0]?.[0].messages?.[0]?.content;
+ if (typeof prompt !== "string") throw new Error("Expected the compaction prompt text.");
+ expect(prompt).not.toContain("PRIVATE_MEMORY_SENTINEL");
expect(JSON.stringify(result.session.history)).toContain("PRIVATE_MEMORY_SENTINEL");
expect(JSON.stringify(result.session.history)).toContain("eve.memory");
});
@@ -290,6 +291,7 @@ describe("tool-loop structured compaction accounting", () => {
expect(vi.mocked(generateText)).toHaveBeenCalledTimes(1);
expect(second.session.history[0]).toEqual({
content: "Summary of our conversation so far:",
+ kind: "context.compaction",
role: "user",
});
expect(second.session.history[1]).toEqual({
@@ -339,7 +341,7 @@ describe("tool-loop structured compaction accounting", () => {
recentWindowSize: 10,
threshold: 101,
},
- history: [{ content: "Previous exact prompt", role: "user" }],
+ history: [{ content: "Previous exact prompt", kind: "user", role: "user" }],
}),
});
@@ -355,6 +357,7 @@ describe("tool-loop structured compaction accounting", () => {
expect(vi.mocked(generateText)).toHaveBeenCalledTimes(1);
expect(result.session.history[0]).toEqual({
content: "Summary of our conversation so far:",
+ kind: "context.compaction",
role: "user",
});
expect(result.session.history[1]).toEqual({
diff --git a/packages/eve/src/harness/tool-loop-generate-approval-resume.integration.test.ts b/packages/eve/src/harness/tool-loop-generate-approval-resume.integration.test.ts
index b8a4918e1..dc6c3bfb8 100644
--- a/packages/eve/src/harness/tool-loop-generate-approval-resume.integration.test.ts
+++ b/packages/eve/src/harness/tool-loop-generate-approval-resume.integration.test.ts
@@ -24,6 +24,7 @@ import { setHarnessEmissionState } from "#harness/emission.js";
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
import type { InputRequest } from "#shared/input.js";
import { appendPendingInputBatch, getApprovedTools } from "#harness/input-requests.js";
+import type { HarnessModelMessage } from "#harness/messages.js";
import { getPendingInputBatches } from "#harness/pending-input-batches.js";
import { createToolLoopHarness } from "#harness/tool-loop.js";
import { setTurnUsageState } from "#harness/turn-tag-state.js";
@@ -117,7 +118,7 @@ const secondApprovalRequest = {
type: "tool-approval-request" as const,
};
-function createBaseSession(history?: readonly ModelMessage[]): HarnessSession {
+function createBaseSession(history?: readonly HarnessModelMessage[]): HarnessSession {
return {
agent: {
modelReference: { id: "generate-approval-resume-model" },
@@ -132,7 +133,7 @@ function createBaseSession(history?: readonly ModelMessage[]): HarnessSession {
},
compaction: { recentWindowSize: 10, threshold: 100_000 },
continuationToken: "http:generate-approval-resume-session",
- history: [...(history ?? [{ content: "Run pwd.", role: "user" }])],
+ history: [...(history ?? [{ content: "Run pwd.", kind: "user" as const, role: "user" }])],
sessionId: "generate-approval-resume-session",
};
}
@@ -156,7 +157,7 @@ const pendingApprovalInputRequest: InputRequest = {
};
function createPendingApprovalSession(
- history?: readonly ModelMessage[],
+ history?: readonly HarnessModelMessage[],
responseAuthorization = false,
): HarnessSession {
return appendPendingInputBatch({
@@ -952,9 +953,9 @@ describe("tool loop generate approval resume (real AI SDK)", () => {
// restored *after* that intervening exchange. This proves the AI SDK accepts the
// late-spliced transcript shape before any behavior change lands.
it("splices the approved batch after an intervening conversation turn", async () => {
- const interveningHistory: readonly ModelMessage[] = [
- { content: "Run pwd.", role: "user" },
- { content: "Any update on that command?", role: "user" },
+ const interveningHistory: readonly HarnessModelMessage[] = [
+ { content: "Run pwd.", kind: "user", role: "user" },
+ { content: "Any update on that command?", kind: "user", role: "user" },
{
content: [{ text: "Still waiting for approval to run pwd.", type: "text" }],
role: "assistant",
diff --git a/packages/eve/src/harness/tool-loop-stream-retry.integration.test.ts b/packages/eve/src/harness/tool-loop-stream-retry.integration.test.ts
index 61ac87646..d72e789d6 100644
--- a/packages/eve/src/harness/tool-loop-stream-retry.integration.test.ts
+++ b/packages/eve/src/harness/tool-loop-stream-retry.integration.test.ts
@@ -24,7 +24,7 @@ function createSession(): HarnessSession {
compaction: { recentWindowSize: 10, threshold: 100_000 },
continuationToken: "http:retry-integration-session",
history: [
- { content: "Complete the long task.", role: "user" },
+ { content: "Complete the long task.", kind: "user", role: "user" },
{ content: "Prior work is complete.", role: "assistant" },
],
sessionId: "retry-integration-session",
diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.ts
index 03dc76bc1..cab4d7594 100644
--- a/packages/eve/src/harness/tool-loop.test.ts
+++ b/packages/eve/src/harness/tool-loop.test.ts
@@ -52,6 +52,12 @@ import type { RunMode } from "#shared/run-mode.js";
import type { ChannelAudience } from "#shared/channel-audience.js";
import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
import { compactMessages, shouldCompact } from "#harness/compaction.js";
+import {
+ createFrameworkUserMessage,
+ createUserMessage,
+ markFrameworkStepInput,
+ type HarnessModelMessage,
+} from "#harness/messages.js";
import {
getHarnessEmissionState,
isHarnessBetweenTurns,
@@ -839,7 +845,11 @@ describe("createToolLoopHarness", () => {
usage: { inputTokens: 123 },
});
- const hidden = { content: "HIDE_FROM_CONSUMERS", role: "user" as const };
+ const hidden = {
+ content: "HIDE_FROM_CONSUMERS",
+ kind: "user" as const,
+ role: "user" as const,
+ };
const projector = vi.fn(({ messages }: { messages: readonly ModelMessage[] }) =>
messages.filter((message) => message !== hidden),
);
@@ -860,7 +870,7 @@ describe("createToolLoopHarness", () => {
);
const session = createTestSession({
history: [
- { content: "first", role: "user" },
+ { content: "first", kind: "user" as const, role: "user" },
hidden,
{ content: "second", role: "assistant" },
],
@@ -870,9 +880,9 @@ describe("createToolLoopHarness", () => {
runStep(session, { message: "third" }),
);
const expectedView = [
- { content: "first", role: "user" },
+ { content: "first", kind: "user" as const, role: "user" },
{ content: "second", role: "assistant" },
- { content: "third", role: "user" },
+ { content: "third", kind: "user" as const, role: "user" },
];
const agent = vi.mocked(ToolLoopAgent).mock.results[0]?.value;
@@ -880,10 +890,10 @@ describe("createToolLoopHarness", () => {
expect(stepEventMessages).toEqual([expectedView]);
expect(agent.stream).toHaveBeenCalledWith(expect.objectContaining({ messages: expectedView }));
expect(result.session.history).toEqual([
- { content: "first", role: "user" },
+ { content: "first", kind: "user" as const, role: "user" },
hidden,
{ content: "second", role: "assistant" },
- { content: "third", role: "user" },
+ { content: "third", kind: "user" as const, role: "user" },
{ content: "Hello!", role: "assistant" },
]);
expect(result.session.compaction).toMatchObject({
@@ -930,7 +940,7 @@ describe("createToolLoopHarness", () => {
expect(result.next).toBeNull();
expect(result.session.history).toEqual([
- { content: "Hi", role: "user" },
+ { content: "Hi", kind: "user" as const, role: "user" },
{ content: "Hello!", role: "assistant" },
]);
});
@@ -959,7 +969,7 @@ describe("createToolLoopHarness", () => {
});
expect(result.session.history).toEqual([
- { content: "channel context", role: "user" },
+ { content: "channel context", kind: "context.instruction", role: "user" },
{ content: "Hello!", role: "assistant" },
]);
}
@@ -996,7 +1006,7 @@ describe("createToolLoopHarness", () => {
};
expect(agent.generate.mock.calls[0]?.[0].messages).toEqual([
{ content: [{ text: "Previous reply", type: "text" }], role: "assistant" },
- { content: "Continue", role: "user" },
+ { content: "Continue", kind: "user" as const, role: "user" },
]);
});
@@ -1028,7 +1038,9 @@ describe("createToolLoopHarness", () => {
const result = await runStep(createTestSession(), { message: "Hi" });
expect(result.next).toBeNull();
- expect(result.session.history).toEqual([{ content: "Hi", role: "user" }]);
+ expect(result.session.history).toEqual([
+ { content: "Hi", kind: "user" as const, role: "user" },
+ ]);
expect(vi.mocked(ToolLoopAgent).mock.calls.length).toBe(1);
expect(events).toContainEqual(
expect.objectContaining({
@@ -1057,7 +1069,7 @@ describe("createToolLoopHarness", () => {
expect(result.next).toBeNull();
expect(result.session.history).toEqual([
- { content: "Hi", role: "user" },
+ { content: "Hi", kind: "user" as const, role: "user" },
{ content: message, role: "assistant" },
]);
expect(vi.mocked(ToolLoopAgent).mock.calls.length).toBe(1);
@@ -1229,17 +1241,20 @@ describe("createToolLoopHarness", () => {
content: expect.stringContaining(
'<agent id="ag_research:123456789012" name="research">waiting</agent>',
),
+ kind: "context.state",
role: "user",
});
// The announcement precedes the turn's actual user message.
- expect(messages.at(-1)).toEqual({ content: "Hi", role: "user" });
+ expect(messages.at(-1)).toEqual({ content: "Hi", kind: "user" as const, role: "user" });
expect(messages.at(-2)).toEqual({
content: expect.stringContaining("[Agents]"),
+ kind: "context.state",
role: "user",
});
expect(JSON.stringify({ instructions, messages })).not.toContain("private-token");
expect(result.session.history).toContainEqual({
content: expect.stringContaining('<agent id="ag_research:123456789012"'),
+ kind: "context.state",
role: "user",
});
});
@@ -1307,7 +1322,7 @@ describe("createToolLoopHarness", () => {
const runStep = createToolLoopHarness(createTestConfig("conversation"));
const session = createTestSession({
history: [
- { content: "Delegate this.", role: "user" },
+ { content: "Delegate this.", kind: "user" as const, role: "user" },
{
content: [
{
@@ -1363,6 +1378,7 @@ describe("createToolLoopHarness", () => {
// The request ends user-final: the announcement trails the tool results.
expect(messages.at(-1)).toEqual({
content: expect.stringContaining('<agent id="ag_research:123456789012"'),
+ kind: "context.state",
role: "user",
});
expect(messages.filter((message) => message.role === "assistant")).toHaveLength(1);
@@ -1372,6 +1388,7 @@ describe("createToolLoopHarness", () => {
// sees it and does not re-announce an unchanged listing.
expect(result.session.history.at(-2)).toEqual({
content: expect.stringContaining("[Agents]"),
+ kind: "context.state",
role: "user",
});
});
@@ -1394,7 +1411,7 @@ describe("createToolLoopHarness", () => {
ToolLoopHarnessConfig["dispatchDynamicModelEvent"]
> = vi.fn(async ({ ctx, event, messages }) => {
expect(event.type).toBe("step.started");
- expect(messages.at(-1)).toEqual({ content: "Hi", role: "user" });
+ expect(messages.at(-1)).toEqual({ content: "Hi", kind: "user" as const, role: "user" });
ctx.setVirtualContext(LiveStepDynamicModelSelectionKey, {
model: selectedModel,
@@ -2230,7 +2247,11 @@ describe("createToolLoopHarness", () => {
expect(resumed.next).toBeNull();
expect(getSessionUsageLimitViolation(resumed.session)).toBeNull();
// The parked user message survives into model history for the resumed call.
- expect(resumed.session.history).toContainEqual({ content: "Hi again", role: "user" });
+ expect(resumed.session.history).toContainEqual({
+ content: "Hi again",
+ kind: "user" as const,
+ role: "user",
+ });
const resolutionIndex = events.findIndex((event) => event.type === "input.resolved");
expect(resolutionIndex).toBeGreaterThan(-1);
expect(events[resolutionIndex]).toMatchObject({
@@ -2359,6 +2380,7 @@ describe("createToolLoopHarness", () => {
expect(vi.mocked(ToolLoopAgent)).toHaveBeenCalledTimes(1);
expect(resumed.session.history).toContainEqual({
content: "also do this other thing",
+ kind: "user" as const,
role: "user",
});
});
@@ -2590,7 +2612,7 @@ describe("createToolLoopHarness", () => {
}),
);
expect(result.session.history).toEqual([
- { content: "Hi", role: "user" },
+ { content: "Hi", kind: "user" as const, role: "user" },
{ content: '{"title":"Done"}', role: "assistant" },
]);
expect(result.session.outputSchema).toBeUndefined();
@@ -2704,7 +2726,7 @@ describe("createToolLoopHarness", () => {
// The un-executed final_output call is never persisted, so no dangling
// tool_use survives into history.
expect(result.session.history).toEqual([
- { content: "Hi", role: "user" },
+ { content: "Hi", kind: "user" as const, role: "user" },
{ content: '{"title":"Done"}', role: "assistant" },
]);
expect(result.session.outputSchema).toBeUndefined();
@@ -2942,7 +2964,7 @@ describe("createToolLoopHarness", () => {
expect(result.next).toBeNull();
expect(result.settledTurn).toEqual({ output: "It is 41 F in New York right now." });
expect(result.session.history).toEqual([
- { content: "What's the weather in NY?", role: "user" },
+ { content: "What's the weather in NY?", kind: "user" as const, role: "user" },
{
content: [
{
@@ -3045,7 +3067,7 @@ describe("createToolLoopHarness", () => {
expect(typeof result.next).toBe("function");
expect(result.session.history).toEqual([
- { content: "What's the weather in NY?", role: "user" },
+ { content: "What's the weather in NY?", kind: "user" as const, role: "user" },
{
content: [
{
@@ -3142,7 +3164,7 @@ describe("createToolLoopHarness", () => {
const config = createTestConfig("conversation");
const runStep = createToolLoopHarness(config);
const session = createTestSession({
- history: [{ content: "prior message", role: "user" }],
+ history: [{ content: "prior message", kind: "user" as const, role: "user" }],
});
const result = await runStep(session);
@@ -3150,7 +3172,7 @@ describe("createToolLoopHarness", () => {
expect(result.next).toBeNull();
expect(result.settledTurn).toEqual({ output: "The result is 42." });
expect(result.session.history).toEqual([
- { content: "prior message", role: "user" },
+ { content: "prior message", kind: "user" as const, role: "user" },
{ content: "The result is 42.", role: "assistant" },
]);
});
@@ -3211,7 +3233,9 @@ describe("createToolLoopHarness", () => {
const { emit, events } = createEventCollector();
const runStep = createToolLoopHarness(createTestConfig("conversation", emit));
- await runStep(createTestSession({ history: [{ content: "prior", role: "user" }] }));
+ await runStep(
+ createTestSession({ history: [{ content: "prior", kind: "user" as const, role: "user" }] }),
+ );
expect(getCompatibilityEventTypes(events)).toEqual([
"step.started",
@@ -3667,7 +3691,7 @@ describe("createToolLoopHarness", () => {
expect(firstStep.next).toBe(runStep);
expect(firstStep.session.history).toEqual([
- { content: "Add these", role: "user" },
+ { content: "Add these", kind: "user" as const, role: "user" },
{
content: [
{
@@ -4337,7 +4361,7 @@ describe("createToolLoopHarness", () => {
expect(modelCallMock).toHaveBeenCalledTimes(2);
expect(result.session.history).toEqual([
- { content: "Hi", role: "user" },
+ { content: "Hi", kind: "user" as const, role: "user" },
{ content: "Recovered", role: "assistant" },
]);
} finally {
@@ -5410,6 +5434,7 @@ describe("createToolLoopHarness", () => {
}>;
expect(reissueMessages.at(-1)).toMatchObject({
content: expect.stringContaining("was not delivered"),
+ kind: "execution.retry",
role: "user",
});
expect(reissueMessages.at(-1)?.content).not.toContain(EMPTY_DELIVERY_SENTINEL);
@@ -5444,6 +5469,7 @@ describe("createToolLoopHarness", () => {
}>;
expect(reissueMessages.at(-1)).toMatchObject({
content: expect.stringContaining(EMPTY_DELIVERY_SENTINEL),
+ kind: "execution.retry",
role: "user",
});
} finally {
@@ -5473,6 +5499,7 @@ describe("createToolLoopHarness", () => {
}>;
expect(reissueMessages.at(-1)).toMatchObject({
content: expect.stringContaining("was not delivered"),
+ kind: "execution.retry",
role: "user",
});
expect(reissueMessages.at(-1)?.content).not.toContain(EMPTY_DELIVERY_SENTINEL);
@@ -5529,6 +5556,7 @@ describe("createToolLoopHarness", () => {
}>;
expect(reissueMessages.at(-1)).toMatchObject({
content: expect.stringContaining("was not delivered"),
+ kind: "execution.retry",
role: "user",
});
expect(reissueMessages.at(-1)?.content).not.toContain(EMPTY_DELIVERY_SENTINEL);
@@ -5598,6 +5626,7 @@ describe("createToolLoopHarness", () => {
}>;
expect(reissueMessages.at(-1)).toMatchObject({
content: expect.stringContaining("was not delivered"),
+ kind: "execution.retry",
role: "user",
});
} finally {
@@ -6355,7 +6384,11 @@ describe("createToolLoopHarness", () => {
});
const { emit } = createEventCollector();
- const hidden = { content: "HIDE_FROM_APPROVAL_RESUME", role: "user" as const };
+ const hidden = {
+ content: "HIDE_FROM_APPROVAL_RESUME",
+ kind: "user" as const,
+ role: "user" as const,
+ };
const pendingSession = createPendingBashApprovalSession();
const session = {
...pendingSession,
@@ -6599,7 +6632,7 @@ describe("createToolLoopHarness", () => {
tools: [{ description: "Search the web", name: "web_search", inputSchema: null }],
},
history: [
- { content: "Search release notes.", role: "user" },
+ { content: "Search release notes.", kind: "user" as const, role: "user" },
{
content: [
{
@@ -6612,7 +6645,7 @@ describe("createToolLoopHarness", () => {
],
role: "assistant",
},
- { content: "Keep working while search resolves.", role: "user" },
+ { content: "Keep working while search resolves.", kind: "user" as const, role: "user" },
],
});
@@ -7778,6 +7811,7 @@ describe("createToolLoopHarness", () => {
expect(result.session.history).toHaveLength(2);
expect(result.session.history[0]).toEqual({
content: "Delete the temp directory.",
+ kind: "user" as const,
role: "user",
});
const projection = result.session.history[1];
@@ -7947,7 +7981,7 @@ describe("createToolLoopHarness", () => {
expect(typeof result.next).toBe("function");
expect(result.session.history).toEqual([
- { content: "Delete the temp directory.", role: "user" },
+ { content: "Delete the temp directory.", kind: "user" as const, role: "user" },
...responseMessages,
]);
expect(events.filter((event) => event.type === "input.requested")).toEqual([]);
@@ -8054,7 +8088,7 @@ describe("createToolLoopHarness", () => {
const settings = vi.mocked(ToolLoopAgent).mock.calls[callIndex]?.[0];
expect(settings?.toolChoice).not.toBe("none");
expect(settings?.tools).toHaveProperty("bash");
- expect(messages.at(-1)).toEqual({ content: question, role: "user" });
+ expect(messages.at(-1)).toEqual({ content: question, kind: "user" as const, role: "user" });
expect(messages.every((message) => message.role !== "tool")).toBe(true);
expect(messages.filter(isPendingApprovalProjection)).toHaveLength(1);
expect(messages.findIndex(isPendingApprovalProjection)).toBe(1);
@@ -8121,6 +8155,7 @@ describe("createToolLoopHarness", () => {
]);
expect(denialMessages[0]).toEqual({
content: "Delete the temp directory.",
+ kind: "user" as const,
role: "user",
});
expect(hasPendingInputBatch(deniedResult.session.state)).toBe(false);
@@ -8751,8 +8786,16 @@ describe("createToolLoopHarness", () => {
const firstMessages = readGenerateMessages(0);
expect(typeof firstResult.next).toBe("function");
expect(firstMessages.at(-1)?.role).toBe("tool");
- expect(firstMessages).not.toContainEqual({ content: context, role: "user" });
- expect(firstMessages).not.toContainEqual({ content: ephemeralContext, role: "user" });
+ expect(firstMessages).not.toContainEqual({
+ content: context,
+ kind: "user" as const,
+ role: "user",
+ });
+ expect(firstMessages).not.toContainEqual({
+ content: ephemeralContext,
+ kind: "user" as const,
+ role: "user",
+ });
expect((await readPreparedMessages(0)).at(-1)).toMatchObject({
providerOptions: {
anthropic: { cacheControl: { type: "ephemeral" } },
@@ -8766,11 +8809,12 @@ describe("createToolLoopHarness", () => {
expect(secondResult.next).toBeNull();
expect(secondMessages.slice(0, firstMessages.length)).toEqual(firstMessages);
expect(secondMessages.slice(-2)).toEqual([
- { content: ephemeralContext, role: "user" },
- { content: context, role: "user" },
+ { content: ephemeralContext, kind: "context.instruction", role: "user" },
+ { content: context, kind: "context.instruction", role: "user" },
]);
expect((await readPreparedMessages(1)).at(-1)).toMatchObject({
content: context,
+ kind: "context.instruction",
providerOptions: {
anthropic: { cacheControl: { type: "ephemeral" } },
},
@@ -8778,6 +8822,7 @@ describe("createToolLoopHarness", () => {
});
expect(secondResult.session.history).not.toContainEqual({
content: ephemeralContext,
+ kind: "user" as const,
role: "user",
});
});
@@ -8906,7 +8951,11 @@ describe("createToolLoopHarness", () => {
});
expect(firstResult.next).toBeNull();
expect(generateCalls).toHaveLength(1);
- expect(generateCalls[0]?.at(-1)).toEqual({ content: "Do something else", role: "user" });
+ expect(generateCalls[0]?.at(-1)).toEqual({
+ content: "Do something else",
+ kind: "user" as const,
+ role: "user",
+ });
expect(hasPendingInputBatch(firstResult.session.state)).toBe(true);
// Step 2: the late denial restores the withheld batch behind the
@@ -8919,7 +8968,11 @@ describe("createToolLoopHarness", () => {
// Committed history keeps the intervening exchange before the batch.
const history = deniedResult.session.history;
- expect(history[0]).toEqual({ content: "Do something else", role: "user" });
+ expect(history[0]).toEqual({
+ content: "Do something else",
+ kind: "user" as const,
+ role: "user",
+ });
expect(history[1]).toEqual({ content: "Sure, here you go.", role: "assistant" });
expect(history.at(-1)).toEqual({
content: "I will not run that command.",
@@ -9056,6 +9109,7 @@ describe("createToolLoopHarness", () => {
expect(generateCalls).toHaveLength(2);
expect(generateCalls[1]?.at(-1)).toEqual({
content: "Do something unrelated.",
+ kind: "user" as const,
role: "user",
});
expect(completed.next).toEqual({ done: true, output: "Task complete." });
@@ -9355,7 +9409,7 @@ describe("createToolLoopHarness", () => {
},
],
session: createTestSession({
- history: [{ content: "Help me choose.", role: "user" }],
+ history: [{ content: "Help me choose.", kind: "user" as const, role: "user" }],
}),
});
@@ -9381,6 +9435,7 @@ describe("createToolLoopHarness", () => {
expect(hasPendingInputBatch(result.session.state)).toBe(false);
expect(modelMessages?.at(-1)).toEqual({
content: expect.stringContaining("STALE-CANDIDATE-7Q4M"),
+ kind: "user" as const,
role: "user",
});
expect(
@@ -9447,7 +9502,7 @@ describe("createToolLoopHarness", () => {
},
],
session: createTestSession({
- history: [{ content: "Help me choose.", role: "user" }],
+ history: [{ content: "Help me choose.", kind: "user" as const, role: "user" }],
}),
});
@@ -9475,6 +9530,7 @@ describe("createToolLoopHarness", () => {
expect(hasPendingInputBatch(result.session.state)).toBe(false);
expect(modelMessages?.at(-1)).toEqual({
content: expect.stringContaining("STALE-CANDIDATE-7Q4M"),
+ kind: "user" as const,
role: "user",
});
// The stale selection must not append a second tool result for
@@ -9494,9 +9550,9 @@ describe("createToolLoopHarness", () => {
it("emits compaction.requested and compaction.completed when compaction triggers", async () => {
vi.mocked(shouldCompact).mockReturnValue(true);
vi.mocked(compactMessages).mockResolvedValue([
- { content: "Summary of our conversation so far:", role: "user" },
+ createFrameworkUserMessage("context.compaction", "Summary of our conversation so far:"),
{ content: "summary", role: "assistant" },
- { content: "recent message", role: "user" },
+ createUserMessage("user", "recent message"),
]);
setupMockAgent({
@@ -9525,7 +9581,7 @@ describe("createToolLoopHarness", () => {
tools: [{ description: "Adds numbers", name: "add", inputSchema: { type: "object" } }],
},
history: [
- { content: "old message", role: "user" },
+ { content: "old message", kind: "user" as const, role: "user" },
{ content: "old reply", role: "assistant" },
],
});
@@ -9577,10 +9633,10 @@ describe("createToolLoopHarness", () => {
it("selects the model from the pre-compaction view and dispatches step consumers after rewrite", async () => {
vi.mocked(shouldCompact).mockReturnValue(true);
- const compactedHistory: ModelMessage[] = [
- { content: "Summary of our conversation so far:", role: "user" },
+ const compactedHistory: HarnessModelMessage[] = [
+ { content: "Summary of our conversation so far:", kind: "context.compaction", role: "user" },
{ content: "summary", role: "assistant" },
- { content: "current", role: "user" },
+ { content: "current", kind: "user" as const, role: "user" },
];
vi.mocked(compactMessages).mockResolvedValue(compactedHistory);
setupMockAgent({
@@ -9591,7 +9647,11 @@ describe("createToolLoopHarness", () => {
toolResults: [],
});
- const hidden = { content: "HIDE_FROM_COMPACTION", role: "user" as const };
+ const hidden = {
+ content: "HIDE_FROM_COMPACTION",
+ kind: "user" as const,
+ role: "user" as const,
+ };
const preCompactionModelViews: Array<readonly ModelMessage[]> = [];
const stepViews: Array<readonly ModelMessage[]> = [];
const emit: HarnessEmitFn = async (event, messages) => {
@@ -9610,7 +9670,7 @@ describe("createToolLoopHarness", () => {
);
const session = createTestSession({
history: [
- { content: "visible", role: "user" },
+ { content: "visible", kind: "user" as const, role: "user" },
hidden,
{ content: "reply", role: "assistant" },
],
@@ -9621,9 +9681,9 @@ describe("createToolLoopHarness", () => {
);
const preCompactionView = [
- { content: "visible", role: "user" },
+ { content: "visible", kind: "user" as const, role: "user" },
{ content: "reply", role: "assistant" },
- { content: "current", role: "user" },
+ { content: "current", kind: "user" as const, role: "user" },
];
expect(preCompactionModelViews).toEqual([preCompactionView]);
expect(vi.mocked(compactMessages).mock.calls[0]?.[0]).toEqual(preCompactionView);
@@ -9650,8 +9710,8 @@ describe("createToolLoopHarness", () => {
threshold: 100_000,
},
history: [
- { content: "Static user instructions.", role: "user" },
- { content: "Dynamic user instructions.", role: "user" },
+ { content: "Static user instructions.", kind: "user" as const, role: "user" },
+ { content: "Dynamic user instructions.", kind: "user" as const, role: "user" },
{ content: "old reply", role: "assistant" },
],
limits,
@@ -9684,15 +9744,19 @@ describe("createToolLoopHarness", () => {
});
it("compacts user instructions as ordinary history without starting a model turn", async () => {
- const compactedHistory: ModelMessage[] = [
- { content: "Summary of our conversation so far:", role: "user" },
+ const compactedHistory: HarnessModelMessage[] = [
+ { content: "Summary of our conversation so far:", kind: "context.compaction", role: "user" },
{ content: "summary", role: "assistant" },
];
vi.mocked(compactMessages).mockResolvedValue(compactedHistory);
const { emit, events } = createEventCollector();
const onCompaction = vi.fn(() => []);
- const hidden = { content: "Hidden internal context.", role: "user" as const };
+ const hidden = {
+ content: "Hidden internal context.",
+ kind: "user" as const,
+ role: "user" as const,
+ };
const runStep = createToolLoopHarness(
createTestConfig("conversation", emit, {
compactOnly: true,
@@ -9711,9 +9775,9 @@ describe("createToolLoopHarness", () => {
threshold: 100_000,
},
history: [
- { content: "Static user instructions.", role: "user" },
+ { content: "Static user instructions.", kind: "user" as const, role: "user" },
hidden,
- { content: "Dynamic user instructions.", role: "user" },
+ { content: "Dynamic user instructions.", kind: "user" as const, role: "user" },
{ content: "old reply", role: "assistant" },
],
});
@@ -9726,8 +9790,8 @@ describe("createToolLoopHarness", () => {
expect(shouldCompact).not.toHaveBeenCalled();
expect(compactMessages).toHaveBeenCalledOnce();
expect(vi.mocked(compactMessages).mock.calls[0]?.[0]).toEqual([
- { content: "Static user instructions.", role: "user" },
- { content: "Dynamic user instructions.", role: "user" },
+ { content: "Static user instructions.", kind: "user" as const, role: "user" },
+ { content: "Dynamic user instructions.", kind: "user" as const, role: "user" },
{ content: "old reply", role: "assistant" },
]);
expect(onCompaction).toHaveBeenCalledOnce();
@@ -9770,7 +9834,7 @@ describe("createToolLoopHarness", () => {
}),
);
const session = createTestSession({
- history: [{ content: "old message", role: "user" }],
+ history: [{ content: "old message", kind: "user" as const, role: "user" }],
});
const ctx = new ContextContainer();
ctx.set(HistoryStateKey, { taskState: "old message" });
@@ -9792,7 +9856,7 @@ describe("createToolLoopHarness", () => {
}),
);
const session = createTestSession({
- history: [{ content: "old message", role: "user" }],
+ history: [{ content: "old message", kind: "user" as const, role: "user" }],
});
const result = await runStep(session);
@@ -9807,9 +9871,9 @@ describe("createToolLoopHarness", () => {
it("uses the authored compaction model when one is configured", async () => {
vi.mocked(shouldCompact).mockReturnValue(true);
vi.mocked(compactMessages).mockResolvedValue([
- { content: "Summary of our conversation so far:", role: "user" },
+ createFrameworkUserMessage("context.compaction", "Summary of our conversation so far:"),
{ content: "summary", role: "assistant" },
- { content: "recent message", role: "user" },
+ createUserMessage("user", "recent message"),
]);
setupMockAgent({
@@ -9840,7 +9904,7 @@ describe("createToolLoopHarness", () => {
tools: [{ description: "Adds numbers", name: "add", inputSchema: { type: "object" } }],
},
history: [
- { content: "old message", role: "user" },
+ { content: "old message", kind: "user" as const, role: "user" },
{ content: "old reply", role: "assistant" },
],
});
@@ -9849,9 +9913,9 @@ describe("createToolLoopHarness", () => {
const call = vi.mocked(compactMessages).mock.calls[0];
expect(call?.[0]).toEqual([
- { content: "old message", role: "user" },
+ { content: "old message", kind: "user" as const, role: "user" },
{ content: "old reply", role: "assistant" },
- { content: "Hi", role: "user" },
+ { content: "Hi", kind: "user" as const, role: "user" },
]);
expect(call?.[1]).toMatchObject({
modelId: "summary-model",
@@ -10020,7 +10084,7 @@ describe("createToolLoopHarness", () => {
it("invokes onCompaction callback after compaction", async () => {
vi.mocked(shouldCompact).mockReturnValue(true);
vi.mocked(compactMessages).mockResolvedValue([
- { content: "Summary of our conversation so far:", role: "user" },
+ createFrameworkUserMessage("context.compaction", "Summary of our conversation so far:"),
{ content: "summary", role: "assistant" },
]);
@@ -10034,27 +10098,27 @@ describe("createToolLoopHarness", () => {
const onCompaction = vi
.fn()
- .mockReturnValue([{ content: "[State preserved]", role: "user" as const }]);
+ .mockReturnValue([createFrameworkUserMessage("context.state", "[State preserved]")]);
const runStep = createToolLoopHarness(
createTestConfig("conversation", undefined, { onCompaction }),
);
const session = createTestSession({
- history: [{ content: "old", role: "user" }],
+ history: [{ content: "old", kind: "user" as const, role: "user" }],
});
const result = await runStep(session, { message: "Continue" });
expect(onCompaction).toHaveBeenCalledTimes(1);
expect(result.session.history).toEqual([
- { content: "Summary of our conversation so far:", role: "user" },
+ { content: "Summary of our conversation so far:", kind: "context.compaction", role: "user" },
{ content: "summary", role: "assistant" },
- { content: "[State preserved]", role: "user" },
+ { content: "[State preserved]", kind: "context.state", role: "user" },
{ content: "Resuming.", role: "assistant" },
]);
});
- it("compaction appends synthetic user message when recent window trails with assistant", async () => {
+ it("compaction appends a framework continuation when recent window trails with assistant", async () => {
// Step 1: tool call → harness continues (next === runStep).
setupMockAgent({
content: [{ type: "tool-call", toolCallId: "call-1", toolName: "add", args: {} }],
@@ -10101,13 +10165,13 @@ describe("createToolLoopHarness", () => {
// Step 3: new turn with compaction. The mock simulates the
// guarded output from the real compactMessages: trailing
- // assistant gets a synthetic user("Continue.") appended.
+ // assistant gets a framework continuation appended.
vi.mocked(shouldCompact).mockReturnValue(true);
vi.mocked(compactMessages).mockResolvedValue([
- { content: "Summary of our conversation so far:", role: "user" },
+ createFrameworkUserMessage("context.compaction", "Summary of our conversation so far:"),
{ content: "summary", role: "assistant" },
{ content: "The answer is 42.", role: "assistant" },
- { content: "Continue.", role: "user" },
+ createFrameworkUserMessage("execution.continuation", "Continue."),
]);
setupMockAgent({
@@ -10121,15 +10185,19 @@ describe("createToolLoopHarness", () => {
const step3Harness = createToolLoopHarness(createTestConfig("conversation"));
await step3Harness(result2.session, {});
- // Verify the model received messages ending with the synthetic
- // user message, not the trailing assistant.
+ // Verify the model received the continuation user message, not the
+ // trailing assistant.
const instance = vi.mocked(ToolLoopAgent).mock.results.at(-1)?.value as {
generate: ReturnType<typeof vi.fn>;
};
const modelMessages = instance.generate.mock.calls[0]?.[0] as {
messages: Array<{ role: string; content: unknown }>;
};
- expect(modelMessages.messages.at(-1)).toEqual({ content: "Continue.", role: "user" });
+ expect(modelMessages.messages.at(-1)).toEqual({
+ content: "Continue.",
+ kind: "execution.continuation",
+ role: "user",
+ });
});
it("does not call onCompaction when compaction does not trigger", async () => {
@@ -10378,14 +10446,18 @@ describe("createToolLoopHarness", () => {
{ gateway: { caching: "auto" } },
]);
expect(modelCalls.map((call) => call.messages)).toEqual([
- [{ content: "Add 1 and 2.", role: "user" }],
- [{ content: "Add 1 and 2.", role: "user" }, toolCallMessage, toolResultMessage],
+ [{ content: "Add 1 and 2.", kind: "user" as const, role: "user" }],
+ [
+ { content: "Add 1 and 2.", kind: "user" as const, role: "user" },
+ toolCallMessage,
+ toolResultMessage,
+ ],
[
- { content: "Add 1 and 2.", role: "user" },
+ { content: "Add 1 and 2.", kind: "user" as const, role: "user" },
toolCallMessage,
toolResultMessage,
firstAnswerMessage,
- { content: "Can you confirm?", role: "user" },
+ { content: "Can you confirm?", kind: "user" as const, role: "user" },
],
]);
});
@@ -10643,7 +10715,7 @@ describe("createToolLoopHarness", () => {
const runStep = createToolLoopHarness(config);
const session = createTestSession({
history: [
- { content: "a", role: "user" },
+ { content: "a", kind: "user" as const, role: "user" },
{ content: "b", role: "assistant" },
],
});
@@ -10651,15 +10723,15 @@ describe("createToolLoopHarness", () => {
const agentCall = vi.mocked(ToolLoopAgent).mock.calls[0]?.[0];
const prepareStep = getPrepareStep<
- Array<{ role: string; content: string; providerOptions?: unknown }>,
+ Array<{ role: string; content: string; kind?: string; providerOptions?: unknown }>,
{ messages?: Array<{ providerOptions?: unknown }> }
>(agentCall?.prepareStep);
const result = await prepareStep({
messages: [
- { role: "user", content: "a" },
+ { kind: "user" as const, role: "user", content: "a" },
{ role: "assistant", content: "b" },
- { role: "user", content: "c" },
+ { kind: "user" as const, role: "user", content: "c" },
],
stepNumber: 0,
steps: [],
@@ -11001,7 +11073,7 @@ describe("createToolLoopHarness", () => {
it("derives compaction attribution from the compaction model", async () => {
vi.mocked(shouldCompact).mockReturnValueOnce(true);
vi.mocked(compactMessages).mockResolvedValueOnce([
- { content: "Summary of our conversation so far:", role: "user" },
+ createFrameworkUserMessage("context.compaction", "Summary of our conversation so far:"),
{ content: "summary", role: "assistant" },
]);
setupStopResultForAttribution();
@@ -11248,7 +11320,7 @@ describe("createToolLoopHarness", () => {
it("keeps compaction telemetry metadata-only on a rejected trace", async () => {
vi.mocked(shouldCompact).mockReturnValueOnce(true);
vi.mocked(compactMessages).mockResolvedValueOnce([
- { content: "Summary of our conversation so far:", role: "user" },
+ createFrameworkUserMessage("context.compaction", "Summary of our conversation so far:"),
{ content: "summary", role: "assistant" },
]);
setupMockAgent({
@@ -11804,7 +11876,11 @@ describe("createToolLoopHarness", () => {
},
});
- const hidden = { content: "HIDE_FROM_INSTRUMENTATION", role: "user" as const };
+ const hidden = {
+ content: "HIDE_FROM_INSTRUMENTATION",
+ kind: "user" as const,
+ role: "user" as const,
+ };
const config = createTestConfig("conversation", emit, {
historyProjector: ({ messages }) => messages.filter((message) => message !== hidden),
});
@@ -11812,7 +11888,7 @@ describe("createToolLoopHarness", () => {
await contextStorage.run(ctx, () =>
runStep(
createTestSession({
- history: [{ content: "visible", role: "user" }, hidden],
+ history: [{ content: "visible", kind: "user" as const, role: "user" }, hidden],
}),
{ message: "hi" },
),
@@ -11826,8 +11902,8 @@ describe("createToolLoopHarness", () => {
expect.objectContaining({
modelInput: expect.objectContaining({
messages: [
- { content: "visible", role: "user" },
- { content: "hi", role: "user" },
+ { content: "visible", kind: "user" as const, role: "user" },
+ { content: "hi", kind: "user" as const, role: "user" },
],
}),
step: { index: 0 },
@@ -12195,7 +12271,7 @@ describe("createToolLoopHarness", () => {
content: "You are a test assistant.\n\ndurable-system",
});
expect(messages.find((m) => m.role === "system")).toBeUndefined();
- expect(messages.at(-1)).toEqual({ role: "user", content: "Hi" });
+ expect(messages.at(-1)).toEqual({ kind: "user" as const, role: "user", content: "Hi" });
});
it("persists context strings in session history as user messages", async () => {
@@ -12209,8 +12285,8 @@ describe("createToolLoopHarness", () => {
});
expect(result.session.history).toEqual([
- { role: "user", content: "background-context" },
- { role: "user", content: "Hi" },
+ { role: "user", content: "background-context", kind: "context.instruction" },
+ { kind: "user" as const, role: "user", content: "Hi" },
{ role: "assistant", content: "ok" },
]);
});
@@ -12231,9 +12307,12 @@ describe("createToolLoopHarness", () => {
typeof message.content === "string" && message.content.startsWith("Client context:"),
);
- expect(visibleClientContext).toEqual([{ content: clientContext, role: "user" }]);
+ expect(visibleClientContext).toEqual([
+ { content: clientContext, kind: "context.instruction", role: "user" },
+ ]);
expect(result.session.history).not.toContainEqual({
content: clientContext,
+ kind: "user" as const,
role: "user",
});
session = result.session;
@@ -12296,13 +12375,14 @@ describe("createToolLoopHarness", () => {
expect(secondPrompt.slice(0, firstPrompt.length)).toEqual(firstPrompt);
expect(secondPrompt).toEqual([
- { content: clientContext, role: "user" },
- { content: "Add 20 and 22.", role: "user" },
+ { content: clientContext, kind: "context.instruction", role: "user" },
+ { content: "Add 20 and 22.", kind: "user" as const, role: "user" },
toolCallMessage,
toolResultMessage,
]);
expect(secondStep.session.history).not.toContainEqual({
content: clientContext,
+ kind: "user" as const,
role: "user",
});
expect(JSON.stringify(secondStep.session.state)).not.toContain(clientContext);
@@ -12311,6 +12391,7 @@ describe("createToolLoopHarness", () => {
await runStep(secondStep.session, { message: "Start another turn." });
expect(getLastAgentSettings().messages).not.toContainEqual({
content: clientContext,
+ kind: "user" as const,
role: "user",
});
});
@@ -12365,7 +12446,7 @@ describe("createToolLoopHarness", () => {
const initial = setHarnessEmissionState(
createTestSession({
history: [
- { role: "user", content: "Previous request" },
+ { role: "user", content: "Previous request", kind: "user" as const },
{ role: "assistant", content: "Previous answer" },
],
}),
@@ -12383,6 +12464,7 @@ describe("createToolLoopHarness", () => {
expect(first.session.history).toContainEqual({
role: "user",
content: analysisTaskAnnouncement,
+ kind: "context.state",
});
const nextState = changed
? '[Task state]\n{"tasks":[{"name":"analysis","status":"pending","taskId":"analysis"},{"name":"verification","status":"pending","taskId":"verification"}]}'
@@ -12402,7 +12484,11 @@ describe("createToolLoopHarness", () => {
).toHaveLength(1);
expect(nextContext.get(HistoryStateKey)).toMatchObject({ taskState: nextState });
if (changed) {
- expect(nextPrompt.at(-1)).toEqual({ role: "user", content: nextState });
+ expect(nextPrompt.at(-1)).toEqual({
+ role: "user",
+ content: nextState,
+ kind: "context.state",
+ });
} else {
expect(nextPrompt.at(-1)?.role).toBe("tool");
}
@@ -12421,6 +12507,7 @@ describe("createToolLoopHarness", () => {
);
expect(ctx.get(HistoryStateKey)).toBeUndefined();
expect(failed.session.history).not.toContainEqual({
+ kind: "user" as const,
role: "user",
content: "Available skills\n- policy: Tenant policy",
});
@@ -12432,6 +12519,7 @@ describe("createToolLoopHarness", () => {
expect(retried.session.history).toContainEqual({
role: "user",
content: "Available skills\n- policy: Tenant policy",
+ kind: "context.state",
});
expect(ctx.get(HistoryStateKey)).toEqual({
availableSkills: "Available skills\n- policy: Tenant policy",
@@ -12455,6 +12543,7 @@ describe("createToolLoopHarness", () => {
expect(getLastAgentSettings().messages).toContainEqual({
role: "user",
content: "Available skills\n- policy: Tenant policy",
+ kind: "context.state",
});
expect(ctx.get(HistoryStateKey)).toBeUndefined();
});
@@ -12471,7 +12560,7 @@ describe("createToolLoopHarness", () => {
lastKnownInputTokens: 50_000,
lastKnownPromptMessageCount: 1,
},
- history: [{ role: "user", content: announcement }],
+ history: [{ role: "user", content: announcement, kind: "user" as const }],
});
const { emit } = createEventCollector();
const runStep = createToolLoopHarness(
@@ -12481,14 +12570,16 @@ describe("createToolLoopHarness", () => {
);
vi.mocked(shouldCompact).mockReturnValueOnce(true);
vi.mocked(compactMessages).mockResolvedValueOnce([
- { role: "user", content: "Conversation summary" },
+ createFrameworkUserMessage("context.compaction", "Conversation summary"),
]);
setupMockAgentError(new Error("Model unavailable"));
const failed = await contextStorage.run(ctx, () =>
runStep(session, { message: "Continue." }),
);
- expect(failed.session.history).toEqual([{ role: "user", content: "Conversation summary" }]);
+ expect(failed.session.history).toEqual([
+ createFrameworkUserMessage("context.compaction", "Conversation summary"),
+ ]);
expect(ctx.get(HistoryStateKey)).toBeUndefined();
expect(failed.session.compaction).not.toHaveProperty("lastKnownInputTokens");
expect(failed.session.compaction).not.toHaveProperty("lastKnownPromptMessageCount");
@@ -12529,7 +12620,7 @@ describe("createToolLoopHarness", () => {
expect(ctx.get(HistoryStateKey)).toEqual(expectedState);
vi.mocked(compactMessages).mockResolvedValue([
- { role: "user", content: "Conversation summary" },
+ createFrameworkUserMessage("context.compaction", "Conversation summary"),
]);
let session = first.session;
if (replacement === "automatic compaction") {
@@ -12576,7 +12667,7 @@ describe("createToolLoopHarness", () => {
);
expect(getLastAgentSettings().messages).toEqual([
...first.session.history,
- { role: "user", content: "Continue." },
+ { kind: "user" as const, role: "user", content: "Continue." },
]);
});
@@ -12589,7 +12680,7 @@ describe("createToolLoopHarness", () => {
});
const runStep = createToolLoopHarness(createTestConfig("conversation"));
const session = createTestSession({
- history: [{ content: "earlier", role: "user" }],
+ history: [{ content: "earlier", kind: "user" as const, role: "user" }],
});
const result = await runStep(
@@ -12599,18 +12690,19 @@ describe("createToolLoopHarness", () => {
expect(vi.mocked(shouldCompact)).toHaveBeenCalledWith(
[
- { content: "earlier", role: "user" },
- { content: "Client context:\ncurrent", role: "user" },
- { content: "Hi", role: "user" },
+ { content: "earlier", kind: "user" as const, role: "user" },
+ { content: "Client context:\ncurrent", kind: "context.instruction", role: "user" },
+ { content: "Hi", kind: "user" as const, role: "user" },
],
session.compaction,
);
expect(vi.mocked(compactMessages).mock.calls[0]?.[0]).toEqual([
- { content: "earlier", role: "user" },
- { content: "Hi", role: "user" },
+ { content: "earlier", kind: "user" as const, role: "user" },
+ { content: "Hi", kind: "user" as const, role: "user" },
]);
expect(result.session.history).not.toContainEqual({
content: "Client context:\ncurrent",
+ kind: "user" as const,
role: "user",
});
expect(result.session.compaction).not.toHaveProperty("lastKnownInputTokens");
@@ -12643,6 +12735,7 @@ describe("createToolLoopHarness", () => {
expect(messages).toContainEqual({
role: "user",
content: CONDITIONAL_DELIVERY_INSTRUCTION,
+ kind: "context.instruction",
});
},
);
@@ -12689,8 +12782,12 @@ describe("createToolLoopHarness", () => {
const { instructions, messages } = getLastAgentSettings();
expect(instructions).toBe("You are a test assistant.");
expect(messages.slice(0, 2)).toEqual([
- { role: "user", content: analysisTaskAnnouncement },
- { role: "user", content: TASK_DELIVERY_INITIATING_INSTRUCTION },
+ { role: "user", content: analysisTaskAnnouncement, kind: "context.state" },
+ {
+ role: "user",
+ content: TASK_DELIVERY_INITIATING_INSTRUCTION,
+ kind: "context.instruction",
+ },
]);
});
@@ -12714,9 +12811,13 @@ describe("createToolLoopHarness", () => {
const { instructions, messages } = getLastAgentSettings();
expect(instructions).toBe("You are a test assistant.");
expect(messages.slice(-3)).toEqual([
- { role: "user", content: taskState },
- { role: "user", content: TASK_DELIVERY_INITIATING_INSTRUCTION },
- { role: "user", content: "Start the background work." },
+ { role: "user", content: taskState, kind: "context.state" },
+ {
+ role: "user",
+ content: TASK_DELIVERY_INITIATING_INSTRUCTION,
+ kind: "context.instruction",
+ },
+ { kind: "user" as const, role: "user", content: "Start the background work." },
]);
});
@@ -12733,6 +12834,7 @@ describe("createToolLoopHarness", () => {
),
);
expect(getLastAgentSettings().messages).not.toContainEqual({
+ kind: "user" as const,
role: "user",
content: analysisTaskAnnouncement,
});
@@ -12755,6 +12857,7 @@ describe("createToolLoopHarness", () => {
expect(messages).toContainEqual({
role: "user",
content: CONDITIONAL_DELIVERY_INSTRUCTION,
+ kind: "context.instruction",
});
});
@@ -12787,10 +12890,20 @@ describe("createToolLoopHarness", () => {
});
const first = await contextStorage.run(ctx, () =>
- runStep(session, { message: "Background task task_1 is completed." }),
+ runStep(
+ session,
+ markFrameworkStepInput(
+ { message: "Background task task_1 is completed." },
+ "execution.background_task",
+ ),
+ ),
);
expect(getLastAgentSettings().messages).toEqual([
- { role: "user", content: "Background task task_1 is completed." },
+ {
+ role: "user",
+ content: "Background task task_1 is completed.",
+ kind: "execution.background_task",
+ },
]);
expect(ctx.get(HistoryStateKey)?.deliveryInstruction).toBeUndefined();
@@ -12800,7 +12913,7 @@ describe("createToolLoopHarness", () => {
);
expect(getLastAgentSettings().messages).toEqual([
...first.session.history,
- { role: "user", content: "What is 7 times 8?" },
+ { kind: "user" as const, role: "user", content: "What is 7 times 8?" },
]);
});
@@ -12817,14 +12930,28 @@ describe("createToolLoopHarness", () => {
});
await contextStorage.run(ctx, () =>
- runStep(session, { message: "Background task task_1 is completed." }),
+ runStep(
+ session,
+ markFrameworkStepInput(
+ { message: "Background task task_1 is completed." },
+ "execution.background_task",
+ ),
+ ),
);
const { instructions, messages } = getLastAgentSettings();
expect(instructions).toBe("You are a test assistant.");
expect(messages.slice(-2)).toEqual([
- { role: "user", content: TASK_DELIVERY_SETTLED_INSTRUCTION },
- { role: "user", content: "Background task task_1 is completed." },
+ {
+ role: "user",
+ content: TASK_DELIVERY_SETTLED_INSTRUCTION,
+ kind: "context.instruction",
+ },
+ {
+ role: "user",
+ content: "Background task task_1 is completed.",
+ kind: "execution.background_task",
+ },
]);
});
@@ -12897,14 +13024,18 @@ describe("createToolLoopHarness", () => {
resolvers: [resolver],
});
};
- const hidden = { content: "Hidden context.", role: "user" as const };
+ const hidden = {
+ content: "Hidden context.",
+ kind: "user" as const,
+ role: "user" as const,
+ };
const runStep = createToolLoopHarness(
createTestConfig("conversation", handleEvent, {
historyProjector: ({ messages }) => messages.filter((message) => message !== hidden),
}),
);
const session = createTestSession({
- history: [{ content: "Static context.", role: "user" }, hidden],
+ history: [{ content: "Static context.", kind: "user" as const, role: "user" }, hidden],
});
const result = await contextStorage.run(ctx, () => runStep(session, { message: "Hello." }));
@@ -12912,17 +13043,17 @@ describe("createToolLoopHarness", () => {
expect(snapshots).toEqual([["Static context."], ["Static context.", "Session context."]]);
expect(getLastAgentSettings().instructions).toBe("You are a test assistant.");
expect(getLastAgentSettings().messages).toEqual([
- { content: "Static context.", role: "user" },
- { content: "Session context.", role: "user" },
- { content: "Turn context.", role: "user" },
- { content: "Hello.", role: "user" },
+ { content: "Static context.", kind: "user" as const, role: "user" },
+ { content: "Session context.", kind: "context.instruction", role: "user" },
+ { content: "Turn context.", kind: "context.instruction", role: "user" },
+ { content: "Hello.", kind: "user" as const, role: "user" },
]);
expect(result.session.history).toEqual([
- { content: "Static context.", role: "user" },
+ { content: "Static context.", kind: "user" as const, role: "user" },
hidden,
- { content: "Session context.", role: "user" },
- { content: "Turn context.", role: "user" },
- { content: "Hello.", role: "user" },
+ { content: "Session context.", kind: "context.instruction", role: "user" },
+ { content: "Turn context.", kind: "context.instruction", role: "user" },
+ { content: "Hello.", kind: "user" as const, role: "user" },
{ content: "ok", role: "assistant" },
]);
});
@@ -12970,7 +13101,7 @@ describe("createToolLoopHarness", () => {
const result = await contextStorage.run(ctx, () => runStep(session, { message: "Hi" }));
expect(result.session.history).toEqual([
- { role: "user", content: "Hi" },
+ { kind: "user" as const, role: "user", content: "Hi" },
{ role: "assistant", content: "ok" },
]);
});
diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.ts
index fdfd6731b..9aebf29b3 100644
--- a/packages/eve/src/harness/tool-loop.ts
+++ b/packages/eve/src/harness/tool-loop.ts
@@ -164,9 +164,15 @@ import {
dropStaleSessionLimitContinuationResponses,
} from "#harness/stale-input-responses.js";
import {
+ createFrameworkUserMessage,
+ createUserMessage,
+ frameworkMessageKindForStepInput,
normalizeModelMessages,
normalizeUserContent,
resolveAssistantStepText,
+ type HarnessModelMessage,
+ type UserModelMessage,
+ validateHarnessModelMessages,
} from "#harness/messages.js";
import { normalizeProviderToolHistory } from "#harness/provider-tool-history.js";
import {
@@ -843,7 +849,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
resolvedCoordination.outcome === "resolved"
? {
...pending.session,
- history: [...resolvedCoordination.messages],
+ history: validateHarnessModelMessages(resolvedCoordination.messages),
}
: pending.session;
@@ -859,7 +865,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
projectHistory(parkedSession.history, parkedSession.state),
);
}
- let instructionMessages: ModelMessage[] = [];
+ let instructionMessages: UserModelMessage[] = [];
try {
const traceContext = await preparePreambleTrace();
emissionState = await emitTurnPreamble(
@@ -874,7 +880,10 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
store === undefined ? [] : drainDynamicInstructionUserMessages(store);
parkedSession = {
...parkedSession,
- history: [...parkedSession.history, ...instructionMessages],
+ history: validateHarnessModelMessages([
+ ...parkedSession.history,
+ ...instructionMessages,
+ ]),
};
session = parkedSession;
return failBoundaryEvent(error, {
@@ -887,7 +896,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
instructionMessages = store === undefined ? [] : drainDynamicInstructionUserMessages(store);
parkedSession = {
...parkedSession,
- history: [...parkedSession.history, ...instructionMessages],
+ history: validateHarnessModelMessages([...parkedSession.history, ...instructionMessages]),
};
emissionState = await emitTurnEpilogue(emit, emissionState, config.mode);
return {
@@ -961,24 +970,31 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
const clientContext =
pending.deferredContext === true ? undefined : readClientContext(effectiveStepInput);
const activeClientContext = clientContext ?? storedClientContext?.messages;
- const ephemeralContextMessages: ModelMessage[] =
- activeClientContext?.map((content) => ({ content, role: "user" })) ?? [];
- const preparedTurnInput: ModelMessage[] = [];
+ const ephemeralContextMessages: UserModelMessage[] =
+ activeClientContext?.map((content) =>
+ createFrameworkUserMessage("context.instruction", content),
+ ) ?? [];
+ const preparedTurnInput: UserModelMessage[] = [];
if (effectiveStepInput?.context !== undefined && pending.deferredContext !== true) {
for (const entry of effectiveStepInput.context) {
- preparedTurnInput.push({ content: entry, role: "user" });
+ preparedTurnInput.push(createFrameworkUserMessage("context.instruction", entry));
}
}
+ const frameworkMessageKind = frameworkMessageKindForStepInput(effectiveStepInput);
const normalizedTurnContent = normalizeUserContent(effectiveStepInput?.message);
const stagedTurnContent =
normalizedTurnContent !== undefined && !pending.deferredMessage && !pending.consumedMessage
? await stageAttachmentsToSandbox(normalizedTurnContent)
: undefined;
if (stagedTurnContent !== undefined) {
- preparedTurnInput.push({ content: stagedTurnContent, role: "user" });
+ preparedTurnInput.push(
+ frameworkMessageKind === undefined
+ ? createUserMessage("user", stagedTurnContent)
+ : createFrameworkUserMessage(frameworkMessageKind, stagedTurnContent),
+ );
}
- let instructionMessages: ModelMessage[] = [];
+ let instructionMessages: UserModelMessage[] = [];
let memoryCommit: ReturnType<typeof drainMemoryCommit> = undefined;
if (emit && hasStepInput(input)) {
if (store !== undefined) {
@@ -1006,7 +1022,10 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
memoryCommit = store === undefined ? undefined : drainMemoryCommit(store);
session = {
...pending.session,
- history: [...(memoryCommit?.history ?? pending.session.history), ...instructionMessages],
+ history: validateHarnessModelMessages([
+ ...(memoryCommit?.history ?? pending.session.history),
+ ...instructionMessages,
+ ]),
state: memoryCommit?.state ?? pending.session.state,
};
return failBoundaryEvent(error, {
@@ -1027,16 +1046,16 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
session = setHarnessEmissionState(
{
...pending.session,
- history: [...committedHistory, ...instructionMessages],
+ history: validateHarnessModelMessages([...committedHistory, ...instructionMessages]),
state: memoryCommit?.state ?? pending.session.state,
},
emissionState,
);
- let messages: ModelMessage[] = [
+ let messages: HarnessModelMessage[] = validateHarnessModelMessages([
...(memoryCommit?.history ?? pending.messages.slice(0, historyLength)),
...instructionMessages,
...(memoryCommit === undefined ? pending.messages.slice(historyLength) : []),
- ];
+ ]);
// A resolved session-limit continuation prompt grants a fresh token
// budget or ends the session; see session-limit-enforcement.
@@ -1079,7 +1098,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
store: agentStore,
});
if (announcement !== undefined) {
- messages.push({ content: announcement, role: "user" });
+ messages.push(createFrameworkUserMessage("context.state", announcement));
}
}
@@ -1098,7 +1117,9 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
messages = [...messages, ...preparedTurnInput];
- const createModelMessages = (durableMessages: readonly ModelMessage[]): ModelMessage[] => {
+ const createModelMessages = (
+ durableMessages: readonly HarnessModelMessage[],
+ ): HarnessModelMessage[] => {
if (turnClientContext === undefined || turnClientContext.messages.length === 0) {
return [...durableMessages];
}
@@ -1109,11 +1130,15 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
);
return [
...durableMessages.slice(0, insertionIndex),
- ...turnClientContext.messages.map((content) => ({ content, role: "user" as const })),
+ ...turnClientContext.messages.map((content) =>
+ createFrameworkUserMessage("context.instruction", content),
+ ),
...durableMessages.slice(insertionIndex),
];
};
- let projectedMessages = projectHistory(createModelMessages(messages), session.state);
+ let projectedMessages = validateHarnessModelMessages(
+ projectHistory(createModelMessages(messages), session.state),
+ );
// --- Model + tools ------------------------------------------------------
@@ -1185,8 +1210,8 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
session = setTurnClientContextState(session, turnClientContext);
}
}
- projectedMessages = normalizeModelMessages(
- projectHistory(createModelMessages(messages), session.state),
+ projectedMessages = validateHarnessModelMessages(
+ normalizeModelMessages(projectHistory(createModelMessages(messages), session.state)),
);
if (emit) {
@@ -1248,7 +1273,9 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
getPendingInputBatches(session.state).flatMap((batch) => batch.requests),
);
if (pendingApprovals !== undefined) {
- currentMessages.add(pendingApprovals, { cacheFriendly: false });
+ currentMessages.add(pendingApprovals, "context.state", {
+ cacheFriendly: false,
+ });
}
const promptMessages = currentMessages.history;
@@ -1326,7 +1353,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
// from the step's prompt messages, so the note exists only on this
// call's wire request.
const callMessages = opts.trailingUserNote
- ? [...modelMessages, { role: "user" as const, content: opts.trailingUserNote }]
+ ? [...modelMessages, createFrameworkUserMessage("execution.retry", opts.trailingUserNote)]
: [...modelMessages];
const harnessTools = buildHarnessToolsWithDynamicSubagents(config.tools, ctx);
const backgroundBatch = createBackgroundToolCallBatch();
@@ -2376,7 +2403,7 @@ async function handleStepResult(input: {
readonly emit?: ToolLoopHarnessConfig["handleEvent"];
readonly emissionState: ReturnType<typeof getHarnessEmissionState>;
readonly durableModelPromptMessageCount?: number;
- readonly promptMessages: readonly ModelMessage[];
+ readonly promptMessages: readonly HarnessModelMessage[];
readonly result: HarnessStepResult;
readonly runStep: StepFn;
readonly coordinationTools: HarnessToolMap;
@@ -2472,7 +2499,7 @@ async function handleStepResult(input: {
});
const inputRequests: InputRequest[] = [...approvalRequests, ...questionRequests];
const pendingApprovals = renderPendingApprovalsSnippet(approvalRequests);
- // Keep outcomes from resumed work ahead of the synthetic pending-approval
+ // Keep outcomes from resumed work ahead of the framework pending-approval
// message; only the unresolved assistant response belongs to the parked batch.
const pendingResponseStart = responseMessages.findIndex((message) => message.role !== "tool");
const committedResponseMessages =
@@ -2480,13 +2507,13 @@ async function handleStepResult(input: {
? responseMessages
: responseMessages.slice(0, pendingResponseStart);
const pendingResponseMessages = responseMessages.slice(committedResponseMessages.length);
- const parkedInputHistory: ModelMessage[] = [
+ const parkedInputHistory: HarnessModelMessage[] = validateHarnessModelMessages([
...promptMessages,
...committedResponseMessages,
...(pendingApprovals === undefined
? []
- : [{ content: pendingApprovals, role: "user" as const }]),
- ];
+ : [createFrameworkUserMessage("context.state", pendingApprovals)]),
+ ]);
const advertisedCoordinationTools = getAdvertisedTools({
session: baseSession,
tools: input.coordinationTools,
@@ -2538,7 +2565,7 @@ async function handleStepResult(input: {
turnId: emissionState.turnId,
},
responseMessages,
- session: { ...baseSession, history: [...promptMessages] },
+ session: { ...baseSession, history: validateHarnessModelMessages(promptMessages) },
}),
advanceStep(emissionState),
),
@@ -2692,7 +2719,7 @@ async function handleStepResult(input: {
session: setHarnessEmissionState(
{
...baseSession,
- history: authorizationHistory,
+ history: validateHarnessModelMessages(authorizationHistory),
state: setPendingAuthorization(baseSession.state, { challenges }),
},
emissionState,
@@ -2707,7 +2734,10 @@ async function handleStepResult(input: {
// hitting across steps. Compaction is the sole mechanism that ever rewrites
// history, and it runs before the model call (see `maybeCompact`).
const continuationMessages = responseMessages;
- const updatedHistory: ModelMessage[] = [...promptMessages, ...continuationMessages];
+ const updatedHistory: HarnessModelMessage[] = validateHarnessModelMessages([
+ ...promptMessages,
+ ...continuationMessages,
+ ]);
let nextSession: HarnessSession = { ...baseSession, history: updatedHistory };
// A `final_output` call is terminal even when the model emits it alongside
@@ -2786,7 +2816,7 @@ function extractFinalOutput(result: HarnessStepResult): JsonValue | undefined {
*/
function persistStructuredAssistantTurn(
session: HarnessSession,
- history: readonly ModelMessage[],
+ history: readonly HarnessModelMessage[],
structured: JsonValue,
): HarnessSession {
return {
@@ -2822,7 +2852,7 @@ async function emitStructuredResult(
async function finishTaskTurn(input: {
readonly emissionState: ReturnType<typeof getHarnessEmissionState>;
readonly emit?: ToolLoopHarnessConfig["handleEvent"];
- readonly history: readonly ModelMessage[];
+ readonly history: readonly HarnessModelMessage[];
readonly result: HarnessStepResult;
readonly schema: JsonObject | undefined;
readonly session: HarnessSession;
@@ -2872,7 +2902,7 @@ async function finishTaskTurn(input: {
async function finishConversationTurn(input: {
readonly emissionState: ReturnType<typeof getHarnessEmissionState>;
readonly emit?: ToolLoopHarnessConfig["handleEvent"];
- readonly history: readonly ModelMessage[];
+ readonly history: readonly HarnessModelMessage[];
readonly result: HarnessStepResult;
readonly schema: JsonObject | undefined;
readonly session: HarnessSession;
@@ -2996,7 +3026,10 @@ async function continuePendingWorkflowInterrupt(input: {
const unwrapped = await unwrapWorkflowSandboxResult(continuationOutput, continuationSecurity);
const finalOutput = unwrapped.status === "interrupted" ? unwrapped.interrupt : unwrapped.output;
- const baseMessages = [...input.session.history, ...pending.responseMessages];
+ const baseMessages = validateHarnessModelMessages([
+ ...input.session.history,
+ ...pending.responseMessages,
+ ]);
const replacedMessages = replaceWorkflowToolResult(
baseMessages,
(interrupt as { outerToolCallId?: string }).outerToolCallId,
@@ -3032,10 +3065,10 @@ async function continuePendingWorkflowInterrupt(input: {
}
function replaceWorkflowToolResult(
- messages: readonly ModelMessage[],
+ messages: readonly HarnessModelMessage[],
outerToolCallId: string | undefined,
output: unknown,
-): ModelMessage[] {
+): HarnessModelMessage[] {
if (outerToolCallId === undefined) return [...messages];
const outputValue =
typeof output === "string"
@@ -3050,7 +3083,7 @@ function replaceWorkflowToolResult(
},
);
return { ...message, content };
- }) as ModelMessage[];
+ }) as HarnessModelMessage[];
}
async function parkOnWorkflowInterrupt(input: {
@@ -3058,7 +3091,7 @@ async function parkOnWorkflowInterrupt(input: {
readonly emit?: ToolLoopHarnessConfig["handleEvent"];
readonly emissionState: ReturnType<typeof getHarnessEmissionState>;
readonly interrupt: WorkflowSandboxInterrupt;
- readonly promptMessages: readonly ModelMessage[];
+ readonly promptMessages: readonly HarnessModelMessage[];
readonly responseMessages: readonly ModelMessage[];
readonly tools: HarnessToolMap;
readonly usedCalls: number;
@@ -3118,7 +3151,10 @@ function createNextCompactionConfig(
return next;
}
-function replaceSessionHistory(session: HarnessSession, history: ModelMessage[]): HarnessSession {
+function replaceSessionHistory(
+ session: HarnessSession,
+ history: HarnessModelMessage[],
+): HarnessSession {
contextStorage.getStore()?.delete(HistoryStateKey);
return {
...session,
@@ -3147,26 +3183,27 @@ async function maybeCompact(input: {
readonly emissionState: ReturnType<typeof getHarnessEmissionState>;
readonly force?: boolean;
readonly historyProjector?: HistoryViewProjector;
- readonly messages: ModelMessage[];
+ readonly messages: HarnessModelMessage[];
readonly model: LanguageModel;
readonly onCompaction?: ToolLoopHarnessConfig["onCompaction"];
/** Model-visible prompt used only to decide whether durable history needs compaction. */
- readonly promptMessages?: readonly ModelMessage[];
+ readonly promptMessages?: readonly HarnessModelMessage[];
readonly resolveModel: ToolLoopHarnessConfig["resolveModel"];
readonly runtimeIdentity?: ToolLoopHarnessConfig["runtimeIdentity"];
readonly session: HarnessSession;
readonly telemetry?: TelemetryOptions;
}): Promise<{
readonly compacted: boolean;
- readonly messages: ModelMessage[];
+ readonly messages: HarnessModelMessage[];
readonly session: HarnessSession;
}> {
const { emit, emissionState } = input;
let messages = input.messages;
let session = input.session;
const promptMessages = input.promptMessages ?? messages;
- const projectedPromptMessages =
- input.historyProjector?.({ messages: promptMessages, state: session.state }) ?? promptMessages;
+ const projectedPromptMessages = validateHarnessModelMessages(
+ input.historyProjector?.({ messages: promptMessages, state: session.state }) ?? promptMessages,
+ );
const needsSummary =
input.force === true || shouldCompact(projectedPromptMessages, session.compaction);
const needsMemoryCanonicalization = shouldCanonicalizeMemory(messages);
@@ -3207,9 +3244,10 @@ async function maybeCompact(input: {
}
const canonical = canonicalizeMemoryRecords(messages);
- const ordinary =
+ const ordinary = validateHarnessModelMessages(
input.historyProjector?.({ messages: canonical.ordinary, state: session.state }) ??
- canonical.ordinary;
+ canonical.ordinary,
+ );
const compactedOrdinary = needsSummary
? await compactMessages(
[...ordinary],
@@ -3222,7 +3260,7 @@ async function maybeCompact(input: {
input.force === true,
)
: [...ordinary];
- messages = [...canonical.memory, ...compactedOrdinary];
+ messages = validateHarnessModelMessages([...canonical.memory, ...compactedOrdinary]);
if (input.onCompaction) {
for (const msg of input.onCompaction()) {
@@ -3247,7 +3285,7 @@ async function maybeCompact(input: {
if (ctx !== undefined) {
const commit = drainMemoryCommit(ctx);
if (commit !== undefined) {
- messages = [...commit.history];
+ messages = validateHarnessModelMessages(commit.history);
session = { ...session, state: commit.state };
}
}
diff --git a/packages/eve/src/harness/types.ts b/packages/eve/src/harness/types.ts
index e4fde1157..e778f9b70 100644
--- a/packages/eve/src/harness/types.ts
+++ b/packages/eve/src/harness/types.ts
@@ -17,6 +17,7 @@ import type { TokenUsage } from "#shared/token-usage.js";
import type { InternalToolDefinition } from "#tools/definition.js";
import type { AgentReasoningDefinition } from "#shared/agent-definition.js";
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
+import type { HarnessModelMessage } from "#harness/messages.js";
import type { SessionInstrumentation } from "#instrumentation/runtime.js";
import type { HistoryViewProjector, PreparedHistoryView } from "#shared/history-view.js";
@@ -79,7 +80,7 @@ export interface HarnessSession {
readonly agent: SessionAgent;
readonly compaction: CompactionConfig;
readonly continuationToken: string;
- readonly history: ModelMessage[];
+ readonly history: HarnessModelMessage[];
readonly limits?: SessionLimits;
readonly outputSchema?: JsonObject;
/**
@@ -159,8 +160,8 @@ export interface StepInput {
/** Internal actor attribution for `message`. */
readonly messageAuth?: SessionAuthContext | null;
/**
- * Context strings from the channel delivery. Each entry is appended
- * as a `role: "user"` message to `session.history` before the
+ * Context strings from the channel delivery. Each entry is appended as a
+ * synthetic user-role message to `session.history` before the
* delivery message. Populated by channels via `SendPayload.context`.
*/
readonly context?: readonly string[];
@@ -330,7 +331,7 @@ export interface ToolLoopHarnessConfig {
* re-injection). The harness appends the returned messages to the
* compacted history.
*/
- readonly onCompaction?: () => readonly ModelMessage[];
+ readonly onCompaction?: () => readonly HarnessModelMessage[];
/** Resolves persisted step-scoped tools before an approval policy reads them. */
readonly resolveStepDynamicTools?: (input: {
readonly ctx: AlsContext;
diff --git a/packages/eve/src/internal/testing/durable-session-workflow.ts b/packages/eve/src/internal/testing/durable-session-workflow.ts
index 6db0c4728..329a6eba7 100644
--- a/packages/eve/src/internal/testing/durable-session-workflow.ts
+++ b/packages/eve/src/internal/testing/durable-session-workflow.ts
@@ -3,8 +3,6 @@
* `readDurableSession` round-trip from inside a real workflow runtime.
* The workflow test-time bundle builder discovers this directory.
*/
-import type { ModelMessage } from "ai";
-
import { getStepMetadata, getWorkflowMetadata } from "#compiled/@workflow/core/index.js";
import {
@@ -20,10 +18,14 @@ function buildSyntheticSession(input: {
marker: string;
historyDepth: number;
}): HarnessSession {
- const history: ModelMessage[] = Array.from({ length: input.historyDepth }, (_, index) => ({
- content: `${input.marker} message ${index}`,
- role: "user",
- }));
+ const history: HarnessSession["history"] = Array.from(
+ { length: input.historyDepth },
+ (_, index) => ({
+ content: `${input.marker} message ${index}`,
+ kind: "user",
+ role: "user",
+ }),
+ );
return {
agent: {
diff --git a/packages/eve/src/internal/testing/task-model-retry-workflow.ts b/packages/eve/src/internal/testing/task-model-retry-workflow.ts
index 70297c3ee..605d3335c 100644
--- a/packages/eve/src/internal/testing/task-model-retry-workflow.ts
+++ b/packages/eve/src/internal/testing/task-model-retry-workflow.ts
@@ -19,8 +19,8 @@ import { createBootstrapGenerateResult } from "#runtime/agent/bootstrap-model-ut
import type { RuntimeTurnAgent } from "#runtime/agent/bootstrap.js";
const MODEL_ID = "task-model-retry-fixture";
-const PRIOR_HISTORY: readonly ModelMessage[] = [
- { content: "Complete the delegated task.", role: "user" },
+const PRIOR_HISTORY: HarnessSession["history"] = [
+ { content: "Complete the delegated task.", kind: "user", role: "user" },
{ content: "Prior durable work is complete.", role: "assistant" },
];
diff --git a/packages/eve/src/runtime/agent/bootstrap.test.ts b/packages/eve/src/runtime/agent/bootstrap.test.ts
index cf25047f8..37acc485a 100644
--- a/packages/eve/src/runtime/agent/bootstrap.test.ts
+++ b/packages/eve/src/runtime/agent/bootstrap.test.ts
@@ -82,7 +82,9 @@ describe("createResolvedRuntimeTurnAgent agent-messaging gating", () => {
tools: [createFrameworkAgentTool()],
});
- expect(turnAgent.initialMessages).toEqual([{ content: "Pinned user context.", role: "user" }]);
+ expect(turnAgent.initialMessages).toEqual([
+ { content: "Pinned user context.", kind: "context.instruction", role: "user" },
+ ]);
expect(turnAgent.instructions).toContainEqual(
"Instructions (instructions/system)\nSystem policy.",
);
diff --git a/packages/eve/src/runtime/agent/bootstrap.ts b/packages/eve/src/runtime/agent/bootstrap.ts
index 6e196942c..06175438c 100644
--- a/packages/eve/src/runtime/agent/bootstrap.ts
+++ b/packages/eve/src/runtime/agent/bootstrap.ts
@@ -1,4 +1,6 @@
-import type { ModelMessage } from "ai";
+import type { HarnessModelMessage } from "#harness/messages.js";
+
+import { createFrameworkUserMessage } from "#harness/messages.js";
import { composeRuntimeBasePrompt } from "#runtime/prompt/compose.js";
import type { PreparedRuntimeTool } from "#runtime/sessions/turn.js";
@@ -35,7 +37,7 @@ interface RuntimeTurnAgentBase {
readonly availableSkills?: readonly AvailableSkillDescription[];
readonly id: string;
readonly instructions: readonly string[];
- readonly initialMessages?: readonly ModelMessage[];
+ readonly initialMessages?: readonly HarnessModelMessage[];
/**
* Optional model used only for compaction summaries.
*
@@ -107,7 +109,7 @@ export function createResolvedRuntimeTurnAgent(input: {
id,
initialMessages: agent.instructions
.filter((entry) => entry.role === "user" && entry.content.trim().length > 0)
- .map((entry) => ({ content: entry.content.trim(), role: "user" as const })),
+ .map((entry) => createFrameworkUserMessage("context.instruction", entry.content.trim())),
instructions: composeRuntimeBasePrompt({
connections: agent.connections,
instructions: agent.instructions,
diff --git a/packages/eve/src/shared/memory-state.test.ts b/packages/eve/src/shared/memory-state.test.ts
index 86736bb14..ac779799a 100644
--- a/packages/eve/src/shared/memory-state.test.ts
+++ b/packages/eve/src/shared/memory-state.test.ts
@@ -137,9 +137,9 @@ describe("memory record state", () => {
expect(
projectMemoryHistory({ locks: readMemoryLocks(second.state), messages: second.history }),
).toEqual([
- { content: "first note", role: "user" },
- { content: "new profile", role: "user" },
- { content: "second note", role: "user" },
+ { content: "first note", kind: "memory.load", role: "user" },
+ { content: "new profile", kind: "memory.load", role: "user" },
+ { content: "second note", kind: "memory.load", role: "user" },
]);
});
@@ -171,7 +171,7 @@ describe("memory record state", () => {
locks: { profile: lock("user_2", "session") },
messages: sessionVisible.history,
}),
- ).toEqual([{ content: "sticky", role: "user" }]);
+ ).toEqual([{ content: "sticky", kind: "memory.load", role: "user" }]);
});
it("canonicalizes private records independently", () => {
diff --git a/packages/eve/src/shared/memory-state.ts b/packages/eve/src/shared/memory-state.ts
index 133309dc0..6c53e30ce 100644
--- a/packages/eve/src/shared/memory-state.ts
+++ b/packages/eve/src/shared/memory-state.ts
@@ -3,6 +3,7 @@ import { createHash } from "node:crypto";
import type { ModelMessage } from "ai";
import type { LockedMemorySlot } from "#context/keys.js";
+import { createFrameworkUserMessage } from "#harness/messages.js";
import type { SessionStateMap } from "#harness/types.js";
import { identityHistoryViewProjector } from "#shared/history-view.js";
import type {
@@ -342,14 +343,9 @@ function attributeMemoryRecord(
content: string,
attribution: MemoryRecordAttribution,
): ModelMessage {
- const message: Extract<ModelMessage, { readonly role: "user" }> & {
- readonly metadata: Record<string, unknown>;
- } = {
- content,
- metadata: { [MEMORY_MESSAGE_METADATA_KEY]: attribution },
- role: "user",
- };
- return message;
+ return createFrameworkUserMessage("memory.load", content, {
+ [MEMORY_MESSAGE_METADATA_KEY]: attribution,
+ });
}
function readMemoryRecordAttribution(message: unknown): MemoryRecordAttribution | null {
diff --git a/packages/eve/src/tasks/delivery-context.test.ts b/packages/eve/src/tasks/delivery-context.test.ts
index 4fc59da5a..9ecc5f65d 100644
--- a/packages/eve/src/tasks/delivery-context.test.ts
+++ b/packages/eve/src/tasks/delivery-context.test.ts
@@ -3,6 +3,8 @@ import { describe, expect, it } from "vitest";
import type { SessionStateMap } from "#harness/types.js";
import { EMPTY_DELIVERY_SENTINEL } from "#shared/empty-delivery.js";
import {
+ getBackgroundTaskDelivery,
+ markBackgroundTaskStepInput,
resolveInitiatingTaskContext,
resolveTaskDeliveryContext,
TASK_DELIVERY_CONTEXT_LABEL,
@@ -43,6 +45,31 @@ describe("task delivery instructions", () => {
});
});
+describe("getBackgroundTaskDelivery", () => {
+ it("recognizes task-owned deliveries independently of their payload", () => {
+ expect(
+ getBackgroundTaskDelivery({
+ kind: "deliver",
+ payloads: [{ message: "Background task task_1 completed." }],
+ taskDeliveryId: "task_1:ready:completed",
+ }),
+ ).toMatchObject({ taskDeliveryId: "task_1:ready:completed" });
+ expect(getBackgroundTaskDelivery({ kind: "deliver", payloads: [{ message: "Hello." }] })).toBe(
+ undefined,
+ );
+ });
+
+ it("marks task-produced input before delivery results are coalesced", () => {
+ expect(markBackgroundTaskStepInput({ message: "Task completed." })).toMatchObject({
+ frameworkMessageKind: "execution.background_task",
+ message: "Task completed.",
+ });
+ expect(markBackgroundTaskStepInput({ context: ["Task state"] })).toEqual({
+ context: ["Task state"],
+ });
+ });
+});
+
describe("resolveInitiatingTaskContext", () => {
it("projects the active turn's accepted background tasks as initiating", () => {
expect(
diff --git a/packages/eve/src/tasks/delivery-context.ts b/packages/eve/src/tasks/delivery-context.ts
index 42f16a7b0..92f6280bc 100644
--- a/packages/eve/src/tasks/delivery-context.ts
+++ b/packages/eve/src/tasks/delivery-context.ts
@@ -1,4 +1,6 @@
-import type { SessionStateMap } from "#harness/types.js";
+import type { DeliverHookPayload } from "#channel/types.js";
+import { markFrameworkStepInput } from "#harness/messages.js";
+import type { SessionStateMap, StepInput } from "#harness/types.js";
import { EMPTY_DELIVERY_SENTINEL } from "#shared/empty-delivery.js";
import { getSessionTaskIndex, type SessionTaskIndexEntry } from "#tasks/session-index.js";
@@ -11,6 +13,26 @@ Continue carrying out the user's request, including starting any remaining backg
export const TASK_DELIVERY_SETTLED_INSTRUCTION = `Background task reporting\nThis turn was triggered by background task activity. The accompanying ${TASK_DELIVERY_CONTEXT_LABEL} message is runtime-authored and lists tasks started by the same parent turn, all settled, with every available terminal output. Do not reply with ${EMPTY_DELIVERY_SENTINEL}. Send one user-facing response that combines their useful results.`;
+type BackgroundTaskDelivery = DeliverHookPayload & {
+ readonly taskDeliveryId: string;
+};
+
+/** Returns task delivery provenance when a child task wakes its parent. */
+export function getBackgroundTaskDelivery(input: unknown): BackgroundTaskDelivery | undefined {
+ if (typeof input !== "object" || input === null) return undefined;
+ const delivery = input as { readonly kind?: unknown; readonly taskDeliveryId?: unknown };
+ return delivery.kind === "deliver" && typeof delivery.taskDeliveryId === "string"
+ ? (input as BackgroundTaskDelivery)
+ : undefined;
+}
+
+/** Marks a task-produced user message before the harness coalesces delivery results. */
+export function markBackgroundTaskStepInput(input: StepInput): StepInput {
+ return input.message === undefined
+ ? input
+ : markFrameworkStepInput(input, "execution.background_task");
+}
+
/** Returns model context and cohort phase for tasks started by the same parent turn as this delivery. */
export function resolveTaskDeliveryContext(input: {
readonly state: SessionStateMap | undefined;
diff --git a/packages/eve/src/tracing/agent-otel-content.test.ts b/packages/eve/src/tracing/agent-otel-content.test.ts
index b81c3a695..39fef6f70 100644
--- a/packages/eve/src/tracing/agent-otel-content.test.ts
+++ b/packages/eve/src/tracing/agent-otel-content.test.ts
@@ -1,5 +1,6 @@
import { describe, expect, it } from "vitest";
+import type { FrameworkMessageKind } from "#harness/messages.js";
import {
CONTENT_ATTRIBUTE_LIMIT,
genAiInputMessagesAttribute,
@@ -8,11 +9,50 @@ import {
toolResultsContentAttribute,
} from "#tracing/agent-otel-content.js";
+const FRAMEWORK_MESSAGE_KINDS = [
+ "context.instruction",
+ "context.state",
+ "context.compaction",
+ "memory.load",
+ "execution.background_task",
+ "execution.continuation",
+ "execution.retry",
+] as const satisfies readonly FrameworkMessageKind[];
+
describe("GenAI message attributes", () => {
+ it("preserves every user-message kind in the GenAI input attribute", () => {
+ expect(
+ genAiInputMessagesAttribute([
+ { content: "A real user message.", kind: "user", role: "user" },
+ {
+ content: "A background task completed.",
+ kind: "execution.background_task",
+ role: "user",
+ },
+ ]),
+ ).toBe(
+ '[{"kind":"user","parts":[{"content":"A real user message.","type":"text"}],"role":"user"},{"kind":"execution.background_task","parts":[{"content":"A background task completed.","type":"text"}],"role":"user"}]',
+ );
+ });
+
+ it.each(FRAMEWORK_MESSAGE_KINDS)("preserves %s in the GenAI input attribute", (kind) => {
+ const attribute = genAiInputMessagesAttribute([
+ { content: "Framework message.", kind, role: "user" },
+ ]);
+
+ expect(JSON.parse(attribute!)).toEqual([
+ {
+ kind,
+ parts: [{ content: "Framework message.", type: "text" }],
+ role: "user",
+ },
+ ]);
+ });
+
it("formats model input, output, and system instructions for inspectors", () => {
expect(
genAiInputMessagesAttribute([
- { content: "hello", role: "user" },
+ { content: "hello", kind: "user", role: "user" },
{
content: [
{
@@ -26,7 +66,7 @@ describe("GenAI message attributes", () => {
},
]),
).toBe(
- '[{"parts":[{"content":"hello","type":"text"}],"role":"user"},{"parts":[{"arguments":{"message":"echo"},"id":"call-1","name":"delegate","type":"tool_call"}],"role":"assistant"}]',
+ '[{"kind":"user","parts":[{"content":"hello","type":"text"}],"role":"user"},{"parts":[{"arguments":{"message":"echo"},"id":"call-1","name":"delegate","type":"tool_call"}],"role":"assistant"}]',
);
expect(genAiSystemInstructionsAttribute("Be concise.")).toBe(
'[{"content":"Be concise.","type":"text"}]',
diff --git a/packages/eve/src/tracing/agent-otel-content.ts b/packages/eve/src/tracing/agent-otel-content.ts
index 9737f2c93..61fd6164f 100644
--- a/packages/eve/src/tracing/agent-otel-content.ts
+++ b/packages/eve/src/tracing/agent-otel-content.ts
@@ -1,3 +1,5 @@
+import { isUserMessageKind } from "#harness/messages.js";
+
/**
* Serializes model and tool payloads into span content attributes for the
* local trace viewer: prompt messages, the system prompt, responses, and
@@ -61,7 +63,12 @@ export function genAiInputMessagesAttribute(messages: unknown): string | undefin
return [];
}
const parts = semanticParts(message.content);
- return parts.length === 0 ? [] : [{ parts, role: message.role }];
+ if (parts.length === 0) return [];
+ const kind =
+ message.role === "user" && isUserMessageKind(message.kind) ? message.kind : undefined;
+ return [
+ kind === undefined ? { parts, role: message.role } : { kind, parts, role: message.role },
+ ];
});
for (let start = 0; start < formatted.length; start += 1) {
const json = semanticJsonAttribute(formatted.slice(start));