eve 0.27.2 → 0.27.4

package/docs/extensions.md

@@ -1,13 +1,13 @@
 ---
 title: "Extensions"
-description: "Publish reusable eve capabilities as an npm package, then install and mount them in an agent."
+description: "Package reusable eve capabilities and mount them from npm or a monorepo workspace."
 ---
 
-Extensions package eve tools, connections, skills, instruction fragments, and hooks. A publisher builds and distributes a package; a consumer installs it and mounts it in an agent.
+Extensions package eve tools, connections, skills, 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 registry or kept private inside a monorepo workspace.
 
 This enables sharing many different capability sets. A browser extension might include several tools for navigating a site. A memory extension could use hooks to capture context and tools to recall it. A self-improving extension could pair hooks with dynamic instructions.
 
-## Publisher: create and publish an extension
+## Author: create an extension
 
 ### Create the package
 
@@ -42,7 +42,7 @@ Keep agent configuration, sandboxes, schedules, and nested extensions in the con
 
 ### Add configuration and contributions
 
-The publisher's `extension/extension.ts` default-exports a `defineExtension` handle. Give it a [Standard Schema](https://standardschema.dev) when consumers need to provide settings:
+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:
 
 ```ts title="extension/extension.ts"
 import { defineExtension } from "eve/extension";
@@ -76,9 +76,9 @@ export default defineTool({
 
 If no configuration is needed, export `defineExtension()` and let consumers re-export it directly. Config schemas must validate synchronously.
 
-`defineState` is automatically scoped to the publisher's package, so the same state name does not collide with the consumer or another extension.
+`defineState` is automatically scoped to the extension package, so the same state name does not collide with the consumer or another extension.
 
-### Build and publish
+### Build and optionally publish
 
 The scaffold's `package.json` declares separate source and distribution roots:
 
@@ -134,29 +134,29 @@ Build the package with `eve extension build`:
 eve extension build
 ```
 
-`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 publisher's TypeScript source.
+`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.
 
-The exact `eve` development pin controls the publisher's 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`.
+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`.
 
 Put runtime packages such as `zod` or an SDK in `dependencies`. If a dependency cannot be bundled, such as a native addon, tell consumers to add it to `build.externalDependencies` in `agent.ts`.
 
-Consumers can now add the built package to an agent.
+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).
 
 ## Consumer: install and mount an extension
 
-A mount gives the publisher's contributions a namespace. Updating the package updates the mounted extension; nothing is copied into the consumer's agent.
+A mount gives the extension's contributions a namespace. Updating the package updates the mounted extension; nothing is copied into the consumer's agent.
 
 ### Install the package
 
-Install the extension in the consumer's agent project:
+Install the extension with the package manager already used by the consumer's agent project. Fresh eve projects use pnpm:
 
 ```bash
-npm install @acme/crm
+pnpm add @acme/crm
 ```
 
 ### Mount it
 
-Create a file under `agent/extensions/`. Its filename becomes the mount namespace. Call the publisher's default export when the extension needs configuration:
+Create a file under `agent/extensions/`. Its filename becomes the mount namespace. Call the extension's default export when it needs configuration:
 
 ```ts title="agent/extensions/crm.ts"
 import crm from "@acme/crm";
@@ -168,7 +168,7 @@ Set `CRM_API_KEY` in the consumer's environment, such as `.env.local` for local
 
 The mount adds `crm__` to named contributions: `tools/search.ts` becomes `crm__search`, and `connections/api.ts` becomes `crm__api`.
 
-For a publisher with no configuration, mount its default export directly:
+For an extension with no configuration, mount its default export directly:
 
 ```ts title="agent/extensions/gizmo.ts"
 export { default } from "@acme/gizmo";
@@ -176,9 +176,89 @@ export { default } from "@acme/gizmo";
 
 The same mount shape works with an npm package, a workspace dependency, or a linked local package.
 
+### Use an extension in a workspace
+
+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.
+
+For example, a pnpm workspace can keep one extension next to two independently deployable agents:
+
+```text
+acme-agents/
+├── pnpm-workspace.yaml
+├── packages/
+│   └── shared-capabilities/
+│       ├── package.json
+│       └── extension/
+│           ├── extension.ts
+│           ├── tools/
+│           ├── skills/
+│           └── hooks/
+└── agents/
+    ├── support/
+    │   ├── package.json
+    │   └── agent/extensions/shared.ts
+    └── operations/
+        ├── package.json
+        └── agent/extensions/shared.ts
+```
+
+Make both the extension and agent directories workspace members:
+
+```yaml title="pnpm-workspace.yaml"
+packages:
+  - "agents/*"
+  - "packages/*"
+```
+
+You can scaffold the extension from a directory already covered by the workspace configuration:
+
+```bash
+cd packages
+npx eve@latest extension init shared-capabilities
+```
+
+Give the generated package the name consumers will import. Add `"private": true` if it should never be published:
+
+```jsonc title="packages/shared-capabilities/package.json"
+{
+  "name": "@acme/shared-capabilities",
+  "private": true,
+  "eve": {
+    "extension": {
+      "source": "./extension",
+      "dist": "./dist/extension",
+    },
+  },
+}
+```
+
+Each consuming agent declares its own workspace dependency:
+
+```jsonc title="agents/support/package.json"
+{
+  "dependencies": {
+    "@acme/shared-capabilities": "workspace:*",
+  },
+}
+```
+
+Then each agent mounts the package:
+
+```ts title="agents/support/agent/extensions/shared.ts"
+export { default } from "@acme/shared-capabilities";
+```
+
+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`.
+
+#### Develop from source
+
+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.
+
+Production `eve build` expects the extension distribution to exist already. Keep `eve extension build` in the extension package's `build` and `prepare` scripts, as the scaffold does, and run workspace builds in dependency order so extensions build before their consuming agents.
+
 ### Override a contribution
 
-Use a directory mount to replace or remove a publisher contribution. Put the mount declaration in `extension.ts` and add overrides beside it:
+Use a directory mount to replace or remove an extension contribution. Put the mount declaration in `extension.ts` and add overrides beside it:
 
 ```
 agent/extensions/crm/
@@ -192,7 +272,7 @@ import crm from "@acme/crm";
 export default crm({ apiKey: process.env.CRM_API_KEY! });
 ```
 
-A same-named consumer tool, connection, or skill wins. To adjust a publisher tool, import it from the package's `./tools` export and define it again:
+A same-named consumer tool, connection, or skill wins. To adjust an extension tool, import it from the package's `./tools` export and define it again:
 
 ```ts title="agent/extensions/crm/tools/search.ts"
 import { search } from "@acme/crm/tools";
@@ -202,7 +282,7 @@ import { always } from "eve/tools/approval";
 export default defineTool({ ...search, approval: always() });
 ```
 
-To remove a publisher tool, use `disableTool()` in its matching slot:
+To remove an extension tool, use `disableTool()` in its matching slot:
 
 ```ts title="agent/extensions/crm/tools/search.ts"
 import { disableTool } from "eve/tools";
@@ -214,9 +294,9 @@ Hooks and instruction fragments are additive, so they cannot be replaced. To rep
 
 The `crm__` prefix is reserved for this directory mount. A consumer cannot override the extension from `agent/tools/`, `agent/connections/`, or another agent-root slot.
 
-### Use a publisher tool result in a hook
+### Use an extension tool result in a hook
 
-To retain a publisher tool's result type in a consumer hook, import its definition from `./tools` and pass it to [`toolResultFrom`](/guides/hooks#narrowing-tool-results):
+To retain an extension tool's result type in a consumer hook, import its definition from `./tools` and pass it to [`toolResultFrom`](/guides/hooks#narrowing-tool-results):
 
 ```ts title="agent/hooks/narrow-crm.ts"
 import { defineHook } from "eve/hooks";
@@ -237,7 +317,7 @@ export default defineHook({
 
 ### Compatibility
 
-At build time, eve checks the publisher's generated capability metadata. If the extension needs an unsupported capability contract, upgrade eve or install a compatible extension release.
+At build time, eve checks the extension's generated capability metadata. If the extension needs an unsupported capability contract, upgrade eve or install a compatible extension release.
 
 ## What to read next
 

package/docs/guides/dev-tui.md

@@ -71,7 +71,8 @@ Chat and freeform `ask_question` inputs behave like a shell line editor.
 
 | Key                                            | Action                                                                                                            |
 | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `Enter`                                        | Submit the message or question response.                                                                          |
+| `Enter`                                        | Submit the message or question response. While a turn is running, queue the message for the next turn.            |
+| `Esc`                                          | While a turn runs: pop the oldest queued message and steer with it; with nothing queued, press twice to cancel.   |
 | `Shift+Enter`                                  | Insert a newline without sending (needs a terminal that reports modified keys).                                   |
 | `Ctrl+C`                                       | Interrupt a running turn. At the chat or freeform-question prompt, clear non-empty input; when empty, quit.       |
 | `↑` / `↓`                                      | Move between input lines; at a chat-buffer edge, navigate messages you have sent this session.                    |
@@ -82,7 +83,13 @@ Chat and freeform `ask_question` inputs behave like a shell line editor.
 
 In terminals that support bracketed paste, pasting multi-line text into chat or a freeform question inserts it intact and renders one row per line rather than submitting at the first line. `Shift+Enter` adds a line by hand. The input grows down to the available terminal height, then scrolls to keep the caret visible; `Enter` submits the whole response.
 
-If a turn fails terminally (the server session dies or the connection drops), the TUI starts a fresh session and notes it inline so you can keep going. Server-side context resets with the old session.
+### Queue and steer while the agent works
+
+Sending a message while a turn is still running does not interrupt it — the message joins a queue of up to five, pinned in a panel directly above the input with one line per message. When the turn ends, the queued messages coalesce into the next turn's message.
+
+`Esc` steers instead of waiting: it pops the oldest queued message, cancels the running turn cooperatively, and submits the popped message as the replacement turn. In the transcript, a steered message carries an accent `↑` on its own line above its gutter bar; a queued message that waited for the boundary carries it below. Any remaining messages stay queued behind it. With nothing queued, the first `Esc` arms cancellation and a second `Esc` cancels the turn. Unlike `Ctrl+C` — which drops the stream client-side — a cancelled turn ends cleanly on the server and the session keeps its context; the conversation picks up at the next prompt.
+
+If a turn fails terminally (the server session dies or the connection drops), the TUI starts a fresh session and notes it inline so you can keep going. Server-side context resets with the old session. Messages still queued when a turn is interrupted or fails are restored into the next prompt's input instead of being sent blind.
 
 ## Answer the agent inline
 

package/docs/guides/frontend/nextjs.mdx

@@ -54,6 +54,8 @@ const billing = useEveAgent({ agent: "billing" });
 
 Use either `eveRoot` or `agents`, not both. `eveRoot` remains the shorthand for a single unnamed agent mounted at `/eve/v1/*`.
 
+Generated agent services build with `EVE_PUBLIC_ROUTE_PREFIX` set to the agent's public mount (for example `/eve/agents/support`) so framework-minted callback URLs — OAuth connection callbacks and remote-subagent session callbacks — resolve to the public per-agent path. If you configure eve services manually in `vercel.json` instead, export that variable in each named agent's build command.
+
 ### `withEve` options
 
 All fields are optional.

package/docs/reference/cli.md

@@ -173,7 +173,7 @@ For bearer tokens or custom schemes, pass explicit headers with `-H`.
 
 Local dev records the last ready URL per resolved app root in `.eve/dev-server-state.v1.json`. A second interactive `eve dev` reconnects only when that URL is loopback and healthy; each terminal UI creates a fresh client session while sharing the server process. A stale or malformed record is replaced when eve starts a new server. Passing `--host`, `--port`, or a `PORT` environment value skips reconnection and reports a healthy recorded server instead.
 
-Local dev keeps immutable runtime source snapshots under `.eve/dev-runtime/snapshots/` so in-flight turns hold a consistent code revision while new turns pick up rebuilds. The terminal REPL keeps its logical session across successful rebuilds, so the next turn continues the conversation on the latest generation; use `/new` to start a fresh session. After a generation is superseded, `eve dev` retains it for at least 30 minutes and also retains the five most recently superseded generations, regardless of the configured Workflow World. The active generation is never pruned. Old runtime snapshots and local sandbox templates are pruned in the background. For manual cleanup, stop `eve dev` before deleting `.eve/dev-runtime/snapshots/` or `.eve/sandbox-cache/local/templates/`. A turn that remains unfinished beyond the automatic retention window can no longer resume after its generation is pruned.
+Local dev keeps immutable runtime source snapshots under `.eve/dev-runtime/snapshots/` so in-flight turns hold a consistent code revision while new turns pick up rebuilds. The terminal REPL keeps its logical session across successful rebuilds, so the next turn continues the conversation on the latest generation; `/new` terminally retires that session before clearing the transcript, and the next prompt starts a fresh session with a new session-scoped sandbox on first sandbox use. After a generation is superseded, `eve dev` retains it for at least 30 minutes and also retains the five most recently superseded generations, regardless of the configured Workflow World. The active generation is never pruned. Old runtime snapshots and local sandbox templates are pruned in the background. For manual cleanup, stop `eve dev` before deleting `.eve/dev-runtime/snapshots/` or `.eve/sandbox-cache/local/templates/`. A turn that remains unfinished beyond the automatic retention window can no longer resume after its generation is pruned.
 
 ## `eve logs`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.27.2",
+  "version": "0.27.4",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [