eve 0.5.4 → 0.6.0-beta.3

package/dist/docs/public/README.md

@@ -0,0 +1,89 @@
+# Eve Public Docs
+
+This folder is for app authors using Eve as a framework.
+
+If you want to understand how to build agents with Eve, start here.
+
+Important naming note:
+
+- The framework is called Eve.
+- The current published package name is `eve`.
+- The CLI binary is `eve`.
+
+## Read This First
+
+Read in this order:
+
+1. [Introduction](./introduction.md)
+2. [Getting Started](./getting-started.mdx)
+3. [Project Layout](./reference/project-layout.md)
+4. [`agent.ts`](./agent-config.md)
+5. [TypeScript API](./reference/typescript-api.md)
+6. [Context Control](./advanced/context-control.md)
+7. [Skills](./skills.mdx)
+8. [Tools](./tools.mdx)
+9. [Connections](./connections.mdx)
+10. [Sandboxes](./sandbox.mdx)
+11. [Channels](./channels/overview.mdx)
+12. [Session Context](./advanced/session-context.md)
+13. [Sessions And Streaming](./advanced/sessions-runs-and-streaming.md)
+14. [TypeScript Client](./client/overview.mdx)
+15. [Subagents](./subagents.mdx)
+16. [Schedules](./schedules.mdx)
+17. [Evals](./advanced/evals.md)
+18. [Auth And Route Protection](./advanced/auth-and-route-protection.md)
+19. [Vercel Deployment](./advanced/deployment.md)
+20. [CLI, Build, And Debugging](./reference/cli.md)
+
+## The Public Mental Model
+
+Eve is a filesystem-first framework for durable backend agents.
+
+You author an agent as files on disk:
+
+- instructions in `instructions.md` or `instructions.ts`
+- optional procedures in `skills/`
+- typed integrations in `tools/`
+- external MCP servers in `connections/`
+- the per-agent sandbox override in `sandbox/`
+- messaging integrations in `channels/`
+- shared authored code in `lib/`
+- specialist child agents in `subagents/`
+- recurring jobs in `schedules/`
+- additive runtime config in `agent.ts`
+
+Eve then gives you:
+
+- a stable HTTP message route
+- optional channel webhook routes
+- a reconnectable session stream
+- durable session state across turns
+- a per-agent sandbox with a shared runtime workspace
+- typed runtime helpers accessed through `ctx` (`ctx.session`, `ctx.getSandbox()`, `ctx.getSkill()`)
+
+## The Runtime Shape
+
+The public surface stays filesystem-first, but the implementation model underneath is still useful to
+know:
+
+- channels normalize inbound transport input and define the `continuationToken`
+- the harness does one unit of AI work and decides whether to continue, wait, or finish
+- the runtime persists session state, streams events, and owns workflow orchestration
+
+That is why Eve exposes two identifiers:
+
+- `continuationToken` for the next user message
+- `sessionId` for streaming and inspection
+
+## How To Use These Docs
+
+- Start with the authored filesystem shape and `agent.ts`.
+- Then add runtime surfaces in this order: skills, tools, workspace, sandbox, channels.
+- Then learn the durable runtime model: HITL, session context, sessions, streaming, and
+  continuation-token follow-ups.
+- Then add advanced features: subagents, schedules, route protection, deployment.
+
+## Good Companions In This Repo
+
+- Minimal end-to-end example: [`../../apps/weather-agent`](../../apps/weather-agent)
+- Public API source of truth: [`../../packages/eve/src/public/index.ts`](../../packages/eve/src/public/index.ts)

package/dist/docs/public/advanced/auth-and-route-protection.md

@@ -0,0 +1,270 @@
+---
+title: "Auth & route protection"
+description: "Secure your agent's HTTP routes with an ordered auth walk, verifier helpers, and connection OAuth via Vercel Connect."
+---
+
+Eve has two separate auth concerns, and this page covers both:
+
+- **Route auth** (inbound): who is allowed to reach your agent's HTTP routes. It runs at the channel layer.
+- **Tool and connection auth** (outbound): how your agent signs in to an external service it calls, like an OAuth MCP server.
+
+They are independent. Route auth gates the request before any model work runs; tool and connection auth happens later, when a tool or connection actually reaches out. Start with route auth.
+
+## Route auth
+
+Route auth runs at the channel layer. The policy lives on the HTTP channel factory (`agent/channels/eve.ts`) and guards three routes:
+
+- `POST /eve/v1/session`
+- `POST /eve/v1/session/:sessionId`
+- `GET /eve/v1/session/:sessionId/stream`
+
+`GET /eve/v1/health` is always public and skips the walk entirely, so load balancers and uptime monitors can probe it without credentials.
+
+```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()],
+});
+```
+
+## The ordered auth walk
+
+`auth` takes a single `AuthFn` or an array that Eve walks in order. Each entry has three possible outcomes:
+
+- returns a `SessionAuthContext`: accept the request and stop the walk
+- returns `null` / `undefined`: skip to the next entry
+- **throws**: reject with a specific status
+
+If every entry skips, the request gets a `401`. An empty array `auth: []` rejects everything.
+
+```ts
+import { type AuthFn, localDev, vercelOidc } from "eve/channels/auth";
+import { eveChannel } from "eve/channels/eve";
+import { getSession } from "@/lib/auth";
+
+function appSession(): AuthFn<Request> {
+  return async (request) => {
+    const session = await getSession(request);
+    if (!session) return null; // skip; fall through to the next entry
+    return {
+      attributes: { providerId: session.providerId },
+      authenticator: "app",
+      principalId: session.userId,
+      principalType: "user",
+    };
+  };
+}
+
+export default eveChannel({
+  auth: [appSession(), localDev(), vercelOidc()],
+});
+```
+
+Put your own providers ahead of the catch-all helpers. Any entry that doesn't recognize the caller returns `null`, and the walk moves on.
+
+Want a precise status instead of a skip? Throw:
+
+```ts
+import { ForbiddenError, UnauthenticatedError } from "eve/channels/auth";
+
+throw new UnauthenticatedError({
+  code: "authentication_required",
+  message: "Sign in to continue.",
+}); // 401
+throw new ForbiddenError({ message: "Not allowed on this workspace." }); // 403
+```
+
+Any other thrown error follows the normal channel failure path. Building a custom channel on `defineChannel`? Call `routeAuth(request, auth)` from `eve/channels/auth` to reuse the same walk semantics.
+
+## Verifier helpers
+
+`eve/channels/auth` ships these channel-auth helpers:
+
+| Helper           | Use when                                                                  |
+| ---------------- | ------------------------------------------------------------------------- |
+| `localDev()`     | Local development. Accepts requests addressed to a loopback hostname.     |
+| `vercelOidc()`   | The common Vercel deployment path. Verifies a Vercel OIDC bearer JWT.     |
+| `none()`         | You want to accept anonymous traffic explicitly (use as the final entry). |
+| `httpBasic(...)` | Operator or service access via a shared username/password.                |
+| `jwtHmac(...)`   | You control a shared-secret JWT signer.                                   |
+| `jwtEcdsa(...)`  | You verify asymmetric JWTs minted by another system.                      |
+| `oidc(...)`      | You want Eve to verify OIDC-issued tokens from an arbitrary issuer.       |
+
+### `localDev()`
+
+Authenticates a synthetic `local-dev` principal, but only when the inbound request is addressed to a loopback hostname (`localhost`, `*.localhost`, `127.0.0.0/8`, or `::1`). The check keys off the request URL's hostname rather than the bare `process.env.VERCEL` flag, and that's deliberate: a deployment outside Vercel leaves `VERCEL` unset, so sniffing that flag alone would wave through all public traffic. There's one process-level exception. `vercel dev`, detected by `VERCEL=1` and `VERCEL_ENV=development` together, opens the local dev server even when it serves over a non-loopback host. Every other non-loopback request returns `null` and falls through.
+
+`localDev()` trusts the advertised hostname, so an attacker who can inject a `Host` header (no normalizing proxy in front of your origin) can spoof it. Always layer a real authenticator on top; never run on `localDev()` alone.
+
+### `vercelOidc()`
+
+Verifies a bearer JWT against the [Vercel OIDC issuer](https://vercel.com/docs/oidc). Tokens minted for the current `VERCEL_PROJECT_ID` are always accepted, which is why internal subagent and runtime callers authenticate with zero configuration. Tokens carrying an `external_sub` authenticate as user callers, but only when their `project_id` matches `VERCEL_PROJECT_ID` and their environment matches `VERCEL_TARGET_ENV` / `VERCEL_ENV`. In that case `external_sub` becomes the session subject, and the profile claims (`name`, `picture`, `email`) show up in `ctx.session.auth.current.attributes`. To admit tokens minted by other Vercel projects, pass `subjects: [...]` (AWS IAM-style `*` wildcards).
+
+Auth fails closed: routes reject unauthenticated traffic by default, and the OIDC user branch verifies `external_sub` against `VERCEL_PROJECT_ID` and the deployment environment, returning `false` when either is unset. An external-subject token cannot authenticate on a deployment that hasn't pinned its project.
+
+#### `subjects` patterns and `vercelSubject(...)`
+
+Each `subjects` entry is matched against the token's `sub` claim, which Vercel shapes as `owner:<team>:project:<name>:environment:<env>`. Hand-writing that string is a footgun: a typo silently rejects every caller, and an over-broad `*` wildcard silently lets unrelated ones in. Build the pattern with `vercelSubject(...)` instead. It rejects malformed input at construction time and forces an explicit `environment` (defaulting to `"production"`):
+
+```ts
+import { vercelOidc, vercelSubject } from "eve/channels/auth";
+
+vercelOidc({
+  subjects: [
+    vercelSubject({ teamSlug: "partner", projectName: "data" }), // environment defaults to "production"
+    vercelSubject({ teamSlug: "acme", projectName: "agent", environment: "*" }),
+  ],
+});
+```
+
+`teamSlug` and `projectName` are the human-readable slugs Vercel embeds in `sub` (not the stable `team_…` / `prj_…` IDs), so they can't contain `:` or `*`. `environment` is `"production" | "preview" | "development" | "*"`. Only hand-write the subject string yourself when you actually mean to match across teams with a wildcard.
+
+### Custom verifiers
+
+When none of the shipped helpers fit, write your own `AuthFn` (the array example above) or call the low-level verifiers directly. Each verifier is the pure function sitting behind the matching strategy helper, and returns `{ ok: true, sessionAuth }` or `{ ok: false }`:
+
+| Verifier                               | Behind         | Input                            |
+| -------------------------------------- | -------------- | -------------------------------- |
+| `verifyHttpBasic(header, credentials)` | `httpBasic()`  | raw `Authorization` header value |
+| `verifyJwtHmac(token, config)`         | `jwtHmac()`    | bearer token (HMAC-signed JWT)   |
+| `verifyJwtEcdsa(token, config)`        | `jwtEcdsa()`   | bearer token (ECDSA-signed JWT)  |
+| `verifyOidc(token, config)`            | `oidc()`       | bearer token (OIDC, any issuer)  |
+| `verifyVercelOidc(token, opts)`        | `vercelOidc()` | bearer token (Vercel OIDC)       |
+
+Pull the token with `extractBearerToken(request.headers.get("authorization"))` before you hand it to the JWT/OIDC verifiers. The configs (`VerifyJwtHmacConfig`, `VerifyJwtEcdsaConfig`, `VerifyOidcConfig`) take `issuer`, `audiences`, the signing material (`secret` / `publicKey` / `discoveryUrl`), and optional `subjects` / `claims` matchers.
+
+```ts
+import { extractBearerToken, verifyJwtHmac, type AuthFn } from "eve/channels/auth";
+
+function hmacAuth(): AuthFn<Request> {
+  return async (request) => {
+    const token = extractBearerToken(request.headers.get("authorization"));
+    const result = await verifyJwtHmac(token, {
+      algorithm: "HS256",
+      issuer: "https://auth.example.com",
+      audiences: ["agent"],
+      secret: process.env.JWT_SECRET!,
+    });
+    return result.ok ? result.sessionAuth : null;
+  };
+}
+```
+
+### Failure responses in custom `defineChannel` routes
+
+If a `defineChannel` route handler runs its own checks instead of `routeAuth`, it can still emit a framework-shaped failure with `createUnauthorizedResponse(...)`. You get back a `Response` with `cache-control: no-store`, a `{ ok: false, code, error }` JSON body, and one `www-authenticate` header per challenge:
+
+```ts title="agent/channels/intake.ts"
+import { defineChannel, POST } from "eve/channels";
+import { createUnauthorizedResponse } from "eve/channels/auth";
+
+export default defineChannel({
+  routes: [
+    POST("/message", async (req, { send }) => {
+      if (!isAllowed(req)) {
+        return createUnauthorizedResponse({
+          status: 403, // defaults to 401; code defaults to "forbidden" / "unauthorized"
+          message: "Not allowed on this workspace.",
+          challenges: [{ scheme: "Bearer" }],
+        });
+      }
+      // authenticated: handle the request
+    }),
+  ],
+});
+```
+
+`UnauthenticatedError` and `ForbiddenError` wrap this builder (status `401` / `403`). Throw those from an `AuthFn` that `routeAuth` walks. Call `createUnauthorizedResponse` directly only when you're returning a `Response` from a hand-rolled route.
+
+## Network policy
+
+`eve/channels/auth` exports `createIpAllowList(...)` and `isIpAllowed(...)` for cutting off requests before any model work starts. A request that fails the network policy is dropped ahead of both auth and runtime execution.
+
+## Replace `placeholderAuth` before production
+
+`pnpm create eve` sometimes scaffolds `agent/channels/eve.ts` with a `placeholderAuth()` guardrail:
+
+```ts
+import { eveChannel } from "eve/channels/eve";
+import { localDev, placeholderAuth, vercelOidc } from "eve/channels/auth";
+
+export default eveChannel({
+  auth: [localDev(), vercelOidc(), placeholderAuth()],
+});
+```
+
+In production, `placeholderAuth()` returns a structured `401` so a generated web chat app can say "auth isn't configured yet" instead of throwing an internal error. Replace it before a browser caller submits a production request: swap in your app's `AuthFn` or one of the shipped helpers. Delete the authored channel file entirely and Eve falls back to the framework default `[localDev(), vercelOidc()]`, which also rejects production browser traffic.
+
+Keep secret values (`ROUTE_AUTH_BASIC_PASSWORD`, signing keys) in environment variables. Route-auth secrets never land in compiled artifacts. The runtime re-materializes them from the authored channel definition at boot.
+
+## What reaches `ctx.session.auth`
+
+Inside runtime code, `ctx.session.auth` carries the result of the channel's route auth (the walk above) forward as the caller snapshot:
+
+- `auth.current`: the caller on the active inbound turn.
+- `auth.initiator`: the caller that started the durable session.
+- A follow-up message updates `auth.current` but leaves `auth.initiator` alone. So when a different caller follows up on the same session, `auth.current` tracks the new caller for that turn while `auth.initiator` stays pinned to whoever started it.
+- Both are `null` only on internal runtime paths (subagents, for instance) that never went through an authored route. HTTP traffic always populates `auth.current`, since the walk either accepts with a `SessionAuthContext` or returns `401`.
+
+Use the principal on `auth.current` (or `auth.initiator`) to scope tools, resolve [dynamic capabilities](./dynamic-capabilities) per principal, or enforce tenant boundaries. There's no second per-session ownership ACL stacked on top of route auth: access is decided at the HTTP boundary, and the durable session just carries the caller snapshot forward into your runtime code.
+
+## Tool and connection auth
+
+Route auth decides who reaches your agent. Tool and connection auth is the flip side: how your agent reaches an external service that wants an interactive sign-in, like an OAuth MCP server. Both a connection and an individual tool can declare an `auth` strategy; Eve drives the sign-in, caches the token per step, and re-runs the call once the caller authorizes.
+
+### On a connection
+
+Attach `connect()` from `@vercel/connect/eve` to the connection:
+
+```ts title="agent/connections/linear.ts"
+import { connect } from "@vercel/connect/eve";
+import { defineMcpClientConnection } from "eve/connections";
+import { once } from "eve/tools/approval";
+
+export default defineMcpClientConnection({
+  url: "https://mcp.linear.app/mcp",
+  description: "Linear: project management, issue tracking, and team workflows.",
+  auth: connect("oauth/linear"),
+  approval: once(),
+});
+```
+
+The first call that needs the connection kicks off an OAuth sign-in, surfaced as an authorization challenge (a URL the caller visits). [Vercel Connect](https://vercel.com/docs/connect) brokers the flow and holds the credentials, which are resolved and cached per workflow step, never serialized into history, and never shown to the model. For non-interactive connections, pass a static token in place of `connect()`. [Connections](../connections) covers both shapes.
+
+### On a single tool
+
+When one tool calls a service behind OAuth, it can declare its own `auth` and skip the separate connection. `auth` takes the same shapes: `connect("...")` for Vercel Connect-backed OAuth, a custom interactive definition, or a plain `{ getToken }` for static credentials.
+
+```ts title="agent/tools/list_okta_groups.ts"
+import { defineTool } from "eve/tools";
+import { connect } from "@vercel/connect/eve";
+import { z } from "zod";
+
+export default defineTool({
+  description: "List the caller's Okta groups.",
+  inputSchema: z.object({}),
+  auth: connect("okta"),
+  async execute(_input, ctx) {
+    const { token } = await ctx.getToken();
+    const res = await fetch("https://api.okta-proxy.internal/groups", {
+      headers: { authorization: `Bearer ${token}` },
+    });
+    return res.json();
+  },
+});
+```
+
+Declaring `auth` adds two accessors to the tool's `ctx`:
+
+- `ctx.getToken()` resolves the bearer for the declared strategy, checking the per-step token cache first. With an interactive strategy, a cache miss suspends the turn on a framework-owned callback URL, shows a "Sign in" affordance, and re-runs the tool once the OAuth callback completes.
+- `ctx.requireAuth()` throws `ConnectionAuthorizationRequiredError` to gate the tool on authorization before any token resolves. The runtime turns that into the same consent prompt.
+
+Throw `ConnectionAuthorizationRequiredError` anywhere in `execute` (directly, via `requireAuth()`, or implicitly from `getToken()`) and you trigger the consent flow, keyed by the tool's name. Calling either accessor on a tool that does not declare `auth` throws.
+
+## What to read next
+
+- [Security model](./security-model): trust boundaries and the pre-production checklist
+- [Connections](../connections): connection auth shapes (`connect()` vs static token)
+- [Deployment](./deployment): where route-auth secrets live in production

package/dist/docs/public/advanced/context-control.md

@@ -0,0 +1,109 @@
+---
+title: "Context control"
+description: "Control what the model sees and when: instructions, skills, the workspace, and subagents."
+---
+
+Eve gives you a few levers for controlling what the model sees and when it sees it.
+
+The most useful mental model is:
+
+- `instructions.md` (or `instructions.ts`) is always on.
+- `skills/` are available but loaded on demand.
+- The workspace and sandbox are visible through tools, not pasted into the prompt.
+
+## 1. Base identity with `instructions.md`
+
+Use `instructions.md` for the core contract of the agent.
+
+```md
+You are a careful support assistant. Be concise, verify facts before replying, and explain when you
+used a tool.
+```
+
+Keep this file focused on stable behavior that should apply on every turn.
+
+## 2. Compose instructions in TypeScript with `instructions.ts`
+
+When you want to build the instructions prompt from typed helpers, lib code, or environment-derived values, author it as a module instead of markdown.
+
+```ts title="agent/instructions.ts"
+import { defineInstructions } from "eve/instructions";
+import { buildInstructionsPrompt } from "./lib/prompts.js";
+
+export default defineInstructions({
+  markdown: buildInstructionsPrompt(),
+});
+```
+
+Module-backed instructions run once at build time. Eve captures the resulting markdown into the compiled manifest, so the runtime serves the same prompt every session without re-running the module.
+
+## 3. Load procedures on demand with `skills/`
+
+Skills are not part of the always-on prompt by default.
+
+Instead, Eve advertises the available skills and adds a framework-owned `load_skill` tool. When the request clearly matches a skill description, or the user names a skill explicitly, the model activates that skill, and Eve appends the skill's markdown to the active instructions for later turn work.
+
+That is how you keep rich procedures available without bloating every turn.
+
+### Flat skill
+
+```md title="agent/skills/get-weather.md"
+Use the weather tool before answering forecast or temperature questions.
+```
+
+### Packaged skill
+
+```md title="agent/skills/research/SKILL.md"
+---
+description: Research unfamiliar topics before answering with confidence.
+---
+
+When the task is novel or ambiguous, gather evidence first, then answer with the key facts and the
+remaining uncertainty.
+```
+
+Packaged skills are useful when you also want sibling files such as `references/`, `assets/`, or `scripts/` under the same skill directory. Those packaged paths show up under the runtime workspace root, so the model can inspect them with the normal file or shell tools instead of pasting all of that content into the prompt.
+
+See [Skills](../skills) for the full authoring model and install notes.
+
+## 4. Put runtime files in the workspace, not the prompt
+
+Eve does not inline the entire authored surface into the prompt. Instead, it gives the model a shallow workspace hint and runtime tools to inspect deeper when needed. That keeps prompts smaller and makes file and command work explicit: skill files are available under the active workspace root, and the model can inspect them with the shared `bash` tool.
+
+See [Sandbox](../sandbox) for the workspace and sandbox model.
+
+## 5. Delegate to a specialist with a subagent
+
+If a task deserves its own prompt and tool surface, use a local subagent instead of overloading the root agent. Subagents are a context-control tool too: they get their own `instructions.md`, their own tools, and their own sandbox, and they run inside their own delegated context instead of extending the root agent inline.
+
+See [Subagents](../subagents).
+
+## Dynamic context with `defineDynamic`
+
+The levers above are static: authored once, the same on every session. When the right context depends on who is calling (their team, tenant, plan, or feature flags), resolve it at runtime instead. `defineDynamic` in `agent/instructions/` returns the per-session system prompt, and `defineDynamic` in `agent/skills/` returns the set of skills a caller can load. Both read `ctx.session.auth` or channel metadata, so a caller on the billing team gets the billing instructions and playbook while nobody else sees them. See [Dynamic capabilities](./dynamic-capabilities) for the resolver API and when each event fires.
+
+## Choosing the right lever
+
+Use:
+
+- `instructions.md` for the agent's permanent identity.
+- `instructions.ts` when you need to compose the prompt from typed helpers at build time.
+- `skills/` for optional procedures that should load only when needed.
+- a subagent when the task needs a different specialist surface.
+- the workspace or sandbox when the model should inspect files or run commands instead of relying on pasted instructions.
+
+## A good pattern
+
+For most agents:
+
+1. Keep `instructions.md` short and stable.
+2. Move long procedures into `skills/`.
+3. Expose typed integrations through `tools/`.
+4. Use subagents only for real specialization boundaries.
+
+## What to read next
+
+- [Tools](../tools)
+- [Skills](../skills)
+- [Subagents](../subagents)
+- [Hooks](./hooks)

package/dist/docs/public/advanced/default-harness.md

@@ -0,0 +1,94 @@
+---
+title: "The Harness"
+description: "The out-of-the-box agent loop and the built-in tools every Eve agent ships with, plus how to override or disable them."
+---
+
+The default harness is what every Eve agent ships with: the framework-owned agent loop, plus a set of built-in tools the model can call without you writing a line. You extend the base harness with capabilities specific to your agent. The loop itself, how a turn runs and checkpoints and resumes, lives in [Execution model & durability](./execution-model-and-durability).
+
+## Compaction
+
+A long session eventually fills the model's context window. The harness handles that for you: once the conversation crosses a fraction of the window (`thresholdPercent`, `0.9` by default), it summarizes the older turns into a compact form and keeps going, so the session continues instead of overflowing. The summary uses the active turn model unless you override it. Tune when and how it kicks in under [`compaction`](../agent-config#compaction) in `agent.ts`:
+
+```ts title="agent/agent.ts"
+export default defineAgent({
+  model: "anthropic/claude-opus-4.8",
+  compaction: {
+    thresholdPercent: 0.75,
+  },
+});
+```
+
+Compaction is also a hook point for tools. When the harness compacts history, it calls each tool's `onCompact(input, ctx)` in registration order, so a tool can re-inject the facts it needs to survive the summary: appending a short message, or patching session state. See [`onCompact`](./dynamic-capabilities) for the hook contract.
+
+## Built-in tools
+
+These ship with every agent, no imports. Discovery never runs them: the harness shows the model the tool descriptors first, then executes only what the model actually calls. The shell and file tools run inside the agent's single [sandbox](../sandbox); the rest run in the app runtime.
+
+| Tool                | Does                                                                                                                                                              | Where it runs |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `bash`              | Run a shell command.                                                                                                                                              | Sandbox       |
+| `read_file`         | Read a text file with line-numbered output (enables read-before-write).                                                                                           | Sandbox FS    |
+| `write_file`        | Write a complete file; enforces read-before-write and stale-read detection.                                                                                       | Sandbox FS    |
+| `glob`              | Find files by glob pattern.                                                                                                                                       | Sandbox FS    |
+| `grep`              | Search file contents by regex.                                                                                                                                    | Sandbox FS    |
+| `web_fetch`         | Fetch a URL.                                                                                                                                                      | App runtime   |
+| `web_search`        | Search the web (provider-managed; resolved from the model provider).                                                                                              | Provider      |
+| `todo`              | Maintain a durable per-session todo list.                                                                                                                         | App runtime   |
+| `ask_question`      | Ask the user a clarifying question or a choice mid-turn and park until they answer. No `execute`; the model calls it with `{ prompt, options?, allowFreeform? }`. | App runtime   |
+| `agent`             | Delegate a subtask to a copy of itself (shares the parent sandbox + tools, fresh history/state).                                                                  | App runtime   |
+| `load_skill`        | Pull an on-demand [skill](../skills)'s instructions into the current turn. Present only when the agent declares skills.                                           | App runtime   |
+| `connection_search` | Discover tools across declared [connections](../connections); matched tools become directly callable. Present only when the agent declares connections.           | App runtime   |
+
+Notes:
+
+- **`agent`** runs a copy of the current agent on a focused task. It inherits the same tools, connections, and instructions, but starts with fresh conversation history and fresh [state](./state). The child shares the parent's sandbox filesystem, so anything it writes is visible to the parent. See [Subagents](../subagents).
+- **`load_skill`** only pulls instructions into context. It adds no new execution surface, because behavior still comes from the tools the agent already has.
+- **`connection_search`** is the model-facing `connection__search` tool. A search surfaces a connection's tools by their qualified name (e.g. `connection__linear__list_issues`), and the model can then call them directly. It's registered only when the agent has connections.
+- **`web_search`** has no local executor; the provider runs it. To supply your own implementation, override it with `defineTool()`.
+
+## Override a default
+
+Author a tool at the same slug and it takes over the built-in of that name. The file `agent/tools/write_file.ts` replaces the built-in `write_file` just by existing:
+
+```ts title="agent/tools/write_file.ts"
+import { defineTool } from "eve/tools";
+import { writeFile } from "eve/tools/defaults";
+
+export default defineTool({
+  ...writeFile, // keep the default description, schema, and executor
+  async execute(input, ctx) {
+    console.log("[write_file]", input.path);
+    return writeFile.execute(input, ctx);
+  },
+});
+```
+
+The framework defaults are importable from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `webSearch`, `todo`, `loadSkill`), so you can spread, wrap, or patch them. Skip the spread and your replacement owns its own context: a fresh `defineTool` for `todo` won't inherit the framework's durable state key.
+
+## Disable a default
+
+Export a `disableTool()` sentinel from a file named after the tool's slug. The filename is what picks the default to remove:
+
+```ts title="agent/tools/bash.ts"
+import { disableTool } from "eve/tools";
+
+export default disableTool();
+```
+
+Misspell the filename so it matches no known framework tool and it fails at resolve time, instead of silently doing nothing.
+
+## The opt-in `Workflow` tool
+
+There's also an experimental `Workflow` tool, shipped but off by default. To turn it on, re-export the opt-in marker from `agent/tools/workflow.ts`:
+
+```ts
+export { ExperimentalWorkflow as default } from "eve/tools";
+```
+
+With it on, the model can orchestrate the agent's own subagents from model-authored JavaScript, all as one durable step. See [Dynamic workflows](./dynamic-workflows).
+
+## What to read next
+
+- [Tools](../tools): define your own tools, gate them on approval, and shape their output (`toModelOutput` / `onCompact`)
+- [Dynamic capabilities](./dynamic-capabilities): generate the tool set per session with `defineDynamic`
+- [Sandbox](../sandbox): the sandbox the shell and file tools run in