# TypeScript API reference

> Exported define* helpers and import paths from packages/eve/src/public, ctx members, approval predicates, built-in tool defaults, and eval/client entrypoints.

- Repository: vercel/eve
- GitHub: https://github.com/vercel/eve
- Human docs: https://grok-wiki.com/public/docs/vercel-eve-759e1d74a10f
- Complete Markdown: https://grok-wiki.com/public/docs/vercel-eve-759e1d74a10f/llms-full.txt

## Source Files

- `docs/reference/typescript-api.md`
- `packages/eve/src/public/index.ts`
- `packages/eve/src/public/definitions/agent.ts`
- `packages/eve/src/public/definitions/tool.ts`
- `packages/eve/src/public/tools/index.ts`
- `packages/eve/src/public/channels/index.ts`

---

---
title: "TypeScript API reference"
description: "Exported define* helpers and import paths from packages/eve/src/public, ctx members, approval predicates, built-in tool defaults, and eval/client entrypoints."
---

The `eve` package exposes a filesystem-first authoring API: you import `define*` helpers, default-export the result from slots under `agent/`, and the compiler derives identity from file paths. The authoritative export surface is `packages/eve/src/public/` (re-exported through `eve` subpath imports in `package.json`). Anything not exported there is a framework internal.

## Path-derived identity

Definitions do not carry `name` or `id` fields. The runtime name comes from the file path:

| Authored path | Runtime identity |
| --- | --- |
| `agent/tools/get_weather.ts` | tool `get_weather` |
| `agent/connections/linear.ts` | connection `linear` |
| `agent/channels/slack.ts` | channel `slack` |
| `agent/skills/deploy.md` | skill `deploy` |
| `evals/smoke/basic.eval.ts` | eval `smoke/basic` |

The root agent identity is derived at compile time from `manifest.agentId` (package name or app-root basename), not from a field in `defineAgent`.

## Authoring pattern

Most authored files follow the same shape: import a helper, default-export the result.

```ts title="agent/agent.ts"
import { defineAgent } from "eve";

export default defineAgent({ model: "anthropic/claude-opus-4.8" });
```

```ts title="agent/tools/get_weather.ts"
import { defineTool } from "eve/tools";
import { z } from "zod";

export default defineTool({
  description: "Get the weather for a city.",
  inputSchema: z.object({ city: z.string() }),
  async execute({ city }, ctx) {
    return { city, condition: "Sunny" };
  },
});
```

`define*` helpers are identity functions at runtime. They preserve literal types, reject unknown keys at compile time, and stamp brands the compiler and lifecycle code validate.

## define* helpers

| Helper | Import from | Authored at |
| --- | --- | --- |
| `defineAgent` | `eve` | `agent/agent.ts` |
| `defineRemoteAgent` | `eve` | `agent/subagents/<id>/agent.ts` |
| `defineTool` | `eve/tools` | `agent/tools/<name>.ts` |
| `defineDynamic` | `eve/tools`, `eve/skills`, `eve/instructions` | matching `agent/` slot |
| `defineMcpClientConnection`, `defineOpenAPIConnection` | `eve/connections` | `agent/connections/<name>.ts` |
| `defineChannel` | `eve/channels` | `agent/channels/<name>.ts` |
| `eveChannel`, `slackChannel`, and other platform factories | `eve/channels/<platform>` | `agent/channels/<platform>.ts` |
| `defineSkill` | `eve/skills` | `agent/skills/<name>.ts` or `.md` |
| `defineInstructions` | `eve/instructions` | `agent/instructions.ts` or `agent/instructions/` |
| `defineHook` | `eve/hooks` | `agent/hooks/<slug>.ts` |
| `defineSchedule` | `eve/schedules` | `agent/schedules/<name>.ts` or `.md` |
| `defineState` | `eve/context` | module scope in tools, hooks, or lifecycle code |
| `defineSandbox` | `eve/sandbox` | `agent/sandbox.ts` |
| `defineInstrumentation` | `eve/instrumentation` | `agent/instrumentation.ts` |
| `defineEval` | `eve/evals` | `evals/<path>.eval.ts` |
| `defineEvalConfig` | `eve/evals` | `evals/evals.config.ts` |
| `useEveAgent` | `eve/react`, `eve/vue`, `eve/svelte` | frontend components |

### defineAgent

`defineAgent` accepts an additive configuration object. Key fields:

<ParamField body="model" type="string | LanguageModel" required>
  Primary model: an AI Gateway model ID or any AI SDK-compatible language model.
</ParamField>

<ParamField body="description" type="string">
  Human-readable purpose. Required for subagents; surfaced as the lowered subagent tool description.
</ParamField>

<ParamField body="compaction" type="object">
  Context compaction settings, including `thresholdPercent`.
</ParamField>

<ParamField body="modelOptions" type="object">
  Provider-specific model call options.
</ParamField>

<ParamField body="modelContextWindowTokens" type="number">
  Escape hatch when the gateway catalog cannot resolve context window metadata.
</ParamField>

<ParamField body="outputSchema" type="StandardJSONSchemaV1 | JsonObject">
  Structured return type for task-mode runs (subagents, schedules, remote jobs). Interactive turns ignore it unless the client supplies a per-message schema.
</ParamField>

<ParamField body="experimental" type="object">
  Opt-in unstable capabilities (for example `codeMode`).
</ParamField>

<ParamField body="build" type="object">
  Packaging options such as `externalDependencies`.
</ParamField>

Authentication and network policies belong on the channel that handles inbound requests, not on `defineAgent`.

### defineTool

`defineTool` schemas use Standard Schema (Zod, Valibot, and others). The public `ToolDefinition` shape includes:

<ParamField body="description" type="string" required>
  Model-facing tool description.
</ParamField>

<ParamField body="inputSchema" type="StandardJSONSchemaV1 | JsonObject" required>
  Validated tool input.
</ParamField>

<ParamField body="outputSchema" type="StandardJSONSchemaV1 | JsonObject">
  Optional structured output schema.
</ParamField>

<ParamField body="execute" type="(input, ctx) => TOutput" required>
  Handler receiving validated input and {@link ToolContext}.
</ParamField>

<ParamField body="needsApproval" type="(ctx) => boolean">
  Per-call HITL gate. Use `always`, `once`, or `never` from `eve/tools/approval`.
</ParamField>

<ParamField body="auth" type="ToolAuthDefinition">
  Authorization strategy. When set, `ctx.getToken()` and `ctx.requireAuth()` become available.
</ParamField>

<ParamField body="toModelOutput" type="(output) => ToolModelOutput">
  Projection controlling what the model sees as the tool result. Channel handlers always receive the full output.
</ParamField>

`defineTool` also exports `defineDynamic` (runtime resolver sentinel), `disableTool()` (opt out of a framework default by slug), and `ExperimentalWorkflow` (opt in to the experimental `Workflow` orchestration tool).

Tool customization factories are also exported from `eve/tools`: `defineBashTool`, `defineGlobTool`, `defineGrepTool`, `defineReadFileTool`, and `defineWriteFileTool`. Use `toolResultFrom` to narrow connection and MCP tool results in `execute`.

### defineDynamic

`defineDynamic` registers runtime resolvers keyed on stream events. The directory you author in determines return shape and which events fire:

| Slot | Return shape | Events honored |
| --- | --- | --- |
| `agent/tools/` | `defineTool(...)`, `Record<string, defineTool(...)>`, or `null` | `session.started`, `turn.started`, `step.started` |
| `agent/skills/` | `defineSkill(...)`, record map, or `null` | `session.started`, `turn.started` |
| `agent/instructions/` | `defineInstructions({ markdown })` or `null` | `session.started`, `turn.started` |

Return `null` to contribute nothing for that event. Map keys become compound slugs (`slug__key`).

### Other define* helpers

- **`defineRemoteAgent`** — declares a remote Eve deployment the parent calls as a subagent tool. Requires `description` and `url`; defaults `path` to `/eve/v1/session`. Optional `auth`, `headers`, and `outputSchema`.
- **`defineMcpClientConnection` / `defineOpenAPIConnection`** — MCP and OpenAPI integrations. Also exports `defineInteractiveAuthorization` and connection authorization error types.
- **`defineChannel`** — custom ingress. Route verbs `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, and `WS` are exported from `eve/channels`.
- **`defineHook`** — stream-event subscribers under `events:`. Handlers are observe-only; they cannot inject model context.
- **`defineSchedule`** — cron schedules with either `markdown` (fire-and-forget) or `run` (imperative handler with `receive`, `waitUntil`, `appAuth`).
- **`defineState`** — durable typed context keyed by a namespaced string. Names must not start with the reserved `eve.` prefix.
- **`defineSandbox`** — sandbox backend and lifecycle. Subpath backends: `eve/sandbox/vercel`, `eve/sandbox/docker`, `eve/sandbox/just-bash`, `eve/sandbox/microsandbox`.
- **`defineInstrumentation`** — OTel setup and stream callbacks. Re-exports `isChannel` and channel metadata types (canonical home is `eve/channels`).
- **`defineEval` / `defineEvalConfig`** — eval cases and run-wide defaults. Eval identity is path-derived; authoring `id` or `name` throws.

## Runtime context (`ctx`)

`ctx` is live only inside ALS-scoped harness execution: tool `execute`, hook handlers, and channel event handlers. Calling context APIs at module top level throws.

`SessionContext` is the shared base. `ToolContext` extends it with token accessors. `HookContext` adds agent and channel metadata.

### SessionContext members

| Member | Type | Use |
| --- | --- | --- |
| `session.id` | `string` | Current session identifier |
| `session.auth` | `SessionAuth` | Caller and initiator principals |
| `session.turn` | `SessionTurn` | Active turn metadata |
| `session.parent` | `SessionParent?` | Parent lineage for subagent sessions |
| `getSandbox()` | `Promise<SandboxSession>` | Live sandbox handle; throws when unavailable |
| `getSkill(identifier)` | `SkillHandle` | Named skill visible to the current agent |

### ToolContext additions

| Member | Use |
| --- | --- |
| `getToken()` | Resolves bearer token for the tool's declared `auth`. Cache miss on interactive strategies throws `ConnectionAuthorizationRequiredError`, suspending the turn for OAuth. Throws when the tool has no `auth`. |
| `requireAuth()` | Gates execution on authorization without resolving a token first. Always throws `ConnectionAuthorizationRequiredError`. |

### HookContext additions

| Member | Use |
| --- | --- |
| `agent.name` | Current agent name |
| `agent.nodeId` | Optional node identifier |
| `channel.kind` | Channel kind discriminator |
| `channel.continuationToken` | Active continuation token when present |

Callbacks outside ALS scope (schedule `run`, sandbox `bootstrap`/`onSession`, instrumentation `setup`) receive domain-specific arguments instead of `ctx`.

## Approval predicates

Import from `eve/tools/approval`. Pass the returned function to `needsApproval`:

```ts title="agent/tools/deploy.ts"
import { defineTool } from "eve/tools";
import { once } from "eve/tools/approval";

export default defineTool({
  description: "Deploy to production.",
  inputSchema: z.object({ target: z.string() }),
  needsApproval: once(),
  async execute(input, ctx) {
    /* ... */
  },
});
```

| Helper | Behavior |
| --- | --- |
| `always()` | Require approval on every call |
| `never()` | Never require approval |
| `once()` | Require approval until the user explicitly approves once per session. Keys off bare `toolName`, not compound approval keys. Denial leaves the tool unrecorded. |

`NeedsApprovalContext` exposes `approvedTools` (a `ReadonlySet<string>`), `toolName`, and optional `toolInput` for input-aware decisions.

Custom predicates can inspect `toolInput` for per-connection scoping or other input-dependent gates.

## Built-in tool defaults

Import plain `ToolDefinition` values from `eve/tools/defaults` to spread, wrap, or patch framework tools in `agent/tools/<slug>.ts`:

| Export | Framework tool | Notes |
| --- | --- | --- |
| `bash` | Shell execution | |
| `readFile` | File reader | Read-before-write stamps reset on compaction |
| `writeFile` | File writer | Enforces read-before-write and stale-read detection |
| `glob` | Path glob search | |
| `grep` | Content regex search | |
| `webFetch` | HTTP fetch | |
| `webSearch` | Provider-managed search | Local `execute` is a throwing stub; override with `defineTool` in `agent/tools/web_search.ts` |
| `todo` | Durable todo list | Spreading preserves framework closure-bound state |
| `loadSkill` | Skill loader | Only useful when the agent declares skills |

### Framework tools without defaults exports

The harness also ships tools that are registered internally rather than through `eve/tools/defaults`:

| Tool | Registration |
| --- | --- |
| `ask_question` | Framework tool in the default harness |
| `agent` | Subagent delegation (lowered from `agent/subagents/`) |
| `connection_search` | Framework dynamic resolver (not a static default export) |

To remove a framework default, export `disableTool()` as the default from `agent/tools/<matching-slug>.ts`. To enable the experimental `Workflow` tool, re-export `ExperimentalWorkflow` from `agent/tools/workflow.ts`.

## Channel auth helpers

Route-level authentication primitives live in `eve/channels/auth`:

| Helper | Use |
| --- | --- |
| `localDev()` | Anonymous auth on loopback hosts and Vercel development |
| `vercelOidc(opts?)` | Vercel OIDC bearer verification |
| `placeholderAuth()` | Scaffold that fails closed in production |
| `httpBasic(credentials)` | HTTP Basic verification |

Lower-level verifier functions (`verifyHttpBasic`, `verifyVercelOidc`, and others) are available for custom `fetch` handlers.

## Eval entrypoints (`eve/evals`)

| Import path | Exports |
| --- | --- |
| `eve/evals` | `defineEval`, `defineEvalConfig`, eval types, `EveEvalTurnFailedError` |
| `eve/evals/expect` | `includes`, `equals`, `matches`, `similarity` assertion builders |
| `eve/evals/reporters` | `Braintrust`, `JUnit`, `EvalReporter` |
| `eve/evals/loaders` | `loadJson`, `loadYaml` |

`defineEval` accepts a `test(t)` function that drives the agent (`t.send`, `t.respond`, …) and asserts on output (`t.completed()`, `t.check(...)`, `t.judge.autoevals.*`). Each eval file is one case; default-export an array for datasets.

`defineEvalConfig` is the required default export of `evals/evals.config.ts`. It supplies optional default `judge`, `reporters`, `maxConcurrency`, and `timeoutMs`. CLI flags and per-eval values override config defaults.

## Client entrypoints (`eve/client`)

| Export | Role |
| --- | --- |
| `Client` | HTTP client bound to one host and auth config |
| `ClientSession` | One conversation; tracks continuation token and stream cursor |
| `ClientError` | Non-success HTTP responses |
| `defaultMessageReducer` | Default NDJSON stream-to-message reducer |
| `EveAgentStore` | Stateful client store for UI integrations |
| `createDataUrlFilePart`, `createTextWithFileContent` | File part helpers |
| `MessageResponse` | Turn response wrapper |
| `resolveTextToResponse`, `resolveTextToResponses` | Text-to-input-response helpers |

`ClientOptions` fields:

<ParamField body="host" type="string" required>
  Base URL of the Eve agent server.
</ParamField>

<ParamField body="auth" type="ClientAuth">
  `{ bearer: TokenValue }` or `{ basic: { username, password } }`. Resolved before every request.
</ParamField>

<ParamField body="headers" type="HeadersValue">
  Static or per-request custom headers.
</ParamField>

<ParamField body="maxReconnectAttempts" type="number" default="3">
  Stream reconnection attempts per message turn.
</ParamField>

<ParamField body="preserveCompletedSessions" type="boolean" default="false">
  Keep continuation token after `session.completed` for follow-up prompts.
</ParamField>

`Client` methods: `health()`, `info()`, `createSession()`, and authenticated `fetch()`. `ClientSession.send()` accepts a string shorthand or a `SendTurnInput` object (message, HITL responses, client context, output schema, abort signal).

The client re-exports stream event types from the protocol so consumers can type-narrow without importing internals.

## Frontend hooks and framework plugins

| Import | Exports |
| --- | --- |
| `eve/react`, `eve/vue`, `eve/svelte` | `useEveAgent`, reducer types, message types |
| `eve/next` | `withEve()` Next.js config wrapper |
| `eve/nuxt` | Nuxt module default export |
| `eve/sveltekit` | `eveSvelteKit()` Vite plugin |

`useEveAgent` wraps `Client`/`ClientSession` with framework-native state, streaming reducers, and HITL input handling.

## Imports at a glance

| Import | Holds |
| --- | --- |
| `eve` | `defineAgent`, `defineRemoteAgent`, agent types |
| `eve/tools` | `defineTool`, `defineDynamic`, `disableTool`, `ExperimentalWorkflow`, tool types, `toolResultFrom`, tool factories |
| `eve/tools/defaults` | Built-in tools as plain values |
| `eve/tools/approval` | `always`, `once`, `never`, `NeedsApprovalContext` |
| `eve/connections` | Connection define helpers, auth types, authorization errors |
| `eve/channels` | `defineChannel`, route verbs, `isChannel`, channel metadata types |
| `eve/channels/eve` | `eveChannel` |
| `eve/channels/auth` | Route auth strategy helpers and verifiers |
| `eve/channels/{slack,discord,teams,telegram,twilio,github,linear}` | Platform channel factories |
| `eve/hooks` | `defineHook`, `HookContext` |
| `eve/schedules` | `defineSchedule` |
| `eve/skills` | `defineSkill`, `defineDynamic`, `SkillHandle` |
| `eve/instructions` | `defineInstructions`, `defineDynamic` |
| `eve/context` | `defineState`, `StateHandle`, session types |
| `eve/sandbox` | `defineSandbox`, backends, sandbox types |
| `eve/instrumentation` | `defineInstrumentation`, `isChannel` |
| `eve/evals` | Eval define helpers and types |
| `eve/client` | `Client`, `ClientSession`, reducers, stream types |
| `eve/agents/auth` | `OutboundAuthFn` for remote agent auth |

Exported types ship from the same entrypoint as the helper they describe (for example `ToolDefinition` from `eve/tools`, `AgentDefinition` from `eve`).

## Related pages

<CardGroup cols={2}>
  <Card title="Configure agent.ts" href="/agent-configuration">
    `defineAgent` fields, compaction, model options, and build packaging.
  </Card>
  <Card title="Tools" href="/tools">
    `defineTool` execution, auth, approval, and dynamic resolution.
  </Card>
  <Card title="State, hooks, and session context" href="/state-hooks-and-context">
    `defineState`, `defineHook`, and where `ctx` APIs are valid.
  </Card>
  <Card title="Default harness" href="/default-harness">
    Built-in tools, compaction defaults, and override patterns.
  </Card>
  <Card title="Instrumentation and evals" href="/instrumentation-and-evals">
    `defineEval`, judges, assertions, and reporters.
  </Card>
  <Card title="Client integration" href="/client-integration">
    `Client`, `ClientSession`, `useEveAgent`, and framework plugins.
  </Card>
</CardGroup>