eve 0.84.1 → 0.85.0

package/docs/schedules.mdx

@@ -81,7 +81,7 @@ export default defineSchedule({
 
 Every run delivers the agent's reply to the channel. To skip a run when there is nothing to report, check that condition in the handler before calling `send`. When only the agent can tell, add the opt-in [`no_reply`](/docs/concepts/built-in-tools#no_reply) tool and ask the agent to call it when there is nothing to report; the run then posts nothing.
 
-- `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.
+- `to(channel, target).send(message, { auth, ...options })`: starts a session on another channel. It has the same contract and [options](./channels/custom#cross-channel-hand-off) 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.
 

package/docs/tools/overview.mdx

@@ -254,6 +254,8 @@ examples.
 - `ctx.messages`: the model input for the step that requested this call, the same messages a [dynamic capability's](/docs/guides/dynamic-capabilities) `ctx.messages()` returns before that call.
 - `ctx.abortSignal`: aborts when the active turn is cancelled. Pass it to cancellation-aware work; sandbox sessions from `ctx.getSandbox()` are already bound to it.
 - `ctx.getSandbox()`: the live [sandbox](/docs/sandbox) handle.
+- `ctx.channel`: the channel serving the session, as [hooks](/docs/guides/hooks) and [dynamic resolvers](/docs/guides/dynamic-capabilities) read it: `kind`, `continuationToken`, and `metadata`, what the channel's `metadata(state)` hook projects, such as a Slack thread's `channelId` and `threadTs`.
+- `ctx.to(channel, target)`: starts or continues a session on one of the agent's channels. See [Start channel sessions](#start-channel-sessions-ctxto).
 
 Running in the app runtime is what lets a tool import shared code from `lib/`, read `process.env`, and take part in eve’s durable pause/resume model.
 
@@ -261,6 +263,38 @@ eve never runs authored tools during discovery. The model sees descriptors first
 
 Use operation-specific idempotency keys for external writes such as charges or emails. Approval records consent; it does not deduplicate an operation. See [Crash recovery](/docs/concepts/execution-model-and-durability#resuming-after-a-crash).
 
+### Start channel sessions: `ctx.to`
+
+`ctx.to(channel, target).send(message, options)` starts a session on one of the agent's channels, or continues the one at that target, through the channel's `receive` hook. It's the same call as a route handler's [cross-channel hand-off](/docs/channels/custom#cross-channel-hand-off), with the same [options](/docs/channels/custom#cross-channel-hand-off), and returns the delivery, whose `sessionId` names the session. Use it when the model decides that work should continue somewhere people can follow it, such as a new Slack thread:
+
+```ts title="agent/tools/escalate.ts"
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import slack from "../channels/slack";
+
+export default defineTool({
+  description: "Hand this investigation to the on-call channel in Slack.",
+  inputSchema: z.object({ summary: z.string() }),
+  async execute({ summary }, ctx) {
+    const delivery = await ctx
+      .to(slack, { channelId: "C0123ABC" })
+      .send("Take over this investigation.", {
+        auth: ctx.session.auth.current,
+        history: [{ role: "user", text: summary }],
+        idempotencyKey: `${ctx.session.id}:${ctx.callId}`,
+      });
+    return { sessionId: delivery.sessionId };
+  },
+});
+```
+
+- The session belongs to the channel. People on that channel continue it, it has no parent, and it keeps running after the tool returns.
+- It runs the root agent with the `auth` you pass. Pass `ctx.session.auth.current` to start it as the caller.
+- A tool call that retries runs the tool again. Pass `` idempotencyKey: `${ctx.session.id}:${ctx.callId}` ``, and the session at the target gets the message once. The destination session dedupes keys from every sender, and `ctx.callId` alone is unique only within the calling session, so include the session id. Built-in channels map a retry to the same session, including a Slack target with only a `channelId`. A platform post made before the session exists, such as an `initialMessage`, repeats.
+- `ctx.to()` throws in a delegated session: a subagent, a root copy, or a remote agent call. A session it started would outlive the delegation and act for the caller, so return the result and send from a tool on the root agent.
+
+See [Fork conversations into a new thread](/docs/patterns/fork-conversations-into-new-threads) for a tool that copies the current conversation into a new Slack thread.
+
 ## When a tool throws
 
 If an authored tool's `execute` function throws, eve records the call as `call.settled` with `outcome: "failed"` and gives the error to the model as a tool error. The model can respond, choose another action, or call the tool again. eve does not automatically call the tool again based on the exception type, an upstream HTTP status, or a `retryable` property.

package/docs/tools/workflows.mdx

@@ -85,14 +85,14 @@ or days later, the run resumes, deploys, and returns. The model sees one tool re
   `start`, `getRun`, and `resumeHook` from `workflow/api` belong in steps. Your app does not install
   the SDK; for types, new projects list `eve/workflow-modules` in the tsconfig `types`.
 - In an `execute` or `task` body, `ctx` is a `WorkflowToolContext` with `session`, `callId`,
-  `toolName`, `abortSignal`, `agent`, `agents`, and `ask`. A `serve` body gets a
-  `WorkflowServeContext` with `session`, `toolName`,
+  `toolName`, `abortSignal`, `channel`, `agent`, `agents`, and `ask`. A `serve` body gets a
+  `WorkflowServeContext` with `session`, `toolName`, `channel`,
   `agent`, `agents`, `ask`, and `reply`; each call it receives carries its own `callId` and
   `abortSignal`.
   A `"use step"` helper that receives `ctx` directly gets a restricted `WorkflowStepToolContext` with
-  `session`, `callId`, `toolName`, `abortSignal`, `getSandbox`, `getToken`, and `requireAuth`. Read `ctx.agents`, call
-  `ctx.agent()`, and call `ctx.ask()` in the workflow body; pass only the serializable values the step needs.
-  Call `getSandbox`, `getToken`, and `requireAuth` in a step: the workflow body throws when it calls them.
+  `session`, `callId`, `toolName`, `abortSignal`, `channel`, `getSandbox`, `getToken`, `requireAuth`, and `to`. Read `ctx.agents`, and call
+  `ctx.agent()` and `ctx.ask()` in the workflow body; pass only the serializable values the step needs.
+  Call `getSandbox`, `getToken`, `requireAuth`, and `to` in a step: the workflow body throws when it calls them.
 - The tool's input must be a JSON object. Workflow bodies are for static tools under `agent/tools/`,
   not tools a `defineDynamic` function returns.
 
@@ -782,6 +782,48 @@ When an authored tool accepts a JSON Schema supplied by the model, represent tha
 
 This pattern controls specialist selection, not whether the parent model delegates at all. Route before the parent model runs if every incoming request must go through Jev.
 
+## Start channel sessions: `ctx.to`
+
+A workflow tool reaches the agent's channels with [`ctx.to(channel, target)`](/docs/tools#start-channel-sessions-ctxto), as an ordinary tool does. Call it in a `"use step"` helper that receives `ctx`, like `ctx.getSandbox()`; the workflow body throws when it calls it:
+
+```ts title="agent/tools/open_incident_channel.ts"
+import { defineWorkflowTool, type WorkflowStepToolContext } from "eve/tools";
+import { z } from "zod";
+import slack from "../channels/slack";
+import { createIncidentChannel } from "../lib/incidents";
+
+export default defineWorkflowTool({
+  description: "Open a Slack channel for an incident and continue the investigation there.",
+  inputSchema: z.object({ title: z.string(), summary: z.string() }),
+  async task({ title, summary }, ctx) {
+    "use workflow";
+    const channelId = await createChannel(title);
+    return await openIncident(ctx, channelId, summary);
+  },
+});
+
+async function createChannel(title: string) {
+  "use step";
+  return await createIncidentChannel(title);
+}
+
+async function openIncident(ctx: WorkflowStepToolContext, channelId: string, summary: string) {
+  "use step";
+  const delivery = await ctx
+    .to(slack, { channelId })
+    .send("Continue the investigation in this channel.", {
+      auth: ctx.session.auth.current,
+      history: [{ role: "user", text: summary }],
+      idempotencyKey: `${ctx.session.id}:${ctx.callId}:incident`,
+    });
+  return { channelId, sessionId: delivery.sessionId };
+}
+```
+
+A step that fails retries, so pass an `idempotencyKey` the retry repeats. The destination session dedupes keys from every sender, and `ctx.callId` is unique only within the calling session and is the same for every step of the call, so include `ctx.session.id` and add a label for each send. Create the channel in its own step: a retried send step then reuses the recorded `channelId` instead of creating another channel.
+
+`ctx.channel` holds the `kind`, `continuationToken`, and `metadata` of the channel serving the calling session, in the workflow body and in steps, as in [ordinary tools](/docs/tools#the-ctx-parameter).
+
 ## Report progress: `yield`
 
 A workflow body may be an async generator whose yields report progress. After processing a yield,

package/package.json

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

package/dist/src/public/channels/slack/approval-cards.d.ts

@@ -1,25 +0,0 @@
-/**
- * eve's default Slack rendering for human-input requests: posting approval
- * and question controls, and retiring an approval's messages once it resolves.
- */
-import type { RefusedAnswer, RequestBatch, RequestSettlement } from "#channel/interaction-prompts.js";
-import type { SlackApprovalChannelResolver, SlackChannelInternalEvents, SlackEventContext } from "#public/channels/slack/slackChannel.js";
-/**
- * Default `interaction.opened` handler — renders each pending HITL
- * request as Slack `block_actions`. Buttons by default; radio for
- * ≤6-option select requests; static_select for >6-option select
- * requests. Batches split into multiple posts when they would exceed
- * Slack's 50-block message cap.
- */
-export declare function defaultInteractionsHandler(approvalChannel?: SlackApprovalChannelResolver): (data: RequestBatch, ctx: Parameters<NonNullable<SlackChannelInternalEvents["interaction.opened"]>>[1]) => Promise<void>;
-/**
- * A responder an approval's policy or check refused hears why privately. A pending answer gets
- * no notice: an ephemeral cannot be removed once the approval settles, and the card itself
- * reports the outcome moments later.
- */
-export declare function notifyRefusedResponder(refused: RefusedAnswer, channel: SlackEventContext): Promise<void>;
-/**
- * Retires an approval's card: with the person whose press decided it, or as no longer needed
- * when it ended any other way (the user replied instead, or it was withdrawn).
- */
-export declare function settleApproval(resolution: RequestSettlement, channel: SlackEventContext): Promise<void>;

package/dist/src/public/channels/slack/approval-cards.js

@@ -1,2 +0,0 @@
-import{createLogger,logError}from"#internal/logging.js";import{slackUserIdForPrincipal,slackUserIdFromAuthContext}from"#public/channels/slack/auth.js";import{SLACK_MAX_BLOCKS_PER_MESSAGE,truncateMessageText}from"#public/channels/slack/limits.js";import{buildAnsweredBlocks,decodeHitlActionId,renderInteractionPostParts}from"#public/channels/slack/hitl.js";import{answeredBlocksFromActionBlock}from"#public/channels/slack/interaction-cards.js";import{deliverPrivateInteraction}from"#public/channels/slack/private-approval-delivery.js";const log=createLogger(`slack.defaults`);function defaultInteractionsHandler(e){return async(t,n)=>{let{channel:r}=n,i=[],a=[];for(let r of t.requests)((e===void 0?`thread`:await e(r,n))===`direct-message`?i:a).push(r);await postPublicInteractions(a,r);for(let e of i){let t=slackUserIdFromAuthContext(n.session.auth.current)??r.state.triggeringUserId;if(!t){log.warn(`direct-message input request not delivered because no reviewer was resolved`,{requestId:e.interactionId,sessionId:n.session.id});continue}let i=await deliverPrivateInteraction({previewMessageTs:r.state.triggeringMessageTs??r.slack.threadTs,request:e,reviewer:t,slack:r.slack});recordApprovalCards(r.state,[e],i);try{let n=await r.thread.post(`Waiting on ${e.request.kind===`approval`?`approval`:`a response`} from <@${t}>…`);n.id&&recordApprovalCards(r.state,[e],{...i,announcementTs:n.id})}catch(t){logError(log,`failed to announce private input request`,t,{requestId:e.interactionId,sessionId:n.session.id})}}}}async function postPublicInteractions(e,t){let n=new Map;for(let r of buildInteractionPosts(e)){let e=await t.thread.post({blocks:r.blocks,text:r.text});if(r.kind===`details`){if(e.id)for(let t of r.requests)n.set(t.interactionId,e.id);continue}for(let i of r.requests){let a=n.get(i.interactionId);recordApprovalCards(t.state,[i],{detailsMessageTs:a,messageBlocks:r.blocks,messageTs:e.id})}}}function recordApprovalCards(e,t,n){if(!n.messageTs)return;let r={...e.pendingApprovalCards};for(let e of t)e.request.kind===`approval`&&(r[e.interactionId]=n);e.pendingApprovalCards=r}async function settleApprovalCard(e,t,n){let r=e.state.pendingApprovalCards??{},i=r[t];if(i===void 0)return;let a={...r};delete a[t],e.state.pendingApprovalCards=a;let o=i.messageChannelId??e.state.channelId;if(o===null)return;let s=i.messageBlocks.flatMap(e=>blockContainsRequestAction(e,t)?answeredBlocksFromActionBlock({answerLabel:n.label,block:e,userId:n.userId})??buildAnsweredBlocks({answerLabel:n.label,promptBlocks:[]}):[e]);for(let[e,t]of Object.entries(a))t.messageTs===i.messageTs&&(a[e]={...t,messageBlocks:s});await settleRequest(e,`chat.update`,t,{blocks:s,channel:o,text:n.text,ts:i.messageTs});let c=i.detailsMessageTs;c!==void 0&&!Object.values(a).some(e=>e.detailsMessageTs===c)&&await settleRequest(e,`chat.delete`,t,{channel:o,ts:c}),i.announcementTs!==void 0&&e.state.channelId!==null&&await settleRequest(e,`chat.update`,t,{channel:e.state.channelId,text:n.announcement,ts:i.announcementTs})}async function settleRequest(e,t,n,r){try{let i=await e.slack.request(t,r);i.ok!==!0&&log.warn(`failed to retire approval message`,{error:i.error,operation:t,requestId:n})}catch(e){logError(log,`failed to retire approval message`,e,{operation:t,requestId:n})}}function buildInteractionPosts(e){let t=[],n=[];for(let r of e){let e=renderInteractionPostParts(r);e.details&&t.push({...e.details,request:r}),n.push({...e.controls,request:r})}return[...groupInteractionPostParts(t).map(e=>({...e,kind:`details`})),...groupInteractionPostParts(n).map(e=>({...e,kind:`controls`}))]}function groupInteractionPostParts(e){let t=[];for(let n of e){let e=t.at(-1);e&&e.blocks.length+n.blocks.length<=SLACK_MAX_BLOCKS_PER_MESSAGE?(e.blocks.push(...n.blocks),e.fallbacks.push(n.text),e.requests.push(n.request)):t.push({blocks:[...n.blocks],fallbacks:[n.text],requests:[n.request]})}return t.map(e=>({blocks:e.blocks,requests:e.requests,text:truncateMessageText(e.fallbacks.join(`
-`))}))}function blockContainsRequestAction(e,t){if(typeof e!=`object`||!e)return!1;let n=e;return[n.actions,n.elements].some(e=>Array.isArray(e)&&e.some(e=>{if(typeof e!=`object`||!e)return!1;let n=e.action_id;return typeof n==`string`&&decodeHitlActionId(n)?.requestId===t}))}async function notifyRefusedResponder(e,t){let n=slackUserIdForPrincipal(t.state,e.responder?.id);n!==void 0&&await t.thread.postEphemeral(n,e.reason??`We couldn’t verify your response. Please try again.`)}async function settleApproval(e,t){if(e.kind!==`approval`)return;if(e.outcome!==`accepted`&&e.outcome!==`declined`){await settleApprovalCard(t,e.interactionId,{announcement:`This approval is no longer needed.`,label:`No longer needed`,text:`No longer needed`});return}let n=e.outcome===`accepted`,r=slackUserIdForPrincipal(t.state,e.responder?.id),i=r===void 0?``:` by <@${r}>`,a=n?`Approve`:`Cancel`;await settleApprovalCard(t,e.interactionId,{announcement:`${n?`Approved`:`Cancelled`}${i}.`,label:a,text:`Answered: ${a}`,userId:r})}export{defaultInteractionsHandler,notifyRefusedResponder,settleApproval};