eve 0.68.0 → 0.69.0

package/docs/channels/overview.mdx

@@ -3,15 +3,23 @@ title: "Overview"
 description: "How users reach your agent: the channel contract, the base eve HTTP channel, and authoring custom channels."
 ---
 
-A channel is the edge adapter between a platform and your agent. It does three things:
+A channel connects a platform to your agent. For conversations, it:
 
-- Normalizes platform input into a user message.
-- Owns the channel-local address that maps a platform conversation to its current durable session.
-- Decides delivery, meaning how, where, and whether a response goes back.
+- Converts incoming messages into agent input.
+- Maps each platform conversation to an eve session.
+- Decides how, where, and whether to deliver replies.
+
+A channel can also receive events and pass them to another channel, without starting a conversation of its own.
 
 eve ships a base HTTP channel plus first-class platform channels, and you can author your own. Browse the full set in the [Integrations](/integrations) gallery and choose the Channels filter.
 
-After a channel normalizes input, eve runs the same agent runtime regardless of where the message came from. Tools and instructions do not need channel-specific logic.
+After a channel dispatches a message, eve runs the same agent runtime regardless of where the event came from. Tools and instructions do not need channel-specific logic.
+
+## Choose where the conversation lives
+
+The agent doesn't have to reply where an event arrived. A webhook, for example, can start a conversation in a team chat without sending an agent reply to the webhook's source.
+
+Use a [cross-channel hand-off](./custom#cross-channel-hand-off) when the conversation belongs elsewhere. The destination channel handles the session, replies, and follow-up messages. To post a notification without running the agent, use the platform's API instead.
 
 ## Audience
 
@@ -72,57 +80,7 @@ The eve channel is the framework's default HTTP session API, the routes the term
 
 ## Custom channels
 
-When eve doesn't ship a channel for your surface, build one with `defineChannel` from `eve/channels`. A custom channel declares route handlers (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `WS`), an `events` map, and uses `send(address, input)` to start or resume a session. See [Custom channels](./custom) for the full walkthrough, including WebSocket routes, cross-channel agent hand-off, channel metadata, address tokens, and file uploads.
-
-A cross-channel `send(...)` supplies input to the agent and invokes the model on the destination channel. eve does not currently provide a direct cross-channel provider-message queue. To post without starting a turn, use the provider API. See [Durable cross-channel notifications](../patterns/durable-cross-channel-notifications) when delivery also needs application-managed retries and deduplication.
-
-## Background task results
-
-Pass `taskDeliveryPolicy` to `send(...)` to choose how the session reports background results:
-
-- `"auto"` (default for new channel sessions): ready results can invoke the parent while other tasks continue. The parent reports results that are useful independently and stays silent when a useful answer needs unfinished work.
-- `"cohort"`: wait for overlapping tasks to settle, then deliver their terminal outcomes together.
-
-```ts title="agent/channels/reports.ts"
-import { defineChannel, POST } from "eve/channels";
-import { localDev, routeAuth } from "eve/channels/auth";
-
-export default defineChannel({
-  routes: [
-    POST("/reports", async (request, { from }) => {
-      const auth = await routeAuth(request, localDev());
-      if (auth instanceof Response) return auth;
-      const session = await from("daily-report").send("Prepare the daily reports.", {
-        auth,
-        taskDeliveryPolicy: "cohort",
-      });
-      return Response.json({ sessionId: session.id });
-    }),
-  ],
-});
-```
-
-The option is available on channel-local `from(...).send(...)`, cross-channel
-`to(...).send(...)`, fixed-session `send(...)`, Chat SDK `bridge.send(...)`, and client
-sends. An explicit value
-updates the session's policy, including pending background tasks; later sends that
-omit it preserve that policy. A cross-channel send carries its setting through the
-receiver's `from(...).send(...)` unless that call supplies an explicit value.
-
-[Schedules](../schedules#background-task-results) default new sessions to `"cohort"`.
-A schedule handler can pass `taskDeliveryPolicy: "auto"` to `send(...)` to override
-that default. Child sessions use their own policy.
-
-With `"auto"`, a model call may finish without a user-visible message. Results
-already queued from the same cohort may share a turn. Each reporting turn receives
-the whole cohort, including pending tasks and available outputs, so previously
-withheld results remain available for a later combined report.
-
-Input requests and explicit task messages remain eligible for delivery under
-either policy. Failure and cancellation update task state immediately; their
-automatic reports follow the selected policy. User messages follow `turnPolicy`.
-See [Completion batching](../subagents#completion-batching) for cohort membership
-and result ordering.
+Build a channel with `defineChannel` from `eve/channels` when you need your own HTTP or WebSocket endpoint. Its routes can start conversations on that channel or hand work to another one. See [Custom channels](./custom) for examples and the authoring API.
 
 ## Relationship to the Chat SDK
 

package/docs/channels/slack.mdx

@@ -152,7 +152,7 @@ controls observability content capture, not access to the channel. See
 Message hooks return `{ auth }` to dispatch, `null` to drop, or `{ auth, context }` to inject background into history. Public conversations use the returned `title`, or the triggering message text when `title` is omitted. DMs and private channels always use `Private message` so the run title does not expose message details.
 
 - `onMessage(ctx, message)` handles Slack `message` events. eve drops messages authored by the installed app before this hook runs, preventing self-reply loops. Messages from other bots remain visible; check `message.author?.isBot` when those should also be ignored. `ctx.isBotMentioned()` and `ctx.isSubscribed()` support mention and active-thread policies.
-- `onAppMention(ctx, message)` handles only `app_mention` and takes precedence over `onMessage`. Its default derives workspace-scoped auth and posts `Thinking…`.
+- `onAppMention(ctx, message)` handles only `app_mention` and takes precedence over `onMessage`. Its default derives workspace-scoped auth.
 - `onDirectMessage(ctx, message)` handles only DMs and takes precedence over `onMessage`. Bot-authored messages and edits are filtered first; Slack requires `message.im` and `im:history`.
 
 | Incoming event         | Handler order                                                       |
@@ -164,6 +164,8 @@ Message hooks return `{ auth }` to dispatch, `null` to drop, or `{ auth, context
 
 Only the first available handler runs. A message hook returning `null` drops the message; it does not continue down the table.
 
+Message hooks only decide whether and how a message starts a turn. They don't render anything, so replacing one never changes what people see: eve still acknowledges the message, shows progress, and posts the reply. To change what the agent posts, add [renderers](#customize-rendering).
+
 `onInteraction(action, ctx)` separately handles user-owned `block_actions` callbacks. eve-owned HITL buttons and modal submissions go through `onInputResponse(ctx, submission)` instead. eve attaches the triggering Slack user id to the same model message as its text, preserving speaker attribution without profile lookups.
 
 Use `onShortcut(shortcut, ctx)` for message shortcuts and global shortcuts configured under **Interactivity & Shortcuts** in your Slack app. The handler receives the shortcut callback ID, user, workspace, and trigger ID. Message shortcuts also include the selected message and channel. The context exposes workspace-scoped Slack API access because global shortcuts have no channel or message. eve acknowledges shortcut requests immediately and keeps their handlers alive in the background.
@@ -397,7 +399,7 @@ const session = await ctx.resolveSession({ target });
 
 ### Slack API calls outside a handler
 
-Inside inbound webhook handlers such as `onAppMention`, `onEvent`, `onInteraction`, `onShortcut`, `onSlashCommand`, and `onInputResponse`, `ctx.slack.request(operation, body)` is the raw-API escape hatch. Inside an `events` handler, use `channel.slack.request(...)` instead. Outside those contexts there is no handle — a schedule resolving reactions on old
+Inside inbound webhook handlers such as `onAppMention`, `onEvent`, `onInteraction`, `onShortcut`, `onSlashCommand`, and `onInputResponse`, `ctx.slack.request(operation, body)` is the raw-API escape hatch. Inside a [renderer](#customize-rendering)'s event handler, use `channel.slack.request(...)` instead. 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:
 
@@ -450,27 +452,179 @@ The bases say where a call may go. `apiBaseUrl` is the base Slack Web API method
 
 ### Delivery
 
-The default handlers reply in-thread and show activity. Typing indicators post automatically: `Thinking…` on inbound, `Working…` on `turn.started`, a truncated reasoning snippet on `reasoning.appended`, and an action label on `actions.requested` — the tool name plus its most telling argument (`grep useEveAgent`, `read_file agent/agent.ts`), the subagent or remote-agent name for dispatched calls, and `+N more` when the model requests several actions at once. The model's own pre-tool narration, when present, takes precedence over the derived label. 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 an inbound handler or the `events` handlers to customize.
+eve shows an agent's progress in two places. Short work, such as thinking or a tool call, appears in the thread status and never posts a message. [Tasks](/docs/tools/tasks), which keep working while the conversation continues, appear in a task card: one message per turn that eve updates in place. Replies post as ordinary messages, so the thread holds the conversation, the task card, and nothing else.
+
+| Moment                             | Thread status                                                                   |
+| ---------------------------------- | ------------------------------------------------------------------------------- |
+| A mention or DM arrives            | `Thinking...`, right away, while the message hook is still deciding             |
+| The message hook drops the message | Cleared                                                                         |
+| The turn starts                    | `Working...`                                                                    |
+| The model reasons                  | The first line of its reasoning                                                 |
+| The model calls tools              | Its narration before the calls, or an action label such as `Search useEveAgent` |
+| The turn waits on its tasks        | `Waiting on researcher...`, or `Waiting on 3 tasks...`                          |
+| A reply posts                      | Cleared by Slack                                                                |
+
+Slack clears a thread status after two minutes without a message, so during a long wait the task card is what shows the work is still going.
+
+Action labels follow the same rule as the task card titles described below, plus `+N more` when the model requests several actions at once. They leave out the model's own `task_wait` and `task_cancel` calls. Reasoning snippets build progressively: extensions of at least four characters appear immediately, while smaller streamed deltas use a five-second refresh interval to avoid one Slack request per token.
+
+Replies up to 12,000 characters render inline. Longer replies are uploaded unchanged as a Markdown snippet named `eve-response.md` with a short in-thread note, which requires the `files:write` bot scope. Upload failures are logged by the channel dispatcher; they do not trigger a model retry.
 
-The built-in `message.completed` handler renders responses up to 12,000 characters inline. Longer responses are uploaded unchanged as a Markdown snippet named `eve-response.md` with a short in-thread note, which requires the `files:write` bot scope. Upload failures are logged by the channel dispatcher; they do not trigger a model retry. An authored `events["message.completed"]` handler replaces this behavior and owns its own delivery limits.
+When the model replies while its tasks keep working, that reply posts like any other, and the reply after the results posts as another message. A schedule's session posts only the final reply.
 
 Outbound text preserves bare `@` tokens as literal text. To mention a user, embed Slack's `<@USER_ID>` syntax directly or use `channel.thread.mentionUser(userId)`.
 
-When a session starts without a `threadTs` (say, from a schedule's `to(slack, target).send(...)`), eve gives it a unique temporary continuation token. The first agent post anchors the session to the Slack message timestamp, and later posts and mentions resume that same session. Pass `initialMessage` with a `Card` to land a structured anchor first instead. `threadTs` and `initialMessage` are mutually exclusive.
+### Task card
 
-The example below overrides `onAppMention` to gate on an authored message. The built-in completion handler still posts the reply and uploads long responses as snippets. Event handlers receive `(eventData, channel, ctx)`, with Slack platform handles on `channel.thread` and `channel.slack`:
+When a turn starts its first task, eve posts a task card in the thread and keeps it current until the turn and its tasks finish. One task renders as a Slack `task_card` block; two or more render as a `plan` block with one row per task the turn started. What an agent task does on its own, including the tasks it starts, stays inside that task and does not add rows. The card needs no configuration beyond the `chat:write` scope the channel already uses.
 
-```ts
-import { defaultSlackAuth, slackChannel } from "eve/channels/slack";
+Each row shows:
+
+- **Title:** the tool's [`label.start`](/docs/tools#label-tool-activity), or the tool name. An agent task shows the agent name and the first sentence of its brief (`researcher: Find the incidents behind the checkout spike`). A task the agent hands to its own copy shows the brief alone.
+- **Waiting:** while the task waits on an approval, an answer, or a sign-in, the row says so, as in `Waiting for approval`. In a DM or private channel it also shows the request's prompt; elsewhere it shows only what kind of request is waiting, since `approvalChannel` can send the request to one person. The request itself posts wherever `approvalChannel` sends it, and the row goes back to working once the request resolves.
+- **How it ended:** the first sentence of the result or the agent's reply, cut to about 100 characters, `Failed` for a failure, or a line for a cancelled task that says why it stopped. A task the model cancelled with `task_cancel` shows `Stopped early since it was no longer needed` with a success check, since the model no longer needed that work. A task stopped by [cancelling the turn](#message-hooks) shows `Stopped by request`, one stopped because its turn ended shows `Stopped when the turn ended`, and one whose run stopped on its own shows `Stopped`. Those rows and failed rows never show a success check. In a DM or private channel, a failure also shows the first sentence of its error, as in `Failed: Rate limited`. Error text can carry internal details, so everywhere else, including proactive sessions without a known `audience`, shows `Failed` alone. A completed or failed task that ran for a second or more also shows how long it took: `Done in 1m 14s: Found three incidents.` or `Failed after 3m`.
+
+The plan title summarizes the turn: `Working on 2 tasks`, `1 of 2 tasks done`, `Waiting for approval`, then `Finished 2 tasks in 3m` or `Finished 3 tasks in 5m 12s: 1 failed, 1 stopped`. When every task calls a declared subagent or remote agent, and the turn calls three or fewer of them, the title names them instead of counting: `Asking researcher and reviewer`, then `Waiting on reviewer · 1 of 2 tasks done`. Tasks the model cancelled with `task_cancel` count as finished, not stopped. A resumable task continued in a later turn appears in that turn's card.
+
+A turn stays open while its tasks work, so messages you send during that time continue the same turn. When that turn starts a task after every task on its card has settled, eve marks that card finished and posts a new card for the new work, so the new tasks don't update a card further up the thread.
+
+eve writes the card from the session's own events as they happen, and only when it changed. A failed Slack call never fails the turn: eve tries a failed write once more after a second, then again on the turn's next change. If someone deletes the card, eve posts it again on its next change. Card posts never unfurl links. Schedule sessions and sessions without a Slack thread get no card.
+
+### Customize rendering
+
+Without `renderers`, eve renders everything above with its default renderer. Pass `renderers` to change what the agent posts without replacing that default. Each renderer wraps the ones after it, ending with eve's default renderer, and has three optional parts:
+
+- `received(message, channel, next)` acknowledges a mention or DM the moment it arrives, and another channel message once `onMessage` dispatches it. eve's default sets `Thinking...`.
+- `events` handles session events such as `message.completed` or `input.requested`. Each handler receives `(eventData, channel, ctx, next)`, with Slack platform handles on `channel.thread` and `channel.slack`; a `session.failed` handler receives `(eventData, channel, next)`.
+- `taskCard(view, next)` returns the task card's blocks and notification text, or `null` for no card.
+
+Call `next()` to run the rest of the chain, ending with eve's default. Call it after your own work, before it, or with changed data, as in `next({ ...event, message })`; the rest of the chain runs at most once. Skip `next` to replace the default for that event. This renderer adds feedback buttons below each final reply and a context row to the finished task card:
+
+```ts title="agent/channels/slack.ts"
 import { connectSlackCredentials } from "@vercel/connect/eve";
+import { defineSlackRenderer, slackChannel } from "eve/channels/slack";
+
+const feedback = defineSlackRenderer({
+  events: {
+    async "message.completed"(event, channel, _ctx, next) {
+      await next(); // eve posts the reply, or uploads a long one as a snippet
+      if (event.finishReason === "tool-calls") return;
+      await channel.thread.post({
+        blocks: [
+          {
+            type: "context_actions",
+            elements: [
+              {
+                type: "feedback_buttons",
+                action_id: "reply_feedback",
+                positive_button: { text: { type: "plain_text", text: "Helpful" }, value: "up" },
+                negative_button: {
+                  text: { type: "plain_text", text: "Not helpful" },
+                  value: "down",
+                },
+              },
+            ],
+          },
+        ],
+        text: "Was this helpful?",
+      });
+    },
+  },
+  taskCard(view, next) {
+    const card = next(view);
+    if (card === null || view.state !== "finished") return card;
+    const note = {
+      type: "context",
+      elements: [{ type: "mrkdwn", text: "Results are in the reply below." }],
+    };
+    return { ...card, blocks: [...card.blocks, note] };
+  },
+});
 
 export default slackChannel({
   credentials: connectSlackCredentials("slack/my-agent"),
-  onAppMention: (ctx, message) =>
-    message.author ? { auth: defaultSlackAuth(message, ctx) } : null,
+  renderers: [feedback],
+});
+```
+
+`taskCard` runs for every turn that calls a tool, and receives the same view eve's default renders from:
+
+- `state`: `blocked` while any task waits on a person, `working` while the turn or any other task works, then `finished`.
+- `tasks`: the tasks the turn started, each with a `title`, `status`, `blockedOn`, and `summary`. A failed task's `summary` and a blocked task's `blockedOn.label` are present only in a DM or private channel.
+- `actions`: the turn's other tool calls, each with its tool `name`, `title`, `status`, and `input`. `input` is left out when its JSON is longer than 4,096 characters.
+
+`taskCard` is synchronous and pure: eve posts the card and updates it as the view changes. eve's default returns `null` for a turn that started no tasks. Its block keeps the same `block_id` for the whole turn; keep that `block_id` on a block you build in its place. To change a row's title in every channel, give the tool a [label](/docs/tools#label-tool-activity) instead.
+
+Renderers run in the order you list them, and the first one is outermost. `onInteraction` receives clicks on buttons a renderer posts, such as the feedback buttons above.
+
+### Show your own tool on the task card
+
+A renderer can draw any of the turn's tool calls from their input. For example, give the agent a `plan` tool that records a checklist, and show the checklist ahead of eve's task rows:
+
+```ts title="agent/tools/plan.ts"
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description:
+    "Show the steps of a multi-step request as a checklist. Pass the complete list on every call.",
+  inputSchema: z.object({
+    items: z.array(
+      z.object({
+        status: z.enum(["pending", "working", "completed", "failed"]),
+        title: z.string(),
+      }),
+    ),
+  }),
+  async execute() {
+    return { updated: true };
+  },
 });
 ```
 
+```ts title="agent/channels/slack.ts"
+import { type BlockKitBlock, defineSlackRenderer, slackChannel } from "eve/channels/slack";
+
+interface PlanItem {
+  readonly status: "pending" | "working" | "completed" | "failed";
+  readonly title: string;
+}
+
+const SLACK_STATUS = {
+  completed: "complete",
+  failed: "error",
+  pending: "pending",
+  working: "in_progress",
+} as const;
+
+const plan = defineSlackRenderer({
+  taskCard(view, next) {
+    const card = next(view);
+    const calls = view.actions.filter((action) => action.name === "plan");
+    const items = calls.at(-1)?.input?.items as PlanItem[] | undefined;
+    if (items === undefined) return card;
+    // eve's card is one `plan` block, or one `task_card` block for a single task.
+    const [block] = card?.blocks ?? [];
+    const taskRows: BlockKitBlock[] =
+      block === undefined ? [] : block.type === "plan" ? (block.tasks as BlockKitBlock[]) : [block];
+    const planRows = items.map((item, index) => ({
+      status: SLACK_STATUS[item.status],
+      task_id: `plan_${index}`,
+      title: item.title,
+    }));
+    const tasks = [...planRows, ...taskRows.map(({ type: _type, ...row }) => row)];
+    return {
+      blocks: [{ type: "plan", block_id: block?.block_id, title: "Plan", tasks }],
+      text: `Plan: ${items.map((item) => item.title).join(", ")}`,
+    };
+  },
+});
+
+export default slackChannel({ renderers: [plan] });
+```
+
+A turn that only plans gets a card too, because `taskCard` runs for every turn that calls a tool.
+
 ### Human-in-the-loop (HITL)
 
 HITL renders as Slack buttons and selects. Fixed-choice actions and freeform modal submissions pass through `onInputResponse` before the parked session resumes. The initial **Type your answer** action only opens eve's modal; the hook runs when the user submits an answer.
@@ -490,7 +644,7 @@ export default slackChannel({
 
 The callback receives the `InputRequest` and current `SessionContext`, so it can switch on `kind`, `action`, or presentation properties. Omit it to keep every request in the thread, or return `"direct-message"` unconditionally to make every request private. If eve cannot resolve the triggering Slack user for a direct message, it logs the undelivered request and posts no fallback, so private delivery fails closed. The existing `onInputResponse` or tool approval response policy still decides whether the person who clicks may respond.
 
-An authored `input.requested` handler can extend delivery and then hand the requests back to eve through `defaultDeliver()`. For example, an application can add non-sensitive context to the Slack thread before eve renders the actionable controls. The configured `approvalChannel` still sends sensitive reviews to a DM and keeps ordinary requests in the thread:
+A renderer's `input.requested` handler can extend delivery and then hand the requests on to eve with `next()`. For example, an application can add non-sensitive context to the Slack thread before eve renders the actionable controls. The configured `approvalChannel` still sends sensitive reviews to a DM and keeps ordinary requests in the thread:
 
 ```ts title="agent/channels/slack.ts"
 import { slackChannel } from "eve/channels/slack";
@@ -500,47 +654,88 @@ export default slackChannel({
   approvalChannel(request) {
     return isPrivate(request) ? "direct-message" : "thread";
   },
-  events: {
-    async "input.requested"(event, channel, _ctx, defaultDeliver) {
-      await channel.thread.post({
-        blocks: [
-          {
-            type: "context",
-            elements: [
+  renderers: [
+    {
+      events: {
+        async "input.requested"(_event, channel, _ctx, next) {
+          await channel.thread.post({
+            blocks: [
               {
-                type: "mrkdwn",
-                text: "A review is needed before this work can continue.",
+                type: "context",
+                elements: [
+                  {
+                    type: "mrkdwn",
+                    text: "A review is needed before this work can continue.",
+                  },
+                ],
               },
             ],
-          },
-        ],
-        text: "A review is needed before this work can continue.",
-      });
-      await defaultDeliver(event);
+            text: "A review is needed before this work can continue.",
+          });
+          await next();
+        },
+      },
     },
-  },
+  ],
 });
 ```
 
-Authorization prompts split public status from private credentials. A sign-in challenge (OAuth URL, device code) is a credential. Anyone who completes it binds their identity to the session's connection. The default `authorization.required` handler posts a public, link-free status in the thread, delivers the actual challenge ephemerally to the triggering user, device code included, and then updates that public status when `authorization.completed` fires. The handler receives a private-delivery context with `postEphemeral`, `postDirectMessage` (needs the `im:write` scope), and `state`. There is, intentionally, no public `post` and no raw API access.
+#### Render and decode HITL controls yourself
+
+`eve/channels/slack` exports the helpers eve uses for its own HITL controls. `renderInputRequestBlocks(request, route?)` returns the Block Kit blocks for one `InputRequest`. `deriveHitlResponse(action)` decodes a click on those blocks into `{ response, kind?, route? }`, where `response` is the eve `InputResponse`, or returns `null` for any other action. Every eve-owned control's `action_id` starts with `HITL_ACTION_PREFIX` (`"eve_input:"`), so give your own buttons a different prefix to keep them routed to `onInteraction`.
+
+```ts
+import { deriveHitlResponse, renderInputRequestBlocks } from "eve/channels/slack";
+
+const [card] = renderInputRequestBlocks(request) as [
+  { actions: { action_id: string; value: string }[] },
+];
+const button = card.actions[0]!;
+
+// For a request whose first option id is "approve":
+deriveHitlResponse({ actionId: button.action_id, value: button.value });
+// { response: { optionId: "approve", requestId: request.requestId } }
+```
+
+Use them to test a custom renderer against eve's wire format, or to post eve's controls from your own renderer. A click on these controls in the session's Slack thread resumes the session through `onInputResponse`, the same as eve's own controls. To pass `response` to `respond()` yourself, validate it first with `parseInputResponses` from `eve/client`.
+
+Authorization prompts split public status from private credentials. A sign-in challenge (OAuth URL, device code) is a credential. Anyone who completes it binds their identity to the session's connection. The default `authorization.required` handler posts a public, link-free status in the thread, delivers the actual challenge ephemerally to the Slack user behind the event's `principalId`, device code included, and then updates that public status when `authorization.completed` fires. A renderer's `authorization.required` handler receives a private-delivery context with `postEphemeral`, `postDirectMessage` (needs the `im:write` scope), and `state`. There is, intentionally, no public `post` and no raw API access. Its `next()` reaches eve's default, which posts the public status; skip `next` to deliver the challenge yourself, as this handler does by direct message. `state.slackUsersByPrincipal` maps each principal eve has seen in the thread, through a message or an input response, to its Slack user ID. If the principal has no entry, the challenge is not sent privately.
 
 ```ts
-events: {
-  "authorization.required"(eventData, channel) {
-    const userId = channel.state.triggeringUserId;
-    if (!userId || !eventData.authorization?.url) return;
-    return channel.postDirectMessage(userId, `Sign in to continue: ${eventData.authorization.url}`);
+renderers: [
+  {
+    events: {
+      "authorization.required"(eventData, channel) {
+        const userId =
+          eventData.principalId === undefined
+            ? undefined
+            : channel.state.slackUsersByPrincipal?.[eventData.principalId];
+        if (!userId || !eventData.authorization?.url) return;
+        return channel.postDirectMessage(userId, `Sign in to continue: ${eventData.authorization.url}`);
+      },
+    },
   },
-},
+],
 ```
 
 The private authorization button uses the label **Sign in**, so long connection display names do not make the button invalid. The public status identifies the connection.
 
 ### Proactive sessions
 
-Start a session without an inbound message through `ctx.to(slack, target).send(message, { auth })` from another channel, or `to(slack, target).send(message, { auth })` from a schedule `run` handler. The proactive target shape is `{ channelId, installationTeamId?, threadTs?, initialMessage?, audience? }`. It defaults to `unknown`; pass `audience` only when the caller already knows the destination's visibility. Set `installationTeamId` to the app installation workspace when a function-form bot token must select an installation. This sends turn input to the agent; it is not a direct Slack post.
+Start a Slack conversation from a [webhook on another channel](./custom#cross-channel-hand-off) or a [schedule](../schedules#handler-form-run), without waiting for someone to message the app.
+
+Pass `{ channelId }` as the target to start a new thread. The agent's first post becomes the thread's root message. You can also set these target fields:
+
+| Field                | Use                                                                                       |
+| -------------------- | ----------------------------------------------------------------------------------------- |
+| `threadTs`           | Continue an existing thread instead of creating one.                                      |
+| `initialMessage`     | Post a card as the thread root before the agent runs. Cannot be combined with `threadTs`. |
+| `installationTeamId` | Select the app installation workspace when using a function-form bot token.               |
+| `audience`           | Set the destination's visibility when you know it. Defaults to `unknown`.                 |
+
+The default mention handler lets teammates continue the session by mentioning the app in the thread. To accept replies without a mention, [configure an `onMessage` hook and the required Slack subscriptions and scopes](#continue-conversations-without-repeated-mentions).
 
-To post without invoking the model, use `ctx.thread.post(...)` in an inbound Slack handler or `channel.thread.post(...)` in an `events` handler. Use `callSlackApi(...)` where no Slack channel context exists. For application-managed retries and deduplication, see [Durable cross-channel notifications](../patterns/durable-cross-channel-notifications).
+For a Slack post without an agent turn, use `ctx.thread.post(...)` in an inbound handler or `channel.thread.post(...)` in a renderer's event handler. Outside a handler, use [`callSlackApi(...)`](#slack-api-calls-outside-a-handler).
 
 ### Attachments
 

package/docs/channels/telegram.mdx

@@ -51,6 +51,8 @@ The default `message.completed` handler sends plain text via `sendMessage`. It p
 
 Human-in-the-loop (HITL) turns option requests into inline-keyboard buttons and freeform requests into `ForceReply`. Telegram caps `callback_data` at 64 bytes, so eve keeps compact callback ids in channel state instead. It acknowledges its own callbacks with `answerCallbackQuery`; anything it doesn't recognize goes to `onCallbackQuery`.
 
+A text reply to a bot message is sent as a normal message, with the replied-to message id in `state.replyToBotMessageId`. When that id matches a pending `ForceReply` prompt, the channel's `deliver` hook turns the reply into the answer. Otherwise the reply reaches the agent as a message, and starts a new session when none owns the thread.
+
 ### Proactive sessions
 
 Start a session without an inbound message through `to(telegram, target).send(message, { auth })` from a schedule `run` handler, or `ctx.to(telegram, target).send(message, { auth })` from another channel. `target.chatId` is required. Add `messageThreadId` to land in a specific forum topic.

package/docs/concepts/built-in-tools.md

@@ -24,7 +24,7 @@ export default defineAgent({
 
 This turns off the optional defaults described below. Add back only the tools the agent needs with the command in each tool's section. Existing files under `agent/tools/` remain available, including same-name replacements such as `agent/tools/bash.ts`.
 
-`connection_search` stays available when the agent has connections because it provides access to their tools.
+`connection_search` and `connection_execute` stay available when the agent has connections because they provide access to connection tools.
 
 ### `bash`
 
@@ -215,7 +215,7 @@ export default disableTool();
 
 ### `agent`
 
-`agent` delegates a subtask to a fresh copy of the root agent. It is root-only, always runs in the background, and returns a task receipt immediately. The child receives the root's instructions, tools, connections, and sandbox, but starts with fresh conversation history and [state](./state). See [Subagents](../subagents).
+`agent` delegates a subtask to a fresh copy of the root agent. It is root-only, and each call is a [task](/docs/tools/tasks): the call returns a receipt, and the child's reply arrives later as the task's result. The child receives the root's instructions, tools, connections, and sandbox, but starts with fresh conversation history and [state](./state). See [Subagents](../subagents).
 
 ```sh
 eve add tool/agent
@@ -225,7 +225,7 @@ eve add tool/agent
 export { default } from "eve/tools/agent";
 ```
 
-An authored tool at `agent/tools/agent.ts` replaces the framework behavior. Re-export the definition above to restore direct root-copy delegation, export another tool such as `agentRouter()` to change the model-facing behavior, or disable the slot:
+An authored tool at `agent/tools/agent.ts` replaces the framework behavior. Re-export the definition above to restore direct root-copy delegation, export another tool such as `agentRouter()` to change the model-facing behavior, or disable the slot. `agentRouter()` runs each call as a [task](/docs/tools/workflows#run-calls-as-tasks-task), which adds `task_wait` and `task_cancel`:
 
 ```ts title="agent/tools/agent.ts"
 import { disableTool } from "eve/tools";
@@ -233,26 +233,6 @@ import { disableTool } from "eve/tools";
 export default disableTool();
 ```
 
-### `task_cancel`
-
-`task_cancel` lets the root session cancel background tasks.
-
-```sh
-eve add tool/task_cancel
-```
-
-```ts title="agent/tools/task_cancel.ts"
-export { default } from "eve/tools/task_cancel";
-```
-
-The framework behavior cannot be overridden. Re-export the definition above to restore it, or disable it:
-
-```ts title="agent/tools/task_cancel.ts"
-import { disableTool } from "eve/tools";
-
-export default disableTool();
-```
-
 ### `load_skill`
 
 `load_skill` pulls an on-demand [skill](../skills)'s instructions into the current turn. It appears only when the agent declares skills and adds no execution surface by itself.
@@ -287,9 +267,21 @@ export default disableTool();
 
 ### `connection_search`
 
-`connection_search` discovers tools across declared [connections](../connections) and makes matches directly callable by qualified name, such as `linear__list_issues`. eve adds it automatically when connections exist, even when `defaultTools` is `false`, so there is no add command.
+`connection_search` and `connection_execute` give the model every tool from the agent's [connections](../connections) without adding each tool to the model's tool list. eve adds both when the agent has a static connection or a dynamic connection resolver, even when `defaultTools` is `false`, so there is no add command.
+
+- `connection_search({ query?, connection?, limit?, offset? })` returns matching tools with their connection, name, description, and a TypeScript signature rendered from the tool's schemas. Omit `query` to list every tool, or pair it with `connection` to list one connection's tools.
+- `connection_execute({ connection, tool, input })` checks `input` against the tool's input schema, calls the tool, and returns its result. The stream reports the call as a nested action named `<connection>__<tool>`, such as `linear__list_issues`, whose `parentCallId` is the `connection_execute` call id.
 
-An authored `agent/tools/connection_search.ts` replaces the framework behavior. Import the framework definition from `eve/tools/connection_search` when you need to reference it directly. Exporting `disableTool()` from this slot is an error because agents with connections require connection discovery.
+The definitions of both tools never change during a session. eve lists connection names and descriptions in append-only context messages rather than in the system prompt, so finding a tool, signing in, or resolving a dynamic connection keeps the cached prompt prefix.
+
+The tools cannot be replaced or disabled. The compiler rejects an authored `agent/tools/connection_search.ts`, `agent/tools/connection_execute.ts`, or `agent/tools/connection_tools.ts`. An agent without connections has neither tool.
+
+### `task_wait` and `task_cancel`
+
+eve adds `task_wait` and `task_cancel` when the agent has a tool that runs its calls as [tasks](/docs/tools/tasks): any agent tool, including the built-in `agent` tool, declared subagents, and remote agents, or a tool such as `agentRouter()`, the `workflow` tool, or an authored workflow tool that defines `task(input, ctx)` or `serve(receive, ctx)`. There is no add command, and the tools are not workflow tools. Both names are reserved: the compiler rejects an authored `agent/tools/task_wait.ts` or `agent/tools/task_cancel.ts`.
+
+- `task_wait({ timeoutSeconds? })` parks the turn until any task has a result, a new message arrives, or `timeoutSeconds` pass, and returns at once when a result is already waiting. While it waits, the stream reports `turn.waiting` for the open turn. Results arrive in a `<task_result>` message right after it returns. Waiting never stops a task.
+- `task_cancel({ taskId })` stops a task's current work and says so, or says the task had no work to stop when it already finished or is an idle [resumable task](/docs/tools/workflows#resumable-tasks-serve). An id that names no task fails with `UNKNOWN_TASK`. A resumable task stays available after a cancel.
 
 Review these tools before production use. Disable, wrap, restrict, or require approval for any tool that can access the filesystem, network, shell, or sensitive data.
 
@@ -313,7 +305,7 @@ import { askQuestion } from "eve/tools/ask_question";
 export default askQuestion();
 ```
 
-`ask_question` is a [workflow tool](/docs/tools/workflows) that calls `ctx.ask()`. The model receives `{ status: "answered", answer }`, where `answer` is the chosen option's label or the user's own words. A plain follow-up message answers the question too when it is the only pending question. When other questions are also pending, a message does not answer any of them: `ask_question` resolves as `{ status: "dismissed" }` and the message reaches the model normally. In a session that cannot request input, such as a scheduled run, the result is `{ status: "unavailable" }` and the model continues on its own judgment. Remove the file to remove the tool.
+`ask_question` is a [workflow tool](/docs/tools/workflows) that calls `ctx.ask()`. The model receives `{ status: "answered", answer }`, where `answer` is the chosen option's label or the user's own words. A plain follow-up message answers the question too when it is the only pending question. When other questions are also pending, a message does not answer any of them: `ask_question` withdraws its question, resolves as `{ interrupted: true }`, which the model reads as `Stopped early because a new message arrived.`, and the model reads the message next. In a session that cannot request input, such as a scheduled run, the result is `{ status: "unavailable" }` and the model continues on its own judgment. Remove the file to remove the tool.
 
 ### `glob`
 
@@ -367,9 +359,25 @@ export default defineTool({
 
 Remove the file to remove the tool. `disableTool()` is unnecessary because `grep` is not added by default.
 
+### `no_reply`
+
+`no_reply` ends the turn without a reply. Use it when a scheduled check finds nothing to report, or when an action the agent already took is the whole answer. The model calls it with an optional `{ reason }`, which stays in the session history and traces and is never sent. The turn completes without a final message, so channels and schedule sends post nothing, and later turns see that the agent chose to stay quiet. Add it:
+
+```sh
+eve add tool/no_reply
+```
+
+```ts title="agent/tools/no_reply.ts"
+import { noReply } from "eve/tools/no_reply";
+
+export default noReply();
+```
+
+`no_reply` is a `defineTool` tool with [`endsTurn: true`](/docs/tools#end-the-turn-after-a-tool-call), so the turn ends only when no other tool runs in the same step. Only root sessions receive it. Slack clears the thread status when the turn completes. Remove the file to remove the tool.
+
 ### `sleep`
 
-`sleep` pauses and durably resumes the current turn. The model calls it with `{ seconds }`; the wait does not hold an application runtime open. Concurrent calls run in parallel, and the turn resumes after the longest wait. Add it:
+`sleep` pauses and durably resumes the current turn. The model calls it with `{ seconds }`; the wait does not hold an application runtime open. Concurrent calls run in parallel, and the turn resumes after the longest wait. A steering message, the default for a new message, ends the wait early: `sleep` returns `{ interrupted: true }`, which the model reads as `Stopped early because a new message arrived.`, followed by the message. Add it:
 
 ```sh
 eve add tool/sleep
@@ -400,4 +408,4 @@ Remove the file to remove the tool. `disableTool()` is unnecessary because `slee
 - [Tools](../tools): define your own tools, gate them on approval, and shape their output with `toModelOutput`
 - [Dynamic capabilities](../guides/dynamic-capabilities): generate the tool set per session with `defineDynamic`
 - [Sandbox](../sandbox): configure the sandbox used by shell and file tools
-- [Subagents](../subagents): declare specialists that the model can call as background tasks
+- [Subagents](../subagents): declare specialists that the model can delegate to

package/docs/concepts/context-control.md

@@ -14,7 +14,7 @@ Control context by putting information in the narrowest surface that needs it. K
 | A procedure needed only for some tasks               | A [skill](../skills)                                   | Its description until the model loads the full skill                             |
 | A typed action or external operation                 | A [tool](../tools) or [connection](../connections)     | The callable schema and the result of each call                                  |
 | Files or command execution                           | The [sandbox workspace](../sandbox)                    | A workspace hint, then files and command output the model requests through tools |
-| A specialist with a separate prompt and capabilities | A [subagent](../subagents)                             | A receipt followed by background task notifications                              |
+| A specialist with a separate prompt and capabilities | A [subagent](../subagents)                             | The child's reply as the tool result                                             |
 | Instructions or capabilities that vary by caller     | A [dynamic capability](../guides/dynamic-capabilities) | The values resolved for the active session                                       |
 | Scoped context retrieved from cross-session storage  | [Memory](../memory)                                    | Attributed user-role messages recalled before the current delivery               |
 
@@ -46,7 +46,7 @@ See [Sandbox](../sandbox) for workspace seeding, runtime access, backends, and l
 
 ## Delegate to a specialist with a subagent
 
-Use a subagent when work needs its own instructions, tools, skills, state, or sandbox. The child runs in a separate context instead of adding its working history to the parent. The call returns a task receipt, and later task notifications deliver its outcome.
+Use a subagent when work needs its own instructions, tools, skills, state, or sandbox. The child runs in a separate context instead of adding its working history to the parent. The call waits for the child's reply and returns it as the tool result.
 
 See [Subagents](../subagents) for the distinction between root-agent copies and declared specialists, including their isolation boundaries.