eve 0.21.1 → 0.22.0

package/dist/src/shared/agent-definition.d.ts

@@ -2,6 +2,7 @@ import type { CallSettings, LanguageModel } from "ai";
 import type { StandardJSONSchemaV1 } from "#compiled/@standard-schema/spec/index.js";
 import type { JsonObject } from "#shared/json.js";
 import type { ModuleSourceRef } from "#shared/source-ref.js";
+import { type DynamicResolveContext, type DynamicSentinel } from "#shared/dynamic-tool-definition.js";
 /**
  * Optional overrides that eve forwards to the AI SDK model runtime call for
  * this model.
@@ -46,11 +47,32 @@ export type InternalAgentModelDefinition = {
     providerOptions?: Record<string, JsonObject>;
 };
 /**
- * The model handle you assign to an agent's `model` field. This is the AI SDK
- * `LanguageModel` value (for example, the result of a provider or gateway
- * model call), not an eve-authored definition object.
+ * A concrete model handle: an AI Gateway model id string or an AI SDK
+ * `LanguageModel` instance.
  */
-export type PublicAgentModelDefinition = LanguageModel;
+export type PublicAgentStaticModelDefinition = string | LanguageModel;
+/** Context passed to dynamic model event handlers; the shared dynamic resolver context. */
+export type AgentModelResolveContext = DynamicResolveContext;
+export interface PublicAgentModelSelectionDefinition {
+    readonly model: PublicAgentStaticModelDefinition;
+    /** Context window of the selected model, in tokens; never inherited from the fallback. */
+    readonly modelContextWindowTokens?: number;
+    /** Provider options for the selected model; defaults to the agent-level `modelOptions`. */
+    readonly modelOptions?: AgentModelOptionsDefinition;
+}
+export type PublicAgentDynamicModelResult = PublicAgentStaticModelDefinition | PublicAgentModelSelectionDefinition | null;
+export type AgentModelResolver = (event: unknown, ctx: AgentModelResolveContext) => PublicAgentDynamicModelResult | Promise<PublicAgentDynamicModelResult>;
+export type PublicAgentDynamicModelDefinition = DynamicSentinel<PublicAgentDynamicModelResult, PublicAgentStaticModelDefinition>;
+export interface PublicAgentDynamicModelDefinitionInput {
+    /** Compiled static model: build-time metadata and the active model when no scope is set. */
+    readonly fallback: PublicAgentStaticModelDefinition;
+    readonly events: DynamicSentinel<PublicAgentDynamicModelResult>["events"];
+}
+export declare function isDynamicModelDefinition(value: unknown): value is PublicAgentDynamicModelDefinition;
+/**
+ * The model handle you assign to an agent's `model` field.
+ */
+export type PublicAgentModelDefinition = PublicAgentStaticModelDefinition | PublicAgentDynamicModelDefinition;
 export interface InternalAgentCompactionDefinition {
     /**
      * Optional model used only for generating compaction summaries.
@@ -85,7 +107,7 @@ export interface PublicAgentCompactionDefinition {
      *
      * When omitted, eve uses the active turn model for the summary call.
      */
-    readonly model?: PublicAgentModelDefinition;
+    readonly model?: PublicAgentStaticModelDefinition;
     /**
      * Fraction of the primary model context window that triggers compaction.
      *
@@ -239,8 +261,9 @@ export type PublicAgentDefinition = {
      */
     readonly experimental?: AgentExperimentalDefinition;
     /**
-     * Language model used for agent turns. Accepts an AI Gateway model ID or any
-     * AI SDK-compatible language model.
+     * Language model used for agent turns. Accepts an AI Gateway model ID, any AI
+     * SDK-compatible language model, or `defineDynamic({ fallback, events })` for
+     * scoped dynamic model selection.
      */
     readonly model: PublicAgentModelDefinition;
     /**

package/dist/src/shared/agent-definition.js

@@ -1 +1 @@
-export{};
+import{isDynamicSentinel}from"#shared/dynamic-tool-definition.js";function isDynamicModelDefinition(e){return isDynamicSentinel(e)&&`fallback`in e}export{isDynamicModelDefinition};

package/dist/src/shared/channel-definition.d.ts

@@ -0,0 +1,92 @@
+import { type ChannelCors } from "#channel/cors.js";
+import type { RouteDefinition, SendFn } from "#channel/routes.js";
+import type { Session, SessionHandle } from "#channel/session.js";
+import type { SessionAuthContext } from "#channel/types.js";
+/**
+ * Enriched return shape from a channel's {@link ChannelAdapter.fetchFile}
+ * function. Return a bare {@link Buffer} when only bytes are known, or
+ * this record when the fetch discovers a more accurate `mediaType` or
+ * `filename` (e.g. from an HTTP `Content-Type` header).
+ *
+ * When fields are provided, staging prefers them over the values the
+ * channel populated at ingestion time.
+ */
+export interface FetchFileResult {
+    readonly bytes: Buffer;
+    readonly mediaType?: string;
+    readonly filename?: string;
+}
+export type FetchFileFunction = (url: string) => Promise<Buffer | FetchFileResult | null>;
+/**
+ * Input passed to a channel's `receive` callback when another channel or
+ * schedule proactively routes a message to it.
+ */
+export interface GenericReceiveInput<TReceiveTarget = Record<string, unknown>> {
+    readonly message: string;
+    readonly target: Readonly<TReceiveTarget>;
+    readonly auth: SessionAuthContext | null;
+}
+/**
+ * The object passed to {@link defineChannel}. `routes` is required; `state`
+ * seeds durable adapter state, `context` builds the per-step `channel` argument
+ * for `events` and `deliver`, `events` handle session lifecycle, `receive`
+ * accepts cross-channel handoffs, `fetchFile` stages remote file URLs, and
+ * `metadata` projects observability data.
+ *
+ * Generics: `TState` (adapter state), `TCtx` (context factory return type),
+ * `TReceiveTarget` (cross-channel target shape), `TMetadata` (instrumentation
+ * projection).
+ */
+export interface GenericChannelDefinition<TEvents, TState = undefined, TCtx = void, TReceiveTarget = Record<string, unknown>, TMetadata extends Record<string, unknown> = Record<string, unknown>> {
+    readonly state?: TState;
+    /**
+     * CORS policy for this channel's HTTP routes. `true` enables H3/Nitro's
+     * permissive defaults (`origin`, methods, request headers, and exposed
+     * headers all `"*"`); `false` or omission leaves CORS untouched. Pass an
+     * object for a serializable subset of H3/Nitro CORS options.
+     */
+    readonly cors?: ChannelCors;
+    /**
+     * Builds the per-step channel context handed to `events` and `deliver`.
+     * Receives the live {@link SessionHandle}, so a factory can close over it to
+     * register late-bound callbacks. eve writes state mutations made inside the
+     * returned context back through `adapter.state`.
+     *
+     * Return the channel-owned context (thread handles, API clients, etc.). The
+     * framework passes it as the `channel` argument to event handlers (with
+     * {@link ChannelSessionOps} injected) and passes {@link SessionContext} as a
+     * separate `ctx` argument.
+     */
+    context?(state: NonNullable<TState>, session: SessionHandle): TCtx;
+    readonly routes: readonly RouteDefinition<TState>[];
+    receive?(input: GenericReceiveInput<TReceiveTarget>, args: {
+        send: SendFn<TState>;
+    }): Promise<Session>;
+    readonly events?: TEvents;
+    /**
+     * Fetches bytes for a `URL` object encountered on a `FilePart.data` by the
+     * staging pipeline. Return `null` to pass the URL through to the model
+     * provider unchanged, or bytes / {@link FetchFileResult} to stage the file to
+     * the sandbox.
+     */
+    readonly fetchFile?: FetchFileFunction;
+    /**
+     * Channel-owned metadata exposed to instrumentation callbacks. This is the
+     * channel's public observability surface, not a dump of durable adapter state,
+     * so keep it small. Return an object of JSON primitives, arrays, and plain
+     * objects: eve omits `undefined` properties and drops projections containing
+     * values such as `Date` or `Map`.
+     */
+    readonly metadata?: (state: NonNullable<TState>) => TMetadata;
+    /**
+     * Identifier of the adapter family this channel belongs to. Set by
+     * higher-level wrappers (e.g. `slackChannel` passes `"slack"`) so downstream
+     * consumers can render typed channel chips instead of bucketing everything
+     * under "unknown".
+     *
+     * Authors calling `defineChannel` directly do not need to set this; the
+     * framework defaults to `"http"` for stateless channels and `"defineChannel"`
+     * for stateful ones.
+     */
+    readonly kindHint?: string;
+}

package/dist/src/shared/channel-definition.js

@@ -0,0 +1 @@
+import"#channel/cors.js";export{};

package/dist/src/shared/dynamic-tool-definition.d.ts

@@ -107,22 +107,32 @@ export type DynamicToolEvents = {
  * the slot directory (tools/ vs skills/) determines the required return,
  * validated at runtime by the respective resolver.
  */
-export type DynamicEvents = {
-    readonly [K in DynamicToolEventName]?: (event: unknown, ctx: DynamicResolveContext) => unknown | Promise<unknown>;
+export type DynamicEvents<TResult = unknown> = {
+    readonly [K in DynamicToolEventName]?: (event: unknown, ctx: DynamicResolveContext) => 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.
  */
 export declare const DYNAMIC_SENTINEL_KIND: "eve:dynamic";
 /**
- * Return value of `defineDynamic`: the runtime shape of a
- * `defineDynamic({ events })` export, stamped with a sentinel kind the
- * compiler/normalizer detects.
+ * Return value of `defineDynamic`: the runtime shape of a dynamic export,
+ * stamped with a sentinel kind the compiler/normalizer detects. `TFallback`
+ * is `never` except for dynamic agent models, the only slot with a fallback.
  */
-export interface DynamicSentinel {
+export type DynamicSentinel<TResult = unknown, TFallback = never> = {
     readonly kind: typeof DYNAMIC_SENTINEL_KIND;
-    readonly events: DynamicEvents;
-}
+    readonly events: DynamicEvents<TResult>;
+} & ([TFallback] extends [never] ? object : {
+    readonly fallback: TFallback;
+});
+/**
+ * Throws when a dynamic sentinel outside the agent `model` slot carries a
+ * `fallback` — anywhere else it would be silently dead configuration.
+ */
+export declare function rejectDynamicSentinelFallback(sentinel: DynamicSentinel, message: string): void;
 export declare function isDynamicSentinel(value: unknown): value is DynamicSentinel;
 /**
  * Symbol-based brand stamped by `defineTool` on every entry. Invisible

package/dist/src/shared/dynamic-tool-definition.js

@@ -1 +1 @@
-const ALLOWED_DYNAMIC_TOOL_EVENTS=new Set([`session.started`,`turn.started`,`step.started`]),ALLOWED_DYNAMIC_INSTRUCTION_EVENTS=new Set([`session.started`,`turn.started`]),ALLOWED_DYNAMIC_SKILL_EVENTS=new Set([`session.started`,`turn.started`]),DYNAMIC_SENTINEL_KIND=`eve:dynamic`;function isDynamicSentinel(e){return typeof e==`object`&&!!e&&e.kind===`eve:dynamic`}const TOOL_BRAND=Symbol.for(`eve:tool-brand`);function isBrandedToolEntry(e){return typeof e==`object`&&!!e&&e[TOOL_BRAND]===!0}const INSTRUCTIONS_BRAND=Symbol.for(`eve:instructions-brand`);function isBrandedInstructionsEntry(e){return typeof e==`object`&&!!e&&e[INSTRUCTIONS_BRAND]===!0}const SKILL_BRAND=Symbol.for(`eve:skill-brand`);function isBrandedSkillEntry(e){return typeof e==`object`&&!!e&&e[SKILL_BRAND]===!0}export{ALLOWED_DYNAMIC_INSTRUCTION_EVENTS,ALLOWED_DYNAMIC_SKILL_EVENTS,ALLOWED_DYNAMIC_TOOL_EVENTS,DYNAMIC_SENTINEL_KIND,INSTRUCTIONS_BRAND,SKILL_BRAND,TOOL_BRAND,isBrandedInstructionsEntry,isBrandedSkillEntry,isBrandedToolEntry,isDynamicSentinel};
+const ALLOWED_DYNAMIC_TOOL_EVENTS=new Set([`session.started`,`turn.started`,`step.started`]),ALLOWED_DYNAMIC_INSTRUCTION_EVENTS=new Set([`session.started`,`turn.started`]),ALLOWED_DYNAMIC_SKILL_EVENTS=new Set([`session.started`,`turn.started`]),DYNAMIC_SENTINEL_KIND=`eve:dynamic`;function rejectDynamicSentinelFallback(e,t){if(`fallback`in e)throw Error(`${t} "fallback" is only supported on a dynamic agent model (the "model" field in agent.ts). For dynamic tools, skills, and instructions, author a static entry as the default or return null.`)}function isDynamicSentinel(e){return typeof e==`object`&&!!e&&e.kind===`eve:dynamic`}const TOOL_BRAND=Symbol.for(`eve:tool-brand`);function isBrandedToolEntry(e){return typeof e==`object`&&!!e&&e[TOOL_BRAND]===!0}const INSTRUCTIONS_BRAND=Symbol.for(`eve:instructions-brand`);function isBrandedInstructionsEntry(e){return typeof e==`object`&&!!e&&e[INSTRUCTIONS_BRAND]===!0}const SKILL_BRAND=Symbol.for(`eve:skill-brand`);function isBrandedSkillEntry(e){return typeof e==`object`&&!!e&&e[SKILL_BRAND]===!0}export{ALLOWED_DYNAMIC_INSTRUCTION_EVENTS,ALLOWED_DYNAMIC_SKILL_EVENTS,ALLOWED_DYNAMIC_TOOL_EVENTS,DYNAMIC_SENTINEL_KIND,INSTRUCTIONS_BRAND,SKILL_BRAND,TOOL_BRAND,isBrandedInstructionsEntry,isBrandedSkillEntry,isBrandedToolEntry,isDynamicSentinel,rejectDynamicSentinelFallback};

package/dist/src/shared/hook-definition.d.ts

@@ -0,0 +1,36 @@
+type BaseEvent = {
+    type: string;
+};
+/**
+ * Side-effect-only handler for one accepted runtime stream event.
+ *
+ * `TEvent` is one variant of the runtime stream-event union.
+ * {@link GenericStreamEventHooks} infers `TEvent` from the event key.
+ */
+export type GenericStreamEventHook<TEvent extends BaseEvent, TContext> = (event: TEvent, ctx: TContext) => void | Promise<void>;
+/**
+ * Map of stream-event subscribers an authored hook file may declare.
+ *
+ * `*` matches every accepted runtime stream event and runs after the
+ * typed handler for that event (if any).
+ */
+export type GenericStreamEventHooks<TEvent extends BaseEvent, TContext> = {
+    readonly "*"?: GenericStreamEventHook<TEvent, TContext>;
+} & {
+    readonly [K in TEvent["type"]]?: GenericStreamEventHook<Extract<TEvent, {
+        type: K;
+    }>, TContext>;
+};
+/**
+ * Public hook definition authored in `agent/hooks/*.ts`.
+ *
+ * Hook files declare stream-event subscribers (under `events:`) that
+ * fire after eve has accepted and durably recorded each event.
+ * Handlers are observe-only: they cannot inject model context. To
+ * contribute runtime model messages, use `defineDynamic` +
+ * `defineInstructions` in `agent/instructions/`.
+ */
+export interface GenericHookDefinition<TEvent extends BaseEvent, TContext> {
+    readonly events?: GenericStreamEventHooks<TEvent, TContext>;
+}
+export {};

package/dist/src/shared/hook-definition.js

@@ -0,0 +1 @@
+export{};

package/dist/src/shared/instructions-definition.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Public definition for an instructions prompt authored in markdown or
+ * TypeScript.
+ *
+ * Authored at the agent root as either `instructions.md` or
+ * `instructions.{ts,cts,mts,js,cjs,mjs}`, or inside the
+ * `agent/instructions/` directory for multi-file setups. Module-backed
+ * static instructions execute once at build time. The compiler captures
+ * the resulting markdown into the compiled manifest.
+ *
+ * When used inside a `defineDynamic` handler, the runtime lowers the
+ * returned markdown to `{ role: "system", content: markdown }`.
+ * Instructions produce system messages only. Use channel `context` for
+ * user-role messages.
+ */
+export interface PublicInstructionsDefinition {
+    markdown: string;
+}
+/**
+ * Internal definition for an instructions prompt authored in markdown or
+ * TypeScript.
+ */
+export interface InternalInstructionsDefinition {
+    name: string;
+    markdown: string;
+}

package/dist/src/shared/instructions-definition.js

@@ -0,0 +1 @@
+export{};

package/dist/src/shared/schedule-definition.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The `run` form of {@link ScheduleDefinition} invokes this handler when a
+ * schedule's cron fires. It receives {@link ScheduleHandlerArgs} (`receive`,
+ * `waitUntil`, `appAuth`) and may return synchronously or as a promise.
+ */
+export type GenericScheduleRunHandler<TArgs> = (args: TArgs) => Promise<void> | void;
+/** Constraint shape that bounds the authored keys accepted by {@link defineSchedule}. */
+export interface GenericScheduleDefinitionFields<TArgs> {
+    readonly cron: string;
+    readonly markdown?: string;
+    readonly run?: GenericScheduleRunHandler<TArgs>;
+}
+/**
+ * Public definition for a schedule authored in TypeScript. Provide a required
+ * `cron` expression plus exactly one of `markdown` or `run`:
+ *
+ * - `markdown`: fire-and-forget agent invocation. The framework runs the agent
+ *   on the prompt and discards the output (equivalent to the `<name>.md`
+ *   markdown form).
+ * - `run`: full handler ({@link GenericScheduleRunHandler}). Receives
+ *   `{ receive, waitUntil, appAuth }` and decides what to do.
+ *
+ * Identity is derived from the file path under `agent/schedules/`; authored
+ * definitions do not carry a `name` field.
+ */
+export type GenericScheduleDefinition<TArgs> = {
+    readonly cron: string;
+    readonly markdown: string;
+    readonly run?: never;
+} | {
+    readonly cron: string;
+    readonly markdown?: never;
+    readonly run: GenericScheduleRunHandler<TArgs>;
+};

package/dist/src/shared/schedule-definition.js

@@ -0,0 +1 @@
+export{};

package/dist/src/source-change/apply-model-name.js

@@ -1,2 +1,2 @@
-import{parseWithNitroRolldownAst}from"#internal/bundler/nitro-rolldown.js";const AGENT_FACTORY=`defineAgent`;async function applyModelNameToSource(e,n){let r=await parseAgentSource(e);if(`kind`in r)return r;if((r.errors?.length??0)>0){let t=r.errors?.[0];return{kind:`bail`,reason:`agent.ts does not parse: ${t?.message??`unknown parse error`}`,line:parseErrorLine(e,t)}}let i=findDefineAgentObject(r.program??r,AGENT_FACTORY);if(i===void 0)return{kind:`bail`,reason:`no \`export default ${AGENT_FACTORY}({ ... })\` call found`,line:1};let a=findStringLiteralProperty(i,`model`);if(a===void 0)return{kind:`bail`,reason:"`model` is absent or is not a string literal (e.g. an env reference, a template, or an inlined SDK model)",line:lineAt(e,i.start??0)};let o=a.value;if(o===n)return{kind:`applied`,from:o,to:n,nextSource:e};let s=a.raw?.[0]===`'`?`'`:`"`,c=`${s}${escapeForQuote(n,s)}${s}`;return{kind:`applied`,from:o,to:n,nextSource:e.slice(0,a.start)+c+e.slice(a.end)}}async function parseAgentSource(t){try{return await parseWithNitroRolldownAst(`agent.ts`,t)}catch(e){let n=e;return{kind:`bail`,reason:`agent.ts does not parse: ${n.message??`unknown parse error`}`,line:parseErrorLine(t,n)}}}function unwrapExpression(e){let t=e;for(;t.type===`ParenthesizedExpression`||t.type===`TSAsExpression`||t.type===`TSSatisfiesExpression`;){if(t.expression===void 0||t.expression===null)return t;t=t.expression}return t}function findDefineAgentObject(e,t){for(let n of e.body??[]){if(n.type!==`ExportDefaultDeclaration`)continue;let e=n.declaration;if(e==null||e.type!==`CallExpression`&&e.type!==`ParenthesizedExpression`&&e.type!==`TSAsExpression`&&e.type!==`TSSatisfiesExpression`)continue;let r=unwrapExpression(e);if(r.type!==`CallExpression`||!isFactoryCallee(r.callee,t))continue;let i=r.arguments?.[0];if(i===void 0||i.type===`SpreadElement`)continue;let a=unwrapExpression(i);if(a.type===`ObjectExpression`)return a}}function isFactoryCallee(e,t){return e?.type===`Identifier`&&e.name===t}function findStringLiteralProperty(e,t){for(let n of e.properties){if(n.type!==`Property`||n.computed||!keyMatches(n.key,t))continue;let e=n.value;if(!isAstNode(e))continue;let r=unwrapExpression(e);return r.type===`Literal`&&typeof r.value==`string`&&r.start!==void 0&&r.end!==void 0?r:void 0}}function keyMatches(e,t){return e===void 0?!1:e.type===`Identifier`?e.name===t:e.type===`Literal`?typeof e.value==`string`&&e.value===t:!1}function isAstNode(e){return typeof e==`object`&&!!e&&typeof e.type==`string`}function parseErrorLine(e,t){return typeof t?.loc?.line==`number`?t.loc.line:lineAt(e,t?.labels?.[0]?.start??t?.start??0)}function escapeForQuote(e,t){return e.replaceAll(`\\`,`\\\\`).replaceAll(t,`\\${t}`)}function lineAt(e,t){let n=1;for(let r=0;r<t&&r<e.length;r+=1)e[r]===`
+import{parseWithNitroRolldownAst}from"#internal/bundler/nitro-rolldown.js";const AGENT_FACTORY=`defineAgent`;async function applyModelNameToSource(e,n){let r=await parseAgentSource(e);if(`kind`in r)return r;if((r.errors?.length??0)>0){let t=r.errors?.[0];return{kind:`bail`,reason:`agent.ts does not parse: ${t?.message??`unknown parse error`}`,line:parseErrorLine(e,t)}}let i=findDefineAgentObject(r.program??r,AGENT_FACTORY);if(i===void 0)return{kind:`bail`,reason:`no \`export default ${AGENT_FACTORY}({ ... })\` call found`,line:1};let a=findStringLiteralProperty(i,`model`);if(a===void 0)return{kind:`bail`,reason:"`model` is absent or is not a string literal (e.g. an env reference, a template, an inlined SDK model, or a defineDynamic() dynamic model)",line:lineAt(e,i.start??0)};let o=a.value;if(o===n)return{kind:`applied`,from:o,to:n,nextSource:e};let s=a.raw?.[0]===`'`?`'`:`"`,c=`${s}${escapeForQuote(n,s)}${s}`;return{kind:`applied`,from:o,to:n,nextSource:e.slice(0,a.start)+c+e.slice(a.end)}}async function parseAgentSource(t){try{return await parseWithNitroRolldownAst(`agent.ts`,t)}catch(e){let n=e;return{kind:`bail`,reason:`agent.ts does not parse: ${n.message??`unknown parse error`}`,line:parseErrorLine(t,n)}}}function unwrapExpression(e){let t=e;for(;t.type===`ParenthesizedExpression`||t.type===`TSAsExpression`||t.type===`TSSatisfiesExpression`;){if(t.expression===void 0||t.expression===null)return t;t=t.expression}return t}function findDefineAgentObject(e,t){for(let n of e.body??[]){if(n.type!==`ExportDefaultDeclaration`)continue;let e=n.declaration;if(e==null||e.type!==`CallExpression`&&e.type!==`ParenthesizedExpression`&&e.type!==`TSAsExpression`&&e.type!==`TSSatisfiesExpression`)continue;let r=unwrapExpression(e);if(r.type!==`CallExpression`||!isFactoryCallee(r.callee,t))continue;let i=r.arguments?.[0];if(i===void 0||i.type===`SpreadElement`)continue;let a=unwrapExpression(i);if(a.type===`ObjectExpression`)return a}}function isFactoryCallee(e,t){return e?.type===`Identifier`&&e.name===t}function findStringLiteralProperty(e,t){for(let n of e.properties){if(n.type!==`Property`||n.computed||!keyMatches(n.key,t))continue;let e=n.value;if(!isAstNode(e))continue;let r=unwrapExpression(e);return r.type===`Literal`&&typeof r.value==`string`&&r.start!==void 0&&r.end!==void 0?r:void 0}}function keyMatches(e,t){return e===void 0?!1:e.type===`Identifier`?e.name===t:e.type===`Literal`?typeof e.value==`string`&&e.value===t:!1}function isAstNode(e){return typeof e==`object`&&!!e&&typeof e.type==`string`}function parseErrorLine(e,t){return typeof t?.loc?.line==`number`?t.loc.line:lineAt(e,t?.labels?.[0]?.start??t?.start??0)}function escapeForQuote(e,t){return e.replaceAll(`\\`,`\\\\`).replaceAll(t,`\\${t}`)}function lineAt(e,t){let n=1;for(let r=0;r<t&&r<e.length;r+=1)e[r]===`
 `&&(n+=1);return n}export{applyModelNameToSource};

package/docs/agent-config.md

@@ -43,6 +43,50 @@ version uses hyphens (`claude-opus-4-8`), while the Gateway id above uses a dot
 
 Model use is subject to the terms, data-processing commitments, retention behavior, and available controls of the selected provider and routing path. Review the [AI Gateway model catalog](https://vercel.com/ai-gateway/models) for gateway-routed models, and review the provider's terms when you configure a direct `LanguageModel`.
 
+### Choose the model dynamically
+
+`model` also accepts `defineDynamic({ fallback, events })`. `fallback` is the
+compiled static model: it anchors build-time metadata (routing, credentials,
+context window) and serves whenever no dynamic selection is set.
+
+```ts title="agent/agent.ts"
+import { defineAgent, defineDynamic } from "eve";
+
+export default defineAgent({
+  model: defineDynamic({
+    fallback: "anthropic/claude-sonnet-5",
+    events: {
+      "session.started": (_event, ctx) =>
+        ctx.session.auth.initiator?.attributes.plan === "enterprise"
+          ? "anthropic/claude-opus-4.8"
+          : null,
+    },
+  }),
+});
+```
+
+Handlers receive the shared [dynamic resolver
+context](./guides/dynamic-capabilities) (`ctx.session`, `ctx.channel`,
+`ctx.messages`) and return a gateway model id, an AI SDK `LanguageModel`, a
+selection object, or `null` to leave the scope unset.
+
+- **Scopes.** `session.started` (once per session), `turn.started` (once per
+  turn), `step.started` (every model step). Precedence: step > turn >
+  session > `fallback`. Prefer `session.started`: prompt caches are per
+  model, so every switch re-ingests the conversation at uncached prices.
+- **Failures degrade, never fail the turn.** A resolver that throws or
+  returns an invalid selection logs an error and leaves its scope unset.
+  Build-time validation covers only `fallback`; a selected model without
+  credentials fails at request time.
+- **Serialization.** Session/turn selections must be model id strings; return
+  live `LanguageModel` objects only from `step.started`.
+- **Selection object.** `{ model, modelContextWindowTokens?, modelOptions? }`.
+  Set `modelContextWindowTokens` when the selected model's window differs
+  from the fallback's — it is never inherited. Omitted `modelOptions` reuses
+  the agent-level `modelOptions`.
+
+Runtime identity reports a dynamic agent's model as `dynamic:<fallback id>`.
+
 ## Reasoning effort
 
 Set `reasoning` to control the model's reasoning effort through AI SDK's

package/docs/guides/dynamic-capabilities.md

@@ -1,9 +1,25 @@
 ---
 title: "Dynamic Capabilities"
-description: "Resolve tools, skills, and instructions at runtime with defineDynamic: the resolver events, execution order, and how dynamic tools survive step boundaries."
+description: "Resolve models, tools, skills, and instructions at runtime: dynamic model selection, defineDynamic resolver events, execution order, and durable dynamic tools."
 ---
 
-`defineDynamic` resolves tools, skills, and instructions at runtime from a session event instead of declaring them up front. Reach for it when the right capabilities aren't known until the session starts, because they hinge on who the caller is, what tenant they belong to, feature flags, or external data. The [tools](../tools), [skills](../skills), and [instructions](../instructions) guides each point here for their dynamic form.
+`defineDynamic` resolves the model, tools, skills, and instructions at runtime from a session event instead of declaring them up front. Reach for it when the right capability isn't known until the session starts, because it hinges on who the caller is, what tenant they belong to, feature flags, or external data. The [tools](../tools), [skills](../skills), and [instructions](../instructions) guides each point here for their dynamic form.
+
+## Dynamic models
+
+The `model` field in `agent.ts` accepts `defineDynamic({ fallback, events })`.
+Resolvers run at `session.started`, `turn.started`, or `step.started`
+(precedence: step > turn > session > `fallback`); `null` leaves a scope unset
+and failures degrade to the next scope. Prefer `session.started` — prompt
+caches are per model, so switching mid-session re-ingests the conversation at
+uncached prices. See
+[agent configuration](../agent-config#choose-the-model-dynamically) for the
+full contract.
+
+`fallback` is model-only: the agent always needs exactly one model, and the
+compiled fallback anchors build-time metadata. Tools, skills, and instructions
+default by authoring a static entry (or returning `null`), so `fallback` on
+their `defineDynamic` export is a build error.
 
 ## Dynamic tools
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [

package/dist/src/public/definitions/defineChannel.d.ts

@@ -1,157 +0,0 @@
-import type { FetchFileResult } from "#channel/adapter.js";
-import { CHANNEL_SENTINEL } from "#channel/compiled-channel.js";
-import { type ChannelCors, type ChannelCorsOptions } from "#channel/cors.js";
-import type { TypedReceiveTarget } from "#channel/receive-target.js";
-import type { SessionAuthContext } from "#channel/types.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
-import type { SessionContext } from "#public/definitions/callback-context.js";
-import type { RouteDefinition, SendFn } from "#channel/routes.js";
-import type { Session, SessionHandle } from "#channel/session.js";
-declare const CHANNEL_METADATA_TYPE: unique symbol;
-export type { Session, SessionHandle } from "#channel/session.js";
-export type { ChannelCors, ChannelCorsOptions } from "#channel/cors.js";
-export { GET, POST, PUT, PATCH, DELETE, WS } from "#channel/routes.js";
-export type { HttpRouteDefinition, RouteDefinition, RouteHandlerArgs, SendFn, SendOptions, SendPayload, GetSessionFn, WebSocketMessage, WebSocketPeer, WebSocketRouteDefinition, WebSocketRouteHandler, WebSocketRouteHooks, WebSocketUpgradeRequest, WebSocketUpgradeResult, } from "#channel/routes.js";
-type EventData<T extends HandleMessageStreamEvent["type"]> = Extract<HandleMessageStreamEvent, {
-    type: T;
-}> extends {
-    data: infer D;
-} ? D : undefined;
-/**
- * Session operations on the `channel` argument of every channel event handler.
- */
-export interface ChannelSessionOps {
-    readonly continuationToken: string;
-    setContinuationToken(token: string): void;
-}
-/**
- * Channel context passed to event handlers: `TCtx` intersected with
- * {@link ChannelSessionOps}.
- */
-export type ChannelContext<TCtx> = TCtx & ChannelSessionOps;
-type ChannelEventHandler<T extends HandleMessageStreamEvent["type"], TCtx> = (data: EventData<T>, channel: ChannelContext<TCtx>, ctx: SessionContext) => void | Promise<void>;
-type ChannelSessionFailedHandler<TCtx> = (data: EventData<"session.failed">, channel: ChannelContext<TCtx>) => void | Promise<void>;
-/**
- * Optional handlers keyed by session lifecycle event name. Each handler receives
- * the event `data`, the {@link ChannelContext}, and a {@link SessionContext}
- * `ctx`. The `session.failed` handler is the exception: it receives only `data`
- * and the channel context, with no `ctx`.
- */
-export interface ChannelEvents<TCtx = void> {
-    readonly "turn.started"?: ChannelEventHandler<"turn.started", TCtx>;
-    readonly "actions.requested"?: ChannelEventHandler<"actions.requested", TCtx>;
-    readonly "action.result"?: ChannelEventHandler<"action.result", TCtx>;
-    readonly "message.completed"?: ChannelEventHandler<"message.completed", TCtx>;
-    readonly "message.appended"?: ChannelEventHandler<"message.appended", TCtx>;
-    readonly "reasoning.appended"?: ChannelEventHandler<"reasoning.appended", TCtx>;
-    readonly "reasoning.completed"?: ChannelEventHandler<"reasoning.completed", TCtx>;
-    readonly "input.requested"?: ChannelEventHandler<"input.requested", TCtx>;
-    readonly "turn.failed"?: ChannelEventHandler<"turn.failed", TCtx>;
-    readonly "turn.completed"?: ChannelEventHandler<"turn.completed", TCtx>;
-    readonly "session.failed"?: ChannelSessionFailedHandler<TCtx>;
-    readonly "session.completed"?: ChannelEventHandler<"session.completed", TCtx>;
-    readonly "session.waiting"?: ChannelEventHandler<"session.waiting", TCtx>;
-    readonly "authorization.required"?: ChannelEventHandler<"authorization.required", TCtx>;
-    readonly "authorization.completed"?: ChannelEventHandler<"authorization.completed", TCtx>;
-}
-/**
- * Input passed to a channel's `receive` callback when another channel or
- * schedule proactively routes a message to it.
- */
-export interface ReceiveInput<TReceiveTarget = Record<string, unknown>> {
-    readonly message: string;
-    readonly target: Readonly<TReceiveTarget>;
-    readonly auth: SessionAuthContext | null;
-}
-/**
- * The object passed to {@link defineChannel}. `routes` is required; `state`
- * seeds durable adapter state, `context` builds the per-step `channel` argument
- * for `events` and `deliver`, `events` handle session lifecycle, `receive`
- * accepts cross-channel handoffs, `fetchFile` stages remote file URLs, and
- * `metadata` projects observability data.
- *
- * Generics: `TState` (adapter state), `TCtx` (context factory return type),
- * `TReceiveTarget` (cross-channel target shape), `TMetadata` (instrumentation
- * projection).
- */
-export interface ChannelDefinition<TState = undefined, TCtx = void, TReceiveTarget = Record<string, unknown>, TMetadata extends Record<string, unknown> = Record<string, unknown>> {
-    readonly state?: TState;
-    /**
-     * CORS policy for this channel's HTTP routes. `true` enables H3/Nitro's
-     * permissive defaults (`origin`, methods, request headers, and exposed
-     * headers all `"*"`); `false` or omission leaves CORS untouched. Pass an
-     * object for a serializable subset of H3/Nitro CORS options.
-     */
-    readonly cors?: ChannelCors;
-    /**
-     * Builds the per-step channel context handed to `events` and `deliver`.
-     * Receives the live {@link SessionHandle}, so a factory can close over it to
-     * register late-bound callbacks. eve writes state mutations made inside the
-     * returned context back through `adapter.state`.
-     *
-     * Return the channel-owned context (thread handles, API clients, etc.). The
-     * framework passes it as the `channel` argument to event handlers (with
-     * {@link ChannelSessionOps} injected) and passes {@link SessionContext} as a
-     * separate `ctx` argument.
-     */
-    context?(state: NonNullable<TState>, session: SessionHandle): TCtx;
-    readonly routes: readonly RouteDefinition<TState>[];
-    receive?(input: ReceiveInput<TReceiveTarget>, args: {
-        send: SendFn<TState>;
-    }): Promise<Session>;
-    readonly events?: ChannelEvents<TCtx>;
-    /**
-     * Fetches bytes for a `URL` object encountered on a `FilePart.data` by the
-     * staging pipeline. Return `null` to pass the URL through to the model
-     * provider unchanged, or bytes / {@link FetchFileResult} to stage the file to
-     * the sandbox.
-     */
-    readonly fetchFile?: (url: string) => Promise<Buffer | FetchFileResult | null>;
-    /**
-     * Channel-owned metadata exposed to instrumentation callbacks. This is the
-     * channel's public observability surface, not a dump of durable adapter state,
-     * so keep it small. Return an object of JSON primitives, arrays, and plain
-     * objects: eve omits `undefined` properties and drops projections containing
-     * values such as `Date` or `Map`.
-     */
-    readonly metadata?: (state: NonNullable<TState>) => TMetadata;
-    /**
-     * Identifier of the adapter family this channel belongs to. Set by
-     * higher-level wrappers (e.g. `slackChannel` passes `"slack"`) so downstream
-     * consumers can render typed channel chips instead of bucketing everything
-     * under "unknown".
-     *
-     * Authors calling `defineChannel` directly do not need to set this; the
-     * framework defaults to `"http"` for stateless channels and `"defineChannel"`
-     * for stateful ones.
-     */
-    readonly kindHint?: string;
-}
-/**
- * Opaque channel value produced by {@link defineChannel} and exported from
- * `agent/channels/<name>.ts`. Exposes the channel's routes, an optional
- * `receive` hook, and (via a phantom property) its metadata shape. Unlike
- * {@link ChannelDefinition} it has no `TCtx` parameter: the context type is
- * internal to the definition.
- */
-export interface Channel<TState = undefined, TReceiveTarget = Record<string, unknown>, TMetadata extends Record<string, unknown> = Record<string, unknown>> extends TypedReceiveTarget<TReceiveTarget> {
-    readonly __kind: typeof CHANNEL_SENTINEL;
-    readonly [CHANNEL_METADATA_TYPE]?: TMetadata;
-    readonly routes: readonly RouteDefinition<TState>[];
-    readonly cors?: ChannelCorsOptions;
-    readonly receive?: (input: ReceiveInput<TReceiveTarget>, args: {
-        send: SendFn<TState>;
-    }) => Promise<Session>;
-}
-/**
- * Extracts the metadata projection type (`TMetadata`) from a {@link Channel}.
- * Resolves to `Record<string, unknown>` when the value is not a Channel.
- */
-export type InferChannelMetadata<TChannel> = TChannel extends Channel<any, any, infer TMetadata> ? TMetadata : Record<string, unknown>;
-/**
- * Builds a {@link Channel} from a {@link ChannelDefinition}. Returns a value
- * placed at `agent/channels/<name>.ts`; the file path supplies the channel name
- * (do not add a `name` field). `TCtx` (the context factory's return type) is
- * internal to the definition and is not part of the returned Channel signature.
- */
-export declare function defineChannel<TState = undefined, TCtx = void, TReceiveTarget = Record<string, unknown>, TMetadata extends Record<string, unknown> = Record<string, unknown>>(definition: ChannelDefinition<TState, TCtx, TReceiveTarget, TMetadata>): Channel<TState, TReceiveTarget, TMetadata>;

package/dist/src/public/definitions/defineChannel.js

@@ -1 +0,0 @@
-import{CHANNEL_SENTINEL}from"#channel/compiled-channel.js";import{defaultDeliverResult}from"#channel/adapter.js";import{buildCallbackContext}from"#context/build-callback-context.js";import{normalizeChannelCors}from"#channel/cors.js";import{HTTP_ADAPTER_KIND}from"#channel/http.js";import{DELETE,GET,PATCH,POST,PUT,WS}from"#channel/routes.js";function defineChannel(t){let n=buildAdapter(t),i=normalizeChannelCors(t.cors);return{__kind:CHANNEL_SENTINEL,routes:t.routes,adapter:n,cors:i,receive:t.receive}}function buildAdapter(e){let r=e.state!=null,a=e.context!=null,o=e.fetchFile!==void 0,s=e.metadata,c=r||a||s!==void 0,l={},u=!1,d=[`turn.started`,`actions.requested`,`action.result`,`message.completed`,`message.appended`,`reasoning.appended`,`reasoning.completed`,`input.requested`,`turn.failed`,`turn.completed`,`session.failed`,`session.completed`,`session.waiting`,`authorization.required`,`authorization.completed`],f=e.events;for(let e of d){let t=f?.[e];t&&(u=!0,l[e]=(r,i)=>{let a={...i,continuationToken:i.session?.continuationToken??``,setContinuationToken:e=>i.session?.setContinuationToken(e)};return e===`session.failed`?t(r,a):t(r,a,buildCallbackContext())})}return!c&&!u&&!o?{kind:e.kindHint??HTTP_ADAPTER_KIND}:{kind:e.kindHint??`defineChannel`,state:r?{...e.state}:{},fetchFile:e.fetchFile,instrumentation:s===void 0?void 0:{metadata(e){return s(e)}},createAdapterContext(t){let n=t.state,r=t.session;return{...a?e.context(n,r):{},state:n,ctx:t.ctx,session:r}},deliver(e){return defaultDeliverResult(e)},...l}}export{DELETE,GET,PATCH,POST,PUT,WS,defineChannel};