The Open Framework for Building Agents
feat(eve): expose effective model to dynamic resolvers (#2298)
prha2d0bad9cb9d0
diff --git a/.changeset/dynamic-resolver-effective-model.md b/.changeset/dynamic-resolver-effective-model.mdnew file mode 100644index 000000000..163e9652b--- /dev/null+++ b/.changeset/dynamic-resolver-effective-model.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Expose the effective model ID to model, subagent, tool, skill, and instruction resolvers through `ctx.model?.id`.diff --git a/docs/agent-config.md b/docs/agent-config.mdindex 841748617..d30e6e7db 100644--- a/docs/agent-config.md+++ b/docs/agent-config.md@@ -87,9 +87,9 @@ export default defineAgent({```Handlers receive the shared [dynamic resolver-context](./guides/dynamic-capabilities) (`ctx.session`, `ctx.channel`,-`ctx.messages`) and return a gateway model id, an AI SDK `LanguageModel`, a-selection object. Returning `null` or `undefined` fails the turn.+context](./guides/dynamic-capabilities) and return a gateway model id, an AI+SDK `LanguageModel`, or a selection object. Returning `null` or `undefined`+fails the turn.- **Scopes.** `session.started` (once per session), `turn.started` (once perturn), `step.started` (every model step). Precedence: step > turn >diff --git a/docs/guides/dynamic-capabilities.md b/docs/guides/dynamic-capabilities.mdindex 38e3646cd..bf2a779f0 100644--- a/docs/guides/dynamic-capabilities.md+++ b/docs/guides/dynamic-capabilities.md@@ -68,22 +68,34 @@ availability depends on the caller, tenant, environment, or a feature flag.Return the child definition to configure and expose it. Return `null` to omitit from the parent's model-visible tools.+The example below exposes a finance subagent to enterprise callers and gives+it the model that the parent would use at that point:+```ts title="agent/subagents/finance/agent.ts"import { defineAgent, defineDynamic } from "eve";export default defineDynamic({events: {- "session.started": (_event, ctx) =>- ctx.session.auth.current?.attributes.plan === "enterprise"- ? defineAgent({- description: "Analyze financial and accounting data.",- model: "openai/gpt-5.5",- })- : null,+ "session.started": (_event, ctx) => {+ if (ctx.session.auth.current?.attributes.plan !== "enterprise") {+ return null;+ }++ return defineAgent({+ description: "Analyze financial and accounting data.",+ model: ctx.model ? ctx.model.id : "openai/gpt-5.5-mini",+ });+ },},});```+`ctx.model` is the parent's effective model when the resolver runs. In this+example, this dynamic subagent uses the parent's effective model when it is+available falls back to `openai/gpt-5.5-mini` if the parent has not selected+one yet. The returned child config snapshots the model ID; a later parent+model change does not retarget the child.+eve always compiles the subagent's filesystem resources, including itsinstructions, tools, skills, connections, sandbox, and nested subagents. Itdoes not compile an agent config or placeholder model for a dynamic subagent.diff --git a/packages/eve/extension-contracts/compatibility/connection/v15.ts b/packages/eve/extension-contracts/compatibility/connection/v15.tsnew file mode 100644index 000000000..c9adb6c9f--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/connection/v15.ts@@ -0,0 +1,6 @@+import { defineMcpClientConnection } from "#public/connections/index.js";++export default defineMcpClientConnection({+ description: "Call-aware MCP service",+ url: "https://example.com/mcp",+});diff --git a/packages/eve/extension-contracts/compatibility/dynamicInstructions/v18.ts b/packages/eve/extension-contracts/compatibility/dynamicInstructions/v18.tsnew file mode 100644index 000000000..745446593--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/dynamicInstructions/v18.ts@@ -0,0 +1,8 @@+import { defineDynamic, defineInstructions } from "#public/instructions/index.js";++export default defineDynamic({+ events: {+ "session.started": (_event, ctx) =>+ defineInstructions({ markdown: `Use session ${ctx.session.id} for correlation.` }),+ },+});diff --git a/packages/eve/extension-contracts/compatibility/dynamicSkill/v17.ts b/packages/eve/extension-contracts/compatibility/dynamicSkill/v17.tsnew file mode 100644index 000000000..bd9ab80cf--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/dynamicSkill/v17.ts@@ -0,0 +1,11 @@+import { defineDynamic, defineSkill } from "#public/skills/index.js";++export default defineDynamic({+ events: {+ "turn.started": (_event, ctx) =>+ defineSkill({+ description: `Review session ${ctx.session.id}.`,+ markdown: "# Review\n\nCheck each claim.",+ }),+ },+});diff --git a/packages/eve/extension-contracts/compatibility/dynamicTool/v34.ts b/packages/eve/extension-contracts/compatibility/dynamicTool/v34.tsnew file mode 100644index 000000000..0552088f0--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/dynamicTool/v34.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/subagent/v13.ts b/packages/eve/extension-contracts/compatibility/subagent/v13.tsnew file mode 100644index 000000000..efc10e123--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/subagent/v13.ts@@ -0,0 +1,6 @@+import { defineWorkspaceAgent } from "#public/index.js";++/** Epoch 13 added name-addressed workspace agents. */+export default defineWorkspaceAgent({+ name: "research",+});diff --git a/packages/eve/extension-contracts/reports/connection/v16.json b/packages/eve/extension-contracts/reports/connection/v16.jsonnew file mode 100644index 000000000..80a19106b--- /dev/null+++ b/packages/eve/extension-contracts/reports/connection/v16.json@@ -0,0 +1,16 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "connection",+ "epoch": 16,+ "sha256": "8c9dbcd7dac1182636e20b51c2d13c594cd98d14b0425148acd8221727198c76",+ "exports": [+ "ConnectionAuthorizationFailedError",+ "ConnectionAuthorizationRequiredError",+ "defineDynamic",+ "defineInteractiveAuthorization",+ "defineMcpClientConnection",+ "defineOpenAPIConnection",+ "isConnectionAuthorizationFailedError",+ "isConnectionAuthorizationRequiredError"+ ]+}diff --git a/packages/eve/extension-contracts/reports/dynamicInstructions/v19.json b/packages/eve/extension-contracts/reports/dynamicInstructions/v19.jsonnew file mode 100644index 000000000..343081c24--- /dev/null+++ b/packages/eve/extension-contracts/reports/dynamicInstructions/v19.json@@ -0,0 +1,7 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "dynamicInstructions",+ "epoch": 19,+ "sha256": "f750e62e4b67a3566097f6b668ec2ab6751da8aa51e4b8d2d6a7d4727f432bf5",+ "exports": ["defineDynamic"]+}diff --git a/packages/eve/extension-contracts/reports/dynamicSkill/v18.json b/packages/eve/extension-contracts/reports/dynamicSkill/v18.jsonnew file mode 100644index 000000000..a44509ad2--- /dev/null+++ b/packages/eve/extension-contracts/reports/dynamicSkill/v18.json@@ -0,0 +1,7 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "dynamicSkill",+ "epoch": 18,+ "sha256": "a7b159d3e152ef44b541764692932569caf38b4266a632429547f6f7ad350710",+ "exports": ["defineDynamic"]+}diff --git a/packages/eve/extension-contracts/reports/dynamicTool/v35.json b/packages/eve/extension-contracts/reports/dynamicTool/v35.jsonnew file mode 100644index 000000000..7844c7288--- /dev/null+++ b/packages/eve/extension-contracts/reports/dynamicTool/v35.json@@ -0,0 +1,14 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "dynamicTool",+ "epoch": 35,+ "sha256": "80be0e75a6e287f3c2235fbec34f393ad3fb792724f138313837260edbe1e1b3",+ "exports": [+ "DynamicToolEntry",+ "DynamicToolEvents",+ "DynamicToolResult",+ "DynamicToolSet",+ "defineDurableCallback",+ "defineDynamic"+ ]+}diff --git a/packages/eve/extension-contracts/reports/subagent/v14.json b/packages/eve/extension-contracts/reports/subagent/v14.jsonnew file mode 100644index 000000000..7916737dc--- /dev/null+++ b/packages/eve/extension-contracts/reports/subagent/v14.json@@ -0,0 +1,23 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "subagent",+ "epoch": 14,+ "sha256": "642bee82c6d3a84a1dce67016865194f78ef2ac665ecbfc51744c6568a3e38a7",+ "exports": [+ "AgentCompactionDefinition",+ "AgentDefinition",+ "AgentModelDefinition",+ "AgentStaticModelDefinition",+ "DefinedAgent",+ "DynamicLocalSubagentDefinition",+ "DynamicSubagentDefinition",+ "RemoteAgentDefinition",+ "RemoteAgentDefinitionInput",+ "WorkspaceAgentDefinition",+ "WorkspaceAgentTransport",+ "defineAgent",+ "defineDynamic",+ "defineRemoteAgent",+ "defineWorkspaceAgent"+ ]+}diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.tsindex 44bb87e44..c1a3ece89 100644--- a/packages/eve/src/compiler/extension-compatibility.ts+++ b/packages/eve/src/compiler/extension-compatibility.ts@@ -43,10 +43,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},dynamicTool: {- current: 34,+ current: 35,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, 34,+ 33, 34, 35,],dropped: {21: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",@@ -72,8 +72,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},subagent: {- current: 13,- supported: [3, 4, 6, 7, 8, 9, 10, 11, 12, 13],+ current: 14,+ supported: [3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14],dropped: {1: "Persistent subagent sessions are now the default and the experimental opt-in was removed",2: "Persistent subagent sessions are now the default and the experimental opt-in was removed",@@ -81,8 +81,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},connection: {- current: 15,- supported: [1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15],+ current: 16,+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 16],dropped: {9: "Dynamic connection resolvers no longer receive conversation or channel continuation data",10: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",@@ -106,16 +106,16 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},skill: { current: 1, supported: [1], dropped: {} },dynamicSkill: {- current: 17,- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 15, 16, 17],+ current: 18,+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 15, 16, 17, 18],dropped: {13: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",},},instructions: { current: 2, supported: [1, 2], dropped: {} },dynamicInstructions: {- current: 18,- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 15, 16, 17, 18],+ current: 19,+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 15, 16, 17, 18, 19],dropped: {14: "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.tsindex 87d2cc6b6..d42a9a3c8 100644--- a/packages/eve/src/context/dynamic-instruction-lifecycle.test.ts+++ b/packages/eve/src/context/dynamic-instruction-lifecycle.test.ts@@ -17,6 +17,7 @@ const {import { ContextContainer } from "#context/container.js";import {+ StaticModelReferenceKey,SessionDynamicInstructionsKey,TurnDynamicInstructionsKey,SessionIdKey,@@ -46,6 +47,7 @@ function createResolver(function createCtx(): ContextContainer {const ctx = new ContextContainer();+ ctx.set(StaticModelReferenceKey, { id: "openai/gpt-5.5" });ctx.set(SessionIdKey, "test-session");return ctx;}diff --git a/packages/eve/src/context/dynamic-model-lifecycle.test.ts b/packages/eve/src/context/dynamic-model-lifecycle.test.tsindex 3e908f02f..500c4aa04 100644--- a/packages/eve/src/context/dynamic-model-lifecycle.test.ts+++ b/packages/eve/src/context/dynamic-model-lifecycle.test.ts@@ -4,11 +4,10 @@ import { afterEach, describe, expect, it, vi } from "vitest";import { ROOT_COMPILED_AGENT_NODE_ID } from "#compiler/manifest.js";import type { CompiledModuleMap } from "#compiler/module-map.js";import { ContextContainer } from "#context/container.js";+import { dispatchDynamicModelEvent } from "#context/dynamic-model-lifecycle.js";+import { getEffectiveModelSelection } from "#context/effective-model.js";import {- dispatchDynamicModelEvent,- getActiveDynamicModelSelection,-} from "#context/dynamic-model-lifecycle.js";-import {+ StaticModelReferenceKey,LiveStepDynamicModelSelectionKey,SessionDynamicModelReferenceKey,TurnDynamicModelReferenceKey,@@ -22,6 +21,8 @@ import {} from "#protocol/message.js";import type { RuntimeDynamicModelReference } from "#runtime/agent/bootstrap.js";+const FALLBACK = { id: "openai/gpt-5.5" } as const;+const DYNAMIC_MODEL_SOURCE: RuntimeDynamicModelReference = {eventNames: ["session.started", "turn.started", "step.started"],logicalPath: "agent.ts",@@ -35,7 +36,7 @@ afterEach(() => {describe("dynamic model lifecycle", () => {it("persists session-scoped model references", async () => {- const ctx = new ContextContainer();+ const ctx = createCtx();const moduleMap = createModuleMap({default: {model: defineDynamic({@@ -57,7 +58,7 @@ describe("dynamic model lifecycle", () => {scope: { moduleMap, nodeId: undefined },});- expect(getActiveDynamicModelSelection(ctx)).toEqual({+ expect(getEffectiveModelSelection(ctx)).toEqual({reference: {contextWindowTokens: 128_000,id: "openai/gpt-5.5-mini",@@ -65,10 +66,11 @@ describe("dynamic model lifecycle", () => {providerOptions: undefined,},});+ expect(ctx.get(StaticModelReferenceKey)?.id).toBe(FALLBACK.id);});it("prefers step, then turn, then session selections", () => {- const ctx = new ContextContainer();+ const ctx = createCtx();ctx.set(SessionDynamicModelReferenceKey, {contextWindowTokens: 100_000,id: "openai/session",@@ -78,16 +80,48 @@ describe("dynamic model lifecycle", () => {id: "openai/turn",});- expect(getActiveDynamicModelSelection(ctx)?.reference.id).toBe("openai/turn");+ expect(getEffectiveModelSelection(ctx)?.reference.id).toBe("openai/turn");ctx.setVirtualContext(LiveStepDynamicModelSelectionKey, {reference: { contextWindowTokens: 100_000, id: "openai/step" },});- expect(getActiveDynamicModelSelection(ctx)?.reference.id).toBe("openai/step");+ expect(getEffectiveModelSelection(ctx)?.reference.id).toBe("openai/step");+ });++ it("exposes the lower-precedence model to a resolver", async () => {+ const ctx = createCtx();+ ctx.set(SessionDynamicModelReferenceKey, { id: "openai/session" });+ ctx.set(TurnDynamicModelReferenceKey, { id: "openai/previous-turn" });+ const observed: Array<string | undefined> = [];+ const moduleMap = createModuleMap({+ default: {+ model: defineDynamic({+ events: {+ "turn.started": (_event, resolveCtx) => {+ observed.push(resolveCtx.model?.id);+ return {+ model: "openai/next-turn",+ modelContextWindowTokens: 100_000,+ };+ },+ },+ }),+ },+ });++ await dispatchDynamicModelEvent({+ ctx,+ dynamicModel: DYNAMIC_MODEL_SOURCE,+ event: createTurnStartedEvent({ sequence: 0, turnId: "turn_0" }),+ messages: [],+ scope: { moduleMap, nodeId: undefined },+ });++ expect(observed).toEqual(["openai/session"]);});it("replaces turn-scoped selections on each matching turn", async () => {- const ctx = new ContextContainer();+ const ctx = createCtx();let turnModel = "openai/first-turn";const moduleMap = createModuleMap({default: {@@ -112,16 +146,16 @@ describe("dynamic model lifecycle", () => {});await dispatch(0);- expect(getActiveDynamicModelSelection(ctx)?.reference.id).toBe("openai/first-turn");+ expect(getEffectiveModelSelection(ctx)?.reference.id).toBe("openai/first-turn");turnModel = "openai/second-turn";await dispatch(1);- expect(getActiveDynamicModelSelection(ctx)?.reference.id).toBe("openai/second-turn");+ expect(getEffectiveModelSelection(ctx)?.reference.id).toBe("openai/second-turn");});it("keeps step-scoped live provider instances outside mock mode", async () => {vi.stubEnv("NODE_ENV", "production");- const ctx = new ContextContainer();+ const ctx = createCtx();const stepModel = createLanguageModel("openai.responses", "gpt-step");const moduleMap = createModuleMap({default: {@@ -149,7 +183,7 @@ describe("dynamic model lifecycle", () => {scope: { moduleMap, nodeId: undefined },});- expect(getActiveDynamicModelSelection(ctx)).toEqual({+ expect(getEffectiveModelSelection(ctx)).toEqual({model: stepModel,reference: {contextWindowTokens: 64_000,@@ -161,7 +195,7 @@ describe("dynamic model lifecycle", () => {});it("strips step-scoped live provider instances in mock mode", async () => {- const ctx = new ContextContainer();+ const ctx = createCtx();const stepModel = createLanguageModel("openai.responses", "gpt-step");const moduleMap = createModuleMap({default: {@@ -189,7 +223,7 @@ describe("dynamic model lifecycle", () => {scope: { moduleMap, nodeId: undefined },});- expect(getActiveDynamicModelSelection(ctx)).toEqual({+ expect(getEffectiveModelSelection(ctx)).toEqual({reference: {contextWindowTokens: 64_000,id: "openai/gpt-step",@@ -208,6 +242,7 @@ describe("dynamic model lifecycle", () => {vi.stubEnv("NODE_ENV", nodeEnv);vi.stubEnv("EVE_MOCK_AUTHORED_MODELS", mockAuthored);const ctx = new ContextContainer();+ ctx.set(StaticModelReferenceKey, null);const stepModel = mockModel({modelId: "scripted-dispatcher",provider: "custom-fixture",@@ -239,7 +274,7 @@ describe("dynamic model lifecycle", () => {scope: { moduleMap, nodeId: undefined },});- const selected = getActiveDynamicModelSelection(ctx);+ const selected = getEffectiveModelSelection(ctx);expect(selected?.model).toBe(stepModel);expect(selected?.reference.id).toBe("custom-fixture/scripted-dispatcher");if (selected?.model === undefined) throw new Error("Expected the explicit mock model.");@@ -252,7 +287,7 @@ describe("dynamic model lifecycle", () => {);it("rejects live provider instances at durable scopes", async () => {- const ctx = new ContextContainer();+ const ctx = createCtx();const liveModel = createLanguageModel("openai.responses", "gpt-live");const moduleMap = createModuleMap({default: {@@ -281,7 +316,7 @@ describe("dynamic model lifecycle", () => {});it("propagates resolver exceptions without selecting a fallback", async () => {- const ctx = new ContextContainer();+ const ctx = createCtx();ctx.set(TurnDynamicModelReferenceKey, {contextWindowTokens: 100_000,id: "openai/previous-turn",@@ -309,11 +344,11 @@ describe("dynamic model lifecycle", () => {).rejects.toThrow("flag service unavailable");expect(ctx.get(TurnDynamicModelReferenceKey)).toBeNull();- expect(getActiveDynamicModelSelection(ctx)).toBeNull();+ expect(getEffectiveModelSelection(ctx)?.reference).toEqual(FALLBACK);});it("rejects null and malformed selections", async () => {- const ctx = new ContextContainer();+ const ctx = createCtx();let result: unknown = null;const moduleMap = createModuleMap({default: {@@ -344,6 +379,12 @@ describe("dynamic model lifecycle", () => {});});+function createCtx(): ContextContainer {+ const ctx = new ContextContainer();+ ctx.set(StaticModelReferenceKey, FALLBACK);+ return ctx;+}+function createModuleMap(moduleNamespace: Record<string, unknown>): CompiledModuleMap {return {nodes: {diff --git a/packages/eve/src/context/dynamic-model-lifecycle.ts b/packages/eve/src/context/dynamic-model-lifecycle.tsindex 67585cd4d..3c5fe42cc 100644--- a/packages/eve/src/context/dynamic-model-lifecycle.ts+++ b/packages/eve/src/context/dynamic-model-lifecycle.ts@@ -8,7 +8,6 @@ import {LiveStepDynamicModelSelectionKey,SessionDynamicModelReferenceKey,TurnDynamicModelReferenceKey,- type LiveDynamicModelSelection,} from "#context/keys.js";import type { UnstampedMessageStreamEvent } from "#protocol/message.js";import type {@@ -31,8 +30,6 @@ const ALLOWED_DYNAMIC_MODEL_EVENTS = new Set<DynamicToolEventName>(["step.started",]);-export type ActiveDynamicModelSelection = LiveDynamicModelSelection;-const DYNAMIC_MODEL_SELECTION_ERROR_CODE = "EVE_DYNAMIC_MODEL_SELECTION_FAILED";export class DynamicModelSelectionError extends Error {@@ -70,27 +67,6 @@ function durableKeyForEvent(}}-export function getActiveDynamicModelSelection(ctx: {- get<T>(key: ContextKey<T>): T | undefined;-}): ActiveDynamicModelSelection | null {- const step = ctx.get(LiveStepDynamicModelSelectionKey);- if (step !== undefined && step !== null) {- return step;- }-- const turn = ctx.get(TurnDynamicModelReferenceKey);- if (turn !== undefined && turn !== null) {- return { reference: turn };- }-- const session = ctx.get(SessionDynamicModelReferenceKey);- if (session !== undefined && session !== null) {- return { reference: session };- }-- return null;-}-export async function dispatchDynamicModelEvent(input: {readonly ctx: AlsContext;readonly dynamicModel: RuntimeDynamicModelReference | undefined;diff --git a/packages/eve/src/context/dynamic-resolve-context.test.ts b/packages/eve/src/context/dynamic-resolve-context.test.tsindex 2b846335a..fb2469f6d 100644--- a/packages/eve/src/context/dynamic-resolve-context.test.ts+++ b/packages/eve/src/context/dynamic-resolve-context.test.ts@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";import { ContextContainer } from "#context/container.js";import {+ StaticModelReferenceKey,AuthKey,ChannelInstrumentationKey,ContinuationTokenKey,@@ -13,6 +14,7 @@ import { buildResolveContext } from "#context/dynamic-resolve-context.js";function createCtx(): ContextContainer {const ctx = new ContextContainer();+ ctx.set(StaticModelReferenceKey, { id: "openai/gpt-5.5" });ctx.set(SessionIdKey, "sess-1");ctx.set(AuthKey, null);ctx.set(InitiatorAuthKey, null);@@ -21,6 +23,19 @@ function createCtx(): ContextContainer {}describe("buildResolveContext", () => {+ it("includes the active agent model", () => {+ const resolveCtx = buildResolveContext(createCtx(), []);++ expect(resolveCtx.model).toEqual({ id: "openai/gpt-5.5" });+ });++ it("includes null before a model is selected", () => {+ const ctx = createCtx();+ ctx.set(StaticModelReferenceKey, null);++ expect(buildResolveContext(ctx, []).model).toBeNull();+ });+it("includes channel metadata from ChannelInstrumentationKey", () => {const ctx = createCtx();ctx.set(ChannelKey, { kind: "http" });@@ -49,6 +64,7 @@ describe("buildResolveContext", () => {it("omits continuation token for an ID-only session", () => {const ctx = new ContextContainer();+ ctx.set(StaticModelReferenceKey, { id: "openai/gpt-5.5" });ctx.set(SessionIdKey, "sess-1");ctx.set(AuthKey, null);ctx.set(InitiatorAuthKey, null);diff --git a/packages/eve/src/context/dynamic-resolve-context.ts b/packages/eve/src/context/dynamic-resolve-context.tsindex 732213866..44f28d038 100644--- a/packages/eve/src/context/dynamic-resolve-context.ts+++ b/packages/eve/src/context/dynamic-resolve-context.ts@@ -2,6 +2,7 @@ import type { ModelMessage } from "ai";import type { DynamicResolveContext } from "#dynamic/definition.js";import type { AlsContext } from "#context/container.js";+import { getEffectiveModelSelection } from "#context/effective-model.js";import {AuthKey,ChannelInstrumentationKey,@@ -30,8 +31,10 @@ export function buildResolveContext(const channelAdapter = ctx.get(ChannelKey);const continuationToken = ctx.get(ContinuationTokenKey);const channelInstrumentation = ctx.get(ChannelInstrumentationKey);+ const effectiveModel = getEffectiveModelSelection(ctx);return {+ model: effectiveModel === null ? null : { id: effectiveModel.reference.id },session: {id: sessionId,auth: {diff --git a/packages/eve/src/context/dynamic-skill-lifecycle.test.ts b/packages/eve/src/context/dynamic-skill-lifecycle.test.tsindex 7c7b938e5..045018cd9 100644--- a/packages/eve/src/context/dynamic-skill-lifecycle.test.ts+++ b/packages/eve/src/context/dynamic-skill-lifecycle.test.ts@@ -5,7 +5,12 @@ import {PendingSkillAnnouncementKey,dispatchDynamicSkillEvent,} from "#context/dynamic-skill-lifecycle.js";-import { DynamicSkillManifestKey, SessionIdKey, SandboxKey } from "#context/keys.js";+import {+ StaticModelReferenceKey,+ DynamicSkillManifestKey,+ SessionIdKey,+ SandboxKey,+} from "#context/keys.js";import { mockSandbox } from "#internal/testing/mocks/mock-sandbox.js";import type { UnstampedMessageStreamEvent } from "#protocol/message.js";import { defineSkill } from "#public/definitions/skill.js";@@ -40,6 +45,7 @@ function createCtx(authoredSkillNames: readonly string[] = []) {[HOME_PROBE_COMMAND]: { exitCode: 0, stderr: "", stdout: "/home/agent\n" },},});+ ctx.set(StaticModelReferenceKey, { id: "openai/gpt-5.5" });ctx.set(SessionIdKey, "test-session");ctx.set(SandboxKey, sandbox.access);ctx.set(BundleKey, createMockBundle(authoredSkillNames));diff --git a/packages/eve/src/context/dynamic-subagent-lifecycle.test.ts b/packages/eve/src/context/dynamic-subagent-lifecycle.test.tsindex a402b3942..98b47f3cc 100644--- a/packages/eve/src/context/dynamic-subagent-lifecycle.test.ts+++ b/packages/eve/src/context/dynamic-subagent-lifecycle.test.ts@@ -7,7 +7,11 @@ import {getDynamicSubagentSelection,refreshDynamicSessionSubagentsForRuntimeRevision,} from "#context/dynamic-subagent-lifecycle.js";-import { SessionDynamicSubagentRuntimeRevisionKey, SessionIdKey } from "#context/keys.js";+import {+ StaticModelReferenceKey,+ SessionDynamicSubagentRuntimeRevisionKey,+ SessionIdKey,+} from "#context/keys.js";import { defineAgent } from "#public/definitions/agent.js";import { defineRemoteAgent } from "#public/definitions/remote-agent.js";import { createSessionStartedEvent, createTurnStartedEvent } from "#protocol/message.js";@@ -29,6 +33,28 @@ describe("dynamic subagent lifecycle", () => {expect(getDynamicSubagentSelection(ctx, resolver.nodeId)).toBeUndefined();});+ it("exposes the active agent model to a resolver", async () => {+ const ctx = createContext();+ const created = createResolver();+ const handler = vi.fn((_model: { readonly id: string }) => created.agentConfig);+ const resolver: ResolvedDynamicSubagentResolver = {+ ...created.resolver,+ events: {+ "session.started": (_event, resolveCtx) =>+ handler((resolveCtx as { model: { id: string } }).model),+ },+ };++ await dispatchDynamicSubagentEvent({+ ctx,+ event: createSessionStartedEvent(),+ messages: [],+ resolvers: [resolver],+ });++ expect(handler).toHaveBeenCalledWith({ id: "openai/gpt-root" });+ });+it("exposes a subagent with the returned agent config", async () => {const ctx = createContext();const created = createResolver();@@ -345,6 +371,7 @@ describe("dynamic subagent lifecycle", () => {function createContext(): ContextContainer {const ctx = new ContextContainer();+ ctx.set(StaticModelReferenceKey, { id: "openai/gpt-root" });ctx.set(SessionIdKey, "session-1");return ctx;}diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts b/packages/eve/src/context/dynamic-tool-lifecycle.test.tsindex adabda248..3e542d2e6 100644--- a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts+++ b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts@@ -40,6 +40,7 @@ const { buildDynamicTools, buildResponseAuthorizationTools } =import { ContextContainer } from "#context/container.js";import { deserializeContext, serializeContext } from "#context/serialize.js";import {+ StaticModelReferenceKey,SessionIdKey,SessionDynamicToolMetadataKey,SessionDynamicToolRuntimeRevisionKey,@@ -403,6 +404,7 @@ function createResolver(let contextCounter = 0;function createCtx(sessionId = `test-session-${++contextCounter}`): ContextContainer {const ctx = new ContextContainer();+ ctx.set(StaticModelReferenceKey, null);ctx.set(SessionIdKey, sessionId);return ctx;}diff --git a/packages/eve/src/context/effective-model.test.ts b/packages/eve/src/context/effective-model.test.tsnew file mode 100644index 000000000..e50b10903--- /dev/null+++ b/packages/eve/src/context/effective-model.test.ts@@ -0,0 +1,45 @@+import { describe, expect, it } from "vitest";++import { ContextContainer } from "#context/container.js";+import { getEffectiveModelSelection } from "#context/effective-model.js";+import {+ LiveStepDynamicModelSelectionKey,+ SessionDynamicModelReferenceKey,+ StaticModelReferenceKey,+ TurnDynamicModelReferenceKey,+} from "#context/keys.js";++const STATIC_MODEL = { id: "openai/static" } as const;++describe("getEffectiveModelSelection", () => {+ it("uses step, turn, session, then static precedence", () => {+ const ctx = new ContextContainer();+ ctx.setVirtualContext(StaticModelReferenceKey, STATIC_MODEL);++ expect(getEffectiveModelSelection(ctx)?.reference.id).toBe("openai/static");++ ctx.set(SessionDynamicModelReferenceKey, { id: "openai/session" });+ expect(getEffectiveModelSelection(ctx)?.reference.id).toBe("openai/session");++ ctx.set(TurnDynamicModelReferenceKey, { id: "openai/turn" });+ expect(getEffectiveModelSelection(ctx)?.reference.id).toBe("openai/turn");++ ctx.setVirtualContext(LiveStepDynamicModelSelectionKey, {+ reference: { id: "openai/step" },+ });+ expect(getEffectiveModelSelection(ctx)?.reference.id).toBe("openai/step");+ });++ it("returns null for a dynamic-only agent without a selection", () => {+ const ctx = new ContextContainer();+ ctx.setVirtualContext(StaticModelReferenceKey, null);++ expect(getEffectiveModelSelection(ctx)).toBeNull();+ });++ it("fails when static model state was not initialized", () => {+ expect(() => getEffectiveModelSelection(new ContextContainer())).toThrow(+ "Effective model resolution requires initialized static model state.",+ );+ });+});diff --git a/packages/eve/src/context/effective-model.ts b/packages/eve/src/context/effective-model.tsnew file mode 100644index 000000000..b36738c87--- /dev/null+++ b/packages/eve/src/context/effective-model.ts@@ -0,0 +1,27 @@+import type { ContextKey } from "#context/key.js";+import {+ LiveStepDynamicModelSelectionKey,+ SessionDynamicModelReferenceKey,+ StaticModelReferenceKey,+ TurnDynamicModelReferenceKey,+ type LiveDynamicModelSelection,+} from "#context/keys.js";++export function getEffectiveModelSelection(ctx: {+ get<T>(key: ContextKey<T>): T | undefined;+}): LiveDynamicModelSelection | null {+ const step = ctx.get(LiveStepDynamicModelSelectionKey);+ if (step !== undefined && step !== null) return step;++ const turn = ctx.get(TurnDynamicModelReferenceKey);+ if (turn !== undefined && turn !== null) return { reference: turn };++ const session = ctx.get(SessionDynamicModelReferenceKey);+ if (session !== undefined && session !== null) return { reference: session };++ const staticModel = ctx.get(StaticModelReferenceKey);+ if (staticModel === undefined) {+ throw new Error("Effective model resolution requires initialized static model state.");+ }+ return staticModel === null ? null : { reference: staticModel };+}diff --git a/packages/eve/src/context/keys.ts b/packages/eve/src/context/keys.tsindex 81c9d986d..ebed3897f 100644--- a/packages/eve/src/context/keys.ts+++ b/packages/eve/src/context/keys.ts@@ -163,6 +163,11 @@ export const HandleEventKey = new ContextKey<HandleEventFn>("eve.internal.handle// Dynamic model keys// ---------------------------------------------------------------------------+/** Static model configured for the effective turn agent, or `null` for a dynamic-only agent. */+export const StaticModelReferenceKey = new ContextKey<RuntimeModelReference | null>(+ "eve.staticModelReference",+);+/** Session-scoped dynamic model selection (from `session.started`). */export const SessionDynamicModelReferenceKey = new ContextKey<RuntimeModelReference | null>("eve.sessionDynamicModelReference",diff --git a/packages/eve/src/context/memory-lifecycle.test.ts b/packages/eve/src/context/memory-lifecycle.test.tsindex c8e8ea79c..32b0c773d 100644--- a/packages/eve/src/context/memory-lifecycle.test.ts+++ b/packages/eve/src/context/memory-lifecycle.test.ts@@ -11,7 +11,13 @@ import {prepareMemoryCompaction,prepareMemoryPreamble,} from "#context/memory-lifecycle.js";-import { AuthKey, SessionIdKey, SessionKey, TurnMemoryLocksKey } from "#context/keys.js";+import {+ AuthKey,+ SessionIdKey,+ SessionKey,+ StaticModelReferenceKey,+ TurnMemoryLocksKey,+} from "#context/keys.js";import { type MemoryInstrumentation } from "#instrumentation/memory.js";import {defineMemory,@@ -38,6 +44,7 @@ function createContext() {principalType: "user",};const ctx = new ContextContainer();+ ctx.set(StaticModelReferenceKey, null);ctx.set(AuthKey, auth);ctx.set(SessionIdKey, "session_1");ctx.set(SessionKey, {diff --git a/packages/eve/src/context/memory-tools.test.ts b/packages/eve/src/context/memory-tools.test.tsindex 5e6f5f005..84457c1dc 100644--- a/packages/eve/src/context/memory-tools.test.ts+++ b/packages/eve/src/context/memory-tools.test.ts@@ -6,7 +6,13 @@ import {dispatchDynamicToolEvent,rebindMissingCompiledDynamicToolCallbacks,} from "#context/dynamic-tool-lifecycle.js";-import { AuthKey, SessionIdKey, SessionKey, TurnMemoryLocksKey } from "#context/keys.js";+import {+ AuthKey,+ SessionIdKey,+ SessionKey,+ StaticModelReferenceKey,+ TurnMemoryLocksKey,+} from "#context/keys.js";import { createMemoryToolDynamicDefinition } from "#context/memory-tools.js";import { resolveApprovalPolicy } from "#approval/definition.js";import { defineTool } from "#tools/definition.js";@@ -27,6 +33,7 @@ function createContext(scope: string) {principalType: "user",};const ctx = new ContextContainer();+ ctx.set(StaticModelReferenceKey, null);ctx.set(AuthKey, auth);ctx.set(SessionIdKey, "session_1");ctx.set(SessionKey, {@@ -143,6 +150,7 @@ describe("memory provider tools", () => {async () =>await dynamic.events["turn.started"]?.(event, {channel: {},+ model: null,messages: [],session: { auth: { current: null, initiator: null }, id: "session_1" },}),diff --git a/packages/eve/src/dynamic/definition.ts b/packages/eve/src/dynamic/definition.tsindex 173b7134f..6bcd908c3 100644--- a/packages/eve/src/dynamic/definition.ts+++ b/packages/eve/src/dynamic/definition.ts@@ -45,6 +45,8 @@ export const ALLOWED_DYNAMIC_CONNECTION_EVENTS: ReadonlySet<string> = new Set<Dy* the session context inside tool `execute` functions.*/export interface DynamicResolveContext {+ /** Effective model for this resolver, or `null` before dynamic model selection. */+ readonly model: { readonly id: string } | null;readonly session: {readonly id: string;readonly auth: SessionAuth;diff --git a/packages/eve/src/execution/tools/connection-search.test.ts b/packages/eve/src/execution/tools/connection-search.test.tsindex 810188ff6..7d8cf0482 100644--- a/packages/eve/src/execution/tools/connection-search.test.ts+++ b/packages/eve/src/execution/tools/connection-search.test.ts@@ -46,6 +46,7 @@ async function executeConnectionSearch(return contextStorage.run(ctx, async () => {const resolve = getConnectionSearchResolver().events["step.started"]!;const resolved = (await resolve({}, {+ model: { id: "openai/gpt-5.5" },channel: {},messages: [],session: { auth: { current: null, initiator: null }, id: "test-session" },@@ -94,6 +95,7 @@ describe("connection dynamic tools", () => {resolve({},{+ model: { id: "openai/gpt-5.5" },channel: {},messages: [],session: { auth: { current: null, initiator: null }, id: "test-session" },@@ -128,6 +130,7 @@ describe("connection dynamic tools", () => {{},{channel: {},+ model: null,messages: [],session: { auth: { current: null, initiator: null }, id: "test-session" },},@@ -136,6 +139,7 @@ describe("connection dynamic tools", () => {return (await resolve({},{+ model: { id: "openai/gpt-5.5" },channel: {},messages: [],session: { auth: { current: null, initiator: null }, id: "test-session" },@@ -181,6 +185,7 @@ describe("connection dynamic tools", () => {const resolve = getConnectionSearchResolver().events["step.started"]!;const resolveContext = {channel: {},+ model: null,messages: [],session: { auth: { current: null, initiator: null }, id: "test-session" },} satisfies DynamicResolveContext;@@ -595,6 +600,7 @@ describe("connection_search", () => {const resolve = getConnectionSearchResolver().events["step.started"]!;const tools = (await resolve({}, {channel: {},+ model: null,messages: [],session: { auth: { current: null, initiator: null }, id: "session-auth-replay" },} satisfies DynamicResolveContext)) as DynamicToolSet;diff --git a/packages/eve/src/execution/workflow-steps.ts b/packages/eve/src/execution/workflow-steps.tsindex 20bfd7ab2..947963eb3 100644--- a/packages/eve/src/execution/workflow-steps.ts+++ b/packages/eve/src/execution/workflow-steps.ts@@ -28,6 +28,7 @@ import {ModeKey,SessionDynamicSubagentRuntimeRevisionKey,SessionDynamicToolRuntimeRevisionKey,+ StaticModelReferenceKey,TurnTaskDeliveryKey,TurnDeliveryIdsKey,} from "#context/keys.js";@@ -346,6 +347,7 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu: await resolveRuntimeCompiledArtifactsVersionedCacheKey(bundle.compiledArtifactsSource);const sessionStarted = initialEmissionState.sessionStarted;+ ctx.setVirtualContext(StaticModelReferenceKey, effectiveAgent.turnAgent.model ?? null);if (!sessionStarted) {ctx.set(SessionDynamicSubagentRuntimeRevisionKey, dynamicRuntimeRevision);ctx.set(SessionDynamicToolRuntimeRevisionKey, dynamicRuntimeRevision);@@ -504,6 +506,7 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResurunStep: async ({ firstCall, session, stepInput }) => {const result = await runBackgroundStep(ctx, session, async (enrichedSession) => {ctx.setVirtualContext(HandleEventKey, handleEvent);+ ctx.setVirtualContext(StaticModelReferenceKey, effectiveAgent.turnAgent.model ?? null);let schemaSession = firstCall? resolveEffectiveOutputSchema({agentOutputSchema: effectiveAgent.turnAgent.outputSchema,diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.tsindex ae20716ee..d2ddc76e1 100644--- a/packages/eve/src/harness/tool-loop.ts+++ b/packages/eve/src/harness/tool-loop.ts@@ -26,6 +26,7 @@ import {ParentSessionKey,ScheduleIdKey,SessionCallbackKey,+ StaticModelReferenceKey,TurnTaskDeliveryKey,} from "#context/keys.js";import {@@ -38,10 +39,8 @@ import {prepareMemoryCompaction,prepareMemoryPreamble,} from "#context/memory-lifecycle.js";-import {- getActiveDynamicModelSelection,- isDynamicModelSelectionError,-} from "#context/dynamic-model-lifecycle.js";+import { isDynamicModelSelectionError } from "#context/dynamic-model-lifecycle.js";+import { getEffectiveModelSelection } from "#context/effective-model.js";import {buildDynamicTools,buildResponseAuthorizationTools,@@ -369,7 +368,7 @@ function buildGatewayAttributionHeaders(return headers;}-async function resolveActiveRuntimeModel(input: {+async function resolveEffectiveRuntimeModel(input: {readonly config: ToolLoopHarnessConfig;readonly ctx: ReturnType<typeof contextStorage.getStore>;readonly session: HarnessSession;@@ -388,19 +387,12 @@ async function resolveActiveRuntimeModel(input: {};}- const selected = getActiveDynamicModelSelection(input.ctx);+ const selected = getEffectiveModelSelection(input.ctx);if (selected === null) {- const reference = input.session.agent.modelReference;- if (input.session.agent.dynamicModel === true || reference === undefined) {- throw new Error(- "Dynamic model selection is required before model-dependent work begins. Add a matching resolver handler that returns a concrete model.",- );- }- return {- model: await input.config.resolveModel(reference),- session: input.session,- };+ throw new Error(+ "Dynamic model selection is required before model-dependent work begins. Add a matching resolver handler that returns a concrete model.",+ );}return {@@ -416,6 +408,7 @@ function updateSessionModelReference(session: HarnessSession,modelReference: RuntimeModelReference,): HarnessSession {+ if (session.agent.modelReference === modelReference) return session;return {...session,agent: {@@ -508,6 +501,12 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {let emissionState = getHarnessEmissionState(session.state);const store = contextStorage.getStore();+ if (store !== undefined && !store.has(StaticModelReferenceKey)) {+ store.setVirtualContext(+ StaticModelReferenceKey,+ session.agent.dynamicModel === true ? null : (session.agent.modelReference ?? null),+ );+ }const parent = store?.get(ParentSessionKey);const callback = store?.get(SessionCallbackKey);const hasDelegatedCaller = parent !== undefined || callback !== undefined;@@ -613,7 +612,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {if (session.history.length > 0) {try {const ctx = contextStorage.getStore();- const resolvedModel = await resolveActiveRuntimeModel({ config, ctx, session });+ const resolvedModel = await resolveEffectiveRuntimeModel({ config, ctx, session });session = resolvedModel.session;const compacted = await maybeCompact({@@ -1150,7 +1149,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {// Direct harness unit tests may run without an ambient context.const ctx = store;- let resolvedModel: Awaited<ReturnType<typeof resolveActiveRuntimeModel>>;+ let resolvedModel: Awaited<ReturnType<typeof resolveEffectiveRuntimeModel>>;try {if (ctx !== undefined && config.dispatchDynamicModelEvent !== undefined) {await config.dispatchDynamicModelEvent({@@ -1166,7 +1165,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {messages: projectedMessages,});}- resolvedModel = await resolveActiveRuntimeModel({+ resolvedModel = await resolveEffectiveRuntimeModel({config,ctx,session,diff --git a/packages/eve/src/public/memory/file/provider.test.ts b/packages/eve/src/public/memory/file/provider.test.tsindex c967f18c1..b3667893c 100644--- a/packages/eve/src/public/memory/file/provider.test.ts+++ b/packages/eve/src/public/memory/file/provider.test.ts@@ -390,6 +390,7 @@ function compactionCompletedContext(): MemoryCompactionCompletedContext {function toolsContext(): MemoryToolsContext {return {channel: { kind: "http" },+ model: null,memory: operationContext().memory,messages: [],session: {diff --git a/packages/eve/src/runtime/agent/resolve-model.test.ts b/packages/eve/src/runtime/agent/resolve-model.test.tsindex 19e8eed76..bfb218dfc 100644--- a/packages/eve/src/runtime/agent/resolve-model.test.ts+++ b/packages/eve/src/runtime/agent/resolve-model.test.ts@@ -71,6 +71,7 @@ describe("dynamic runtime model resolution", () => {const result = await definition.events["session.started"]?.({ type: "session.started" },{+ model: { id: "openai/gpt-5.5" },channel: { kind: "slack" },messages: [{ content: "Hi", role: "user" }],session: { auth: { current: null, initiator: null }, id: "session-1" },