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.
Files changed (185) hide show
  1. package/CHANGELOG.md +34 -23
  2. package/dist/src/channel/auth/http-basic.js +1 -1
  3. package/dist/src/channel/channel-operations.d.ts +1 -1
  4. package/dist/src/channel/types.d.ts +2 -0
  5. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  6. package/dist/src/client/session.d.ts +1 -1
  7. package/dist/src/compiled/.vendor-stamp.json +1 -1
  8. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  9. package/dist/src/execution/proxied-deliver-step.js +1 -1
  10. package/dist/src/execution/sandbox/bash.js +2 -2
  11. package/dist/src/execution/session/active-turn.js +1 -1
  12. package/dist/src/execution/session/admission.d.ts +6 -0
  13. package/dist/src/execution/session/admission.js +1 -1
  14. package/dist/src/execution/session/delivery-facts.js +1 -1
  15. package/dist/src/execution/session/next-input.d.ts +2 -2
  16. package/dist/src/execution/session/next-input.js +1 -1
  17. package/dist/src/execution/session/program.js +1 -1
  18. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  19. package/dist/src/execution/session-inbox/inbox.js +1 -1
  20. package/dist/src/execution/session-inbox/protocol.js +1 -1
  21. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  22. package/dist/src/harness/compaction/engine.js +2 -2
  23. package/dist/src/harness/current-messages.js +1 -1
  24. package/dist/src/harness/emission.d.ts +3 -0
  25. package/dist/src/harness/emission.js +1 -1
  26. package/dist/src/harness/facts.d.ts +5 -2
  27. package/dist/src/harness/facts.js +1 -1
  28. package/dist/src/harness/model-call/call.d.ts +7 -1
  29. package/dist/src/harness/model-call/call.js +3 -1
  30. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  31. package/dist/src/harness/provider-tool-history.js +1 -1
  32. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  33. package/dist/src/harness/step/after-model.js +1 -1
  34. package/dist/src/harness/step/context.js +1 -1
  35. package/dist/src/harness/step/intake.js +1 -1
  36. package/dist/src/harness/step/prompt.js +1 -1
  37. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  38. package/dist/src/harness/tool-history-repair.js +1 -1
  39. package/dist/src/harness/tool-loop.js +1 -1
  40. package/dist/src/internal/application/stamped-package-version.js +1 -1
  41. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  42. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  43. package/dist/src/protocol/session-projection/fold.js +1 -1
  44. package/dist/src/public/channels/discord/hitl.js +1 -1
  45. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  46. package/dist/src/public/channels/slack/hitl.js +3 -3
  47. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  48. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  49. package/dist/src/public/channels/teams/hitl.js +1 -1
  50. package/dist/src/public/channels/teams/verify.js +1 -1
  51. package/dist/src/public/definitions/hook.d.ts +90 -7
  52. package/dist/src/public/definitions/hook.js +1 -1
  53. package/dist/src/public/hooks/index.d.ts +3 -2
  54. package/dist/src/reactions/continuation.d.ts +19 -0
  55. package/dist/src/reactions/continuation.js +1 -0
  56. package/dist/src/reactions/intents.d.ts +10 -4
  57. package/dist/src/reactions/intents.js +1 -1
  58. package/dist/src/reactions/kinds/hook.js +1 -1
  59. package/dist/src/reactions/runner.js +1 -1
  60. package/dist/src/reactions/state.d.ts +15 -2
  61. package/dist/src/reactions/state.js +1 -1
  62. package/dist/src/runtime/resolve-connection.js +1 -1
  63. package/dist/src/runtime/subagents/workflow.js +1 -1
  64. package/dist/src/setup/primitives/open-url.js +1 -1
  65. package/dist/src/setup/scaffold/create/project.js +1 -1
  66. package/dist/src/shared/value-delta.d.ts +5 -4
  67. package/dist/src/shared/value-delta.js +1 -1
  68. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  69. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  70. package/dist/src/tools/provided/web-fetch.js +1 -1
  71. package/docs/agent-config.md +199 -222
  72. package/docs/channels/chat-sdk.mdx +60 -64
  73. package/docs/channels/custom.mdx +264 -281
  74. package/docs/channels/discord.mdx +176 -123
  75. package/docs/channels/eve.mdx +136 -206
  76. package/docs/channels/github.mdx +24 -22
  77. package/docs/channels/linear.mdx +30 -30
  78. package/docs/channels/linq.mdx +25 -13
  79. package/docs/channels/mcp.mdx +154 -116
  80. package/docs/channels/overview.mdx +31 -32
  81. package/docs/channels/photon.mdx +32 -56
  82. package/docs/channels/slack.mdx +538 -375
  83. package/docs/channels/teams.mdx +40 -26
  84. package/docs/channels/telegram.mdx +13 -13
  85. package/docs/channels/twilio.mdx +11 -11
  86. package/docs/code-extension.mdx +40 -42
  87. package/docs/concepts/built-in-tools.md +89 -57
  88. package/docs/concepts/context-control.md +20 -20
  89. package/docs/concepts/default-harness.md +20 -36
  90. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  91. package/docs/concepts/project-structure.mdx +21 -14
  92. package/docs/concepts/security-model.md +27 -27
  93. package/docs/concepts/sessions-runs-and-streaming.md +184 -198
  94. package/docs/concepts/state.md +7 -15
  95. package/docs/connections/mcp.mdx +109 -93
  96. package/docs/connections/openapi.mdx +57 -59
  97. package/docs/connections/overview.mdx +175 -170
  98. package/docs/evals/assertions.mdx +36 -29
  99. package/docs/evals/cases.mdx +38 -42
  100. package/docs/evals/judge.mdx +21 -29
  101. package/docs/evals/overview.mdx +42 -38
  102. package/docs/evals/reporters.mdx +54 -27
  103. package/docs/evals/running.mdx +15 -8
  104. package/docs/evals/targets.mdx +16 -19
  105. package/docs/evals/tool-stubs.mdx +111 -97
  106. package/docs/experimental/dynamic-schedules.mdx +118 -63
  107. package/docs/extensions.md +58 -65
  108. package/docs/getting-started.mdx +4 -6
  109. package/docs/guides/auth-and-route-protection.md +87 -70
  110. package/docs/guides/client/continuations.mdx +23 -26
  111. package/docs/guides/client/messages.mdx +47 -66
  112. package/docs/guides/client/output-schema.mdx +8 -8
  113. package/docs/guides/client/overview.mdx +45 -43
  114. package/docs/guides/client/streaming.mdx +62 -71
  115. package/docs/guides/decide.md +24 -79
  116. package/docs/guides/deployment/meta.json +1 -1
  117. package/docs/guides/deployment/overview.md +27 -18
  118. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  119. package/docs/guides/deployment/self-hosting.md +63 -80
  120. package/docs/guides/deployment/vercel.mdx +31 -27
  121. package/docs/guides/deployment/workflow-worlds.md +100 -0
  122. package/docs/guides/dev-tui.md +48 -41
  123. package/docs/guides/dynamic-capabilities.md +49 -50
  124. package/docs/guides/frontend/nextjs.mdx +2 -2
  125. package/docs/guides/frontend/nuxt.mdx +11 -11
  126. package/docs/guides/frontend/overview.mdx +1 -1
  127. package/docs/guides/frontend/sveltekit.mdx +11 -11
  128. package/docs/guides/frontend/tanstack.mdx +16 -16
  129. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  130. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  131. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  132. package/docs/guides/hooks.md +152 -106
  133. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  134. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  135. package/docs/guides/instrumentation/meta.json +1 -1
  136. package/docs/guides/instrumentation/otel.mdx +113 -179
  137. package/docs/guides/remote-agents.md +125 -187
  138. package/docs/guides/self-modification.md +18 -18
  139. package/docs/guides/session-context.md +16 -16
  140. package/docs/install-integrations.mdx +26 -24
  141. package/docs/instructions.mdx +37 -42
  142. package/docs/memory/custom-provider.md +35 -41
  143. package/docs/memory/file.md +93 -76
  144. package/docs/memory/overview.mdx +145 -156
  145. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  146. package/docs/patterns/dynamic-scheduling.md +19 -23
  147. package/docs/patterns/multi-tenant-approvals.md +17 -22
  148. package/docs/patterns/multi-tenant-auth.md +43 -42
  149. package/docs/patterns/multi-tenant-memory.md +39 -36
  150. package/docs/patterns/voice-notes.md +3 -3
  151. package/docs/protocols/acp.md +13 -13
  152. package/docs/protocols/ucp.mdx +7 -7
  153. package/docs/reference/agent-files.md +6 -6
  154. package/docs/reference/cli.md +99 -98
  155. package/docs/reference/telemetry.md +1 -1
  156. package/docs/reference/typescript-api.md +52 -53
  157. package/docs/responsible-use.md +2 -2
  158. package/docs/sandbox/custom-providers.mdx +60 -56
  159. package/docs/sandbox/default.mdx +23 -24
  160. package/docs/sandbox/docker.mdx +16 -10
  161. package/docs/sandbox/index.mdx +93 -61
  162. package/docs/sandbox/just-bash.mdx +17 -11
  163. package/docs/sandbox/troubleshooting.mdx +29 -23
  164. package/docs/sandbox/vercel.mdx +45 -52
  165. package/docs/schedules.mdx +65 -54
  166. package/docs/skills.mdx +74 -49
  167. package/docs/subagents/index.mdx +97 -136
  168. package/docs/tools/human-in-the-loop.md +160 -90
  169. package/docs/tools/meta.json +1 -1
  170. package/docs/tools/overview.mdx +229 -237
  171. package/docs/tools/tasks.md +118 -117
  172. package/docs/tools/workflows.mdx +447 -543
  173. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  174. package/docs/tutorial/first-agent.mdx +14 -16
  175. package/docs/tutorial/guard-the-spend.mdx +6 -8
  176. package/docs/tutorial/how-it-runs.mdx +8 -8
  177. package/docs/tutorial/query-sample-data.mdx +8 -8
  178. package/docs/tutorial/remember-definitions.mdx +4 -4
  179. package/docs/tutorial/run-analysis.mdx +20 -22
  180. package/docs/tutorial/ship-it.mdx +19 -19
  181. package/docs/tutorial/team-playbooks.mdx +9 -9
  182. package/docs/use-cases.mdx +13 -11
  183. package/package.json +1 -1
  184. package/docs/guides/instrumentation/migration.md +0 -96
  185. package/docs/tools/tasks-upgrade.md +0 -218
@@ -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
- Extensions package eve tools, channels, connections, skills, schedules, subagents, instruction fragments, and hooks. An author builds an extension package; each agent that uses it declares the package as a dependency and mounts it. The package can be published to a package registry or kept private inside a monorepo workspace.
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
- Ready-made extensions can also be distributed through an eve integration registry. See [Add Integrations](./install-integrations) to discover and add one with `eve add`; this page explains how extension packages are authored, mounted, configured, and overridden.
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, installs dependencies, and initializes Git. It includes `extension/extension.ts`, TypeScript configuration, and the package metadata required to build and publish.
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 listed slot accepts the same authored forms as its agent counterpart. Static and dynamic tools, connections, skills, and instructions all work in an extension: `extension/instructions.ts` is as valid as `extension/instructions.md`, and `extension/connections/` can contain `defineDynamic(...)`.
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`; the consumer's mount adds the `crm__` prefix. The same prefix applies to channel, schedule, and parent-visible subagent IDs, while channel route paths and schedule cron expressions stay unchanged. Keep shared code in `extension/lib/`.
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 cannot declare agent configuration, instrumentation,
47
- [memory](./memory), a sandbox, or nested extensions. Those agent-level concerns
48
- belong to the consuming application. A subagent contributed under
49
- `extension/subagents/` owns its own agent configuration, memory, and sandbox
50
- like any other [declared subagent](./subagents).
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
- The author's `extension/extension.ts` default-exports a `defineExtension` handle. Give it a [Standard Schema](https://standardschema.dev) when consumers need to provide settings:
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
- Contributions, including schedule handlers, can import that handle to read the validated configuration. Defaults have already been applied:
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 consumers re-export it directly. Config schemas must validate synchronously.
82
+ If no configuration is needed, export `defineExtension()` and let agents re-export it directly. Config schemas must validate synchronously.
87
83
 
88
- `defineState` uses a durable key scoped to the logical mount path and the authored state name. Two mounts of the same package can use the same state name without sharing a slot in one context. Contributed subagents use their parent extension's mount identity, but retain their own runtime contexts.
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>/` using the same files as a subagent declared by an agent. Mounting the extension as `crm` exposes `extension/subagents/reviewer/` to the consuming agent node as `crm__reviewer`. The subagent's own tools, connections, skills, hooks, instructions, sandbox, and nested subagents remain isolated inside its node and keep their path-derived names.
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 contributed subagent can mount another extension under `extension/subagents/<id>/extensions/` and derive that mount's configuration from its own extension's configuration:
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, copies skill assets, emits declarations, and records compatibility metadata. It also manages the package exports for the mount factory (`@acme/crm`) and tool definitions (`@acme/crm/tools`). Publish `dist/`; consumers do not need the author's TypeScript source.
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
- The exact `eve` development pin controls the extension authoring API and build tooling. The wildcard peer lets the consumer provide the runtime copy of eve. At consumption time, eve checks generated metadata, not the npm peer range. Do not add eve to regular `dependencies`.
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
- Put runtime packages such as `zod` or an SDK in `dependencies`. Most dependencies are bundled into the consuming agent automatically.
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
- When a package must keep normal Node.js package layout at runtime, add it to `eve.extension.externalDependencies`. Common cases include native addons and SDKs that load package-relative assets. `eve extension build` requires each listed package to also appear in `dependencies`, `optionalDependencies`, or `peerDependencies`, and records the requirement in the generated compatibility manifest. The consuming eve keeps the package external and preserves its complete package tree; consumers do not need to edit `agent.ts` or install the transitive package directly.
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 contributions a namespace. Updating the package updates the mounted extension; nothing is copied into the consumer's agent.
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 package manager already used by the consumer's agent project. For example, in a pnpm project:
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 consumer's environment, such as `.env.local` for local development.
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 named contributions: `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 declared route paths, and schedules keep their cron expressions.
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
- Do not mount an extension under the name of one of the agent's connections. A [connection owns](/docs/connections) every name that starts with `<name>__`, so the compiler rejects the mounted tools and subagents. Nor can a mount be named `eve`: eve reserves that namespace for its [built-in tools](/docs/concepts/built-in-tools#eve__search-eve__tool-and-eve__skill).
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. Moving or renaming a mount creates a new instance.
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
- Deployments before eve 0.69 stored extension state under package-prefixed keys, such as `acme-crm.requests`. When a session from one of those deployments hands off to a newer deployment, eve moves each package-prefixed value to the mount that uses that package.
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 kept in the same monorepo as its consumers. It is useful when several agents need the same capabilities, or when a private capability should evolve alongside the agents that use it.
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
- You can scaffold the extension from a directory already covered by the workspace configuration:
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 consumers will import. Add `"private": true` if it should never be published:
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 consuming agent declares its own workspace dependency:
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
- The mount is intentionally per agent. Each consumer chooses its own mount namespace and, for a configured extension, passes its own configuration. For example, `shared.ts` contributes `shared__search`, while mounting the same package as `company.ts` in another agent contributes `company__search`.
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
- When `eve dev` starts a consuming agent, it builds mounted, source-backed extensions found inside the same workspace before compiling the agent. It watches the extension source and relevant package and TypeScript configuration, then rebuilds only the affected extension. If an extension edit fails to build, the previous successful development generation keeps running.
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
- If an extension fails to build, the agent build stops with an error that names the extension package and its directory. Fix the reported error, or run `eve extension build` in that package directory to build it on its own.
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. Put the declaration in `extension.ts` and add overrides beside it:
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 same-named consumer channel, tool, connection, skill, schedule, or subagent wins. To adjust an extension tool, import it from the package's `./tools` export and define it again:
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 are additive, so they cannot be replaced. To replace a dynamic tool, use a dynamic definition in the same slot; dynamic tools win over same-named static tools at runtime. `disableTool()` removes either kind.
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 place an override in the corresponding agent-root slot by using the final qualified name. For example, `agent/tools/crm__search.ts` replaces `tools/search.ts` from the extension package or its directory override. Application sources have the highest precedence, so an agent-root override wins when both forms exist.
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 retain an extension tool's result type in a consumer hook, import its definition from `./tools` and pass it to [`toolResultFrom`](/docs/guides/hooks#narrowing-tool-results):
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` recognizes the mounted `crm__search` result from the original definition, not the namespaced string. Publishers should keep descriptions distinct across different tool definitions so eve can assign each definition an unambiguous identity. Re-exporting the same definition, such as from a subagent's `tools/` directory, does not conflict.
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` also mounts bundled development extensions without creating a project mount. The self-modification extension is included by default when `eve dev` starts a local server. Bundled development extensions are not included in production builds. See [Self-Modification](./guides/self-modification) for the local workflow.
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
- `eve extension build` records the eve version used to build the extension. When you mount a package, eve checks its distribution before loading extension code. A distribution built with a newer eve release needs that release or later; build with the oldest eve release you want to support and test the same distribution with newer consumers. An unsupported distribution generation needs a rebuilt extension or a compatible release. npm peer ranges do not replace this check.
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
- **Extensions built with the old epoch-based manifest need a rebuild** when you upgrade to the first eve release that uses the new format. Upgrade to a compatible extension release, or rebuild a source-backed workspace extension with that eve release. An installed, source-free extension cannot be rebuilt by the consuming app.
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
 
@@ -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
- Start with one agent in `agent/`.
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 capability, such as `iMessage` or `SMS`. The picker matches item names, addresses, titles, and descriptions. Select an item to install it and complete its required setup.
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 and applies the connection before returning to the composer. Changing only the account, team, or key does not rebuild your agent. Once connected, you can send your first message while the agent information refreshes in the background; no restart is required.
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) for the mental model behind sessions, turns, durable steps, and parked work.
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.