Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

Reimplement dynamic agent configuration without fallbacks (#1946)

Casey Gowrieccaa59610dbe
diff --git a/.changeset/dynamic-agent-resolution.md b/.changeset/dynamic-agent-resolution.md
new file mode 100644
index 000000000..a5e0c285c
--- /dev/null
+++ b/.changeset/dynamic-agent-resolution.md
@@ -0,0 +1,5 @@
+---
+"eve": minor
+---
+
+Dynamic models and subagents now resolve without compiled fallbacks or placeholder configs. `defineDynamic` accepts only `events`; dynamic model handlers must return a concrete selection, while runtime model metadata is normalized and cached when the selection becomes active.
diff --git a/docs/agent-config.md b/docs/agent-config.md
index 2fbde3dc2..3faddf5ab 100644
--- a/docs/agent-config.md
+++ b/docs/agent-config.md
@@ -49,21 +49,23 @@ Model use is subject to the terms, data-processing commitments, retention behavi
### 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.
+`model` also accepts `defineDynamic({ events })`. Each matching handler must
+return the concrete model for its scope; a dynamic model has no compiled
+default.
```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,
+ "session.started": (_event, ctx) => {
+ if (ctx.session.auth.initiator?.attributes.plan === "enterprise") {
+ return "anthropic/claude-opus-4.8";
+ }
+
+ return "anthropic/claude-sonnet-5";
+ },
},
}),
});
@@ -72,24 +74,28 @@ export default defineAgent({
Handlers receive the shared [dynamic resolver
context](./guides/dynamic-capabilities) (`ctx.session`, `ctx.channel`,
`ctx.messages`) and return a gateway model id, an AI SDK `LanguageModel`, a
-selection object, or `null` to leave the scope unset.
+selection object. Returning `null` or `undefined` fails the turn.
- **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.
+ session. Prefer `session.started`: prompt caches are per model, so every
+ switch re-ingests the conversation at uncached prices. If no active
+ selection exists before model-dependent work begins, the turn fails.
+- **Failures stop the turn.** A resolver that throws, returns no model, or
+ returns an invalid selection fails before the provider call. A selected
+ model without valid 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>`.
+ When `modelContextWindowTokens` is omitted, eve resolves it from the AI
+ Gateway catalog and caches successful metadata in durable session state for
+ 24 hours. Set it explicitly for an unlisted or custom model. Dynamic agents
+ cannot set sibling `modelContextWindowTokens` or `modelOptions` fields;
+ return per-model values from the handler.
+
+The `session.started` runtime identity does not include a model id for a
+dynamic agent. Each public `step.started` event reports the concrete `modelId`
+selected for that model call.
## Reasoning effort
diff --git a/docs/guides/dynamic-capabilities.md b/docs/guides/dynamic-capabilities.md
index a82419b47..daa013d73 100644
--- a/docs/guides/dynamic-capabilities.md
+++ b/docs/guides/dynamic-capabilities.md
@@ -7,26 +7,26 @@ description: "Resolve models, subagents, tools, skills, and instructions at runt
## 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
+The `model` field in `agent.ts` accepts `defineDynamic({ events })`. Resolvers
+run at `session.started`, `turn.started`, or `step.started` (precedence: step >
+turn > session). Every matching handler must return a concrete model. A
+missing, invalid, or throwing selection fails the turn before model-dependent
+work begins. 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.
-The agent always needs exactly one model, so the compiled fallback anchors
-build-time metadata. Tools, skills, instructions, and subagents default by
-authoring a static entry (or returning `null`), so `fallback` on their
-`defineDynamic` export is a build error.
+Dynamic models do not compile a default model or model metadata. When a
+resolver first selects a model, eve normalizes the selection and resolves any
+omitted context-window metadata from the AI Gateway catalog. Dynamic tools,
+skills, instructions, and subagents may return `null` to omit a capability.
## Dynamic subagents
Wrap a declared subagent's own `agent.ts` in `defineDynamic` when its
availability depends on the caller, tenant, environment, or a feature flag.
-Return the child definition to configure and expose it. Return `null` or
-`undefined` to omit it from the parent's model-visible tools.
+Return the child definition to configure and expose it. Return `null` to omit
+it from the parent's model-visible tools.
```ts title="agent/subagents/finance/agent.ts"
import { defineAgent, defineDynamic } from "eve";
@@ -44,15 +44,19 @@ export default defineDynamic({
});
```
-eve always compiles the subagent's filesystem manifest, including its
-instructions, tools, skills, connections, sandbox, and nested subagents. When
-the resolver selects it, eve injects the returned agent configuration into that
-compiled manifest. Each resolution can return a different model or other
-runtime agent settings. Runtime-selected models must use string model IDs;
-build and Workflow-world configuration cannot be selected at runtime.
+eve always compiles the subagent's filesystem resources, including its
+instructions, tools, skills, connections, sandbox, and nested subagents. It
+does not compile an agent config or placeholder model for a dynamic subagent.
+When the resolver selects the subagent, eve combines the returned config with
+those resources before starting the child session. Each resolution can return
+a different model or other runtime agent settings. A returned local config
+must use a static model; it cannot contain another `defineDynamic` model.
+Runtime-selected models must use string model IDs. Put build configuration on
+the outer `defineDynamic` definition; build and Workflow-world configuration
+cannot be selected in a handler result.
A single-file remote subagent uses the same lifecycle. Return
-`defineRemoteAgent(...)` to expose the selected deployment, or nil to omit it:
+`defineRemoteAgent(...)` to expose the selected deployment, or `null` to omit it:
```ts title="agent/subagents/finance.ts"
import { defineDynamic, defineRemoteAgent } from "eve";
@@ -77,7 +81,7 @@ outbound request without entering durable workflow state.
Dynamic subagents support `session.started` and `turn.started`. A turn selection
shadows the session selection for that turn, including when the turn handler
-returns nil. If a resolver throws or returns an invalid definition, eve logs the
+returns `null`. If a resolver throws or returns an invalid definition, eve logs the
failure and omits the subagent.
The resolved set applies to local and remote direct delegation and the
diff --git a/e2e/README.md b/e2e/README.md
index e2cfcf843..2ece0ed7d 100644
--- a/e2e/README.md
+++ b/e2e/README.md
@@ -29,7 +29,7 @@ Fixture agents author their harness-owned configuration through the private
- `e2eSubagentConfig({ mock? })` — the same model resolution for subagents,
without root-only settings.
- `e2eModel({ mock? })` — a bare model handle for nested slots such as
- compaction models and dynamic fallbacks.
+ compaction models and dynamic selections.
- `e2eJudgeModel()` — the judge model for `evals.config.ts`.
When `EVE_E2E_MODEL=mock`, all of these return a deterministic `mockModel()`
diff --git a/e2e/fixtures/agent-model/agent/agent.ts b/e2e/fixtures/agent-model/agent/agent.ts
index 3cce7474b..8309ed444 100644
--- a/e2e/fixtures/agent-model/agent/agent.ts
+++ b/e2e/fixtures/agent-model/agent/agent.ts
@@ -1,21 +1,18 @@
import { e2eAgentConfig, e2eModel } from "@eve-e2e/config";
-import { defineAgent, defineDynamic, type DynamicResolveContext } from "eve";
+import { defineAgent, defineDynamic, type AgentDefinition, type DynamicResolveContext } from "eve";
const model = e2eModel();
+const { experimental } = e2eAgentConfig();
/**
- * 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.
+ * Dynamic-model e2e fixture. Resolves at `step.started` so live model objects
+ * exercise the same selection, omission, and failure paths as gateway ids.
*/
-export default defineAgent({
- // Harness config wires the workflow world; the dynamic definition below
- // overrides the harness model.
- ...e2eAgentConfig(),
+const agent: AgentDefinition = defineAgent({
+ experimental,
model: defineDynamic({
- fallback: model,
events: {
- "turn.started": (_event, ctx) => {
+ "step.started": (_event, ctx) => {
const text = lastUserText(ctx.messages);
if (text.includes("[model: boom]")) {
@@ -29,12 +26,22 @@ export default defineAgent({
};
}
- return null;
+ if (text.includes("[model: catalog]")) {
+ return model;
+ }
+
+ if (text.includes("[model: missing]")) {
+ return null as never;
+ }
+
+ return { model, modelContextWindowTokens: 1_000_000 };
},
},
}),
});
+export default agent;
+
function lastUserText(messages: DynamicResolveContext["messages"]): string {
for (let index = messages.length - 1; index >= 0; index -= 1) {
const message = messages[index];
diff --git a/e2e/fixtures/agent-model/evals/dynamic-model/catalog-cache.eval.ts b/e2e/fixtures/agent-model/evals/dynamic-model/catalog-cache.eval.ts
new file mode 100644
index 000000000..afe2955fe
--- /dev/null
+++ b/e2e/fixtures/agent-model/evals/dynamic-model/catalog-cache.eval.ts
@@ -0,0 +1,27 @@
+import { defineEval } from "eve/evals";
+
+const model = process.env.EVE_E2E_MODEL ?? "openai/gpt-5.6-sol";
+
+export default defineEval({
+ tags: ["real-model"],
+ description: "Dynamic model smoke: runtime catalog metadata is reusable across turns.",
+ async test(t) {
+ const first = await t.send(
+ '[model: catalog] Reply with exactly the text "catalog one" and nothing else.',
+ );
+ first.expectOk();
+ first.messageIncludes("catalog one");
+
+ const second = await t.send(
+ '[model: catalog] Reply with exactly the text "catalog two" and nothing else.',
+ );
+ second.expectOk();
+ second.messageIncludes("catalog two");
+ second.eventsSatisfy("the model call is attributed to the selected model", (events) =>
+ events.some((event) => event.type === "step.started" && event.data.modelId === model),
+ );
+
+ t.succeeded();
+ t.usedNoTools();
+ },
+});
diff --git a/e2e/fixtures/agent-model/evals/dynamic-model/fallback.eval.ts b/e2e/fixtures/agent-model/evals/dynamic-model/fallback.eval.ts
deleted file mode 100644
index b7b391c69..000000000
--- a/e2e/fixtures/agent-model/evals/dynamic-model/fallback.eval.ts
+++ /dev/null
@@ -1,25 +0,0 @@
-import { defineEval } from "eve/evals";
-
-const model = process.env.EVE_E2E_MODEL ?? "openai/gpt-5.6-sol";
-
-/**
- * No selection marker: the resolver returns `null`, the fallback serves the
- * turn, and the runtime identity reports `dynamic:<fallback id>`.
- */
-export default defineEval({
- tags: ["real-model"],
- 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:${model}`,
- ),
- );
- },
-});
diff --git a/e2e/fixtures/agent-model/evals/dynamic-model/missing-selection.eval.ts b/e2e/fixtures/agent-model/evals/dynamic-model/missing-selection.eval.ts
new file mode 100644
index 000000000..4c989e068
--- /dev/null
+++ b/e2e/fixtures/agent-model/evals/dynamic-model/missing-selection.eval.ts
@@ -0,0 +1,17 @@
+import { defineEval } from "eve/evals";
+
+export default defineEval({
+ description: "Dynamic model smoke: a missing selection fails the turn.",
+ async test(t) {
+ const turn = await t.send("[model: missing] This turn must fail before a model call.");
+
+ turn.eventsSatisfy("the turn reports a missing dynamic model selection", (events) =>
+ events.some(
+ (event) =>
+ event.type === "turn.failed" &&
+ event.data.message.includes("Dynamic model resolver returned no model"),
+ ),
+ );
+ turn.usedNoTools();
+ },
+});
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.ts
index 3debf82f9..c98fc4dc4 100644
--- a/e2e/fixtures/agent-model/evals/dynamic-model/resolver-failure.eval.ts
+++ b/e2e/fixtures/agent-model/evals/dynamic-model/resolver-failure.eval.ts
@@ -1,13 +1,17 @@
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.",
+ description: "Dynamic model smoke: a throwing resolver fails the turn.",
async test(t) {
- await t.send('[model: boom] Reply with exactly the text "still here" and nothing else.');
+ const turn = await t.send("[model: boom] This turn must fail before a model call.");
- t.succeeded();
- t.messageIncludes("still here");
- t.usedNoTools();
+ turn.eventsSatisfy("the turn reports the resolver exception", (events) =>
+ events.some(
+ (event) =>
+ event.type === "turn.failed" &&
+ event.data.message.includes("intentional resolver failure"),
+ ),
+ );
+ turn.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.ts
index 74550d36d..dc36f5190 100644
--- a/e2e/fixtures/agent-model/evals/dynamic-model/turn-selection.eval.ts
+++ b/e2e/fixtures/agent-model/evals/dynamic-model/turn-selection.eval.ts
@@ -1,12 +1,11 @@
import { defineEval } from "eve/evals";
/**
- * A marked turn selects an explicit reference to `EVE_E2E_MODEL`; the next
- * unmarked turn falls back to the same matrix-selected model. Both completing
- * proves the selection and fallback paths serve real model calls.
+ * Both turns select the matrix model independently. The first uses a smaller
+ * explicit context window so the session exercises metadata replacement.
*/
export default defineEval({
- description: "Dynamic model smoke: per-turn selection and null fallback in one session.",
+ description: "Dynamic model smoke: concrete per-turn selections in one session.",
async test(t) {
const selected = await t.send(
'[model: mini] Reply with exactly the text "mini ping" and nothing else.',
@@ -14,9 +13,11 @@ export default defineEval({
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");
+ const selectedAgain = await t.send(
+ 'Reply with exactly the text "selected again" and nothing else.',
+ );
+ selectedAgain.expectOk();
+ selectedAgain.messageIncludes("selected again");
t.succeeded();
t.usedNoTools();
diff --git a/e2e/fixtures/agent-subagents/agent/subagents/conditional-marker/agent.ts b/e2e/fixtures/agent-subagents/agent/subagents/conditional-marker/agent.ts
index 57b92a7c1..d50e69abf 100644
--- a/e2e/fixtures/agent-subagents/agent/subagents/conditional-marker/agent.ts
+++ b/e2e/fixtures/agent-subagents/agent/subagents/conditional-marker/agent.ts
@@ -11,6 +11,7 @@ export default defineDynamic({
model: mockMode
? "eve-mock/dynamic-subagent"
: e2eSubagentConfig({ mock: "DYNAMIC_SUBAGENT_ENABLED" }).model,
+ modelContextWindowTokens: 1_000_000,
}),
},
});
diff --git a/e2e/fixtures/e2e-config/src/index.ts b/e2e/fixtures/e2e-config/src/index.ts
index 32f960bea..9c2235156 100644
--- a/e2e/fixtures/e2e-config/src/index.ts
+++ b/e2e/fixtures/e2e-config/src/index.ts
@@ -1,4 +1,4 @@
-import type { AgentDefinition } from "eve";
+import type { AgentDefinition, AgentStaticModelDefinition } from "eve";
import { mockModel, type MockModelResponder } from "eve/evals";
/**
@@ -17,18 +17,23 @@ const DEFAULT_MODEL = "openai/gpt-5.6-sol";
const MOCK_MODEL_CONTEXT_WINDOW_TOKENS = 1_000_000;
/** Harness-owned agent configuration shared by e2e fixture root agents. */
-export type E2EAgentConfig = Pick<
+type StaticAgentDefinition = Extract<
AgentDefinition,
+ { readonly model: AgentStaticModelDefinition }
+>;
+
+export type E2EAgentConfig = Pick<
+ StaticAgentDefinition,
"experimental" | "model" | "modelContextWindowTokens"
>;
/** Harness-owned configuration for fixture subagents: model identity only. */
-export type E2ESubagentConfig = Pick<AgentDefinition, "model" | "modelContextWindowTokens">;
+export type E2ESubagentConfig = Pick<StaticAgentDefinition, "model" | "modelContextWindowTokens">;
/**
* A static model handle: a gateway model id string or a deterministic mock
* instance. Assignable anywhere fixtures author a non-dynamic model
- * (agent `model`, compaction `model`, dynamic fallbacks, subagents).
+ * (agent `model`, compaction `model`, dynamic selections, subagents).
*/
export type E2EModel = string | ReturnType<typeof mockModel>;
diff --git a/packages/eve/extension-contracts/compatibility/dynamicInstructions/v7.ts b/packages/eve/extension-contracts/compatibility/dynamicInstructions/v7.ts
new file mode 100644
index 000000000..02a61cf70
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/dynamicInstructions/v7.ts
@@ -0,0 +1,10 @@
+import { defineDynamic, defineInstructions } from "#public/instructions/index.js";
+
+export default defineDynamic({
+ events: {
+ "session.started": (_event, ctx) =>
+ defineInstructions({
+ markdown: `Use session ${ctx.session.id} when correlating evidence.`,
+ }),
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/dynamicSkill/v7.ts b/packages/eve/extension-contracts/compatibility/dynamicSkill/v7.ts
new file mode 100644
index 000000000..3c6e1498e
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/dynamicSkill/v7.ts
@@ -0,0 +1,11 @@
+import { defineDynamic, defineSkill } from "#public/skills/index.js";
+
+export default defineDynamic({
+ events: {
+ "turn.started": (_event, ctx) =>
+ defineSkill({
+ description: `Review evidence for session ${ctx.session.id}.`,
+ markdown: "# Evidence review\n\nCheck every claim against its source.",
+ }),
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/dynamicTool/v12.ts b/packages/eve/extension-contracts/compatibility/dynamicTool/v12.ts
new file mode 100644
index 000000000..76b54cd92
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/dynamicTool/v12.ts
@@ -0,0 +1,14 @@
+import { z as z3 } from "zod/v3";
+
+import { defineDynamic, defineTool } from "#public/tools/index.js";
+
+export default defineDynamic({
+ events: {
+ "session.started": (_event, ctx) =>
+ defineTool({
+ description: "Return the active session identifier.",
+ inputSchema: z3.object({ prefix: z3.string() }),
+ execute: ({ prefix }) => ({ sessionId: `${prefix}:${ctx.session.id}` }),
+ }),
+ },
+});
diff --git a/packages/eve/extension-contracts/reports/dynamicInstructions/v8.json b/packages/eve/extension-contracts/reports/dynamicInstructions/v8.json
new file mode 100644
index 000000000..bd87ffef1
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/dynamicInstructions/v8.json
@@ -0,0 +1,7 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "dynamicInstructions",
+ "epoch": 8,
+ "sha256": "f069f81e82c83675cf0b3281b4ea96fd6b3c6378f7932d3b14923ea9e8ff6fea",
+ "exports": ["defineDynamic"]
+}
diff --git a/packages/eve/extension-contracts/reports/dynamicSkill/v8.json b/packages/eve/extension-contracts/reports/dynamicSkill/v8.json
new file mode 100644
index 000000000..e29d05aa1
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/dynamicSkill/v8.json
@@ -0,0 +1,7 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "dynamicSkill",
+ "epoch": 8,
+ "sha256": "f069f81e82c83675cf0b3281b4ea96fd6b3c6378f7932d3b14923ea9e8ff6fea",
+ "exports": ["defineDynamic"]
+}
diff --git a/packages/eve/extension-contracts/reports/dynamicTool/v13.json b/packages/eve/extension-contracts/reports/dynamicTool/v13.json
new file mode 100644
index 000000000..6409b8545
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/dynamicTool/v13.json
@@ -0,0 +1,13 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "dynamicTool",
+ "epoch": 13,
+ "sha256": "104c08aed1e1e7f40d8b4bc62cfbb9c47b25d626659afb47f7abba9763c2f9f4",
+ "exports": [
+ "DynamicToolEntry",
+ "DynamicToolEvents",
+ "DynamicToolResult",
+ "DynamicToolSet",
+ "defineDynamic"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/hook/v10.json b/packages/eve/extension-contracts/reports/hook/v10.json
new file mode 100644
index 000000000..1534be803
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/hook/v10.json
@@ -0,0 +1,7 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "hook",
+ "epoch": 10,
+ "sha256": "c3cf9fe58f1b3fb96e89c1b8e7c97a5b73ec4c2d3a6ac5c8b02718de80f2f049",
+ "exports": ["defineHook"]
+}
diff --git a/packages/eve/src/cli/commands/info.ts b/packages/eve/src/cli/commands/info.ts
index 3bff489c9..98d94c533 100644
--- a/packages/eve/src/cli/commands/info.ts
+++ b/packages/eve/src/cli/commands/info.ts
@@ -53,7 +53,7 @@ export function buildApplicationInfoJson(inspection: ApplicationInspection): App
warnings: compiledState.metadata.discovery.summary.warnings,
}
: null,
- model: compiledState?.manifest.config.model.id ?? null,
+ model: compiledState?.manifest.config.model?.id ?? null,
instructions: compiledState?.manifest.instructions?.logicalPath ?? null,
skills: (compiledState?.manifest.skills ?? []).map((skill) => skill.name),
tools: (compiledState?.manifest.tools ?? []).map((tool) => tool.name),
diff --git a/packages/eve/src/cli/dev/tui/agent-header.test.ts b/packages/eve/src/cli/dev/tui/agent-header.test.ts
index aedc41819..4f9dca1e2 100644
--- a/packages/eve/src/cli/dev/tui/agent-header.test.ts
+++ b/packages/eve/src/cli/dev/tui/agent-header.test.ts
@@ -45,6 +45,7 @@ const INFO: AgentInfoResult = {
appRoot: "/tmp/weather-agent",
model: {
id: "anthropic/claude-opus-4.7",
+ routing: { kind: "gateway", target: "anthropic" },
},
name: "Weather Agent",
},
diff --git a/packages/eve/src/cli/dev/tui/remote-connection.test.ts b/packages/eve/src/cli/dev/tui/remote-connection.test.ts
index 81422ef55..b519df3fc 100644
--- a/packages/eve/src/cli/dev/tui/remote-connection.test.ts
+++ b/packages/eve/src/cli/dev/tui/remote-connection.test.ts
@@ -47,7 +47,7 @@ const INFO: AgentInfoResult = {
agent: {
agentRoot: "/tmp/weather-agent/agent",
appRoot: "/tmp/weather-agent",
- model: { id: "gpt-5" },
+ model: { id: "gpt-5", routing: { kind: "gateway", target: "openai" } },
name: "Weather Agent",
},
capabilities: { devRoutes: true },
diff --git a/packages/eve/src/cli/dev/tui/runner.test.ts b/packages/eve/src/cli/dev/tui/runner.test.ts
index 6e3ebe636..bb31b4fb7 100644
--- a/packages/eve/src/cli/dev/tui/runner.test.ts
+++ b/packages/eve/src/cli/dev/tui/runner.test.ts
@@ -90,6 +90,7 @@ const AGENT_INFO: AgentInfoResult = {
appRoot: "/tmp/weather-agent",
model: {
id: "gpt-5",
+ routing: { kind: "gateway", target: "openai" },
},
name: "Weather Agent",
},
@@ -379,6 +380,7 @@ describe("EveTUIRunner agent header", () => {
...AGENT_INFO.agent,
model: {
id: "anthropic/claude-sonnet-5",
+ routing: { kind: "gateway", target: "anthropic" },
},
},
};
@@ -430,6 +432,7 @@ describe("EveTUIRunner agent header", () => {
...AGENT_INFO.agent,
model: {
id: "anthropic/claude-sonnet-5",
+ routing: { kind: "gateway", target: "anthropic" },
},
},
};
@@ -2638,9 +2641,9 @@ describe("EveTUIRunner boot setup detection", () => {
agent: {
...AGENT_INFO.agent,
model: {
- ...AGENT_INFO.agent.model,
- routing: { kind: "gateway", target: "openai" },
- endpoint: { kind: "gateway", connected: false },
+ id: "gpt-5",
+ routing: { kind: "gateway" as const, target: "openai" },
+ endpoint: { kind: "gateway" as const, connected: false as const },
},
},
};
diff --git a/packages/eve/src/cli/dev/tui/setup-issues.test.ts b/packages/eve/src/cli/dev/tui/setup-issues.test.ts
index aa44a99bb..18d34569b 100644
--- a/packages/eve/src/cli/dev/tui/setup-issues.test.ts
+++ b/packages/eve/src/cli/dev/tui/setup-issues.test.ts
@@ -23,7 +23,11 @@ function infoWithRouting(
endpoint?: AgentInfo["agent"]["model"]["endpoint"],
): AgentInfo {
const model: AgentInfo["agent"]["model"] =
- endpoint === undefined ? { id: "m", routing } : { endpoint, id: "m", routing };
+ routing.kind === "dynamic"
+ ? { routing }
+ : endpoint === undefined
+ ? { id: "m", routing }
+ : { endpoint, id: "m", routing };
return {
agent: {
diff --git a/packages/eve/src/cli/dev/tui/setup-issues.ts b/packages/eve/src/cli/dev/tui/setup-issues.ts
index 44bc0510f..c6c3fe43f 100644
--- a/packages/eve/src/cli/dev/tui/setup-issues.ts
+++ b/packages/eve/src/cli/dev/tui/setup-issues.ts
@@ -62,18 +62,29 @@ export function resolveModelProviderState(
const { credential } = access.runtime;
const model = info.agent.model;
+ if (model.id === undefined || model.routing.kind !== "gateway") return info;
const endpoint = model.endpoint;
if (endpoint?.kind === "gateway" && endpoint.connected && endpoint.credential === credential) {
return info;
}
+ const connectedEndpoint = {
+ connected: true as const,
+ credential,
+ kind: "gateway" as const,
+ };
return {
...info,
agent: {
...info.agent,
model: {
- ...model,
- endpoint: { kind: "gateway", connected: true, credential },
+ contextWindowTokens: model.contextWindowTokens,
+ endpoint: connectedEndpoint,
+ id: model.id,
+ providerOptions: model.providerOptions,
+ reasoning: model.reasoning,
+ routing: model.routing,
+ source: model.source,
},
},
};
diff --git a/packages/eve/src/cli/dev/tui/terminal-renderer.test.ts b/packages/eve/src/cli/dev/tui/terminal-renderer.test.ts
index cb678d0ab..62d3516d6 100644
--- a/packages/eve/src/cli/dev/tui/terminal-renderer.test.ts
+++ b/packages/eve/src/cli/dev/tui/terminal-renderer.test.ts
@@ -78,10 +78,12 @@ function stubDiagnostics() {
};
}
+type StaticAgentInfoModel = Extract<AgentInfoResult["agent"]["model"], { readonly id: string }>;
+
function agentInfoWithModel(
modelId: string,
- endpoint?: AgentInfoResult["agent"]["model"]["endpoint"],
- extras?: Partial<AgentInfoResult["agent"]["model"]>,
+ endpoint?: StaticAgentInfoModel["endpoint"],
+ extras?: Partial<StaticAgentInfoModel>,
): AgentInfoResult {
return {
agent: {
@@ -90,6 +92,7 @@ function agentInfoWithModel(
model: {
id: modelId,
endpoint,
+ routing: { kind: "gateway" as const, target: modelId.split("/")[0] ?? "openai" },
...extras,
},
name: "Weather Agent",
diff --git a/packages/eve/src/client/agent-info-schema.ts b/packages/eve/src/client/agent-info-schema.ts
index 31ee51b6b..baf88dcd9 100644
--- a/packages/eve/src/client/agent-info-schema.ts
+++ b/packages/eve/src/client/agent-info-schema.ts
@@ -24,6 +24,36 @@ const modelEndpoint = z.union([
z.object({ kind: z.literal("gateway"), connected: z.literal(false) }),
]);
+const agentModelBaseFields = {
+ contextWindowTokens: z.number().optional(),
+ providerOptions: z.unknown().optional(),
+ // An unrecognized future effort level degrades to absent, not a parse failure.
+ reasoning: z
+ .enum(["provider-default", "none", "minimal", "low", "medium", "high", "xhigh"])
+ .optional()
+ .catch(undefined),
+ source: source.optional(),
+};
+
+const agentModel = z.union([
+ z
+ .object({
+ ...agentModelBaseFields,
+ id: z.string(),
+ routing: modelRouting,
+ endpoint: modelEndpoint.optional(),
+ })
+ .strict(),
+ z
+ .object({
+ ...agentModelBaseFields,
+ endpoint: z.never().optional(),
+ id: z.never().optional(),
+ routing: z.object({ kind: z.literal("dynamic") }).strict(),
+ })
+ .strict(),
+]);
+
const tool = entry.extend({
description: z.string(),
hasAuth: z.boolean(),
@@ -125,19 +155,7 @@ export const AgentInfoResultSchema = z.object({
appRoot: z.string(),
configSource: source.optional(),
description: z.string().optional(),
- model: z.object({
- contextWindowTokens: z.number().optional(),
- id: z.string(),
- providerOptions: z.unknown().optional(),
- // An unrecognized future effort level degrades to absent, not a parse failure.
- reasoning: z
- .enum(["provider-default", "none", "minimal", "low", "medium", "high", "xhigh"])
- .optional()
- .catch(undefined),
- source: source.optional(),
- routing: modelRouting.optional(),
- endpoint: modelEndpoint.optional(),
- }),
+ model: agentModel,
name: z.string(),
outputSchema: z.unknown().optional(),
}),
diff --git a/packages/eve/src/client/client.test.ts b/packages/eve/src/client/client.test.ts
index 227d95371..065927434 100644
--- a/packages/eve/src/client/client.test.ts
+++ b/packages/eve/src/client/client.test.ts
@@ -12,7 +12,7 @@ const AGENT_INFO: AgentInfoResult = {
agent: {
agentRoot: "/tmp/weather-agent/agent",
appRoot: "/tmp/weather-agent",
- model: { id: "openai/gpt-5.5" },
+ model: { id: "openai/gpt-5.5", routing: { kind: "gateway", target: "openai" } },
name: "Weather Agent",
},
capabilities: { devRoutes: true },
@@ -244,7 +244,12 @@ describe("Client request policy", () => {
it("rejects an incomplete agent info payload", async () => {
vi.spyOn(globalThis, "fetch").mockResolvedValue(
Response.json({
- agent: { model: { id: "openai/gpt-5.5" } },
+ agent: {
+ model: {
+ id: "openai/gpt-5.5",
+ routing: { kind: "gateway", target: "openai" },
+ },
+ },
diagnostics: { discoveryErrors: 0, discoveryWarnings: 0 },
kind: "eve-agent-info",
version: 1,
@@ -258,7 +263,12 @@ describe("Client request policy", () => {
it("names the offending fields when the agent info payload is incomplete", async () => {
vi.spyOn(globalThis, "fetch").mockResolvedValue(
Response.json({
- agent: { model: { id: "openai/gpt-5.5" } },
+ agent: {
+ model: {
+ id: "openai/gpt-5.5",
+ routing: { kind: "gateway", target: "openai" },
+ },
+ },
diagnostics: { discoveryErrors: 0, discoveryWarnings: 0 },
kind: "eve-agent-info",
version: 1,
diff --git a/packages/eve/src/client/message-reducer.test.ts b/packages/eve/src/client/message-reducer.test.ts
index 23ef5ecad..4138acdd0 100644
--- a/packages/eve/src/client/message-reducer.test.ts
+++ b/packages/eve/src/client/message-reducer.test.ts
@@ -634,6 +634,7 @@ describe("defaultMessageReducer", () => {
});
data = reduceServerEvents(reducer, data, [
createStepStartedEvent({
+ modelId: "openai/gpt-5.5",
sequence: 1,
stepIndex: 0,
turnId: "turn_1",
diff --git a/packages/eve/src/compiler/compile-from-memory.test.ts b/packages/eve/src/compiler/compile-from-memory.test.ts
index f24be3358..90a648895 100644
--- a/packages/eve/src/compiler/compile-from-memory.test.ts
+++ b/packages/eve/src/compiler/compile-from-memory.test.ts
@@ -15,7 +15,7 @@ describe("compileFromMemory", () => {
expect(manifest.kind).toBe(COMPILED_AGENT_MANIFEST_KIND);
expect(manifest.version).toBe(COMPILED_AGENT_MANIFEST_VERSION);
expect(manifest.config.name).toBe("memory-agent");
- expect(manifest.config.model.id).toBe("openai/gpt-5.4");
+ expect(manifest.config.model?.id).toBe("openai/gpt-5.4");
expect(manifest.tools).toEqual([]);
expect(manifest.skills).toEqual([]);
expect(manifest.subagents).toEqual([]);
@@ -31,7 +31,7 @@ describe("compileFromMemory", () => {
});
expect(manifest.config.name).toBe("custom-agent");
- expect(manifest.config.model.id).toBe("mock/custom");
+ expect(manifest.config.model?.id).toBe("mock/custom");
expect(manifest.appRoot).toBe("/app");
expect(manifest.agentRoot).toBe("/app/agent");
});
diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.ts
index 2dac0730d..b0921cc3d 100644
--- a/packages/eve/src/compiler/extension-compatibility.ts
+++ b/packages/eve/src/compiler/extension-compatibility.ts
@@ -22,13 +22,31 @@ interface ExtensionCapabilityContract {
const EXTENSION_CAPABILITY_CONTRACTS = {
extension: { current: 1, supported: [1], dropped: {} },
tool: { current: 11, supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11], dropped: {} },
- dynamicTool: { current: 12, supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12], dropped: {} },
+ dynamicTool: {
+ current: 13,
+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13],
+ dropped: {},
+ },
connection: { current: 4, supported: [1, 2, 3, 4], dropped: {} },
- hook: { current: 9, supported: [1, 2, 3, 4, 5, 6, 7, 8, 9], dropped: {} },
+ hook: {
+ current: 10,
+ supported: [10],
+ dropped: {
+ 1: "Model identity moved from session.started runtime metadata to step.started call attribution.",
+ 2: "Model identity moved from session.started runtime metadata to step.started call attribution.",
+ 3: "Model identity moved from session.started runtime metadata to step.started call attribution.",
+ 4: "Model identity moved from session.started runtime metadata to step.started call attribution.",
+ 5: "Model identity moved from session.started runtime metadata to step.started call attribution.",
+ 6: "Model identity moved from session.started runtime metadata to step.started call attribution.",
+ 7: "Model identity moved from session.started runtime metadata to step.started call attribution.",
+ 8: "Model identity moved from session.started runtime metadata to step.started call attribution.",
+ 9: "Model identity moved from session.started runtime metadata to step.started call attribution.",
+ },
+ },
skill: { current: 1, supported: [1], dropped: {} },
- dynamicSkill: { current: 7, supported: [1, 2, 3, 4, 5, 6, 7], dropped: {} },
+ dynamicSkill: { current: 8, supported: [1, 2, 3, 4, 5, 6, 7, 8], dropped: {} },
instructions: { current: 1, supported: [1], dropped: {} },
- dynamicInstructions: { current: 7, supported: [1, 2, 3, 4, 5, 6, 7], dropped: {} },
+ dynamicInstructions: { current: 8, supported: [1, 2, 3, 4, 5, 6, 7, 8], dropped: {} },
config: { current: 1, supported: [1], dropped: {} },
state: { current: 3, supported: [1, 2, 3], dropped: {} },
} as const satisfies Record<string, ExtensionCapabilityContract>;
diff --git a/packages/eve/src/compiler/manifest.test.ts b/packages/eve/src/compiler/manifest.test.ts
index ae9a80bd7..9e63883c7 100644
--- a/packages/eve/src/compiler/manifest.test.ts
+++ b/packages/eve/src/compiler/manifest.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
import {
compiledAgentManifestSchema,
+ createCompiledAgentResources,
createCompiledAgentManifest,
createCompiledAgentNodeManifest,
} from "#compiler/manifest.js";
@@ -41,12 +42,30 @@ describe("compiledAgentManifestSchema", () => {
}).success;
expect(parses({ description: "Research requests." })).toBe(true);
- expect(parses({ dynamic: { eventNames: ["session.started"] } })).toBe(true);
+ expect(
+ parses({
+ agent: createCompiledAgentResources({
+ agentRoot: "/app/agent/subagents/research",
+ appRoot: "/app",
+ }),
+ configResolver: {
+ eventNames: ["session.started"],
+ logicalPath: "agent.ts",
+ sourceId: "agent.ts",
+ sourceKind: "module",
+ },
+ }),
+ ).toBe(true);
expect(parses({})).toBe(false);
expect(
parses({
description: "Research requests.",
- dynamic: { eventNames: ["session.started"] },
+ configResolver: {
+ eventNames: ["session.started"],
+ logicalPath: "agent.ts",
+ sourceId: "agent.ts",
+ sourceKind: "module",
+ },
}),
).toBe(false);
});
@@ -170,7 +189,6 @@ describe("compiledAgentManifestSchema", () => {
sourceId: "agent-config",
sourceKind: "module",
},
- model: { id: "openai/gpt-5.5", routing: classifyModelRouting("openai/gpt-5.5") },
name: "app",
},
});
@@ -183,6 +201,32 @@ describe("compiledAgentManifestSchema", () => {
sourceId: "agent-config",
sourceKind: "module",
});
+ expect(parsed.config.model).toBeUndefined();
+ });
+
+ it("rejects compiled configs with both static and dynamic models", () => {
+ expect(() =>
+ compiledAgentManifestSchema.parse({
+ ...createCompiledAgentManifest({
+ agentRoot: "/app/agent",
+ appRoot: "/app",
+ config: {
+ model: { id: "openai/gpt-5.5", routing: classifyModelRouting("openai/gpt-5.5") },
+ name: "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",
+ },
+ }),
+ ).toThrow();
});
it("preserves uncapped (false) session token limits", () => {
diff --git a/packages/eve/src/compiler/manifest.ts b/packages/eve/src/compiler/manifest.ts
index aec6a0b59..fd5a9f432 100644
--- a/packages/eve/src/compiler/manifest.ts
+++ b/packages/eve/src/compiler/manifest.ts
@@ -43,7 +43,7 @@ export const ROOT_COMPILED_AGENT_NODE_ID = "__root__";
/**
* Current compiled manifest schema version.
*/
-export const COMPILED_AGENT_MANIFEST_VERSION = 39;
+export const COMPILED_AGENT_MANIFEST_VERSION = 40;
/**
* Compiled channel entry preserved in the compiled manifest.
@@ -103,8 +103,7 @@ export type CompiledRuntimeModelReference = InternalAgentModelDefinition & {
};
/**
- * Dynamic model resolver source preserved in the compiled manifest; the
- * compiled `config.model` remains the fallback model.
+ * Dynamic model resolver source preserved in the compiled manifest.
*/
export type CompiledDynamicModelDefinition = ModuleSourceRef & {
readonly eventNames: readonly string[];
@@ -126,12 +125,22 @@ type CompiledAgentCompactionDefinition = Omit<InternalAgentCompactionDefinition,
/**
* Normalized additive agent configuration preserved in the compiled manifest.
*/
-export type CompiledAgentDefinition = Omit<InternalAgentDefinition, "model" | "compaction"> & {
- model: CompiledRuntimeModelReference;
+type CompiledAgentDefinitionBase = Omit<InternalAgentDefinition, "model" | "compaction"> & {
compaction?: CompiledAgentCompactionDefinition;
- dynamicModel?: CompiledDynamicModelDefinition;
};
+export type CompiledAgentDefinition = CompiledAgentDefinitionBase &
+ (
+ | {
+ readonly model: CompiledRuntimeModelReference;
+ readonly dynamicModel?: never;
+ }
+ | {
+ readonly model?: never;
+ readonly dynamicModel: CompiledDynamicModelDefinition;
+ }
+ );
+
/**
* Normalized authored instructions prompt preserved in the compiled
* manifest.
@@ -249,21 +258,24 @@ export interface CompiledHookDefinition extends ModuleSourceRef {
*/
export type CompiledAgentNodeManifest = z.infer<typeof compiledAgentNodeManifestSchema>;
+export type CompiledAgentResources = z.infer<typeof compiledAgentResourcesSchema>;
+
export type CompiledSubagentNode = Readonly<
ModuleSourceRef &
Node & {
- agent: CompiledAgentNodeManifest;
entryPath: string;
name: string;
rootPath: string;
} & (
| {
+ agent: CompiledAgentNodeManifest;
+ configResolver?: never;
description: string;
- dynamic?: never;
}
| {
+ agent: CompiledAgentResources;
+ configResolver: CompiledDynamicSubagentDefinition;
description?: never;
- dynamic: CompiledDynamicSubagentDefinition;
}
)
>;
@@ -376,6 +388,7 @@ const compiledRuntimeModelReferenceSchema: z.ZodType<CompiledRuntimeModelReferen
.object({
contextWindowTokens: z.number().int().positive().optional(),
id: z.string(),
+ maxOutputTokens: z.number().int().positive().optional(),
source: moduleSourceRefSchema.optional(),
providerOptions: z.record(z.string(), jsonObjectSchema).optional(),
routing: modelRoutingSchema,
@@ -420,29 +433,40 @@ const compiledWorkflowToolDefinitionSchema: z.ZodType<CompiledWorkflowToolDefini
})
.strict();
-const compiledAgentConfigSchema: z.ZodType<CompiledAgentDefinition> = z
- .object({
- build: compiledAgentBuildDefinitionSchema.optional(),
- compaction: compiledAgentCompactionDefinitionSchema.optional(),
- description: z.string().optional(),
- dynamicModel: compiledDynamicModelDefinitionSchema.optional(),
- experimental: z
- .object({
- subagentPersistentSessions: z.boolean().optional(),
- workflow: compiledAgentWorkflowDefinitionSchema.optional(),
- })
- .strict()
- .optional(),
- model: compiledRuntimeModelReferenceSchema,
- name: z.string(),
- outputSchema: jsonObjectSchema.optional(),
- reasoning: z
- .enum(["provider-default", "none", "minimal", "low", "medium", "high", "xhigh"])
- .optional(),
- source: moduleSourceRefSchema.optional(),
- limits: compiledAgentLimitsDefinitionSchema.optional(),
- })
- .strict();
+const compiledAgentConfigBaseFields = {
+ build: compiledAgentBuildDefinitionSchema.optional(),
+ compaction: compiledAgentCompactionDefinitionSchema.optional(),
+ description: z.string().optional(),
+ experimental: z
+ .object({
+ subagentPersistentSessions: z.boolean().optional(),
+ workflow: compiledAgentWorkflowDefinitionSchema.optional(),
+ })
+ .strict()
+ .optional(),
+ name: z.string(),
+ outputSchema: jsonObjectSchema.optional(),
+ reasoning: z
+ .enum(["provider-default", "none", "minimal", "low", "medium", "high", "xhigh"])
+ .optional(),
+ source: moduleSourceRefSchema.optional(),
+ limits: compiledAgentLimitsDefinitionSchema.optional(),
+};
+
+const compiledAgentConfigSchema: z.ZodType<CompiledAgentDefinition> = z.union([
+ z
+ .object({
+ ...compiledAgentConfigBaseFields,
+ model: compiledRuntimeModelReferenceSchema,
+ })
+ .strict(),
+ z
+ .object({
+ ...compiledAgentConfigBaseFields,
+ dynamicModel: compiledDynamicModelDefinitionSchema,
+ })
+ .strict(),
+]);
const compiledInstructionsSchema: z.ZodType<CompiledInstructionsDefinition> = z
.object({
@@ -654,35 +678,40 @@ const compiledExtensionMountSchema: z.ZodType<CompiledExtensionMount> = z
/**
* Zod schema for one non-recursive compiled authored agent payload.
*/
+const compiledAgentResourceFields = {
+ agentRoot: z.string(),
+ appRoot: z.string(),
+ channels: z.array(compiledChannelEntrySchema),
+ connections: z.array(compiledConnectionDefinitionSchema),
+ diagnosticsSummary: discoverDiagnosticsSummarySchema,
+ disabledFrameworkTools: z.array(z.string()).readonly(),
+ workflowTool: compiledWorkflowToolDefinitionSchema.optional(),
+ webSearchProvider: z.enum(["exa", "parallel"]).optional(),
+ dynamicInstructions: z.array(compiledDynamicInstructionsDefinitionSchema).default([]),
+ dynamicSkills: z.array(compiledDynamicSkillDefinitionSchema).default([]),
+ dynamicTools: z.array(compiledDynamicToolDefinitionSchema).default([]),
+ extensionMounts: z.array(compiledExtensionMountSchema).default([]),
+ hooks: z.array(compiledHookDefinitionSchema),
+ sandbox: compiledSandboxDefinitionSchema.nullable(),
+ sandboxWorkspaces: z.array(compiledSandboxWorkspaceSchema),
+ schedules: z.array(compiledScheduleDefinitionSchema),
+ remoteAgents: z.array(compiledRemoteAgentNodeSchema),
+ skills: z.array(compiledSkillSourceSchema).readonly(),
+ instructions: compiledInstructionsSchema.optional(),
+ tools: z.array(compiledToolDefinitionSchema),
+ workspaceResourceRoot: compiledWorkspaceResourceRootSchema,
+};
+
+const compiledAgentResourcesSchema = z.object(compiledAgentResourceFields).strict();
+
const compiledAgentNodeManifestSchema = z
.object({
- agentRoot: z.string(),
- appRoot: z.string(),
- channels: z.array(compiledChannelEntrySchema),
+ ...compiledAgentResourceFields,
config: compiledAgentConfigSchema,
- connections: z.array(compiledConnectionDefinitionSchema),
- diagnosticsSummary: discoverDiagnosticsSummarySchema,
- disabledFrameworkTools: z.array(z.string()).readonly(),
- workflowTool: compiledWorkflowToolDefinitionSchema.optional(),
- webSearchProvider: z.enum(["exa", "parallel"]).optional(),
- dynamicInstructions: z.array(compiledDynamicInstructionsDefinitionSchema).default([]),
- dynamicSkills: z.array(compiledDynamicSkillDefinitionSchema).default([]),
- dynamicTools: z.array(compiledDynamicToolDefinitionSchema).default([]),
- extensionMounts: z.array(compiledExtensionMountSchema).default([]),
- hooks: z.array(compiledHookDefinitionSchema),
- sandbox: compiledSandboxDefinitionSchema.nullable(),
- sandboxWorkspaces: z.array(compiledSandboxWorkspaceSchema),
- schedules: z.array(compiledScheduleDefinitionSchema),
- remoteAgents: z.array(compiledRemoteAgentNodeSchema),
- skills: z.array(compiledSkillSourceSchema).readonly(),
- instructions: compiledInstructionsSchema.optional(),
- tools: z.array(compiledToolDefinitionSchema),
- workspaceResourceRoot: compiledWorkspaceResourceRootSchema,
})
.strict();
const compiledSubagentNodeBaseFields = {
- agent: compiledAgentNodeManifestSchema,
entryPath: z.string(),
logicalPath: z.string(),
name: z.string(),
@@ -694,15 +723,27 @@ const compiledSubagentNodeBaseFields = {
};
const compiledDynamicSubagentDefinitionSchema = z
.object({
+ build: compiledAgentBuildDefinitionSchema.optional(),
eventNames: z.array(z.string()).readonly(),
+ exportName: z.string().optional(),
+ logicalPath: z.string(),
+ sourceId: z.string(),
+ sourceKind: z.literal("module"),
})
.strict();
const compiledSubagentNodeSchema: z.ZodType<CompiledSubagentNode> = z.union([
- z.object({ ...compiledSubagentNodeBaseFields, description: z.string() }).strict(),
z
.object({
...compiledSubagentNodeBaseFields,
- dynamic: compiledDynamicSubagentDefinitionSchema,
+ agent: compiledAgentNodeManifestSchema,
+ description: z.string(),
+ })
+ .strict(),
+ z
+ .object({
+ ...compiledSubagentNodeBaseFields,
+ agent: compiledAgentResourcesSchema,
+ configResolver: compiledDynamicSubagentDefinitionSchema,
})
.strict(),
]);
@@ -773,14 +814,10 @@ export const compiledAgentManifestSchema = z
})
.strict();
-/**
- * Creates a compiled authored agent payload with stable defaults.
- */
-export function createCompiledAgentNodeManifest(input: {
+export interface CreateCompiledAgentResourcesInput {
readonly agentRoot: string;
readonly appRoot: string;
readonly channels?: readonly CompiledChannelEntry[];
- readonly config: CompiledAgentDefinition;
readonly connections?: readonly CompiledConnectionDefinition[];
readonly diagnosticsSummary?: DiscoverDiagnosticsSummary;
readonly disabledFrameworkTools?: readonly string[];
@@ -799,67 +836,17 @@ export function createCompiledAgentNodeManifest(input: {
readonly instructions?: CompiledInstructionsDefinition;
readonly tools?: readonly CompiledToolDefinition[];
readonly workspaceResourceRoot?: CompiledWorkspaceResourceRoot;
-}): CompiledAgentNodeManifest {
- const node: CompiledAgentNodeManifest = {
+}
+
+/** Creates compiled filesystem-owned resources with stable defaults. */
+export function createCompiledAgentResources(
+ input: CreateCompiledAgentResourcesInput,
+): CompiledAgentResources {
+ const resources: CompiledAgentResources = {
agentRoot: input.agentRoot,
appRoot: input.appRoot,
channels: [...(input.channels ?? [])],
connections: [...(input.connections ?? [])],
- config: {
- build:
- input.config.build === undefined
- ? undefined
- : {
- externalDependencies:
- input.config.build.externalDependencies === undefined
- ? undefined
- : [...input.config.build.externalDependencies],
- },
- compaction: {
- model:
- input.config.compaction?.model === undefined
- ? undefined
- : cloneCompiledRuntimeModelReference(input.config.compaction.model),
- thresholdPercent: input.config.compaction?.thresholdPercent,
- },
- description: input.config.description,
- dynamicModel:
- input.config.dynamicModel === undefined
- ? undefined
- : {
- ...input.config.dynamicModel,
- },
- experimental:
- input.config.experimental === undefined
- ? undefined
- : {
- subagentPersistentSessions: input.config.experimental.subagentPersistentSessions,
- workflow:
- input.config.experimental.workflow === undefined
- ? undefined
- : {
- world: input.config.experimental.workflow.world,
- },
- },
- model: cloneCompiledRuntimeModelReference(input.config.model),
- name: input.config.name,
- outputSchema: input.config.outputSchema,
- reasoning: input.config.reasoning,
- limits:
- input.config.limits === undefined
- ? undefined
- : {
- maxInputTokensPerSession: input.config.limits.maxInputTokensPerSession,
- maxOutputTokensPerSession: input.config.limits.maxOutputTokensPerSession,
- sessionTimeoutMs: input.config.limits.sessionTimeoutMs,
- },
- source:
- input.config.source === undefined
- ? undefined
- : {
- ...input.config.source,
- },
- },
diagnosticsSummary: input.diagnosticsSummary ?? {
errors: 0,
warnings: 0,
@@ -891,10 +878,83 @@ export function createCompiledAgentNodeManifest(input: {
};
if (input.instructions !== undefined) {
- node.instructions = input.instructions;
+ resources.instructions = input.instructions;
}
- return node;
+ return resources;
+}
+
+/** Creates a compiled authored agent payload with stable defaults. */
+export function createCompiledAgentNodeManifest(
+ input: CreateCompiledAgentResourcesInput & { readonly config: CompiledAgentDefinition },
+): CompiledAgentNodeManifest {
+ return {
+ ...createCompiledAgentResources(input),
+ config: cloneCompiledAgentDefinition(input.config),
+ };
+}
+
+function cloneCompiledAgentDefinition(config: CompiledAgentDefinition): CompiledAgentDefinition {
+ const base = {
+ build:
+ config.build === undefined
+ ? undefined
+ : {
+ externalDependencies:
+ config.build.externalDependencies === undefined
+ ? undefined
+ : [...config.build.externalDependencies],
+ },
+ compaction: {
+ model:
+ config.compaction?.model === undefined
+ ? undefined
+ : cloneCompiledRuntimeModelReference(config.compaction.model),
+ thresholdPercent: config.compaction?.thresholdPercent,
+ },
+ description: config.description,
+ experimental:
+ config.experimental === undefined
+ ? undefined
+ : {
+ subagentPersistentSessions: config.experimental.subagentPersistentSessions,
+ workflow:
+ config.experimental.workflow === undefined
+ ? undefined
+ : {
+ world: config.experimental.workflow.world,
+ },
+ },
+ name: config.name,
+ outputSchema: config.outputSchema,
+ reasoning: config.reasoning,
+ limits:
+ config.limits === undefined
+ ? undefined
+ : {
+ maxInputTokensPerSession: config.limits.maxInputTokensPerSession,
+ maxOutputTokensPerSession: config.limits.maxOutputTokensPerSession,
+ sessionTimeoutMs: config.limits.sessionTimeoutMs,
+ },
+ source:
+ config.source === undefined
+ ? undefined
+ : {
+ ...config.source,
+ },
+ };
+
+ if (config.dynamicModel !== undefined) {
+ return {
+ ...base,
+ dynamicModel: { ...config.dynamicModel },
+ };
+ }
+
+ return {
+ ...base,
+ model: cloneCompiledRuntimeModelReference(config.model),
+ };
}
/**
@@ -979,6 +1039,9 @@ function cloneCompiledRuntimeModelReference(
if (model.contextWindowTokens !== undefined) {
clone.contextWindowTokens = model.contextWindowTokens;
}
+ if (model.maxOutputTokens !== undefined) {
+ clone.maxOutputTokens = model.maxOutputTokens;
+ }
if (model.providerOptions !== undefined) {
clone.providerOptions = { ...model.providerOptions };
}
diff --git a/packages/eve/src/compiler/model-catalog.ts b/packages/eve/src/compiler/model-catalog.ts
index cccc4f87f..0e4d8d468 100644
--- a/packages/eve/src/compiler/model-catalog.ts
+++ b/packages/eve/src/compiler/model-catalog.ts
@@ -3,36 +3,24 @@ import { join } from "node:path";
import { z } from "#compiled/zod/index.js";
import { AI_GATEWAY_MODELS_CATALOG_URL, vercelGatewayFetch } from "#internal/gateway.js";
+import {
+ catalogModelSchema,
+ findCatalogModelByProviderModelId,
+ findCatalogModelBySlug,
+ modelCatalogLimitsFromProvider,
+ modelCatalogResponseSchema,
+ normalizeCatalogModelId,
+ type CatalogModel,
+} from "#internal/model-catalog.js";
const COMPILED_RUNTIME_MODEL_CATALOG_CACHE_KIND = "eve-model-catalog-cache";
const COMPILED_RUNTIME_MODEL_CATALOG_CACHE_VERSION = 2;
const COMPILED_RUNTIME_MODEL_CATALOG_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
-const THINKING_SUFFIX = "-thinking";
-
-export const catalogModelProviderSchema = z
- .object({
- provider: z.string().min(1),
- providerModelId: z.string().min(1),
- contextWindowTokens: z.number().int().nonnegative().optional(),
- maxOutputTokens: z.number().int().nonnegative().optional(),
- })
- .passthrough();
-
-export const catalogModelSchema = z
- .object({
- slug: z.string().min(1),
- providers: z.array(catalogModelProviderSchema).min(1),
- })
- .passthrough();
-
-export const modelCatalogResponseSchema = z
- .object({
- models: z.array(catalogModelSchema),
- providerAliases: z.record(z.string(), z.string()),
- })
- .passthrough();
-
-export type CatalogModelProvider = z.infer<typeof catalogModelProviderSchema>;
-export type CatalogModel = z.infer<typeof catalogModelSchema>;
+export {
+ catalogModelProviderSchema,
+ catalogModelSchema,
+ modelCatalogResponseSchema,
+} from "#internal/model-catalog.js";
+export type { CatalogModelProvider, CatalogModel } from "#internal/model-catalog.js";
/**
* Stable runtime model limits that eve can embed in compiled artifacts without
@@ -160,14 +148,14 @@ export function createCompiledRuntimeModelCatalogLoader(
return {
async getModelLimits(modelId) {
- const normalizedId = normalizeModelId(modelId);
+ const normalizedId = normalizeCatalogModelId(modelId);
const resolved = await resolveModelsFromCacheOrFetch();
if (resolved !== null) {
- const model = findBySlug(resolved.models, normalizedId);
+ const model = findCatalogModelBySlug(resolved.models, normalizedId);
if (model) {
for (const p of model.providers) {
- const limits = limitsFromProvider(p);
+ const limits = modelCatalogLimitsFromProvider(p);
if (limits !== null) {
return limits;
}
@@ -184,21 +172,16 @@ export function createCompiledRuntimeModelCatalogLoader(
return null;
}
- const baseProvider = provider.split(".")[0]!;
- const resolvedProvider = resolved.providerAliases[baseProvider] ?? baseProvider;
- const normalizedModelId = normalizeModelId(providerModelId);
-
- for (const model of resolved.models) {
- for (const p of model.providers) {
- if (
- p.provider === resolvedProvider &&
- normalizeModelId(p.providerModelId) === normalizedModelId
- ) {
- const limits = limitsFromProvider(p);
- if (limits !== null) {
- return { slug: model.slug, limits };
- }
- }
+ const match = findCatalogModelByProviderModelId({
+ models: resolved.models,
+ provider,
+ providerAliases: resolved.providerAliases,
+ providerModelId,
+ });
+ if (match !== null) {
+ const limits = modelCatalogLimitsFromProvider(match.provider);
+ if (limits !== null) {
+ return { slug: match.model.slug, limits };
}
}
@@ -265,21 +248,6 @@ async function readModelCatalogCache(
}
}
-function findBySlug(models: readonly CatalogModel[], slug: string): CatalogModel | undefined {
- return models.find((m) => m.slug === slug);
-}
-
-function limitsFromProvider(provider: CatalogModelProvider): CompiledRuntimeModelLimits | null {
- if (provider.contextWindowTokens === undefined || provider.contextWindowTokens <= 0) {
- return null;
- }
- return {
- contextWindowTokens: provider.contextWindowTokens,
- ...(provider.maxOutputTokens !== undefined &&
- provider.maxOutputTokens > 0 && { maxOutputTokens: provider.maxOutputTokens }),
- };
-}
-
function isCacheFresh(cache: CompiledRuntimeModelCatalogCache): boolean {
const fetchedAt = Date.parse(cache.fetchedAt);
if (!Number.isFinite(fetchedAt)) {
@@ -287,7 +255,3 @@ function isCacheFresh(cache: CompiledRuntimeModelCatalogCache): boolean {
}
return Date.now() - fetchedAt <= COMPILED_RUNTIME_MODEL_CATALOG_CACHE_TTL_MS;
}
-
-function normalizeModelId(modelId: string): string {
- return modelId.endsWith(THINKING_SUFFIX) ? modelId.slice(0, -THINKING_SUFFIX.length) : modelId;
-}
diff --git a/packages/eve/src/compiler/module-map.test.ts b/packages/eve/src/compiler/module-map.test.ts
index 82d8b6b56..ce928d854 100644
--- a/packages/eve/src/compiler/module-map.test.ts
+++ b/packages/eve/src/compiler/module-map.test.ts
@@ -1,7 +1,11 @@
import { describe, expect, it } from "vitest";
import type { CompiledAgentManifest } from "./manifest.js";
-import { COMPILED_AGENT_MANIFEST_VERSION, ROOT_COMPILED_AGENT_NODE_ID } from "./manifest.js";
+import {
+ COMPILED_AGENT_MANIFEST_VERSION,
+ createCompiledAgentResources,
+ ROOT_COMPILED_AGENT_NODE_ID,
+} from "./manifest.js";
import { collectModuleRefsForManifest, createCompiledModuleMapSource } from "./module-map.js";
function createManifestWithTool(agentRoot: string): CompiledAgentManifest {
@@ -75,6 +79,41 @@ describe("createCompiledModuleMapSource", () => {
);
expect(source).toContain(`"${ROOT_COMPILED_AGENT_NODE_ID}"`);
});
+
+ it("imports a dynamic subagent config resolver relative to the child agent root", () => {
+ const manifest: CompiledAgentManifest = {
+ ...createManifestWithTool("/agent"),
+ subagents: [
+ {
+ agent: createCompiledAgentResources({
+ agentRoot: "/agent/subagents/researcher",
+ appRoot: "/agent",
+ }),
+ configResolver: {
+ eventNames: ["turn.started"],
+ logicalPath: "agent.ts",
+ sourceId: "agent.ts",
+ sourceKind: "module",
+ },
+ entryPath: "/agent/subagents/researcher/agent.ts",
+ logicalPath: "subagents/researcher",
+ name: "researcher",
+ nodeId: "subagents/researcher",
+ rootPath: "/agent/subagents/researcher",
+ sourceId: "subagents/researcher",
+ sourceKind: "module",
+ },
+ ],
+ };
+
+ const source = createCompiledModuleMapSource({
+ manifest,
+ moduleMapPath: "/agent/.eve/compile/module-map.mjs",
+ });
+
+ expect(source).toContain('from "../../subagents/researcher/agent.ts";');
+ expect(source).not.toContain("subagents/researcher/subagents/researcher");
+ });
});
describe("collectModuleRefsForManifest", () => {
diff --git a/packages/eve/src/compiler/module-map.ts b/packages/eve/src/compiler/module-map.ts
index ce0588a22..a5bef96d0 100644
--- a/packages/eve/src/compiler/module-map.ts
+++ b/packages/eve/src/compiler/module-map.ts
@@ -3,6 +3,7 @@ import type { ModuleSourceRef } from "#shared/source-ref.js";
import type {
CompiledAgentManifest,
CompiledAgentNodeManifest,
+ CompiledAgentResources,
CompiledExtensionMount,
} from "#compiler/manifest.js";
import { ROOT_COMPILED_AGENT_NODE_ID } from "#compiler/manifest.js";
@@ -84,6 +85,7 @@ export function createCompiledModuleMapSource(input: CreateCompiledModuleMapSour
agentRoot: subagent.agent.agentRoot,
importSpecifierStyle,
manifest: subagent.agent,
+ additionalModuleRef: subagent.configResolver,
moduleMapDirectory,
nextBindingName() {
return `module_${nextBindingIndex++}`;
@@ -112,15 +114,19 @@ export function createCompiledModuleMapSource(input: CreateCompiledModuleMapSour
}
function collectModuleNodeScope(input: {
+ readonly additionalModuleRef?: ModuleSourceRef;
readonly agentRoot: string;
readonly importSpecifierStyle: "absolute" | "relative";
- readonly manifest: CompiledAgentNodeManifest;
+ readonly manifest: CompiledAgentNodeManifest | CompiledAgentResources;
readonly moduleMapDirectory: string;
readonly nextBindingName: () => string;
readonly nodeId: string;
}): CollectedModuleNodeScope {
return {
- modules: collectModuleRefsForManifest(input.manifest)
+ modules: [
+ ...collectModuleRefsForManifest(input.manifest),
+ ...(input.additionalModuleRef === undefined ? [] : [input.additionalModuleRef]),
+ ]
.sort((left, right) => left.sourceId.localeCompare(right.sourceId))
.map((moduleSourceRef) => ({
bindingName: input.nextBindingName(),
@@ -142,15 +148,15 @@ function collectModuleNodeScope(input: {
* from the manifest when the pre-built artifact is unavailable).
*/
export function collectModuleRefsForManifest(
- manifest: CompiledAgentNodeManifest,
+ manifest: CompiledAgentNodeManifest | CompiledAgentResources,
): ModuleSourceRef[] {
const moduleSourceRefs = new Map<string, ModuleSourceRef>();
- if (manifest.config.source !== undefined) {
+ if ("config" in manifest && manifest.config.source !== undefined) {
moduleSourceRefs.set(manifest.config.source.sourceId, manifest.config.source);
}
- if (manifest.config.model.source !== undefined) {
+ if ("config" in manifest && manifest.config.model?.source !== undefined) {
moduleSourceRefs.set(manifest.config.model.source.sourceId, manifest.config.model.source);
}
diff --git a/packages/eve/src/compiler/normalize-agent-config.test.ts b/packages/eve/src/compiler/normalize-agent-config.test.ts
index 98023eddb..0c06e3e48 100644
--- a/packages/eve/src/compiler/normalize-agent-config.test.ts
+++ b/packages/eve/src/compiler/normalize-agent-config.test.ts
@@ -19,13 +19,12 @@ describe("compileAgentConfig", () => {
mocks.loadModuleBackedDefinition.mockReset();
});
- it("compiles a dynamic model fallback and preserves the resolver source", async () => {
+ it("compiles a dynamic model resolver without a model reference", async () => {
mocks.loadModuleBackedDefinition.mockResolvedValue({
model: defineDynamic({
- fallback: "openai/gpt-5.5",
events: {
"session.started": () => "openai/gpt-5.5-mini",
- "step.started": () => null,
+ "step.started": () => "openai/gpt-5.5",
},
}),
});
@@ -40,24 +39,20 @@ describe("compileAgentConfig", () => {
}),
});
- const compiled = await compileAgentConfig(manifest, {
- modelCatalog: createModelCatalog(),
- });
+ const modelCatalog = createModelCatalog();
+ const compiled = await compileAgentConfig(manifest, { modelCatalog });
- expect(compiled.model).toEqual({
- contextWindowTokens: 256_000,
- id: "openai/gpt-5.5",
- routing: { kind: "gateway", target: "openai" },
- });
+ expect(compiled.model).toBeUndefined();
expect(compiled.dynamicModel).toEqual({
eventNames: ["session.started", "step.started"],
logicalPath: "agent.ts",
sourceId: "agent-config",
sourceKind: "module",
});
+ expect(modelCatalog.getModelLimits).not.toHaveBeenCalled();
});
- it("compiles an injected dynamic-subagent placeholder without reloading agent.ts", async () => {
+ it("compiles an injected agent definition without reloading agent.ts", async () => {
const manifest = createAgentSourceManifest({
agentId: "researcher",
agentRoot: "/app/agent/subagents/researcher",
diff --git a/packages/eve/src/compiler/normalize-agent-config.ts b/packages/eve/src/compiler/normalize-agent-config.ts
index 710f6fc68..8faf3dfb5 100644
--- a/packages/eve/src/compiler/normalize-agent-config.ts
+++ b/packages/eve/src/compiler/normalize-agent-config.ts
@@ -54,18 +54,21 @@ 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",
- contextWindowTokens: definition.modelContextWindowTokens,
- providerOptions: definition.modelOptions?.providerOptions,
- source: configModule,
- sourcePath: configModulePath,
- value: authoredModel,
- });
+ const dynamicModelDefinition = isDynamicModelDefinition(definition.model)
+ ? definition.model
+ : undefined;
+ const model =
+ dynamicModelDefinition === undefined
+ ? await normalizeAuthoredModelReference({
+ modelCatalog: context.modelCatalog,
+ purpose: "the primary compaction trigger model",
+ contextWindowTokens: definition.modelContextWindowTokens,
+ providerOptions: definition.modelOptions?.providerOptions,
+ source: configModule,
+ sourcePath: configModulePath,
+ value: definition.model as PublicAgentStaticModelDefinition,
+ })
+ : undefined;
const compaction: {
model?: CompiledRuntimeModelReference;
thresholdPercent?: number;
@@ -78,9 +81,7 @@ export async function compileAgentConfig(
thresholdPercent?: number;
};
description?: string;
- dynamicModel?: CompiledAgentDefinition["dynamicModel"];
experimental?: CompiledAgentDefinition["experimental"];
- model: CompiledRuntimeModelReference;
name: string;
outputSchema?: JsonObject;
reasoning?: CompiledAgentDefinition["reasoning"];
@@ -88,7 +89,6 @@ export async function compileAgentConfig(
limits?: CompiledAgentDefinition["limits"];
} = {
compaction,
- model,
name: manifest.agentId,
};
@@ -96,12 +96,13 @@ export async function compileAgentConfig(
compiledConfig.description = definition.description;
}
- if (isDynamicModelDefinition(definition.model)) {
+ let dynamicModel: CompiledAgentDefinition["dynamicModel"] | undefined;
+ if (dynamicModelDefinition !== undefined) {
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[],
+ dynamicModel = {
+ eventNames: Object.keys(dynamicModelDefinition.events) as DynamicToolEventName[],
exportName: configModule.exportName,
sourceKind: "module",
logicalPath: configModule.logicalPath,
@@ -164,7 +165,15 @@ export async function compileAgentConfig(
compaction.thresholdPercent = definition.compaction.thresholdPercent;
}
- return compiledConfig;
+ if (dynamicModel !== undefined) {
+ return { ...compiledConfig, dynamicModel };
+ }
+
+ if (model === undefined) {
+ throw new Error("Expected a static agent model to compile to a concrete model reference.");
+ }
+
+ return { ...compiledConfig, model };
}
function normalizeExperimentalDefinition(
@@ -265,6 +274,7 @@ async function normalizeAuthoredModelReference(input: {
...sourceBackedModel,
id: providerResult.slug,
contextWindowTokens: providerResult.limits.contextWindowTokens,
+ maxOutputTokens: providerResult.limits.maxOutputTokens,
};
}
}
@@ -333,6 +343,7 @@ async function withCompiledRuntimeModelLimits(
return {
...model,
contextWindowTokens: limits.contextWindowTokens,
+ maxOutputTokens: limits.maxOutputTokens,
};
}
diff --git a/packages/eve/src/compiler/normalize-instructions.ts b/packages/eve/src/compiler/normalize-instructions.ts
index 04832b631..6b89c6a0a 100644
--- a/packages/eve/src/compiler/normalize-instructions.ts
+++ b/packages/eve/src/compiler/normalize-instructions.ts
@@ -10,8 +10,8 @@ import {
type ModuleBackedDefinitionLoadOptions,
} from "#compiler/normalize-helpers.js";
import {
+ assertResolverOnlyDynamicSentinel,
isDynamicSentinel,
- rejectDynamicSentinelFallback,
type DynamicToolEventName,
} from "#shared/dynamic-tool-definition.js";
@@ -72,7 +72,7 @@ export async function compileInstructionsEntry(
});
if (isDynamicSentinel(exportValue)) {
- rejectDynamicSentinelFallback(
+ assertResolverOnlyDynamicSentinel(
exportValue,
`Expected the instructions export "${source.exportName ?? "default"}" from "${source.logicalPath}" to match the public eve shape.`,
);
diff --git a/packages/eve/src/compiler/normalize-manifest.test.ts b/packages/eve/src/compiler/normalize-manifest.test.ts
index d09f7afd5..28f458390 100644
--- a/packages/eve/src/compiler/normalize-manifest.test.ts
+++ b/packages/eve/src/compiler/normalize-manifest.test.ts
@@ -13,7 +13,6 @@ import { collectModuleRefsForManifest } from "#compiler/module-map.js";
import { defineAgent, defineDynamic } from "#public/definitions/agent.js";
import { experimental_workflow } from "#public/definitions/tool.js";
import { webSearch } from "#public/tools/web-search.js";
-import { DEFAULT_AGENT_MODEL_ID } from "#shared/default-agent-model.js";
const mocks = vi.hoisted(() => ({
compileAgentConfig: vi.fn(),
@@ -213,13 +212,15 @@ describe("compileAgentManifest", () => {
const compiled = await compileAgentManifest(manifest);
- expect(compiled.subagents[0]?.dynamic).toEqual({
+ expect(compiled.subagents[0]?.configResolver).toMatchObject({
eventNames: ["session.started", "turn.started"],
+ logicalPath: "agent.ts",
+ sourceId: "agent.ts",
+ sourceKind: "module",
});
+ expect("config" in compiled.subagents[0]!.agent).toBe(false);
expect(compiled.subagents[0]?.description).toBeUndefined();
- expect(mocks.compileAgentConfig.mock.calls[1]?.[2]).toMatchObject({
- definition: { model: DEFAULT_AGENT_MODEL_ID },
- });
+ expect(mocks.compileAgentConfig).toHaveBeenCalledTimes(1);
});
it("applies dynamic subagent build configuration before resolving events", async () => {
@@ -241,15 +242,15 @@ describe("compileAgentManifest", () => {
const compiled = await compileAgentManifest(manifest);
- expect(compiled.subagents[0]?.dynamic).toEqual({
+ expect(compiled.subagents[0]?.configResolver).toMatchObject({
+ build: { externalDependencies: ["just-bash"] },
eventNames: ["session.started"],
+ logicalPath: "agent.ts",
+ sourceId: "agent.ts",
+ sourceKind: "module",
});
- expect(mocks.compileAgentConfig.mock.calls[1]?.[2]).toMatchObject({
- definition: {
- build: { externalDependencies: ["just-bash"] },
- model: DEFAULT_AGENT_MODEL_ID,
- },
- });
+ expect("config" in compiled.subagents[0]!.agent).toBe(false);
+ expect(mocks.compileAgentConfig).toHaveBeenCalledTimes(1);
});
it("rejects invalid dynamic subagent build configuration", async () => {
@@ -267,20 +268,20 @@ describe("compileAgentManifest", () => {
it("rejects fallback on a dynamic subagent", async () => {
mocks.compileAgentConfig.mockResolvedValue(createConfig({ name: "root" }));
- mocks.loadModuleBackedDefinition.mockResolvedValue(
- defineDynamic({
- fallback: defineAgent({
- description: "Research the request.",
- model: "openai/gpt-5.5",
- }),
+ mocks.loadModuleBackedDefinition.mockResolvedValue({
+ ...defineDynamic({
events: {
"session.started": () => null,
},
}),
- );
+ fallback: defineAgent({
+ description: "Research the request.",
+ model: "openai/gpt-5.5",
+ }),
+ });
await expect(compileAgentManifest(createManifestWithSubagent())).rejects.toThrow(
- 'Dynamic subagent definitions do not support "fallback"',
+ 'Unknown key "fallback"',
);
});
diff --git a/packages/eve/src/compiler/normalize-manifest.ts b/packages/eve/src/compiler/normalize-manifest.ts
index 1e9bf0b88..e93ea50d4 100644
--- a/packages/eve/src/compiler/normalize-manifest.ts
+++ b/packages/eve/src/compiler/normalize-manifest.ts
@@ -3,6 +3,7 @@ import { mountRefNamespace, packageStateNamespace } from "#discover/extensions.j
import {
type CompiledAgentManifest,
type CompiledAgentNodeManifest,
+ type CompiledAgentResources,
type CompiledDynamicInstructionsDefinition,
type CompiledExtensionMount,
type CompiledDynamicSkillDefinition,
@@ -13,6 +14,7 @@ import {
type CompiledWorkflowToolDefinition,
createCompiledAgentManifest,
createCompiledAgentNodeManifest,
+ createCompiledAgentResources,
ROOT_COMPILED_AGENT_NODE_ID,
} from "#compiler/manifest.js";
import type { WebSearchProvider } from "#shared/web-search.js";
@@ -43,6 +45,7 @@ export async function compileAgentManifest(
const subagentGraph = await compileSubagentGraph({
appRoot: manifest.appRoot,
compileAgentNodeManifest,
+ compileAgentResources,
context,
externalDependencies: compiledNode.config.build?.externalDependencies ?? [],
parentNodeId: ROOT_COMPILED_AGENT_NODE_ID,
@@ -91,6 +94,16 @@ async function compileAgentNodeManifest(
externalDependencies,
},
};
+ const resources = await compileAgentResources(manifest, context, { externalDependencies });
+ return createCompiledAgentNodeManifest({ ...resources, config });
+}
+
+async function compileAgentResources(
+ manifest: AgentSourceManifest,
+ context: ManifestCompileContext,
+ options: { readonly externalDependencies?: readonly string[] } = {},
+): Promise<CompiledAgentResources> {
+ const externalDependencies = [...(options.externalDependencies ?? [])];
const compiledToolEntries = await Promise.all(
manifest.tools.map((toolSource) =>
compileToolEntry(manifest.agentRoot, toolSource, { externalDependencies }),
@@ -234,12 +247,11 @@ async function compileAgentNodeManifest(
sourceKind: "module",
};
- return createCompiledAgentNodeManifest({
+ return createCompiledAgentResources({
agentRoot: manifest.agentRoot,
appRoot: manifest.appRoot,
channels: compiledChannels,
extensionMounts: compileExtensionMounts(manifest),
- config,
connections,
diagnosticsSummary: manifest.diagnosticsSummary,
disabledFrameworkTools,
diff --git a/packages/eve/src/compiler/normalize-skill.ts b/packages/eve/src/compiler/normalize-skill.ts
index e54d3b646..32f3c9e10 100644
--- a/packages/eve/src/compiler/normalize-skill.ts
+++ b/packages/eve/src/compiler/normalize-skill.ts
@@ -12,8 +12,8 @@ import {
type ModuleBackedDefinitionLoadOptions,
} from "#compiler/normalize-helpers.js";
import {
+ assertResolverOnlyDynamicSentinel,
isDynamicSentinel,
- rejectDynamicSentinelFallback,
type DynamicToolEventName,
} from "#shared/dynamic-tool-definition.js";
@@ -76,7 +76,7 @@ export async function compileSkillSource(
});
if (isDynamicSentinel(exportValue)) {
- rejectDynamicSentinelFallback(
+ assertResolverOnlyDynamicSentinel(
exportValue,
`Expected the skill export "${source.exportName ?? "default"}" from "${source.logicalPath}" to match the public eve shape.`,
);
diff --git a/packages/eve/src/compiler/normalize-subagent.ts b/packages/eve/src/compiler/normalize-subagent.ts
index fcb5b18ac..07c6b2fb2 100644
--- a/packages/eve/src/compiler/normalize-subagent.ts
+++ b/packages/eve/src/compiler/normalize-subagent.ts
@@ -5,11 +5,13 @@ import {
} from "#discover/manifest.js";
import {
type CompiledAgentNodeManifest,
+ type CompiledAgentResources,
type CompiledRemoteAgentNode,
type CompiledSubagentEdge,
type CompiledSubagentNode,
createCompiledSubagentNodeId,
} from "#compiler/manifest.js";
+import type { CompiledDynamicSubagentDefinition } from "#compiler/remote-agent-node.js";
import {
loadModuleBackedDefinition,
type ManifestCompileContext,
@@ -22,11 +24,9 @@ import {
expectString,
} from "#internal/authored-module.js";
import { EVE_SESSION_ROUTE_PATH } from "#protocol/routes.js";
-import { DEFAULT_AGENT_MODEL_ID } from "#shared/default-agent-model.js";
import { serializeOutputSchema, type ToolSchemaSource } from "#shared/tool-schema.js";
import type { JsonObject } from "#shared/json.js";
import { isDynamicSentinel, type DynamicToolEventName } from "#shared/dynamic-tool-definition.js";
-import { normalizeAgentDefinition } from "#internal/authored-definition/core.js";
const ALLOWED_DYNAMIC_SUBAGENT_EVENTS = new Set<DynamicToolEventName>([
"session.started",
@@ -49,6 +49,12 @@ export type CompileAgentNodeManifestFn = (
},
) => Promise<CompiledAgentNodeManifest>;
+export type CompileAgentResourcesFn = (
+ manifest: AgentSourceManifest,
+ context: ManifestCompileContext,
+ options?: { readonly externalDependencies?: readonly string[] },
+) => Promise<CompiledAgentResources>;
+
/**
* Compiles every local subagent reachable from one parent node into a
* flat node list and the parent→child edges that connect them.
@@ -60,6 +66,7 @@ export type CompileAgentNodeManifestFn = (
export async function compileSubagentGraph(input: {
readonly appRoot: string;
readonly compileAgentNodeManifest: CompileAgentNodeManifestFn;
+ readonly compileAgentResources: CompileAgentResourcesFn;
readonly context: ManifestCompileContext;
readonly externalDependencies?: readonly string[];
readonly parentNodeId: string;
@@ -77,6 +84,7 @@ export async function compileSubagentGraph(input: {
const compiledSubagent = await compileSubagentDefinition({
appRoot: input.appRoot,
compileAgentNodeManifest: input.compileAgentNodeManifest,
+ compileAgentResources: input.compileAgentResources,
context: input.context,
externalDependencies: input.externalDependencies,
parentNodeId: input.parentNodeId,
@@ -108,6 +116,7 @@ export async function compileSubagentGraph(input: {
async function compileSubagentDefinition(input: {
readonly appRoot: string;
readonly compileAgentNodeManifest: CompileAgentNodeManifestFn;
+ readonly compileAgentResources: CompileAgentResourcesFn;
readonly context: ManifestCompileContext;
readonly externalDependencies?: readonly string[];
readonly parentNodeId: string;
@@ -155,24 +164,15 @@ async function compileSubagentDefinition(input: {
};
}
- let agentConfigDefinition = definition;
- if (dynamic !== undefined) {
- const dynamicAgentConfig: {
- build?: { readonly externalDependencies?: readonly string[] };
- readonly model: string;
- } = { model: DEFAULT_AGENT_MODEL_ID };
- if (dynamic.build !== undefined) {
- dynamicAgentConfig.build = dynamic.build;
- }
- agentConfigDefinition = dynamicAgentConfig;
- }
-
return {
kind: "local",
...(await compileLocalSubagent({
...input,
- agentConfigDefinition,
- dynamic: dynamic?.definition,
+ agentConfigDefinition: dynamic === undefined ? definition : undefined,
+ configResolver:
+ dynamic === undefined
+ ? undefined
+ : { ...configModule, ...dynamic.definition, build: dynamic.build },
})),
};
}
@@ -180,9 +180,10 @@ async function compileSubagentDefinition(input: {
async function compileSubagent(input: {
readonly appRoot: string;
readonly compileAgentNodeManifest: CompileAgentNodeManifestFn;
+ readonly compileAgentResources: CompileAgentResourcesFn;
readonly context: ManifestCompileContext;
readonly agentConfigDefinition?: unknown;
- readonly dynamic?: { readonly eventNames: readonly string[] };
+ readonly configResolver?: CompiledDynamicSubagentDefinition;
readonly externalDependencies?: readonly string[];
readonly parentNodeId: string;
readonly source: LocalSubagentSourceRef;
@@ -196,62 +197,75 @@ async function compileSubagent(input: {
}> {
const nodeId = createCompiledSubagentNodeId(input.parentNodeId, input.source.sourceId);
const subagentName = input.source.subagentId;
- const agent = await input.compileAgentNodeManifest(
- {
- ...input.source.manifest,
- appRoot: input.appRoot,
- },
- input.context,
- {
- agentConfigDefinition: input.agentConfigDefinition,
- allowWorkflowConfig: false,
- externalDependencies: input.externalDependencies,
- },
+ const sourceManifest = {
+ ...input.source.manifest,
+ appRoot: input.appRoot,
+ };
+ const inheritedExternalDependencies = mergeExternalDependencies(
+ input.externalDependencies,
+ input.configResolver?.build?.externalDependencies,
);
+ const nodeBase = {
+ entryPath: input.source.entryPath,
+ logicalPath: input.source.logicalPath,
+ name: subagentName,
+ nodeId,
+ rootPath: input.source.rootPath,
+ sourceId: input.source.sourceId,
+ sourceKind: "module" as const,
+ };
- const description = agent.config.description;
-
- let variant:
- | { readonly description: string; readonly dynamic?: never }
- | {
- readonly description?: never;
- readonly dynamic: { readonly eventNames: readonly string[] };
- };
-
- if (input.dynamic !== undefined) {
- variant = { dynamic: input.dynamic };
- } else {
+ if (input.configResolver === undefined) {
+ const agent = await input.compileAgentNodeManifest(sourceManifest, input.context, {
+ agentConfigDefinition: input.agentConfigDefinition,
+ allowWorkflowConfig: false,
+ externalDependencies: inheritedExternalDependencies,
+ });
+ const description = agent.config.description;
if (!description) {
throw new Error(
`Local subagent "${input.source.logicalPath}" is missing a "description" field on its agent config. Add \`description\` to \`defineAgent({ ... })\` so the parent agent can decide when to delegate to this subagent.`,
);
}
- variant = { description };
+
+ const descendants = await compileSubagentGraph({
+ appRoot: input.appRoot,
+ compileAgentNodeManifest: input.compileAgentNodeManifest,
+ context: input.context,
+ compileAgentResources: input.compileAgentResources,
+ externalDependencies:
+ agent.config.build?.externalDependencies ?? inheritedExternalDependencies,
+ parentNodeId: nodeId,
+ subagents: input.source.manifest.subagents,
+ });
+ return {
+ descendants,
+ node: {
+ ...nodeBase,
+ agent: { ...agent, remoteAgents: [...descendants.remoteAgents] },
+ description,
+ },
+ };
}
+ const resources = await input.compileAgentResources(sourceManifest, input.context, {
+ externalDependencies: inheritedExternalDependencies,
+ });
const descendants = await compileSubagentGraph({
appRoot: input.appRoot,
compileAgentNodeManifest: input.compileAgentNodeManifest,
context: input.context,
- externalDependencies: agent.config.build?.externalDependencies,
+ compileAgentResources: input.compileAgentResources,
+ externalDependencies: inheritedExternalDependencies,
parentNodeId: nodeId,
subagents: input.source.manifest.subagents,
});
return {
descendants,
node: {
- agent: {
- ...agent,
- remoteAgents: [...descendants.remoteAgents],
- },
- ...variant,
- entryPath: input.source.entryPath,
- logicalPath: input.source.logicalPath,
- name: subagentName,
- nodeId,
- rootPath: input.source.rootPath,
- sourceId: input.source.sourceId,
- sourceKind: "module",
+ ...nodeBase,
+ agent: { ...resources, remoteAgents: [...descendants.remoteAgents] },
+ configResolver: input.configResolver,
},
};
}
@@ -304,18 +318,10 @@ function normalizeDynamicSubagentDefinition(
}
const record = expectObjectRecord(value, message);
- if (Object.hasOwn(record, "fallback")) {
- throw new Error(
- `${message} Dynamic subagent definitions do not support "fallback". Return defineAgent(...) or defineRemoteAgent(...) from an event handler instead.`,
- );
- }
expectOnlyKnownKeys(record, ["build", "events", "kind"], message);
const build =
- record.build === undefined
- ? undefined
- : normalizeAgentDefinition({ build: record.build, model: DEFAULT_AGENT_MODEL_ID }, message)
- .build;
+ record.build === undefined ? undefined : normalizeDynamicSubagentBuild(record.build, message);
const rawEvents = expectObjectRecord(record.events, message);
const eventNames: DynamicToolEventName[] = [];
@@ -341,6 +347,25 @@ function normalizeDynamicSubagentDefinition(
return normalized;
}
+function normalizeDynamicSubagentBuild(
+ value: unknown,
+ message: string,
+): { readonly externalDependencies?: readonly string[] } {
+ const record = expectObjectRecord(value, message);
+ expectOnlyKnownKeys(record, ["externalDependencies"], message);
+ if (record.externalDependencies === undefined) return {};
+ if (!Array.isArray(record.externalDependencies)) throw new Error(message);
+ return {
+ externalDependencies: record.externalDependencies.map((entry) => expectString(entry, message)),
+ };
+}
+
+function mergeExternalDependencies(
+ ...lists: ReadonlyArray<readonly string[] | undefined>
+): readonly string[] {
+ return [...new Set(lists.flatMap((list) => list ?? []))];
+}
+
function createSubagentConfigModuleSourceRef(
source: LocalSubagentSourceRef,
configModule: NonNullable<LocalSubagentSourceRef["manifest"]["configModule"]>,
diff --git a/packages/eve/src/compiler/remote-agent-node.ts b/packages/eve/src/compiler/remote-agent-node.ts
index 1d2f43256..b1122f114 100644
--- a/packages/eve/src/compiler/remote-agent-node.ts
+++ b/packages/eve/src/compiler/remote-agent-node.ts
@@ -5,7 +5,10 @@ import type { JsonObject } from "#shared/json.js";
import type { Node } from "#shared/node.js";
import type { ModuleSourceRef } from "#shared/source-ref.js";
-export interface CompiledDynamicSubagentDefinition {
+export interface CompiledDynamicSubagentDefinition extends Readonly<ModuleSourceRef> {
+ readonly build?: {
+ readonly externalDependencies?: readonly string[];
+ };
readonly eventNames: readonly string[];
}
diff --git a/packages/eve/src/compiler/workspace-resources.ts b/packages/eve/src/compiler/workspace-resources.ts
index 9956d0ab3..5244f8821 100644
--- a/packages/eve/src/compiler/workspace-resources.ts
+++ b/packages/eve/src/compiler/workspace-resources.ts
@@ -4,7 +4,7 @@ import { join, posix as pathPosix } from "node:path";
import type {
CompiledAgentManifest,
- CompiledAgentNodeManifest,
+ CompiledAgentResources,
CompiledSkillDefinition,
CompiledWorkspaceResourceRoot,
} from "#compiler/manifest.js";
@@ -38,14 +38,27 @@ export async function materializeWorkspaceResources(input: {
manifest: input.manifest,
});
const subagents = await Promise.all(
- input.manifest.subagents.map(async (subagent) => ({
- ...subagent,
- agent: await materializeNode({
- nodeId: subagent.nodeId,
- resourcesRoot,
- manifest: subagent.agent,
- }),
- })),
+ input.manifest.subagents.map(async (subagent) => {
+ if (subagent.configResolver === undefined) {
+ return {
+ ...subagent,
+ agent: await materializeNode({
+ nodeId: subagent.nodeId,
+ resourcesRoot,
+ manifest: subagent.agent,
+ }),
+ };
+ }
+ return {
+ ...subagent,
+ agent: await materializeNode({
+ nodeId: subagent.nodeId,
+ resourcesRoot,
+ manifest: subagent.agent,
+ }),
+ configResolver: subagent.configResolver,
+ };
+ }),
);
return {
@@ -59,7 +72,7 @@ export async function materializeWorkspaceResources(input: {
}
function createResourceRoot(
- manifest: CompiledAgentNodeManifest,
+ manifest: CompiledAgentResources,
nodeId: string,
contentHash: string | undefined,
): CompiledWorkspaceResourceRoot {
@@ -73,11 +86,11 @@ function createResourceRoot(
};
}
-async function materializeNode(input: {
- readonly manifest: CompiledAgentNodeManifest;
+async function materializeNode<TManifest extends CompiledAgentResources>(input: {
+ readonly manifest: TManifest;
readonly nodeId: string;
readonly resourcesRoot: string;
-}): Promise<CompiledAgentNodeManifest> {
+}): Promise<TManifest> {
const nodeRoot = join(input.resourcesRoot, input.nodeId);
await mkdir(nodeRoot, { recursive: true });
diff --git a/packages/eve/src/context/dynamic-model-lifecycle.test.ts b/packages/eve/src/context/dynamic-model-lifecycle.test.ts
index cb5febdde..990e59539 100644
--- a/packages/eve/src/context/dynamic-model-lifecycle.test.ts
+++ b/packages/eve/src/context/dynamic-model-lifecycle.test.ts
@@ -8,7 +8,11 @@ import {
dispatchDynamicModelEvent,
getActiveDynamicModelSelection,
} from "#context/dynamic-model-lifecycle.js";
-import { SessionDynamicModelReferenceKey, TurnDynamicModelReferenceKey } from "#context/keys.js";
+import {
+ LiveStepDynamicModelSelectionKey,
+ SessionDynamicModelReferenceKey,
+ TurnDynamicModelReferenceKey,
+} from "#context/keys.js";
import { defineDynamic } from "#public/definitions/tool.js";
import {
createSessionStartedEvent,
@@ -24,8 +28,6 @@ const DYNAMIC_MODEL_SOURCE: RuntimeDynamicModelReference = {
sourceKind: "module",
};
-const FALLBACK = { contextWindowTokens: 256_000, id: "openai/gpt-5.5" };
-
afterEach(() => {
vi.unstubAllEnvs();
});
@@ -36,7 +38,6 @@ describe("dynamic model lifecycle", () => {
const moduleMap = createModuleMap({
default: {
model: defineDynamic({
- fallback: "openai/gpt-5.5",
events: {
"session.started": () => ({
model: "openai/gpt-5.5-mini",
@@ -51,7 +52,6 @@ describe("dynamic model lifecycle", () => {
ctx,
dynamicModel: DYNAMIC_MODEL_SOURCE,
event: createSessionStartedEvent(),
- fallback: FALLBACK,
messages: [],
scope: { moduleMap, nodeId: undefined },
});
@@ -60,69 +60,62 @@ describe("dynamic model lifecycle", () => {
reference: {
contextWindowTokens: 128_000,
id: "openai/gpt-5.5-mini",
+ maxOutputTokens: undefined,
providerOptions: undefined,
},
});
});
- it("does not inherit the fallback context window for a different model", async () => {
+ it("prefers step, then turn, then session selections", () => {
const ctx = new ContextContainer();
- const moduleMap = createModuleMap({
- default: {
- model: defineDynamic({
- fallback: "openai/gpt-5.5",
- events: {
- "session.started": () => "openai/gpt-5.5-mini",
- },
- }),
- },
+ ctx.set(SessionDynamicModelReferenceKey, {
+ contextWindowTokens: 100_000,
+ id: "openai/session",
});
-
- await dispatchDynamicModelEvent({
- ctx,
- dynamicModel: DYNAMIC_MODEL_SOURCE,
- event: createSessionStartedEvent(),
- fallback: FALLBACK,
- messages: [],
- scope: { moduleMap, nodeId: undefined },
+ ctx.set(TurnDynamicModelReferenceKey, {
+ contextWindowTokens: 100_000,
+ id: "openai/turn",
});
- expect(getActiveDynamicModelSelection(ctx)?.reference.contextWindowTokens).toBeUndefined();
+ expect(getActiveDynamicModelSelection(ctx)?.reference.id).toBe("openai/turn");
+
+ ctx.setVirtualContext(LiveStepDynamicModelSelectionKey, {
+ reference: { contextWindowTokens: 100_000, id: "openai/step" },
+ });
+ expect(getActiveDynamicModelSelection(ctx)?.reference.id).toBe("openai/step");
});
- it("lets turn-scoped selections override session selections and null fall back", async () => {
+ it("replaces turn-scoped selections on each matching turn", async () => {
const ctx = new ContextContainer();
- let turnResult: string | null = "openai/gpt-5.5-turn";
+ let turnModel = "openai/first-turn";
const moduleMap = createModuleMap({
default: {
model: defineDynamic({
- fallback: "openai/gpt-5.5",
events: {
- "session.started": () => "openai/gpt-5.5-mini",
- "turn.started": () => turnResult,
+ "turn.started": () => ({
+ model: turnModel,
+ modelContextWindowTokens: 100_000,
+ }),
},
}),
},
});
- const dispatch = (event: Parameters<typeof dispatchDynamicModelEvent>[0]["event"]) =>
+
+ const dispatch = (sequence: number) =>
dispatchDynamicModelEvent({
ctx,
dynamicModel: DYNAMIC_MODEL_SOURCE,
- event,
- fallback: FALLBACK,
+ event: createTurnStartedEvent({ sequence, turnId: `turn_${sequence}` }),
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" }));
+ await dispatch(0);
+ expect(getActiveDynamicModelSelection(ctx)?.reference.id).toBe("openai/first-turn");
- expect(getActiveDynamicModelSelection(ctx)?.reference.id).toBe("openai/gpt-5.5-mini");
+ turnModel = "openai/second-turn";
+ await dispatch(1);
+ expect(getActiveDynamicModelSelection(ctx)?.reference.id).toBe("openai/second-turn");
});
it("keeps step-scoped live provider instances outside mock mode", async () => {
@@ -132,10 +125,11 @@ describe("dynamic model lifecycle", () => {
const moduleMap = createModuleMap({
default: {
model: defineDynamic({
- fallback: "openai/gpt-5.5",
events: {
- "session.started": () => "openai/gpt-5.5-mini",
- "step.started": () => stepModel,
+ "step.started": () => ({
+ model: stepModel,
+ modelContextWindowTokens: 64_000,
+ }),
},
}),
},
@@ -144,16 +138,12 @@ describe("dynamic model lifecycle", () => {
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" },
+ event: createStepStartedEvent({
+ modelId: "unresolved",
+ sequence: 0,
+ stepIndex: 0,
+ turnId: "turn_0",
+ }),
messages: [{ content: "Use the direct model.", role: "user" }],
scope: { moduleMap, nodeId: undefined },
});
@@ -161,23 +151,25 @@ describe("dynamic model lifecycle", () => {
expect(getActiveDynamicModelSelection(ctx)).toEqual({
model: stepModel,
reference: {
- contextWindowTokens: undefined,
+ contextWindowTokens: 64_000,
id: "openai/gpt-step",
+ maxOutputTokens: undefined,
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,
+ "step.started": () => ({
+ model: stepModel,
+ modelContextWindowTokens: 64_000,
+ }),
},
}),
},
@@ -186,55 +178,64 @@ describe("dynamic model lifecycle", () => {
await dispatchDynamicModelEvent({
ctx,
dynamicModel: DYNAMIC_MODEL_SOURCE,
- event: createStepStartedEvent({ sequence: 0, stepIndex: 0, turnId: "turn_0" }),
- fallback: { id: "openai/gpt-5.5" },
+ event: createStepStartedEvent({
+ modelId: "unresolved",
+ sequence: 0,
+ stepIndex: 0,
+ turnId: "turn_0",
+ }),
messages: [],
scope: { moduleMap, nodeId: undefined },
});
expect(getActiveDynamicModelSelection(ctx)).toEqual({
reference: {
- contextWindowTokens: undefined,
+ contextWindowTokens: 64_000,
id: "openai/gpt-step",
+ maxOutputTokens: undefined,
providerOptions: undefined,
},
});
});
- it("rejects live provider instances at session and turn scope", async () => {
+ it("rejects live provider instances at durable scopes", 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,
+ "session.started": () => ({
+ model: liveModel,
+ modelContextWindowTokens: 64_000,
+ }),
},
}),
},
});
- await dispatchDynamicModelEvent({
- ctx,
- dynamicModel: DYNAMIC_MODEL_SOURCE,
- event: createSessionStartedEvent(),
- fallback: FALLBACK,
- messages: [],
- scope: { moduleMap, nodeId: undefined },
- });
+ await expect(
+ dispatchDynamicModelEvent({
+ ctx,
+ dynamicModel: DYNAMIC_MODEL_SOURCE,
+ event: createSessionStartedEvent(),
+ messages: [],
+ scope: { moduleMap, nodeId: undefined },
+ }),
+ ).rejects.toThrow(/must be serializable/);
expect(ctx.get(SessionDynamicModelReferenceKey)).toBeNull();
- expect(getActiveDynamicModelSelection(ctx)).toBeNull();
});
- it("clears the scope and falls back when a resolver throws", async () => {
+ it("propagates resolver exceptions without selecting a fallback", async () => {
const ctx = new ContextContainer();
- ctx.set(TurnDynamicModelReferenceKey, { id: "openai/gpt-prior" });
+ ctx.set(TurnDynamicModelReferenceKey, {
+ contextWindowTokens: 100_000,
+ id: "openai/previous-turn",
+ });
const moduleMap = createModuleMap({
default: {
model: defineDynamic({
- fallback: "openai/gpt-5.5",
events: {
"turn.started": () => {
throw new Error("flag service unavailable");
@@ -244,46 +245,49 @@ describe("dynamic model lifecycle", () => {
},
});
- await dispatchDynamicModelEvent({
- ctx,
- dynamicModel: DYNAMIC_MODEL_SOURCE,
- event: createTurnStartedEvent({ sequence: 0, turnId: "turn_0" }),
- fallback: FALLBACK,
- messages: [],
- scope: { moduleMap, nodeId: undefined },
- });
+ await expect(
+ dispatchDynamicModelEvent({
+ ctx,
+ dynamicModel: DYNAMIC_MODEL_SOURCE,
+ event: createTurnStartedEvent({ sequence: 0, turnId: "turn_0" }),
+ messages: [],
+ scope: { moduleMap, nodeId: undefined },
+ }),
+ ).rejects.toThrow("flag service unavailable");
expect(ctx.get(TurnDynamicModelReferenceKey)).toBeNull();
expect(getActiveDynamicModelSelection(ctx)).toBeNull();
});
- it("clears the scope when a selection carries unknown keys", async () => {
+ it("rejects null and malformed selections", async () => {
const ctx = new ContextContainer();
+ let result: unknown = null;
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,
+ "session.started": () => result as never,
},
}),
},
});
+ const dispatch = () =>
+ dispatchDynamicModelEvent({
+ ctx,
+ dynamicModel: DYNAMIC_MODEL_SOURCE,
+ event: createSessionStartedEvent(),
+ messages: [],
+ scope: { moduleMap, nodeId: undefined },
+ });
- await dispatchDynamicModelEvent({
- ctx,
- dynamicModel: DYNAMIC_MODEL_SOURCE,
- event: createSessionStartedEvent(),
- fallback: FALLBACK,
- messages: [],
- scope: { moduleMap, nodeId: undefined },
- });
+ await expect(dispatch()).rejects.toThrow(/returned no model/);
+ expect(ctx.get(SessionDynamicModelReferenceKey)).toBeNull();
- expect(getActiveDynamicModelSelection(ctx)).toBeNull();
+ result = {
+ contextWindowTokens: 128_000,
+ model: "openai/gpt-5.5-mini",
+ };
+ await expect(dispatch()).rejects.toThrow(/unknown key\(s\): contextWindowTokens/);
});
});
diff --git a/packages/eve/src/context/dynamic-model-lifecycle.ts b/packages/eve/src/context/dynamic-model-lifecycle.ts
index 76e4886b2..95578b4a4 100644
--- a/packages/eve/src/context/dynamic-model-lifecycle.ts
+++ b/packages/eve/src/context/dynamic-model-lifecycle.ts
@@ -9,7 +9,6 @@ import {
TurnDynamicModelReferenceKey,
type LiveDynamicModelSelection,
} from "#context/keys.js";
-import { createLogger } from "#internal/logging.js";
import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import type {
RuntimeDynamicModelReference,
@@ -17,15 +16,13 @@ import type {
} from "#runtime/agent/bootstrap.js";
import {
loadDynamicRuntimeModelDefinition,
- normalizeDynamicRuntimeModelResult,
+ resolveRuntimeModelSelection,
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");
+import { toErrorMessage } from "#shared/errors.js";
const ALLOWED_DYNAMIC_MODEL_EVENTS = new Set<DynamicToolEventName>([
"session.started",
@@ -35,6 +32,26 @@ const ALLOWED_DYNAMIC_MODEL_EVENTS = new Set<DynamicToolEventName>([
export type ActiveDynamicModelSelection = LiveDynamicModelSelection;
+const DYNAMIC_MODEL_SELECTION_ERROR_CODE = "EVE_DYNAMIC_MODEL_SELECTION_FAILED";
+
+export class DynamicModelSelectionError extends Error {
+ readonly code = DYNAMIC_MODEL_SELECTION_ERROR_CODE;
+ override readonly name = "DynamicModelSelectionError";
+
+ constructor(error: unknown) {
+ super(toErrorMessage(error), { cause: error });
+ }
+}
+
+export function isDynamicModelSelectionError(error: unknown): error is DynamicModelSelectionError {
+ return (
+ error instanceof DynamicModelSelectionError ||
+ (typeof error === "object" &&
+ error !== null &&
+ (error as { readonly code?: unknown }).code === DYNAMIC_MODEL_SELECTION_ERROR_CODE)
+ );
+}
+
function isDynamicModelEventName(value: string): value is DynamicToolEventName {
return ALLOWED_DYNAMIC_MODEL_EVENTS.has(value as DynamicToolEventName);
}
@@ -77,7 +94,6 @@ export async function dispatchDynamicModelEvent(input: {
readonly ctx: AlsContext;
readonly dynamicModel: RuntimeDynamicModelReference | undefined;
readonly event: UnstampedMessageStreamEvent;
- readonly fallback: RuntimeModelReference;
readonly messages: readonly ModelMessage[];
readonly scope: RuntimeModelResolutionScope;
}): Promise<void> {
@@ -85,6 +101,7 @@ export async function dispatchDynamicModelEvent(input: {
if (!isDynamicModelEventName(input.event.type)) return;
if (!input.dynamicModel.eventNames.includes(input.event.type)) return;
+ setSelectionForEvent(input.ctx, input.event.type, null);
try {
const definition = await loadDynamicRuntimeModelDefinition({
dynamicModel: input.dynamicModel,
@@ -93,37 +110,21 @@ export async function dispatchDynamicModelEvent(input: {
const handler = definition.events[input.event.type];
if (handler === undefined) {
- setSelectionForEvent(input.ctx, input.event.type, null);
- return;
+ throw new Error(
+ `Dynamic model resolver is missing its compiled "${input.event.type}" handler.`,
+ );
}
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;
- }
+ const selection = await resolveRuntimeModelSelection({
+ durability: input.event.type === "step.started" ? "live" : "durable",
+ selection: rawResult as never,
+ state: input.ctx,
+ });
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);
+ throw isDynamicModelSelectionError(error) ? error : new DynamicModelSelectionError(error);
}
}
diff --git a/packages/eve/src/context/dynamic-subagent-lifecycle.test.ts b/packages/eve/src/context/dynamic-subagent-lifecycle.test.ts
index d7cbea2ff..01e06d0ae 100644
--- a/packages/eve/src/context/dynamic-subagent-lifecycle.test.ts
+++ b/packages/eve/src/context/dynamic-subagent-lifecycle.test.ts
@@ -105,11 +105,13 @@ describe("dynamic subagent lifecycle", () => {
defineAgent({
description: "Research the request.",
model: "anthropic/claude-sonnet-4.5",
+ modelContextWindowTokens: 200_000,
}),
"turn.started": () =>
defineAgent({
description: "Research the request deeply.",
model: "anthropic/claude-opus-4.6",
+ modelContextWindowTokens: 200_000,
}),
},
};
@@ -276,6 +278,7 @@ function createResolver(
const agentConfig = defineAgent({
description: "Research the request.",
model: "openai/gpt-5.5",
+ modelContextWindowTokens: 200_000,
});
const eventNames = input.eventNames ?? ["session.started"];
const handler = input.handler ?? (() => null);
diff --git a/packages/eve/src/context/dynamic-subagent-lifecycle.ts b/packages/eve/src/context/dynamic-subagent-lifecycle.ts
index d9e834f77..415630f77 100644
--- a/packages/eve/src/context/dynamic-subagent-lifecycle.ts
+++ b/packages/eve/src/context/dynamic-subagent-lifecycle.ts
@@ -72,11 +72,13 @@ async function resolveSelections(input: {
const agentConfig = normalizeDynamicSubagentAgentConfig({
name: resolver.name,
+ state: input.ctx,
value: result,
});
+ const resolvedAgentConfig = await agentConfig;
const prepared = createPreparedRuntimeSubagentTool(
{
- description: agentConfig.description,
+ description: resolvedAgentConfig.description,
kind: "subagent",
logicalPath: resolver.logicalPath,
name: resolver.name,
@@ -87,7 +89,10 @@ async function resolveSelections(input: {
inputSchema,
);
- return [resolver.nodeId, { agentConfig, kind: "subagent", prepared }] as const;
+ return [
+ resolver.nodeId,
+ { agentConfig: resolvedAgentConfig, kind: "subagent", prepared },
+ ] as const;
}),
);
const selections: Record<string, DurableDynamicSubagentSelection> = {};
diff --git a/packages/eve/src/context/hook-lifecycle.integration.test.ts b/packages/eve/src/context/hook-lifecycle.integration.test.ts
index 3027318f5..b02a0a595 100644
--- a/packages/eve/src/context/hook-lifecycle.integration.test.ts
+++ b/packages/eve/src/context/hook-lifecycle.integration.test.ts
@@ -24,7 +24,13 @@ function createMockBundle(): CompiledBundle {
resolvedAgent: { config: { name: "test-agent" }, skills: [] } as never,
subagentRegistry: undefined as never,
toolRegistry: undefined as never,
- turnAgent: undefined as never,
+ turnAgent: {
+ id: "test-agent",
+ instructions: [],
+ model: { id: "openai/gpt-5.5" },
+ tools: [],
+ workspaceSpec: { rootEntries: [] },
+ },
};
}
diff --git a/packages/eve/src/context/hook-lifecycle.ts b/packages/eve/src/context/hook-lifecycle.ts
index 70f2655ea..8f99bdd5b 100644
--- a/packages/eve/src/context/hook-lifecycle.ts
+++ b/packages/eve/src/context/hook-lifecycle.ts
@@ -45,7 +45,7 @@ function buildHookContext(ctx: ContextContainer): HookContext {
return {
...callbackCtx,
agent: {
- name: bundle.resolvedAgent.config.name ?? "agent",
+ name: bundle.turnAgent.id,
nodeId: bundle.nodeId,
},
channel: {
diff --git a/packages/eve/src/context/keys.ts b/packages/eve/src/context/keys.ts
index 917c188bc..27199c22f 100644
--- a/packages/eve/src/context/keys.ts
+++ b/packages/eve/src/context/keys.ts
@@ -109,6 +109,18 @@ export const TurnDynamicModelReferenceKey = new ContextKey<RuntimeModelReference
"eve.turnDynamicModelReference",
);
+export interface CachedModelMetadata {
+ readonly contextWindowTokens: number;
+ readonly expiresAt: number;
+ readonly maxOutputTokens?: number;
+ readonly resolvedModelId: string;
+}
+
+/** Successful runtime catalog selections cached in durable workflow state. */
+export const RuntimeModelMetadataCacheKey = new ContextKey<
+ Readonly<Record<string, CachedModelMetadata>>
+>("eve.runtimeModelMetadataCache");
+
export interface LiveDynamicModelSelection {
/** Live provider instance; absent for string selections, which resolve through the reference. */
readonly model?: LanguageModel;
diff --git a/packages/eve/src/evals/target.test.ts b/packages/eve/src/evals/target.test.ts
index 4febf3026..e3e8a674e 100644
--- a/packages/eve/src/evals/target.test.ts
+++ b/packages/eve/src/evals/target.test.ts
@@ -123,7 +123,7 @@ function infoPayload(input: { readonly name: string }) {
agent: {
agentRoot: "/tmp/app/agent",
appRoot: "/tmp/app",
- model: { id: "mock" },
+ model: { id: "mock", routing: { kind: "gateway", target: "mock" } },
name: input.name,
},
capabilities: { devRoutes: true },
diff --git a/packages/eve/src/execution/dispatch-runtime-actions-step.ts b/packages/eve/src/execution/dispatch-runtime-actions-step.ts
index a6bbebe60..c7c7e1c15 100644
--- a/packages/eve/src/execution/dispatch-runtime-actions-step.ts
+++ b/packages/eve/src/execution/dispatch-runtime-actions-step.ts
@@ -158,7 +158,7 @@ export async function dispatchRuntimeActionsStep(input: {
// context, so this is the last place the parent's window is visible.
const parentTraceContext = readSessionTraceContext(input.serializedContext, session.sessionId);
const persistentSessions =
- bundle.resolvedAgent.config.experimental?.subagentPersistentSessions === true;
+ bundle.resolvedAgent.config?.experimental?.subagentPersistentSessions === true;
// A corrupt handle store throws; surface that before anything dispatches.
// A mid-loop throw after a sibling started would durably replay the whole
// batch and re-dispatch that sibling.
diff --git a/packages/eve/src/execution/effective-agent-config.ts b/packages/eve/src/execution/effective-agent-config.ts
index 3221a90b6..c9a099bdd 100644
--- a/packages/eve/src/execution/effective-agent-config.ts
+++ b/packages/eve/src/execution/effective-agent-config.ts
@@ -23,20 +23,29 @@ export function resolveEffectiveAgentRuntimeFromConfig(
config: DynamicSubagentAgentConfig | undefined,
): EffectiveAgentRuntime {
if (config === undefined) {
+ if (bundle.turnAgent.configResolver === true) {
+ throw new Error("Dynamic subagent execution requires a selected concrete agent config.");
+ }
return {
- limits: bundle.resolvedAgent.config.limits,
- thresholdPercent: bundle.resolvedAgent.config.compaction?.thresholdPercent,
+ limits: bundle.resolvedAgent.config?.limits,
+ thresholdPercent: bundle.resolvedAgent.config?.compaction?.thresholdPercent,
turnAgent: bundle.turnAgent,
};
}
+ const {
+ compactionModel: _compiledCompactionModel,
+ configResolver: _configResolver,
+ dynamicModel: _dynamicModel,
+ model: _compiledModel,
+ ...turnAgent
+ } = bundle.turnAgent;
return {
limits: config.limits,
thresholdPercent: config.compaction?.thresholdPercent,
turnAgent: {
- ...bundle.turnAgent,
+ ...turnAgent,
compactionModel: config.compaction?.model,
- dynamicModel: undefined,
model: config.model,
outputSchema: config.outputSchema,
reasoning: config.reasoning,
diff --git a/packages/eve/src/execution/node-step.test.ts b/packages/eve/src/execution/node-step.test.ts
index b7471fbc8..069741ad8 100644
--- a/packages/eve/src/execution/node-step.test.ts
+++ b/packages/eve/src/execution/node-step.test.ts
@@ -177,7 +177,9 @@ function createEmptyToolRegistry(): RuntimeToolRegistry {
};
}
-function createTestTurnAgent(overrides?: Partial<RuntimeTurnAgent>): RuntimeTurnAgent {
+type StaticRuntimeTurnAgent = Extract<RuntimeTurnAgent, { readonly model: unknown }>;
+
+function createTestTurnAgent(overrides?: Partial<StaticRuntimeTurnAgent>): RuntimeTurnAgent {
return {
id: "test-agent",
instructions: ["You are a test agent."],
diff --git a/packages/eve/src/execution/node-step.ts b/packages/eve/src/execution/node-step.ts
index 5d23e429b..78346a351 100644
--- a/packages/eve/src/execution/node-step.ts
+++ b/packages/eve/src/execution/node-step.ts
@@ -135,10 +135,6 @@ export function buildRuntimeIdentity(node: ResolvedRuntimeAgentNode): RuntimeIde
agentId: node.turnAgent.id,
agentName: node.agent.config?.name,
eveVersion: packageInfo.version,
- modelId:
- node.turnAgent.dynamicModel === undefined
- ? node.turnAgent.model.id
- : `dynamic:${node.turnAgent.model.id}`,
};
const gitSha = process.env.VERCEL_GIT_COMMIT_SHA?.trim();
@@ -174,7 +170,6 @@ function createRuntimeDynamicModelEventDispatcher(
ctx: input.ctx,
dynamicModel,
event: input.event,
- fallback: input.fallback,
messages: input.messages,
scope,
});
diff --git a/packages/eve/src/execution/session.test.ts b/packages/eve/src/execution/session.test.ts
index 2a3c77403..f48e05310 100644
--- a/packages/eve/src/execution/session.test.ts
+++ b/packages/eve/src/execution/session.test.ts
@@ -11,7 +11,9 @@ import {
refreshSessionFromTurnAgent,
} from "#execution/session.js";
-function createTestTurnAgent(overrides?: Partial<RuntimeTurnAgent>): RuntimeTurnAgent {
+type StaticRuntimeTurnAgent = Extract<RuntimeTurnAgent, { readonly model: unknown }>;
+
+function createTestTurnAgent(overrides?: Partial<StaticRuntimeTurnAgent>): RuntimeTurnAgent {
return {
id: "test-agent",
instructions: ["You are a helpful assistant.", "Be concise."],
@@ -46,6 +48,7 @@ describe("createCompactionConfig", () => {
).toEqual({
recentWindowSize: 10,
threshold: 180_000,
+ thresholdPercent: 0.9,
});
});
@@ -58,6 +61,7 @@ describe("createCompactionConfig", () => {
).toEqual({
recentWindowSize: 10,
threshold: 100_000,
+ thresholdPercent: 0.5,
});
});
@@ -65,6 +69,7 @@ describe("createCompactionConfig", () => {
expect(createCompactionConfig()).toEqual({
recentWindowSize: 10,
threshold: 100_000,
+ thresholdPercent: 0.9,
});
});
});
@@ -158,6 +163,7 @@ describe("createSession", () => {
expect(session.compaction).toEqual({
recentWindowSize: 10,
threshold: 100_000,
+ thresholdPercent: 0.9,
});
});
@@ -174,6 +180,7 @@ describe("createSession", () => {
expect(session.compaction).toEqual({
recentWindowSize: 10,
threshold: 100_000,
+ thresholdPercent: 0.5,
});
});
@@ -466,6 +473,7 @@ describe("refreshSessionFromTurnAgent", () => {
lastKnownPromptMessageCount: 7,
recentWindowSize: 10,
threshold: 100_000,
+ thresholdPercent: 0.5,
});
});
diff --git a/packages/eve/src/execution/session.ts b/packages/eve/src/execution/session.ts
index 0f49fce71..6f5315388 100644
--- a/packages/eve/src/execution/session.ts
+++ b/packages/eve/src/execution/session.ts
@@ -1,6 +1,11 @@
import type { DurableSession } from "#execution/durable-session-store.js";
import { formatAvailableSkillsSection } from "#execution/skills/instructions.js";
-import type { HarnessSession, SessionLimits, SessionToolDefinition } from "#harness/types.js";
+import type {
+ HarnessSession,
+ SessionAgent,
+ SessionLimits,
+ SessionToolDefinition,
+} from "#harness/types.js";
import type { RuntimeTurnAgent } from "#runtime/agent/bootstrap.js";
const DEFAULT_COMPACTION_RECENT_WINDOW_SIZE = 10;
@@ -38,6 +43,7 @@ export function createCompactionConfig(
const config = {
recentWindowSize: DEFAULT_COMPACTION_RECENT_WINDOW_SIZE,
threshold,
+ thresholdPercent,
};
if (input.lastKnownInputTokens !== undefined) {
@@ -78,17 +84,9 @@ export function createSession(input: CreateSessionInput): HarnessSession {
const session: {
-readonly [K in keyof HarnessSession]: HarnessSession[K];
} = {
- agent: {
- compactionModelReference: turnAgent.compactionModel,
- dynamicModelDefaultReference:
- turnAgent.dynamicModel === undefined ? undefined : turnAgent.model,
- modelReference: turnAgent.model,
- reasoning: turnAgent.reasoning,
- system: createSessionSystemPrompt({ turnAgent }),
- tools,
- },
+ agent: createSessionAgent(turnAgent, createSessionSystemPrompt({ turnAgent }), tools),
compaction: createCompactionConfig({
- contextWindowTokens: turnAgent.model.contextWindowTokens,
+ contextWindowTokens: turnAgent.model?.contextWindowTokens,
thresholdPercent: input.compactionOverrides?.thresholdPercent,
}),
continuationToken: input.continuationToken,
@@ -113,6 +111,27 @@ export function createSession(input: CreateSessionInput): HarnessSession {
return session;
}
+function createSessionAgent(
+ turnAgent: RuntimeTurnAgent,
+ system: string,
+ tools: readonly SessionToolDefinition[],
+): SessionAgent {
+ const base = {
+ compactionModelReference: turnAgent.compactionModel,
+ reasoning: turnAgent.reasoning,
+ system,
+ tools,
+ };
+
+ if (turnAgent.model !== undefined) {
+ return { ...base, modelReference: turnAgent.model };
+ }
+ if (turnAgent.dynamicModel !== undefined) {
+ return { ...base, dynamicModel: true };
+ }
+ throw new Error("Cannot create a session before dynamic subagent config is selected.");
+}
+
/**
* Refreshes a session with the latest `turnAgent` — replaces the system
* prompt, model/tool metadata, and compaction thresholds while preserving
@@ -127,17 +146,13 @@ export function refreshSessionFromTurnAgent(input: {
}): HarnessSession {
return {
...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({ turnAgent: input.turnAgent }),
- tools: createSessionToolDefinitions(input.turnAgent),
- },
+ agent: createSessionAgent(
+ input.turnAgent,
+ createSessionSystemPrompt({ turnAgent: input.turnAgent }),
+ createSessionToolDefinitions(input.turnAgent),
+ ),
compaction: createCompactionConfig({
- contextWindowTokens: input.turnAgent.model.contextWindowTokens,
+ contextWindowTokens: input.turnAgent.model?.contextWindowTokens,
lastKnownInputTokens: input.session.compaction.lastKnownInputTokens,
lastKnownPromptMessageCount: input.session.compaction.lastKnownPromptMessageCount,
thresholdPercent: input.compactionOverrides?.thresholdPercent,
@@ -245,17 +260,9 @@ export function hydrateDurableSession(input: {
const session: {
-readonly [K in keyof HarnessSession]: HarnessSession[K];
} = {
- agent: {
- compactionModelReference: turnAgent.compactionModel,
- dynamicModelDefaultReference:
- turnAgent.dynamicModel === undefined ? undefined : turnAgent.model,
- modelReference: turnAgent.model,
- reasoning: turnAgent.reasoning,
- system: durable.agent.system,
- tools,
- },
+ agent: createSessionAgent(turnAgent, durable.agent.system, tools),
compaction: createCompactionConfig({
- contextWindowTokens: turnAgent.model.contextWindowTokens,
+ contextWindowTokens: turnAgent.model?.contextWindowTokens,
lastKnownInputTokens: durable.compaction?.lastKnownInputTokens,
lastKnownPromptMessageCount: durable.compaction?.lastKnownPromptMessageCount,
thresholdPercent: input.compactionOverrides?.thresholdPercent,
diff --git a/packages/eve/src/execution/settle-cancelled-turn-step.ts b/packages/eve/src/execution/settle-cancelled-turn-step.ts
index 10eaddd36..f5efab0b0 100644
--- a/packages/eve/src/execution/settle-cancelled-turn-step.ts
+++ b/packages/eve/src/execution/settle-cancelled-turn-step.ts
@@ -102,7 +102,7 @@ export async function settleCancelledTurnStep(input: {
};
const emit =
createInstrumentationHandleEvent({
- agentName: bundle.resolvedAgent.config.name,
+ agentName: bundle.turnAgent.id,
handleEvent: baseEmit,
hooks: instrumentation?.hooks,
sessionId: session.sessionId,
diff --git a/packages/eve/src/execution/workflow-runtime.test.ts b/packages/eve/src/execution/workflow-runtime.test.ts
index 9cc9d70bc..cd2151048 100644
--- a/packages/eve/src/execution/workflow-runtime.test.ts
+++ b/packages/eve/src/execution/workflow-runtime.test.ts
@@ -275,6 +275,16 @@ describe("createWorkflowRuntime#resolveContinuation", () => {
describe("createWorkflowRuntime#createSession", () => {
const adapter: ChannelAdapter = { kind: "http" };
+ function createTestTurnAgent() {
+ return {
+ id: "test-agent",
+ instructions: [],
+ model: { id: "openai/gpt-5.5" },
+ tools: [],
+ workspaceSpec: { rootEntries: [] },
+ } as const;
+ }
+
function buildRuntime(compiledArtifactsSource: RuntimeCompiledArtifactsSource) {
return createWorkflowRuntime({ compiledArtifactsSource });
}
@@ -290,6 +300,7 @@ describe("createWorkflowRuntime#createSession", () => {
limits: sessionTimeoutMs === undefined ? undefined : { sessionTimeoutMs },
},
},
+ turnAgent: createTestTurnAgent(),
} as never);
getHookByTokenMock.mockResolvedValue({ runId: "driver-run" });
getRunMock.mockReturnValue({
@@ -453,6 +464,7 @@ describe("createWorkflowRuntime#createSession", () => {
compiledArtifactsSource,
nodeId: "researcher",
resolvedAgent: { config: {} },
+ turnAgent: createTestTurnAgent(),
} as never);
startMock.mockResolvedValue({ runId: "subagent-run" });
getHookByTokenMock.mockResolvedValue({ runId: "subagent-run" });
@@ -562,6 +574,7 @@ describe("createWorkflowRuntime#createSession", () => {
vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue({
compiledArtifactsSource,
resolvedAgent: { config: {} },
+ turnAgent: createTestTurnAgent(),
} as never);
const bytes = new TextEncoder().encode('{"type":"test.event"}\n');
const getReadable = vi.fn(
diff --git a/packages/eve/src/execution/workflow-steps.ts b/packages/eve/src/execution/workflow-steps.ts
index 4916c31bc..bbcc2913e 100644
--- a/packages/eve/src/execution/workflow-steps.ts
+++ b/packages/eve/src/execution/workflow-steps.ts
@@ -273,7 +273,7 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
const dynamicSkillResolvers = bundle.resolvedAgent.dynamicSkillResolvers ?? [];
const dynamicSubagentResolvers = bundle.subagentRegistry.dynamicResolvers ?? [];
const persistentSubagentSessions =
- bundle.resolvedAgent.config.experimental?.subagentPersistentSessions === true;
+ bundle.resolvedAgent.config?.experimental?.subagentPersistentSessions === true;
const dynamicToolResolvers = bundle.resolvedAgent.dynamicToolResolvers ?? [];
const effectiveNode = {
...bundle.graph.root,
@@ -332,7 +332,6 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
ctx,
dynamicModel: effectiveAgent.turnAgent.dynamicModel,
event: emitted,
- fallback: effectiveAgent.turnAgent.model,
messages: messages ?? [],
scope: {
moduleMap: bundle.moduleMap,
diff --git a/packages/eve/src/harness/emission.ts b/packages/eve/src/harness/emission.ts
index c7b730d7f..104d3e0ed 100644
--- a/packages/eve/src/harness/emission.ts
+++ b/packages/eve/src/harness/emission.ts
@@ -109,10 +109,12 @@ export async function emitTurnPreamble(
export async function emitStepStarted(
emitFn: HarnessEmitFn,
state: HarnessEmissionState,
+ modelId: string,
messages?: readonly import("ai").ModelMessage[],
): Promise<void> {
await emitFn(
createStepStartedEvent({
+ modelId,
sequence: state.sequence,
stepIndex: state.stepIndex,
turnId: state.turnId,
diff --git a/packages/eve/src/harness/instrumentation-native-events.test.ts b/packages/eve/src/harness/instrumentation-native-events.test.ts
index 2d3bc62bc..629e8a9ee 100644
--- a/packages/eve/src/harness/instrumentation-native-events.test.ts
+++ b/packages/eve/src/harness/instrumentation-native-events.test.ts
@@ -32,7 +32,14 @@ describe("createInstrumentationHandleEvent", () => {
await handleEvent(createSessionStartedEvent());
await handleEvent(createTurnStartedEvent({ sequence: 0, turnId: "turn-1" }));
- await handleEvent(createStepStartedEvent({ sequence: 0, stepIndex: 0, turnId: "turn-1" }));
+ await handleEvent(
+ createStepStartedEvent({
+ modelId: "openai/gpt-5.5",
+ sequence: 0,
+ stepIndex: 0,
+ turnId: "turn-1",
+ }),
+ );
await handleEvent(
createStepCompletedEvent({
finishReason: "stop",
diff --git a/packages/eve/src/harness/step-hooks.ts b/packages/eve/src/harness/step-hooks.ts
index cacbb5b56..b01ee87e9 100644
--- a/packages/eve/src/harness/step-hooks.ts
+++ b/packages/eve/src/harness/step-hooks.ts
@@ -33,7 +33,12 @@ import {
import { createRuntimeActionRequestFromToolCall } from "#harness/runtime-actions.js";
import { isInvalidToolCall } from "#harness/tool-call-input-errors.js";
import type { RuntimeToolResultActionResult } from "#runtime/actions/types.js";
-import type { HarnessEmitFn, HarnessSession, ToolLoopHarnessConfig } from "#harness/types.js";
+import {
+ type HarnessEmitFn,
+ type HarnessSession,
+ requireSessionModelReference,
+ type ToolLoopHarnessConfig,
+} from "#harness/types.js";
import { contextStorage } from "#context/container.js";
import { isAuthorizationSignal, isPendingAuthorizationToolOutput } from "#harness/authorization.js";
import { readToolInterrupt } from "#harness/tool-interrupts.js";
@@ -158,7 +163,12 @@ export function buildStepHooks(input: StepHooksInput): StepHooks {
let processed = messages;
if (emit && input.emitStepStarted !== false) {
- await emitStepStarted(emit, input.emissionState, messages);
+ await emitStepStarted(
+ emit,
+ input.emissionState,
+ requireSessionModelReference(session).id,
+ messages,
+ );
}
if (input.cachePath.kind === "anthropic-direct" && input.marker) {
@@ -169,10 +179,15 @@ export function buildStepHooks(input: StepHooksInput): StepHooks {
messages: processed,
};
+ const providerOptions = requireSessionModelReference(session).providerOptions;
if (input.cachePath.kind === "gateway-auto") {
- stepResult.providerOptions = mergeGatewayAutoCaching(
- session.agent.modelReference.providerOptions,
- ) as NonNullable<typeof stepResult.providerOptions>;
+ stepResult.providerOptions = mergeGatewayAutoCaching(providerOptions) as NonNullable<
+ typeof stepResult.providerOptions
+ >;
+ } else if (providerOptions !== undefined) {
+ stepResult.providerOptions = providerOptions as NonNullable<
+ typeof stepResult.providerOptions
+ >;
}
return stepResult;
diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.ts
index 415925923..d9b7b8441 100644
--- a/packages/eve/src/harness/tool-loop.test.ts
+++ b/packages/eve/src/harness/tool-loop.test.ts
@@ -11,6 +11,7 @@ import { MockLanguageModelV3 } from "ai/test";
import { afterEach, describe, expect, it, vi } from "vitest";
import { ContextContainer, contextStorage } from "#context/container.js";
+import { DynamicModelSelectionError } from "#context/dynamic-model-lifecycle.js";
import {
AuthKey,
ChannelInstrumentationKey,
@@ -909,20 +910,23 @@ describe("createToolLoopHarness", () => {
toolResults: [],
});
+ const selectedModel = new MockLanguageModelV3({
+ modelId: "gpt-5",
+ provider: "openai.chat",
+ });
const resolveModel = vi.fn().mockResolvedValue("fallback-model" as LanguageModel);
const dispatchDynamicModelEvent: NonNullable<
ToolLoopHarnessConfig["dispatchDynamicModelEvent"]
- > = vi.fn(async ({ ctx, event, fallback, messages }) => {
+ > = vi.fn(async ({ ctx, event, 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,
+ model: selectedModel,
reference: {
contextWindowTokens: 200_000,
- id: "selected-model",
- providerOptions: { gateway: { order: ["openai"] } },
+ id: "openai/gpt-5",
+ providerOptions: { openai: { parallelToolCalls: false } },
},
});
});
@@ -934,8 +938,7 @@ describe("createToolLoopHarness", () => {
const ctx = new ContextContainer();
const session = createTestSession({
agent: {
- dynamicModelDefaultReference: { contextWindowTokens: 100_000, id: "fallback-model" },
- modelReference: { contextWindowTokens: 100_000, id: "fallback-model" },
+ dynamicModel: true,
system: "You are a test assistant.",
tools: [{ description: "Adds numbers", name: "add", inputSchema: { type: "object" } }],
},
@@ -946,13 +949,24 @@ describe("createToolLoopHarness", () => {
const agentCall = vi.mocked(ToolLoopAgent).mock.calls[0]?.[0];
expect(agentCall).toBeDefined();
- expect(agentCall!.model).toBe("selected-model");
+ expect(agentCall!.model).toBe(selectedModel);
+ const prepareStep = getPrepareStep<unknown[], { providerOptions?: unknown }>(
+ agentCall!.prepareStep,
+ );
+ const prepared = await prepareStep({
+ context: undefined,
+ messages: [],
+ model: null,
+ stepNumber: 0,
+ steps: [],
+ });
+ expect(prepared.providerOptions).toEqual({ openai: { parallelToolCalls: false } });
expect(dispatchDynamicModelEvent).toHaveBeenCalledTimes(1);
expect(resolveModel).not.toHaveBeenCalled();
expect(result.session.agent.modelReference).toEqual({
contextWindowTokens: 200_000,
- id: "selected-model",
- providerOptions: { gateway: { order: ["openai"] } },
+ id: "openai/gpt-5",
+ providerOptions: { openai: { parallelToolCalls: false } },
});
expect(result.session.compaction.threshold).toBe(180_000);
});
@@ -986,8 +1000,7 @@ describe("createToolLoopHarness", () => {
});
const session = createTestSession({
agent: {
- dynamicModelDefaultReference: { contextWindowTokens: 100_000, id: "fallback-model" },
- modelReference: { contextWindowTokens: 100_000, id: "fallback-model" },
+ dynamicModel: true,
system: "You are a test assistant.",
tools: [{ description: "Adds numbers", name: "add", inputSchema: { type: "object" } }],
},
@@ -1007,7 +1020,7 @@ describe("createToolLoopHarness", () => {
expect(result.session.compaction.threshold).toBe(180_000);
});
- it("keeps the compaction threshold stable across steps with the same dynamic selection", async () => {
+ it("keeps the compaction threshold stable and fails when no dynamic selection remains", async () => {
setupMockAgent({
finishReason: "stop",
response: { messages: [{ content: "Hello!", role: "assistant" }] },
@@ -1027,8 +1040,7 @@ describe("createToolLoopHarness", () => {
});
const session = createTestSession({
agent: {
- dynamicModelDefaultReference: { contextWindowTokens: 100_000, id: "fallback-model" },
- modelReference: { contextWindowTokens: 100_000, id: "fallback-model" },
+ dynamicModel: true,
system: "You are a test assistant.",
tools: [{ description: "Adds numbers", name: "add", inputSchema: { type: "object" } }],
},
@@ -1045,12 +1057,63 @@ describe("createToolLoopHarness", () => {
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",
+ await expect(
+ contextStorage.run(ctx, () => runStep(second.session, { message: "Back" })),
+ ).rejects.toThrow(/Dynamic model selection is required/);
+ });
+
+ it("emits a terminal failure when no dynamic model selection is active", async () => {
+ const { emit, events } = createEventCollector();
+ const runStep = createToolLoopHarness(createTestConfig("conversation", emit));
+ const session = createTestSession({
+ agent: {
+ dynamicModel: true,
+ system: "You are a test assistant.",
+ tools: [],
+ },
});
- expect(third.session.compaction.threshold).toBe(90_000);
+
+ const result = await contextStorage.run(new ContextContainer(), () =>
+ runStep(session, { message: "Hi" }),
+ );
+
+ expect(result.next).toEqual({ done: true, output: "" });
+ expect(events.map((event) => event.type)).toEqual([
+ "session.started",
+ "turn.started",
+ "message.received",
+ "step.failed",
+ "turn.failed",
+ "session.failed",
+ ]);
+ const turnFailed = events.find((event) => event.type === "turn.failed");
+ expect(turnFailed?.data.message).toContain("Dynamic model selection is required");
+ expect(ToolLoopAgent).not.toHaveBeenCalled();
+ });
+
+ it("emits a terminal failure when a turn-scoped dynamic model resolver throws", async () => {
+ const events: UnstampedMessageStreamEvent[] = [];
+ const emit: HarnessEmitFn = async (event) => {
+ events.push(event);
+ if (event.type === "turn.started") {
+ throw new DynamicModelSelectionError(new Error("flag service unavailable"));
+ }
+ };
+ const runStep = createToolLoopHarness(createTestConfig("conversation", emit));
+
+ const result = await runStep(createTestSession(), { message: "Hi" });
+
+ expect(result.next).toEqual({ done: true, output: "" });
+ expect(events.map((event) => event.type)).toEqual([
+ "session.started",
+ "turn.started",
+ "step.failed",
+ "turn.failed",
+ "session.failed",
+ ]);
+ const turnFailed = events.find((event) => event.type === "turn.failed");
+ expect(turnFailed?.data.message).toBe("flag service unavailable");
+ expect(ToolLoopAgent).not.toHaveBeenCalled();
});
it("keeps declared subagent tools visible in deeply nested sessions", async () => {
@@ -8003,9 +8066,9 @@ describe("createToolLoopHarness", () => {
"session.started",
"turn.started",
"message.received",
+ "step.started",
"compaction.requested",
"compaction.completed",
- "step.started",
"message.completed",
"step.completed",
"turn.completed",
@@ -9163,7 +9226,6 @@ describe("createToolLoopHarness", () => {
agentId: "weather-agent",
agentName: "Weather Agent",
eveVersion: "0.0.0",
- modelId: "anthropic/claude-sonnet-4-5",
},
tools: new Map(),
};
@@ -9198,7 +9260,6 @@ describe("createToolLoopHarness", () => {
runtimeIdentity: {
agentId: "weather-agent",
eveVersion: "0.0.0",
- modelId: "anthropic/claude-sonnet-4-5",
},
tools: new Map(),
};
@@ -9234,7 +9295,6 @@ describe("createToolLoopHarness", () => {
agentId: "my-agent",
agentName: "My Agent",
eveVersion: "0.0.0",
- modelId: "anthropic/claude-sonnet-4-5",
},
tools: new Map(),
};
@@ -9272,7 +9332,6 @@ describe("createToolLoopHarness", () => {
agentId: "my-agent",
agentName: "My Agent",
eveVersion: "0.0.0",
- modelId: "anthropic/claude-sonnet-4-5",
},
tools: new Map(),
};
@@ -9360,7 +9419,6 @@ describe("createToolLoopHarness", () => {
agentId: "weather-agent",
agentName: "Weather Agent",
eveVersion: "0.0.0",
- modelId: "anthropic/claude-sonnet-4-5",
},
tools: new Map(),
};
@@ -9724,7 +9782,7 @@ describe("createToolLoopHarness", () => {
Object.fromEntries(Object.keys(agentCall?.runtimeContext ?? {}).map((key) => [key, true])),
);
expect(order.indexOf("turn.started")).toBeLessThan(order.indexOf('events["step.started"]'));
- expect(order.indexOf('events["step.started"]')).toBeLessThan(order.indexOf("step.started"));
+ expect(order.indexOf("step.started")).toBeLessThan(order.indexOf('events["step.started"]'));
expect(getCompatibilityEventTypes(events)).toContain("step.started");
});
diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.ts
index 441cccf54..248dc9bab 100644
--- a/packages/eve/src/harness/tool-loop.ts
+++ b/packages/eve/src/harness/tool-loop.ts
@@ -37,7 +37,10 @@ import {
SessionCallbackKey,
} from "#context/keys.js";
import { buildDynamicInstructionMessages } from "#context/dynamic-instruction-lifecycle.js";
-import { getActiveDynamicModelSelection } from "#context/dynamic-model-lifecycle.js";
+import {
+ getActiveDynamicModelSelection,
+ isDynamicModelSelectionError,
+} from "#context/dynamic-model-lifecycle.js";
import { buildDynamicTools } from "#context/build-dynamic-tools.js";
import { buildDynamicSubagentTools } from "#context/dynamic-subagent-lifecycle.js";
import { PendingSkillAnnouncementKey } from "#context/dynamic-skill-lifecycle.js";
@@ -50,7 +53,7 @@ import {
createInputRequestedEvent,
createResultCompletedEvent,
createSessionWaitingEvent,
- createStepStartedEvent,
+ type UnstampedMessageStreamEvent,
} from "#protocol/message.js";
import type { InstrumentationDefinition } from "#public/instrumentation/index.js";
import { ASK_QUESTION_TOOL_NAME } from "#runtime/framework-tools/ask-question.js";
@@ -200,15 +203,16 @@ import {
} 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,
- HarnessSession,
- HarnessToolMap,
- SettledTurn,
- StepFn,
- StepInput,
- StepResult,
- ToolLoopHarnessConfig,
+import {
+ type CompactionConfig,
+ type HarnessSession,
+ type HarnessToolMap,
+ requireSessionModelReference,
+ type SettledTurn,
+ type StepFn,
+ type StepInput,
+ type StepResult,
+ type ToolLoopHarnessConfig,
} from "#harness/types.js";
/**
@@ -358,20 +362,28 @@ async function resolveActiveRuntimeModel(input: {
readonly session: HarnessSession;
}> {
if (input.ctx === undefined) {
+ const reference = input.session.agent.modelReference;
+ if (reference === undefined) {
+ throw new Error("Dynamic model selection is unavailable outside an eve runtime context.");
+ }
return {
- model: await input.config.resolveModel(input.session.agent.modelReference),
+ model: await input.config.resolveModel(reference),
session: input.session,
};
}
- const fallback =
- input.session.agent.dynamicModelDefaultReference ?? input.session.agent.modelReference;
const selected = getActiveDynamicModelSelection(input.ctx);
if (selected === null) {
+ const reference = input.session.agent.modelReference;
+ if (input.session.agent.dynamicModel === true || reference === undefined) {
+ throw new Error(
+ "Dynamic model selection is required before model-dependent work begins. Add a matching resolver handler that returns a concrete model.",
+ );
+ }
return {
- model: await input.config.resolveModel(fallback),
- session: updateSessionModelReference(input.session, fallback),
+ model: await input.config.resolveModel(reference),
+ session: input.session,
};
}
@@ -388,9 +400,6 @@ 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: {
@@ -400,7 +409,6 @@ function updateSessionModelReference(
compaction: updateCompactionThresholdForModelReference({
compaction: session.compaction,
modelReference,
- priorReference,
}),
};
}
@@ -408,19 +416,19 @@ function updateSessionModelReference(
function updateCompactionThresholdForModelReference(input: {
readonly compaction: CompactionConfig;
readonly modelReference: RuntimeModelReference;
- readonly priorReference: RuntimeModelReference;
}): CompactionConfig {
- if (
- input.modelReference.contextWindowTokens === undefined ||
- input.priorReference.contextWindowTokens === undefined
- ) {
+ if (input.modelReference.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)),
+ threshold: Math.max(
+ 1,
+ Math.floor(
+ input.modelReference.contextWindowTokens * (input.compaction.thresholdPercent ?? 0.9),
+ ),
+ ),
};
}
@@ -576,6 +584,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
let emissionState = getHarnessEmissionState(session.state);
const store = contextStorage.getStore();
const parent = store?.get(ParentSessionKey);
+ const hasDelegatedCaller = parent !== undefined || store?.get(SessionCallbackKey) !== undefined;
const emit = createInstrumentationHandleEvent({
agentName: config.runtimeIdentity?.agentName,
handleEvent: baseEmit,
@@ -586,6 +595,41 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
sessionId: session.sessionId,
turnId: activeTurnId(emissionState),
});
+ const failModelSelection = async (
+ error: unknown,
+ failureState: ReturnType<typeof getHarnessEmissionState>,
+ ): Promise<StepResult> => {
+ throwIfTurnAborted(config.abortSignal);
+ if (turnSpan) {
+ recordErrorOnSpan(turnSpan, error);
+ }
+ if (!emit) {
+ throw error;
+ }
+
+ const errorId = createErrorId();
+ const message = toErrorMessage(error);
+ log.error("model selection failed terminally", {
+ error,
+ errorId,
+ sessionId: session.sessionId,
+ turnId: failureState.turnId,
+ });
+ await emitFailedStep(emit, failureState, {
+ code: "MODEL_SELECTION_FAILED",
+ details: { errorId },
+ message,
+ sessionId: session.sessionId,
+ });
+
+ return {
+ next:
+ config.mode === "task" || hasDelegatedCaller
+ ? { done: true, isError: true, output: message }
+ : { done: true, output: "" },
+ session,
+ };
+ };
if (config.clearOnly === true) {
session = {
@@ -593,6 +637,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
compaction: {
recentWindowSize: session.compaction.recentWindowSize,
threshold: session.compaction.threshold,
+ thresholdPercent: session.compaction.thresholdPercent,
},
history: [],
};
@@ -636,6 +681,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
compaction: {
recentWindowSize: compacted.session.compaction.recentWindowSize,
threshold: compacted.session.compaction.threshold,
+ thresholdPercent: compacted.session.compaction.thresholdPercent,
},
history: compacted.messages,
};
@@ -692,12 +738,22 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
});
if (pending.outcome === "unresolved") {
if (emit && pending.deferredMessage === true && hasStepInput(input)) {
- emissionState = await emitTurnPreamble(
- emit,
- preambleStepInput ?? {},
- emissionState,
- config.runtimeIdentity,
- );
+ try {
+ emissionState = await emitTurnPreamble(
+ emit,
+ preambleStepInput ?? {},
+ emissionState,
+ config.runtimeIdentity,
+ );
+ } catch (error) {
+ if (!isDynamicModelSelectionError(error)) throw error;
+ return failModelSelection(error, {
+ sessionStarted: true,
+ sequence: emissionState.sequence,
+ stepIndex: 0,
+ turnId: `turn_${emissionState.sequence}`,
+ });
+ }
emissionState = await emitTurnEpilogue(emit, emissionState, config.mode);
return {
next: null,
@@ -729,12 +785,22 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
// --- Turn preamble ------------------------------------------------------
if (emit && hasStepInput(input)) {
- emissionState = await emitTurnPreamble(
- emit,
- preambleStepInput ?? {},
- emissionState,
- config.runtimeIdentity,
- );
+ try {
+ emissionState = await emitTurnPreamble(
+ emit,
+ preambleStepInput ?? {},
+ emissionState,
+ config.runtimeIdentity,
+ );
+ } catch (error) {
+ if (!isDynamicModelSelectionError(error)) throw error;
+ return failModelSelection(error, {
+ sessionStarted: true,
+ sequence: emissionState.sequence,
+ stepIndex: 0,
+ turnId: `turn_${emissionState.sequence}`,
+ });
+ }
session = setHarnessEmissionState(session, emissionState);
if (turnSpan) {
@@ -795,28 +861,42 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
// --- Model + tools ------------------------------------------------------
// Direct harness unit tests may run without an ambient context.
- const ctx = contextStorage.getStore();
- const hasDelegatedCaller =
- ctx?.get(ParentSessionKey) !== undefined || ctx?.get(SessionCallbackKey) !== undefined;
- if (ctx !== undefined && config.dispatchDynamicModelEvent !== undefined) {
- await config.dispatchDynamicModelEvent({
+ const ctx = store;
+ let resolvedModel: Awaited<ReturnType<typeof resolveActiveRuntimeModel>>;
+ try {
+ if (ctx !== undefined && config.dispatchDynamicModelEvent !== undefined) {
+ await config.dispatchDynamicModelEvent({
+ ctx,
+ event: {
+ data: {
+ sequence: emissionState.sequence,
+ stepIndex: emissionState.stepIndex,
+ turnId: emissionState.turnId,
+ },
+ type: "step.started",
+ } as UnstampedMessageStreamEvent,
+ messages,
+ });
+ }
+ resolvedModel = await resolveActiveRuntimeModel({
+ config,
ctx,
- event: createStepStartedEvent({
- sequence: emissionState.sequence,
- stepIndex: emissionState.stepIndex,
- turnId: emissionState.turnId,
- }),
- fallback: session.agent.dynamicModelDefaultReference ?? session.agent.modelReference,
- messages,
+ session,
});
+ } catch (error) {
+ return failModelSelection(error, emissionState);
}
- const resolvedModel = await resolveActiveRuntimeModel({
- config,
- ctx,
- session,
- });
session = resolvedModel.session;
const model = resolvedModel.model;
+
+ if (emit) {
+ await emitStepStarted(
+ emit,
+ emissionState,
+ requireSessionModelReference(session).id,
+ messages,
+ );
+ }
const cachePath = detectPromptCachePath(model);
const marker = cachePath.kind === "anthropic-direct" ? getAnthropicCacheMarker() : undefined;
@@ -968,7 +1048,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
approvedTools,
capabilities: config.capabilities,
disabledProviderTools: opts.disabledProviderTools,
- modelReference: session.agent.modelReference,
+ modelReference: requireSessionModelReference(session),
tools: advertisedHarnessTools,
webSearchProvider: config.webSearchProvider,
});
@@ -1203,16 +1283,10 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
config.abortSignal,
);
- // Resolve first-attempt instrumentation before step.started dispatch
- // allows dynamic tool resolvers to update the effective toolset.
+ // Resolve first-attempt instrumentation after step.started dynamic
+ // capabilities have updated the effective prompt and toolset.
const initialModelCallInput = prepareModelCallInput();
- // Emit step.started before building the toolset so dynamic tool
- // resolvers subscribed to step.started write to LiveStepToolsKey.
- if (emit) {
- await emitStepStarted(emit, emissionState, messages);
- }
-
// Workflow continuations replay the sandbox after step.started so nested
// action lifecycle events keep the active turn's emission coordinates.
const pendingWorkflowInterrupt = await continuePendingWorkflowInterrupt({
@@ -2602,9 +2676,11 @@ function createNextCompactionConfig(
lastKnownPromptMessageCount?: number;
recentWindowSize: number;
threshold: number;
+ thresholdPercent?: number;
} = {
recentWindowSize: current.recentWindowSize,
threshold: current.threshold,
+ thresholdPercent: current.thresholdPercent,
};
if (result.usage?.inputTokens !== undefined) {
@@ -2648,7 +2724,7 @@ async function maybeCompact(input: {
const compaction = await resolveCompactionModel({
compactionModelReference: session.agent.compactionModelReference,
model: input.model,
- modelReference: session.agent.modelReference,
+ modelReference: requireSessionModelReference(session),
resolveModel: input.resolveModel,
});
diff --git a/packages/eve/src/harness/types.ts b/packages/eve/src/harness/types.ts
index 570766f4f..27b0391a7 100644
--- a/packages/eve/src/harness/types.ts
+++ b/packages/eve/src/harness/types.ts
@@ -35,26 +35,36 @@ export interface CompactionConfig {
readonly lastKnownPromptMessageCount?: number;
readonly recentWindowSize: number;
readonly threshold: number;
+ readonly thresholdPercent?: number;
}
/**
* Serializable agent configuration stored on the session.
*/
-export interface SessionAgent {
+interface SessionAgentBase {
/**
* Optional model used only for compaction summaries.
*
* 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;
readonly tools: readonly SessionToolDefinition[];
}
+export type SessionAgent = SessionAgentBase &
+ (
+ | {
+ readonly dynamicModel?: never;
+ readonly modelReference: RuntimeModelReference;
+ }
+ | {
+ readonly dynamicModel: true;
+ readonly modelReference?: RuntimeModelReference;
+ }
+ );
+
/**
* Serializable session state passed between harness and runtime.
*
@@ -93,6 +103,14 @@ export interface HarnessSession {
readonly workflowMaxSubagents?: number;
}
+export function requireSessionModelReference(session: HarnessSession): RuntimeModelReference {
+ const reference = session.agent.modelReference;
+ if (reference === undefined) {
+ throw new Error("Expected a concrete model selection for the active model call.");
+ }
+ return reference;
+}
+
/**
* Token limits stored on one durable session.
*/
@@ -295,7 +313,6 @@ export interface ToolLoopHarnessConfig {
readonly dispatchDynamicModelEvent?: (input: {
readonly ctx: AlsContext;
readonly event: UnstampedMessageStreamEvent;
- readonly fallback: RuntimeModelReference;
readonly messages: readonly ModelMessage[];
}) => Promise<void>;
readonly resolveModel: (reference: RuntimeModelReference) => Promise<LanguageModel>;
diff --git a/packages/eve/src/internal/authored-definition/core.test.ts b/packages/eve/src/internal/authored-definition/core.test.ts
index cc22eb334..9caa2c5b6 100644
--- a/packages/eve/src/internal/authored-definition/core.test.ts
+++ b/packages/eve/src/internal/authored-definition/core.test.ts
@@ -23,7 +23,6 @@ describe("normalizeAgentDefinition", () => {
it("accepts dynamic model definitions", () => {
const model = defineDynamic({
- fallback: "openai/gpt-5.5",
events: {
"session.started": () => "openai/gpt-5.5-mini",
},
@@ -36,13 +35,27 @@ describe("normalizeAgentDefinition", () => {
);
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", () => {
+ it("rejects fallback-shaped dynamic models", () => {
+ expect(() =>
+ normalizeAgentDefinition(
+ {
+ model: {
+ events: { "session.started": () => "openai/gpt-5.5-mini" },
+ fallback: "openai/gpt-5.5",
+ kind: "eve:dynamic",
+ },
+ },
+ FAILURE_MESSAGE,
+ ),
+ ).toThrow('Unknown key "fallback"');
+ });
+
+ it("rejects definition-level model metadata for dynamic models", () => {
expect(() =>
normalizeAgentDefinition(
{
@@ -51,10 +64,11 @@ describe("normalizeAgentDefinition", () => {
"session.started": () => "openai/gpt-5.5-mini",
},
}),
+ modelContextWindowTokens: 128_000,
},
FAILURE_MESSAGE,
),
- ).toThrow('Dynamic model definitions must include a "fallback" model.');
+ ).toThrow(/Dynamic model.*modelContextWindowTokens/);
});
it("rejects a dynamic compaction model", () => {
@@ -63,7 +77,6 @@ describe("normalizeAgentDefinition", () => {
{
compaction: {
model: defineDynamic({
- fallback: "openai/gpt-5.5-mini",
events: {
"session.started": () => "openai/gpt-5.5-mini",
},
diff --git a/packages/eve/src/internal/authored-definition/core.ts b/packages/eve/src/internal/authored-definition/core.ts
index 348ed5a2a..93ce950ae 100644
--- a/packages/eve/src/internal/authored-definition/core.ts
+++ b/packages/eve/src/internal/authored-definition/core.ts
@@ -68,6 +68,15 @@ export function normalizeAgentDefinition(
model: normalizeAgentModelDefinition(record.model, message),
};
+ if (
+ isDynamicSentinel(definition.model) &&
+ (record.modelContextWindowTokens !== undefined || record.modelOptions !== undefined)
+ ) {
+ throw new Error(
+ `${message} Dynamic model definitions do not support sibling "modelContextWindowTokens" or "modelOptions" fields. Return those overrides from the resolver selection instead.`,
+ );
+ }
+
if (record.description !== undefined) {
definition.description = expectString(record.description, message);
}
@@ -134,18 +143,12 @@ 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.`);
- }
+ expectOnlyKnownKeys(record, ["events", "kind"], message);
const rawEvents = expectObjectRecord(record.events, message);
const events: MutableDynamicEvents = {};
@@ -157,7 +160,6 @@ function normalizeAgentModelDefinition(
return {
events,
- fallback: record.fallback as PublicAgentStaticModelDefinition,
kind: record.kind,
} as NormalizedAgentDefinition["model"];
}
diff --git a/packages/eve/src/internal/authored-definition/schema-backed.test.ts b/packages/eve/src/internal/authored-definition/schema-backed.test.ts
index 7cfc68903..2d816edbe 100644
--- a/packages/eve/src/internal/authored-definition/schema-backed.test.ts
+++ b/packages/eve/src/internal/authored-definition/schema-backed.test.ts
@@ -262,15 +262,17 @@ describe("normalizeToolDefinition", () => {
});
it("rejects a defineDynamic tool export carrying a fallback", () => {
- const dynamicTools = defineDynamic({
+ const dynamicTools = {
+ ...defineDynamic({
+ events: {
+ "session.started": async () => ({}),
+ },
+ }),
fallback: "not-supported-here",
- events: {
- "session.started": async () => ({}),
- },
- });
+ } as never;
expect(() => normalizeToolDefinition(dynamicTools, FAILURE_MESSAGE)).toThrow(
- '"fallback" is only supported on a dynamic agent model',
+ "Unknown key(s): fallback",
);
});
diff --git a/packages/eve/src/internal/authored-definition/schema-backed.ts b/packages/eve/src/internal/authored-definition/schema-backed.ts
index b6919a272..417d8feee 100644
--- a/packages/eve/src/internal/authored-definition/schema-backed.ts
+++ b/packages/eve/src/internal/authored-definition/schema-backed.ts
@@ -17,8 +17,8 @@ import {
type ToolSchemaSource,
} from "#shared/tool-schema.js";
import {
+ assertResolverOnlyDynamicSentinel,
isDynamicSentinel,
- rejectDynamicSentinelFallback,
type DynamicToolEventName,
} from "#shared/dynamic-tool-definition.js";
@@ -59,7 +59,7 @@ type NormalizedToolEntry =
*/
export function normalizeToolDefinition(value: unknown, message: string): NormalizedToolEntry {
if (isDynamicSentinel(value)) {
- rejectDynamicSentinelFallback(value, message);
+ assertResolverOnlyDynamicSentinel(value, message);
return {
kind: "dynamic-tool",
eventNames: Object.keys(value.events) as DynamicToolEventName[],
diff --git a/packages/eve/src/internal/authored-module-loader.scenario.test.ts b/packages/eve/src/internal/authored-module-loader.scenario.test.ts
index ad3993797..3727b35da 100644
--- a/packages/eve/src/internal/authored-module-loader.scenario.test.ts
+++ b/packages/eve/src/internal/authored-module-loader.scenario.test.ts
@@ -1119,12 +1119,14 @@ describe("loadAuthoredModuleNamespace", () => {
appRoot: app.appRoot,
});
const manifest = await compileAgentManifest(discovered.manifest);
+ const subagent = manifest.subagents[0];
+ if (subagent?.configResolver !== undefined) {
+ throw new Error("expected a static subagent");
+ }
expect(manifest.config.build?.externalDependencies).toEqual(["external-only"]);
- expect(manifest.subagents[0]?.agent.config.build?.externalDependencies).toEqual([
- "external-only",
- ]);
- expect(manifest.subagents[0]?.agent.tools).toHaveLength(1);
+ expect(subagent?.agent.config.build?.externalDependencies).toEqual(["external-only"]);
+ expect(subagent?.agent.tools).toHaveLength(1);
} finally {
await rm(workspaceRoot, { force: true, recursive: true });
}
diff --git a/packages/eve/src/internal/authored-module-loader.ts b/packages/eve/src/internal/authored-module-loader.ts
index e90b0fb7e..5242c227a 100644
--- a/packages/eve/src/internal/authored-module-loader.ts
+++ b/packages/eve/src/internal/authored-module-loader.ts
@@ -259,11 +259,14 @@ export async function bundleAuthoredModuleMapForGeneration(input: {
readonly moduleMapPath: string;
}): Promise<string> {
const packageRoot = resolveAuthoredPackageRoot(input.manifest.agentRoot);
- const externalDependencies = normalizeExternalDependencies(
- [input.manifest, ...input.manifest.subagents.map((subagent) => subagent.agent)].flatMap(
- (node) => node.config.build?.externalDependencies ?? [],
+ const externalDependencies = normalizeExternalDependencies([
+ ...(input.manifest.config.build?.externalDependencies ?? []),
+ ...input.manifest.subagents.flatMap((subagent) =>
+ subagent.configResolver === undefined
+ ? (subagent.agent.config.build?.externalDependencies ?? [])
+ : (subagent.configResolver.build?.externalDependencies ?? []),
),
- );
+ ]);
const moduleMapSource = createCompiledModuleMapSource({
manifest: input.manifest,
moduleMapPath: input.moduleMapPath,
diff --git a/packages/eve/src/internal/authored-module-map-loader.ts b/packages/eve/src/internal/authored-module-map-loader.ts
index ea34c156e..d2f8a4f0a 100644
--- a/packages/eve/src/internal/authored-module-map-loader.ts
+++ b/packages/eve/src/internal/authored-module-map-loader.ts
@@ -1,7 +1,12 @@
import { join } from "node:path";
import { pathToFileURL } from "node:url";
-import type { CompiledAgentManifest, CompiledAgentNodeManifest } from "#compiler/manifest.js";
+import type {
+ CompiledAgentManifest,
+ CompiledAgentNodeManifest,
+ CompiledAgentResources,
+} from "#compiler/manifest.js";
+import type { ModuleSourceRef } from "#shared/source-ref.js";
import { ROOT_COMPILED_AGENT_NODE_ID } from "#compiler/manifest.js";
import {
collectModuleRefsForManifest,
@@ -62,19 +67,27 @@ async function hydrateCompiledModuleMapFromManifest(
const nodes: CompiledModuleMap["nodes"] = {};
const nodeManifests: Array<{
+ additionalModuleRef?: ModuleSourceRef;
agentRoot: string;
- manifest: CompiledAgentNodeManifest;
+ externalDependencies: readonly string[];
+ manifest: CompiledAgentNodeManifest | CompiledAgentResources;
nodeId: string;
}> = [
{
agentRoot: manifest.agentRoot,
+ externalDependencies: manifest.config.build?.externalDependencies ?? [],
manifest,
nodeId: ROOT_COMPILED_AGENT_NODE_ID,
},
...[...manifest.subagents]
.sort((left, right) => left.nodeId.localeCompare(right.nodeId))
.map((subagent) => ({
+ additionalModuleRef: subagent.configResolver,
agentRoot: subagent.agent.agentRoot,
+ externalDependencies:
+ subagent.configResolver === undefined
+ ? (subagent.agent.config.build?.externalDependencies ?? [])
+ : (subagent.configResolver.build?.externalDependencies ?? []),
manifest: subagent.agent,
nodeId: subagent.nodeId,
})),
@@ -98,6 +111,8 @@ async function hydrateCompiledModuleMapFromManifest(
nodes[nodeManifest.nodeId] = {
modules: await hydrateCompiledNodeScope({
agentRoot: nodeManifest.agentRoot,
+ additionalModuleRef: nodeManifest.additionalModuleRef,
+ externalDependencies: nodeManifest.externalDependencies,
manifest: nodeManifest.manifest,
scopeIndex,
}),
@@ -143,14 +158,16 @@ function extensionNamespaceForSourceId(
}
async function hydrateCompiledNodeScope(input: {
+ additionalModuleRef?: ModuleSourceRef;
agentRoot: string;
- manifest: CompiledAgentNodeManifest;
+ externalDependencies: readonly string[];
+ manifest: CompiledAgentNodeManifest | CompiledAgentResources;
scopeIndex: ExtensionScopeIndex;
}): Promise<CompiledModuleMap["nodes"][string]["modules"]> {
- const refs = collectModuleRefsForManifest(input.manifest).sort((left, right) =>
- left.sourceId.localeCompare(right.sourceId),
- );
- const externalDependencies = input.manifest.config.build?.externalDependencies ?? [];
+ const refs = [
+ ...collectModuleRefsForManifest(input.manifest),
+ ...(input.additionalModuleRef === undefined ? [] : [input.additionalModuleRef]),
+ ].sort((left, right) => left.sourceId.localeCompare(right.sourceId));
const container = globalThis as Record<symbol, unknown>;
const modules: CompiledModuleMap["nodes"][string]["modules"] = {};
@@ -169,7 +186,7 @@ async function hydrateCompiledNodeScope(input: {
}
try {
modules[ref.sourceId] = await loadAuthoredModuleNamespace(modulePath, {
- externalDependencies,
+ externalDependencies: input.externalDependencies,
extensionScopeNamespace,
});
} finally {
diff --git a/packages/eve/src/internal/model-catalog.ts b/packages/eve/src/internal/model-catalog.ts
new file mode 100644
index 000000000..dd18bb12a
--- /dev/null
+++ b/packages/eve/src/internal/model-catalog.ts
@@ -0,0 +1,82 @@
+import { z } from "#compiled/zod/index.js";
+
+const THINKING_SUFFIX = "-thinking";
+
+export const catalogModelProviderSchema = z
+ .object({
+ provider: z.string().min(1),
+ providerModelId: z.string().min(1),
+ contextWindowTokens: z.number().int().nonnegative().optional(),
+ maxOutputTokens: z.number().int().nonnegative().optional(),
+ })
+ .passthrough();
+
+export const catalogModelSchema = z
+ .object({
+ slug: z.string().min(1),
+ providers: z.array(catalogModelProviderSchema).min(1),
+ })
+ .passthrough();
+
+export const modelCatalogResponseSchema = z
+ .object({
+ models: z.array(catalogModelSchema),
+ providerAliases: z.record(z.string(), z.string()),
+ })
+ .passthrough();
+
+export type CatalogModelProvider = z.infer<typeof catalogModelProviderSchema>;
+export type CatalogModel = z.infer<typeof catalogModelSchema>;
+
+export interface ModelCatalogLimits {
+ readonly contextWindowTokens: number;
+ readonly maxOutputTokens?: number;
+}
+
+export function normalizeCatalogModelId(modelId: string): string {
+ return modelId.endsWith(THINKING_SUFFIX) ? modelId.slice(0, -THINKING_SUFFIX.length) : modelId;
+}
+
+export function findCatalogModelBySlug(
+ models: readonly CatalogModel[],
+ slug: string,
+): CatalogModel | undefined {
+ return models.find((model) => model.slug === normalizeCatalogModelId(slug));
+}
+
+export function findCatalogModelByProviderModelId(input: {
+ readonly models: readonly CatalogModel[];
+ readonly provider: string;
+ readonly providerAliases: Readonly<Record<string, string>>;
+ readonly providerModelId: string;
+}): { readonly model: CatalogModel; readonly provider: CatalogModelProvider } | null {
+ const baseProvider = input.provider.split(".")[0]!;
+ const resolvedProvider = input.providerAliases[baseProvider] ?? baseProvider;
+ const normalizedModelId = normalizeCatalogModelId(input.providerModelId);
+
+ for (const model of input.models) {
+ for (const provider of model.providers) {
+ if (
+ provider.provider === resolvedProvider &&
+ normalizeCatalogModelId(provider.providerModelId) === normalizedModelId
+ ) {
+ return { model, provider };
+ }
+ }
+ }
+
+ return null;
+}
+
+export function modelCatalogLimitsFromProvider(
+ provider: CatalogModelProvider,
+): ModelCatalogLimits | null {
+ if (provider.contextWindowTokens === undefined || provider.contextWindowTokens <= 0) {
+ return null;
+ }
+ return {
+ contextWindowTokens: provider.contextWindowTokens,
+ ...(provider.maxOutputTokens !== undefined &&
+ provider.maxOutputTokens > 0 && { maxOutputTokens: provider.maxOutputTokens }),
+ };
+}
diff --git a/packages/eve/src/internal/nitro/dev-generation-artifacts.scenario.test.ts b/packages/eve/src/internal/nitro/dev-generation-artifacts.scenario.test.ts
index 893c4e438..8887d0de8 100644
--- a/packages/eve/src/internal/nitro/dev-generation-artifacts.scenario.test.ts
+++ b/packages/eve/src/internal/nitro/dev-generation-artifacts.scenario.test.ts
@@ -118,7 +118,7 @@ describe("development generation artifacts", () => {
),
});
const subagent = compileResult.manifest.subagents[0];
- const sourceId = subagent?.agent.config.source?.sourceId;
+ const sourceId = subagent?.sourceId;
expect(sourceId).toBeDefined();
const moduleNamespace = moduleMap.nodes[subagent!.nodeId]?.modules[sourceId!] as {
default: { events: Record<string, Function> };
@@ -141,6 +141,41 @@ describe("development generation artifacts", () => {
expect(credentials.headers()).toEqual({ authorization: "Bearer fresh" });
});
+ it("hydrates a dynamic directory subagent resolver relative to the child root", async () => {
+ const app = await scenarioApp({
+ files: {
+ "agent/agent.mjs": 'export default { model: "openai/gpt-5.4" };\n',
+ "agent/instructions.md": "Use the available subagent.",
+ "agent/subagents/conditional/agent.mjs": [
+ 'const defineDynamic = (definition) => ({ ...definition, kind: "eve:dynamic" });',
+ "export default defineDynamic({",
+ " events: {",
+ ' "session.started": () => ({',
+ ' description: "Conditionally available.",',
+ ' model: "openai/gpt-5.4",',
+ " }),",
+ " },",
+ "});",
+ "",
+ ].join("\n"),
+ },
+ name: "dynamic-directory-subagent-source-map",
+ });
+
+ const compileResult = await compileAgent({ startPath: app.appRoot });
+ const moduleMap = await loadCompiledModuleMapFromAuthoredSource({
+ compiledArtifactsSource: createAuthoredSourceRuntimeCompiledArtifactsSource(app.appRoot),
+ });
+ const subagent = compileResult.manifest.subagents[0];
+ if (subagent?.configResolver === undefined) throw new Error("expected a dynamic subagent");
+
+ const moduleNamespace = moduleMap.nodes[subagent.nodeId]?.modules[
+ subagent.configResolver.sourceId
+ ] as { default: { events: Record<string, Function> } };
+
+ expect(moduleNamespace.default.events["session.started"]).toBeDefined();
+ });
+
it("preserves extension scope in a shared generation graph", async () => {
const packageName = "@acme/shared-graph-extension";
const app = await scenarioApp({
diff --git a/packages/eve/src/internal/nitro/host/build-vercel-agent-summary.ts b/packages/eve/src/internal/nitro/host/build-vercel-agent-summary.ts
index 15eb93f98..4643a4ec4 100644
--- a/packages/eve/src/internal/nitro/host/build-vercel-agent-summary.ts
+++ b/packages/eve/src/internal/nitro/host/build-vercel-agent-summary.ts
@@ -43,11 +43,18 @@ export function buildVercelAgentSummary(input: {
kind: VERCEL_EVE_AGENT_SUMMARY_KIND,
schemaVersion: VERCEL_EVE_AGENT_SUMMARY_VERSION,
generatorVersion: input.generatorVersion ?? resolveInstalledPackageInfo().version,
- agent: {
- name: manifest.config.name,
- description: manifest.config.description,
- modelId: manifest.config.model.id,
- },
+ agent:
+ manifest.config.dynamicModel === undefined
+ ? {
+ name: manifest.config.name,
+ description: manifest.config.description,
+ modelId: manifest.config.model.id,
+ }
+ : {
+ name: manifest.config.name,
+ description: manifest.config.description,
+ modelRouting: { kind: "dynamic" },
+ },
instructions: manifest.instructions ? toInstructionsEntry(manifest.instructions) : null,
schedules: manifest.schedules.map(toScheduleEntry),
tools: manifest.tools.map(toToolEntry),
diff --git a/packages/eve/src/internal/nitro/host/create-application-nitro.ts b/packages/eve/src/internal/nitro/host/create-application-nitro.ts
index c3f2ccce5..06bae42bf 100644
--- a/packages/eve/src/internal/nitro/host/create-application-nitro.ts
+++ b/packages/eve/src/internal/nitro/host/create-application-nitro.ts
@@ -100,13 +100,14 @@ function collectHostedTraceDependencies(
preparedHost: PreparedApplicationHost,
configuredOptionalEnginePackages: readonly string[],
): string[] {
- const agentNodes = [
- preparedHost.compileResult.manifest,
- ...preparedHost.compileResult.manifest.subagents.map((subagent) => subagent.agent),
+ const configuredExternalDependencies = [
+ ...(preparedHost.compileResult.manifest.config.build?.externalDependencies ?? []),
+ ...preparedHost.compileResult.manifest.subagents.flatMap((subagent) =>
+ subagent.configResolver === undefined
+ ? (subagent.agent.config.build?.externalDependencies ?? [])
+ : (subagent.configResolver.build?.externalDependencies ?? []),
+ ),
];
- const configuredExternalDependencies = agentNodes.flatMap(
- (node) => node.config.build?.externalDependencies ?? [],
- );
// Nitro already classifies known native and non-bundleable packages through
// its nf3 database. traceDeps is only for eve-owned or author-configured
// additions to that upstream policy.
diff --git a/packages/eve/src/internal/nitro/host/dev-host-fingerprint.ts b/packages/eve/src/internal/nitro/host/dev-host-fingerprint.ts
index 6ab2f04e0..5206c23f5 100644
--- a/packages/eve/src/internal/nitro/host/dev-host-fingerprint.ts
+++ b/packages/eve/src/internal/nitro/host/dev-host-fingerprint.ts
@@ -14,7 +14,14 @@ export async function computeDevelopmentHostFingerprint(
agentName: manifest.config.name,
bundler: {
externalDependencies: [
- ...new Set(agentNodes.flatMap((node) => node.config.build?.externalDependencies ?? [])),
+ ...new Set([
+ ...(manifest.config.build?.externalDependencies ?? []),
+ ...manifest.subagents.flatMap((subagent) =>
+ subagent.configResolver === undefined
+ ? (subagent.agent.config.build?.externalDependencies ?? [])
+ : (subagent.configResolver.build?.externalDependencies ?? []),
+ ),
+ ]),
].sort((left, right) => left.localeCompare(right)),
extensionScopes: agentNodes
.flatMap((node) => node.extensionMounts)
diff --git a/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response-from-manifest.test.ts b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response-from-manifest.test.ts
new file mode 100644
index 000000000..f50099171
--- /dev/null
+++ b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response-from-manifest.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+
+import { AgentInfoResultSchema } from "#client/agent-info-schema.js";
+import { createCompiledAgentManifest } from "#compiler/manifest.js";
+import { buildAgentInfoResponseFromManifest } from "#internal/nitro/routes/agent-info/build-agent-info-response-from-manifest.js";
+
+describe("buildAgentInfoResponseFromManifest", () => {
+ it("reports unresolved dynamic models without a model id", () => {
+ const manifest = createCompiledAgentManifest({
+ agentRoot: "/app/agent",
+ appRoot: "/app",
+ config: {
+ dynamicModel: {
+ eventNames: ["turn.started"],
+ logicalPath: "agent.ts",
+ sourceId: "agent-config",
+ sourceKind: "module",
+ },
+ name: "app",
+ },
+ });
+
+ const result = buildAgentInfoResponseFromManifest(
+ { manifest, schedules: [] },
+ {
+ gatewayCredentials: { apiKey: false, oidc: false },
+ mode: "development",
+ },
+ );
+
+ expect(result.agent.model).toEqual({
+ reasoning: undefined,
+ routing: { kind: "dynamic" },
+ });
+ expect("id" in result.agent.model).toBe(false);
+ expect(AgentInfoResultSchema.safeParse(result).success).toBe(true);
+ });
+});
diff --git a/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response-from-manifest.ts b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response-from-manifest.ts
index ce19c24aa..9cfbc84bc 100644
--- a/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response-from-manifest.ts
+++ b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response-from-manifest.ts
@@ -86,18 +86,26 @@ export function buildAgentInfoResponseFromManifest(
appRoot: manifest.appRoot,
configSource: manifest.config.source ? toSource(manifest.config.source) : undefined,
description: manifest.config.description,
- model: {
- contextWindowTokens: manifest.config.model.contextWindowTokens,
- id: manifest.config.model.id,
- providerOptions: manifest.config.model.providerOptions,
- reasoning: manifest.config.reasoning,
- source: manifest.config.model.source ? toSource(manifest.config.model.source) : undefined,
- routing: manifest.config.model.routing,
- endpoint: resolveModelEndpointStatus(
- manifest.config.model.routing,
- input.gatewayCredentials,
- ),
- },
+ model:
+ manifest.config.dynamicModel === undefined
+ ? {
+ contextWindowTokens: manifest.config.model.contextWindowTokens,
+ id: manifest.config.model.id,
+ providerOptions: manifest.config.model.providerOptions,
+ reasoning: manifest.config.reasoning,
+ source: manifest.config.model.source
+ ? toSource(manifest.config.model.source)
+ : undefined,
+ routing: manifest.config.model.routing,
+ endpoint: resolveModelEndpointStatus(
+ manifest.config.model.routing,
+ input.gatewayCredentials,
+ ),
+ }
+ : {
+ reasoning: manifest.config.reasoning,
+ routing: { kind: "dynamic" },
+ },
name: manifest.config.name,
outputSchema: manifest.config.outputSchema,
},
diff --git a/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.test.ts b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.test.ts
index 5898486fe..de7492af6 100644
--- a/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.test.ts
+++ b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.test.ts
@@ -1,6 +1,11 @@
import { describe, expect, it } from "vitest";
-import { buildFrameworkToolInfo } from "#internal/nitro/routes/agent-info/build-agent-info-response.js";
+import { createCompiledAgentManifest } from "#compiler/manifest.js";
+import {
+ buildAgentInfoResponse,
+ buildFrameworkToolInfo,
+} from "#internal/nitro/routes/agent-info/build-agent-info-response.js";
+import { resolveAgent } from "#runtime/resolve-agent.js";
describe("buildFrameworkToolInfo", () => {
it("reports the built-in agent action as active and available by default", () => {
@@ -57,3 +62,34 @@ describe("buildFrameworkToolInfo", () => {
});
});
});
+
+describe("buildAgentInfoResponse", () => {
+ it("preserves direct-provider routing from the compiled manifest", async () => {
+ const manifest = createCompiledAgentManifest({
+ agentRoot: "/app/agent",
+ appRoot: "/app",
+ config: {
+ compaction: {},
+ model: {
+ id: "openai/gpt-5",
+ routing: { kind: "external", provider: "openai" },
+ },
+ name: "direct-model-agent",
+ },
+ });
+ const agent = await resolveAgent({
+ manifest,
+ moduleMap: { nodes: { __root__: { modules: {} } } },
+ });
+
+ const response = buildAgentInfoResponse(
+ { agent, manifest, schedules: [] },
+ { mode: "development" },
+ );
+
+ expect(response.agent.model).toMatchObject({
+ id: "openai/gpt-5",
+ routing: { kind: "external", provider: "openai" },
+ });
+ });
+});
diff --git a/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.ts b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.ts
index f94270fcf..b1cb033d1 100644
--- a/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.ts
+++ b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.ts
@@ -162,22 +162,35 @@ export interface AgentInfoDiagnostics {
readonly discoveryWarnings: number;
}
+interface AgentInfoModelBase {
+ readonly contextWindowTokens?: number;
+ readonly providerOptions?: unknown;
+ /** The agent's authored reasoning effort, forwarded to the model call. */
+ readonly reasoning?: AgentReasoningDefinition;
+ readonly source?: AgentInfoSource;
+}
+
+export type AgentInfoModel = AgentInfoModelBase &
+ (
+ | {
+ readonly id: string;
+ readonly routing: ModelRouting;
+ readonly endpoint?: ModelEndpointStatus;
+ }
+ | {
+ readonly id?: never;
+ readonly routing: { readonly kind: "dynamic" };
+ readonly endpoint?: never;
+ }
+ );
+
export interface AgentInfoResponse {
readonly agent: {
readonly agentRoot: string;
readonly appRoot: string;
readonly configSource?: AgentInfoSource;
readonly description?: string;
- readonly model: {
- readonly contextWindowTokens?: number;
- readonly id: string;
- readonly providerOptions?: unknown;
- /** The agent's authored reasoning effort, forwarded to the model call. */
- readonly reasoning?: AgentReasoningDefinition;
- readonly source?: AgentInfoSource;
- readonly routing?: ModelRouting;
- readonly endpoint?: ModelEndpointStatus;
- };
+ readonly model: AgentInfoModel;
readonly name: string;
readonly outputSchema?: unknown;
};
@@ -220,23 +233,34 @@ export function buildAgentInfoResponse(
},
): AgentInfoResponse {
const agent = data.agent;
+ const config = agent.config;
+ if (config === undefined) {
+ throw new Error("Cannot inspect unresolved dynamic subagent resources as a root agent.");
+ }
const tools = buildToolInfo(agent, getRootDelegationToolNames(data.manifest));
return {
agent: {
agentRoot: agent.metadata.agentRoot,
appRoot: agent.metadata.appRoot,
- configSource: agent.config.source ? toSource(agent.config.source) : undefined,
- description: agent.config.description,
- model: {
- contextWindowTokens: agent.config.model.contextWindowTokens,
- id: agent.config.model.id,
- providerOptions: agent.config.model.providerOptions,
- reasoning: agent.config.reasoning,
- source: agent.config.model.source ? toSource(agent.config.model.source) : undefined,
- },
- name: agent.config.name,
- outputSchema: agent.config.outputSchema,
+ configSource: config.source ? toSource(config.source) : undefined,
+ description: config.description,
+ model:
+ config.dynamicModel === undefined
+ ? {
+ contextWindowTokens: config.model.contextWindowTokens,
+ id: config.model.id,
+ providerOptions: config.model.providerOptions,
+ reasoning: config.reasoning,
+ source: config.model.source ? toSource(config.model.source) : undefined,
+ routing: resolveStaticAgentModelRouting(data.manifest),
+ }
+ : {
+ reasoning: config.reasoning,
+ routing: { kind: "dynamic" },
+ },
+ name: config.name,
+ outputSchema: config.outputSchema,
},
capabilities: {
devRoutes: input.mode === "development",
@@ -301,6 +325,13 @@ export function buildAgentInfoResponse(
};
}
+function resolveStaticAgentModelRouting(manifest: CompiledAgentManifest): ModelRouting {
+ if (manifest.config.model === undefined) {
+ throw new Error("Resolved static agent config does not match its compiled manifest.");
+ }
+ return manifest.config.model.routing;
+}
+
function buildChannelInfo(agent: ResolvedAgent): AgentInfoChannels {
const authoredChannelNames = new Set(agent.channels.map((channel) => channel.name));
const disabledFrameworkChannels = new Set(agent.disabledFrameworkChannels);
diff --git a/packages/eve/src/internal/nitro/routes/info.ts b/packages/eve/src/internal/nitro/routes/info.ts
index 7b7c7b246..39df13b5e 100644
--- a/packages/eve/src/internal/nitro/routes/info.ts
+++ b/packages/eve/src/internal/nitro/routes/info.ts
@@ -16,7 +16,10 @@ async function createAgentInfoPayload(input: NitroArtifactsConfig) {
return buildAgentInfoResponseFromManifest(data, {
mode: input.kind,
- gatewayCredentials: await resolveGatewayCredentialPresence(data.manifest.config.model.routing),
+ gatewayCredentials:
+ data.manifest.config.dynamicModel === undefined
+ ? await resolveGatewayCredentialPresence(data.manifest.config.model.routing)
+ : { apiKey: false, oidc: false },
});
}
diff --git a/packages/eve/src/internal/testing/durable-session-workflow.ts b/packages/eve/src/internal/testing/durable-session-workflow.ts
index 286e11ac5..6db0c4728 100644
--- a/packages/eve/src/internal/testing/durable-session-workflow.ts
+++ b/packages/eve/src/internal/testing/durable-session-workflow.ts
@@ -34,6 +34,7 @@ function buildSyntheticSession(input: {
},
compaction: {
recentWindowSize: 0,
+ thresholdPercent: 0.9,
threshold: 0.7,
},
continuationToken: `test:${input.sessionId}`,
diff --git a/packages/eve/src/internal/testing/task-model-retry-workflow.ts b/packages/eve/src/internal/testing/task-model-retry-workflow.ts
index b91acdf25..70297c3ee 100644
--- a/packages/eve/src/internal/testing/task-model-retry-workflow.ts
+++ b/packages/eve/src/internal/testing/task-model-retry-workflow.ts
@@ -46,7 +46,7 @@ export async function createTaskModelRetrySessionStep(input: {
system: "You are a test assistant.",
tools: [],
},
- compaction: { recentWindowSize: 10, threshold: 100_000 },
+ compaction: { recentWindowSize: 10, threshold: 100_000, thresholdPercent: 0.9 },
continuationToken: `subagent:${input.sessionId}`,
history: [...PRIOR_HISTORY],
sessionId: input.sessionId,
diff --git a/packages/eve/src/internal/vercel-agent-summary.ts b/packages/eve/src/internal/vercel-agent-summary.ts
index 1de6db317..324013769 100644
--- a/packages/eve/src/internal/vercel-agent-summary.ts
+++ b/packages/eve/src/internal/vercel-agent-summary.ts
@@ -37,7 +37,7 @@ export const VERCEL_EVE_AGENT_SUMMARY_KIND = "vercel-eve-agent-summary" as const
* making semantic changes consumers must opt into. Adding optional fields
* does not require a version bump.
*/
-export const VERCEL_EVE_AGENT_SUMMARY_VERSION = 3;
+export const VERCEL_EVE_AGENT_SUMMARY_VERSION = 4;
/**
* Output path (relative to the agent's `appRoot`) where eve writes the
@@ -62,12 +62,17 @@ export type VercelEveChannelType = "slack" | "http" | "webhook" | "unknown";
/**
* Top-level agent identity used to label the dashboard card.
*/
-export interface VercelEveAgentEntry {
+interface VercelEveAgentEntryBase {
readonly name: string;
readonly description?: string;
- readonly modelId: string;
}
+export type VercelEveAgentEntry = VercelEveAgentEntryBase &
+ (
+ | { readonly modelId: string; readonly modelRouting?: never }
+ | { readonly modelId?: never; readonly modelRouting: { readonly kind: "dynamic" } }
+ );
+
/**
* Authored agent instructions resolved at build time from the agent's
* `instructions.md` or `instructions.{ts,cts,mts,js,cjs,mjs}` source.
diff --git a/packages/eve/src/protocol/message.test.ts b/packages/eve/src/protocol/message.test.ts
index c391b5d96..0fb830816 100644
--- a/packages/eve/src/protocol/message.test.ts
+++ b/packages/eve/src/protocol/message.test.ts
@@ -102,7 +102,12 @@ describe("message stream protocol", () => {
it("stamps durable envelope metadata and preserves it through encoding", () => {
const stamped = stampMessageStreamEvent(
- createStepStartedEvent({ sequence: 0, stepIndex: 1, turnId: "turn_0" }),
+ createStepStartedEvent({
+ modelId: "openai/gpt-5.5",
+ sequence: 0,
+ stepIndex: 1,
+ turnId: "turn_0",
+ }),
);
expect(isEventId(stamped.meta.id)).toBe(true);
@@ -115,7 +120,12 @@ describe("message stream protocol", () => {
});
it("mints a distinct id for each emission of an identical payload", () => {
- const event = createStepStartedEvent({ sequence: 0, stepIndex: 0, turnId: "turn_0" });
+ const event = createStepStartedEvent({
+ modelId: "openai/gpt-5.5",
+ sequence: 0,
+ stepIndex: 0,
+ turnId: "turn_0",
+ });
expect(stampMessageStreamEvent(event).meta.id).not.toBe(stampMessageStreamEvent(event).meta.id);
});
diff --git a/packages/eve/src/protocol/message.ts b/packages/eve/src/protocol/message.ts
index 2fa37aa13..92c47133a 100644
--- a/packages/eve/src/protocol/message.ts
+++ b/packages/eve/src/protocol/message.ts
@@ -117,8 +117,6 @@ export interface RuntimeIdentity {
readonly gitBranch?: string;
readonly gitSha?: string;
};
- /** Configured model id; dynamic-model agents report `dynamic:<fallback id>`. */
- readonly modelId: string;
}
/**
@@ -399,6 +397,7 @@ export interface ResultCompletedStreamEvent {
*/
export interface StepStartedStreamEvent {
data: {
+ readonly modelId: string;
sequence: number;
stepIndex: number;
turnId: string;
@@ -1249,12 +1248,14 @@ export function createResultCompletedEvent(input: {
* Creates the `step.started` event for one model call.
*/
export function createStepStartedEvent(input: {
+ readonly modelId: string;
readonly sequence: number;
readonly stepIndex: number;
readonly turnId: string;
}): StepStartedStreamEvent {
return {
data: {
+ modelId: input.modelId,
sequence: input.sequence,
stepIndex: input.stepIndex,
turnId: input.turnId,
diff --git a/packages/eve/src/public/definitions/agent.ts b/packages/eve/src/public/definitions/agent.ts
index 80179add2..0290fad44 100644
--- a/packages/eve/src/public/definitions/agent.ts
+++ b/packages/eve/src/public/definitions/agent.ts
@@ -1,12 +1,12 @@
-import type { AgentBuildDefinition, PublicAgentDefinition } from "#shared/agent-definition.js";
+import type {
+ AgentBuildDefinition,
+ PublicAgentDefinition,
+ PublicAgentStaticModelDefinition,
+} from "#shared/agent-definition.js";
import type { ExactDefinition } from "#public/definitions/exact.js";
import type { RemoteAgentDefinition } from "#public/definitions/remote-agent.js";
import { defineDynamic as defineDynamicBase } from "#public/definitions/tool.js";
-import type {
- DynamicEvents,
- DynamicEventsWithFallback,
- DynamicSentinel,
-} from "#shared/dynamic-tool-definition.js";
+import type { DynamicEvents, DynamicSentinel } from "#shared/dynamic-tool-definition.js";
declare const DEFINED_AGENT: unique symbol;
@@ -49,9 +49,10 @@ export type DefinedAgent<TAgent extends AgentDefinition = AgentDefinition> = TAg
* Agent configuration returned by a dynamic subagent resolver. The description
* tells the parent agent when to delegate.
*/
-export type DynamicLocalSubagentDefinition = AgentDefinition & {
- readonly description: string;
-};
+export type DynamicLocalSubagentDefinition = Extract<
+ AgentDefinition,
+ { readonly model: PublicAgentStaticModelDefinition }
+> & { readonly description: string };
/** Definition a dynamic subagent resolver may select at runtime. */
export type DynamicSubagentDefinition = DynamicLocalSubagentDefinition | RemoteAgentDefinition;
@@ -72,12 +73,6 @@ type DynamicSubagentDescriptionConstraint<TEvents extends DynamicEvents> =
: { readonly "Dynamic subagent definitions require a description": never };
interface DefineDynamicAgent {
- <const TEvents extends DynamicEventsWithFallback, TFallback = unknown>(
- definition: {
- readonly fallback: TFallback;
- readonly events: TEvents;
- } & DynamicSubagentDescriptionConstraint<TEvents>,
- ): DynamicSentinel<Exclude<DynamicEventResult<TEvents>, undefined>, TFallback>;
<const TEvents extends DynamicEvents>(
definition: {
readonly build?: AgentBuildDefinition;
@@ -94,11 +89,8 @@ interface DefineDynamicAgent {
export const defineDynamic: DefineDynamicAgent = ((definition: {
readonly build?: AgentBuildDefinition;
readonly events: DynamicEvents;
- readonly fallback?: unknown;
}) => {
- const sentinel = Object.hasOwn(definition, "fallback")
- ? defineDynamicBase({ events: definition.events, fallback: definition.fallback })
- : defineDynamicBase({ events: definition.events });
+ const sentinel = defineDynamicBase({ events: definition.events });
return definition.build === undefined ? sentinel : { ...sentinel, build: definition.build };
}) as DefineDynamicAgent;
diff --git a/packages/eve/src/public/definitions/exact.test.ts b/packages/eve/src/public/definitions/exact.test.ts
index 066ae8ff2..d6aa982e6 100644
--- a/packages/eve/src/public/definitions/exact.test.ts
+++ b/packages/eve/src/public/definitions/exact.test.ts
@@ -101,6 +101,33 @@ describe("definition helper exact inputs", () => {
});
function typeOnlyFixtures(): void {
+ defineDynamic({
+ // @ts-expect-error defineDynamic is resolver-only.
+ fallback: "anthropic/claude-sonnet-5",
+ events: {
+ "session.started": () => "anthropic/claude-sonnet-5",
+ },
+ });
+
+ defineAgent({
+ // @ts-expect-error Dynamic model handlers must return a concrete selection.
+ model: defineDynamic({
+ events: {
+ "session.started": () => null,
+ },
+ }),
+ });
+
+ // @ts-expect-error Dynamic model metadata belongs on each returned selection.
+ defineAgent({
+ model: defineDynamic({
+ events: {
+ "session.started": () => "anthropic/claude-sonnet-5",
+ },
+ }),
+ modelContextWindowTokens: 200_000,
+ });
+
// @ts-expect-error Dynamic subagents require a parent-facing description.
defineDynamic({
events: {
@@ -137,6 +164,21 @@ function typeOnlyFixtures(): void {
},
});
+ // @ts-expect-error A dynamic local-subagent selection must use a static model.
+ defineDynamic({
+ events: {
+ "session.started": () =>
+ defineAgent({
+ description: "Delegate research tasks.",
+ model: defineDynamic({
+ events: {
+ "session.started": () => "anthropic/claude-sonnet-5",
+ },
+ }),
+ }),
+ },
+ });
+
defineAgent({
limits: {
// @ts-expect-error Recursive delegation is root-only; this limit was removed.
diff --git a/packages/eve/src/public/definitions/tool.ts b/packages/eve/src/public/definitions/tool.ts
index 8a7fca566..943cdf0d6 100644
--- a/packages/eve/src/public/definitions/tool.ts
+++ b/packages/eve/src/public/definitions/tool.ts
@@ -18,7 +18,6 @@ import {
DYNAMIC_SENTINEL_KIND,
TOOL_BRAND,
type DynamicEvents,
- type DynamicEventsWithFallback,
type DynamicSentinel,
} from "#shared/dynamic-tool-definition.js";
@@ -304,22 +303,13 @@ export function defineTool<TInput = unknown, TOutput = unknown>(
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;
+export function defineDynamic<TResult = unknown>(definition: {
readonly events: DynamicEvents<TResult>;
-}): DynamicSentinel<TResult, TFallback> {
+}): DynamicSentinel<TResult> {
const sentinel = {
kind: DYNAMIC_SENTINEL_KIND,
events: definition.events,
- ...(Object.hasOwn(definition, "fallback") ? { fallback: definition.fallback } : {}),
- } as DynamicSentinel<TResult, TFallback>;
+ } as DynamicSentinel<TResult>;
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.ts
index 2af5757f8..84d8a7500 100644
--- a/packages/eve/src/public/index.ts
+++ b/packages/eve/src/public/index.ts
@@ -10,6 +10,7 @@ export {
type AgentModelDefinition,
type AgentModelOptionsDefinition,
type AgentReasoningDefinition,
+ type AgentStaticModelDefinition,
type AgentWorkflowDefinition,
type AgentWorkflowWorldDefinition,
type DefinedAgent,
diff --git a/packages/eve/src/runtime/agent/bootstrap.ts b/packages/eve/src/runtime/agent/bootstrap.ts
index e44166a9d..66a0d2a6c 100644
--- a/packages/eve/src/runtime/agent/bootstrap.ts
+++ b/packages/eve/src/runtime/agent/bootstrap.ts
@@ -1,7 +1,7 @@
import { AGENT_TOOL_NAME, isImplicitAgentToolAvailable } from "#runtime/framework-tools/agent.js";
import { composeRuntimeBasePrompt } from "#runtime/prompt/compose.js";
import type { PreparedRuntimeTool } from "#runtime/sessions/turn.js";
-import type { ResolvedAgent } from "#runtime/types.js";
+import type { ResolvedAgent, ResolvedAgentDefinition } 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";
@@ -30,7 +30,7 @@ export type RuntimeDynamicModelReference = Readonly<
/**
* Minimal runtime-owned agent shape prepared for one harness turn.
*/
-export interface RuntimeTurnAgent {
+interface RuntimeTurnAgentBase {
readonly availableSkills?: readonly AvailableSkillDescription[];
readonly id: string;
readonly instructions: readonly string[];
@@ -40,15 +40,32 @@ 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"];
- readonly reasoning?: ResolvedAgent["config"]["reasoning"];
+ readonly outputSchema?: ResolvedAgentDefinition["outputSchema"];
+ readonly reasoning?: ResolvedAgentDefinition["reasoning"];
readonly tools: readonly PreparedRuntimeTool[];
readonly workspaceSpec: WorkspaceRuntimeSpec;
}
+export type RuntimeTurnAgent = RuntimeTurnAgentBase &
+ (
+ | {
+ readonly configResolver?: never;
+ readonly dynamicModel?: never;
+ readonly model: RuntimeModelReference;
+ }
+ | {
+ readonly dynamicModel: RuntimeDynamicModelReference;
+ readonly configResolver?: never;
+ readonly model?: never;
+ }
+ | {
+ readonly configResolver: true;
+ readonly dynamicModel?: never;
+ readonly model?: never;
+ }
+ );
+
/**
* Static system prompt for the bootstrap runtime path.
*/
@@ -61,10 +78,16 @@ export const BOOTSTRAP_RUNTIME_SYSTEM_PROMPT =
*/
export function createResolvedRuntimeTurnAgent(input: {
readonly agent: ResolvedAgent;
+ readonly id?: string;
readonly nodeId?: string;
readonly tools: readonly PreparedRuntimeTool[];
}): RuntimeTurnAgent {
const agent = input.agent;
+ const config = agent.config;
+ const id = input.id ?? config?.name;
+ if (id === undefined) {
+ throw new Error("Expected a path-derived agent id while resolving agent resources.");
+ }
const subagentDeclaredTool = input.tools.some(
(tool) => tool.kind === "subagent" || tool.kind === "remote",
);
@@ -78,27 +101,30 @@ export function createResolvedRuntimeTurnAgent(input: {
hasAuthoredAgentTool: input.tools.some((tool) => tool.name === AGENT_TOOL_NAME),
nodeId: input.nodeId,
});
- return {
+ const base: RuntimeTurnAgentBase = {
availableSkills: agent.skills.map((skill) => ({
description: skill.description,
name: skill.name,
})),
- id: agent.config.name,
+ id,
instructions: composeRuntimeBasePrompt({
connections: agent.connections,
instructions: agent.instructions,
- persistentSubagentSessions: agent.config.experimental?.subagentPersistentSessions === true,
+ persistentSubagentSessions: config?.experimental?.subagentPersistentSessions === true,
subagentsAvailable: subagentDeclaredTool || subagentImplicitRootTool,
toolsAvailable: input.tools.length > 0 || subagentImplicitRootTool,
workspaceSpec: agent.workspaceSpec,
}),
- compactionModel: agent.config.compaction?.model,
- dynamicModel: agent.config.dynamicModel,
- model: agent.config.model,
+ compactionModel: config?.compaction?.model,
nodeId: input.nodeId,
- outputSchema: agent.config.outputSchema,
- reasoning: agent.config.reasoning,
+ outputSchema: config?.outputSchema,
+ reasoning: config?.reasoning,
tools: [...input.tools],
workspaceSpec: agent.workspaceSpec,
};
+
+ if (config === undefined) return { ...base, configResolver: true };
+ return config.dynamicModel === undefined
+ ? { ...base, model: config.model }
+ : { ...base, dynamicModel: config.dynamicModel };
}
diff --git a/packages/eve/src/runtime/agent/model-catalog.test.ts b/packages/eve/src/runtime/agent/model-catalog.test.ts
new file mode 100644
index 000000000..5be2d0987
--- /dev/null
+++ b/packages/eve/src/runtime/agent/model-catalog.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createRuntimeModelCatalog } from "#runtime/agent/model-catalog.js";
+
+const CATALOG = {
+ models: [
+ {
+ providers: [
+ {
+ contextWindowTokens: 200_000,
+ maxOutputTokens: 32_000,
+ provider: "anthropic",
+ providerModelId: "claude-opus-4-7",
+ },
+ ],
+ slug: "anthropic/claude-opus-4.7",
+ },
+ {
+ providers: [
+ {
+ contextWindowTokens: 1_000,
+ maxOutputTokens: 1_000,
+ provider: "bfl",
+ providerModelId: "flux-pro",
+ },
+ ],
+ slug: "bfl/flux-pro",
+ },
+ ],
+ providerAliases: { blackForestLabs: "bfl" },
+};
+
+describe("createRuntimeModelCatalog", () => {
+ it("resolves gateway ids and provider aliases from one execution-local response", async () => {
+ const fetchCatalog = vi.fn(async () => Response.json(CATALOG));
+ const catalog = createRuntimeModelCatalog(fetchCatalog);
+
+ await expect(catalog.getByGatewayId("anthropic/claude-opus-4.7-thinking")).resolves.toEqual({
+ contextWindowTokens: 200_000,
+ maxOutputTokens: 32_000,
+ resolvedModelId: "anthropic/claude-opus-4.7",
+ });
+ await expect(
+ catalog.getByProviderModelId("blackForestLabs.images", "flux-pro"),
+ ).resolves.toEqual({
+ contextWindowTokens: 1_000,
+ maxOutputTokens: 1_000,
+ resolvedModelId: "bfl/flux-pro",
+ });
+ expect(fetchCatalog).toHaveBeenCalledOnce();
+ });
+
+ it("does not retain a failed catalog request", async () => {
+ const fetchCatalog = vi
+ .fn<typeof fetch>()
+ .mockRejectedValueOnce(new Error("transport unavailable"))
+ .mockResolvedValueOnce(Response.json(CATALOG));
+ const catalog = createRuntimeModelCatalog(fetchCatalog);
+
+ await expect(catalog.getByGatewayId("anthropic/claude-opus-4.7")).rejects.toThrow(
+ "transport unavailable",
+ );
+ await expect(catalog.getByGatewayId("anthropic/claude-opus-4.7")).resolves.toMatchObject({
+ resolvedModelId: "anthropic/claude-opus-4.7",
+ });
+ expect(fetchCatalog).toHaveBeenCalledTimes(2);
+ });
+
+ it("keeps authentication and HTTP failures distinct from missing models", async () => {
+ const catalog = createRuntimeModelCatalog(
+ vi.fn(async () => new Response(null, { status: 401, statusText: "Unauthorized" })),
+ );
+
+ await expect(catalog.getByGatewayId("anthropic/claude-opus-4.7")).rejects.toThrow(
+ "HTTP 401 Unauthorized",
+ );
+ });
+});
diff --git a/packages/eve/src/runtime/agent/model-catalog.ts b/packages/eve/src/runtime/agent/model-catalog.ts
new file mode 100644
index 000000000..1a82a47d1
--- /dev/null
+++ b/packages/eve/src/runtime/agent/model-catalog.ts
@@ -0,0 +1,83 @@
+import { AI_GATEWAY_MODELS_CATALOG_URL, vercelGatewayFetch } from "#internal/gateway.js";
+import {
+ findCatalogModelByProviderModelId,
+ findCatalogModelBySlug,
+ modelCatalogLimitsFromProvider,
+ modelCatalogResponseSchema,
+} from "#internal/model-catalog.js";
+
+export interface RuntimeModelMetadata {
+ readonly contextWindowTokens: number;
+ readonly maxOutputTokens?: number;
+ readonly resolvedModelId: string;
+}
+
+export interface RuntimeModelCatalog {
+ getByGatewayId(modelId: string): Promise<RuntimeModelMetadata | null>;
+ getByProviderModelId(
+ provider: string,
+ providerModelId: string,
+ ): Promise<RuntimeModelMetadata | null>;
+}
+
+export function createRuntimeModelCatalog(
+ fetchCatalog: typeof globalThis.fetch = vercelGatewayFetch,
+): RuntimeModelCatalog {
+ let catalogPromise: Promise<ReturnType<typeof parseCatalogResponse>> | null = null;
+
+ const loadCatalog = async () => {
+ if (catalogPromise === null) {
+ catalogPromise = fetchCatalog(AI_GATEWAY_MODELS_CATALOG_URL)
+ .then(async (response) => {
+ if (!response.ok) {
+ throw new Error(
+ `AI Gateway model catalog request failed with HTTP ${response.status} ${response.statusText}.`,
+ );
+ }
+ return parseCatalogResponse(await response.json());
+ })
+ .catch((error: unknown) => {
+ catalogPromise = null;
+ throw error;
+ });
+ }
+ return await catalogPromise;
+ };
+
+ return {
+ async getByGatewayId(modelId) {
+ const catalog = await loadCatalog();
+ const model = findCatalogModelBySlug(catalog.models, modelId);
+ if (model === undefined) return null;
+
+ for (const provider of model.providers) {
+ const limits = modelCatalogLimitsFromProvider(provider);
+ if (limits !== null) {
+ return { ...limits, resolvedModelId: model.slug };
+ }
+ }
+ return null;
+ },
+
+ async getByProviderModelId(provider, providerModelId) {
+ const catalog = await loadCatalog();
+ const match = findCatalogModelByProviderModelId({
+ models: catalog.models,
+ provider,
+ providerAliases: catalog.providerAliases,
+ providerModelId,
+ });
+ if (match === null) return null;
+ const limits = modelCatalogLimitsFromProvider(match.provider);
+ return limits === null ? null : { ...limits, resolvedModelId: match.model.slug };
+ },
+ };
+}
+
+function parseCatalogResponse(value: unknown) {
+ const parsed = modelCatalogResponseSchema.safeParse(value);
+ if (!parsed.success) {
+ throw new Error("AI Gateway model catalog response did not match the expected schema.");
+ }
+ return parsed.data;
+}
diff --git a/packages/eve/src/runtime/agent/resolve-model.test.ts b/packages/eve/src/runtime/agent/resolve-model.test.ts
index b93789775..32f90992d 100644
--- a/packages/eve/src/runtime/agent/resolve-model.test.ts
+++ b/packages/eve/src/runtime/agent/resolve-model.test.ts
@@ -1,12 +1,17 @@
+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 { RuntimeModelMetadataCacheKey } from "#context/keys.js";
+import { deserializeContext, serializeContext } from "#context/serialize.js";
import { defineDynamic } from "#public/definitions/tool.js";
+import type { RuntimeModelCatalog } from "#runtime/agent/model-catalog.js";
import {
loadDynamicRuntimeModelDefinition,
- normalizeDynamicRuntimeModelResult,
resolveRuntimeModelReference,
+ resolveRuntimeModelSelection,
} from "#runtime/agent/resolve-model.js";
const DYNAMIC_MODEL_SOURCE = {
@@ -18,6 +23,7 @@ const DYNAMIC_MODEL_SOURCE = {
describe("dynamic runtime model resolution", () => {
afterEach(() => {
+ vi.restoreAllMocks();
vi.unstubAllEnvs();
});
@@ -41,22 +47,18 @@ describe("dynamic runtime model resolution", () => {
expect(model.modelId).toBe("eve-mock/dynamic-subagent");
});
- it("loads dynamic model definitions and normalizes string selections", async () => {
+ it("loads resolver-only definitions and normalizes explicit metadata", 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,
+ "session.started": (_event, ctx) => ({
+ model: ctx.channel.kind === "slack" ? "openai/gpt-5.5-mini" : "openai/gpt-5.5",
+ modelContextWindowTokens: 128_000,
+ modelOptions: {
+ providerOptions: { gateway: { order: ["openai"] } },
+ },
+ }),
},
}),
},
@@ -75,53 +77,207 @@ describe("dynamic runtime model resolution", () => {
},
);
- 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,
+ const resolved = await resolveRuntimeModelSelection({
+ durability: "live",
+ selection: result as never,
+ state: new ContextContainer(),
});
expect(resolved).toEqual({
reference: {
contextWindowTokens: 128_000,
id: "openai/gpt-5.5-mini",
+ maxOutputTokens: undefined,
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"] } },
+ it("resolves omitted metadata from the catalog and caches successful selections", async () => {
+ const state = new ContextContainer();
+ const catalog = createCatalog();
+
+ const first = await resolveRuntimeModelSelection({
+ catalog,
+ durability: "live",
+ selection: "openai/gpt-5.5",
+ state,
+ });
+ const second = await resolveRuntimeModelSelection({
+ catalog,
+ durability: "live",
+ selection: "openai/gpt-5.5",
+ state,
+ });
+
+ expect(first.reference).toMatchObject({
+ contextWindowTokens: 256_000,
+ id: "openai/gpt-5.5",
+ maxOutputTokens: 32_000,
+ });
+ expect(second).toEqual(first);
+ expect(catalog.getByGatewayId).toHaveBeenCalledTimes(1);
+ });
+
+ it("reuses cached metadata after durable context serialization", async () => {
+ const state = new ContextContainer();
+ await resolveRuntimeModelSelection({
+ catalog: createCatalog(),
+ durability: "live",
+ selection: "openai/gpt-5.5",
+ state,
+ });
+ const resumedState = await deserializeContext(serializeContext(state));
+ const resumedCatalog = createCatalog();
+
+ await expect(
+ resolveRuntimeModelSelection({
+ catalog: resumedCatalog,
+ durability: "live",
+ selection: "openai/gpt-5.5",
+ state: resumedState,
+ }),
+ ).resolves.toMatchObject({ reference: { id: "openai/gpt-5.5" } });
+ expect(resumedCatalog.getByGatewayId).not.toHaveBeenCalled();
+ });
+
+ it("prunes expired entries during successful cache writes", async () => {
+ vi.spyOn(Date, "now").mockReturnValue(2_000);
+ const state = new ContextContainer();
+ state.set(RuntimeModelMetadataCacheKey, {
+ "gateway:expired/model": {
+ contextWindowTokens: 1,
+ expiresAt: 1_999,
+ resolvedModelId: "expired/model",
},
- result: "openai/gpt-5.5-mini",
});
- expect(resolved.reference).toEqual({
- contextWindowTokens: undefined,
- id: "openai/gpt-5.5-mini",
- providerOptions: { gateway: { order: ["openai"] } },
+ await resolveRuntimeModelSelection({
+ catalog: createCatalog(),
+ durability: "live",
+ selection: "openai/gpt-5.5",
+ state,
});
+
+ expect(state.get(RuntimeModelMetadataCacheKey)).not.toHaveProperty("gateway:expired/model");
+ expect(state.get(RuntimeModelMetadataCacheKey)).toHaveProperty("gateway:openai/gpt-5.5");
});
- it("rejects selections with unknown keys", () => {
- expect(() =>
- normalizeDynamicRuntimeModelResult({
- fallback: { id: "openai/gpt-5.5" },
- result: {
- model: "openai/gpt-5.5-mini",
+ it("does not cache failed catalog requests", async () => {
+ const getByGatewayId = vi
+ .fn<RuntimeModelCatalog["getByGatewayId"]>()
+ .mockRejectedValueOnce(new Error("catalog unavailable"))
+ .mockResolvedValueOnce({
+ contextWindowTokens: 256_000,
+ resolvedModelId: "openai/gpt-5.5",
+ });
+ const catalog: RuntimeModelCatalog = {
+ getByGatewayId,
+ getByProviderModelId: vi.fn(),
+ };
+ const state = new ContextContainer();
+
+ await expect(
+ resolveRuntimeModelSelection({
+ catalog,
+ durability: "live",
+ selection: "openai/gpt-5.5",
+ state,
+ }),
+ ).rejects.toThrow("catalog unavailable");
+ await expect(
+ resolveRuntimeModelSelection({
+ catalog,
+ durability: "live",
+ selection: "openai/gpt-5.5",
+ state,
+ }),
+ ).resolves.toMatchObject({ reference: { id: "openai/gpt-5.5" } });
+
+ expect(getByGatewayId).toHaveBeenCalledTimes(2);
+ });
+
+ it("normalizes live provider objects through the same catalog path", async () => {
+ const model = createLanguageModel("openai.responses", "gpt-5.5");
+ const catalog = createCatalog();
+
+ const resolved = await resolveRuntimeModelSelection({
+ catalog,
+ durability: "live",
+ selection: model,
+ state: new ContextContainer(),
+ });
+
+ expect(catalog.getByProviderModelId).toHaveBeenCalledWith("openai.responses", "gpt-5.5");
+ expect(resolved).toMatchObject({
+ model,
+ reference: {
+ contextWindowTokens: 256_000,
+ id: "openai/gpt-5.5",
+ maxOutputTokens: 32_000,
+ },
+ });
+ });
+
+ it("rejects missing, malformed, and unknown selections", async () => {
+ const state = new ContextContainer();
+
+ await expect(
+ resolveRuntimeModelSelection({ durability: "live", selection: null as never, state }),
+ ).rejects.toThrow(/returned no model/);
+ await expect(
+ resolveRuntimeModelSelection({
+ durability: "live",
+ selection: {
contextWindowTokens: 128_000,
+ model: "openai/gpt-5.5-mini",
} as never,
+ state,
+ }),
+ ).rejects.toThrow(/unknown key\(s\): contextWindowTokens/);
+ await expect(
+ resolveRuntimeModelSelection({
+ catalog: createCatalog(null),
+ durability: "live",
+ selection: "custom/unknown",
+ state,
+ }),
+ ).rejects.toThrow(/Return modelContextWindowTokens/);
+ });
+
+ it("rejects durable provider objects before catalog lookup", async () => {
+ const catalog = createCatalog();
+
+ await expect(
+ resolveRuntimeModelSelection({
+ catalog,
+ durability: "durable",
+ selection: createLanguageModel("openai.responses", "gpt-5.5"),
+ state: new ContextContainer(),
}),
- ).toThrowError(/unknown key\(s\): contextWindowTokens/);
+ ).rejects.toThrow(/durable model selections must be serializable/);
+
+ expect(catalog.getByGatewayId).not.toHaveBeenCalled();
+ expect(catalog.getByProviderModelId).not.toHaveBeenCalled();
});
});
+function createCatalog(
+ result: Awaited<ReturnType<RuntimeModelCatalog["getByGatewayId"]>> = {
+ contextWindowTokens: 256_000,
+ maxOutputTokens: 32_000,
+ resolvedModelId: "openai/gpt-5.5",
+ },
+): RuntimeModelCatalog & {
+ getByGatewayId: ReturnType<typeof vi.fn<RuntimeModelCatalog["getByGatewayId"]>>;
+ getByProviderModelId: ReturnType<typeof vi.fn<RuntimeModelCatalog["getByProviderModelId"]>>;
+} {
+ return {
+ getByGatewayId: vi.fn(async () => result),
+ getByProviderModelId: vi.fn(async () => result),
+ };
+}
+
function createModuleMap(moduleNamespace: Record<string, unknown>): CompiledModuleMap {
return {
nodes: {
@@ -133,3 +289,18 @@ function createModuleMap(moduleNamespace: Record<string, unknown>): CompiledModu
},
};
}
+
+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/runtime/agent/resolve-model.ts b/packages/eve/src/runtime/agent/resolve-model.ts
index e013b6ecf..148119e31 100644
--- a/packages/eve/src/runtime/agent/resolve-model.ts
+++ b/packages/eve/src/runtime/agent/resolve-model.ts
@@ -1,6 +1,9 @@
import type { LanguageModel } from "ai";
import type { CompiledModuleMap } from "#compiler/module-map.js";
+import type { ContextAccessor } from "#context/key.js";
+import { RuntimeModelMetadataCacheKey, type CachedModelMetadata } from "#context/keys.js";
import { normalizeAgentDefinition } from "#internal/authored-definition/core.js";
+import { normalizeCatalogModelId } from "#internal/model-catalog.js";
import { formatLanguageModelGatewayId } from "#internal/runtime-model.js";
import type {
RuntimeDynamicModelReference,
@@ -21,6 +24,11 @@ import {
type PublicAgentStaticModelDefinition,
} from "#shared/agent-definition.js";
import { parseJsonObject, type JsonObject } from "#shared/json.js";
+import {
+ createRuntimeModelCatalog,
+ type RuntimeModelCatalog,
+ type RuntimeModelMetadata,
+} from "#runtime/agent/model-catalog.js";
export { shouldMockAuthoredRuntimeModels };
@@ -93,7 +101,9 @@ async function loadSourceBackedRuntimeModelReference(
}
if (isDynamicModelDefinition(model)) {
- return model.fallback;
+ throw new Error(
+ `Expected the authored agent config export "${reference.source.exportName ?? "default"}" from "${reference.source.logicalPath}" to provide a static runtime model.`,
+ );
}
return model;
@@ -132,42 +142,136 @@ export async function loadDynamicRuntimeModelDefinition(input: {
return authoredModel;
}
-export function normalizeDynamicRuntimeModelResult(input: {
- readonly fallback: RuntimeModelReference;
- readonly result: NonNullable<PublicAgentDynamicModelResult>;
-}): ResolvedRuntimeModelSelection {
- const selection = normalizeDynamicModelSelection(input.result);
+export async function resolveRuntimeModelSelection(input: {
+ readonly catalog?: RuntimeModelCatalog;
+ readonly durability: "durable" | "live";
+ readonly selection: PublicAgentDynamicModelResult;
+ readonly state: ContextAccessor;
+}): Promise<ResolvedRuntimeModelSelection> {
+ if (input.selection === null || input.selection === undefined) {
+ throw new Error(
+ "Dynamic model resolver returned no model. Every matching dynamic model handler must return a concrete model selection.",
+ );
+ }
+
+ const selection = normalizeDynamicModelSelection(input.selection);
validateDynamicModelSelection(selection);
const providerOptions =
selection.modelOptions?.providerOptions === undefined
- ? input.fallback.providerOptions
+ ? undefined
: 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);
+ const selectedModel = selection.model;
+ const catalog = input.catalog ?? runtimeModelCatalogForState(input.state);
+ if (typeof selectedModel === "string") {
+ const id = formatLanguageModelGatewayId(selectedModel);
+ const metadata = await resolveSelectionMetadata({
+ cacheKey: `gateway:${normalizeCatalogModelId(id)}`,
+ catalog,
+ contextWindowTokens: selection.modelContextWindowTokens,
+ load: (catalog) => catalog.getByGatewayId(id),
+ modelLabel: id,
+ state: input.state,
+ });
return {
reference: {
- id,
- contextWindowTokens,
+ id: metadata.resolvedModelId,
+ contextWindowTokens: metadata.contextWindowTokens,
+ maxOutputTokens: metadata.maxOutputTokens,
providerOptions,
},
};
}
- validateRuntimeLanguageModel(selection.model);
+ validateRuntimeLanguageModel(selectedModel);
+ if (input.durability === "durable") {
+ throw new Error(
+ 'Dynamic model selection returned a provider object, but durable model selections must be serializable. Return a model id string, or use a "step.started" model resolver.',
+ );
+ }
+
+ const formattedId = formatLanguageModelGatewayId(selectedModel);
+ const topLevelProvider = selectedModel.provider.split(".")[0]!;
+ const metadata = await resolveSelectionMetadata({
+ cacheKey:
+ topLevelProvider === "gateway"
+ ? `gateway:${normalizeCatalogModelId(selectedModel.modelId)}`
+ : `provider:${selectedModel.provider}:${normalizeCatalogModelId(selectedModel.modelId)}`,
+ catalog,
+ contextWindowTokens: selection.modelContextWindowTokens,
+ load: (catalog) =>
+ topLevelProvider === "gateway"
+ ? catalog.getByGatewayId(selectedModel.modelId)
+ : catalog.getByProviderModelId(selectedModel.provider, selectedModel.modelId),
+ modelLabel: formattedId,
+ state: input.state,
+ });
return {
- model: selection.model,
+ model: selectedModel,
reference: {
- id: formatLanguageModelGatewayId(selection.model),
- contextWindowTokens,
+ id: metadata.resolvedModelId,
+ contextWindowTokens: metadata.contextWindowTokens,
+ maxOutputTokens: metadata.maxOutputTokens,
providerOptions,
},
};
}
+const runtimeModelCatalogsByState = new WeakMap<ContextAccessor, RuntimeModelCatalog>();
+
+function runtimeModelCatalogForState(state: ContextAccessor): RuntimeModelCatalog {
+ const existing = runtimeModelCatalogsByState.get(state);
+ if (existing !== undefined) return existing;
+
+ const catalog = createRuntimeModelCatalog();
+ runtimeModelCatalogsByState.set(state, catalog);
+ return catalog;
+}
+
+const RUNTIME_MODEL_METADATA_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+async function resolveSelectionMetadata(input: {
+ readonly cacheKey: string;
+ readonly catalog: RuntimeModelCatalog;
+ readonly contextWindowTokens?: number;
+ readonly load: (catalog: RuntimeModelCatalog) => Promise<RuntimeModelMetadata | null>;
+ readonly modelLabel: string;
+ readonly state: ContextAccessor;
+}): Promise<RuntimeModelMetadata> {
+ if (input.contextWindowTokens !== undefined) {
+ return {
+ contextWindowTokens: input.contextWindowTokens,
+ resolvedModelId: input.modelLabel,
+ };
+ }
+
+ const now = Date.now();
+ const cached = input.state.get(RuntimeModelMetadataCacheKey)?.[input.cacheKey];
+ if (cached !== undefined && cached.expiresAt > now) {
+ return cached;
+ }
+
+ const resolved = await input.load(input.catalog);
+ if (resolved === null) {
+ throw new Error(
+ `Cannot select model "${input.modelLabel}" because AI Gateway did not provide context window metadata. Return modelContextWindowTokens with this selection for an unlisted or custom model.`,
+ );
+ }
+
+ const entry: CachedModelMetadata = {
+ ...resolved,
+ expiresAt: now + RUNTIME_MODEL_METADATA_CACHE_TTL_MS,
+ };
+ input.state.set(RuntimeModelMetadataCacheKey, (current) => ({
+ ...Object.fromEntries(
+ Object.entries(current ?? {}).filter(([, value]) => value.expiresAt > now),
+ ),
+ [input.cacheKey]: entry,
+ }));
+ return entry;
+}
+
const DYNAMIC_MODEL_SELECTION_KEYS = new Set(["model", "modelContextWindowTokens", "modelOptions"]);
function validateDynamicModelSelection(selection: PublicAgentModelSelectionDefinition): void {
@@ -189,6 +293,10 @@ function validateDynamicModelSelection(selection: PublicAgentModelSelectionDefin
"Dynamic model resolver returned an invalid modelContextWindowTokens value. Expected a positive integer.",
);
}
+
+ if (typeof selection.model === "string" && selection.model.trim() === "") {
+ throw new Error("Dynamic model resolver returned an empty model id.");
+ }
}
function normalizeDynamicModelSelection(
diff --git a/packages/eve/src/runtime/resolve-agent-graph.ts b/packages/eve/src/runtime/resolve-agent-graph.ts
index ab0858cd7..3b7808ab8 100644
--- a/packages/eve/src/runtime/resolve-agent-graph.ts
+++ b/packages/eve/src/runtime/resolve-agent-graph.ts
@@ -1,6 +1,7 @@
import type {
CompiledAgentManifest,
CompiledAgentNodeManifest,
+ CompiledAgentResources,
CompiledRemoteAgentNode,
CompiledSubagentNode,
} from "#compiler/manifest.js";
@@ -108,7 +109,8 @@ export async function resolveRuntimeAgentGraph(
interface ResolveRuntimeAgentNodeInput {
readonly childNodeIdsByParentNodeId: ReadonlyMap<string, readonly string[]>;
- readonly manifest: CompiledAgentNodeManifest;
+ readonly agentId?: string;
+ readonly manifest: CompiledAgentNodeManifest | CompiledAgentResources;
readonly moduleMap: CompiledModuleMap;
readonly nodeId: string;
readonly nodesByNodeId: Map<string, ResolvedAgentGraphBundle["root"]>;
@@ -215,7 +217,7 @@ async function resolveRuntimeAgentNode(
workspaceResourceRoot: agent.workspaceResourceRoot,
});
const subagentRegistry = createRuntimeSubagentRegistry({
- persistentSessions: agent.config.experimental?.subagentPersistentSessions === true,
+ persistentSessions: agent.config?.experimental?.subagentPersistentSessions === true,
reservedToolNames: [
LOAD_SKILL_TOOL_NAME,
...toolRegistry.preparedTools.map((tool) => tool.name),
@@ -245,6 +247,7 @@ async function resolveRuntimeAgentNode(
toolRegistry,
turnAgent: createResolvedRuntimeTurnAgent({
agent: resolvedAgent,
+ id: input.agentId,
nodeId,
tools: [...toolRegistry.preparedTools, ...subagentRegistry.preparedTools],
}),
@@ -257,7 +260,7 @@ async function resolveRuntimeAgentNode(
async function resolveRuntimeSubagents(input: {
readonly childNodeIdsByParentNodeId: ReadonlyMap<string, readonly string[]>;
- readonly manifest: CompiledAgentNodeManifest;
+ readonly manifest: CompiledAgentNodeManifest | CompiledAgentResources;
readonly moduleMap: CompiledModuleMap;
readonly nodesByNodeId: Map<string, ResolvedAgentGraphBundle["root"]>;
readonly parentNodeId: string;
@@ -310,27 +313,14 @@ async function resolveRuntimeSubagent(input: {
readonly sourceRef: CompiledSubagentNode;
readonly subagentNodesById: ReadonlyMap<string, CompiledSubagentNode>;
}): Promise<ResolvedRuntimeSubagentNode> {
- const dynamicSource = input.sourceRef.agent.config.source;
- if (input.sourceRef.dynamic !== undefined && dynamicSource === undefined) {
- throw new ResolveRuntimeAgentGraphError(
- `Dynamic subagent "${input.sourceRef.logicalPath}" is missing its agent config source.`,
- {
- nodeId: toRuntimeNodeId(input.sourceRef.nodeId),
- sourceId: input.sourceRef.sourceId,
- },
- );
- }
const variant:
| { readonly description: string; readonly dynamic?: never }
| { readonly description?: never; readonly dynamic: ResolvedDynamicSubagentDefinition } =
- input.sourceRef.dynamic === undefined
+ input.sourceRef.configResolver === undefined
? { description: input.sourceRef.description }
: {
dynamic: await resolveDynamicSubagentDefinition({
- definition: {
- ...dynamicSource!,
- ...input.sourceRef.dynamic,
- },
+ definition: input.sourceRef.configResolver,
moduleMap: input.moduleMap,
nodeId: input.sourceRef.nodeId,
}),
@@ -345,6 +335,7 @@ async function resolveRuntimeSubagent(input: {
sourceKind: "module",
};
await resolveRuntimeAgentNode({
+ agentId: input.sourceRef.name,
childNodeIdsByParentNodeId: input.childNodeIdsByParentNodeId,
manifest: input.sourceRef.agent,
moduleMap: input.moduleMap,
diff --git a/packages/eve/src/runtime/resolve-agent.ts b/packages/eve/src/runtime/resolve-agent.ts
index 65ebf719e..dae3eaf2e 100644
--- a/packages/eve/src/runtime/resolve-agent.ts
+++ b/packages/eve/src/runtime/resolve-agent.ts
@@ -1,5 +1,6 @@
import type {
CompiledAgentNodeManifest,
+ CompiledAgentResources,
CompiledInstructionsDefinition,
} from "#compiler/manifest.js";
import type { CompiledModuleMap } from "#compiler/module-map.js";
@@ -29,7 +30,7 @@ import type {
* Input for resolving one compiled authored agent into a runtime-owned model.
*/
export interface ResolveAgentInput {
- manifest: CompiledAgentNodeManifest;
+ manifest: CompiledAgentNodeManifest | CompiledAgentResources;
moduleMap: CompiledModuleMap;
nodeId?: string;
}
@@ -103,7 +104,6 @@ export async function resolveAgent(input: ResolveAgentInput): Promise<ResolvedAg
const workspaceResourceRoot = input.manifest.workspaceResourceRoot;
const resolvedAgent: ResolvedAgent = {
channels: resolvedChannels,
- config: createResolvedAgentConfig(input.manifest),
connections: resolvedConnections,
disabledFrameworkChannels,
disabledFrameworkTools: [...input.manifest.disabledFrameworkTools],
@@ -128,11 +128,11 @@ export async function resolveAgent(input: ResolveAgentInput): Promise<ResolvedAg
workspaceSpec: { rootEntries: [...workspaceResourceRoot.rootEntries] },
};
- if (instructions !== undefined) {
- return { ...resolvedAgent, instructions };
- }
-
- return resolvedAgent;
+ const withInstructions =
+ instructions === undefined ? resolvedAgent : { ...resolvedAgent, instructions };
+ return "config" in input.manifest
+ ? { ...withInstructions, config: createResolvedAgentConfig(input.manifest) }
+ : withInstructions;
}
function createResolvedInstructionsDefinition(
@@ -151,42 +151,24 @@ function createResolvedInstructionsDefinition(
};
}
-function createResolvedAgentConfig(manifest: CompiledAgentNodeManifest): ResolvedAgent["config"] {
+function createResolvedAgentConfig(
+ manifest: CompiledAgentNodeManifest,
+): NonNullable<ResolvedAgent["config"]> {
const config: {
- compaction?: ResolvedAgent["config"]["compaction"];
- dynamicModel?: ResolvedAgent["config"]["dynamicModel"];
- experimental?: ResolvedAgent["config"]["experimental"];
- model: ResolvedAgent["config"]["model"];
+ compaction?: NonNullable<ResolvedAgent["config"]>["compaction"];
+ experimental?: NonNullable<ResolvedAgent["config"]>["experimental"];
name: string;
- outputSchema?: ResolvedAgent["config"]["outputSchema"];
- reasoning?: ResolvedAgent["config"]["reasoning"];
- source?: ResolvedAgent["config"]["source"];
- limits?: ResolvedAgent["config"]["limits"];
+ outputSchema?: NonNullable<ResolvedAgent["config"]>["outputSchema"];
+ reasoning?: NonNullable<ResolvedAgent["config"]>["reasoning"];
+ source?: NonNullable<ResolvedAgent["config"]>["source"];
+ limits?: NonNullable<ResolvedAgent["config"]>["limits"];
} = {
- model:
- manifest.config.model.source === undefined
- ? {
- id: manifest.config.model.id,
- contextWindowTokens: manifest.config.model.contextWindowTokens,
- providerOptions: manifest.config.model.providerOptions,
- }
- : {
- contextWindowTokens: manifest.config.model.contextWindowTokens,
- id: manifest.config.model.id,
- providerOptions: manifest.config.model.providerOptions,
- source: {
- exportName: manifest.config.model.source.exportName,
- sourceKind: "module" as const,
- logicalPath: manifest.config.model.source.logicalPath,
- sourceId: manifest.config.model.source.sourceId,
- },
- },
name: manifest.config.name,
};
if (manifest.config.compaction !== undefined) {
const compaction: {
- model?: ResolvedAgent["config"]["model"];
+ model?: NonNullable<NonNullable<ResolvedAgent["config"]>["compaction"]>["model"];
thresholdPercent?: number;
} = {};
@@ -196,11 +178,13 @@ function createResolvedAgentConfig(manifest: CompiledAgentNodeManifest): Resolve
? {
contextWindowTokens: manifest.config.compaction.model.contextWindowTokens,
id: manifest.config.compaction.model.id,
+ maxOutputTokens: manifest.config.compaction.model.maxOutputTokens,
providerOptions: manifest.config.compaction.model.providerOptions,
}
: {
contextWindowTokens: manifest.config.compaction.model.contextWindowTokens,
id: manifest.config.compaction.model.id,
+ maxOutputTokens: manifest.config.compaction.model.maxOutputTokens,
providerOptions: manifest.config.compaction.model.providerOptions,
source: {
exportName: manifest.config.compaction.model.source.exportName,
@@ -218,13 +202,6 @@ function createResolvedAgentConfig(manifest: CompiledAgentNodeManifest): Resolve
config.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 = {
subagentPersistentSessions: manifest.config.experimental.subagentPersistentSessions,
@@ -255,5 +232,38 @@ function createResolvedAgentConfig(manifest: CompiledAgentNodeManifest): Resolve
};
}
- return config;
+ if (manifest.config.dynamicModel !== undefined) {
+ return {
+ ...config,
+ dynamicModel: {
+ ...createResolvedModuleSourceRef(manifest.config.dynamicModel),
+ eventNames: [...manifest.config.dynamicModel.eventNames],
+ },
+ };
+ }
+
+ const model = manifest.config.model;
+ return {
+ ...config,
+ model:
+ model.source === undefined
+ ? {
+ id: model.id,
+ contextWindowTokens: model.contextWindowTokens,
+ maxOutputTokens: model.maxOutputTokens,
+ providerOptions: model.providerOptions,
+ }
+ : {
+ contextWindowTokens: model.contextWindowTokens,
+ id: model.id,
+ maxOutputTokens: model.maxOutputTokens,
+ providerOptions: model.providerOptions,
+ source: {
+ exportName: model.source.exportName,
+ sourceKind: "module" as const,
+ logicalPath: model.source.logicalPath,
+ sourceId: model.source.sourceId,
+ },
+ },
+ };
}
diff --git a/packages/eve/src/runtime/resolve-dynamic-subagent.ts b/packages/eve/src/runtime/resolve-dynamic-subagent.ts
index 463175cc7..b06b9a782 100644
--- a/packages/eve/src/runtime/resolve-dynamic-subagent.ts
+++ b/packages/eve/src/runtime/resolve-dynamic-subagent.ts
@@ -8,12 +8,9 @@ import {
import { loadResolvedModuleExport, ResolveAgentError } from "#runtime/resolve-helpers.js";
import type { ResolvedDynamicSubagentDefinition } from "#runtime/types.js";
import { toErrorMessage } from "#shared/errors.js";
-import type { ModuleSourceRef } from "#shared/source-ref.js";
-
-type DynamicSubagentSource = ModuleSourceRef & CompiledDynamicSubagentDefinition;
export async function resolveDynamicSubagentDefinition(input: {
- readonly definition: DynamicSubagentSource;
+ readonly definition: CompiledDynamicSubagentDefinition;
readonly moduleMap: CompiledModuleMap;
readonly nodeId: string;
}): Promise<ResolvedDynamicSubagentDefinition> {
@@ -41,7 +38,7 @@ export async function resolveDynamicSubagentDefinition(input: {
}
export function normalizeResolvedDynamicSubagentDefinition(
- definition: DynamicSubagentSource,
+ definition: CompiledDynamicSubagentDefinition,
value: unknown,
): ResolvedDynamicSubagentDefinition {
const message = `Expected the dynamic subagent export "${definition.exportName ?? "default"}" from "${definition.logicalPath}" to provide defineDynamic({ events }).`;
diff --git a/packages/eve/src/runtime/subagents/dynamic-agent-config.ts b/packages/eve/src/runtime/subagents/dynamic-agent-config.ts
index 8ba4f8558..768a5a532 100644
--- a/packages/eve/src/runtime/subagents/dynamic-agent-config.ts
+++ b/packages/eve/src/runtime/subagents/dynamic-agent-config.ts
@@ -1,12 +1,14 @@
import { normalizeAgentDefinition } from "#internal/authored-definition/core.js";
-import { formatLanguageModelGatewayId } from "#internal/runtime-model.js";
+import type { ContextAccessor } from "#context/key.js";
+import type { RuntimeModelReference } from "#runtime/agent/bootstrap.js";
+import { resolveRuntimeModelSelection } from "#runtime/agent/resolve-model.js";
+import type { RuntimeModelCatalog } from "#runtime/agent/model-catalog.js";
import {
isDynamicModelDefinition,
type AgentLimitsDefinition,
type AgentReasoningDefinition,
- type PublicAgentStaticModelDefinition,
} from "#shared/agent-definition.js";
-import { parseJsonObject, type JsonObject } from "#shared/json.js";
+import type { JsonObject } from "#shared/json.js";
import { serializeOutputSchema } from "#shared/tool-schema.js";
export interface DynamicSubagentAgentConfig {
@@ -21,16 +23,14 @@ export interface DynamicSubagentAgentConfig {
readonly reasoning?: AgentReasoningDefinition;
}
-export interface DynamicSubagentModelReference {
- readonly contextWindowTokens?: number;
- readonly id: string;
- readonly providerOptions?: Record<string, JsonObject>;
-}
+export type DynamicSubagentModelReference = RuntimeModelReference;
-export function normalizeDynamicSubagentAgentConfig(input: {
+export async function normalizeDynamicSubagentAgentConfig(input: {
+ readonly catalog?: RuntimeModelCatalog;
readonly name: string;
+ readonly state: ContextAccessor;
readonly value: unknown;
-}): DynamicSubagentAgentConfig {
+}): Promise<DynamicSubagentAgentConfig> {
const message = `Dynamic subagent "${input.name}" must return defineAgent(...), defineRemoteAgent(...), or null.`;
const definition = normalizeAgentDefinition(input.value, message);
@@ -56,11 +56,14 @@ export function normalizeDynamicSubagentAgentConfig(input: {
reasoning?: AgentReasoningDefinition;
} = {
description: definition.description,
- model: normalizeModelReference({
- contextWindowTokens: definition.modelContextWindowTokens,
- model: definition.model,
- name: input.name,
- providerOptions: definition.modelOptions?.providerOptions,
+ model: await normalizeDurableModelSelection({
+ catalog: input.catalog,
+ selection: {
+ model: definition.model,
+ modelContextWindowTokens: definition.modelContextWindowTokens,
+ modelOptions: definition.modelOptions,
+ },
+ state: input.state,
}),
};
@@ -70,11 +73,14 @@ export function normalizeDynamicSubagentAgentConfig(input: {
thresholdPercent?: number;
} = {};
if (definition.compaction.model !== undefined) {
- compaction.model = normalizeModelReference({
- contextWindowTokens: definition.compaction.modelContextWindowTokens,
- model: definition.compaction.model,
- name: input.name,
- providerOptions: definition.modelOptions?.providerOptions,
+ compaction.model = await normalizeDurableModelSelection({
+ catalog: input.catalog,
+ selection: {
+ model: definition.compaction.model,
+ modelContextWindowTokens: definition.compaction.modelContextWindowTokens,
+ modelOptions: definition.modelOptions,
+ },
+ state: input.state,
});
}
if (definition.compaction.thresholdPercent !== undefined) {
@@ -95,33 +101,16 @@ export function normalizeDynamicSubagentAgentConfig(input: {
return config;
}
-function normalizeModelReference(input: {
- readonly contextWindowTokens?: number;
- readonly model: PublicAgentStaticModelDefinition;
- readonly name: string;
- readonly providerOptions?: Record<string, JsonObject>;
-}): DynamicSubagentModelReference {
- if (typeof input.model !== "string") {
- throw new Error(
- `Dynamic subagent "${input.name}" must return model IDs as strings so its agent config can cross durable workflow boundaries.`,
- );
- }
-
- const reference: {
- contextWindowTokens?: number;
- id: string;
- providerOptions?: Record<string, JsonObject>;
- } = { id: formatLanguageModelGatewayId(input.model) };
- if (input.contextWindowTokens !== undefined) {
- reference.contextWindowTokens = input.contextWindowTokens;
- }
- if (input.providerOptions !== undefined) {
- reference.providerOptions = Object.fromEntries(
- Object.entries(input.providerOptions).map(([provider, options]) => [
- provider,
- parseJsonObject(options),
- ]),
- );
- }
- return reference;
+async function normalizeDurableModelSelection(input: {
+ readonly catalog?: RuntimeModelCatalog;
+ readonly selection: Parameters<typeof resolveRuntimeModelSelection>[0]["selection"];
+ readonly state: ContextAccessor;
+}): Promise<DynamicSubagentModelReference> {
+ const resolved = await resolveRuntimeModelSelection({
+ catalog: input.catalog,
+ durability: "durable",
+ selection: input.selection,
+ state: input.state,
+ });
+ return resolved.reference;
}
diff --git a/packages/eve/src/runtime/types.ts b/packages/eve/src/runtime/types.ts
index a7e141040..8550b07da 100644
--- a/packages/eve/src/runtime/types.ts
+++ b/packages/eve/src/runtime/types.ts
@@ -322,11 +322,22 @@ export interface ResolvedDynamicSubagentDefinition extends Readonly<ModuleSource
/**
* Runtime-owned additive agent configuration resolved from `agent.ts`.
*/
+type ResolvedAgentDefinitionBase = Omit<InternalAgentDefinition, "build" | "model" | "source"> & {
+ source?: Readonly<NonNullable<InternalAgentDefinition["source"]>>;
+};
+
export type ResolvedAgentDefinition = Readonly<
- Omit<InternalAgentDefinition, "build" | "source"> & {
- dynamicModel?: RuntimeDynamicModelReference;
- source?: Readonly<NonNullable<InternalAgentDefinition["source"]>>;
- }
+ ResolvedAgentDefinitionBase &
+ (
+ | {
+ dynamicModel?: never;
+ model: InternalAgentDefinition["model"];
+ }
+ | {
+ dynamicModel: RuntimeDynamicModelReference;
+ model?: never;
+ }
+ )
>;
/**
@@ -391,7 +402,7 @@ export interface ResolvedDynamicInstructionsResolver extends Readonly<ModuleSour
*/
export interface ResolvedAgent {
readonly channels: readonly ResolvedChannelDefinition[];
- readonly config: ResolvedAgentDefinition;
+ readonly config?: ResolvedAgentDefinition;
readonly connections: readonly ResolvedConnectionDefinition[];
/**
* Logical names of framework-provided channels the author opted out of by
diff --git a/packages/eve/src/services/dev-client/agent-info-probe.test.ts b/packages/eve/src/services/dev-client/agent-info-probe.test.ts
index 1db0dc95c..85339b9dd 100644
--- a/packages/eve/src/services/dev-client/agent-info-probe.test.ts
+++ b/packages/eve/src/services/dev-client/agent-info-probe.test.ts
@@ -13,7 +13,7 @@ const AGENT_INFO = {
agent: {
agentRoot: "/tmp/weather-agent/agent",
appRoot: "/tmp/weather-agent",
- model: { id: "gpt-5" },
+ model: { id: "gpt-5", routing: { kind: "gateway", target: "openai" } },
name: "Weather Agent",
},
capabilities: { devRoutes: true },
diff --git a/packages/eve/src/shared/agent-definition.ts b/packages/eve/src/shared/agent-definition.ts
index e79311fb7..a42a5c941 100644
--- a/packages/eve/src/shared/agent-definition.ts
+++ b/packages/eve/src/shared/agent-definition.ts
@@ -46,6 +46,7 @@ export type ModelRouting =
export type InternalAgentModelDefinition = {
id: string;
contextWindowTokens?: number;
+ maxOutputTokens?: number;
source?: ModuleSourceRef;
providerOptions?: Record<string, JsonObject>;
};
@@ -61,37 +62,31 @@ export type AgentModelResolveContext = DynamicResolveContext;
export interface PublicAgentModelSelectionDefinition {
readonly model: PublicAgentStaticModelDefinition;
- /** Context window of the selected model, in tokens; never inherited from the fallback. */
+ /** Context window of the selected model, in tokens. */
readonly modelContextWindowTokens?: number;
- /** Provider options for the selected model; defaults to the agent-level `modelOptions`. */
+ /** Provider options for the selected model. */
readonly modelOptions?: AgentModelOptionsDefinition;
}
export type PublicAgentDynamicModelResult =
| PublicAgentStaticModelDefinition
- | PublicAgentModelSelectionDefinition
- | null;
+ | PublicAgentModelSelectionDefinition;
export type AgentModelResolver = (
event: unknown,
ctx: AgentModelResolveContext,
) => PublicAgentDynamicModelResult | Promise<PublicAgentDynamicModelResult>;
-export type PublicAgentDynamicModelDefinition = DynamicSentinel<
- PublicAgentDynamicModelResult,
- PublicAgentStaticModelDefinition
->;
+export type PublicAgentDynamicModelDefinition = DynamicSentinel<PublicAgentDynamicModelResult>;
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;
+ return isDynamicSentinel(value);
}
/**
@@ -273,7 +268,7 @@ export type InternalAgentDefinition = {
* package name or app-root basename). Authored definitions do not carry
* a `name` field.
*/
-export type PublicAgentDefinition = {
+type PublicAgentDefinitionBase = {
/**
* Human-readable description of the agent's purpose. Required for
* subagents (authored under `subagents/<id>/agent.ts`): surfaced to
@@ -287,22 +282,6 @@ export type PublicAgentDefinition = {
* {@link AgentExperimentalDefinition}.
*/
readonly experimental?: AgentExperimentalDefinition;
- /**
- * 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;
- /**
- * Optional override for the primary model's context window size, in tokens.
- *
- * Escape hatch for cases where eve cannot resolve the model's metadata via
- * the AI Gateway model catalog (e.g. a custom or unlisted model id). When
- * set, eve uses this value verbatim and skips the AI Gateway lookup. Prefer
- * leaving this unset so eve can stay in sync with provider metadata.
- */
- readonly modelContextWindowTokens?: number;
- readonly modelOptions?: AgentModelOptionsDefinition;
/**
* Provider-agnostic reasoning effort for the agent's turn model calls.
* Support for individual levels depends on the selected model and provider.
@@ -320,3 +299,24 @@ export type PublicAgentDefinition = {
*/
readonly outputSchema?: StandardJSONSchemaV1<unknown, unknown> | JsonObject;
};
+
+/**
+ * Shared public definition for an agent. Static models may carry definition-level
+ * metadata; dynamic models must return metadata with each concrete selection.
+ */
+export type PublicAgentDefinition = PublicAgentDefinitionBase &
+ (
+ | {
+ /** Language model used for agent turns. */
+ readonly model: PublicAgentStaticModelDefinition;
+ /** Optional context-window override for the static model. */
+ readonly modelContextWindowTokens?: number;
+ readonly modelOptions?: AgentModelOptionsDefinition;
+ }
+ | {
+ /** Resolver that must select a concrete model before model-dependent work. */
+ readonly model: PublicAgentDynamicModelDefinition;
+ readonly modelContextWindowTokens?: never;
+ readonly modelOptions?: never;
+ }
+ );
diff --git a/packages/eve/src/shared/dynamic-tool-definition.ts b/packages/eve/src/shared/dynamic-tool-definition.ts
index 2540615d9..978e1300b 100644
--- a/packages/eve/src/shared/dynamic-tool-definition.ts
+++ b/packages/eve/src/shared/dynamic-tool-definition.ts
@@ -142,13 +142,6 @@ export type DynamicEvents<TResult = unknown> = {
) => TResult | Promise<TResult>;
};
-export type DynamicEventsWithFallback<TResult = unknown> = {
- readonly [K in DynamicToolEventName]?: (
- event: unknown,
- ctx: DynamicResolveContext,
- ) => Exclude<TResult, undefined> | Promise<Exclude<TResult, undefined>>;
-};
-
/**
* Marker discriminator for a `defineDynamic({ events })` export.
*/
@@ -156,21 +149,21 @@ export const DYNAMIC_SENTINEL_KIND = "eve:dynamic" as const;
/**
* Return value of `defineDynamic`: the runtime shape of a dynamic export,
- * stamped with a sentinel kind the compiler/normalizer detects. `TFallback`
- * is used by dynamic agent models.
+ * stamped with a sentinel kind the compiler/normalizer detects.
*/
-export type DynamicSentinel<TResult = unknown, TFallback = never> = {
+export type DynamicSentinel<TResult = unknown> = {
readonly kind: typeof DYNAMIC_SENTINEL_KIND;
readonly events: DynamicEvents<TResult>;
-} & ([TFallback] extends [never] ? object : { readonly fallback: TFallback });
+};
-export function rejectDynamicSentinelFallback(sentinel: DynamicSentinel, message: string): void {
- if (!("fallback" in sentinel)) {
- return;
+export function assertResolverOnlyDynamicSentinel(
+ sentinel: DynamicSentinel,
+ message: string,
+): void {
+ const unknownKeys = Object.keys(sentinel).filter((key) => key !== "events" && key !== "kind");
+ if (unknownKeys.length > 0) {
+ throw new Error(`${message} Unknown key(s): ${unknownKeys.join(", ")}.`);
}
- throw new Error(
- `${message} "fallback" is only supported on a dynamic agent model. For dynamic tools, skills, instructions, and subagents, return null when the capability should be omitted.`,
- );
}
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.ts
index c12850296..26b2858f1 100644
--- a/packages/eve/src/source-change/apply-model-name.test.ts
+++ b/packages/eve/src/source-change/apply-model-name.test.ts
@@ -89,14 +89,13 @@ describe("applyModelNameToSource", () => {
expect(result.kind).toBe("bail");
});
- it("bails on a defineDynamic model without touching the fallback literal", async () => {
+ it("bails on a defineDynamic model without touching resolver selections", 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",
+ "session.started": () => "anthropic/claude-sonnet-5",
},
}),
});
@@ -105,7 +104,6 @@ export default defineAgent({
expect(result.kind).toBe("bail");
if (result.kind !== "bail") return;
- // The fallback string inside defineDynamic must never be rewritten.
expect(result.reason).toContain("defineDynamic");
});
diff --git a/packages/eve/test/client.test.ts b/packages/eve/test/client.test.ts
index 5a3af7530..0b0e0a5f2 100644
--- a/packages/eve/test/client.test.ts
+++ b/packages/eve/test/client.test.ts
@@ -235,6 +235,7 @@ describe("Client.info", () => {
appRoot: "/tmp/weather-agent",
model: {
id: "gpt-5",
+ routing: { kind: "gateway", target: "openai" },
},
name: "Weather Agent",
},
diff --git a/packages/eve/test/resolve-agent.test.ts b/packages/eve/test/resolve-agent.test.ts
index 36e86539f..974073b59 100644
--- a/packages/eve/test/resolve-agent.test.ts
+++ b/packages/eve/test/resolve-agent.test.ts
@@ -167,7 +167,7 @@ describe("resolveAgent", () => {
});
const [resolvedChannel] = resolved.channels;
- expect(resolved.config.name).toBe("weather-agent");
+ expect(resolved.config?.name).toBe("weather-agent");
expect(resolved.config).toEqual({
compaction: {},
model: {
@@ -376,7 +376,7 @@ describe("resolveAgent", () => {
},
});
- expect(resolved.config.name).toBe("weather-agent");
+ expect(resolved.config?.name).toBe("weather-agent");
expect(resolved.config).toEqual({
compaction: {},
model: {
@@ -454,7 +454,7 @@ describe("resolveAgent", () => {
},
});
- expect(resolved.config.model).toEqual({
+ expect(resolved.config?.model).toEqual({
id: "test-provider/weather-pro",
source: {
sourceKind: "module",
@@ -493,7 +493,7 @@ describe("resolveAgent", () => {
},
});
- expect(resolved.config.model).toEqual({
+ expect(resolved.config?.model).toEqual({
id: "anthropic/claude-opus-4.5-thinking",
providerOptions: {
anthropic: {
diff --git a/packages/eve/test/runtime-agent-graph.test.ts b/packages/eve/test/runtime-agent-graph.test.ts
index cdf06d668..20dff309c 100644
--- a/packages/eve/test/runtime-agent-graph.test.ts
+++ b/packages/eve/test/runtime-agent-graph.test.ts
@@ -1,5 +1,6 @@
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import {
+ createCompiledAgentResources,
createCompiledAgentManifest,
createCompiledAgentNodeManifest,
ROOT_COMPILED_AGENT_NODE_ID,
@@ -145,23 +146,16 @@ describe("resolveRuntimeAgentGraph", () => {
],
subagents: [
{
- agent: createCompiledAgentNodeManifest({
+ agent: createCompiledAgentResources({
agentRoot: "/app/agent/subagents/researcher",
appRoot: "/app",
- config: {
- model: {
- id: TEST_DEFAULT_MODEL_ID,
- routing: { kind: "gateway", target: "openai" },
- },
- name: "researcher",
- source: {
- logicalPath: "agent.ts",
- sourceId: "agent-config",
- sourceKind: "module",
- },
- },
}),
- dynamic: { eventNames: ["session.started"] },
+ configResolver: {
+ eventNames: ["session.started"],
+ logicalPath: "agent.ts",
+ sourceId: "agent.ts",
+ sourceKind: "module",
+ },
entryPath: "/app/agent/subagents/researcher/agent.ts",
logicalPath: "subagents/researcher",
name: "researcher",
@@ -180,7 +174,7 @@ describe("resolveRuntimeAgentGraph", () => {
[ROOT_COMPILED_AGENT_NODE_ID]: { modules: {} },
"subagents/researcher": {
modules: {
- "agent-config": { default: dynamic },
+ "agent.ts": { default: dynamic },
},
},
},
@@ -445,7 +439,7 @@ describe("resolveRuntimeAgentGraph", () => {
const researcherNode = graph.nodesByNodeId.get("subagents/researcher");
const reviewerNode = graph.nodesByNodeId.get("subagents/researcher::subagents/reviewer");
- expect(researcherNode?.agent.config.name).toBe("researcher");
+ expect(researcherNode?.agent.config?.name).toBe("researcher");
expect(researcherNode?.agent.instructions).toEqual({
name: "researcher-instructions",
logicalPath: "instructions.md",
diff --git a/packages/eve/test/scenarios/compile-agent.scenario.test.ts b/packages/eve/test/scenarios/compile-agent.scenario.test.ts
index a01a49622..5d8ade9ef 100644
--- a/packages/eve/test/scenarios/compile-agent.scenario.test.ts
+++ b/packages/eve/test/scenarios/compile-agent.scenario.test.ts
@@ -1045,7 +1045,9 @@ describe("compileAgent", () => {
expect(result.manifest.subagents[0]).toMatchObject({
sourceId: "subagents/researcher",
});
- expect(result.manifest.subagents[0]?.agent.config.name).toBe("researcher");
+ const researcher = result.manifest.subagents[0];
+ if (researcher?.configResolver !== undefined) throw new Error("expected a static subagent");
+ expect(researcher?.agent.config.name).toBe("researcher");
});
it("compiles remote subagents into the owning node manifest", async () => {
diff --git a/packages/eve/test/scenarios/load-agent-info-data.scenario.test.ts b/packages/eve/test/scenarios/load-agent-info-data.scenario.test.ts
index 9ba3c84e2..72add9295 100644
--- a/packages/eve/test/scenarios/load-agent-info-data.scenario.test.ts
+++ b/packages/eve/test/scenarios/load-agent-info-data.scenario.test.ts
@@ -71,7 +71,7 @@ describe("loadAgentInfoData", () => {
compiledArtifactsSource: agentInfoCompiledArtifactsSource,
});
- expect(data.agent.config.name).toBe(data.manifest.config.name);
+ expect(data.agent.config?.name).toBe(data.manifest.config.name);
expect(data.manifest.config.name).toBe(manifest.config.name);
expect(data.agent.sandbox).not.toBeNull();
expect(data.agent.sandbox?.sourceKind).toBe("module");
diff --git a/packages/eve/test/scenarios/runtime-loaders.scenario.test.ts b/packages/eve/test/scenarios/runtime-loaders.scenario.test.ts
index a1540b719..d82f8403a 100644
--- a/packages/eve/test/scenarios/runtime-loaders.scenario.test.ts
+++ b/packages/eve/test/scenarios/runtime-loaders.scenario.test.ts
@@ -353,6 +353,7 @@ describe("runtime compiled artifact loaders", () => {
model: {
contextWindowTokens: expect.any(Number),
id: "openai/gpt-5.4",
+ maxOutputTokens: 128_000,
routing: { kind: "gateway", target: "openai" },
},
name: "runtime-loader-test-agent",
diff --git a/packages/eve/test/scenarios/runtime-model-resolution.scenario.test.ts b/packages/eve/test/scenarios/runtime-model-resolution.scenario.test.ts
index 5e0d4f482..7ee49e570 100644
--- a/packages/eve/test/scenarios/runtime-model-resolution.scenario.test.ts
+++ b/packages/eve/test/scenarios/runtime-model-resolution.scenario.test.ts
@@ -110,6 +110,7 @@ describe("runtime model resolution", () => {
},
});
+ if (bundle.turnAgent.model === undefined) throw new Error("expected a static model");
const resolvedModel = await resolveRuntimeModelReference(bundle.turnAgent.model, {
moduleMap: bundle.moduleMap,
nodeId: bundle.nodeId,
@@ -173,6 +174,7 @@ describe("runtime model resolution", () => {
compiledArtifactsSource,
nodeId: "subagents/researcher",
});
+ if (childBundle.turnAgent.model === undefined) throw new Error("expected a static model");
const resolvedModel = await resolveRuntimeModelReference(childBundle.turnAgent.model, {
moduleMap: childBundle.moduleMap,
nodeId: childBundle.nodeId,
diff --git a/packages/eve/test/tui-client/lib/stream.ts b/packages/eve/test/tui-client/lib/stream.ts
index 9692841a5..d9fb901f8 100644
--- a/packages/eve/test/tui-client/lib/stream.ts
+++ b/packages/eve/test/tui-client/lib/stream.ts
@@ -26,9 +26,7 @@ export function printStreamEvent(event: MessageStreamEvent): void {
switch (event.type) {
case "session.started":
process.stdout.write(
- theme.muted(
- `[session.started] ${event.data.runtime?.agentName ?? "?"} · ${event.data.runtime?.modelId ?? "?"}\n`,
- ),
+ theme.muted(`[session.started] ${event.data.runtime?.agentName ?? "?"}\n`),
);
return;
@@ -117,6 +115,9 @@ export function printStreamEvent(event: MessageStreamEvent): void {
return;
case "step.started":
+ process.stdout.write(theme.muted(`[model ${event.data.modelId}]\n`));
+ return;
+
case "step.completed":
case "session.waiting":
case "session.completed":
diff --git a/packages/eve/test/tui-client/tui-connection-auth-states.ts b/packages/eve/test/tui-client/tui-connection-auth-states.ts
index 8a693c5be..03cf308db 100644
--- a/packages/eve/test/tui-client/tui-connection-auth-states.ts
+++ b/packages/eve/test/tui-client/tui-connection-auth-states.ts
@@ -98,7 +98,7 @@ const next = () => ++sequence;
const firstTurn: UnstampedMessageStreamEvent[] = [
{ type: "session.started", data: {} },
{ type: "turn.started", data: { sequence: next(), turnId } },
- { type: "step.started", data: { sequence: next(), stepIndex, turnId } },
+ { type: "step.started", data: { modelId: "eve-mock/test", sequence: next(), stepIndex, turnId } },
{
type: "authorization.required",
data: {
@@ -151,7 +151,10 @@ const firstCallbackTurn: UnstampedMessageStreamEvent[] = [
const secondTurnId = "turn-2";
const secondTurn: UnstampedMessageStreamEvent[] = [
{ type: "turn.started", data: { sequence: next(), turnId: secondTurnId } },
- { type: "step.started", data: { sequence: next(), stepIndex, turnId: secondTurnId } },
+ {
+ type: "step.started",
+ data: { modelId: "eve-mock/test", sequence: next(), stepIndex, turnId: secondTurnId },
+ },
{
type: "authorization.required",
data: {
diff --git a/research/dynamic-agent-configuration.md b/research/dynamic-agent-configuration.md
new file mode 100644
index 000000000..a8d15d89f
--- /dev/null
+++ b/research/dynamic-agent-configuration.md
@@ -0,0 +1,187 @@
+---
+issue: "1945"
+status: proposed
+last_updated: "2026-08-11"
+---
+
+# Dynamic agent configuration without fallbacks or placeholders
+
+## Decision
+
+Reimplement dynamic model and dynamic subagent configuration around one rule:
+the compiler stores either a concrete value or a resolver, never both.
+
+- `defineDynamic` is resolver-only: `defineDynamic({ events })`.
+- A dynamic model handler must return a concrete model selection. It cannot
+ return `null` or `undefined`, and it has no fallback.
+- Dynamic tools, skills, instructions, and subagents may return `null` to omit
+ a capability.
+- A dynamic model has no compiled model reference. The selected model becomes
+ concrete at runtime before model-dependent work begins.
+- A dynamic subagent has no compiled agent config or placeholder model. Its
+ filesystem resources compile independently, and its handler supplies the
+ concrete config before a child session starts.
+- Root dynamic models and dynamically selected subagent configs share runtime
+ model normalization and AI Gateway metadata lookup.
+
+`DEFAULT_AGENT_MODEL_ID` remains the product default used by `eve init`, the
+setup model picker, and agents with no `agent.ts`. It is not an internal
+placeholder. The bootstrap model remains limited to the framework-owned
+bootstrap runtime.
+
+## Authoring API
+
+The default choice belongs in the model handler:
+
+```ts
+import { defineAgent, defineDynamic } from "eve";
+
+export default defineAgent({
+ model: defineDynamic({
+ events: {
+ "step.started": (_event, ctx) => {
+ if (ctx.messages.some(isLargeContextRequest)) {
+ return "anthropic/claude-opus-4.1";
+ }
+
+ return "openai/gpt-5.5";
+ },
+ },
+ }),
+});
+```
+
+A dynamic model handler returns a model ID, a live AI SDK model, or
+`{ model, modelContextWindowTokens?, modelOptions? }`. Runtime validation still
+rejects `null`, `undefined`, malformed results, and unknown keys. When context
+metadata is omitted, eve resolves it from AI Gateway at selection time.
+Dynamic agents cannot set sibling `modelContextWindowTokens` or `modelOptions`
+fields because those would become implicit selection defaults.
+
+A dynamic subagent returns a concrete `defineAgent`, a concrete
+`defineRemoteAgent`, or `null`:
+
+```ts
+import { defineAgent, defineDynamic } from "eve";
+
+export default defineDynamic({
+ events: {
+ "turn.started": (_event, ctx) => {
+ if (!shouldOfferResearcher(ctx)) return null;
+
+ return defineAgent({
+ description: "Research the request.",
+ model: "openai/gpt-5.5",
+ });
+ },
+ },
+});
+```
+
+A returned local config must use a static model. Build-only configuration
+stays on the outer dynamic definition or another static compile input.
+
+## Compiled ownership
+
+Compiled root config and subagent nodes use mutually exclusive unions:
+
+```ts
+type CompiledAgentModelConfig =
+ | { readonly model: CompiledRuntimeModelReference; readonly dynamicModel?: never }
+ | { readonly model?: never; readonly dynamicModel: CompiledDynamicModelResolver };
+
+type CompiledSubagentNode = CompiledSubagentNodeBase &
+ (
+ | { readonly config: CompiledAgentConfig; readonly configResolver?: never }
+ | { readonly config?: never; readonly configResolver: CompiledDynamicSubagentResolver }
+ ) & {
+ readonly resources: CompiledAgentResources;
+ };
+```
+
+The exact manifest layout may remain flattened. Its TypeScript and Zod shapes
+must still enforce that filesystem resources compile independently from agent
+execution config. Dynamic nodes contain no `DEFAULT_AGENT_MODEL_ID`, synthetic
+`"dynamic"` model ID, bootstrap model, or hidden default.
+
+Inspection uses the same invariant: static model data contains an ID and
+static routing; unresolved dynamic model data contains only a dynamic routing
+discriminator.
+
+## Runtime resolution and caching
+
+One runtime-owned operation normalizes root model selections, selected local
+subagent models, and explicit compaction models in selected subagent configs.
+It validates live models, serializes provider options, normalizes provider IDs,
+and produces a serializable runtime reference with the resolved model ID and
+metadata.
+
+Successful runtime catalog metadata is cached in durable workflow state for 24
+hours. Gateway models are keyed by normalized gateway ID; provider models are
+keyed by provider and provider model ID. Writes remove expired entries. Failed
+requests and missing models are never cached, and transport or authentication
+failures remain distinct from a missing-model result. A full catalog response
+may remain execution-local, but only metadata for selected models is durable.
+
+Dynamic model scope precedence is:
+
+```text
+step selection > turn selection > session selection
+```
+
+Session and turn selections are durable and therefore accept only serializable
+model IDs. A step selection lasts for one model call and may carry a live
+provider object. The harness requires an active selection before compaction,
+prompt caching, model-dependent tool preparation, or a provider call.
+
+A selected dynamic subagent config is normalized and persisted before child
+dispatch. The child combines that config with compiled resources and does not
+repeat catalog lookup.
+
+## Events and failures
+
+Session identity and model-call identity are separate. `session.started`
+identifies the agent, eve version, deployment, and source revision. It does not
+invent a model for an unresolved dynamic agent. The concrete model ID is
+reported on the public `step.started` event after dynamic selection and before
+model-dependent work.
+
+- A dynamic model handler that returns `null` or `undefined` fails the turn.
+- A malformed selection fails before model-dependent work.
+- An unknown model without explicit context metadata produces an actionable
+ metadata error.
+- Catalog authentication and transport failures propagate and are not cached.
+- A dynamic subagent may return `null` to omit itself.
+- A dynamic subagent resolver exception or malformed selected config follows
+ the existing capability policy: log the failure and omit the subagent.
+
+## Compatibility and validation
+
+This is an intentional pre-1.0 breaking change. Remove the fallback overload,
+fallback generics, and fallback runtime guards. Bump the compiled manifest
+version. Publish new dynamic tool, skill, and instruction contract epochs while
+retaining older executable epochs. Bump and drop the affected hook epochs when
+model identity moves from session runtime metadata to step attribution. Add a
+minor changeset.
+
+Coverage must include public type rejection, exact unions and schemas, scope
+precedence, durable live-object rejection, shared normalization, metadata-cache
+hits and expiry, provider aliases, request errors without negative caching,
+placeholder-free manifests, dynamic subagent resource compilation, inspection
+output, subprocess build/boot coverage, deterministic failure behavior, and
+real-model catalog resolution and reuse.
+
+## Invariants
+
+- A model ID always names a concrete provider model.
+- `"dynamic"` is a discriminator, never a model ID.
+- A dynamic model has no reference until a handler selects one.
+- A dynamic local subagent has no execution config until a handler selects one.
+- `DEFAULT_AGENT_MODEL_ID` is a product default, not a compiler escape hatch.
+- Every model call has one normalized concrete model reference before any
+ model-dependent work.
+- Runtime-derived metadata is durable, serializable, TTL-bounded, and cached
+ only after successful lookup.
+- TypeScript and runtime schemas enforce identical static and dynamic variants.
+- Missing selections, resolver failures, stale manifests, and inspection
+ surfaces contain no hidden fallback behavior.