eve 0.5.4 → 0.6.0-beta.3

package/dist/docs/public/advanced/state.md

@@ -0,0 +1,62 @@
+---
+title: "State"
+description: "Durable per-session memory with defineState: get() and update(), persisted across step boundaries."
+---
+
+`defineState` is a typed, named slot of durable per-session memory for an agent. Use it when the agent has to remember something between the turns of a conversation (a running budget, a glossary, a checklist) and you don't want to stand up an external store for it. The values survive workflow step boundaries, so they outlast crashes, redeploys, and days-long sessions.
+
+```ts
+import { defineState } from "eve/context";
+
+const budget = defineState("my-agent.budget", () => ({ count: 0, cap: 25 }));
+```
+
+Pass `defineState(name, initial)` a stable string `name` (namespace it to your agent) and an `initial` function that produces the starting value the first time the slot is read. You get back a `StateHandle<T>`:
+
+- `get()`: read the current value. Returns `initial()` on first access within a context.
+- `update(fn)`: replace the value with `fn(current)`.
+
+Use the handle from inside a tool, hook, or other framework-managed runtime code:
+
+```ts title="agent/tools/spend.ts"
+import { defineState } from "eve/context";
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+const budget = defineState("my-agent.budget", () => ({ count: 0, cap: 25 }));
+
+export default defineTool({
+  description: "Run a query, counting it against the session budget.",
+  inputSchema: z.object({ sql: z.string() }),
+  async execute({ sql }) {
+    const { count, cap } = budget.get();
+    if (count >= cap) throw new Error("Query budget exhausted for this session.");
+    budget.update((s) => ({ ...s, count: s.count + 1 }));
+    return runQuery(sql);
+  },
+});
+```
+
+`get()` and `update()` require an active Eve context. Calling them outside tools, hooks, or framework-managed code throws.
+
+## Reset state between turns
+
+State is durable by default and does not reset between turns. If you want a clean slate every turn, overwrite it from a lifecycle [hook](./hooks) on `turn.started`:
+
+```ts
+budget.update(() => ({ count: 0, cap: 25 }));
+```
+
+## State is never shared with subagents
+
+Every [subagent](../subagents) starts with its own fresh state, whether it's a built-in `agent` copy or a declared specialist. `defineState` values never cross the parent/child boundary, even when the child is a copy of the same agent.
+
+## State vs. connection-side storage
+
+`defineState` is for conversation-scoped working memory that lives and dies with the session: counters, the current plan, what the user has told you this conversation. Anything that has to outlive the session, be shared across sessions or users, or be queried independently of a turn belongs in an external store, either a [connection](../connections) or your own database. State is not a database. It's the agent's short-term memory, persisted durably for the life of the session.
+
+## What to read next
+
+- Read state inside dynamic resolvers → [Dynamic capabilities](./dynamic-capabilities)
+- How step durability works → [Execution model & durability](../advanced/execution-model-and-durability)
+- The `ctx` accessors available alongside state → [Tools](../tools)

package/dist/docs/public/agent-config.md

@@ -0,0 +1,80 @@
+---
+title: "agent.ts"
+description: "The agent's runtime config: defineAgent, the model, and compaction."
+---
+
+Every agent has an `agent.ts` that calls `defineAgent` (from `eve`) to set its runtime config.
+
+## A good default
+
+Most agents need exactly this, a model:
+
+```ts title="agent/agent.ts"
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  model: "anthropic/claude-opus-4.8",
+});
+```
+
+`model` can be a gateway model id string (which routes through the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway)) or a provider-authored `LanguageModel`, when you want to call the provider directly, bypassing the gateway and configuring the model in code:
+
+```ts title="agent/agent.ts"
+import { anthropic } from "@ai-sdk/anthropic";
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  model: anthropic("claude-opus-4.8"),
+});
+```
+
+## Compaction
+
+Compaction summarizes older turns as you approach the context window. It is on by default, so you only touch it to tune when it kicks in. Lower `thresholdPercent` to compact sooner:
+
+```ts title="agent/agent.ts"
+export default defineAgent({
+  model: "anthropic/claude-opus-4.8",
+  compaction: {
+    thresholdPercent: 0.75, // default 0.9
+  },
+});
+```
+
+See [Default harness](./advanced/default-harness#compaction) for how the loop applies it.
+
+## Other fields
+
+`defineAgent` takes a few more fields. For every field and its type, see the [TypeScript API](./reference/typescript-api).
+
+### `modelOptions`
+
+Provider option overrides forwarded to the model call.
+
+### `experimental`
+
+Opt-in flags that can change or disappear in any release, so treat them as unstable. The main one is `codeMode`, which routes executable tools through a sandboxed code-execution wrapper.
+
+### `outputSchema`
+
+A structured return type for task-mode runs: a subagent, schedule, or remote job.
+
+### `build`
+
+Hosted-build packaging, such as `externalDependencies` to keep listed packages external and trace them into the hosted output.
+
+## Where adjacent settings live
+
+| Concern                       | Lives in                                                                           |
+| ----------------------------- | ---------------------------------------------------------------------------------- |
+| Instructions prompt           | `agent/instructions.md`, [Instructions](./instructions)                            |
+| Per-tool approval (HITL)      | `agent/tools/*.ts`, [Tools](./tools)                                               |
+| Inbound auth & network policy | the channel layer, [Auth & route protection](./advanced/auth-and-route-protection) |
+| Sandbox / workspace           | `agent/sandbox/`, [Sandbox](./sandbox)                                             |
+| Telemetry & debugging         | `agent/instrumentation.ts`, [Instrumentation](./advanced/instrumentation)          |
+
+## What to read next
+
+- [Default harness](./advanced/default-harness) for the loop and built-in tools this config drives
+- [TypeScript API](./reference/typescript-api) for every `defineAgent` field and type
+- [Subagents](./subagents) for the `description` requirement and child-agent config

package/dist/docs/public/channels/custom.mdx

@@ -0,0 +1,275 @@
+---
+title: "Custom channels"
+description: "Author custom HTTP and WebSocket channels with routes, events, metadata, continuation tokens, and file uploads."
+---
+
+When Eve doesn't ship a channel for your surface, you build one. Custom channels let you expose HTTP or WebSocket endpoints, parse incoming requests, start or resume sessions, observe runtime events, and own delivery back to your platform.
+
+## File location and identity
+
+Custom channels live in `agent/channels/` at the root agent. Local subagents do not declare channels today.
+
+The channel file stem becomes the channel id, so `agent/channels/internal-webhook.ts` is addressed as `internal-webhook`. Channel files are module-backed: export the channel definition as the default export.
+
+## Define a channel
+
+```ts
+import { defineChannel, GET, POST } from "eve/channels";
+
+export default defineChannel({
+  routes: [
+    POST("/message", async (req, { send }) => {
+      const body = await req.json();
+      const session = await send(body.message, {
+        auth: null,
+        continuationToken: body.token,
+      });
+
+      return Response.json({ sessionId: session.id });
+    }),
+    GET("/sessions/:sessionId/stream", async (_req, { getSession, params }) => {
+      const session = getSession(params.sessionId);
+      const stream = await session.getEventStream();
+
+      return new Response(stream, {
+        headers: { "content-type": "text/event-stream" },
+      });
+    }),
+  ],
+  events: {
+    "message.completed"(event, channel, ctx) {
+      // deliver completed messages back to the surface that owns this channel
+    },
+  },
+});
+```
+
+`defineChannel({ routes, ... })` defines a channel. Routes are declared with the `POST()` and `GET()` helpers. Each route handler receives the raw `Request` and a helpers object:
+
+- `send(message, { auth, continuationToken, state? })`: start or resume a session. Returns a `Session`.
+- `getSession(sessionId)`: look up an existing session. The returned `Session` exposes `getEventStream({ startIndex? })` for streaming.
+- `params`: route parameters extracted from the path pattern.
+- `waitUntil(promise)`: extend the request lifetime for background work.
+
+Event handlers like `"message.completed"` are declared under the `events` key. They receive `(eventData, channel, ctx)`, where `channel` carries platform handles and session continuation operations, and `ctx` is the Eve `SessionContext`.
+
+## WebSocket routes
+
+Use `WS()` when a custom channel needs a WebSocket endpoint. The route handler runs once per upgrade request and returns lifecycle hooks for that connection:
+
+```ts
+import { defineChannel, WS } from "eve/channels";
+
+export default defineChannel({
+  routes: [
+    WS("/voice/ws", async (_req, { send }) => ({
+      async message(_peer, message) {
+        await send(message.text(), {
+          auth: null,
+          continuationToken: "voice-demo",
+        });
+      },
+    })),
+  ],
+});
+```
+
+`WS()` handlers receive the same helpers as HTTP route handlers: `send`, `getSession`, `receive`, `params`, `waitUntil`, and `requestIp`. The returned hooks are Eve-owned structural types compatible with Nitro/H3 websocket routing, including `upgrade`, `open`, `message`, `close`, and `error`.
+
+### Node upgrade server escape hatch
+
+Prefer the `WS()` lifecycle hooks above when you own the websocket behavior. Eve also exposes `createWebSocketUpgradeServer()` for the narrower case where a third-party SDK or framework expects to bind directly to a Node `http.Server` with `server.on("upgrade", ...)`.
+
+```ts
+import { defineChannel, WS, createWebSocketUpgradeServer } from "eve/channels";
+
+const bridge = createWebSocketUpgradeServer();
+
+thirdPartySdk.attach(bridge.server);
+
+export default defineChannel({
+  routes: [WS("/vendor/ws", bridge.route)],
+});
+```
+
+The bridge server does not listen on its own port. It receives only upgrade events that matched the Eve route, and only on hosts where Nitro exposes the raw Node upgrade request, socket, and head. Treat it as a compatibility adapter for libraries with server-binding APIs, not as the primary way to build websocket channels in Eve.
+
+## Cross-channel hand-off
+
+Route handlers can start a session on a different channel via `args.receive(channel, ...)`. Use this when an inbound request on one channel should pivot the conversation onto another, such as an incident webhook that opens an investigation thread in Slack.
+
+```ts
+import { defineChannel, POST } from "eve/channels";
+import slack from "./slack.js";
+
+export default defineChannel({
+  routes: [
+    POST("/incident", async (req, args) => {
+      const incident = await req.json();
+
+      args.waitUntil(
+        args.receive(slack, {
+          message: `Investigate ${incident.reference}: ${incident.title}`,
+          target: { channelId: "C0123ABC" },
+          auth: {
+            authenticator: "incidentio",
+            principalType: "service",
+            principalId: incident.actor.id,
+            attributes: { reference: incident.reference, severity: incident.severity },
+          },
+        }),
+      );
+
+      return new Response("ok");
+    }),
+  ],
+});
+```
+
+Semantics:
+
+- The target channel's authored `receive(input, { send })` hook owns the continuation-token format and initial state. Callers supply only `{ message, target, auth }`.
+- `auth` flows through to `session.auth.initiator` so the target's event handlers and the agent's tools can read who started the session.
+- Calling `args.receive(...)` does not also start a session on the current channel. The inbound channel's response is whatever the route handler returns explicitly.
+- The first argument is the target channel module's default export. Import it directly from `agent/channels/<name>.ts`. Identity is matched by reference.
+
+## Channel metadata
+
+Channels can project a subset of their adapter state as metadata available to instrumentation resolvers, dynamic tool resolvers, and dynamic skill or instruction resolvers. Define a `metadata(state)` function on the channel config:
+
+```ts
+import { defineChannel, POST } from "eve/channels";
+
+export default defineChannel({
+  state: {
+    topic: null as string | null,
+    contextMessages: [] as string[],
+    internalCounter: 0,
+  },
+
+  metadata(state) {
+    return {
+      topic: state.topic,
+      contextMessages: state.contextMessages,
+    };
+  },
+
+  routes: [
+    POST("/start", async (req, { send }) => {
+      const body = await req.json();
+      await send(body.message, {
+        auth: null,
+        continuationToken: body.token,
+        state: { topic: body.topic, contextMessages: body.context, internalCounter: 0 },
+      });
+
+      return new Response("ok");
+    }),
+  ],
+  events: {
+    "turn.started"(_event, ctx) {
+      ctx.state.internalCounter += 1;
+    },
+  },
+});
+```
+
+The projection is re-evaluated whenever adapter state changes after channel event handlers run. Dynamic tool resolvers read it via `ctx.channel.metadata` and narrow it with `isChannel`. See [Dynamic capabilities](../advanced/dynamic-capabilities) for the full consumption pattern.
+
+When a parent agent dispatches a subagent, the framework forwards the parent's channel metadata projection to the child. The same `metadata(state)` projector also serves instrumentation metadata resolvers.
+
+## Continuation tokens
+
+Each call to `send(message, { auth, continuationToken, state? })` from a channel route addresses a session by its channel-local raw token. The framework prepends the channel name, derived from the file stem under `agent/channels/`, before handing the token to the runtime.
+
+```ts
+import { slackContinuationToken } from "eve/channels/slack";
+import { twilioContinuationToken } from "eve/channels/twilio";
+
+slackContinuationToken("C0123ABC", "1800000000.001234"); // "C0123ABC:1800000000.001234"
+twilioContinuationToken("+15551234567", "+15557654321"); // "+15551234567:+15557654321"
+```
+
+Custom channels write their own function that joins the identity fields. The framework does not derive anything for you: the channel owns its token format.
+
+When the identity that should address a session is not known until later, the channel can re-key the parked session by calling `ctx.session.setContinuationToken(...)` from a handler. Pass the channel-local raw token; the runtime preserves the current channel namespace.
+
+```ts
+import { defineChannel } from "eve/channels";
+
+defineChannel<{ ref: string | null }>({
+  state: { ref: null },
+  context(state, session) {
+    return {
+      state,
+      registerAnchor(ref: string) {
+        state.ref = ref;
+        session.setContinuationToken(ref);
+      },
+    };
+  },
+  events: {
+    "message.completed"(_event, ctx) {
+      if (!ctx.state.ref) ctx.registerAnchor(mintRef());
+    },
+  },
+  routes: [
+    /* ... */
+  ],
+});
+```
+
+The workflow runtime disposes the current park hook at the next step boundary and registers a new one at the new token. Inbound deliveries already addressed to the old token are dropped, so coordinate with your senders to use the new token.
+
+## File uploads
+
+`send()` accepts `string | UserContent`. To include file attachments, pass a `UserContent` array mixing text and file parts:
+
+```ts
+await send(
+  [
+    { type: "text", text: body.message },
+    { type: "file", data: imageBytes, mediaType: "image/png" },
+  ],
+  { auth, continuationToken },
+);
+```
+
+For platforms like Slack where files sit behind authenticated URLs, put a `URL` object in `FilePart.data` and declare `fetchFile` on the channel config:
+
+```ts
+defineChannel({
+  fetchFile(url) {
+    if (!url.startsWith("https://files.slack.com/")) return null;
+    return fetch(url, { headers: { authorization: `Bearer ${token}` } })
+      .then((r) => r.arrayBuffer())
+      .then((b) => ({ bytes: Buffer.from(b) }));
+  },
+
+  routes: [
+    POST("/webhook", async (req, { send }) => {
+      await send(
+        [
+          { type: "text", text: message.text },
+          ...message.attachments.map((a) => ({
+            type: "file" as const,
+            data: new URL(a.url),
+            mediaType: a.mediaType,
+          })),
+        ],
+        { auth, continuationToken, state },
+      );
+    }),
+  ],
+});
+```
+
+The `URL` object survives the queue boundary as a string and is reconstituted inside the workflow step. The staging pipeline calls `fetchFile(url)`: return bytes to stage the file to the sandbox, or return `null` to let the URL pass through to the model provider.
+
+The framework handles staging bytes to the sandbox, enforcing upload policy, hydrating files for the model call, and reconstituting `URL` objects after queue serialization.
+
+## What to read next
+
+- [Channels overview](./overview)
+- [Dynamic capabilities](../advanced/dynamic-capabilities)
+- [Auth & route protection](../advanced/auth-and-route-protection)

package/dist/docs/public/channels/discord.mdx

@@ -0,0 +1,74 @@
+---
+title: "Discord"
+description: "Reach your agent from Discord HTTP Interactions: slash commands, components, and modals."
+type: integration
+---
+
+The Discord channel wires your agent into Discord's HTTP Interactions: slash and application commands, message components, and modal submissions. The hard part Discord forces on you is the three-second ACK deadline, so the channel verifies the Ed25519 signature headers, acknowledges the command right away, and runs the actual Eve work in the background. See [Channels](./overview) for the contract this builds on.
+
+## Add the channel
+
+```ts title="agent/channels/discord.ts"
+import { discordChannel } from "eve/channels/discord";
+
+export default discordChannel();
+```
+
+```bash
+DISCORD_PUBLIC_KEY=...      # verifies X-Signature-Ed25519 + X-Signature-Timestamp
+DISCORD_APPLICATION_ID=...  # edits the deferred response and sends followups
+DISCORD_BOT_TOKEN=...       # proactive messages + fallback + typing indicators
+```
+
+If you'd rather not use env vars, pass the same values through `credentials: { applicationId, botToken, publicKey }`. The route is `POST /eve/v1/discord` by default. Paste that public URL into your Discord application's Interactions Endpoint URL.
+
+## Register a command
+
+Registering commands is on you, not the channel. Use Discord's API or the Developer Portal. If you give the command a string option named `message`, it lines up with Eve's default prompt extraction:
+
+```bash
+curl -X PUT "https://discord.com/api/v10/applications/$DISCORD_APPLICATION_ID/commands" \
+  -H "Authorization: Bot $DISCORD_BOT_TOKEN" -H "Content-Type: application/json" \
+  -d '[{"name":"ask","description":"Ask the Eve agent","type":1,
+    "options":[{"name":"message","description":"What should the agent do?","type":3,"required":true}]}]'
+```
+
+Use guild commands during development for faster propagation.
+
+## Affordances
+
+`onCommand(ctx, interaction)` is where you decide whether to dispatch and under what `auth`. Return `{ auth }` to proceed or `null` to drop the interaction. Out of the box, auth comes from the invoking user.
+
+```ts
+import { discordChannel } from "eve/channels/discord";
+
+export default discordChannel({
+  onCommand: (ctx, interaction) => ({
+    auth: {
+      principalId: interaction.user.id,
+      principalType: "user",
+      authenticator: "discord",
+      attributes: { channel_id: interaction.channelId, guild_id: interaction.guildId ?? "" },
+    },
+  }),
+  events: {
+    "message.completed"(event, ctx) {
+      if (event.finishReason === "tool-calls") return;
+      if (event.message) ctx.discord.post(event.message);
+    },
+  },
+});
+```
+
+**Delivery.** The default `message.completed` handler edits the deferred response for the first reply and sends followups after that. If the interaction token gets rejected, it falls back to a bot-authenticated channel message. Long text is split to Discord's 2000-char limit, and generated messages default to `allowed_mentions: { parse: [] }`.
+
+**Typing** fires on `turn.started` and `actions.requested`, but only when a bot token is present. In custom hooks, call `ctx.discord.startTyping()` yourself.
+
+**HITL** shows up as Discord components. Confirmations and options become buttons, `display: "select"` becomes a string select, and freeform input becomes a button that opens a modal. When the user responds, the parked session resumes on its own.
+
+**Proactive sessions** go through `receive(discord, { message, target, auth })` from a schedule `run` handler, or `args.receive(discord, ...)` from another channel. Either way you need `DISCORD_BOT_TOKEN`.
+
+## What to read next
+
+- [Channels overview](./overview): the channel contract and every built-in channel
+- [Auth & route protection](../advanced/auth-and-route-protection): authenticating inbound traffic

package/dist/docs/public/channels/eve.mdx

@@ -0,0 +1,82 @@
+---
+title: "Eve"
+description: "The default HTTP API for an agent: session routes, auth, and customization."
+---
+
+The Eve channel is the framework's default HTTP API. It's what the terminal UI, [`useEveAgent`](../frontend/overview), `curl`, and any SDK client talk to when they start sessions, send messages, and stream events. `eveChannel()` mounts the canonical session routes under `/eve/v1/session*`, and they are enabled by default even when `agent/channels/eve.ts` does not exist.
+
+Reach for it when something needs HTTP access to your agent: local tooling, a browser frontend, the terminal UI, or another API client. Most apps never write this file. Add `agent/channels/eve.ts` only to override the defaults, usually the route auth policy:
+
+```ts title="agent/channels/eve.ts"
+import { eveChannel } from "eve/channels/eve";
+import { localDev, vercelOidc } from "eve/channels/auth";
+
+export default eveChannel({
+  auth: [localDev(), vercelOidc()],
+});
+```
+
+## Routes
+
+The channel exposes the routes that create sessions, send follow-ups, and stream events:
+
+- `GET /eve/v1/health`
+- `POST /eve/v1/session` (start a session)
+- `POST /eve/v1/session/:sessionId` (send a follow-up)
+- `GET /eve/v1/session/:sessionId/stream` (stream events, NDJSON)
+
+See [Sessions, runs & streaming](../advanced/sessions-runs-and-streaming) for the request and stream flow.
+
+## Authentication
+
+The `auth` option decides who can call these routes. The built-in helpers are meant for development and trusted infrastructure:
+
+- `localDev()` accepts requests during local development.
+- `vercelOidc()` lets the local CLI reach a deployed agent, and lets other internal deployments from your team call it.
+
+Neither admits browser users or external clients in production. For a public app, wire the channel to your own auth (Clerk, Auth.js, or your own OIDC/JWT verification).
+
+`pnpm create eve` scaffolds an `agent/channels/eve.ts` with a production placeholder so you replace it before going live. The generated channel allows Vercel OIDC and localhost, and includes `placeholderAuth()`, which returns a setup-focused 401 in production until you swap it for real auth. Delete the file and Eve falls back to `[localDev(), vercelOidc()]`, which still does not admit browser users in production.
+
+For the full auth model and helper list, see [Auth & route protection](../advanced/auth-and-route-protection).
+
+## Customization
+
+Use `onMessage` to add request-specific context before the agent sees the user message, and `events` to observe stream events from sessions this channel created:
+
+```ts title="agent/channels/eve.ts"
+import { eveChannel, defaultEveAuth } from "eve/channels/eve";
+import { localDev, vercelOidc } from "eve/channels/auth";
+
+export default eveChannel({
+  auth: [localDev(), vercelOidc()],
+  onMessage(ctx, message) {
+    const callerId = ctx.eve.caller?.principalId ?? "anonymous";
+    return {
+      auth: defaultEveAuth(ctx),
+      context: [`HTTP caller ${callerId} sent: ${message}`],
+    };
+  },
+  events: {
+    "message.completed"(event, channel, ctx) {
+      console.log("Eve response completed", {
+        continuationToken: channel.continuationToken,
+        sessionId: ctx.session.id,
+      });
+    },
+  },
+});
+```
+
+## Clients
+
+The browser side of this API lives in the [Frontend](../frontend/overview) docs, where `useEveAgent` drives the Eve channel from React UI.
+
+For scripts, server-to-server calls, evals, tests, and custom clients, use the [TypeScript Client](../client/overview). It wraps the session routes, continuation token, stream cursor, and reconnect loop.
+
+## What to read next
+
+- [Frontend](../frontend/overview): drive the Eve channel from browser UI with `useEveAgent`
+- [TypeScript Client](../client/overview): call the Eve channel from TypeScript
+- [Auth & route protection](../advanced/auth-and-route-protection): the route auth policy
+- [Sessions, runs & streaming](../advanced/sessions-runs-and-streaming): the routes this channel exposes

package/dist/docs/public/channels/github.mdx

@@ -0,0 +1,56 @@
+---
+title: "GitHub"
+description: "Reach your agent from GitHub App webhooks, with @mention dispatch, PR diff context, and sandbox checkout."
+type: integration
+---
+
+The GitHub channel lets the agent work directly on a repository. Someone `@mentions` it in an issue, PR, or review comment, and the agent answers right there in the thread, with the PR diff already in context and the repo checked out into the sandbox. Under the hood it takes GitHub App webhooks at `/eve/v1/github`, checks the signature, figures out auth from whoever triggered the event, and replies on the native surface. See [Channels](./overview) for the contract this builds on.
+
+## Add the channel
+
+```ts title="agent/channels/github.ts"
+import { githubChannel } from "eve/channels/github";
+
+export default githubChannel({
+  botName: "my-agent",
+  credentials: {
+    appId: process.env.GITHUB_APP_ID,
+    privateKey: process.env.GITHUB_APP_PRIVATE_KEY,
+    webhookSecret: process.env.GITHUB_WEBHOOK_SECRET,
+  },
+});
+```
+
+Every field falls back to an env var (`GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, `GITHUB_WEBHOOK_SECRET`; `botName` reads `GITHUB_APP_SLUG`), so you can drop the `credentials` block entirely once those are set. `appId`/`privateKey`/`webhookSecret` will also take a lazy resolver function if you'd rather fetch them on demand.
+
+Point the GitHub App webhook URL at `https://<deployment>/eve/v1/github`. For mention-driven turns, subscribe to `issue_comment` and `pull_request_review_comment`; add `issues` / `pull_request` if you wire up their opt-in hooks. A comment that `@mention`s `botName` starts a turn.
+
+## Affordances
+
+**Acknowledgement & replies.** When a turn starts, the channel drops an `eyes` reaction on the triggering comment (turn this off with `progress: { reactions: false }`). The reply comes back as a comment, on the timeline or in the review thread, and splits across multiple comments when it runs long. If the turn fails, you get a short error comment carrying an error id.
+
+**PR context.** Summon the agent on a PR and it always sees the diff. PR metadata and the changed-file patch land in `context`. Large generated files still show up in the list, but their patch body is dropped; add more paths to the skip list with `pullRequestContext.excludedFiles`.
+
+**Sandbox checkout.** Before the first model call, every triggered turn checks out the relevant ref into the sandbox, so `read_file`/`glob`/`grep`/`bash` all run against the real tree. The trick with the installation token is that it never enters the sandbox: `git` fetches a token-free URL, and the platform injects auth on egress at the firewall. That requires a firewall-capable backend (Vercel); the local backend skips checkout. Within a session, checkout is incremental across turns.
+
+**Inbound hooks** return `{ auth }` to dispatch, or `null` to ignore. Reach for `defaultGitHubAuth(ctx)` to derive auth from the actor.
+
+```ts
+import { defaultGitHubAuth, githubChannel } from "eve/channels/github";
+
+export default githubChannel({
+  botName: "my-agent",
+  // Replaces the @mention gate. ctx.conversation.kind: "issue" | "pull_request" | "review_thread".
+  onComment: (ctx, comment) => ({ auth: defaultGitHubAuth(ctx) }),
+  // Opt in; no default dispatch on these events.
+  onIssue: (ctx, issue) => (issue.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null),
+  onPullRequest: (ctx, pr) => (pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null),
+});
+```
+
+**Arbitrary API calls.** For anything the channel doesn't wrap, call `ctx.github.request({ method, path, body })`; it carries installation-token auth.
+
+## What to read next
+
+- [Channels overview](./overview): the channel contract and every built-in channel
+- [Auth & route protection](../advanced/auth-and-route-protection): authenticating inbound traffic