eve 0.21.1 → 0.22.1

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/shared/vercel-project.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Claims eve reads from a Vercel OIDC token payload.
+ *
+ * Decoded locally without signature verification: callers use the values
+ * as stable identifiers (sandbox key derivation, credential routing),
+ * never to make authentication decisions.
+ */
+export interface VercelOidcTokenClaims {
+    readonly ownerId: string | undefined;
+    readonly projectId: string | undefined;
+}
+/**
+ * Decodes the payload claims of a Vercel OIDC token. Values that are not
+ * decodable JWTs, or that carry no recognized claims, decode to empty
+ * claims — callers only ever check individual fields.
+ */
+export declare function decodeVercelOidcTokenClaims(token: string): VercelOidcTokenClaims;
+/**
+ * Resolves the Vercel project id visible to this process: the
+ * `VERCEL_PROJECT_ID` env var when exposed, otherwise the `project_id`
+ * claim of `VERCEL_OIDC_TOKEN`. Both sources exist at build time and at
+ * deployed runtime and name the same project, so identifiers derived
+ * from this value agree across the two phases.
+ */
+export declare function resolveVercelProjectIdFromEnvironment(): string | undefined;

package/dist/src/shared/vercel-project.js

@@ -0,0 +1 @@
+const EMPTY_CLAIMS={ownerId:void 0,projectId:void 0};function decodeVercelOidcTokenClaims(t){let n=t.split(`.`)[1];if(n===void 0||n.length===0)return EMPTY_CLAIMS;let r;try{r=JSON.parse(Buffer.from(n,`base64url`).toString(`utf8`))}catch{return EMPTY_CLAIMS}if(typeof r!=`object`||!r)return EMPTY_CLAIMS;let i=r;return{ownerId:typeof i.owner_id==`string`?i.owner_id:void 0,projectId:typeof i.project_id==`string`?i.project_id:void 0}}function resolveVercelProjectIdFromEnvironment(){let e=process.env.VERCEL_PROJECT_ID?.trim();if(e!==void 0&&e.length>0)return e;let t=process.env.VERCEL_OIDC_TOKEN?.trim();if(!(t===void 0||t.length===0))return decodeVercelOidcTokenClaims(t).projectId}export{decodeVercelOidcTokenClaims,resolveVercelProjectIdFromEnvironment};

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/channels/slack.mdx

@@ -70,6 +70,33 @@ export default slackChannel({
 
 `threadContext` performs one `conversations.replies` request for each triggering thread reply and requires the matching Slack history scope. Omit it when the agent should see only direct mentions. `loadThreadContextMessages` remains available when you need custom filtering or non-model processing of the raw thread messages.
 
+### Slack API calls outside a handler
+
+Inside webhook-side handlers (`onAppMention`, `onInteraction`, `events`),
+`ctx.slack.request(operation, body)` is the raw-API escape hatch. Outside
+those contexts there is no handle — a schedule resolving reactions on old
+messages, for example, has no inbound Slack request. For that, call the
+same primitive the handle uses directly:
+
+```ts
+import { callSlackApi, resolveSlackBotToken } from "eve/channels/slack";
+import { connectSlackCredentials } from "@vercel/connect/eve";
+
+const { botToken } = connectSlackCredentials("slack/my-agent");
+const response = await callSlackApi({
+  botToken,
+  operation: "reactions.get",
+  body: { channel: "C0123456789", timestamp: "1712345678.000100", full: true },
+});
+if (!response.ok) throw new Error(String(response.error));
+```
+
+`callSlackApi` resolves function-form tokens (secret managers, Connect
+rotation) at call time and form-encodes the body — the only safe default,
+since Slack's JSON support is partial (`conversations.replies` rejects
+JSON). `resolveSlackBotToken` materializes a `SlackBotToken` to a string
+when you need the bearer token itself.
+
 ### Delivery
 
 The default handlers reply in-thread and show progress. Typing indicators post automatically: `Thinking…` on inbound, `Working…` on `turn.started`, a truncated reasoning snippet on `reasoning.appended`, and tool status on `actions.requested`. Reasoning snippets build progressively: extensions of at least four characters appear immediately, while smaller streamed deltas use the five-second refresh interval to avoid one Slack request per token. Override `events["reasoning.appended"]` if you prefer generic wording. Override `onAppMention` or the `events` handlers to customize.

package/docs/connections/overview.mdx

@@ -138,6 +138,8 @@ export default defineMcpClientConnection({
 
 `"linear/myagent"` is the UID you chose when registering the Connect client. `connect("linear/myagent")` is shorthand for a user-scoped interactive OAuth connection: eve resolves a token for the active user before each tool call, emits `authorization.required` when that user has not authorized yet, and resumes the parked turn after the callback completes.
 
+When a local subagent needs interactive authorization, eve surfaces the authorization lifecycle on the root session's channel, including through nested subagent chains. The challenge still points to the child session's callback, so completing it resumes the child directly while the parent continues waiting for its result.
+
 That means the channel that creates or continues the session must authenticate a real user. For a web app, configure `agent/channels/eve.ts` so your app session maps to `principalType: "user"`; for platform channels, use the built-in channel auth that maps the sender to a user principal. If no authenticated user is attached to the session, the first user-scoped connection call fails with `reason: "principal_required"`.
 
 If the remote service should act as the agent itself instead of the end-user, make the Connect connection app-scoped:

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/docs/sandbox.mdx

@@ -164,7 +164,7 @@ You can also write your own backend. A `SandboxBackend` is an adapter object wit
 There are two hooks, scoped differently:
 
 - **`bootstrap({ use })`** is template-scoped and runs once when the template is built. Put reusable setup here that every later session inherits, such as cloning a baseline repo, installing dependencies, or seeding files. Call `use()` to get a `SandboxSession`. Only template filesystem state and supported backend metadata carry into later sessions; config like network policy does not. If external inputs affect what bootstrap produces, set `revalidationKey: () => string` so eve knows when to rebuild the template (authored sandbox source and seed contents are already tracked for you).
-- **`onSession({ use, ctx })`** is durable-session-scoped and runs once per session. Put per-session setup here, including network policy, resources, timeout, per-user credentials, and one-time markers. Because it runs inside the active runtime context, it can read `ctx.session` and derive the current principal without baking credentials into the template. Call `use(opts?)` to get a `SandboxSession`; `opts` flow to the backend's update path after create.
+- **`onSession({ use, ctx })`** is durable-session-scoped and runs once per session (and again if a sandbox definition change replaces the session's sandbox). Put per-session setup here, including network policy, resources, timeout, per-user credentials, and one-time markers. Because it runs inside the active runtime context, it can read `ctx.session` and derive the current principal without baking credentials into the template. Call `use(opts?)` to get a `SandboxSession`; `opts` flow to the backend's update path after create.
 
 If you require a network policy or other configuration for every session, configure it on the backend factory or in `onSession`; do not rely on bootstrap-only configuration.
 
@@ -185,6 +185,8 @@ export default defineSandbox({
 
 Sessions are persistent, and how the underlying runtime idles out depends on the backend. On the Vercel backend, the VM times out after a period of inactivity (default 30 minutes); eve preserves the filesystem and resumes the sandbox on the next message as if nothing happened, even days later. The Docker backend keeps a long-lived container per durable session and persists `/workspace` across turns without that timeout, and the just-bash backend stores its virtual filesystem under `.eve/sandbox-cache/`. In every case, `/workspace` survives between turns for the same session.
 
+Session sandboxes are keyed per durable session, not per deployment, so redeploying your app does not discard them. A session gets a replacement sandbox only when the sandbox definition itself changes — the authored sandbox source, workspace seed content, or `revalidationKey` — in which case the next turn starts from the rebuilt template and `onSession` runs again.
+
 When the eve server stops, no sandbox compute outlives it. `eve dev` stops the sandboxes it started when the dev server closes, and a self-hosted production server stops every open sandbox on shutdown (`SIGTERM`/`SIGINT`). Session state persists across the stop — the next server start reattaches each durable session from its stopped container, VM, or snapshot. Custom `SandboxBackend` adapters participate through the handle's `shutdown()` method: stop the underlying compute, keeping the session reattachable from persisted state where the backend supports it.
 
 ## Network policy

package/docs/subagents.mdx

@@ -109,7 +109,7 @@ Because the name lives in the same runtime tool namespace as authored tools, a s
 
 Do not rely on subagent delegation by itself as an approval boundary. Put sensitive tools behind `approval`, connection approval, route/session authorization, or other controls wherever those tools can be called.
 
-Each delegated subagent spins up its own child session and stream. The parent stream carries only the control-plane events `subagent.called` and `subagent.completed`. To follow the child's full progress, read `subagent.called.data.childSessionId` and subscribe at `GET /eve/v1/session/:childSessionId/stream`.
+Each delegated subagent spins up its own child session and stream. The parent stream carries the control-plane events `subagent.called` and `subagent.completed`, plus interactive `input.requested`, `authorization.required`, and `authorization.completed` events proxied from descendants so the root channel can prompt the user. To follow the child's other progress, read `subagent.called.data.childSessionId` and subscribe at `GET /eve/v1/session/:childSessionId/stream`.
 
 ## When to split
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.21.1",
+  "version": "0.22.1",
   "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};