eve 0.30.8 → 0.31.0

package/docs/guides/frontend/use-eve-agent-vue.mdx

@@ -25,16 +25,17 @@ const { data } = useEveAgent();
 
 ## What it returns
 
-| Property  | Type                                         | Description                                                               |
-| --------- | -------------------------------------------- | ------------------------------------------------------------------------- |
-| `data`    | `ComputedRef<TData>`                         | Projected state. With the default reducer, `EveMessageData` (`messages`). |
-| `status`  | `ComputedRef<UseEveAgentStatus>`             | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`.                    |
-| `error`   | `ComputedRef<Error \| undefined>`            | Last transport-level error.                                               |
-| `events`  | `ComputedRef<readonly MessageStreamEvent[]>` | Raw server events for this session.                                       |
-| `session` | `ComputedRef<SessionState>`                  | Snapshot of session state.                                                |
-| `send`    | `(input: SendTurnPayload) => Promise<void>`  | Send text or a full turn (multi-part, attachments, HITL responses).       |
-| `stop`    | `() => void`                                 | Abort the client's in-flight stream.                                      |
-| `reset`   | `() => void`                                 | Clear state and start a new session.                                      |
+| Property  | Type                                           | Description                                                               |
+| --------- | ---------------------------------------------- | ------------------------------------------------------------------------- |
+| `data`    | `ComputedRef<TData>`                           | Projected state. With the default reducer, `EveMessageData` (`messages`). |
+| `status`  | `ComputedRef<UseEveAgentStatus>`               | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`.                    |
+| `error`   | `ComputedRef<Error \| undefined>`              | Last transport-level error.                                               |
+| `events`  | `ComputedRef<readonly MessageStreamEvent[]>`   | Raw server events for this session.                                       |
+| `session` | `ComputedRef<ClientSessionState \| undefined>` | Fixed session ID and stream cursor.                                       |
+| `send`    | `(message, options?) => Promise<void>`         | Send text or a multi-part message.                                        |
+| `respond` | `(inputResponses, options?) => Promise<void>`  | Answer pending HITL input requests.                                       |
+| `stop`    | `() => void`                                   | Abort the client's in-flight stream.                                      |
+| `reset`   | `() => void`                                   | Clear state and start a new session.                                      |
 
 The first five are `ComputedRef`s; the rest are methods. Destructure whatever you need, since refs keep their reactivity through destructuring. Read them with `.value` in `<script>`, and unwrapped in `<template>`.
 
@@ -52,7 +53,7 @@ async function handleSubmit() {
   const text = message.value.trim();
   if (!text) return;
   message.value = "";
-  await send({ message: text });
+  await send(text);
 }
 </script>
 
@@ -77,24 +78,22 @@ async function onFileChange(event: Event) {
   if (!file) return;
   const bytes = new Uint8Array(await file.arrayBuffer());
   const base64 = btoa(String.fromCodePoint(...bytes));
-  await send({
-    message: [
-      { type: "text", text: "Describe this image." },
-      { type: "file", data: `data:${file.type};base64,${base64}`, mediaType: file.type },
-    ],
-  });
+  await send([
+    { type: "text", text: "Describe this image." },
+    { type: "file", data: `data:${file.type};base64,${base64}`, mediaType: file.type },
+  ]);
 }
 </script>
 ```
 
 ## Human-in-the-loop prompts
 
-A tool opts into approval with `approval` ([Tools](../../tools)). When it triggers, the pending request shows up as a `dynamic-tool` part on the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `send({ inputResponses })`:
+A tool opts into approval with `approval` ([Tools](../../tools)). When it triggers, the pending request shows up as a `dynamic-tool` part on the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `respond(inputResponses)`:
 
 ```ts
 import type { EveDynamicToolPart, EveMessagePart } from "eve/vue";
 
-const { data, send } = useEveAgent();
+const { data, respond } = useEveAgent();
 
 const isDynamicToolPart = (part: EveMessagePart): part is EveDynamicToolPart =>
   part.type === "dynamic-tool";
@@ -106,9 +105,7 @@ const request = data.value.messages
   .find((value) => value !== undefined);
 
 if (request) {
-  await send({
-    inputResponses: [{ requestId: request.requestId, optionId: "approve" }],
-  });
+  await respond([{ requestId: request.requestId, optionId: "approve" }]);
 }
 ```
 
@@ -143,11 +140,10 @@ const agent = useEveAgent({
 
 ## Attach page context per turn
 
-`clientContext` adds ephemeral context for the next model call and nothing more. Strings (or an array of strings) become user-role context messages; an object is JSON-serialized into one. It rides along with a message or HITL response, never dispatches a turn on its own, and never lands in durable session history. Pass it to `send()`:
+`clientContext` adds ephemeral context for the next model call and nothing more. Strings (or an array of strings) become user-role context messages; an object is JSON-serialized into one. It rides along with a message or HITL response, never dispatches a turn on its own, and never lands in durable session history. Pass it in the second argument to `send()` or `respond()`:
 
 ```ts
-await send({
-  message: "What should I do on this screen?",
+await send("What should I do on this screen?", {
   clientContext: { route: "/billing", plan: "pro", seatsUsed: 4 },
 });
 ```

package/docs/guides/instrumentation.md

@@ -181,7 +181,7 @@ When `eve build` fails on discovery errors, the CLI prints the full diagnostics
 | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Tool not discovered (the model never sees it) | Run `eve info`. Confirm the file is in the right slot (`agent/tools/<name>.ts`) and default-exports `defineTool(...)`, and check `.eve/diagnostics.json` for shape errors. `schedules/` are root-only.                                                                      |
 | Model won't call a tool it should             | Tighten the tool `description` and `inputSchema`; put procedural guidance in a [skill](../skills), not the description. Confirm it's in the active set with `eve info`.                                                                                                     |
-| Stuck on `session.waiting`                    | The turn is parked on an approval, a question, or a connection sign-in. Answer it, or POST a follow-up with the `continuationToken` (a stale token is rejected).                                                                                                            |
+| Stuck on `session.waiting`                    | The turn is parked for input. Answer the pending approval or question, or POST a follow-up to `/eve/v1/session/:sessionId`.                                                                                                                                                 |
 | 401 on production routes                      | Expected: auth fails closed. Replace `placeholderAuth()` with your route policy. Use `vercelOidc()` only for Vercel-issued tokens; otherwise configure `httpBasic()`, JWT/OIDC helpers, or a custom `AuthFn`. See [Auth and route protection](./auth-and-route-protection). |
 | Build fails with discovery errors             | Read the printed diagnostics and `.eve/diagnostics.json`; confirm the root-vs-subagent boundary is valid and secrets come from env vars.                                                                                                                                    |
 

package/docs/patterns/dynamic-scheduling.md

@@ -35,7 +35,7 @@ import { scheduleStore } from "../lib/schedule-store";
 
 export default defineSchedule({
   cron: "* * * * *",
-  run({ receive, waitUntil }) {
+  run({ to, waitUntil }) {
     waitUntil(
       (async () => {
         const jobs = await scheduleStore.claimDue({
@@ -47,25 +47,26 @@ export default defineSchedule({
         await Promise.all(
           jobs.map(async (job) => {
             try {
-              await receive(slack, {
-                message: [
+              await to(slack, { channelId: job.channelId }).send(
+                [
                   `Run dynamic schedule ${job.id}.`,
                   "Complete this tenant-owned task:",
                   job.prompt,
                 ].join("\n\n"),
-                target: { channelId: job.channelId },
-                auth: {
-                  attributes: {
-                    tenantId: job.tenantId,
-                    role: job.ownerRole,
-                    scheduleId: job.id,
+                {
+                  auth: {
+                    attributes: {
+                      tenantId: job.tenantId,
+                      role: job.ownerRole,
+                      scheduleId: job.id,
+                    },
+                    authenticator: job.authenticator,
+                    ...(job.issuer ? { issuer: job.issuer } : {}),
+                    principalId: job.ownerId,
+                    principalType: "user",
                   },
-                  authenticator: job.authenticator,
-                  ...(job.issuer ? { issuer: job.issuer } : {}),
-                  principalId: job.ownerId,
-                  principalType: "user",
                 },
-              });
+              );
               await scheduleStore.complete(job);
             } catch (error) {
               await scheduleStore.release(job, { error, retryAt: new Date(Date.now() + 300_000) });
@@ -78,7 +79,7 @@ export default defineSchedule({
 });
 ```
 
-`waitUntil` keeps the cron invocation alive until claiming and handoff settle. `receive` starts the same durable runtime used by inbound channel messages.
+`waitUntil` keeps the cron invocation alive until claiming and handoff settle. `to(...).send(...)` starts the same durable runtime used by inbound channel messages.
 
 This example uses Slack because it has a proactive target of `{ channelId }`. Any channel that implements `receive` can replace it.
 

package/docs/schedules.mdx

@@ -19,7 +19,7 @@ interface ScheduleDefinition {
 }
 
 interface ScheduleHandlerArgs {
-  receive: CrossChannelReceiveFn; // hand the work off to a channel
+  to: ScheduleToFn; // select a channel target, then send
   waitUntil: (task: Promise<unknown>) => void; // keep the cron task alive past return
   appAuth: SessionAuthContext; // pre-built app principal
 }
@@ -56,7 +56,7 @@ Sweep stale workflow state.
 
 ## Handler form (`run`)
 
-Use a handler when the schedule needs to deliver to a channel, branch on conditions, or compute its arguments at fire time. The handler is in full control. It has no channel of its own, so it passes the work to one with `receive`.
+Use a handler when the schedule needs to deliver to a channel, branch on conditions, or compute its arguments at fire time. The handler is in full control. It has no channel of its own, so it selects a channel target with `to(...)` and sends through the returned handle.
 
 ```ts title="agent/schedules/critical-alerts.ts"
 import { defineSchedule } from "eve/schedules";
@@ -65,13 +65,12 @@ import slack from "../channels/slack";
 
 export default defineSchedule({
   cron: "* * * * *",
-  async run({ receive, waitUntil, appAuth }) {
+  async run({ to, waitUntil, appAuth }) {
     waitUntil(
-      receive(slack, {
-        message: "Check for new critical alerts. Report only when there are any.",
-        target: { channelId: "C0123ABC" },
-        auth: appAuth,
-      }),
+      to(slack, { channelId: "C0123ABC" }).send(
+        "Check for new critical alerts. Report only when there are any.",
+        { auth: appAuth },
+      ),
     );
   },
 });
@@ -79,9 +78,9 @@ export default defineSchedule({
 
 The agent does not have to deliver a message on every run. When a prompt makes delivery conditional, as in the alert check above, eve tells the agent how to finish successfully without sending anything to the channel. Frequent polling schedules do not need a separate filter or delivery setting.
 
-- `receive(channel, { message, target, auth })`: starts a session on another channel. Same contract as a route handler's `args.receive`.
-- `waitUntil(promise)`: extends the cron task's lifetime so the parked session and any in-flight fetches settle before the task ends. Wrap the `receive` call in it.
-- `appAuth`: the app principal (`{ authenticator: "app", principalId: "eve:app", principalType: "runtime" }`). Pass it as `receive(..., { auth: appAuth })` for work the agent does on its own behalf.
+- `to(channel, target).send(message, { auth })`: starts a session on another channel. It has the same contract as a route handler's `ctx.to(...)` handle.
+- `waitUntil(promise)`: extends the cron task's lifetime so the parked session and any in-flight fetches settle before the task ends. Wrap the `send` call in it.
+- `appAuth`: the app principal (`{ authenticator: "app", principalId: "eve:app", principalType: "runtime" }`). Pass it as `to(...).send(..., { auth: appAuth })` for work the agent does on its own behalf.
 
 A handler-form session runs on the same durable runtime engine as any other session, so it can park (durably suspend), for instance when the channel handoff is waiting for a Slack reply. Only markdown task mode is barred from waiting.
 

package/docs/subagents.mdx

@@ -192,7 +192,7 @@ Without the opt-in, delegated children run as one-shot tasks: they answer once a
 
 With it enabled, a child parks after answering instead of terminating, keeping its session and conversation history alive. A failed child turn can also leave the child parked — its latest status shows the error and the parent may message it again. Pass a parked child's `agentId` to the same subagent tool with a new `message` to continue that session. Omitting `agentId` (or passing an empty string or `null`) always starts a new child, and an `agentId` that matches no known agent falls back to starting a new child rather than failing. Passing a known `agentId` through a different subagent tool fails with `AGENT_MISMATCH`, and messaging a child that is still starting or working on its previous request fails with `AGENT_BUSY` — wait for its result before continuing it.
 
-On every model call, eve injects a system message containing an `<agents>` block listing the currently parked (resumable) children — each entry carries the `agentId`, name, and latest status. It is a per-call injection, not part of the conversation history: it always reflects the current state, never accumulates stale copies, and children that are starting or running do not appear until they park again.
+Whenever the set of parked (resumable) children changes, eve appends a framework-injected note to the conversation — labeled `[Agents]` and carrying an `<agents>` block — listing each child's `agentId`, name, and latest status. The static system prompt tells the model the note is injected by eve, not written by the user. The note is appended only when the listing changes (an append-only design that preserves the provider prompt cache), the most recent note is authoritative, and children that are starting or running do not appear until they park again.
 
 The parent holds agent handles only for its session lifetime. When the parent session ends, eve terminates its local children. Remote children are not terminated on parent shutdown — that is a known gap: a parked remote child stays alive on its own deployment until that deployment's own lifecycle ends it. For [remote agents](./guides/remote-agents), both deployments must run the same eve version to use agent messaging.
 

package/docs/tools/human-in-the-loop.md

@@ -58,7 +58,7 @@ Gating a side effect on approval is also how you make non-idempotent work safe a
 
 ### Skipping approval for schedule-dispatched turns
 
-`session.auth.current` identifies the caller of this turn. Markdown schedules use the app principal (`authenticator: "app"`, `principalId: "eve:app"`, `principalType: "runtime"`) automatically. A `run` schedule must pass its `appAuth` to `receive(...)` for the child session to use that principal. Match all three fields to skip approval for automated turns while still prompting when a person calls the same tool:
+`session.auth.current` identifies the caller of this turn. Markdown schedules use the app principal (`authenticator: "app"`, `principalId: "eve:app"`, `principalType: "runtime"`) automatically. A `run` schedule must pass its `appAuth` to `send(...)` for the child session to use that principal. Match all three fields to skip approval for automated turns while still prompting when a person calls the same tool:
 
 ```ts title="agent/tools/refund_charge.ts"
 import { defineTool } from "eve/tools";

package/docs/tutorial/ship-it.mdx

@@ -43,7 +43,7 @@ export function AgentChat() {
         event.preventDefault();
         const data = new FormData(event.currentTarget);
         const message = String(data.get("q") ?? "").trim();
-        if (message) void agent.send({ message });
+        if (message) void agent.send(message);
       }}
     >
       {agent.data.messages.map((message) => (

package/package.json

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

package/dist/src/channel/cancel.d.ts

@@ -1,6 +0,0 @@
-import type { CancelFn } from "#channel/routes.js";
-import type { Runtime } from "#channel/types.js";
-/**
- * Builds the route-handler `cancel` helper for one channel.
- */
-export declare function createCancelFn(runtime: Runtime, channelName: string): CancelFn;

package/dist/src/channel/cancel.js

@@ -1 +0,0 @@
-function createCancelFn(e,t){return async n=>await e.dispatchContinuation({command:{kind:`cancel`,turnId:n.turnId},continuationToken:`${t}:${n.continuationToken}`})}export{createCancelFn};

package/dist/src/channel/clear-session.d.ts

@@ -1,4 +0,0 @@
-import type { ClearFn } from "#channel/routes.js";
-import type { Runtime } from "#channel/types.js";
-/** Builds a channel-scoped context-clear helper. */
-export declare function createClearFn(runtime: Runtime, channelName: string): ClearFn;

package/dist/src/channel/clear-session.js

@@ -1 +0,0 @@
-function createClearFn(e,t){return async n=>await e.dispatchContinuation({command:{kind:`clear`},continuationToken:`${t}:${n.continuationToken}`})}export{createClearFn};

package/dist/src/channel/compact-session.d.ts

@@ -1,4 +0,0 @@
-import type { CompactFn } from "#channel/routes.js";
-import type { Runtime } from "#channel/types.js";
-/** Builds a channel-scoped manual compaction helper. */
-export declare function createCompactFn(runtime: Runtime, channelName: string): CompactFn;

package/dist/src/channel/compact-session.js

@@ -1 +0,0 @@
-function createCompactFn(e,t){return async n=>await e.dispatchContinuation({command:{kind:`compact`},continuationToken:`${t}:${n.continuationToken}`})}export{createCompactFn};

package/dist/src/channel/reset-session.d.ts

@@ -1,6 +0,0 @@
-import type { ResetFn } from "#channel/routes.js";
-import type { Runtime } from "#channel/types.js";
-/**
- * Builds a channel-scoped session reset helper.
- */
-export declare function createResetFn(runtime: Runtime, channelName: string): ResetFn;

package/dist/src/channel/reset-session.js

@@ -1 +0,0 @@
-function createResetFn(e,t){return async n=>{let r=`${t}:${n.continuationToken}`;return await e.dispatchContinuation({command:{kind:`reset`,reason:n.reason},continuationToken:r})}}export{createResetFn};

package/dist/src/channel/resolve-active-session.d.ts

@@ -1,4 +0,0 @@
-import type { ResolveActiveSessionFn } from "#channel/routes.js";
-import type { Runtime } from "#channel/types.js";
-/** Builds a channel-scoped lookup for the active owner of a continuation token. */
-export declare function createResolveActiveSessionFn(runtime: Runtime, channelName: string): ResolveActiveSessionFn;

package/dist/src/channel/resolve-active-session.js

@@ -1 +0,0 @@
-function createResolveActiveSessionFn(e,t){return({continuationToken:n})=>e.resolveContinuation(`${t}:${n}`)}export{createResolveActiveSessionFn};

package/dist/src/channel/send.d.ts

@@ -1,6 +0,0 @@
-import type { ChannelAdapter } from "#channel/adapter.js";
-import type { Runtime } from "#channel/types.js";
-import type { SendFn } from "#channel/routes.js";
-export declare function createSendFn<TState = undefined>(runtime: Runtime, adapter: ChannelAdapter<any>, channelName: string, metadata?: {
-    readonly requestId?: string;
-}): SendFn<TState>;

package/dist/src/channel/send.js

@@ -1 +0,0 @@
-import{createSession}from"#channel/session.js";import{RuntimeNoActiveSessionError,isRuntimeSessionOwnershipConflictError}from"#execution/runtime-errors.js";import{serializeUrlFilePart}from"#internal/attachments/url-refs.js";function createSendFn(r,i,a,o={}){return async(s,c)=>{let l=c,{auth:u,callback:d,caller:f,capabilities:p,initiatorAuth:m,state:h,title:g}=l,_=l.intent??`resume-or-start`,v=l.mode??`conversation`,y=l.continuationToken,b=`${a}:${y}`,{message:x,inputResponses:S,context:C,outputSchema:w}=normalizeSendInput(s),T=serializeUrlFilePartsInMessage(x),E={auth:u,caller:f,kind:`send`,payload:{inputResponses:S,message:T,context:C,outputSchema:w},requestId:o.requestId},dispatch=async()=>{let t=await r.dispatchContinuation({command:E,continuationToken:b});return t.status===`accepted`?createSession(t.sessionId,y,r):void 0},D=await dispatch();if(D!==void 0)return D;if(_===`resume`)throw new RuntimeNoActiveSessionError(b);if(S&&S.length>0)throw Error(`Cannot deliver inputResponses — the target session was not found via continuation token.`);let O={adapter:h?{...i,state:{...i.state,...h}}:i,auth:u,capabilities:p??(v===`conversation`?{requestInput:!0}:void 0),channelName:a,callback:d,continuationToken:b,input:{message:T??``,context:C,outputSchema:w},mode:v,requestId:o.requestId,title:g};m!==void 0&&(O.initiatorAuth=m);try{return createSession((await r.createSession(O)).sessionId,y,r)}catch(e){if(!isRuntimeSessionOwnershipConflictError(e))throw e;let t=await dispatch();if(t!==void 0)return t;throw e}}}function serializeUrlFilePartsInMessage(e){if(e===void 0||typeof e==`string`)return e;let t=!1,n=e.map(e=>e.type===`file`&&e.data instanceof URL&&e.data.protocol!==`data:`?(t=!0,{...e,data:serializeUrlFilePart(e.data)}):e);return t?n:e}function normalizeSendInput(e){return typeof e==`string`||Array.isArray(e)?{message:e}:e}export{createSendFn};