The Open Framework for Building Agents
feat(eve): dynamic model selection (#581)
Andrew Barbab7d10896f472
diff --git a/.changeset/dynamic-agent-models.md b/.changeset/dynamic-agent-models.mdnew file mode 100644index 000000000..968dd3dba--- /dev/null+++ b/.changeset/dynamic-agent-models.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Add `defineDynamic({ fallback, events })` support for scoped dynamic agent model selection. Agents can choose a model once per session, once per turn, or per model step while keeping a compiled fallback for metadata and unset scopes.diff --git a/docs/agent-config.md b/docs/agent-config.mdindex ca7ef13f7..a61a87a92 100644--- a/docs/agent-config.md+++ b/docs/agent-config.md@@ -43,6 +43,50 @@ version uses hyphens (`claude-opus-4-8`), while the Gateway id above uses a dotModel use is subject to the terms, data-processing commitments, retention behavior, and available controls of the selected provider and routing path. Review the [AI Gateway model catalog](https://vercel.com/ai-gateway/models) for gateway-routed models, and review the provider's terms when you configure a direct `LanguageModel`.+### Choose the model dynamically++`model` also accepts `defineDynamic({ fallback, events })`. `fallback` is the+compiled static model: it anchors build-time metadata (routing, credentials,+context window) and serves whenever no dynamic selection is set.++```ts title="agent/agent.ts"+import { defineAgent, defineDynamic } from "eve";++export default defineAgent({+ model: defineDynamic({+ fallback: "anthropic/claude-sonnet-5",+ events: {+ "session.started": (_event, ctx) =>+ ctx.session.auth.initiator?.attributes.plan === "enterprise"+ ? "anthropic/claude-opus-4.8"+ : null,+ },+ }),+});+```++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, or `null` to leave the scope unset.++- **Scopes.** `session.started` (once per session), `turn.started` (once per+ turn), `step.started` (every model step). Precedence: step > turn >+ session > `fallback`. Prefer `session.started`: prompt caches are per+ model, so every switch re-ingests the conversation at uncached prices.+- **Failures degrade, never fail the turn.** A resolver that throws or+ returns an invalid selection logs an error and leaves its scope unset.+ Build-time validation covers only `fallback`; a selected model without+ credentials fails at request time.+- **Serialization.** Session/turn selections must be model id strings; return+ live `LanguageModel` objects only from `step.started`.+- **Selection object.** `{ model, modelContextWindowTokens?, modelOptions? }`.+ Set `modelContextWindowTokens` when the selected model's window differs+ from the fallback's — it is never inherited. Omitted `modelOptions` reuses+ the agent-level `modelOptions`.++Runtime identity reports a dynamic agent's model as `dynamic:<fallback id>`.+## Reasoning effortSet `reasoning` to control the model's reasoning effort through AI SDK'sdiff --git a/docs/guides/dynamic-capabilities.md b/docs/guides/dynamic-capabilities.mdindex bf92f19e3..cb88410f0 100644--- a/docs/guides/dynamic-capabilities.md+++ b/docs/guides/dynamic-capabilities.md@@ -1,9 +1,25 @@---title: "Dynamic Capabilities"-description: "Resolve tools, skills, and instructions at runtime with defineDynamic: the resolver events, execution order, and how dynamic tools survive step boundaries."+description: "Resolve models, tools, skills, and instructions at runtime: dynamic model selection, defineDynamic resolver events, execution order, and durable dynamic tools."----`defineDynamic` resolves tools, skills, and instructions at runtime from a session event instead of declaring them up front. Reach for it when the right capabilities aren't known until the session starts, because they hinge on who the caller is, what tenant they belong to, feature flags, or external data. The [tools](../tools), [skills](../skills), and [instructions](../instructions) guides each point here for their dynamic form.+`defineDynamic` resolves the model, tools, skills, and instructions at runtime from a session event instead of declaring them up front. Reach for it when the right capability isn't known until the session starts, because it hinges on who the caller is, what tenant they belong to, feature flags, or external data. The [tools](../tools), [skills](../skills), and [instructions](../instructions) guides each point here for their dynamic form.++## Dynamic models++The `model` field in `agent.ts` accepts `defineDynamic({ fallback, events })`.+Resolvers run at `session.started`, `turn.started`, or `step.started`+(precedence: step > turn > session > `fallback`); `null` leaves a scope unset+and failures degrade to the next scope. Prefer `session.started` — prompt+caches are per model, so switching mid-session re-ingests the conversation at+uncached prices. See+[agent configuration](../agent-config#choose-the-model-dynamically) for the+full contract.++`fallback` is model-only: the agent always needs exactly one model, and the+compiled fallback anchors build-time metadata. Tools, skills, and instructions+default by authoring a static entry (or returning `null`), so `fallback` on+their `defineDynamic` export is a build error.## Dynamic toolsdiff --git a/e2e/fixtures/agent-model/.gitignore b/e2e/fixtures/agent-model/.gitignorenew file mode 100644index 000000000..4301967e4--- /dev/null+++ b/e2e/fixtures/agent-model/.gitignore@@ -0,0 +1,11 @@+node_modules+.env*+.eve+.vercel+.workflow-data+.next+.output+.nitro+dist+.DS_Store+*.tsbuildinfodiff --git a/e2e/fixtures/agent-model/.vercelignore b/e2e/fixtures/agent-model/.vercelignorenew file mode 100644index 000000000..357664320--- /dev/null+++ b/e2e/fixtures/agent-model/.vercelignore@@ -0,0 +1,6 @@+node_modules+.eve+.next+.output+.nitro+distdiff --git a/e2e/fixtures/agent-model/agent/agent.ts b/e2e/fixtures/agent-model/agent/agent.tsnew file mode 100644index 000000000..7400bd22a--- /dev/null+++ b/e2e/fixtures/agent-model/agent/agent.ts@@ -0,0 +1,40 @@+import { defineAgent, defineDynamic, type DynamicResolveContext } from "eve";++/**+ * Dynamic-model e2e fixture. Resolves at `turn.started` (not the usual+ * `session.started`) so one session can exercise selection, null fallback,+ * and resolver-failure degradation.+ */+export default defineAgent({+ model: defineDynamic({+ fallback: "openai/gpt-5.5",+ events: {+ "turn.started": (_event, ctx) => {+ const text = lastUserText(ctx.messages);++ if (text.includes("[model: boom]")) {+ throw new Error("intentional resolver failure");+ }++ if (text.includes("[model: mini]")) {+ return {+ model: "openai/gpt-5.5-mini",+ modelContextWindowTokens: 128_000,+ };+ }++ return null;+ },+ },+ }),+});++function lastUserText(messages: DynamicResolveContext["messages"]): string {+ for (let index = messages.length - 1; index >= 0; index -= 1) {+ const message = messages[index];+ if (message?.role !== "user") continue;+ if (typeof message.content === "string") return message.content;+ return message.content.map((part) => (part.type === "text" ? part.text : "")).join(" ");+ }+ return "";+}diff --git a/e2e/fixtures/agent-model/agent/instructions.md b/e2e/fixtures/agent-model/agent/instructions.mdnew file mode 100644index 000000000..cdd2813c3--- /dev/null+++ b/e2e/fixtures/agent-model/agent/instructions.md@@ -0,0 +1,4 @@+# Identity++You are a helpful assistant. Follow echo instructions exactly, character for+character, with no extra commentary.diff --git a/e2e/fixtures/agent-model/evals/dynamic-model/fallback.eval.ts b/e2e/fixtures/agent-model/evals/dynamic-model/fallback.eval.tsnew file mode 100644index 000000000..09a44c505--- /dev/null+++ b/e2e/fixtures/agent-model/evals/dynamic-model/fallback.eval.ts@@ -0,0 +1,23 @@+import { defineEval } from "eve/evals";++/**+ * No selection marker: the resolver returns `null`, the fallback serves the+ * turn, and the runtime identity reports `dynamic:<fallback id>`.+ */+export default defineEval({+ description: "Dynamic model smoke: null selection serves the fallback model.",+ async test(t) {+ await t.send('Reply with exactly the text "fallback ping" and nothing else.');++ t.succeeded();+ t.messageIncludes("fallback ping");+ t.usedNoTools();+ t.eventsSatisfy("runtime identity reports a dynamic model", (events) =>+ events.some(+ (event) =>+ event.type === "session.started" &&+ event.data.runtime?.modelId === "dynamic:openai/gpt-5.5",+ ),+ );+ },+});diff --git a/e2e/fixtures/agent-model/evals/dynamic-model/resolver-failure.eval.ts b/e2e/fixtures/agent-model/evals/dynamic-model/resolver-failure.eval.tsnew file mode 100644index 000000000..3debf82f9--- /dev/null+++ b/e2e/fixtures/agent-model/evals/dynamic-model/resolver-failure.eval.ts@@ -0,0 +1,13 @@+import { defineEval } from "eve/evals";++/** A throwing resolver degrades to the fallback model instead of failing the turn. */+export default defineEval({+ description: "Dynamic model smoke: a throwing resolver falls back instead of failing the turn.",+ async test(t) {+ await t.send('[model: boom] Reply with exactly the text "still here" and nothing else.');++ t.succeeded();+ t.messageIncludes("still here");+ t.usedNoTools();+ },+});diff --git a/e2e/fixtures/agent-model/evals/dynamic-model/turn-selection.eval.ts b/e2e/fixtures/agent-model/evals/dynamic-model/turn-selection.eval.tsnew file mode 100644index 000000000..acd09bada--- /dev/null+++ b/e2e/fixtures/agent-model/evals/dynamic-model/turn-selection.eval.ts@@ -0,0 +1,23 @@+import { defineEval } from "eve/evals";++/**+ * A marked turn selects `openai/gpt-5.5-mini`; the next unmarked turn falls+ * back. Both completing proves each reference serves a real model call.+ */+export default defineEval({+ description: "Dynamic model smoke: per-turn selection and null fallback in one session.",+ async test(t) {+ const selected = await t.send(+ '[model: mini] Reply with exactly the text "mini ping" and nothing else.',+ );+ selected.expectOk();+ selected.messageIncludes("mini ping");++ const fallback = await t.send('Reply with exactly the text "fallback again" and nothing else.');+ fallback.expectOk();+ fallback.messageIncludes("fallback again");++ t.succeeded();+ t.usedNoTools();+ },+});diff --git a/e2e/fixtures/agent-model/evals/evals.config.ts b/e2e/fixtures/agent-model/evals/evals.config.tsnew file mode 100644index 000000000..6864dd176--- /dev/null+++ b/e2e/fixtures/agent-model/evals/evals.config.ts@@ -0,0 +1,6 @@+import { defineEvalConfig } from "eve/evals";++/** Default judge model for any `t.judge.*` assertion in this fixture. */+export default defineEvalConfig({+ judge: { model: "openai/gpt-5.5" },+});diff --git a/e2e/fixtures/agent-model/package.json b/e2e/fixtures/agent-model/package.jsonnew file mode 100644index 000000000..91c7b0edf--- /dev/null+++ b/e2e/fixtures/agent-model/package.json@@ -0,0 +1,20 @@+{+ "name": "agent-model",+ "version": "0.0.0",+ "private": true,+ "type": "module",+ "scripts": {+ "build": "eve build",+ "dev": "eve dev",+ "start": "eve start",+ "typecheck": "eve build && tsc",+ "test:e2e": "eve eval --strict"+ },+ "dependencies": {+ "eve": "workspace:*"+ },+ "devDependencies": {+ "@types/node": "catalog:",+ "typescript": "catalog:"+ }+}diff --git a/e2e/fixtures/agent-model/tsconfig.json b/e2e/fixtures/agent-model/tsconfig.jsonnew file mode 100644index 000000000..66f5b1ea5--- /dev/null+++ b/e2e/fixtures/agent-model/tsconfig.json@@ -0,0 +1,17 @@+{+ "compilerOptions": {+ "target": "ES2022",+ "module": "NodeNext",+ "moduleResolution": "NodeNext",+ "outDir": "dist",+ "rootDir": ".",+ "strict": true,+ "esModuleInterop": true,+ "skipLibCheck": true,+ "forceConsistentCasingInFileNames": true,+ "declaration": true,+ "noEmit": true,+ "types": ["node"]+ },+ "include": ["agent/**/*.ts", "evals/**/*.ts", ".eve/**/*.d.ts"]+}diff --git a/packages/eve/src/compiler/manifest.test.ts b/packages/eve/src/compiler/manifest.test.tsindex 757edc585..c3a1423bf 100644--- a/packages/eve/src/compiler/manifest.test.ts+++ b/packages/eve/src/compiler/manifest.test.ts@@ -44,6 +44,32 @@ describe("compiledAgentManifestSchema", () => {});});+ it("preserves dynamic model resolver source", () => {+ const manifest = createCompiledAgentManifest({+ agentRoot: "/app/agent",+ appRoot: "/app",+ config: {+ dynamicModel: {+ eventNames: ["session.started"],+ logicalPath: "agent.ts",+ sourceId: "agent-config",+ sourceKind: "module",+ },+ model: { id: "openai/gpt-5.5", routing: classifyModelRouting("openai/gpt-5.5") },+ name: "app",+ },+ });++ const parsed = compiledAgentManifestSchema.parse(manifest);++ expect(parsed.config.dynamicModel).toEqual({+ eventNames: ["session.started"],+ logicalPath: "agent.ts",+ sourceId: "agent-config",+ sourceKind: "module",+ });+ });+it("preserves uncapped (false) session token limits", () => {const manifest = createCompiledAgentManifest({agentRoot: "/app/agent",diff --git a/packages/eve/src/compiler/manifest.ts b/packages/eve/src/compiler/manifest.tsindex d6cb12d15..e94d12e7e 100644--- a/packages/eve/src/compiler/manifest.ts+++ b/packages/eve/src/compiler/manifest.ts@@ -41,7 +41,7 @@ export const ROOT_COMPILED_AGENT_NODE_ID = "__root__";/*** Current compiled manifest schema version.*/-export const COMPILED_AGENT_MANIFEST_VERSION = 32;+export const COMPILED_AGENT_MANIFEST_VERSION = 33;/*** Compiled channel entry preserved in the compiled manifest.@@ -100,6 +100,14 @@ export type CompiledRuntimeModelReference = InternalAgentModelDefinition & {routing: ModelRouting;};+/**+ * Dynamic model resolver source preserved in the compiled manifest; the+ * compiled `config.model` remains the fallback model.+ */+export type CompiledDynamicModelDefinition = ModuleSourceRef & {+ readonly eventNames: readonly string[];+};+/*** Normalized hosted-build configuration preserved in the compiled manifest.*/@@ -119,6 +127,7 @@ type CompiledAgentCompactionDefinition = Omit<InternalAgentCompactionDefinition,export type CompiledAgentDefinition = Omit<InternalAgentDefinition, "model" | "compaction"> & {model: CompiledRuntimeModelReference;compaction?: CompiledAgentCompactionDefinition;+ dynamicModel?: CompiledDynamicModelDefinition;};/**@@ -258,6 +267,16 @@ const moduleSourceRefSchema: z.ZodType<ModuleSourceRef> = z}).strict();+const compiledDynamicModelDefinitionSchema: z.ZodType<CompiledDynamicModelDefinition> = z+ .object({+ eventNames: z.array(z.string()).readonly(),+ exportName: z.string().optional(),+ sourceKind: z.literal("module"),+ logicalPath: z.string(),+ sourceId: z.string(),+ })+ .strict();+const channelMethodSchema = z.union([z.literal("GET"),z.literal("POST"),@@ -375,6 +394,7 @@ const compiledAgentConfigSchema: z.ZodType<CompiledAgentDefinition> = zbuild: compiledAgentBuildDefinitionSchema.optional(),compaction: compiledAgentCompactionDefinitionSchema.optional(),description: z.string().optional(),+ dynamicModel: compiledDynamicModelDefinitionSchema.optional(),experimental: z.object({workflow: compiledAgentWorkflowDefinitionSchema.optional(),@@ -716,6 +736,12 @@ export function createCompiledAgentNodeManifest(input: {thresholdPercent: input.config.compaction?.thresholdPercent,},description: input.config.description,+ dynamicModel:+ input.config.dynamicModel === undefined+ ? undefined+ : {+ ...input.config.dynamicModel,+ },experimental:input.config.experimental === undefined? undefineddiff --git a/packages/eve/src/compiler/normalize-agent-config.test.ts b/packages/eve/src/compiler/normalize-agent-config.test.tsnew file mode 100644index 000000000..7c75c0df5--- /dev/null+++ b/packages/eve/src/compiler/normalize-agent-config.test.ts@@ -0,0 +1,66 @@+import { beforeEach, describe, expect, it, vi } from "vitest";++import { createAgentSourceManifest, createModuleSourceRef } from "#discover/manifest.js";+import { defineDynamic } from "#public/definitions/tool.js";+import { compileAgentConfig } from "#compiler/normalize-agent-config.js";+import type { ManifestCompileContext } from "#compiler/normalize-helpers.js";++const mocks = vi.hoisted(() => ({+ loadModuleBackedDefinition: vi.fn(),+}));++vi.mock("#compiler/normalize-helpers.js", async (importOriginal) => ({+ ...(await importOriginal<typeof import("#compiler/normalize-helpers.js")>()),+ loadModuleBackedDefinition: mocks.loadModuleBackedDefinition,+}));++describe("compileAgentConfig", () => {+ beforeEach(() => {+ mocks.loadModuleBackedDefinition.mockReset();+ });++ it("compiles a dynamic model fallback and preserves the resolver source", async () => {+ mocks.loadModuleBackedDefinition.mockResolvedValue({+ model: defineDynamic({+ fallback: "openai/gpt-5.5",+ events: {+ "session.started": () => "openai/gpt-5.5-mini",+ "step.started": () => null,+ },+ }),+ });++ const manifest = createAgentSourceManifest({+ agentId: "app",+ agentRoot: "/app/agent",+ appRoot: "/app",+ configModule: createModuleSourceRef({+ logicalPath: "agent.ts",+ sourceId: "agent-config",+ }),+ });++ const compiled = await compileAgentConfig(manifest, {+ modelCatalog: createModelCatalog(),+ });++ expect(compiled.model).toEqual({+ contextWindowTokens: 256_000,+ id: "openai/gpt-5.5",+ routing: { kind: "gateway", target: "openai" },+ });+ expect(compiled.dynamicModel).toEqual({+ eventNames: ["session.started", "step.started"],+ logicalPath: "agent.ts",+ sourceId: "agent-config",+ sourceKind: "module",+ });+ });+});++function createModelCatalog(): ManifestCompileContext["modelCatalog"] {+ return {+ getByProviderModelId: vi.fn(),+ getModelLimits: vi.fn(async () => ({ contextWindowTokens: 256_000 })),+ };+}diff --git a/packages/eve/src/compiler/normalize-agent-config.ts b/packages/eve/src/compiler/normalize-agent-config.tsindex 0e3452c1a..3ef0e3e98 100644--- a/packages/eve/src/compiler/normalize-agent-config.ts+++ b/packages/eve/src/compiler/normalize-agent-config.ts@@ -10,7 +10,11 @@ import { DEFAULT_AGENT_MODEL_ID } from "#shared/default-agent-model.js";import { toErrorMessage } from "#shared/errors.js";import { parseJsonObject, type JsonObject } from "#shared/json.js";import type { ModuleSourceRef } from "#shared/source-ref.js";-import type { PublicAgentModelDefinition } from "#shared/agent-definition.js";+import {+ isDynamicModelDefinition,+ type PublicAgentStaticModelDefinition,+} from "#shared/agent-definition.js";+import type { DynamicToolEventName } from "#shared/dynamic-tool-definition.js";import type { CompiledAgentDefinition, CompiledRuntimeModelReference } from "#compiler/manifest.js";import type { CompiledRuntimeModelLimits } from "#compiler/model-catalog.js";import {@@ -44,6 +48,9 @@ export async function compileAgentConfig(? `Expected the default agent config to match the public eve shape.`: `Expected the agent config export "${configModule.exportName ?? "default"}" from "${configModulePath}" to match the public eve shape.`,);+ const authoredModel = isDynamicModelDefinition(definition.model)+ ? definition.model.fallback+ : definition.model;const model = await normalizeAuthoredModelReference({modelCatalog: context.modelCatalog,purpose: "the primary compaction trigger model",@@ -51,7 +58,7 @@ export async function compileAgentConfig(providerOptions: definition.modelOptions?.providerOptions,source: configModule,sourcePath: configModulePath,- value: definition.model,+ value: authoredModel,});const compaction: {model?: CompiledRuntimeModelReference;@@ -65,6 +72,7 @@ export async function compileAgentConfig(thresholdPercent?: number;};description?: string;+ dynamicModel?: CompiledAgentDefinition["dynamicModel"];experimental?: CompiledAgentDefinition["experimental"];model: CompiledRuntimeModelReference;name: string;@@ -82,6 +90,19 @@ export async function compileAgentConfig(compiledConfig.description = definition.description;}+ if (isDynamicModelDefinition(definition.model)) {+ if (configModule === undefined) {+ throw new Error("Expected dynamic model definitions to be authored in agent.ts.");+ }+ compiledConfig.dynamicModel = {+ eventNames: Object.keys(definition.model.events) as DynamicToolEventName[],+ exportName: configModule.exportName,+ sourceKind: "module",+ logicalPath: configModule.logicalPath,+ sourceId: configModule.sourceId,+ };+ }+const experimental = normalizeExperimentalDefinition(definition.experimental);if (experimental !== undefined) {compiledConfig.experimental = experimental;@@ -166,7 +187,7 @@ async function normalizeAuthoredModelReference(input: {readonly providerOptions?: Record<string, JsonObject>;readonly source?: ModuleSourceRef;readonly sourcePath?: string;- readonly value: PublicAgentModelDefinition;+ readonly value: PublicAgentStaticModelDefinition;}): Promise<CompiledRuntimeModelReference> {if (typeof input.value === "string") {return await withCompiledRuntimeModelLimits(diff --git a/packages/eve/src/compiler/normalize-instructions.ts b/packages/eve/src/compiler/normalize-instructions.tsindex 989d0f6ee..04832b631 100644--- a/packages/eve/src/compiler/normalize-instructions.ts+++ b/packages/eve/src/compiler/normalize-instructions.ts@@ -9,7 +9,11 @@ import {loadModuleBackedDefinition,type ModuleBackedDefinitionLoadOptions,} from "#compiler/normalize-helpers.js";-import { isDynamicSentinel, type DynamicToolEventName } from "#shared/dynamic-tool-definition.js";+import {+ isDynamicSentinel,+ rejectDynamicSentinelFallback,+ type DynamicToolEventName,+} from "#shared/dynamic-tool-definition.js";/*** Compiled instructions entry produced from one authored `instructions/*`@@ -68,6 +72,10 @@ export async function compileInstructionsEntry(});if (isDynamicSentinel(exportValue)) {+ rejectDynamicSentinelFallback(+ exportValue,+ `Expected the instructions export "${source.exportName ?? "default"}" from "${source.logicalPath}" to match the public eve shape.`,+ );const slug = stripLogicalPathExtension(source.logicalPath).replace(/^instructions\//, "");return {kind: "dynamic-instructions",diff --git a/packages/eve/src/compiler/normalize-skill.ts b/packages/eve/src/compiler/normalize-skill.tsindex 907d73184..e54d3b646 100644--- a/packages/eve/src/compiler/normalize-skill.ts+++ b/packages/eve/src/compiler/normalize-skill.ts@@ -11,7 +11,11 @@ import {loadModuleBackedDefinition,type ModuleBackedDefinitionLoadOptions,} from "#compiler/normalize-helpers.js";-import { isDynamicSentinel, type DynamicToolEventName } from "#shared/dynamic-tool-definition.js";+import {+ isDynamicSentinel,+ rejectDynamicSentinelFallback,+ type DynamicToolEventName,+} from "#shared/dynamic-tool-definition.js";/*** Compiled skill entry produced from one authored `skills/*` file.@@ -72,6 +76,10 @@ export async function compileSkillSource(});if (isDynamicSentinel(exportValue)) {+ rejectDynamicSentinelFallback(+ exportValue,+ `Expected the skill export "${source.exportName ?? "default"}" from "${source.logicalPath}" to match the public eve shape.`,+ );const slug = stripLogicalPathExtension(source.logicalPath).replace(/^skills\//, "");return {kind: "dynamic-skill",diff --git a/packages/eve/src/context/container.ts b/packages/eve/src/context/container.tsindex 3f73956d5..0f6029f08 100644--- a/packages/eve/src/context/container.ts+++ b/packages/eve/src/context/container.ts@@ -20,6 +20,8 @@ export interface AlsContext extends ContextAccessor {* Used by the serialization layer to persist context at step boundaries.*/entries(): Iterable<readonly [ContextKey<unknown>, unknown]>;+ /** Stores a step-local value that shadows the durable value and is never serialized. */+ setVirtualContext<T>(key: ContextKey<T>, value: T): void;}/**diff --git a/packages/eve/src/context/dynamic-model-lifecycle.test.ts b/packages/eve/src/context/dynamic-model-lifecycle.test.tsnew file mode 100644index 000000000..cb5febdde--- /dev/null+++ b/packages/eve/src/context/dynamic-model-lifecycle.test.ts@@ -0,0 +1,315 @@+import type { LanguageModel } from "ai";+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,+ getActiveDynamicModelSelection,+} from "#context/dynamic-model-lifecycle.js";+import { SessionDynamicModelReferenceKey, TurnDynamicModelReferenceKey } from "#context/keys.js";+import { defineDynamic } from "#public/definitions/tool.js";+import {+ createSessionStartedEvent,+ createStepStartedEvent,+ createTurnStartedEvent,+} from "#protocol/message.js";+import type { RuntimeDynamicModelReference } from "#runtime/agent/bootstrap.js";++const DYNAMIC_MODEL_SOURCE: RuntimeDynamicModelReference = {+ eventNames: ["session.started", "turn.started", "step.started"],+ logicalPath: "agent.ts",+ sourceId: "agent-config",+ sourceKind: "module",+};++const FALLBACK = { contextWindowTokens: 256_000, id: "openai/gpt-5.5" };++afterEach(() => {+ vi.unstubAllEnvs();+});++describe("dynamic model lifecycle", () => {+ it("persists session-scoped model references", async () => {+ const ctx = new ContextContainer();+ const moduleMap = createModuleMap({+ default: {+ model: defineDynamic({+ fallback: "openai/gpt-5.5",+ events: {+ "session.started": () => ({+ model: "openai/gpt-5.5-mini",+ modelContextWindowTokens: 128_000,+ }),+ },+ }),+ },+ });++ await dispatchDynamicModelEvent({+ ctx,+ dynamicModel: DYNAMIC_MODEL_SOURCE,+ event: createSessionStartedEvent(),+ fallback: FALLBACK,+ messages: [],+ scope: { moduleMap, nodeId: undefined },+ });++ expect(getActiveDynamicModelSelection(ctx)).toEqual({+ reference: {+ contextWindowTokens: 128_000,+ id: "openai/gpt-5.5-mini",+ providerOptions: undefined,+ },+ });+ });++ it("does not inherit the fallback context window for a different model", async () => {+ const ctx = new ContextContainer();+ const moduleMap = createModuleMap({+ default: {+ model: defineDynamic({+ fallback: "openai/gpt-5.5",+ events: {+ "session.started": () => "openai/gpt-5.5-mini",+ },+ }),+ },+ });++ await dispatchDynamicModelEvent({+ ctx,+ dynamicModel: DYNAMIC_MODEL_SOURCE,+ event: createSessionStartedEvent(),+ fallback: FALLBACK,+ messages: [],+ scope: { moduleMap, nodeId: undefined },+ });++ expect(getActiveDynamicModelSelection(ctx)?.reference.contextWindowTokens).toBeUndefined();+ });++ it("lets turn-scoped selections override session selections and null fall back", async () => {+ const ctx = new ContextContainer();+ let turnResult: string | null = "openai/gpt-5.5-turn";+ const moduleMap = createModuleMap({+ default: {+ model: defineDynamic({+ fallback: "openai/gpt-5.5",+ events: {+ "session.started": () => "openai/gpt-5.5-mini",+ "turn.started": () => turnResult,+ },+ }),+ },+ });+ const dispatch = (event: Parameters<typeof dispatchDynamicModelEvent>[0]["event"]) =>+ dispatchDynamicModelEvent({+ ctx,+ dynamicModel: DYNAMIC_MODEL_SOURCE,+ event,+ fallback: FALLBACK,+ messages: [],+ scope: { moduleMap, nodeId: undefined },+ });++ await dispatch(createSessionStartedEvent());+ await dispatch(createTurnStartedEvent({ sequence: 0, turnId: "turn_0" }));++ expect(getActiveDynamicModelSelection(ctx)?.reference.id).toBe("openai/gpt-5.5-turn");++ turnResult = null;+ await dispatch(createTurnStartedEvent({ sequence: 1, turnId: "turn_1" }));++ expect(getActiveDynamicModelSelection(ctx)?.reference.id).toBe("openai/gpt-5.5-mini");+ });++ it("keeps step-scoped live provider instances outside mock mode", async () => {+ vi.stubEnv("NODE_ENV", "production");+ const ctx = new ContextContainer();+ const stepModel = createLanguageModel("openai.responses", "gpt-step");+ const moduleMap = createModuleMap({+ default: {+ model: defineDynamic({+ fallback: "openai/gpt-5.5",+ events: {+ "session.started": () => "openai/gpt-5.5-mini",+ "step.started": () => stepModel,+ },+ }),+ },+ });++ await dispatchDynamicModelEvent({+ ctx,+ dynamicModel: DYNAMIC_MODEL_SOURCE,+ event: createSessionStartedEvent(),+ fallback: { id: "openai/gpt-5.5" },+ messages: [],+ scope: { moduleMap, nodeId: undefined },+ });+ await dispatchDynamicModelEvent({+ ctx,+ dynamicModel: DYNAMIC_MODEL_SOURCE,+ event: createStepStartedEvent({ sequence: 0, stepIndex: 0, turnId: "turn_0" }),+ fallback: { id: "openai/gpt-5.5" },+ messages: [{ content: "Use the direct model.", role: "user" }],+ scope: { moduleMap, nodeId: undefined },+ });++ expect(getActiveDynamicModelSelection(ctx)).toEqual({+ model: stepModel,+ reference: {+ contextWindowTokens: undefined,+ id: "openai/gpt-step",+ providerOptions: undefined,+ },+ });+ });++ it("strips step-scoped live provider instances in mock mode", async () => {+ // NODE_ENV=test (the vitest default) activates the mock adapter.+ const ctx = new ContextContainer();+ const stepModel = createLanguageModel("openai.responses", "gpt-step");+ const moduleMap = createModuleMap({+ default: {+ model: defineDynamic({+ fallback: "openai/gpt-5.5",+ events: {+ "step.started": () => stepModel,+ },+ }),+ },+ });++ await dispatchDynamicModelEvent({+ ctx,+ dynamicModel: DYNAMIC_MODEL_SOURCE,+ event: createStepStartedEvent({ sequence: 0, stepIndex: 0, turnId: "turn_0" }),+ fallback: { id: "openai/gpt-5.5" },+ messages: [],+ scope: { moduleMap, nodeId: undefined },+ });++ expect(getActiveDynamicModelSelection(ctx)).toEqual({+ reference: {+ contextWindowTokens: undefined,+ id: "openai/gpt-step",+ providerOptions: undefined,+ },+ });+ });++ it("rejects live provider instances at session and turn scope", async () => {+ const ctx = new ContextContainer();+ const liveModel = createLanguageModel("openai.responses", "gpt-live");+ const moduleMap = createModuleMap({+ default: {+ model: defineDynamic({+ fallback: "openai/gpt-5.5",+ events: {+ "session.started": () => liveModel,+ },+ }),+ },+ });++ await dispatchDynamicModelEvent({+ ctx,+ dynamicModel: DYNAMIC_MODEL_SOURCE,+ event: createSessionStartedEvent(),+ fallback: FALLBACK,+ messages: [],+ scope: { moduleMap, nodeId: undefined },+ });++ expect(ctx.get(SessionDynamicModelReferenceKey)).toBeNull();+ expect(getActiveDynamicModelSelection(ctx)).toBeNull();+ });++ it("clears the scope and falls back when a resolver throws", async () => {+ const ctx = new ContextContainer();+ ctx.set(TurnDynamicModelReferenceKey, { id: "openai/gpt-prior" });+ const moduleMap = createModuleMap({+ default: {+ model: defineDynamic({+ fallback: "openai/gpt-5.5",+ events: {+ "turn.started": () => {+ throw new Error("flag service unavailable");+ },+ },+ }),+ },+ });++ await dispatchDynamicModelEvent({+ ctx,+ dynamicModel: DYNAMIC_MODEL_SOURCE,+ event: createTurnStartedEvent({ sequence: 0, turnId: "turn_0" }),+ fallback: FALLBACK,+ messages: [],+ scope: { moduleMap, nodeId: undefined },+ });++ expect(ctx.get(TurnDynamicModelReferenceKey)).toBeNull();+ expect(getActiveDynamicModelSelection(ctx)).toBeNull();+ });++ it("clears the scope when a selection carries unknown keys", async () => {+ const ctx = new ContextContainer();+ const moduleMap = createModuleMap({+ default: {+ model: defineDynamic({+ fallback: "openai/gpt-5.5",+ events: {+ "session.started": () =>+ ({+ model: "openai/gpt-5.5-mini",+ contextWindowTokens: 128_000,+ }) as never,+ },+ }),+ },+ });++ await dispatchDynamicModelEvent({+ ctx,+ dynamicModel: DYNAMIC_MODEL_SOURCE,+ event: createSessionStartedEvent(),+ fallback: FALLBACK,+ messages: [],+ scope: { moduleMap, nodeId: undefined },+ });++ expect(getActiveDynamicModelSelection(ctx)).toBeNull();+ });+});++function createModuleMap(moduleNamespace: Record<string, unknown>): CompiledModuleMap {+ return {+ nodes: {+ [ROOT_COMPILED_AGENT_NODE_ID]: {+ modules: {+ [DYNAMIC_MODEL_SOURCE.sourceId]: moduleNamespace,+ },+ },+ },+ };+}++function createLanguageModel(provider: string, modelId: string): LanguageModel {+ return {+ specificationVersion: "v2",+ provider,+ modelId,+ supportedUrls: {},+ doGenerate: async () => {+ throw new Error("not implemented");+ },+ doStream: async () => {+ throw new Error("not implemented");+ },+ } as LanguageModel;+}diff --git a/packages/eve/src/context/dynamic-model-lifecycle.ts b/packages/eve/src/context/dynamic-model-lifecycle.tsnew file mode 100644index 000000000..4b9366d0a--- /dev/null+++ b/packages/eve/src/context/dynamic-model-lifecycle.ts@@ -0,0 +1,148 @@+import type { ModelMessage } from "ai";++import { buildResolveContext } from "#context/dynamic-resolve-context.js";+import type { AlsContext } from "#context/container.js";+import type { ContextKey } from "#context/key.js";+import {+ LiveStepDynamicModelSelectionKey,+ SessionDynamicModelReferenceKey,+ TurnDynamicModelReferenceKey,+ type LiveDynamicModelSelection,+} from "#context/keys.js";+import { createLogger } from "#internal/logging.js";+import type { HandleMessageStreamEvent } from "#protocol/message.js";+import type {+ RuntimeDynamicModelReference,+ RuntimeModelReference,+} from "#runtime/agent/bootstrap.js";+import {+ loadDynamicRuntimeModelDefinition,+ normalizeDynamicRuntimeModelResult,+ shouldMockAuthoredRuntimeModels,+ type ResolvedRuntimeModelSelection,+ type RuntimeModelResolutionScope,+} from "#runtime/agent/resolve-model.js";+import { toErrorMessage } from "#shared/errors.js";+import type { DynamicToolEventName } from "#shared/dynamic-tool-definition.js";++const log = createLogger("dynamic-models");++const ALLOWED_DYNAMIC_MODEL_EVENTS = new Set<DynamicToolEventName>([+ "session.started",+ "turn.started",+ "step.started",+]);++export type ActiveDynamicModelSelection = LiveDynamicModelSelection;++function isDynamicModelEventName(value: string): value is DynamicToolEventName {+ return ALLOWED_DYNAMIC_MODEL_EVENTS.has(value as DynamicToolEventName);+}++function durableKeyForEvent(+ eventType: DynamicToolEventName,+): ContextKey<RuntimeModelReference | null> | undefined {+ switch (eventType) {+ case "session.started":+ return SessionDynamicModelReferenceKey;+ case "turn.started":+ return TurnDynamicModelReferenceKey;+ case "step.started":+ return undefined;+ }+}++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;+ readonly event: HandleMessageStreamEvent;+ readonly fallback: RuntimeModelReference;+ readonly messages: readonly ModelMessage[];+ readonly scope: RuntimeModelResolutionScope;+}): Promise<void> {+ if (input.dynamicModel === undefined) return;+ if (!isDynamicModelEventName(input.event.type)) return;+ if (!input.dynamicModel.eventNames.includes(input.event.type)) return;++ try {+ const definition = await loadDynamicRuntimeModelDefinition({+ dynamicModel: input.dynamicModel,+ scope: input.scope,+ });+ const handler = definition.events[input.event.type];++ if (handler === undefined) {+ setSelectionForEvent(input.ctx, input.event.type, null);+ return;+ }++ const rawResult = await handler(input.event, buildResolveContext(input.ctx, input.messages));+ const selection =+ rawResult === null || rawResult === undefined+ ? null+ : normalizeDynamicRuntimeModelResult({+ fallback: input.fallback,+ result: rawResult,+ });++ if (+ selection !== null &&+ input.event.type !== "step.started" &&+ selection.model !== undefined+ ) {+ log.error(+ `Dynamic model resolver (${input.event.type}) returned a provider object, but session- and turn-scoped model selections must be serializable. Return a model id string for this scope, or use "step.started".`,+ );+ setSelectionForEvent(input.ctx, input.event.type, null);+ return;+ }++ setSelectionForEvent(input.ctx, input.event.type, selection);+ } catch (error) {+ log.error(`Dynamic model resolver (${input.event.type}) threw - skipping.`, {+ error: toErrorMessage(error),+ });+ setSelectionForEvent(input.ctx, input.event.type, null);+ }+}++function setSelectionForEvent(+ ctx: AlsContext,+ eventType: DynamicToolEventName,+ selection: ResolvedRuntimeModelSelection | null,+): void {+ if (eventType === "step.started") {+ // In mock mode drop the live instance so the mock adapter keeps precedence.+ const stored =+ selection !== null && selection.model !== undefined && shouldMockAuthoredRuntimeModels()+ ? { reference: selection.reference }+ : selection;+ ctx.setVirtualContext(LiveStepDynamicModelSelectionKey, stored);+ return;+ }++ const durableKey = durableKeyForEvent(eventType);+ if (durableKey === undefined) return;+ ctx.set(durableKey, selection?.reference ?? null);+}diff --git a/packages/eve/src/context/keys.ts b/packages/eve/src/context/keys.tsindex 691fc24df..05f07015a 100644--- a/packages/eve/src/context/keys.ts+++ b/packages/eve/src/context/keys.ts@@ -4,7 +4,7 @@* `#runtime/sessions/runtime-context-keys.ts`.*/-import type { SystemModelMessage } from "ai";+import type { LanguageModel, SystemModelMessage } from "ai";import type { JsonObject } from "#shared/json.js";import type {@@ -18,6 +18,7 @@ import type {import { ContextKey } from "#context/key.js";import type { SandboxAccess } from "#sandbox/state.js";import type { RunMode } from "#shared/run-mode.js";+import type { RuntimeModelReference } from "#runtime/agent/bootstrap.js";// Re-export so consumers don't need a direct channel/ import.export type { SessionAuthContext, SessionParent, SessionTurn } from "#channel/types.js";@@ -87,6 +88,31 @@ export const SessionCallbackKey = new ContextKey<SessionCallback>("eve.sessionCaexport const SessionKey = new ContextKey<Session>("eve.session");export const SandboxKey = new ContextKey<SandboxAccess>("eve.sandbox");+// ---------------------------------------------------------------------------+// Dynamic model keys+// ---------------------------------------------------------------------------++/** Session-scoped dynamic model selection (from `session.started`). */+export const SessionDynamicModelReferenceKey = new ContextKey<RuntimeModelReference | null>(+ "eve.sessionDynamicModelReference",+);++/** Turn-scoped dynamic model selection (from `turn.started`). */+export const TurnDynamicModelReferenceKey = new ContextKey<RuntimeModelReference | null>(+ "eve.turnDynamicModelReference",+);++export interface LiveDynamicModelSelection {+ /** Live provider instance; absent for string selections, which resolve through the reference. */+ readonly model?: LanguageModel;+ readonly reference: RuntimeModelReference;+}++/** Virtual step-scoped dynamic model selection (from `step.started`); never serialized. */+export const LiveStepDynamicModelSelectionKey = new ContextKey<LiveDynamicModelSelection | null>(+ "eve.liveStepDynamicModelSelection",+);+// ---------------------------------------------------------------------------// Dynamic tool keys// ---------------------------------------------------------------------------diff --git a/packages/eve/src/execution/node-step.ts b/packages/eve/src/execution/node-step.tsindex 19a06abdb..347fb0486 100644--- a/packages/eve/src/execution/node-step.ts+++ b/packages/eve/src/execution/node-step.ts@@ -1,6 +1,7 @@import { jsonSchema, type FlexibleSchema, type LanguageModel } from "ai";import type { Runtime, SessionCapabilities } from "#channel/types.js";+import { dispatchDynamicModelEvent } from "#context/dynamic-model-lifecycle.js";import type { HarnessToolDefinition } from "#harness/execute-tool.js";import { createToolLoopHarness } from "#harness/tool-loop.js";import type { HandleEventFn, HarnessToolMap, StepFn } from "#harness/types.js";@@ -78,6 +79,13 @@ export interface CreateExecutionNodeStepInput {*/export function createExecutionNodeStep(input: CreateExecutionNodeStepInput): StepFn {const resolveModel = createRuntimeModelResolver(input.modelResolutionScope);+ const dispatchModelEvent =+ input.node.turnAgent.dynamicModel === undefined+ ? undefined+ : createRuntimeDynamicModelEventDispatcher(+ input.modelResolutionScope,+ input.node.turnAgent.dynamicModel,+ );const tools = createNodeHarnessTools({ node: input.node });return createToolLoopHarness({abortSignal: input.abortSignal,@@ -87,6 +95,7 @@ export function createExecutionNodeStep(input: CreateExecutionNodeStepInput): SthandleEvent: input.handleEvent,mode: input.mode,onCompaction: preserveFrameworkStateOnCompaction,+ dispatchDynamicModelEvent: dispatchModelEvent,resolveModel,runtimeIdentity: buildRuntimeIdentity(input.node),tools,@@ -104,7 +113,10 @@ function buildRuntimeIdentity(node: ResolvedRuntimeAgentNode): RuntimeIdentity {agentId: node.turnAgent.id,agentName: node.agent.config?.name,eveVersion: packageInfo.version,- modelId: node.turnAgent.model.id,+ modelId:+ node.turnAgent.dynamicModel === undefined+ ? node.turnAgent.model.id+ : `dynamic:${node.turnAgent.model.id}`,};const gitSha = process.env.VERCEL_GIT_COMMIT_SHA?.trim();@@ -131,6 +143,21 @@ function createRuntimeModelResolver(return (modelReference) => resolveRuntimeModelReference(modelReference, scope);}+function createRuntimeDynamicModelEventDispatcher(+ scope: RuntimeModelResolutionScope,+ dynamicModel: NonNullable<ResolvedRuntimeAgentNode["turnAgent"]["dynamicModel"]>,+): NonNullable<Parameters<typeof createToolLoopHarness>[0]["dispatchDynamicModelEvent"]> {+ return (input) =>+ dispatchDynamicModelEvent({+ ctx: input.ctx,+ dynamicModel,+ event: input.event,+ fallback: input.fallback,+ messages: input.messages,+ scope,+ });+}+/*** Resolves unified {@link HarnessToolDefinition}s from the node's registries.*diff --git a/packages/eve/src/execution/session.ts b/packages/eve/src/execution/session.tsindex 91b800646..a4ee56f15 100644--- a/packages/eve/src/execution/session.ts+++ b/packages/eve/src/execution/session.ts@@ -82,6 +82,8 @@ export function createSession(input: CreateSessionInput): HarnessSession {} = {agent: {compactionModelReference: turnAgent.compactionModel,+ dynamicModelDefaultReference:+ turnAgent.dynamicModel === undefined ? undefined : turnAgent.model,modelReference: turnAgent.model,reasoning: turnAgent.reasoning,system: createSessionSystemPrompt({@@ -136,6 +138,8 @@ export function refreshSessionFromTurnAgent(input: {...input.session,agent: {compactionModelReference: input.turnAgent.compactionModel,+ dynamicModelDefaultReference:+ input.turnAgent.dynamicModel === undefined ? undefined : input.turnAgent.model,modelReference: input.turnAgent.model,reasoning: input.turnAgent.reasoning,system: createSessionSystemPrompt({@@ -264,6 +268,8 @@ export function hydrateDurableSession(input: {} = {agent: {compactionModelReference: turnAgent.compactionModel,+ dynamicModelDefaultReference:+ turnAgent.dynamicModel === undefined ? undefined : turnAgent.model,modelReference: turnAgent.model,reasoning: turnAgent.reasoning,system: durable.agent.system,diff --git a/packages/eve/src/execution/workflow-steps.ts b/packages/eve/src/execution/workflow-steps.tsindex a3e2801a7..862b1eb43 100644--- a/packages/eve/src/execution/workflow-steps.ts+++ b/packages/eve/src/execution/workflow-steps.ts@@ -7,6 +7,7 @@ import type {} from "#channel/types.js";import { dispatchStreamEventHooks } from "#context/hook-lifecycle.js";import { dispatchDynamicInstructionEvent } from "#context/dynamic-instruction-lifecycle.js";+import { dispatchDynamicModelEvent } from "#context/dynamic-model-lifecycle.js";import { dispatchDynamicSkillEvent } from "#context/dynamic-skill-lifecycle.js";import { dispatchDynamicToolEvent } from "#context/dynamic-tool-lifecycle.js";import { AuthKey, CapabilitiesKey, ContinuationTokenKey, ModeKey } from "#context/keys.js";@@ -265,6 +266,19 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu): Promise<void> => {const emitted = await emit(event);await dispatchStreamEventHooks({ ctx, registry: hookRegistry, event: emitted });+ if (emitted.type !== "step.started") {+ await dispatchDynamicModelEvent({+ ctx,+ dynamicModel: bundle.turnAgent.dynamicModel,+ event: emitted,+ fallback: bundle.turnAgent.model,+ messages: messages ?? [],+ scope: {+ moduleMap: bundle.moduleMap,+ nodeId: bundle.nodeId,+ },+ });+ }await dispatchDynamicToolEvent({ctx,resolvers: dynamicToolResolvers,diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.tsindex 5e2265a6c..f355bf280 100644--- a/packages/eve/src/harness/tool-loop.test.ts+++ b/packages/eve/src/harness/tool-loop.test.ts@@ -14,11 +14,13 @@ import {AuthKey,ChannelInstrumentationKey,InitiatorAuthKey,+ LiveStepDynamicModelSelectionKey,LiveStepToolsKey,ParentSessionKey,SandboxKey,SessionKey,SessionDynamicInstructionsKey,+ SessionDynamicModelReferenceKey,} from "#context/keys.js";import { SCHEDULE_APP_AUTH } from "#channel/schedule-auth.js";import { decodeSandboxRef, isSandboxRefUrl } from "#internal/attachments/sandbox-refs.js";@@ -628,6 +630,159 @@ describe("createToolLoopHarness", () => {expect(agentCall!.tools).not.toHaveProperty("Workflow");});+ it("uses dynamic model selection for the model call", async () => {+ setupMockAgent({+ finishReason: "stop",+ response: { messages: [{ content: "Hello!", role: "assistant" }] },+ text: "Hello!",+ toolCalls: [],+ toolResults: [],+ });++ const resolveModel = vi.fn().mockResolvedValue("fallback-model" as LanguageModel);+ const dispatchDynamicModelEvent: NonNullable<+ ToolLoopHarnessConfig["dispatchDynamicModelEvent"]+ > = vi.fn(async ({ ctx, event, fallback, messages }) => {+ expect(event.type).toBe("step.started");+ expect(messages.at(-1)).toEqual({ content: "Hi", role: "user" });+ expect(fallback).toEqual({ contextWindowTokens: 100_000, id: "fallback-model" });++ ctx.setVirtualContext(LiveStepDynamicModelSelectionKey, {+ model: "selected-model" as LanguageModel,+ reference: {+ contextWindowTokens: 200_000,+ id: "selected-model",+ providerOptions: { gateway: { order: ["openai"] } },+ },+ });+ });+ const config = createTestConfig("conversation", undefined, {+ dispatchDynamicModelEvent,+ resolveModel,+ });+ const runStep = createToolLoopHarness(config);+ const ctx = new ContextContainer();+ const session = createTestSession({+ agent: {+ dynamicModelDefaultReference: { contextWindowTokens: 100_000, id: "fallback-model" },+ modelReference: { contextWindowTokens: 100_000, id: "fallback-model" },+ system: "You are a test assistant.",+ tools: [{ description: "Adds numbers", name: "add", inputSchema: { type: "object" } }],+ },+ compaction: { recentWindowSize: 10, threshold: 90_000 },+ });++ const result = await contextStorage.run(ctx, () => runStep(session, { message: "Hi" }));++ const agentCall = vi.mocked(ToolLoopAgent).mock.calls[0]?.[0];+ expect(agentCall).toBeDefined();+ expect(agentCall!.model).toBe("selected-model");+ expect(dispatchDynamicModelEvent).toHaveBeenCalledTimes(1);+ expect(resolveModel).not.toHaveBeenCalled();+ expect(result.session.agent.modelReference).toEqual({+ contextWindowTokens: 200_000,+ id: "selected-model",+ providerOptions: { gateway: { order: ["openai"] } },+ });+ expect(result.session.compaction.threshold).toBe(180_000);+ });++ it("uses session-scoped dynamic model selection for the model call", async () => {+ setupMockAgent({+ finishReason: "stop",+ response: { messages: [{ content: "Hello!", role: "assistant" }] },+ text: "Hello!",+ toolCalls: [],+ toolResults: [],+ });++ const resolveModel = vi.fn(async (reference) => {+ expect(reference).toEqual({+ contextWindowTokens: 200_000,+ id: "selected-model",+ providerOptions: { gateway: { order: ["openai"] } },+ });+ return "selected-model" as LanguageModel;+ });+ const config = createTestConfig("conversation", undefined, {+ resolveModel,+ });+ const runStep = createToolLoopHarness(config);+ const ctx = new ContextContainer();+ ctx.set(SessionDynamicModelReferenceKey, {+ contextWindowTokens: 200_000,+ id: "selected-model",+ providerOptions: { gateway: { order: ["openai"] } },+ });+ const session = createTestSession({+ agent: {+ dynamicModelDefaultReference: { contextWindowTokens: 100_000, id: "fallback-model" },+ modelReference: { contextWindowTokens: 100_000, id: "fallback-model" },+ system: "You are a test assistant.",+ tools: [{ description: "Adds numbers", name: "add", inputSchema: { type: "object" } }],+ },+ compaction: { recentWindowSize: 10, threshold: 90_000 },+ });++ const result = await contextStorage.run(ctx, () => runStep(session, { message: "Hi" }));++ const agentCall = vi.mocked(ToolLoopAgent).mock.calls[0]?.[0];+ expect(agentCall).toBeDefined();+ expect(agentCall!.model).toBe("selected-model");+ expect(result.session.agent.modelReference).toEqual({+ contextWindowTokens: 200_000,+ id: "selected-model",+ providerOptions: { gateway: { order: ["openai"] } },+ });+ expect(result.session.compaction.threshold).toBe(180_000);+ });++ it("keeps the compaction threshold stable across steps with the same dynamic selection", async () => {+ setupMockAgent({+ finishReason: "stop",+ response: { messages: [{ content: "Hello!", role: "assistant" }] },+ text: "Hello!",+ toolCalls: [],+ toolResults: [],+ });++ const config = createTestConfig("conversation", undefined, {+ resolveModel: vi.fn().mockResolvedValue("selected-model" as LanguageModel),+ });+ const runStep = createToolLoopHarness(config);+ const ctx = new ContextContainer();+ ctx.set(SessionDynamicModelReferenceKey, {+ contextWindowTokens: 200_000,+ id: "selected-model",+ });+ const session = createTestSession({+ agent: {+ dynamicModelDefaultReference: { contextWindowTokens: 100_000, id: "fallback-model" },+ modelReference: { contextWindowTokens: 100_000, id: "fallback-model" },+ system: "You are a test assistant.",+ tools: [{ description: "Adds numbers", name: "add", inputSchema: { type: "object" } }],+ },+ compaction: { recentWindowSize: 10, threshold: 90_000 },+ });++ const first = await contextStorage.run(ctx, () => runStep(session, { message: "Hi" }));+ expect(first.session.compaction.threshold).toBe(180_000);++ // Regression: the threshold used to compound (360k) on every extra step.+ const second = await contextStorage.run(ctx, () =>+ runStep(first.session, { message: "Again" }),+ );+ expect(second.session.compaction.threshold).toBe(180_000);++ ctx.set(SessionDynamicModelReferenceKey, null);+ const third = await contextStorage.run(ctx, () => runStep(second.session, { message: "Back" }));+ expect(third.session.agent.modelReference).toEqual({+ contextWindowTokens: 100_000,+ id: "fallback-model",+ });+ expect(third.session.compaction.threshold).toBe(90_000);+ });+it("hides subagent tools from the model after the subagent depth limit", async () => {setupMockAgent({finishReason: "stop",diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.tsindex 4f052297a..dc7cc06a5 100644--- a/packages/eve/src/harness/tool-loop.ts+++ b/packages/eve/src/harness/tool-loop.ts@@ -30,6 +30,7 @@ import { formatLanguageModelGatewayId } from "#internal/runtime-model.js";import { contextStorage } from "#context/container.js";import { AuthKey, ParentSessionKey } from "#context/keys.js";import { buildDynamicInstructionMessages } from "#context/dynamic-instruction-lifecycle.js";+import { getActiveDynamicModelSelection } from "#context/dynamic-model-lifecycle.js";import { buildDynamicTools } from "#context/build-dynamic-tools.js";import { PendingSkillAnnouncementKey } from "#context/dynamic-skill-lifecycle.js";import { toErrorMessage } from "#shared/errors.js";@@ -39,6 +40,7 @@ import {createCompactionRequestedEvent,createInputRequestedEvent,createResultCompletedEvent,+ createStepStartedEvent,} from "#protocol/message.js";import type { InstrumentationDefinition } from "#public/instrumentation/index.js";import { ASK_QUESTION_TOOL_NAME } from "#runtime/framework-tools/ask-question.js";@@ -168,6 +170,7 @@ import {buildFinalOutputTool,FINAL_OUTPUT_TOOL_NAME,} from "#runtime/framework-tools/final-output.js";+import type { RuntimeModelReference } from "#runtime/agent/bootstrap.js";import type { RunMode } from "#shared/run-mode.js";import type {CompactionConfig,@@ -285,6 +288,81 @@ function buildGatewayAttributionHeaders(return headers;}+async function resolveActiveRuntimeModel(input: {+ readonly config: ToolLoopHarnessConfig;+ readonly ctx: ReturnType<typeof contextStorage.getStore>;+ readonly session: HarnessSession;+}): Promise<{+ readonly model: LanguageModel;+ readonly session: HarnessSession;+}> {+ if (input.ctx === undefined) {+ return {+ model: await input.config.resolveModel(input.session.agent.modelReference),+ session: input.session,+ };+ }++ const fallback =+ input.session.agent.dynamicModelDefaultReference ?? input.session.agent.modelReference;+ const selected = getActiveDynamicModelSelection(input.ctx);++ if (selected === null) {+ return {+ model: await input.config.resolveModel(fallback),+ session: updateSessionModelReference(input.session, fallback),+ };+ }++ return {+ model:+ selected.model !== undefined+ ? selected.model+ : await input.config.resolveModel(selected.reference),+ session: updateSessionModelReference(input.session, selected.reference),+ };+}++function updateSessionModelReference(+ session: HarnessSession,+ modelReference: RuntimeModelReference,+): HarnessSession {+ // Rescale from the reference the current threshold was computed against;+ // rescaling from the static fallback would compound the threshold per step.+ const priorReference = session.agent.modelReference;+ return {+ ...session,+ agent: {+ ...session.agent,+ modelReference,+ },+ compaction: updateCompactionThresholdForModelReference({+ compaction: session.compaction,+ modelReference,+ priorReference,+ }),+ };+}++function updateCompactionThresholdForModelReference(input: {+ readonly compaction: CompactionConfig;+ readonly modelReference: RuntimeModelReference;+ readonly priorReference: RuntimeModelReference;+}): CompactionConfig {+ if (+ input.modelReference.contextWindowTokens === undefined ||+ input.priorReference.contextWindowTokens === undefined+ ) {+ return input.compaction;+ }++ const thresholdPercent = input.compaction.threshold / input.priorReference.contextWindowTokens;+ return {+ ...input.compaction,+ threshold: Math.max(1, Math.floor(input.modelReference.contextWindowTokens * thresholdPercent)),+ };+}+// ---------------------------------------------------------------------------// Turn trace state — survives step boundaries via session.state// ---------------------------------------------------------------------------@@ -528,7 +606,27 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {// --- Model + tools ------------------------------------------------------- const model = await config.resolveModel(session.agent.modelReference);+ // Direct harness unit tests may run without an ambient context.+ const ctx = contextStorage.getStore();+ if (ctx !== undefined && config.dispatchDynamicModelEvent !== undefined) {+ await config.dispatchDynamicModelEvent({+ ctx,+ event: createStepStartedEvent({+ sequence: emissionState.sequence,+ stepIndex: emissionState.stepIndex,+ turnId: emissionState.turnId,+ }),+ fallback: session.agent.dynamicModelDefaultReference ?? session.agent.modelReference,+ messages,+ });+ }+ const resolvedModel = await resolveActiveRuntimeModel({+ config,+ ctx,+ session,+ });+ session = resolvedModel.session;+ const model = resolvedModel.model;const cachePath = detectPromptCachePath(model);const marker = cachePath.kind === "anthropic-direct" ? getAnthropicCacheMarker() : undefined;@@ -553,8 +651,6 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {const approvedTools = getApprovedTools(session);- // Direct harness unit tests may run without an ambient context.- const ctx = contextStorage.getStore();const emptyDeliveryEnabled =session.outputSchema === undefined &&ctx !== undefined &&diff --git a/packages/eve/src/harness/types.ts b/packages/eve/src/harness/types.tsindex 1ee6d4e9d..818f55807 100644--- a/packages/eve/src/harness/types.ts+++ b/packages/eve/src/harness/types.ts@@ -1,6 +1,7 @@import type { LanguageModel, ModelMessage, UserContent } from "ai";import type { SessionCapabilities } from "#channel/types.js";+import type { AlsContext } from "#context/container.js";import type { HandleMessageStreamEvent, RuntimeIdentity } from "#protocol/message.js";import type { RunMode } from "#shared/run-mode.js";import type { RuntimeActionResult } from "#runtime/actions/types.js";@@ -43,6 +44,8 @@ export interface SessionAgent {* When omitted, the harness uses the active turn model for compaction.*/readonly compactionModelReference?: RuntimeModelReference;+ /** `defineDynamic.fallback` for dynamic-model agents; serves whenever no scoped selection is set. */+ readonly dynamicModelDefaultReference?: RuntimeModelReference;readonly modelReference: RuntimeModelReference;readonly reasoning?: AgentReasoningDefinition;readonly system: string;@@ -260,6 +263,12 @@ export interface ToolLoopHarnessConfig {* compacted history.*/readonly onCompaction?: () => readonly ModelMessage[];+ readonly dispatchDynamicModelEvent?: (input: {+ readonly ctx: AlsContext;+ readonly event: HandleMessageStreamEvent;+ readonly fallback: RuntimeModelReference;+ readonly messages: readonly ModelMessage[];+ }) => Promise<void>;readonly resolveModel: (reference: RuntimeModelReference) => Promise<LanguageModel>;/*** Runtime identity metadata attached to the `session.started` event.diff --git a/packages/eve/src/internal/authored-definition/core.test.ts b/packages/eve/src/internal/authored-definition/core.test.tsindex 2054b1cb2..f1ce81d45 100644--- a/packages/eve/src/internal/authored-definition/core.test.ts+++ b/packages/eve/src/internal/authored-definition/core.test.ts@@ -4,6 +4,7 @@ import {normalizeAgentDefinition,normalizeScheduleDefinition,} from "#internal/authored-definition/core.js";+import { defineDynamic } from "#public/definitions/tool.js";const FAILURE_MESSAGE = "Expected the agent config to match the public eve shape.";@@ -20,6 +21,61 @@ describe("normalizeAgentDefinition", () => {expect(definition.reasoning).toBe("high");});+ it("accepts dynamic model definitions", () => {+ const model = defineDynamic({+ fallback: "openai/gpt-5.5",+ events: {+ "session.started": () => "openai/gpt-5.5-mini",+ },+ });+ const definition = normalizeAgentDefinition(+ {+ model,+ },+ FAILURE_MESSAGE,+ );++ expect(definition.model).toMatchObject({+ fallback: "openai/gpt-5.5",+ kind: "eve:dynamic",+ });+ expect(typeof (definition.model as typeof model).events["session.started"]).toBe("function");+ });++ it("rejects a dynamic model without a fallback", () => {+ expect(() =>+ normalizeAgentDefinition(+ {+ model: defineDynamic({+ events: {+ "session.started": () => "openai/gpt-5.5-mini",+ },+ }),+ },+ FAILURE_MESSAGE,+ ),+ ).toThrow('Dynamic model definitions must include a "fallback" model.');+ });++ it("rejects a dynamic compaction model", () => {+ expect(() =>+ normalizeAgentDefinition(+ {+ compaction: {+ model: defineDynamic({+ fallback: "openai/gpt-5.5-mini",+ events: {+ "session.started": () => "openai/gpt-5.5-mini",+ },+ }),+ },+ model: "openai/gpt-5.5",+ },+ FAILURE_MESSAGE,+ ),+ ).toThrow('"compaction.model" does not support defineDynamic');+ });+it("rejects unsupported reasoning effort", () => {expect(() =>normalizeAgentDefinition(diff --git a/packages/eve/src/internal/authored-definition/core.ts b/packages/eve/src/internal/authored-definition/core.tsindex 0739a4789..57917cf26 100644--- a/packages/eve/src/internal/authored-definition/core.ts+++ b/packages/eve/src/internal/authored-definition/core.ts@@ -14,8 +14,17 @@ import {expectString,getOptionalStringRecordProperty,} from "#internal/authored-module.js";+import type { PublicAgentStaticModelDefinition } from "#shared/agent-definition.js";+import {+ isDynamicSentinel,+ type DynamicEvents,+ type DynamicToolEventName,+} from "#shared/dynamic-tool-definition.js";type Mutable<T> = { -readonly [K in keyof T]: T[K] };+type MutableDynamicEvents = {+ -readonly [K in DynamicToolEventName]?: DynamicEvents[DynamicToolEventName];+};type NormalizedAgentDefinition = Omit<AgentDefinition, "build"> & {build?: {@@ -55,7 +64,7 @@ export function normalizeAgentDefinition(}const definition: Mutable<NormalizedAgentDefinition> = {- model: record.model as NormalizedAgentDefinition["model"],+ model: normalizeAgentModelDefinition(record.model, message),};if (record.description !== undefined) {@@ -128,6 +137,38 @@ function expectPositiveInteger(value: unknown, message: string): number {return value;}+function normalizeAgentModelDefinition(+ value: unknown,+ message: string,+): NormalizedAgentDefinition["model"] {+ // Bare-sentinel check so a fallback-less defineDynamic hits the+ // actionable error below instead of the generic invalid-model path.+ if (!isDynamicSentinel(value)) {+ return value as NormalizedAgentDefinition["model"];+ }++ const record = expectObjectRecord(value, message);+ expectOnlyKnownKeys(record, ["events", "fallback", "kind"], message);++ if (record.fallback === undefined) {+ throw new Error(`${message} Dynamic model definitions must include a "fallback" model.`);+ }++ const rawEvents = expectObjectRecord(record.events, message);+ const events: MutableDynamicEvents = {};+ for (const [eventName, handler] of Object.entries(rawEvents)) {+ events[eventName as DynamicToolEventName] = expectFunction(handler, message) as NonNullable<+ DynamicEvents[DynamicToolEventName]+ >;+ }++ return {+ events,+ fallback: record.fallback as PublicAgentStaticModelDefinition,+ kind: record.kind,+ } as NormalizedAgentDefinition["model"];+}+/** `false` means "explicitly uncapped" for session token limits. */function expectPositiveIntegerOrFalse(value: unknown, message: string): number | false {if (value === false) {@@ -260,7 +301,12 @@ function normalizeAgentCompactionDefinition(const normalizedDefinition: Mutable<NonNullable<NormalizedAgentDefinition["compaction"]>> = {};if (record.model !== undefined) {- normalizedDefinition.model = record.model as NormalizedAgentDefinition["model"];+ if (isDynamicSentinel(record.model)) {+ throw new Error(+ `${message} "compaction.model" does not support defineDynamic — provide a static model.`,+ );+ }+ normalizedDefinition.model = record.model as PublicAgentStaticModelDefinition;}if (record.modelContextWindowTokens !== undefined) {diff --git a/packages/eve/src/internal/authored-definition/schema-backed.test.ts b/packages/eve/src/internal/authored-definition/schema-backed.test.tsindex eb0669184..cbb463454 100644--- a/packages/eve/src/internal/authored-definition/schema-backed.test.ts+++ b/packages/eve/src/internal/authored-definition/schema-backed.test.ts@@ -213,6 +213,19 @@ describe("normalizeToolDefinition", () => {expect(entry.eventNames).toEqual(["session.started"]);});+ it("rejects a defineDynamic tool export carrying a fallback", () => {+ const dynamicTools = defineDynamic({+ fallback: "not-supported-here",+ events: {+ "session.started": async () => ({}),+ },+ });++ expect(() => normalizeToolDefinition(dynamicTools, FAILURE_MESSAGE)).toThrow(+ '"fallback" is only supported on a dynamic agent model',+ );+ });+it("handles defineDynamic with multiple events", () => {const dynamicTools = defineDynamic({events: {diff --git a/packages/eve/src/internal/authored-definition/schema-backed.ts b/packages/eve/src/internal/authored-definition/schema-backed.tsindex 869f5b0de..15e2a8626 100644--- a/packages/eve/src/internal/authored-definition/schema-backed.ts+++ b/packages/eve/src/internal/authored-definition/schema-backed.ts@@ -7,7 +7,11 @@ import {} from "#internal/authored-module.js";import type { InternalToolDefinitionWithExecuteFn } from "#shared/tool-definition.js";import { normalizeJsonSchemaDefinition } from "#internal/json-schema.js";-import { isDynamicSentinel, type DynamicToolEventName } from "#shared/dynamic-tool-definition.js";+import {+ isDynamicSentinel,+ rejectDynamicSentinelFallback,+ type DynamicToolEventName,+} from "#shared/dynamic-tool-definition.js";/*** Canonical normalized shape of one authored tool default export.@@ -45,6 +49,7 @@ type NormalizedToolEntry =*/export function normalizeToolDefinition(value: unknown, message: string): NormalizedToolEntry {if (isDynamicSentinel(value)) {+ rejectDynamicSentinelFallback(value, message);return {kind: "dynamic-tool",eventNames: Object.keys(value.events) as DynamicToolEventName[],diff --git a/packages/eve/src/internal/runtime-model.ts b/packages/eve/src/internal/runtime-model.tsindex 5087d7a6f..2838d7a46 100644--- a/packages/eve/src/internal/runtime-model.ts+++ b/packages/eve/src/internal/runtime-model.ts@@ -11,7 +11,7 @@ import type { LanguageModel } from "ai";* `openai.responses`) to disambiguate request shapes. The Gateway routes on the* top-level provider only, so any segments after the first dot are dropped.*/-export function formatLanguageModelGatewayId(model: LanguageModel): string {+export function formatLanguageModelGatewayId(model: string | LanguageModel): string {if (typeof model === "string") {return model;}diff --git a/packages/eve/src/protocol/message.ts b/packages/eve/src/protocol/message.tsindex 8c42d3f83..eff239f31 100644--- a/packages/eve/src/protocol/message.ts+++ b/packages/eve/src/protocol/message.ts@@ -100,6 +100,7 @@ export interface RuntimeIdentity {readonly gitBranch?: string;readonly gitSha?: string;};+ /** Configured model id; dynamic-model agents report `dynamic:<fallback id>`. */readonly modelId: string;}diff --git a/packages/eve/src/public/definitions/agent.ts b/packages/eve/src/public/definitions/agent.tsindex eede780c9..cf7b5bbf4 100644--- a/packages/eve/src/public/definitions/agent.ts+++ b/packages/eve/src/public/definitions/agent.ts@@ -2,14 +2,20 @@ import type { PublicAgentDefinition } from "#shared/agent-definition.js";import type { ExactDefinition } from "#public/definitions/exact.js";export type {+ AgentModelResolveContext,AgentModelOptionsDefinition,+ AgentModelResolver,AgentReasoningDefinition,AgentBuildDefinition,+ PublicAgentDynamicModelDefinition as AgentDynamicModelDefinition,+ PublicAgentDynamicModelResult as AgentDynamicModelResult,AgentExperimentalDefinition,AgentLimitsDefinition,+ PublicAgentModelSelectionDefinition as AgentModelSelectionDefinition,AgentWorkflowDefinition,AgentWorkflowWorldDefinition,PublicAgentModelDefinition as AgentModelDefinition,+ PublicAgentStaticModelDefinition as AgentStaticModelDefinition,PublicAgentCompactionDefinition as AgentCompactionDefinition,} from "#shared/agent-definition.js";diff --git a/packages/eve/src/public/definitions/tool.ts b/packages/eve/src/public/definitions/tool.tsindex 7af38a376..9349a479d 100644--- a/packages/eve/src/public/definitions/tool.ts+++ b/packages/eve/src/public/definitions/tool.ts@@ -15,10 +15,18 @@ import {DYNAMIC_SENTINEL_KIND,TOOL_BRAND,type DynamicEvents,+ type DynamicEventsWithFallback,type DynamicSentinel,} from "#shared/dynamic-tool-definition.js";type ApprovalContextInput<TInput> = unknown extends TInput ? Record<string, unknown> : TInput;+type DynamicEventMapHandler<TEvents extends DynamicEvents> = Extract<+ NonNullable<TEvents[keyof TEvents]>,+ (...args: never[]) => unknown+>;+type DynamicEventMapResult<TEvents extends DynamicEvents> = Awaited<+ ReturnType<DynamicEventMapHandler<TEvents>>+>;export type { ToolModelOutput } from "#shared/tool-definition.js";@@ -262,11 +270,25 @@ export function defineTool<TInput = unknown, TOutput = unknown>(* whose name matches an authored one overrides it; two dynamic resolvers* emitting the same name is an error.*/-export function defineDynamic(definition: { readonly events: DynamicEvents }): DynamicSentinel {- const sentinel: DynamicSentinel = {+export function defineDynamic<const TEvents extends DynamicEvents>(definition: {+ readonly events: TEvents;+}): DynamicSentinel<DynamicEventMapResult<TEvents>>;+export function defineDynamic<+ const TEvents extends DynamicEventsWithFallback,+ TFallback = unknown,+>(definition: {+ readonly fallback: TFallback;+ readonly events: TEvents;+}): DynamicSentinel<Exclude<DynamicEventMapResult<TEvents>, undefined>, TFallback>;+export function defineDynamic<TResult = unknown, TFallback = unknown>(definition: {+ readonly fallback?: TFallback;+ readonly events: DynamicEvents<TResult>;+}): DynamicSentinel<TResult, TFallback> {+ const sentinel = {kind: DYNAMIC_SENTINEL_KIND,events: definition.events,- };+ ...(Object.hasOwn(definition, "fallback") ? { fallback: definition.fallback } : {}),+ } as DynamicSentinel<TResult, TFallback>;stampDefinitionKey(sentinel, `dynamic:${Object.keys(definition.events).join(",")}`);return sentinel;}diff --git a/packages/eve/src/public/index.ts b/packages/eve/src/public/index.tsindex e32fedae6..04f0536a7 100644--- a/packages/eve/src/public/index.ts+++ b/packages/eve/src/public/index.ts@@ -14,6 +14,8 @@ export {type AgentWorkflowWorldDefinition,defineAgent,} from "#public/definitions/agent.js";+export { defineDynamic } from "#public/definitions/tool.js";+export type { DynamicResolveContext, DynamicSentinel } from "#shared/dynamic-tool-definition.js";export {type RemoteAgentDefinition,type RemoteAgentDefinitionInput,diff --git a/packages/eve/src/runtime/agent/bootstrap.ts b/packages/eve/src/runtime/agent/bootstrap.tsindex 35bfd5a64..e0396746e 100644--- a/packages/eve/src/runtime/agent/bootstrap.ts+++ b/packages/eve/src/runtime/agent/bootstrap.ts@@ -3,6 +3,7 @@ import type { PreparedRuntimeTool } from "#runtime/sessions/turn.js";import type { ResolvedAgent } from "#runtime/types.js";import type { WorkspaceRuntimeSpec } from "#runtime/workspace/types.js";import type { InternalAgentModelDefinition } from "#shared/agent-definition.js";+import type { ModuleSourceRef } from "#shared/source-ref.js";import type { AvailableSkillDescription } from "#execution/skills/instructions.js";/**@@ -16,6 +17,15 @@ export const BOOTSTRAP_RUNTIME_MODEL_ID = "eve-bootstrap-model";*/export type RuntimeModelReference = Readonly<InternalAgentModelDefinition>;+/**+ * Runtime-owned reference to a dynamic model resolver authored in `agent.ts`.+ */+export type RuntimeDynamicModelReference = Readonly<+ ModuleSourceRef & {+ readonly eventNames: readonly string[];+ }+>;+/*** Minimal runtime-owned agent shape prepared for one harness turn.*/@@ -29,6 +39,7 @@ export interface RuntimeTurnAgent {* When omitted, the harness uses the active turn model for compaction.*/readonly compactionModel?: RuntimeModelReference;+ readonly dynamicModel?: RuntimeDynamicModelReference;readonly model: RuntimeModelReference;readonly nodeId?: string;readonly outputSchema?: ResolvedAgent["config"]["outputSchema"];@@ -66,6 +77,7 @@ export function createResolvedRuntimeTurnAgent(input: {workspaceSpec: agent.workspaceSpec,}),compactionModel: agent.config.compaction?.model,+ dynamicModel: agent.config.dynamicModel,model: agent.config.model,nodeId: input.nodeId,outputSchema: agent.config.outputSchema,diff --git a/packages/eve/src/runtime/agent/resolve-model.test.ts b/packages/eve/src/runtime/agent/resolve-model.test.tsnew file mode 100644index 000000000..d723fa469--- /dev/null+++ b/packages/eve/src/runtime/agent/resolve-model.test.ts@@ -0,0 +1,110 @@+import { describe, expect, it } from "vitest";++import { ROOT_COMPILED_AGENT_NODE_ID } from "#compiler/manifest.js";+import type { CompiledModuleMap } from "#compiler/module-map.js";+import { defineDynamic } from "#public/definitions/tool.js";+import {+ loadDynamicRuntimeModelDefinition,+ normalizeDynamicRuntimeModelResult,+} from "#runtime/agent/resolve-model.js";++const DYNAMIC_MODEL_SOURCE = {+ eventNames: ["session.started"],+ logicalPath: "agent.ts",+ sourceId: "agent-config",+ sourceKind: "module" as const,+};++describe("dynamic runtime model resolution", () => {+ it("loads dynamic model definitions and normalizes string selections", async () => {+ const moduleMap = createModuleMap({+ default: {+ model: defineDynamic({+ fallback: "openai/gpt-5.5",+ events: {+ "session.started": (_event, ctx) =>+ ctx.channel.kind === "slack"+ ? {+ model: "openai/gpt-5.5-mini",+ modelContextWindowTokens: 128_000,+ modelOptions: {+ providerOptions: { gateway: { order: ["openai"] } },+ },+ }+ : null,+ },+ }),+ },+ });++ const definition = await loadDynamicRuntimeModelDefinition({+ dynamicModel: DYNAMIC_MODEL_SOURCE,+ scope: { moduleMap, nodeId: undefined },+ });+ const result = await definition.events["session.started"]?.(+ { type: "session.started" },+ {+ channel: { kind: "slack" },+ messages: [{ content: "Hi", role: "user" }],+ session: { auth: { current: null, initiator: null }, id: "session-1" },+ },+ );++ expect(result).not.toBeNull();+ if (result === null || result === undefined) throw new Error("expected selection");++ const resolved = normalizeDynamicRuntimeModelResult({+ fallback: { contextWindowTokens: 256_000, id: "openai/gpt-5.5" },+ result,+ });++ expect(resolved).toEqual({+ reference: {+ contextWindowTokens: 128_000,+ id: "openai/gpt-5.5-mini",+ providerOptions: { gateway: { order: ["openai"] } },+ },+ });+ });++ it("inherits fallback provider options but never the fallback context window", () => {+ const resolved = normalizeDynamicRuntimeModelResult({+ fallback: {+ contextWindowTokens: 256_000,+ id: "openai/gpt-5.5",+ providerOptions: { gateway: { order: ["openai"] } },+ },+ result: "openai/gpt-5.5-mini",+ });++ expect(resolved.reference).toEqual({+ contextWindowTokens: undefined,+ id: "openai/gpt-5.5-mini",+ providerOptions: { gateway: { order: ["openai"] } },+ });+ });++ it("rejects selections with unknown keys", () => {+ expect(() =>+ normalizeDynamicRuntimeModelResult({+ fallback: { id: "openai/gpt-5.5" },+ result: {+ model: "openai/gpt-5.5-mini",+ contextWindowTokens: 128_000,+ } as never,+ }),+ ).toThrowError(/unknown key\(s\): contextWindowTokens/);+ });+});++function createModuleMap(moduleNamespace: Record<string, unknown>): CompiledModuleMap {+ return {+ nodes: {+ [ROOT_COMPILED_AGENT_NODE_ID]: {+ modules: {+ [DYNAMIC_MODEL_SOURCE.sourceId]: moduleNamespace,+ },+ },+ },+ };+}diff --git a/packages/eve/src/runtime/agent/resolve-model.ts b/packages/eve/src/runtime/agent/resolve-model.tsindex 8229a85ae..e013b6ecf 100644--- a/packages/eve/src/runtime/agent/resolve-model.ts+++ b/packages/eve/src/runtime/agent/resolve-model.ts@@ -1,13 +1,26 @@import type { LanguageModel } from "ai";import type { CompiledModuleMap } from "#compiler/module-map.js";import { normalizeAgentDefinition } from "#internal/authored-definition/core.js";-import type { RuntimeModelReference } from "#runtime/agent/bootstrap.js";+import { formatLanguageModelGatewayId } from "#internal/runtime-model.js";+import type {+ RuntimeDynamicModelReference,+ RuntimeModelReference,+} from "#runtime/agent/bootstrap.js";import { resolveBootstrapRuntimeModel } from "#runtime/agent/bootstrap-model.js";import {resolveMockAuthoredRuntimeModel,shouldMockAuthoredRuntimeModels,} from "#runtime/agent/mock-model-adapter.js";import { loadResolvedModuleExport } from "#runtime/resolve-helpers.js";+import {+ isDynamicModelDefinition,+ type AgentModelOptionsDefinition,+ type PublicAgentDynamicModelDefinition,+ type PublicAgentDynamicModelResult,+ type PublicAgentModelSelectionDefinition,+ type PublicAgentStaticModelDefinition,+} from "#shared/agent-definition.js";+import { parseJsonObject, type JsonObject } from "#shared/json.js";export { shouldMockAuthoredRuntimeModels };@@ -17,6 +30,12 @@ export interface RuntimeModelResolutionScope {readonly nodeId: string | undefined;}+export interface ResolvedRuntimeModelSelection {+ /** Live provider instance; absent for string selections, which resolve through the reference so mock/bootstrap adapters keep precedence. */+ readonly model?: LanguageModel;+ readonly reference: RuntimeModelReference;+}+/*** Resolves one runtime model reference into the active language model.*/@@ -73,6 +92,10 @@ async function loadSourceBackedRuntimeModelReference();}+ if (isDynamicModelDefinition(model)) {+ return model.fallback;+ }+return model;}@@ -83,3 +106,154 @@ function isSourceBackedRuntimeModelReference(} {return reference.source !== undefined;}++export async function loadDynamicRuntimeModelDefinition(input: {+ readonly dynamicModel: RuntimeDynamicModelReference;+ readonly scope: RuntimeModelResolutionScope;+}): Promise<PublicAgentDynamicModelDefinition> {+ const definition = await loadResolvedModuleExport({+ definition: input.dynamicModel,+ kindLabel: "dynamic runtime model",+ moduleMap: input.scope.moduleMap,+ nodeId: input.scope.nodeId,+ });+ const normalizedDefinition = normalizeAgentDefinition(+ definition,+ `Expected the authored agent config export "${input.dynamicModel.exportName ?? "default"}" from "${input.dynamicModel.logicalPath}" to match the public eve shape.`,+ );+ const authoredModel = normalizedDefinition.model;++ if (!isDynamicModelDefinition(authoredModel)) {+ throw new Error(+ `Expected the authored agent config export "${input.dynamicModel.exportName ?? "default"}" from "${input.dynamicModel.logicalPath}" to provide a dynamic model definition.`,+ );+ }++ return authoredModel;+}++export function normalizeDynamicRuntimeModelResult(input: {+ readonly fallback: RuntimeModelReference;+ readonly result: NonNullable<PublicAgentDynamicModelResult>;+}): ResolvedRuntimeModelSelection {+ const selection = normalizeDynamicModelSelection(input.result);+ validateDynamicModelSelection(selection);+ const providerOptions =+ selection.modelOptions?.providerOptions === undefined+ ? input.fallback.providerOptions+ : parseProviderOptionsRecord(selection.modelOptions.providerOptions);+ // Never inherited from the fallback: a different model's window is not a safe guess.+ const contextWindowTokens = selection.modelContextWindowTokens;++ if (typeof selection.model === "string") {+ const id = formatLanguageModelGatewayId(selection.model);+ return {+ reference: {+ id,+ contextWindowTokens,+ providerOptions,+ },+ };+ }++ validateRuntimeLanguageModel(selection.model);++ return {+ model: selection.model,+ reference: {+ id: formatLanguageModelGatewayId(selection.model),+ contextWindowTokens,+ providerOptions,+ },+ };+}++const DYNAMIC_MODEL_SELECTION_KEYS = new Set(["model", "modelContextWindowTokens", "modelOptions"]);++function validateDynamicModelSelection(selection: PublicAgentModelSelectionDefinition): void {+ const unknownKeys = Object.keys(selection).filter(+ (key) => !DYNAMIC_MODEL_SELECTION_KEYS.has(key),+ );+ if (unknownKeys.length > 0) {+ throw new Error(+ `Dynamic model resolver returned a selection with unknown key(s): ${unknownKeys.join(", ")}. Expected { model, modelContextWindowTokens?, modelOptions? }.`,+ );+ }++ const contextWindowTokens = selection.modelContextWindowTokens;+ if (+ contextWindowTokens !== undefined &&+ (!Number.isInteger(contextWindowTokens) || contextWindowTokens <= 0)+ ) {+ throw new Error(+ "Dynamic model resolver returned an invalid modelContextWindowTokens value. Expected a positive integer.",+ );+ }+}++function normalizeDynamicModelSelection(+ result: NonNullable<PublicAgentDynamicModelResult>,+): PublicAgentModelSelectionDefinition {+ if (isModelSelectionDefinition(result)) {+ return result;+ }++ return { model: result as PublicAgentStaticModelDefinition };+}++function isModelSelectionDefinition(value: unknown): value is PublicAgentModelSelectionDefinition {+ return (+ typeof value === "object" &&+ value !== null &&+ "model" in value &&+ !isRuntimeLanguageModel(value)+ );+}++function validateRuntimeLanguageModel(model: unknown): asserts model is LanguageModel {+ if (!isRuntimeLanguageModel(model)) {+ throw new Error(+ "Dynamic model resolver returned an invalid model. Return an AI Gateway model id string, an AI SDK language model, or { model, modelContextWindowTokens?, modelOptions? }.",+ );+ }+}++export function isRuntimeLanguageModel(value: unknown): value is LanguageModel {+ if (typeof value !== "object" || value === null) {+ return false;+ }++ const model = value as {+ specificationVersion?: unknown;+ provider?: unknown;+ modelId?: unknown;+ doGenerate?: unknown;+ doStream?: unknown;+ };++ return (+ (model.specificationVersion === "v2" ||+ model.specificationVersion === "v3" ||+ model.specificationVersion === "v4") &&+ typeof model.provider === "string" &&+ typeof model.modelId === "string" &&+ typeof model.doGenerate === "function" &&+ typeof model.doStream === "function"+ );+}++function parseProviderOptionsRecord(+ value: AgentModelOptionsDefinition["providerOptions"],+): Record<string, JsonObject> | undefined {+ if (value === undefined) {+ return undefined;+ }++ const normalized: Record<string, JsonObject> = {};++ for (const [provider, entry] of Object.entries(value)) {+ normalized[provider] = parseJsonObject(entry);+ }++ return normalized;+}diff --git a/packages/eve/src/runtime/resolve-agent.ts b/packages/eve/src/runtime/resolve-agent.tsindex 7f07f9c52..89801eb20 100644--- a/packages/eve/src/runtime/resolve-agent.ts+++ b/packages/eve/src/runtime/resolve-agent.ts@@ -150,6 +150,7 @@ function createResolvedInstructionsDefinition(function createResolvedAgentConfig(manifest: CompiledAgentNodeManifest): ResolvedAgent["config"] {const config: {compaction?: ResolvedAgent["config"]["compaction"];+ dynamicModel?: ResolvedAgent["config"]["dynamicModel"];experimental?: ResolvedAgent["config"]["experimental"];model: ResolvedAgent["config"]["model"];name: string;@@ -213,6 +214,13 @@ function createResolvedAgentConfig(manifest: CompiledAgentNodeManifest): Resolveconfig.compaction = compaction;}+ if (manifest.config.dynamicModel !== undefined) {+ config.dynamicModel = {+ ...createResolvedModuleSourceRef(manifest.config.dynamicModel),+ eventNames: [...manifest.config.dynamicModel.eventNames],+ };+ }+if (manifest.config.experimental !== undefined) {config.experimental = {workflow:diff --git a/packages/eve/src/runtime/types.ts b/packages/eve/src/runtime/types.tsindex 473158973..de8020a8e 100644--- a/packages/eve/src/runtime/types.ts+++ b/packages/eve/src/runtime/types.ts@@ -33,6 +33,7 @@ import type {} from "#shared/source-ref.js";import type { NamedSkillDefinition } from "#shared/skill-definition.js";import type { InternalAgentDefinition } from "#shared/agent-definition.js";+import type { RuntimeDynamicModelReference } from "#runtime/agent/bootstrap.js";import type { InternalToolDefinitionWithExecuteFn } from "#shared/tool-definition.js";import type { SandboxBackend } from "#shared/sandbox-backend.js";import type { SandboxBootstrapContext, SandboxSessionContext } from "#shared/sandbox-definition.js";@@ -302,6 +303,7 @@ export type ResolvedRuntimeDelegationNode =*/export type ResolvedAgentDefinition = Readonly<Omit<InternalAgentDefinition, "build" | "source"> & {+ dynamicModel?: RuntimeDynamicModelReference;source?: Readonly<NonNullable<InternalAgentDefinition["source"]>>;}>;diff --git a/packages/eve/src/shared/agent-definition.ts b/packages/eve/src/shared/agent-definition.tsindex 294cbc0cd..1b6d2ded7 100644--- a/packages/eve/src/shared/agent-definition.ts+++ b/packages/eve/src/shared/agent-definition.ts@@ -2,6 +2,11 @@ import type { CallSettings, LanguageModel } from "ai";import type { StandardJSONSchemaV1 } from "#compiled/@standard-schema/spec/index.js";import type { JsonObject } from "#shared/json.js";import type { ModuleSourceRef } from "#shared/source-ref.js";+import {+ isDynamicSentinel,+ type DynamicResolveContext,+ type DynamicSentinel,+} from "#shared/dynamic-tool-definition.js";/*** Optional overrides that eve forwards to the AI SDK model runtime call for@@ -46,11 +51,55 @@ export type InternalAgentModelDefinition = {};/**- * The model handle you assign to an agent's `model` field. This is the AI SDK- * `LanguageModel` value (for example, the result of a provider or gateway- * model call), not an eve-authored definition object.+ * A concrete model handle: an AI Gateway model id string or an AI SDK+ * `LanguageModel` instance.*/-export type PublicAgentModelDefinition = LanguageModel;+export type PublicAgentStaticModelDefinition = string | LanguageModel;++/** Context passed to dynamic model event handlers; the shared dynamic resolver context. */+export type AgentModelResolveContext = DynamicResolveContext;++export interface PublicAgentModelSelectionDefinition {+ readonly model: PublicAgentStaticModelDefinition;+ /** Context window of the selected model, in tokens; never inherited from the fallback. */+ readonly modelContextWindowTokens?: number;+ /** Provider options for the selected model; defaults to the agent-level `modelOptions`. */+ readonly modelOptions?: AgentModelOptionsDefinition;+}++export type PublicAgentDynamicModelResult =+ | PublicAgentStaticModelDefinition+ | PublicAgentModelSelectionDefinition+ | null;++export type AgentModelResolver = (+ event: unknown,+ ctx: AgentModelResolveContext,+) => PublicAgentDynamicModelResult | Promise<PublicAgentDynamicModelResult>;++export type PublicAgentDynamicModelDefinition = DynamicSentinel<+ PublicAgentDynamicModelResult,+ PublicAgentStaticModelDefinition+>;++export interface PublicAgentDynamicModelDefinitionInput {+ /** Compiled static model: build-time metadata and the active model when no scope is set. */+ readonly fallback: PublicAgentStaticModelDefinition;+ readonly events: DynamicSentinel<PublicAgentDynamicModelResult>["events"];+}++export function isDynamicModelDefinition(+ value: unknown,+): value is PublicAgentDynamicModelDefinition {+ return isDynamicSentinel(value) && "fallback" in value;+}++/**+ * The model handle you assign to an agent's `model` field.+ */+export type PublicAgentModelDefinition =+ | PublicAgentStaticModelDefinition+ | PublicAgentDynamicModelDefinition;export interface InternalAgentCompactionDefinition {/**@@ -87,7 +136,7 @@ export interface PublicAgentCompactionDefinition {** When omitted, eve uses the active turn model for the summary call.*/- readonly model?: PublicAgentModelDefinition;+ readonly model?: PublicAgentStaticModelDefinition;/*** Fraction of the primary model context window that triggers compaction.*@@ -248,8 +297,9 @@ export type PublicAgentDefinition = {*/readonly experimental?: AgentExperimentalDefinition;/**- * Language model used for agent turns. Accepts an AI Gateway model ID or any- * AI SDK-compatible language model.+ * Language model used for agent turns. Accepts an AI Gateway model ID, any AI+ * SDK-compatible language model, or `defineDynamic({ fallback, events })` for+ * scoped dynamic model selection.*/readonly model: PublicAgentModelDefinition;/**diff --git a/packages/eve/src/shared/dynamic-tool-definition.ts b/packages/eve/src/shared/dynamic-tool-definition.tsindex 4eb6f4aa2..207617256 100644--- a/packages/eve/src/shared/dynamic-tool-definition.ts+++ b/packages/eve/src/shared/dynamic-tool-definition.ts@@ -140,11 +140,18 @@ export type DynamicToolEvents = {* the slot directory (tools/ vs skills/) determines the required return,* validated at runtime by the respective resolver.*/-export type DynamicEvents = {+export type DynamicEvents<TResult = unknown> = {readonly [K in DynamicToolEventName]?: (event: unknown,ctx: DynamicResolveContext,- ) => unknown | Promise<unknown>;+ ) => TResult | Promise<TResult>;+};++export type DynamicEventsWithFallback<TResult = unknown> = {+ readonly [K in DynamicToolEventName]?: (+ event: unknown,+ ctx: DynamicResolveContext,+ ) => Exclude<TResult, undefined> | Promise<Exclude<TResult, undefined>>;};/**@@ -153,13 +160,26 @@ export type DynamicEvents = {export const DYNAMIC_SENTINEL_KIND = "eve:dynamic" as const;/**- * Return value of `defineDynamic`: the runtime shape of a- * `defineDynamic({ events })` export, stamped with a sentinel kind the- * compiler/normalizer detects.+ * Return value of `defineDynamic`: the runtime shape of a dynamic export,+ * stamped with a sentinel kind the compiler/normalizer detects. `TFallback`+ * is `never` except for dynamic agent models, the only slot with a fallback.*/-export interface DynamicSentinel {+export type DynamicSentinel<TResult = unknown, TFallback = never> = {readonly kind: typeof DYNAMIC_SENTINEL_KIND;- readonly events: DynamicEvents;+ readonly events: DynamicEvents<TResult>;+} & ([TFallback] extends [never] ? object : { readonly fallback: TFallback });++/**+ * Throws when a dynamic sentinel outside the agent `model` slot carries a+ * `fallback` — anywhere else it would be silently dead configuration.+ */+export function rejectDynamicSentinelFallback(sentinel: DynamicSentinel, message: string): void {+ if (!("fallback" in sentinel)) {+ return;+ }+ throw new Error(+ `${message} "fallback" is only supported on a dynamic agent model (the "model" field in agent.ts). For dynamic tools, skills, and instructions, author a static entry as the default or return null.`,+ );}export function isDynamicSentinel(value: unknown): value is DynamicSentinel {diff --git a/packages/eve/src/source-change/apply-model-name.test.ts b/packages/eve/src/source-change/apply-model-name.test.tsindex 4c1a404b5..c12850296 100644--- a/packages/eve/src/source-change/apply-model-name.test.ts+++ b/packages/eve/src/source-change/apply-model-name.test.ts@@ -89,6 +89,26 @@ describe("applyModelNameToSource", () => {expect(result.kind).toBe("bail");});+ it("bails on a defineDynamic model without touching the fallback literal", async () => {+ const source = `import { defineAgent, defineDynamic } from "eve";++export default defineAgent({+ model: defineDynamic({+ fallback: "anthropic/claude-sonnet-5",+ events: {+ "session.started": () => "anthropic/claude-opus-4.6",+ },+ }),+});+`;+ const result = await applyModelNameToSource(source, "c/d");++ expect(result.kind).toBe("bail");+ if (result.kind !== "bail") return;+ // The fallback string inside defineDynamic must never be rewritten.+ expect(result.reason).toContain("defineDynamic");+ });+it("bails when there is no defineAgent call", async () => {const result = await applyModelNameToSource(`export const x = 1;\n`, "c/d");diff --git a/packages/eve/src/source-change/apply-model-name.ts b/packages/eve/src/source-change/apply-model-name.tsindex 1d4c29d09..d85a25d42 100644--- a/packages/eve/src/source-change/apply-model-name.ts+++ b/packages/eve/src/source-change/apply-model-name.ts@@ -105,7 +105,7 @@ export async function applyModelNameToSource(return {kind: "bail",reason:- "`model` is absent or is not a string literal (e.g. an env reference, a template, or an inlined SDK model)",+ "`model` is absent or is not a string literal (e.g. an env reference, a template, an inlined SDK model, or a defineDynamic() dynamic model)",line: lineAt(sourceText, object.start ?? 0),};}diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 59e9c6363..f018a324b 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -575,6 +575,19 @@ importers:specifier: 'catalog:'version: 7.0.1-rc+ e2e/fixtures/agent-model:+ dependencies:+ eve:+ specifier: workspace:*+ version: link:../../../packages/eve+ devDependencies:+ '@types/node':+ specifier: 'catalog:'+ version: 25.9.1+ typescript:+ specifier: 'catalog:'+ version: 7.0.1-rc+e2e/fixtures/agent-openapi-swagger:dependencies:'@opentelemetry/core':diff --git a/research/dynamic-model.md b/research/dynamic-model.mdindex 0bc1311bc..06932e824 100644--- a/research/dynamic-model.md+++ b/research/dynamic-model.md@@ -1,6 +1,6 @@---issue: https://github.com/vercel/eve/issues/577-status: proposed+status: in-reviewlast_updated: "2026-07-07"---@@ -15,148 +15,136 @@ blocks routing cheap channels to a smaller model, picking a model per tenant froescalating to a larger-context model as a conversation grows, and per-session A/B tests.This plan extends the existing `model` field to accept the same `defineDynamic` sentinel used-everywhere else. The runtime seam already exists — the harness resolves-`session.agent.modelReference` once per step, immediately before every model call-(`harness/tool-loop.ts`) — so dynamic resolution slots into the established dispatch → durable+everywhere else, with one addition: a required `fallback` model. The fallback is the compiled+static model, which keeps every compile-time surface (routing classification, gateway credential+checks, catalog context-window lookup, agent-info) working unchanged. The runtime seam already+exists — the harness resolves `session.agent.modelReference` immediately before every model call+(`harness/tool-loop.ts`) — so dynamic selection slots into the established dispatch → durablecontext → tool-loop pipeline that dynamic instructions use today.+Implementation: vercel/eve#581.+## Authoring API-`model` becomes a union: a static value (unchanged) or a `defineDynamic({ events })` sentinel.+`model` becomes a union: a static value (unchanged) or `defineDynamic({ fallback, events })`.```ts// agent/agent.ts-import { defineAgent, defineDynamic, defineModel } from "eve";-import { anthropic } from "@ai-sdk/anthropic";+import { defineAgent, defineDynamic } from "eve";export default defineAgent({model: defineDynamic({+ fallback: "anthropic/claude-sonnet-5",events: {- "session.started": () => "anthropic/claude-sonnet-5",- "turn.started": (event, ctx) => {+ "session.started": (event, ctx) => {if (ctx.channel.kind === "slack") return "anthropic/claude-haiku-4.5";- if (needsDeepReasoning(ctx.messages)) return anthropic("claude-opus-4-8");- if (isHugeContext(ctx.messages))- return defineModel({- model: "google/gemini-3-pro",- contextWindowTokens: 1_000_000,- providerOptions: { google: { thinkingConfig: { thinkingBudget: 0 } } },- });- return null; // keep the session-scope choice+ if (isEnterprise(ctx.session.auth)) return "anthropic/claude-opus-4.8";+ return null; // use the fallback},},}),});```+- `fallback` (required) is the build-time model: compiled metadata, compaction defaults, and the+ active model whenever no scoped selection is set.- Handlers receive the standard `(event, ctx)` pair with the shared `DynamicResolveContext`(`session.id`, `session.auth`, `channel`, `messages`).- Handlers return one of:- a gateway model id string (`"anthropic/claude-haiku-4.5"`);- - a live AI SDK `LanguageModel` instance;- - `defineModel({ model, contextWindowTokens?, providerOptions? })` — the branded entry form,- where `model` is a gateway id or a live instance;- - `null` — leave this scope's slot unchanged.-- `defineModel` and `defineDynamic` are exported from the root `eve` entrypoint, next to- `defineAgent`. A `DynamicModelEvents` type gives authoring-time return checking, mirroring- `DynamicToolEvents`.-- `compaction.model` stays static-only. When the primary model is dynamic, compaction falls back to- the active dynamic reference exactly as it falls back to the static model today.+ - a live AI SDK `LanguageModel` instance (`step.started` scope only);+ - a selection object `{ model, modelContextWindowTokens?, modelOptions? }`, mirroring the+ agent-level field names, for selections that need their own metadata;+ - `null` — leave this scope's slot unset.+- `defineDynamic` and the `DynamicResolveContext` type are exported from the root `eve`+ entrypoint, next to `defineAgent`.+- `compaction.model` stays static-only and rejects the sentinel with a dedicated error. When the+ primary model is dynamic, compaction falls back to the active selection exactly as it falls back+ to the static model today.## Semantics-- **Events.** `session.started` and `turn.started` only, enforced like- `ALLOWED_DYNAMIC_INSTRUCTION_EVENTS`. The model is stable within a turn: it is the most- cache-sensitive input to the wire format, and a mid-turn switch would also scramble turn-level- telemetry and compaction accounting.-- **Precedence.** Turn result overrides session result. `null` keeps the current slot, so a- `turn.started` handler that returns `null` falls back to the `session.started` choice.-- **No silent default.** A dynamic `model` has no static fallback. If no scope has produced a model- when the first step needs one (all handlers returned `null`, or a handler threw), the turn fails- with an error naming the agent config and the events that ran. Pre-1.0 we prefer a loud failure- over an invisible default model.-- **Scope stability.** A resolved model is pinned for its scope. Serializable results (gateway id- strings and string-backed `defineModel` entries) are pinned durably and survive workflow replay- without re-invoking the handler — a non-deterministic resolver (per-session A/B) cannot flip- mid-scope. Live-instance results cannot cross a step boundary; they are pinned in-process and the- resolver is re-invoked after replay (park/resume). Live-instance resolvers must therefore be- deterministic per scope; this is documented, matching the inline-`execute` replay constraint on- dynamic tools.-- **Context window.** A dynamic reference has no compile-time catalog lookup.- `defineModel({ contextWindowTokens })` sets the compaction trigger for that scope; otherwise the- authored `modelContextWindowTokens` applies; otherwise the token-based compaction trigger is- inactive, as today for unknown models. Docs recommend setting one of the two when switching- between models with different windows.-- **Mocks first.** The bootstrap and eval mock-model short-circuits in- `resolveRuntimeModelReference` keep precedence over dynamic resolution, so `eve eval` mock mode- stays deterministic.+- **Events and scopes.** `session.started`, `turn.started`, and `step.started`. Precedence: step >+ turn > session > `fallback`; `null` leaves a scope unset so resolution falls through to the next+ scope. `session.started` is the documented default — model identity is almost always a function+ of session-stable facts, and **every model switch invalidates the provider prompt cache** (caches+ are per model). The docs carry an explicit warning that turn/step switching re-ingests the whole+ conversation at uncached prices on every flip.+- **Serialization boundary.** Session- and turn-scoped selections are stored durably (context keys+ `Session/TurnDynamicModelReferenceKey`) and must be serializable — a resolver returning a live+ provider instance from those scopes logs an error and leaves the scope unset. Live instances are+ step-scoped only: held in virtual (non-serialized) context and re-resolved every step, the same+ pattern as live step-scoped dynamic tools.+- **Degrade to fallback, never fail the turn.** A resolver that throws or returns an invalid+ selection logs an error and clears its scope; the turn proceeds on the next scope or `fallback`.+ This matches the dynamic tools/skills/instructions failure posture and is documented — a broken+ resolver silently serves the fallback, so resolvers backed by external services need monitoring.+- **Context window.** `modelContextWindowTokens` on a selection sets the compaction trigger for+ that scope. It is **never inherited from the fallback** — a different model's window is not a+ safe guess. A selection without it has no known window and the compaction threshold keeps using+ the last known window. The threshold rescales against the reference it was computed from (the+ session's current model reference), so repeated steps on one selection are idempotent, and+ clearing a selection restores the fallback-derived threshold.+- **Mocks keep precedence.** String selections are stored reference-only and resolve through+ `resolveRuntimeModelReference`, where the bootstrap and eval mock adapters short-circuit first.+ In mock mode (`NODE_ENV=test`, `EVE_MOCK_AUTHORED_MODELS=1`), live step-scoped instances are+ also stripped to reference-only so `eve eval` mock runs never hit real providers.- **Static form unchanged.** `model: "anthropic/claude-sonnet-5"` and `model: anthropic(...)`- compile, route, and resolve exactly as before, including catalog-derived context windows and the- TUI `/model` rewrite. `/model` detects a dynamic config and reports that it cannot rewrite it.+ compile, route, and resolve exactly as before. The TUI `/model` command rewrites only plain+ string literals; on a `defineDynamic` model it bails to the manual-edit path (it never rewrites+ the `fallback` literal).+- **Observability.** The `session.started` runtime identity reports a dynamic agent's model as+ `dynamic:<fallback id>` — per-scope selections happen after that identity is built. Build-time+ validation (routing, credentials, catalog) applies to the fallback only; a resolver can select a+ model the deployment has no credentials for, which fails at request time.## Data flow```text-compile agent.ts model = DynamicSentinel- └─ manifest model ref { id: "dynamic", dynamic: true, source, routing: { kind: "dynamic" } }+compile agent.ts model = defineDynamic({ fallback, events })+ ├─ manifest config.model = compiled fallback (id, routing, window — unchanged path)+ └─ manifest config.dynamicModel = { eventNames, source ref to agent.ts }boot resolve-agent- └─ re-import agent.ts from the module map, reattach events → dynamicModelResolver+ └─ dynamicModel source ref → RuntimeTurnAgent.dynamicModelrun workflow-steps handleEvent (session.started / turn.started)- └─ dispatchDynamicModelEvent- ├─ string / defineModel(string) → durable Session/TurnDynamicModelKey { id, ... }- └─ live instance → virtual live key + durable { live: true } marker--step tool-loop model resolution- └─ getActiveDynamicModel(ctx): turn > session; re-invoke resolver on live marker- └─ resolveModel(active ?? session.agent.modelReference)+ └─ dispatchDynamicModelEvent → re-import agent.ts, run handler+ ├─ string / selection object → durable Session/TurnDynamicModelReferenceKey+ └─ live instance → error at these scopes (scope cleared)++step tool-loop (before compaction and the model call)+ ├─ dispatch synthetic step.started → virtual LiveStepDynamicModelSelectionKey+ └─ getActiveDynamicModelSelection: step > turn > session > fallback+ ├─ live instance → used directly (stripped in mock mode)+ └─ reference → resolveModel (bootstrap/mock adapters first)+ └─ session.agent.modelReference + compaction threshold updated per step```-The active reference also feeds the other `session.agent.modelReference` consumers: web-search-backend selection, compaction fallback, and per-step `providerOptions`. Gateway attribution headers-and prompt-cache path detection already derive from the resolved model object and need no change.--## Compile-time surface--- `normalizeAgentDefinition` accepts the sentinel for `model` (validating event names and handler- functions) and rejects it under `compaction.model`.-- `ModelRouting` gains `{ kind: "dynamic" }`. Credential checks (`info.ts`,- `resolve-model-endpoint-status.ts`, TUI setup issues) treat it as gateway-credentials-recommended,- since string results route through the gateway; agent-info passes it through.-- The compiled reference stores the agent-config `source` ref (the mechanism source-backed static- instances already use), so runtime can reattach handlers with no emitted code.+The updated session reference flows to the other consumers unchanged: web-search backend+selection, compaction model fallback, per-step `providerOptions`, and gateway attribution headers+derive from the active reference or the resolved model object.## Out of scope- Dynamic `compaction.model`.-- A `step.started` event (mid-turn switching).-- A runtime model catalog (context windows for dynamic references come from the author).-- Subagent-specific behavior: each node's `agent.ts` compiles independently, so subagents get- dynamic models for free through the same path.+- A runtime model catalog (context windows for dynamic selections come from the author).+- Per-selection routing/credential validation at build time.+- Remote subagents; local subagent nodes compile their own `agent.ts` and get dynamic models+ through the same path.## Delivery and verification-One PR with a patch changeset:--1. Types + `defineModel` + root exports; normalization; compiler + manifest schema + routing- consumers.-2. `runtime/resolve-dynamic-model.ts`, `context/dynamic-model-lifecycle.ts`, dispatch wiring in- `execution/workflow-steps.ts`, harness consumption in `tool-loop.ts` / `tools.ts` /- `compaction.ts` / `step-hooks.ts`.-3. Docs: `docs/agent-config.md` model section and `docs/guides/dynamic-capabilities.md` gain the- model capability, its events, and the live-instance determinism note.--Tests:--- unit: `dynamic-model-lifecycle.test.ts` mirroring `dynamic-instruction-lifecycle.test.ts`- (pinning, precedence, null, unbranded and throwing resolvers, live marker after replay);- `core.test.ts` normalization; `normalize-agent-config` compile cases; `tool-loop.test.ts` cases- asserting the override reference reaches `resolveModel`, provider tools, and compaction; the- no-model-resolved failure.-- e2e: a fixture eval (new `e2e/fixtures/agent-model`) proving a `turn.started` switch between two- real models based on channel metadata, deterministic and self-contained beyond model-provider- credentials.--Run the repository's required unit, integration, scenario, typecheck, lint, format, invariant,-docs, and build checks.+Shipped in one PR (vercel/eve#581) with a patch changeset: shared types + normalization, compiler ++manifest (`config.dynamicModel`, schema v33), runtime resolver reattachment, dispatch lifecycle+(`context/dynamic-model-lifecycle.ts`), harness consumption, docs+(`docs/agent-config.md`, `docs/guides/dynamic-capabilities.md`), and tests:++- unit: lifecycle (scope pinning, precedence, null fallback, live-instance rejection at+ session/turn, mock-mode stripping, throwing resolvers, unknown-key selections), normalization+ (missing `fallback`, dynamic `compaction.model` rejection), compile (fallback compiled as the+ static model, resolver source preserved), harness (selection reaches the model call, compaction+ threshold stable across steps of one selection and restored when cleared), `/model` rewrite+ bails on `defineDynamic`.+- e2e: `e2e/fixtures/agent-model` evals — fallback turn with `dynamic:` runtime identity, per-turn+ selection plus null fallback in one session, and throwing-resolver degradation.