eve 0.90.0 → 0.91.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +34 -23
- package/dist/src/channel/auth/http-basic.js +1 -1
- package/dist/src/channel/channel-operations.d.ts +1 -1
- package/dist/src/channel/types.d.ts +2 -0
- package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
- package/dist/src/client/session.d.ts +1 -1
- package/dist/src/compiled/.vendor-stamp.json +1 -1
- package/dist/src/execution/dynamic-workflow/tool.js +1 -1
- package/dist/src/execution/proxied-deliver-step.js +1 -1
- package/dist/src/execution/sandbox/bash.js +2 -2
- package/dist/src/execution/session/active-turn.js +1 -1
- package/dist/src/execution/session/admission.d.ts +6 -0
- package/dist/src/execution/session/admission.js +1 -1
- package/dist/src/execution/session/delivery-facts.js +1 -1
- package/dist/src/execution/session/next-input.d.ts +2 -2
- package/dist/src/execution/session/next-input.js +1 -1
- package/dist/src/execution/session/program.js +1 -1
- package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
- package/dist/src/execution/session-inbox/inbox.js +1 -1
- package/dist/src/execution/session-inbox/protocol.js +1 -1
- package/dist/src/execution/tools/agent-router-workflow.js +1 -1
- package/dist/src/harness/compaction/engine.js +2 -2
- package/dist/src/harness/current-messages.js +1 -1
- package/dist/src/harness/emission.d.ts +3 -0
- package/dist/src/harness/emission.js +1 -1
- package/dist/src/harness/facts.d.ts +5 -2
- package/dist/src/harness/facts.js +1 -1
- package/dist/src/harness/model-call/call.d.ts +7 -1
- package/dist/src/harness/model-call/call.js +3 -1
- package/dist/src/harness/provider-tool-history.d.ts +8 -0
- package/dist/src/harness/provider-tool-history.js +1 -1
- package/dist/src/harness/session-machine/transitions.d.ts +3 -2
- package/dist/src/harness/step/after-model.js +1 -1
- package/dist/src/harness/step/context.js +1 -1
- package/dist/src/harness/step/intake.js +1 -1
- package/dist/src/harness/step/prompt.js +1 -1
- package/dist/src/harness/tool-history-repair.d.ts +2 -0
- package/dist/src/harness/tool-history-repair.js +1 -1
- package/dist/src/harness/tool-loop.js +1 -1
- package/dist/src/internal/application/stamped-package-version.js +1 -1
- package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
- package/dist/src/protocol/session-events/families/delivery.js +1 -1
- package/dist/src/protocol/session-projection/fold.js +1 -1
- package/dist/src/public/channels/discord/hitl.js +1 -1
- package/dist/src/public/channels/slack/hitl.d.ts +2 -1
- package/dist/src/public/channels/slack/hitl.js +3 -3
- package/dist/src/public/channels/slack/interaction-cards.js +1 -1
- package/dist/src/public/channels/slack/request-card-render.js +1 -1
- package/dist/src/public/channels/teams/hitl.js +1 -1
- package/dist/src/public/channels/teams/verify.js +1 -1
- package/dist/src/public/definitions/hook.d.ts +90 -7
- package/dist/src/public/definitions/hook.js +1 -1
- package/dist/src/public/hooks/index.d.ts +3 -2
- package/dist/src/reactions/continuation.d.ts +19 -0
- package/dist/src/reactions/continuation.js +1 -0
- package/dist/src/reactions/intents.d.ts +10 -4
- package/dist/src/reactions/intents.js +1 -1
- package/dist/src/reactions/kinds/hook.js +1 -1
- package/dist/src/reactions/runner.js +1 -1
- package/dist/src/reactions/state.d.ts +15 -2
- package/dist/src/reactions/state.js +1 -1
- package/dist/src/runtime/resolve-connection.js +1 -1
- package/dist/src/runtime/subagents/workflow.js +1 -1
- package/dist/src/setup/primitives/open-url.js +1 -1
- package/dist/src/setup/scaffold/create/project.js +1 -1
- package/dist/src/shared/value-delta.d.ts +5 -4
- package/dist/src/shared/value-delta.js +1 -1
- package/dist/src/tools/provided/ask-question-workflow.js +1 -1
- package/dist/src/tools/provided/sleep-workflow.js +1 -1
- package/dist/src/tools/provided/web-fetch.js +1 -1
- package/docs/agent-config.md +199 -222
- package/docs/channels/chat-sdk.mdx +60 -64
- package/docs/channels/custom.mdx +264 -281
- package/docs/channels/discord.mdx +176 -123
- package/docs/channels/eve.mdx +136 -206
- package/docs/channels/github.mdx +24 -22
- package/docs/channels/linear.mdx +30 -30
- package/docs/channels/linq.mdx +25 -13
- package/docs/channels/mcp.mdx +154 -116
- package/docs/channels/overview.mdx +31 -32
- package/docs/channels/photon.mdx +32 -56
- package/docs/channels/slack.mdx +538 -375
- package/docs/channels/teams.mdx +40 -26
- package/docs/channels/telegram.mdx +13 -13
- package/docs/channels/twilio.mdx +11 -11
- package/docs/code-extension.mdx +40 -42
- package/docs/concepts/built-in-tools.md +89 -57
- package/docs/concepts/context-control.md +20 -20
- package/docs/concepts/default-harness.md +20 -36
- package/docs/concepts/execution-model-and-durability.mdx +96 -160
- package/docs/concepts/project-structure.mdx +21 -14
- package/docs/concepts/security-model.md +27 -27
- package/docs/concepts/sessions-runs-and-streaming.md +184 -198
- package/docs/concepts/state.md +7 -15
- package/docs/connections/mcp.mdx +109 -93
- package/docs/connections/openapi.mdx +57 -59
- package/docs/connections/overview.mdx +175 -170
- package/docs/evals/assertions.mdx +36 -29
- package/docs/evals/cases.mdx +38 -42
- package/docs/evals/judge.mdx +21 -29
- package/docs/evals/overview.mdx +42 -38
- package/docs/evals/reporters.mdx +54 -27
- package/docs/evals/running.mdx +15 -8
- package/docs/evals/targets.mdx +16 -19
- package/docs/evals/tool-stubs.mdx +111 -97
- package/docs/experimental/dynamic-schedules.mdx +118 -63
- package/docs/extensions.md +58 -65
- package/docs/getting-started.mdx +4 -6
- package/docs/guides/auth-and-route-protection.md +87 -70
- package/docs/guides/client/continuations.mdx +23 -26
- package/docs/guides/client/messages.mdx +47 -66
- package/docs/guides/client/output-schema.mdx +8 -8
- package/docs/guides/client/overview.mdx +45 -43
- package/docs/guides/client/streaming.mdx +62 -71
- package/docs/guides/decide.md +24 -79
- package/docs/guides/deployment/meta.json +1 -1
- package/docs/guides/deployment/overview.md +27 -18
- package/docs/guides/deployment/self-hosted-operations.md +99 -0
- package/docs/guides/deployment/self-hosting.md +63 -80
- package/docs/guides/deployment/vercel.mdx +31 -27
- package/docs/guides/deployment/workflow-worlds.md +100 -0
- package/docs/guides/dev-tui.md +48 -41
- package/docs/guides/dynamic-capabilities.md +49 -50
- package/docs/guides/frontend/nextjs.mdx +2 -2
- package/docs/guides/frontend/nuxt.mdx +11 -11
- package/docs/guides/frontend/overview.mdx +1 -1
- package/docs/guides/frontend/sveltekit.mdx +11 -11
- package/docs/guides/frontend/tanstack.mdx +16 -16
- package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
- package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
- package/docs/guides/frontend/use-eve-agent.mdx +25 -25
- package/docs/guides/hooks.md +152 -106
- package/docs/guides/instrumentation/agent-runs.mdx +26 -30
- package/docs/guides/instrumentation/instrumentation.mdx +49 -76
- package/docs/guides/instrumentation/meta.json +1 -1
- package/docs/guides/instrumentation/otel.mdx +113 -179
- package/docs/guides/remote-agents.md +125 -187
- package/docs/guides/self-modification.md +18 -18
- package/docs/guides/session-context.md +16 -16
- package/docs/install-integrations.mdx +26 -24
- package/docs/instructions.mdx +37 -42
- package/docs/memory/custom-provider.md +35 -41
- package/docs/memory/file.md +93 -76
- package/docs/memory/overview.mdx +145 -156
- package/docs/patterns/durable-cross-channel-notifications.md +15 -19
- package/docs/patterns/dynamic-scheduling.md +19 -23
- package/docs/patterns/multi-tenant-approvals.md +17 -22
- package/docs/patterns/multi-tenant-auth.md +43 -42
- package/docs/patterns/multi-tenant-memory.md +39 -36
- package/docs/patterns/voice-notes.md +3 -3
- package/docs/protocols/acp.md +13 -13
- package/docs/protocols/ucp.mdx +7 -7
- package/docs/reference/agent-files.md +6 -6
- package/docs/reference/cli.md +99 -98
- package/docs/reference/telemetry.md +1 -1
- package/docs/reference/typescript-api.md +52 -53
- package/docs/responsible-use.md +2 -2
- package/docs/sandbox/custom-providers.mdx +60 -56
- package/docs/sandbox/default.mdx +23 -24
- package/docs/sandbox/docker.mdx +16 -10
- package/docs/sandbox/index.mdx +93 -61
- package/docs/sandbox/just-bash.mdx +17 -11
- package/docs/sandbox/troubleshooting.mdx +29 -23
- package/docs/sandbox/vercel.mdx +45 -52
- package/docs/schedules.mdx +65 -54
- package/docs/skills.mdx +74 -49
- package/docs/subagents/index.mdx +97 -136
- package/docs/tools/human-in-the-loop.md +160 -90
- package/docs/tools/meta.json +1 -1
- package/docs/tools/overview.mdx +229 -237
- package/docs/tools/tasks.md +118 -117
- package/docs/tools/workflows.mdx +447 -543
- package/docs/tutorial/connect-a-warehouse.mdx +11 -13
- package/docs/tutorial/first-agent.mdx +14 -16
- package/docs/tutorial/guard-the-spend.mdx +6 -8
- package/docs/tutorial/how-it-runs.mdx +8 -8
- package/docs/tutorial/query-sample-data.mdx +8 -8
- package/docs/tutorial/remember-definitions.mdx +4 -4
- package/docs/tutorial/run-analysis.mdx +20 -22
- package/docs/tutorial/ship-it.mdx +19 -19
- package/docs/tutorial/team-playbooks.mdx +9 -9
- package/docs/use-cases.mdx +13 -11
- package/package.json +1 -1
- package/docs/guides/instrumentation/migration.md +0 -96
- package/docs/tools/tasks-upgrade.md +0 -218
package/docs/extensions.md
CHANGED
|
@@ -3,11 +3,9 @@ title: "Extensions"
|
|
|
3
3
|
description: "Package reusable eve capabilities and mount them from npm or a monorepo workspace."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
An extension is a package of eve tools, channels, connections, skills, schedules, subagents, instruction fragments, and hooks. An agent installs the package as a dependency and mounts it with a file under `agent/extensions/`. Use an extension to share the same tools and skills across agents, from npm or from a monorepo workspace.
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
This enables sharing many different capability sets. A browser extension might include several tools for navigating a site. A self-improving extension could pair hooks with dynamic instructions.
|
|
8
|
+
To add a ready-made extension with `eve add`, see [Add Integrations](./install-integrations).
|
|
11
9
|
|
|
12
10
|
## Author: create an extension
|
|
13
11
|
|
|
@@ -19,9 +17,7 @@ Start with the extension scaffold:
|
|
|
19
17
|
npx eve@latest extension init my-crm
|
|
20
18
|
```
|
|
21
19
|
|
|
22
|
-
The command creates the package
|
|
23
|
-
|
|
24
|
-
An extension uses the same file conventions as an agent for its contributions:
|
|
20
|
+
The command creates the package with `extension/extension.ts`, TypeScript configuration, and build and publish metadata. It also installs dependencies and initializes Git. Files under `extension/` follow the same layout as an agent:
|
|
25
21
|
|
|
26
22
|
```
|
|
27
23
|
@acme/crm/
|
|
@@ -39,19 +35,19 @@ An extension uses the same file conventions as an agent for its contributions:
|
|
|
39
35
|
lib/http.ts
|
|
40
36
|
```
|
|
41
37
|
|
|
42
|
-
Each
|
|
38
|
+
Each directory accepts the same static and dynamic forms as in an agent. For example, `extension/instructions.ts` works like `extension/instructions.md`, and `extension/connections/` can contain `defineDynamic(...)`. Keep shared code in `extension/lib/`.
|
|
43
39
|
|
|
44
|
-
Names come from paths, so call the tool `search`, not `crm_search
|
|
40
|
+
Names come from paths, so call the tool `search`, not `crm_search`. The agent's mount adds a prefix such as `crm__`; see [Mount it](#mount-it).
|
|
45
41
|
|
|
46
|
-
The extension root
|
|
47
|
-
[memory](./memory), a sandbox, or nested extensions
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
42
|
+
The extension root can't declare agent configuration, instrumentation,
|
|
43
|
+
[memory](./memory), a sandbox, or nested extensions, because the agent that
|
|
44
|
+
mounts the extension decides those. A subagent under `extension/subagents/` has
|
|
45
|
+
its own agent configuration, memory, and sandbox like any other
|
|
46
|
+
[declared subagent](./subagents).
|
|
51
47
|
|
|
52
48
|
### Add configuration and contributions
|
|
53
49
|
|
|
54
|
-
|
|
50
|
+
`extension/extension.ts` default-exports a `defineExtension` handle. Give it a [Standard Schema](https://standardschema.dev) when the agent that mounts it provides settings:
|
|
55
51
|
|
|
56
52
|
```ts title="extension/extension.ts"
|
|
57
53
|
import { defineExtension } from "eve/extension";
|
|
@@ -65,7 +61,7 @@ export default defineExtension({
|
|
|
65
61
|
});
|
|
66
62
|
```
|
|
67
63
|
|
|
68
|
-
|
|
64
|
+
Any file in the extension, including a schedule handler, can import that handle to read the validated configuration, with defaults applied:
|
|
69
65
|
|
|
70
66
|
```ts title="extension/tools/search.ts"
|
|
71
67
|
import { defineTool } from "eve/tools";
|
|
@@ -83,17 +79,15 @@ export default defineTool({
|
|
|
83
79
|
});
|
|
84
80
|
```
|
|
85
81
|
|
|
86
|
-
If no configuration is needed, export `defineExtension()` and let
|
|
82
|
+
If no configuration is needed, export `defineExtension()` and let agents re-export it directly. Config schemas must validate synchronously.
|
|
87
83
|
|
|
88
|
-
`defineState`
|
|
84
|
+
`defineState` keys belong to the mount path and state name, so two mounts of the same package don't share state; see [Mount it](#mount-it).
|
|
89
85
|
|
|
90
86
|
### Add a subagent
|
|
91
87
|
|
|
92
|
-
Author a subagent under `extension/subagents/<id>/`
|
|
93
|
-
|
|
94
|
-
Modules inside the contributed subagent can import the extension handle. For example, a tool under `extension/subagents/reviewer/tools/` can read the configuration bound by the consumer's `agent/extensions/crm.ts` mount.
|
|
88
|
+
Author a subagent under `extension/subagents/<id>/` with the same files as an agent's [declared subagent](./subagents). Mounting the extension as `crm` exposes `extension/subagents/reviewer/` as `crm__reviewer`. The subagent's own tools, connections, skills, hooks, instructions, sandbox, and nested subagents stay inside it and keep their path-derived names. The subagent uses the extension's mount path for its state keys, but keeps its own state.
|
|
95
89
|
|
|
96
|
-
A
|
|
90
|
+
Files inside the subagent can import the extension handle. A tool under `extension/subagents/reviewer/tools/` reads the configuration from the agent's `agent/extensions/crm.ts` mount. The subagent can also mount another extension under `extension/subagents/<id>/extensions/`, with configuration taken from its own extension's configuration:
|
|
97
91
|
|
|
98
92
|
```ts
|
|
99
93
|
// extension/subagents/reviewer/extensions/search.ts
|
|
@@ -162,23 +156,26 @@ Build the package with `eve extension build`:
|
|
|
162
156
|
eve extension build
|
|
163
157
|
```
|
|
164
158
|
|
|
165
|
-
`eve extension build` writes an agent-shaped `dist/extension` tree
|
|
159
|
+
`eve extension build` writes an agent-shaped `dist/extension` tree with skill assets, type declarations, and the eve version that built it. It also manages the package exports for the mount factory (`@acme/crm`) and tool definitions (`@acme/crm/tools`). Publish `dist/`; agents don't need the TypeScript source.
|
|
166
160
|
|
|
167
|
-
|
|
161
|
+
| Package entry | What to put there |
|
|
162
|
+
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
163
|
+
| `devDependencies.eve` | An exact version, which pins the authoring API and build tools |
|
|
164
|
+
| `peerDependencies.eve` | `*`, so the agent provides eve at runtime. eve checks the build's recorded version, not this range. |
|
|
165
|
+
| `dependencies` | Runtime packages such as `zod` or an SDK. Most are bundled into the agent. Don't add eve here. |
|
|
166
|
+
| `eve.extension.externalDependencies` | Packages that must keep a normal Node.js package layout at runtime, such as a native addon or an SDK that loads package-relative assets |
|
|
168
167
|
|
|
169
|
-
|
|
168
|
+
Each package in `externalDependencies` must also appear in `dependencies`, `optionalDependencies`, or `peerDependencies`. The agent keeps it external with its complete package tree. The agent author doesn't edit `agent.ts` or install the package directly.
|
|
170
169
|
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
Consumers can now add the built package to an agent. A workspace-only extension uses the same package contract but does not need to be published; see [Use an extension in a workspace](#use-an-extension-in-a-workspace).
|
|
170
|
+
A workspace-only extension uses the same package contract without publishing; see [Use an extension in a workspace](#use-an-extension-in-a-workspace).
|
|
174
171
|
|
|
175
172
|
## Consumer: install and mount an extension
|
|
176
173
|
|
|
177
|
-
A mount gives the extension's
|
|
174
|
+
A mount gives the extension's tools, channels, and other files a name prefix in your agent. eve copies nothing into your agent, so updating the package updates the mounted extension.
|
|
178
175
|
|
|
179
176
|
### Install the package
|
|
180
177
|
|
|
181
|
-
Install the extension with the
|
|
178
|
+
Install the extension with the agent project's package manager, for example pnpm:
|
|
182
179
|
|
|
183
180
|
```bash
|
|
184
181
|
pnpm add @acme/crm
|
|
@@ -194,11 +191,11 @@ import crm from "@acme/crm";
|
|
|
194
191
|
export default crm({ apiKey: process.env.CRM_API_KEY! });
|
|
195
192
|
```
|
|
196
193
|
|
|
197
|
-
Set `CRM_API_KEY` in the
|
|
194
|
+
Set `CRM_API_KEY` in the agent's environment, such as `.env.local` for local development.
|
|
198
195
|
|
|
199
|
-
The mount adds `crm__` to
|
|
196
|
+
The mount adds `crm__` to each name: `tools/search.ts` becomes `crm__search`, `channels/webhook.ts` becomes `crm__webhook`, `schedules/sync.ts` becomes `crm__sync`, `connections/api.ts` becomes `crm__api`, and `subagents/reviewer/` becomes `crm__reviewer`. Channels keep their route paths, and schedules keep their cron expressions.
|
|
200
197
|
|
|
201
|
-
|
|
198
|
+
Don't name a mount after one of the agent's connections. A [connection reserves](/docs/connections) every name that starts with `<name>__`, so the compiler rejects the mounted tools and subagents. The name `eve` is reserved for [built-in tools](/docs/concepts/built-in-tools#eve__search-eve__tool-and-eve__skill).
|
|
202
199
|
|
|
203
200
|
For an extension with no configuration, mount its default export directly:
|
|
204
201
|
|
|
@@ -206,25 +203,13 @@ For an extension with no configuration, mount its default export directly:
|
|
|
206
203
|
export { default } from "@acme/gizmo";
|
|
207
204
|
```
|
|
208
205
|
|
|
209
|
-
The same mount shape works with an npm package, a workspace dependency, or a linked local package. Each mount binds its own configuration, even when two mounts use the same package.
|
|
210
|
-
|
|
211
|
-
Extension state belongs to the logical mount path (for example, `extensions/crm` or `subagents/research/extensions/crm`). A flat `crm.ts` mount and a directory `crm/extension.ts` mount have the same identity; moving or renaming the mount changes its state keys. Application-defined state keys are unchanged.
|
|
212
|
-
|
|
213
|
-
### Upgrade from package-scoped extension state
|
|
206
|
+
The same mount shape works with an npm package, a workspace dependency, or a linked local package. Each mount binds its own configuration, even when two mounts use the same package.
|
|
214
207
|
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
- The value moves when exactly one mount of that package defines that state name.
|
|
218
|
-
- When no mount of that package defines that state name, for example because the extension removed it or the package was renamed, eve drops the value. The target deployment's runtime logs show a `dropping unknown context key during deserialization` warning with the key.
|
|
219
|
-
- When two or more mounts use the package and define that state name, eve cannot tell which mount owns the value, so the handoff is rejected and the session stays on its current deployment. Keep that deployment available until the session finishes, or start a new session on the deployment you want to use.
|
|
220
|
-
- Older deployments cannot read sessions saved by a newer release, so a session that already moved does not hand back after a rollback.
|
|
221
|
-
- Local context snapshots follow the same rules.
|
|
208
|
+
Extension state belongs to the mount path, such as `extensions/crm` or `subagents/research/extensions/crm`. A flat `crm.ts` mount and a directory `crm/extension.ts` mount share a path. Moving or renaming a mount creates a new instance with new state keys. The agent's own state keys don't change.
|
|
222
209
|
|
|
223
210
|
### Use an extension in a workspace
|
|
224
211
|
|
|
225
|
-
A workspace extension is a regular extension package
|
|
226
|
-
|
|
227
|
-
For example, a pnpm workspace can keep one extension next to two independently deployable agents:
|
|
212
|
+
A workspace extension is a regular extension package in the same monorepo as the agents that use it. Use one when several agents need the same tools and skills, or when private tools should change together with their agents. For example, a pnpm workspace can keep one extension next to two independently deployable agents:
|
|
228
213
|
|
|
229
214
|
```text
|
|
230
215
|
acme-agents/
|
|
@@ -254,14 +239,14 @@ packages:
|
|
|
254
239
|
- "packages/*"
|
|
255
240
|
```
|
|
256
241
|
|
|
257
|
-
|
|
242
|
+
Scaffold the extension from a directory the workspace configuration covers:
|
|
258
243
|
|
|
259
244
|
```bash
|
|
260
245
|
cd packages
|
|
261
246
|
npx eve@latest extension init shared-capabilities
|
|
262
247
|
```
|
|
263
248
|
|
|
264
|
-
Give the generated package the name
|
|
249
|
+
Give the generated package the name agents will import. Add `"private": true` if it should never be published:
|
|
265
250
|
|
|
266
251
|
```jsonc title="packages/shared-capabilities/package.json"
|
|
267
252
|
{
|
|
@@ -276,7 +261,7 @@ Give the generated package the name consumers will import. Add `"private": true`
|
|
|
276
261
|
}
|
|
277
262
|
```
|
|
278
263
|
|
|
279
|
-
Each
|
|
264
|
+
Each agent declares its own workspace dependency:
|
|
280
265
|
|
|
281
266
|
```jsonc title="agents/support/package.json"
|
|
282
267
|
{
|
|
@@ -292,19 +277,17 @@ Then each agent mounts the package:
|
|
|
292
277
|
export { default } from "@acme/shared-capabilities";
|
|
293
278
|
```
|
|
294
279
|
|
|
295
|
-
|
|
280
|
+
Each agent chooses its own mount name and configuration. For example, `shared.ts` contributes `shared__search`, while mounting the same package as `company.ts` in another agent contributes `company__search`.
|
|
296
281
|
|
|
297
282
|
#### Develop from source
|
|
298
283
|
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
Production builds build the same extensions from source. `eve build` builds each mounted, source-backed workspace extension before it compiles the agent, and `withEve` does the same for its agents during `next build`. Production builds therefore do not depend on the extension package's `prepare` script, which package managers skip for no-op installs and with `--ignore-scripts`. eve skips an extension whose distribution was built by the same eve version and is newer than the extension's source, `package.json`, and TypeScript configuration.
|
|
284
|
+
`eve dev` builds mounted workspace extensions from source before it compiles the agent. It watches each extension's source, `package.json`, and TypeScript configuration, and rebuilds only the extension you changed. If an edit fails to build, the last successful build keeps running.
|
|
302
285
|
|
|
303
|
-
|
|
286
|
+
`eve build`, and `withEve` during `next build`, also build these extensions from source first, and skip an extension that is already up to date. Production builds don't need the package's `prepare` script, which package managers skip for no-op installs and with `--ignore-scripts`.
|
|
304
287
|
|
|
305
288
|
### Override a contribution
|
|
306
289
|
|
|
307
|
-
Use a directory mount to keep overrides beside the mount declaration
|
|
290
|
+
Use a directory mount to keep overrides beside the mount declaration in `extension.ts`:
|
|
308
291
|
|
|
309
292
|
```
|
|
310
293
|
agent/extensions/crm/
|
|
@@ -318,7 +301,7 @@ import crm from "@acme/crm";
|
|
|
318
301
|
export default crm({ apiKey: process.env.CRM_API_KEY! });
|
|
319
302
|
```
|
|
320
303
|
|
|
321
|
-
A
|
|
304
|
+
A channel, tool, connection, skill, schedule, or subagent in your mount directory with the same name replaces the extension's. To adjust an extension tool, import it from the package's `./tools` export and define it again:
|
|
322
305
|
|
|
323
306
|
```ts title="agent/extensions/crm/tools/search.ts"
|
|
324
307
|
import { search } from "@acme/crm/tools";
|
|
@@ -336,9 +319,9 @@ import { disableTool } from "eve/tools";
|
|
|
336
319
|
export default disableTool();
|
|
337
320
|
```
|
|
338
321
|
|
|
339
|
-
Hooks and instruction fragments
|
|
322
|
+
Hooks and instruction fragments add to the agent's own, so you can't replace them. A dynamic tool wins over a static tool with the same name, so replace a dynamic tool with a dynamic definition in the same file. `disableTool()` removes either kind.
|
|
340
323
|
|
|
341
|
-
You can also
|
|
324
|
+
You can also override from the agent root with the prefixed name. `agent/tools/crm__search.ts` replaces the extension's `tools/search.ts`, and wins over a directory-mount override.
|
|
342
325
|
|
|
343
326
|
### Computer-use overrides
|
|
344
327
|
|
|
@@ -354,7 +337,7 @@ the managed display and driver after opening each session sandbox.
|
|
|
354
337
|
|
|
355
338
|
### Use an extension tool result in a hook
|
|
356
339
|
|
|
357
|
-
To
|
|
340
|
+
To keep an extension tool's result type in your hook, import its definition from `./tools` and pass it to [`toolResultFrom`](/docs/guides/hooks#narrowing-tool-results):
|
|
358
341
|
|
|
359
342
|
```ts title="agent/hooks/narrow-crm.ts"
|
|
360
343
|
import { defineHook } from "eve/hooks";
|
|
@@ -372,17 +355,27 @@ export default defineHook({
|
|
|
372
355
|
});
|
|
373
356
|
```
|
|
374
357
|
|
|
375
|
-
`toolResultFrom`
|
|
358
|
+
`toolResultFrom` matches the mounted `crm__search` result by its original definition, not by the prefixed name. Extension authors should give each tool definition a distinct description so eve can tell the tools apart. Re-exporting the same definition, such as from a subagent's `tools/` directory, doesn't conflict.
|
|
376
359
|
|
|
377
360
|
### Bundled development extensions
|
|
378
361
|
|
|
379
|
-
Local `eve dev`
|
|
362
|
+
Local `eve dev` mounts the bundled self-modification extension by default, without a file under `agent/extensions/`. Production builds don't include it. See [Self-Modification](./guides/self-modification).
|
|
380
363
|
|
|
381
364
|
### Compatibility
|
|
382
365
|
|
|
383
|
-
|
|
366
|
+
eve checks the eve version that built an extension before it loads the extension's code. A built extension needs that eve release or a later one. Build with the oldest release you want to support, and test with newer agents. An agent can't rebuild an installed extension that ships without source.
|
|
367
|
+
|
|
368
|
+
Sessions saved by eve 0.68 or earlier store extension state per package, not per mount. When such a session moves to a newer deployment, eve gives each value to the one mount that defines it. It drops values that no mount defines.
|
|
369
|
+
|
|
370
|
+
### Troubleshooting
|
|
384
371
|
|
|
385
|
-
|
|
372
|
+
| What you see | What to do |
|
|
373
|
+
| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
374
|
+
| `Extension "<package>" was built with eve <version>.` | Upgrade eve to that version or later, or install an extension built with your eve version. |
|
|
375
|
+
| `Extension "<package>" requires distribution contract <n>, which this eve does not support.` | Rebuild the extension with your eve version, or install a compatible extension release. |
|
|
376
|
+
| `Extension "<package>" has no valid compatibility manifest` | Rebuild or reinstall the extension. |
|
|
377
|
+
| The agent build stops with an error that names an extension package and its directory | Fix the reported error, or run `eve extension build` in that package directory to build it on its own. |
|
|
378
|
+
| `Incompatible context state layout for key "<key>".` | Continue the session on its original deployment, or start a new session. The session stays on its deployment because two or more mounts of one package define that state, so eve can't pick an owner. |
|
|
386
379
|
|
|
387
380
|
## What to read next
|
|
388
381
|
|
package/docs/getting-started.mdx
CHANGED
|
@@ -18,9 +18,7 @@ Choose a model, provider, and channel that meet your data-processing and complia
|
|
|
18
18
|
|
|
19
19
|
## Create a project
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
Run `eve init` with a project name:
|
|
21
|
+
Run `eve init` with a project name to create a project with one agent in `agent/`:
|
|
24
22
|
|
|
25
23
|
```bash
|
|
26
24
|
npx eve@latest init my-agent
|
|
@@ -28,9 +26,9 @@ npx eve@latest init my-agent
|
|
|
28
26
|
|
|
29
27
|
The command creates the project, installs dependencies, initializes Git, and opens the terminal UI. eve reuses an available model connection or opens `/login`. Once connected, type your first message. Channel and integration setup is optional; use `/add` when you need it.
|
|
30
28
|
|
|
31
|
-
In `/add`, search by name or
|
|
29
|
+
In `/add`, search by name or by what an item does, such as `iMessage` or `SMS`. Select an item to install it and complete its setup.
|
|
32
30
|
|
|
33
|
-
During startup, the status line shows what eve is waiting for. If you choose a Vercel account, finish signing in in your browser and select a team when prompted. eve checks that team's AI Gateway access
|
|
31
|
+
During startup, the status line shows what eve is waiting for. If you choose a Vercel account, finish signing in in your browser and select a team when prompted. eve checks that team's AI Gateway access before returning to the composer. Changing the account, team, or key needs no rebuild or restart.
|
|
34
32
|
|
|
35
33
|
To add eve to a project that already has a `package.json`, run this command from its root before you create any `agent/` files:
|
|
36
34
|
|
|
@@ -105,4 +103,4 @@ After the tutorial, continue with the task you need:
|
|
|
105
103
|
| Test agent behavior | [Evals](/docs/evals/overview) |
|
|
106
104
|
| Secure and deploy the agent | [Authentication](/docs/guides/auth-and-route-protection), then [Deployment](/docs/guides/deployment/overview) |
|
|
107
105
|
|
|
108
|
-
Read [Execution Model and Durability](/docs/concepts/execution-model-and-durability)
|
|
106
|
+
Read [Execution Model and Durability](/docs/concepts/execution-model-and-durability) to learn how sessions, turns, and steps run, and how waiting work survives restarts.
|