eve 0.19.0 → 0.21.0

package/dist/src/setup/scaffold/create/web-template.js

@@ -15,6 +15,7 @@ export default eveChannel({
 });
 `,"app/_components/agent-chat.tsx":`"use client";
 
+import type { UserContent } from "ai";
 import { useEveAgent } from "eve/react";
 import { AlertCircleIcon } from "lucide-react";
 import {
@@ -42,9 +43,27 @@ export function AgentChat() {
 
   const handleSubmit = async (message: PromptInputMessage) => {
     const text = message.text.trim();
-    if (!text || isBusy) return;
+    if ((text.length === 0 && message.files.length === 0) || isBusy) return;
 
-    await agent.send({ message: text });
+    if (message.files.length === 0) {
+      await agent.send({ message: text });
+      return;
+    }
+
+    const parts: UserContent = [];
+    if (text.length > 0) {
+      parts.push({ text, type: "text" });
+    }
+    for (const file of message.files) {
+      parts.push({
+        data: file.url,
+        filename: file.filename,
+        mediaType: file.mediaType,
+        type: "file",
+      });
+    }
+
+    await agent.send({ message: parts });
   };
 
   const composer = (
@@ -148,7 +167,14 @@ import type {
   EveMessage,
   EveMessagePart,
 } from "eve/react";
-import { CheckCircleIcon, ExternalLinkIcon, KeyRoundIcon, XCircleIcon } from "lucide-react";
+import {
+  CheckCircleIcon,
+  ExternalLinkIcon,
+  FileIcon,
+  ImageIcon,
+  KeyRoundIcon,
+  XCircleIcon,
+} from "lucide-react";
 import { Message, MessageContent, MessageResponse } from "@/components/ai-elements/message";
 import { Reasoning, ReasoningContent, ReasoningTrigger } from "@/components/ai-elements/reasoning";
 import {
@@ -167,6 +193,8 @@ export type AgentInputResponse = {
   readonly text?: string;
 };
 
+type EveFilePart = Extract<EveMessagePart, { type: "file" }>;
+
 export function AgentMessage({
   canRespond,
   isStreaming,
@@ -230,6 +258,8 @@ function AgentMessagePart({
           <ReasoningContent>{part.text}</ReasoningContent>
         </Reasoning>
       );
+    case "file":
+      return <AttachmentPart part={part} />;
     case "authorization":
       return <AuthorizationPrompt part={part} />;
     case "dynamic-tool":
@@ -257,6 +287,37 @@ function AgentMessagePart({
   }
 }
 
+function AttachmentPart({ part }: { readonly part: EveFilePart }) {
+  const label = part.filename ?? "Attachment";
+  const detail = [part.mediaType, formatBytes(part.size)].filter(Boolean).join(" - ");
+  const isImage = part.mediaType.startsWith("image/") && part.url !== undefined;
+  const Icon = isImage ? ImageIcon : FileIcon;
+  const body = (
+    <span className="flex max-w-sm items-center gap-3 rounded-md border bg-background/60 p-2 text-sm">
+      {isImage ? (
+        <img alt={label} className="size-12 shrink-0 rounded-sm object-cover" src={part.url} />
+      ) : (
+        <span className="flex size-10 shrink-0 items-center justify-center rounded-sm bg-muted text-muted-foreground">
+          <Icon className="size-4" />
+        </span>
+      )}
+      <span className="min-w-0 flex-1">
+        <span className="block truncate font-medium">{label}</span>
+        {detail ? <span className="block truncate text-muted-foreground">{detail}</span> : null}
+      </span>
+      {part.url ? <ExternalLinkIcon className="size-4 shrink-0 text-muted-foreground" /> : null}
+    </span>
+  );
+
+  return part.url ? (
+    <a href={part.url} rel="noreferrer" target="_blank">
+      {body}
+    </a>
+  ) : (
+    body
+  );
+}
+
 function AuthorizationPrompt({ part }: { readonly part: EveAuthorizationPart }) {
   const isAuthorized = part.state === "completed" && part.outcome === "authorized";
   const isCompleted = part.state === "completed";
@@ -350,6 +411,19 @@ function formatAuthorizationOutcome(outcome: NonNullable<EveAuthorizationPart["o
   }
 }
 
+function formatBytes(size: number | undefined): string | undefined {
+  if (size === undefined) {
+    return undefined;
+  }
+  if (size < 1024) {
+    return \`\${size} B\`;
+  }
+  if (size < 1024 * 1024) {
+    return \`\${(size / 1024).toFixed(1)} KB\`;
+  }
+  return \`\${(size / (1024 * 1024)).toFixed(1)} MB\`;
+}
+
 function InputRequestActions({
   canRespond,
   onInputResponses,

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

@@ -103,9 +103,28 @@ export interface AgentLimitsDefinition {
      * Root sessions are depth 0. A `maxSubagentDepth` of 3 allows child sessions at
      * depths 1, 2, and 3; sessions already at depth 3 cannot delegate again.
      *
+     * Delegated subagent sessions resolve this against the cap inherited from
+     * the delegating parent; the tighter value wins.
+     *
      * @default 3
      */
     readonly maxSubagentDepth?: number;
+    /**
+     * Maximum number of subagent calls one `Workflow` tool invocation may
+     * dispatch.
+     *
+     * Applies to the opt-in `Workflow` orchestration tool: a single
+     * model-authored workflow program may spawn at most this many subagent or
+     * remote-agent calls, counted across the whole program (sequential and
+     * parallel calls alike). Calls beyond the limit fail with an error result
+     * instead of starting a child session.
+     *
+     * Delegated subagent sessions resolve this against the cap inherited from
+     * the delegating parent; the tighter value wins.
+     *
+     * @default 100
+     */
+    readonly maxSubagents?: number;
     /**
      * Maximum provider-reported input tokens accumulated by one durable session.
      *
@@ -113,17 +132,26 @@ export interface AgentLimitsDefinition {
      * the limit is allowed to finish because providers only report exact usage
      * after the call completes; later model calls in the same session are blocked.
      *
-     * @default 40_000_000 for root sessions; 5_000_000 for delegated subagent sessions
+     * `false` disables the limit: the session is uncapped.
+     *
+     * Delegated subagent sessions default to the delegating parent's remaining
+     * quota at dispatch time, and the parent's remaining quota always caps an
+     * authored child limit — a child can never outspend its parent's budget.
+     *
+     * @default 40_000_000 for root sessions; the parent's remaining quota for delegated subagent sessions
      */
-    readonly maxInputTokensPerSession?: number;
+    readonly maxInputTokensPerSession?: number | false;
     /**
      * Maximum provider-reported output tokens accumulated by one durable session.
      *
      * eve checks this before starting each model call. The model call that crosses
      * the limit is allowed to finish because providers only report exact usage
      * after the call completes; later model calls in the same session are blocked.
+     *
+     * `false` disables the limit. Unset by default; delegated subagent sessions
+     * inherit the parent's remaining output quota when the parent has one.
      */
-    readonly maxOutputTokensPerSession?: number;
+    readonly maxOutputTokensPerSession?: number | false;
 }
 /**
  * Experimental, opt-in agent capabilities authored in `agent.ts`.

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

@@ -4,7 +4,10 @@ import type { SessionContext } from "#public/definitions/callback-context.js";
 import type { Approval } from "#public/definitions/approval.js";
 import type { SessionAuth } from "#context/keys.js";
 import type { HandleMessageStreamEvent } from "#protocol/message.js";
-type ToolContext = SessionContext;
+type ToolContext = SessionContext & {
+    /** Aborts when the active turn is cancelled. */
+    readonly abortSignal: AbortSignal;
+};
 /**
  * Stream event types allowed for dynamic tool resolvers. Dispatch
  * supports any event; this extract restricts the public surface until

package/dist/src/shared/sandbox-backend.d.ts

@@ -11,7 +11,13 @@ export interface SandboxBackendHandle<SO = Record<string, never>> {
     readonly session: SandboxSession;
     readonly useSessionFn: SandboxSessionUseFn<SO>;
     captureState(): Promise<SandboxBackendSessionState>;
-    dispose(): Promise<void>;
+    /**
+     * Stops the underlying compute because the eve server is shutting
+     * down; nothing may be left running afterwards. The session must
+     * remain reattachable from persisted state on the next server start
+     * when the backend supports durable sessions.
+     */
+    shutdown(): Promise<void>;
 }
 /**
  * Serializable per-sandbox reconnect record stored on the harness session.

package/dist/src/shared/skill-package.d.ts

@@ -30,7 +30,7 @@ export declare function writeSkillPackageDirectory(input: {
 }): Promise<void>;
 /**
  * Writes a normalized package into the live sandbox under
- * `/workspace/skills/<name>/`.
+ * the sandbox skill root.
  */
 export declare function writeSkillPackageToSandbox(input: {
     readonly sandbox: SandboxSession;
@@ -45,6 +45,6 @@ export declare function removeSkillPackageFromSandbox(input: {
 }): Promise<void>;
 /**
  * Validates a runtime-contributed skill name before it becomes one path
- * segment under `/workspace/skills`.
+ * segment under the sandbox skill root.
  */
 export declare function assertSafeSkillPackageName(name: string): void;

package/dist/src/shared/skill-package.js

@@ -1 +1 @@
-import{dirname,join}from"node:path";import{mkdir,writeFile}from"node:fs/promises";import{Buffer}from"node:buffer";const WORKSPACE_ROOT=`/workspace`;function normalizeSkillPackage(e){assertSafeSkillPackageName(e.name);let t=[{content:Buffer.from(e.markdown,`utf8`),relativePath:`SKILL.md`}];for(let[n,r]of Object.entries(e.files??{}))assertSafeSkillPackageFilePath(n),t.push({content:contentToBuffer(r),relativePath:n});return t.sort((e,t)=>comparePaths(e.relativePath,t.relativePath)),{description:e.description,files:t,license:e.license,markdown:e.markdown,metadata:e.metadata===void 0?void 0:{...e.metadata},name:e.name}}async function writeSkillPackageDirectory(i){for(let a of i.skill.files){let o=join(i.rootPath,`skills`,i.skill.name,a.relativePath);await mkdir(dirname(o),{recursive:!0}),await writeFile(o,a.content)}}async function writeSkillPackageToSandbox(e){for(let t of e.skill.files)await e.sandbox.writeBinaryFile({content:t.content,path:`${WORKSPACE_ROOT}/skills/${e.skill.name}/${t.relativePath}`})}async function removeSkillPackageFromSandbox(e){assertSafeSkillPackageName(e.name),await e.sandbox.removePath({force:!0,path:`${WORKSPACE_ROOT}/skills/${e.name}`,recursive:!0})}function assertSafeSkillPackageName(e){if(e.length===0||e.startsWith(`.`)||e.includes(`/`)||e.includes(`\\`)||e.includes(`..`)||!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(e)||/^[A-Za-z]:/.test(e))throw Error(`Expected skill name to be a non-empty shell-safe path segment starting with an alphanumeric character and containing only alphanumerics, ".", "_", or "-".`)}function assertSafeSkillPackageFilePath(e){if(e===`SKILL.md`)throw Error(`Skill package files must not include "SKILL.md"; eve generates it.`);if(e.length===0||e.startsWith(`/`)||e.includes(`\\`)||/^[A-Za-z]:/.test(e)||e.split(`/`).some(e=>e.length===0||e===`.`||e===`..`))throw Error(`Expected skill package file paths to be relative POSIX paths.`)}function contentToBuffer(e){return typeof e==`string`?Buffer.from(e,`utf8`):Buffer.from(e)}function comparePaths(e,t){return e<t?-1:+(e>t)}export{assertSafeSkillPackageName,normalizeSkillPackage,removeSkillPackageFromSandbox,writeSkillPackageDirectory,writeSkillPackageToSandbox};
+import{dirname,join}from"node:path";import{mkdir,writeFile}from"node:fs/promises";import{resolveSandboxSkillRoot,resolveSandboxSkillWritePath}from"#shared/skill-paths.js";import{Buffer}from"node:buffer";function normalizeSkillPackage(e){assertSafeSkillPackageName(e.name);let t=[{content:Buffer.from(e.markdown,`utf8`),relativePath:`SKILL.md`}];for(let[n,r]of Object.entries(e.files??{}))assertSafeSkillPackageFilePath(n),t.push({content:contentToBuffer(r),relativePath:n});return t.sort((e,t)=>comparePaths(e.relativePath,t.relativePath)),{description:e.description,files:t,license:e.license,markdown:e.markdown,metadata:e.metadata===void 0?void 0:{...e.metadata},name:e.name}}async function writeSkillPackageDirectory(i){for(let a of i.skill.files){let o=join(i.rootPath,`skills`,i.skill.name,a.relativePath);await mkdir(dirname(o),{recursive:!0}),await writeFile(o,a.content)}}async function writeSkillPackageToSandbox(e){for(let t of e.skill.files)await e.sandbox.writeBinaryFile({content:t.content,path:await resolveSandboxSkillWritePath({name:e.skill.name,relativePath:t.relativePath,sandbox:e.sandbox})})}async function removeSkillPackageFromSandbox(e){assertSafeSkillPackageName(e.name);let t=await resolveSandboxSkillRoot({sandbox:e.sandbox});await e.sandbox.removePath({force:!0,path:`${t}/${e.name}`,recursive:!0})}function assertSafeSkillPackageName(e){if(e.length===0||e.startsWith(`.`)||e.includes(`/`)||e.includes(`\\`)||e.includes(`..`)||!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(e)||/^[A-Za-z]:/.test(e))throw Error(`Expected skill name to be a non-empty shell-safe path segment starting with an alphanumeric character and containing only alphanumerics, ".", "_", or "-".`)}function assertSafeSkillPackageFilePath(e){if(e===`SKILL.md`)throw Error(`Skill package files must not include "SKILL.md"; eve generates it.`);if(e.length===0||e.startsWith(`/`)||e.includes(`\\`)||/^[A-Za-z]:/.test(e)||e.split(`/`).some(e=>e.length===0||e===`.`||e===`..`))throw Error(`Expected skill package file paths to be relative POSIX paths.`)}function contentToBuffer(e){return typeof e==`string`?Buffer.from(e,`utf8`):Buffer.from(e)}function comparePaths(e,t){return e<t?-1:+(e>t)}export{assertSafeSkillPackageName,normalizeSkillPackage,removeSkillPackageFromSandbox,writeSkillPackageDirectory,writeSkillPackageToSandbox};

package/dist/src/shared/skill-paths.d.ts

@@ -0,0 +1,28 @@
+import type { SandboxSession } from "#shared/sandbox-session.js";
+export declare const MODEL_SKILL_ROOT = "$HOME/.agents/skills";
+export declare const FALLBACK_SKILL_ROOT = "/workspace/skills";
+export declare function formatSkillModelPath(input: {
+    readonly name: string;
+    readonly relativePath: string;
+}): string;
+export declare function formatFallbackSkillPath(input: {
+    readonly name: string;
+    readonly relativePath: string;
+}): string;
+export declare function resolveSandboxSkillRoot(input: {
+    readonly sandbox: SandboxSession;
+}): Promise<string>;
+export declare function resolveSandboxSkillReadPaths(input: {
+    readonly name: string;
+    readonly relativePath: string;
+    readonly sandbox: SandboxSession;
+}): Promise<readonly string[]>;
+export declare function resolveSandboxSkillWritePath(input: {
+    readonly name: string;
+    readonly relativePath: string;
+    readonly sandbox: SandboxSession;
+}): Promise<string>;
+export declare function resolveSandboxSeedFilePath(input: {
+    readonly path: string;
+    readonly sandbox: SandboxSession;
+}): Promise<string>;

package/dist/src/shared/skill-paths.js

@@ -0,0 +1,2 @@
+const MODEL_SKILL_ROOT=`$HOME/.agents/skills`,FALLBACK_SKILL_ROOT=`/workspace/skills`,skillRootCache=new WeakMap;function formatSkillModelPath(t){return formatSkillPath({name:t.name,relativePath:t.relativePath,root:MODEL_SKILL_ROOT})}function formatFallbackSkillPath(e){return formatSkillPath({name:e.name,relativePath:e.relativePath,root:FALLBACK_SKILL_ROOT})}async function resolveSandboxSkillRoot(e){let t=skillRootCache.get(e.sandbox);if(t!==void 0)return await t;let r=probeSandboxSkillRoot(e.sandbox);return skillRootCache.set(e.sandbox,r),await r}async function resolveSandboxSkillReadPaths(e){return[formatSkillPath({name:e.name,relativePath:e.relativePath,root:await resolveSandboxSkillRoot({sandbox:e.sandbox})})]}async function resolveSandboxSkillWritePath(e){return formatSkillPath({name:e.name,relativePath:e.relativePath,root:await resolveSandboxSkillRoot({sandbox:e.sandbox})})}async function resolveSandboxSeedFilePath(e){return e.path.startsWith(`$HOME/.agents/skills/`)?`${await resolveSandboxSkillRoot({sandbox:e.sandbox})}${e.path.slice(20)}`:e.path}function formatSkillPath(e){return`${e.root}/${e.name}/${e.relativePath}`}async function probeSandboxSkillRoot(e){try{let n=await e.run({command:`printf '%s\\n' "$HOME"`});if(n.exitCode!==0)return FALLBACK_SKILL_ROOT;let r=n.stdout.trim();return isUsableSandboxHome(r)?joinHomeSkillRoot(r):FALLBACK_SKILL_ROOT}catch{return FALLBACK_SKILL_ROOT}}function isUsableSandboxHome(e){return e.length>0&&e.startsWith(`/`)&&!e.includes(`\0`)&&!e.includes(`
+`)&&!e.includes(`\r`)}function joinHomeSkillRoot(e){return`${e===`/`?``:e.replace(/\/+$/,``)}/.agents/skills`}export{FALLBACK_SKILL_ROOT,MODEL_SKILL_ROOT,formatFallbackSkillPath,formatSkillModelPath,resolveSandboxSeedFilePath,resolveSandboxSkillReadPaths,resolveSandboxSkillRoot,resolveSandboxSkillWritePath};

package/dist/src/shared/token-usage.d.ts

@@ -0,0 +1,22 @@
+import { z } from "#compiled/zod/index.js";
+/**
+ * Provider-reported token usage totals.
+ *
+ * The single usage shape across eve: harness accumulation
+ * (`turn-tag-state`), delegated subagent results, remote session
+ * callbacks, and usage spans all carry this type.
+ */
+export type TokenUsage = z.infer<typeof tokenUsageSchema>;
+/**
+ * Zod schema for {@link TokenUsage}.
+ *
+ * Validates the `usage` field of remote session callbacks, which may come
+ * from a callee on a different eve version — unknown keys are stripped
+ * rather than rejected so a newer sender never voids the whole payload.
+ */
+export declare const tokenUsageSchema: z.ZodObject<{
+    cacheReadTokens: z.ZodNumber;
+    cacheWriteTokens: z.ZodNumber;
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+}, z.core.$strip>;

package/dist/src/shared/token-usage.js

@@ -0,0 +1 @@
+import{z}from"#compiled/zod/index.js";const tokenUsageSchema=z.object({cacheReadTokens:z.number().int().nonnegative(),cacheWriteTokens:z.number().int().nonnegative(),inputTokens:z.number().int().nonnegative(),outputTokens:z.number().int().nonnegative()});export{tokenUsageSchema};

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

@@ -6,7 +6,7 @@ import type { JsonObject } from "#shared/json.js";
  * function. These are the same options the SDK passes to every tool call.
  */
 export type ToolExecuteOptions = Omit<ToolExecutionOptions<unknown>, "context">;
-export type ToolExecuteFn<TInput = unknown, TOutput = unknown> = (input: TInput, options?: ToolExecuteOptions) => Promise<TOutput> | TOutput;
+export type ToolExecuteFn<TInput = unknown, TOutput = unknown> = (input: TInput, options: ToolExecuteOptions) => Promise<TOutput> | TOutput;
 interface ToolDefinitionBase {
     readonly description: string;
 }

package/dist/src/svelte/index.js

@@ -1,3 +1,3 @@
-import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-Bh1NmXO9.js";
+import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-CxcKypLZ.js";
 
 export { defaultMessageReducer, useEveAgent };

package/dist/src/svelte/use-eve-agent.js

@@ -1,3 +1,3 @@
-import { t as useEveAgent } from "../chunks/use-eve-agent-Bh1NmXO9.js";
+import { t as useEveAgent } from "../chunks/use-eve-agent-CxcKypLZ.js";
 
 export { useEveAgent };

package/dist/src/vue/index.js

@@ -1,3 +1,3 @@
-import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-Dvy_Wjvq.js";
+import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-CM24ZUEI.js";
 
 export { defaultMessageReducer, useEveAgent };

package/dist/src/vue/use-eve-agent.js

@@ -1,3 +1,3 @@
-import { t as useEveAgent } from "../chunks/use-eve-agent-Dvy_Wjvq.js";
+import { t as useEveAgent } from "../chunks/use-eve-agent-CM24ZUEI.js";
 
 export { useEveAgent };

package/docs/agent-config.md

@@ -93,13 +93,30 @@ export default defineAgent({
 
 Input and output budgets are checked independently. The model call that crosses
 either limit is allowed to finish because providers only report exact token
-usage after a call completes. Follow-up model calls in the same session fail
-with `SESSION_TOKEN_LIMIT_REACHED`.
-
-When `maxInputTokensPerSession` is omitted, eve applies a default input budget:
-`40_000_000` provider-reported input tokens for root sessions and `5_000_000`
-for delegated subagent sessions. `maxOutputTokensPerSession` is unset unless
-configured.
+usage after a call completes. Before the next model call, eve pauses the
+session and sends a deterministic continuation prompt with two options:
+**Continue** grants a fresh budget window of the configured size (both input
+and output windows reset together), and **Stop** ends the session gracefully
+(`session.completed`) — declining is a user decision, not an error. A reply
+that answers neither option re-raises the prompt; the reply stays in history
+and is processed once the budget is granted.
+
+Sessions that cannot reach a human — task-mode runs such as schedules and
+subagents without input proxying — skip the prompt and fail the next model
+call with `SESSION_TOKEN_LIMIT_REACHED`.
+
+When `maxInputTokensPerSession` is omitted, root sessions apply a default
+input budget of `40_000_000` provider-reported input tokens.
+`maxOutputTokensPerSession` is unset unless configured. Setting either limit
+to `false` uncaps that axis — the session never stops on it.
+
+Delegated subagent sessions have no fixed default. Each child receives a
+share of the delegating parent's remaining quota at dispatch time — the
+remainder (limit minus accumulated usage) split evenly across the batch's
+local subagent calls — and a completed child's usage counts against the
+parent's quota, so a delegation tree can never outspend the budget configured
+at its root. An authored child limit applies only when it is tighter than the
+parent's grant; an uncapped parent delegates uncapped children.
 
 ## Workflow world
 
@@ -142,14 +159,14 @@ installed package must stay external in hosted output, list it in
 
 `defineAgent` takes a few more fields, all optional. For the exported types, see the [TypeScript API](./reference/typescript-api).
 
-| Field          | Type                                    | Default          | Description                                                                                                                                                                                                                                        |
-| -------------- | --------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `reasoning`    | `AgentReasoningDefinition`              | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls.                                                                                                                                                                      |
-| `modelOptions` | `AgentModelOptionsDefinition`           | none             | Provider option overrides forwarded to the model call.                                                                                                                                                                                             |
-| `limits`       | `AgentLimitsDefinition`                 | field-specific   | Framework-owned runtime limits. `maxSubagentDepth` defaults to `3`; `maxInputTokensPerSession` defaults to `40_000_000` for root sessions and `5_000_000` for delegated subagent sessions; `maxOutputTokensPerSession` is unset unless configured. |
-| `experimental` | `{ workflow?: { world?: string } }`     | unset            | Opt-in settings that can change or disappear in any release. Treat them as unstable. `workflow.world` selects the Workflow world package backing session state, queues, hooks, and streams on the root agent.                                      |
-| `outputSchema` | Standard Schema or a JSON Schema object | none             | Structured return type for task-mode runs (a subagent, schedule, or remote job). Interactive conversation turns ignore it unless the client supplies a per-message schema.                                                                         |
-| `build`        | `{ externalDependencies?: string[] }`   | none             | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output.                                           |
+| Field          | Type                                    | Default          | Description                                                                                                                                                                                                                                                                                                    |
+| -------------- | --------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `reasoning`    | `AgentReasoningDefinition`              | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls.                                                                                                                                                                                                                                  |
+| `modelOptions` | `AgentModelOptionsDefinition`           | none             | Provider option overrides forwarded to the model call.                                                                                                                                                                                                                                                         |
+| `limits`       | `AgentLimitsDefinition`                 | field-specific   | Framework-owned runtime limits. `maxSubagentDepth` defaults to `3`; `maxInputTokensPerSession` defaults to `40_000_000` for root sessions, and delegated subagent sessions inherit the parent's remaining quota; `maxOutputTokensPerSession` is unset unless configured; `false` uncaps a session token limit. |
+| `experimental` | `{ workflow?: { world?: string } }`     | unset            | Opt-in settings that can change or disappear in any release. Treat them as unstable. `workflow.world` selects the Workflow world package backing session state, queues, hooks, and streams on the root agent.                                                                                                  |
+| `outputSchema` | Standard Schema or a JSON Schema object | none             | Structured return type for task-mode runs (a subagent, schedule, or remote job). Interactive conversation turns ignore it unless the client supplies a per-message schema.                                                                                                                                     |
+| `build`        | `{ externalDependencies?: string[] }`   | none             | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output.                                                                                                       |
 
 `externalDependencies` is a packaging control only. It keeps selected packages as runtime dependencies in the hosted output; it does not authorize, configure, or review any third-party service those packages may call.
 

package/docs/channels/chat-sdk.mdx

@@ -0,0 +1,209 @@
+---
+title: "Chat SDK"
+description: "Bridge any Vercel Chat SDK adapter — Slack, Discord, Telegram, WhatsApp, email, and more — to your agent through one channel, using your own credentials and state store."
+---
+
+The Chat SDK channel connects your agent to any [Vercel Chat SDK](https://chat-sdk.dev) adapter. You pick an adapter (`@chat-adapter/slack`, `@resend/chat-sdk-adapter`, and so on), register handlers for the messages you care about, and call `send` to hand each turn to eve. Use it to reach a surface eve does not ship a first-class channel for, or when you want to manage credentials and state with the Chat SDK's own primitives rather than [Vercel Connect](../guides/auth-and-route-protection). See [Channels](./overview) for the contract this builds on.
+
+You supply an adapter and a state store: the adapter owns provider auth, webhook verification, and delivery, while eve owns session dispatch, streaming, typing, and human-in-the-loop. First-class channels such as [Slack](./slack) manage credentials through Vercel Connect instead — reach for whichever fits the surface you are targeting.
+
+## Install
+
+Add eve, the Chat SDK core (`chat`), an adapter, and a state adapter. The example below uses the Resend email adapter with the in-memory state store:
+
+```bash
+npm install eve@latest chat @resend/chat-sdk-adapter @chat-adapter/state-memory
+```
+
+Swap in whichever adapter matches your surface — `@chat-adapter/slack`, `@chat-adapter/discord`, `@chat-adapter/telegram`, and so on. Any Chat SDK adapter works.
+
+## Add the channel
+
+`chatSdkChannel` returns `{ bot, channel, send }`. Register Chat SDK handlers on `bot`, call `send` from those handlers to start or resume an eve session, and export `channel` as the module default:
+
+```ts title="agent/channels/resend.ts"
+import { createMemoryState } from "@chat-adapter/state-memory";
+import { createResendAdapter } from "@resend/chat-sdk-adapter";
+import type { Message, Thread } from "chat";
+import { chatSdkChannel } from "eve/channels/chat-sdk";
+
+export const { bot, channel, send } = chatSdkChannel({
+  userName: "Resend Bot",
+  adapters: {
+    resend: createResendAdapter({
+      fromAddress: "hello@example.com",
+      fromName: "Resend Bot",
+    }),
+  },
+  state: createMemoryState(),
+  streaming: false,
+});
+
+bot.onNewMention(async (thread: Thread, message: Message) => {
+  await thread.subscribe();
+  await send(message.text, { thread });
+});
+
+bot.onSubscribedMessage(async (thread: Thread, message: Message) => {
+  await send(message.text, { thread });
+});
+
+export default channel;
+```
+
+`adapters` is a map of adapter name to adapter instance; each entry mounts its own webhook (see below). `state` takes any Chat SDK state adapter: `createMemoryState()` is fine for local development, but use a durable adapter (Redis, Upstash, etc.) in production so thread subscriptions and inbound deduplication survive restarts. `send` accepts a plain string, an AI SDK `UserContent` array, or a `SendPayload`, and must be called from inside a Chat SDK handler — it dispatches the turn on the webhook that is currently running.
+
+Deploy once the channel file is in place:
+
+```bash
+eve deploy
+```
+
+`eve deploy` links the project if needed and deploys to Vercel production.
+
+## Configure the webhook route
+
+Each adapter mounts one `POST` route at `/eve/v1/{adapterName}`, so the `resend` adapter above is served at `/eve/v1/resend`. Point your provider's webhook (the Resend inbound address, the Slack Event Subscriptions URL, etc.) at that path.
+
+Override the base path for every adapter with `route`, or pin an individual adapter's path with `routes`:
+
+```ts
+export const { bot, channel, send } = chatSdkChannel({
+  userName: "Resend Bot",
+  adapters: { resend: createResendAdapter({ fromAddress: "hello@example.com" }) },
+  state: createMemoryState(),
+  route: "/webhooks", // resend now mounts at /webhooks/resend
+  routes: { resend: "/webhooks/inbound-email" }, // …or pin it exactly
+});
+```
+
+Use `routes` when a provider requires a fixed URL or when you are migrating an existing endpoint without changing the provider's settings.
+
+## How the channel handles messages
+
+### Dispatch
+
+You choose which Chat SDK events start a turn by registering handlers on `bot` and calling `send`:
+
+- `bot.onNewMention(thread, message)` fires on a fresh `@mention` (or, for surfaces like email, a new inbound thread). Call `thread.subscribe()` when you want later replies in the same thread to keep reaching the agent.
+- `bot.onSubscribedMessage(thread, message)` fires on subsequent messages in a subscribed thread.
+- `bot.onAction`, `bot.onReaction`, and `bot.onSlashCommand` are available for adapters that emit them.
+
+`send(input, options)` starts or resumes the eve session. The `thread` you pass determines the continuation token and the persisted channel state, so replies land back on the originating thread:
+
+```ts
+bot.onNewMention(async (thread, message) => {
+  await send(message.text, { thread, title: "Support request" });
+});
+```
+
+`options` accepts `{ thread, auth?, title?, mode?, callback?, adapterName? }`. `title` sets the eve session's display title without changing the model message; `auth` attaches an authenticated principal to the turn.
+
+### Delivery
+
+The default handlers post the agent's reply back to the thread — no `events` override required. Completed assistant messages are posted as markdown (`{ markdown: … }`) so adapters render rich text and email HTML rather than a raw string.
+
+Streaming is on by default: the channel posts an initial message and edits it as tokens arrive (`message.appended`), throttled by `streamingEditIntervalMs` (default `1000`). Set `streaming: false` for surfaces that deliver one message per turn — email, for example — so the reply posts once on completion instead of editing:
+
+```ts
+chatSdkChannel({
+  userName: "Resend Bot",
+  adapters: { resend: createResendAdapter({ fromAddress: "hello@example.com" }) },
+  state: createMemoryState(),
+  streaming: false,
+});
+```
+
+Typing indicators post automatically where the adapter supports them: `Working…` on `turn.started`, and tool status on `actions.requested`.
+
+### Optional capabilities degrade gracefully
+
+Adapters do not all implement every operation. When an adapter's `startTyping` or `editMessage` throws a `NotImplementedError` (or an error with code `NOT_IMPLEMENTED`), the channel swallows it: typing indicators are skipped, and a streaming edit falls back to a single final post for the rest of the session. You never have to guard optional capabilities in your own handlers. The same predicate is exported as `isNotImplemented` if you want it in custom `events`:
+
+```ts
+import { isNotImplemented } from "eve/channels/chat-sdk";
+```
+
+Override any default by passing `events`. Handlers receive `(eventData, channel, ctx)`, with the rebuilt Chat SDK thread on `channel.thread`:
+
+```ts
+chatSdkChannel({
+  userName: "Resend Bot",
+  adapters: { resend: createResendAdapter({ fromAddress: "hello@example.com" }) },
+  state: createMemoryState(),
+  events: {
+    "message.completed"(eventData, channel) {
+      if (eventData.finishReason === "tool-calls" || !eventData.message || !channel.thread) return;
+      return channel.thread.post({ markdown: eventData.message });
+    },
+  },
+});
+```
+
+### Human-in-the-loop (HITL)
+
+HITL prompts render as a Chat SDK `Card` with buttons. Button clicks resume the parked session automatically — the channel wires `bot.onAction` for you. Change the action-id prefix with `inputActionPrefix` (default `eve_input:`) if your app already uses it, and provide `resolveInputAuth` to carry user or tenant auth across the resume:
+
+```ts
+chatSdkChannel({
+  userName: "Support Bot",
+  adapters: { slack: createSlackAdapter() },
+  state: createMemoryState(),
+  resolveInputAuth: (event) => ({
+    authenticator: "slack",
+    principalType: "user",
+    principalId: event.user?.userId ?? "unknown",
+    attributes: {},
+  }),
+});
+```
+
+### Proactive sessions
+
+Start a session without an inbound webhook through `channel.receive({ message, target, auth })` — from a schedule `run` handler, or `args.receive(channel, ...)` from another channel. The target is a serialized Chat SDK thread, or `{ threadId, adapterName }` when you only have a provider-native thread id:
+
+```ts
+await channel.receive({
+  message: "Your weekly digest is ready.",
+  target: { adapterName: "resend", threadId: "resend:user@example.com" },
+  auth: null,
+});
+```
+
+### Attachments
+
+`send` takes plain text or an AI SDK `UserContent` array. To forward a Chat SDK message's attachments, convert it with `messageToUserContent`, which returns `message.text` when there are no attachments and a `UserContent` array (text plus one file part per attachment URL) when there are:
+
+```ts
+import { messageToUserContent } from "eve/channels/chat-sdk";
+
+bot.onNewMention(async (thread, message) => {
+  await send(messageToUserContent(message), { thread });
+});
+```
+
+See [File uploads](./custom#file-uploads) for how eve stages remote file URLs before the model call.
+
+## Configuration reference
+
+| Option                    | Default      | Purpose                                                                  |
+| ------------------------- | ------------ | ------------------------------------------------------------------------ |
+| `adapters`                | —            | Map of adapter name to Chat SDK adapter instance. One webhook per entry. |
+| `state`                   | —            | Chat SDK state adapter for subscriptions, locks, and dedupe.             |
+| `userName`                | —            | Display name for the bot (a standard Chat SDK `ChatConfig` field).       |
+| `route`                   | `/eve/v1`    | Base path for generated adapter webhooks (`{route}/{adapter}`).          |
+| `routes`                  | —            | Per-adapter path overrides for fixed or migrated webhook URLs.           |
+| `streaming`               | `true`       | Post-then-edit streaming. Set `false` for one-message-per-turn surfaces. |
+| `streamingEditIntervalMs` | `1000`       | Minimum interval between streaming edits.                                |
+| `events`                  | built-in     | Per-event handlers. A supplied handler replaces that built-in default.   |
+| `inputActionPrefix`       | `eve_input:` | Prefix for default HITL button action ids.                               |
+| `resolveInputAuth`        | `null`       | Auth resolver applied when a HITL button click resumes a session.        |
+| `webhook`                 | —            | Extra Chat SDK webhook options (eve owns `waitUntil`).                   |
+
+Any other Chat SDK `ChatConfig` field (for example `concurrency`) is accepted and passed through.
+
+## What to read next
+
+- [Channels overview](./overview): the channel contract and every built-in channel
+- [Custom channels](./custom): build a channel for any surface with `defineChannel`
+- [Auth & route protection](../guides/auth-and-route-protection): authenticating inbound traffic

package/docs/channels/meta.json

@@ -10,6 +10,7 @@
     "twilio",
     "github",
     "linear",
+    "chat-sdk",
     "custom"
   ]
 }