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
|
@@ -3,19 +3,19 @@ title: "Session Context"
|
|
|
3
3
|
description: "Use ctx.session and runtime accessors inside eve-managed execution."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
The runtime `ctx` is the object eve passes to tool executors, hook handlers, channel event handlers, and connection auth and header resolvers. Use it to read the current session and reach resources for the code that is running.
|
|
7
7
|
|
|
8
8
|
| Accessor | Provides | Full guide |
|
|
9
9
|
| ---------------------------- | --------------------------------------------------------- | -------------------------- |
|
|
10
10
|
| `ctx.session` | Session identity, turn metadata, auth, and parent lineage | This page |
|
|
11
11
|
| `ctx.getSandbox()` | The current agent's live sandbox handle | [Sandbox](../sandbox) |
|
|
12
|
-
| `defineState(name, initial)` |
|
|
12
|
+
| `defineState(name, initial)` | Typed state shared by runtime code in one session | [State](../concepts/state) |
|
|
13
13
|
|
|
14
|
-
These APIs work only
|
|
14
|
+
These APIs work only while eve runs your code. Calling them while a module loads, during discovery, or during a build throws.
|
|
15
15
|
|
|
16
16
|
## `ctx.session`
|
|
17
17
|
|
|
18
|
-
`ctx.session` describes the
|
|
18
|
+
`ctx.session` describes the session and the active turn:
|
|
19
19
|
|
|
20
20
|
```ts title="agent/tools/who_called_me.ts"
|
|
21
21
|
import { defineTool } from "eve/tools";
|
|
@@ -40,28 +40,28 @@ export default defineTool({
|
|
|
40
40
|
|
|
41
41
|
Public fields include:
|
|
42
42
|
|
|
43
|
-
- `id`: the
|
|
43
|
+
- `id`: the session ID.
|
|
44
44
|
- `turn.id`: the current turn ID.
|
|
45
45
|
- `turn.sequence`: the turn's position in the session.
|
|
46
46
|
- `auth.current`: the caller for the active inbound turn.
|
|
47
47
|
- `auth.initiator`: the caller that started the session.
|
|
48
48
|
- `parent`: the parent call, session, root session, and turn for a child subagent session.
|
|
49
|
-
- `predecessor`: present only when this session replaced a stranded one; `sessionId` names that earlier session. See [Recover a stranded session](./deployment/self-
|
|
49
|
+
- `predecessor`: present only when this session replaced a stranded one; `sessionId` names that earlier session. See [Recover a stranded session](./deployment/self-hosted-operations#recover-a-stranded-session) to read its earlier conversation.
|
|
50
50
|
|
|
51
|
-
Unprotected agents expose `auth.current` and `auth.initiator` as `null`.
|
|
51
|
+
Unprotected agents expose `auth.current` and `auth.initiator` as `null`. Sessions that a top-level schedule starts use eve's app identity (`principalId: "eve:app"`, `principalType: "runtime"`). See [Authentication](./auth-and-route-protection#what-reaches-ctxsessionauth) for how inbound identity becomes session auth.
|
|
52
52
|
|
|
53
53
|
## `ctx.getSandbox()`
|
|
54
54
|
|
|
55
|
-
|
|
55
|
+
`ctx.getSandbox()` returns a handle for filesystem and process access in the current agent's sandbox:
|
|
56
56
|
|
|
57
57
|
```ts
|
|
58
58
|
const sandbox = await ctx.getSandbox();
|
|
59
59
|
const result = await sandbox.run({ command: "npm test" });
|
|
60
60
|
```
|
|
61
61
|
|
|
62
|
-
The accessor is asynchronous because eve may need to
|
|
62
|
+
The accessor is asynchronous because eve may need to attach or restore the sandbox. A subagent sees its own sandbox, not its parent's. The returned handle also exposes `stop()` and `delete()`; see [Sandbox lifecycle](../sandbox#lifecycle) for their behavior.
|
|
63
63
|
|
|
64
|
-
|
|
64
|
+
Pass the exported environment object to get methods specific to that environment. Provider-specific methods such as `setNetworkPolicy()` are not available from the no-argument accessor:
|
|
65
65
|
|
|
66
66
|
```ts
|
|
67
67
|
import { environment } from "../sandbox";
|
|
@@ -70,11 +70,11 @@ const sandbox = await ctx.getSandbox(environment);
|
|
|
70
70
|
await sandbox.setNetworkPolicy("deny-all");
|
|
71
71
|
```
|
|
72
72
|
|
|
73
|
-
The environment must be the one configured for the current sandbox
|
|
73
|
+
The environment must be the one configured for the current sandbox; eve rejects any other.
|
|
74
74
|
|
|
75
75
|
## Custom state with `defineState`
|
|
76
76
|
|
|
77
|
-
|
|
77
|
+
`defineState` declares a per-session value that tools, hooks, and channel handlers share. The value survives crashes and redeploys. Import it from `eve/context` and declare the handle at module scope. Its `get()` and `update()` methods still work only while eve runs your code. See [State](../concepts/state) for the read, update, reset, and subagent-isolation model.
|
|
78
78
|
|
|
79
79
|
## Where these APIs work
|
|
80
80
|
|
|
@@ -85,14 +85,14 @@ Runtime context is available:
|
|
|
85
85
|
- inside channel and agent hook callbacks that receive the full runtime `ctx`;
|
|
86
86
|
- after asynchronous boundaries within the same authored execution chain.
|
|
87
87
|
|
|
88
|
-
|
|
88
|
+
Declare reusable definitions and state handles at module scope, but call their context-dependent methods only from a callback that eve runs.
|
|
89
89
|
|
|
90
90
|
## How it works
|
|
91
91
|
|
|
92
|
-
eve
|
|
92
|
+
eve sets up session data and per-step resources before your code runs. They stay available across asynchronous work in the same call chain. eve saves state changes at the end of the step.
|
|
93
93
|
|
|
94
94
|
## What to read next
|
|
95
95
|
|
|
96
|
-
- [State](../concepts/state):
|
|
96
|
+
- [State](../concepts/state): typed values that belong to one session.
|
|
97
97
|
- [Sandbox](../sandbox): runtime filesystem and process access.
|
|
98
|
-
- [Sessions, runs, and streaming](../concepts/sessions-runs-and-streaming):
|
|
98
|
+
- [Sessions, runs, and streaming](../concepts/sessions-runs-and-streaming): how sessions and their events work.
|
|
@@ -4,11 +4,11 @@ description: "Discover and install extensions and other integrations from eve an
|
|
|
4
4
|
contentType: "How-to"
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
An integration is a set of project files and dependencies, such as an extension, channel, or memory provider. `eve add` installs integrations from eve's official catalog, a third-party source, or a URL. Integrations use the [shadcn registry format](https://ui.shadcn.com/docs/registry).
|
|
8
8
|
|
|
9
9
|
## Install an integration
|
|
10
10
|
|
|
11
|
-
Run `eve add` from an eve agent project
|
|
11
|
+
Run `eve add` from an eve agent project to install the integration's dependencies and write its files into your project.
|
|
12
12
|
|
|
13
13
|
```bash
|
|
14
14
|
eve add extension/agent-browser
|
|
@@ -17,19 +17,27 @@ eve add instrumentation/braintrust
|
|
|
17
17
|
eve add memory/file
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
If an item
|
|
20
|
+
If an item isn't found, `eve add` prints close matches from the available catalogs without installing anything.
|
|
21
21
|
|
|
22
|
-
Web Chat installs a
|
|
22
|
+
Web Chat installs a Next.js or TanStack Start application at `apps/web` for a standalone agent or a selected workspace member. The installer asks for the framework (`web-framework`), then the deployment. Non-interactive runs use Next.js unless you answer `web-framework="tanstack"`.
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
For the deployment, choose **Vercel services** (recommended) to deploy Web Chat and agents as separate services. Choose the framework (**Next.js** or **TanStack Start**) to serve Web Chat and route agent requests through one app. Vercel services run locally without a linked Vercel project. If you already have Next.js or Vercel configuration, eve stops with manual composition guidance instead of overwriting it. See [Project Structure](./concepts/project-structure) for browser-app placement, and [Next.js](./guides/frontend/nextjs) or [TanStack Start](./guides/frontend/tanstack) for framework-owned integration.
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
Run `eve add` without an argument to see how to search the registry with `eve registry search <query>`.
|
|
27
27
|
|
|
28
|
-
|
|
28
|
+
Each kind of integration writes files in its own directory:
|
|
29
29
|
|
|
30
|
-
|
|
30
|
+
- Extensions may create a mount under `agent/extensions/`, as `eve add eve/self-modification` does.
|
|
31
|
+
- Connections write a definition under `agent/connections/` and install `@vercel/connect` when required.
|
|
32
|
+
- Instrumentation integrations write one destination file under `agent/instrumentation/`, so you can configure several exporters independently.
|
|
31
33
|
|
|
32
|
-
|
|
34
|
+
Configure generated files and required environment variables before running your agent.
|
|
35
|
+
|
|
36
|
+
When an official item has interactive setup steps, eve asks whether to run them after installation. To resume a skipped or cancelled setup, run the printed `eve add <item> --skip-install` command, which reruns the setup from the beginning.
|
|
37
|
+
|
|
38
|
+
For example, setup for `eve add memory/file` creates or reuses a private Vercel Blob store, connects it to production, preview, and development, and offers to deploy. Before provisioning, it shows the project, store, region, environments, and possible Blob usage charges. See [File memory](./memory/file).
|
|
39
|
+
|
|
40
|
+
An official item may name optional pnpm dependencies that have build scripts. Before installation, eve asks whether to skip those packages, allow their build scripts, or abort. It records your choice in `ignoredOptionalDependencies` or `allowBuilds` in the owning pnpm workspace. Allow build scripts only when you trust the packages named in the prompt.
|
|
33
41
|
|
|
34
42
|
## Automate setup
|
|
35
43
|
|
|
@@ -41,7 +49,7 @@ Use `eve add <item> --non-interactive` when a script or coding agent cannot answ
|
|
|
41
49
|
| `1` | Installation or setup failed. |
|
|
42
50
|
| `2` | Setup needs an answer or an unmet prerequisite. |
|
|
43
51
|
|
|
44
|
-
On exit code `2`, read the final event and run its `next.command`. For a non-secret question, replace its `<JSON value>` placeholder with the answer you collected. Never pass a secret in `--answer
|
|
52
|
+
On exit code `2`, read the final event and run its `next.command`. For a non-secret question, replace its `<JSON value>` placeholder with the answer you collected. Never pass a secret in `--answer`. Use the environment variable or secret store the integration documents instead. Add `--yes` to accept recommended values; explicit answers take precedence.
|
|
45
53
|
|
|
46
54
|
A setup may report `eve link` as a prerequisite. Run it, then retry the continuation. See [Deployment](./guides/deployment/vercel.mdx) for the non-interactive `eve link` and `eve deploy` forms.
|
|
47
55
|
|
|
@@ -55,7 +63,7 @@ List every official integration and configured third-party source:
|
|
|
55
63
|
eve registry list
|
|
56
64
|
```
|
|
57
65
|
|
|
58
|
-
Search the catalog
|
|
66
|
+
Search the catalog by what an integration does. Omit `--limit` to return up to 10 matches, or set it between 1 and 100:
|
|
59
67
|
|
|
60
68
|
```bash
|
|
61
69
|
eve registry search browser --limit 5
|
|
@@ -110,13 +118,11 @@ eve add https://registry.acme.com/r/analytics.json
|
|
|
110
118
|
|
|
111
119
|
## Contribute an official integration
|
|
112
120
|
|
|
113
|
-
|
|
121
|
+
Open an issue and get maintainer agreement before you submit a pull request to the official registry. Then follow the [registry contribution guide](https://github.com/vercel/eve/blob/main/CONTRIBUTING.md#adding-an-integration-to-the-registry) for the required source files, metadata, validation, and extension requirements.
|
|
114
122
|
|
|
115
123
|
## Host your own registry
|
|
116
124
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
An eve registry is a standard [shadcn registry](https://ui.shadcn.com/docs/registry), so it can be hosted by any service that serves JSON over HTTP. It needs two kinds of endpoint:
|
|
125
|
+
A hosted registry is what other eve projects add as a [third-party source](#add-a-third-party-source). It is a standard [shadcn registry](https://ui.shadcn.com/docs/registry), so any service that serves JSON over HTTP can host it. It needs two kinds of endpoint:
|
|
120
126
|
|
|
121
127
|
- A catalog such as `https://registry.acme.com/r/registry.json` for `eve registry list` and `eve registry search`
|
|
122
128
|
- One JSON document per integration, such as `https://registry.acme.com/r/analytics.json`, for `eve registry view` and `eve add`
|
|
@@ -156,7 +162,7 @@ registry/
|
|
|
156
162
|
}
|
|
157
163
|
```
|
|
158
164
|
|
|
159
|
-
`files[].path` is relative to `registry.json
|
|
165
|
+
`files[].path` is relative to `registry.json`, and `files[].target` to the root of the installing eve project. Use `registry:item` with explicit `registry:file` targets so installation doesn't depend on a UI framework or shadcn project aliases.
|
|
160
166
|
|
|
161
167
|
Validate the source registry, then build its static JSON:
|
|
162
168
|
|
|
@@ -165,7 +171,7 @@ pnpm dlx shadcn@latest registry validate
|
|
|
165
171
|
pnpm dlx shadcn@latest build
|
|
166
172
|
```
|
|
167
173
|
|
|
168
|
-
|
|
174
|
+
The build writes the catalog to `public/r/registry.json` and each item to `public/r/<name>.json`. Deploy the `public` directory to a static host, or use the shadcn registry APIs to serve the same payloads from dynamic routes.
|
|
169
175
|
|
|
170
176
|
Before sharing the registry, test its deployed catalog and item endpoints from an eve project:
|
|
171
177
|
|
|
@@ -174,7 +180,7 @@ eve registry list --registry https://registry.acme.com/r/registry.json
|
|
|
174
180
|
eve registry view https://registry.acme.com/r/analytics.json
|
|
175
181
|
```
|
|
176
182
|
|
|
177
|
-
Share the item URL template with consumers
|
|
183
|
+
Share the item URL template with consumers, who add it as a third-party source:
|
|
178
184
|
|
|
179
185
|
```bash
|
|
180
186
|
eve registry add @acme=https://registry.acme.com/r/{name}.json
|
|
@@ -183,17 +189,13 @@ eve add @acme/analytics
|
|
|
183
189
|
|
|
184
190
|
## Configure generated files
|
|
185
191
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
For an extension, this usually means setting environment variables and editing the file under `agent/extensions/`. See [Extensions](./extensions) for mount configuration, namespacing, and overrides.
|
|
192
|
+
Read the generated files before you run the agent. For an extension, this usually means setting environment variables and editing the mount under `agent/extensions/`. See [Extensions](./extensions) for mount configuration, namespacing, and overrides.
|
|
189
193
|
|
|
190
194
|
Provider-specific setup lives in the [Integrations directory](/integrations). Follow that guidance for credentials, approval policies, and service-specific options.
|
|
191
195
|
|
|
192
196
|
## Update an installed integration
|
|
193
197
|
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
Run the same command when the registry publisher provides an updated scaffold:
|
|
198
|
+
Generated files are project code, so commit or review local changes before you install again. Run the same command to get the publisher's updated scaffold:
|
|
197
199
|
|
|
198
200
|
```bash
|
|
199
201
|
eve add extension/agent-browser
|
package/docs/instructions.mdx
CHANGED
|
@@ -3,11 +3,11 @@ title: "Instructions"
|
|
|
3
3
|
description: "Add system context or durable user context with instructions.md or instructions.ts."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
Instructions
|
|
6
|
+
Instructions are text you write for the model in `agent/instructions.md` or `agent/instructions.ts`. Use system-role instructions for the agent's identity and standing rules. Use user-role instructions for application context that belongs in the conversation history, such as an imported brief or retrieved memory.
|
|
7
7
|
|
|
8
8
|
## Author instructions
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
The smallest instructions are a markdown file at the agent root. Its contents are the prompt:
|
|
11
11
|
|
|
12
12
|
```md title="agent/instructions.md"
|
|
13
13
|
You are a concise assistant. Use tools when they are available.
|
|
@@ -15,82 +15,77 @@ You are a concise assistant. Use tools when they are available.
|
|
|
15
15
|
|
|
16
16
|
Keep this file to stable behavior such as identity, tone, and standing rules.
|
|
17
17
|
|
|
18
|
-
##
|
|
18
|
+
## System and user roles
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
System-role instructions stay outside the conversation history, and eve includes them on every model call. When you deploy a new version, or `eve dev` reloads, existing sessions use the current system instructions.
|
|
21
21
|
|
|
22
|
-
|
|
23
|
-
import { defineInstructions } from "eve/instructions";
|
|
24
|
-
import { buildInstructionsPrompt } from "./lib/prompts";
|
|
22
|
+
eve adds static user-role instructions to a new session's history once, in source order. A newer deployment doesn't add them again or replace them.
|
|
25
23
|
|
|
26
|
-
|
|
27
|
-
content: buildInstructionsPrompt(),
|
|
28
|
-
});
|
|
29
|
-
```
|
|
24
|
+
## Markdown vs TypeScript
|
|
30
25
|
|
|
31
|
-
`
|
|
26
|
+
Put a static system prompt in markdown (`agent/instructions.md`). Switch to a TypeScript module (`agent/instructions.ts`) when you need typed composition, `lib/` code, build-time values, or a user-role message:
|
|
32
27
|
|
|
33
28
|
```ts title="agent/instructions/brief.ts"
|
|
34
29
|
import { defineInstructions } from "eve/instructions";
|
|
35
30
|
import { buildCustomerBrief } from "../lib/customer";
|
|
36
31
|
|
|
37
32
|
export default defineInstructions({
|
|
38
|
-
content: buildCustomerBrief(),
|
|
39
|
-
role: "user",
|
|
33
|
+
content: buildCustomerBrief(), // blank content adds nothing
|
|
34
|
+
role: "user", // "system" or "user"; omit for "system"
|
|
40
35
|
});
|
|
41
36
|
```
|
|
42
37
|
|
|
43
|
-
|
|
38
|
+
The module, including its ESM and [asset imports](./reference/typescript-api#asset-imports) such as a prompt imported with `?raw`, runs once at build time and never at runtime. See [Authored module lifecycle](./reference/typescript-api#authored-module-lifecycle).
|
|
44
39
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
This includes its normal ESM and [asset imports](./reference/typescript-api#asset-imports), such as a top-level prompt imported with `?raw`. See [Authored module lifecycle](./reference/typescript-api#authored-module-lifecycle) for the full compile/runtime contract.
|
|
48
|
-
|
|
49
|
-
## System and user roles
|
|
40
|
+
## Split instructions across a directory
|
|
50
41
|
|
|
51
|
-
|
|
42
|
+
For more than one file, add an `agent/instructions/` directory. eve reads its `.md` files and `.ts` modules, but not subdirectories. A `.ts` file can export `defineInstructions` or `defineDynamic`. Static system and user entries apply in alphabetical filename order (`localeCompare`).
|
|
52
43
|
|
|
53
|
-
|
|
44
|
+
A root `agent/instructions.md` (or `.ts`) can sit beside the directory, and the root file comes first. Having both `instructions.md` and `instructions.ts` at the root is a build error.
|
|
54
45
|
|
|
55
|
-
##
|
|
46
|
+
## Dynamic instructions
|
|
56
47
|
|
|
57
|
-
|
|
48
|
+
To compute instructions from auth, tenant, channel, or external data, use `defineDynamic((ctx) => ...)` and return `defineInstructions(...)` or `null`. The function runs before each ordinary model call. Use `ctx.memo(key, fn)` to keep a JSON result fixed for a key.
|
|
58
49
|
|
|
59
|
-
A
|
|
50
|
+
A dynamic system instruction applies, outside history, while the function returns it.
|
|
60
51
|
|
|
61
|
-
|
|
52
|
+
A dynamic user instruction joins the conversation history only when its content changes:
|
|
62
53
|
|
|
63
|
-
|
|
54
|
+
- Before a turn's first model call, it joins ahead of the turn's input.
|
|
55
|
+
- During a turn, a change appends at the current position.
|
|
56
|
+
- Returning `null` adds nothing and resets change tracking, so a later return of the earlier text adds it again.
|
|
57
|
+
- Existing history is not removed.
|
|
58
|
+
- Change tracking survives deployments, clear, and compaction.
|
|
64
59
|
|
|
65
|
-
|
|
66
|
-
| ------------------------ | ----------------------------------------------------- | -------------------------------------------------------- |
|
|
67
|
-
| System-role instructions | Outside history on every model call | Permanent identity and standing rules |
|
|
68
|
-
| User-role instructions | Once at their static or dynamic lifecycle boundary | Application context that belongs in conversation history |
|
|
69
|
-
| `agent/skills/*` | On demand, when the model loads one with `eve__skill` | Optional procedures that should not bloat every turn |
|
|
60
|
+
See [Dynamic capabilities](./guides/dynamic-capabilities) for examples and failure behavior.
|
|
70
61
|
|
|
71
|
-
|
|
62
|
+
A session that replaced a [stranded session](./concepts/execution-model-and-durability#what-a-replacement-session-receives) can receive the earlier conversation. In a user-role instruction, read the earlier session's stream with `sessions.attach()` and `transcriptOf()`, memoized by that session's ID.
|
|
72
63
|
|
|
73
|
-
|
|
64
|
+
## History controls and prompt caching
|
|
74
65
|
|
|
75
|
-
|
|
66
|
+
[Compaction](./concepts/sessions-runs-and-streaming#compact-clear-and-end) treats user-role instructions like any other history, so a summary can replace their text. Clear removes them with the rest of the conversation history and doesn't run static or dynamic instructions again. System-role instructions remain, because they are outside history.
|
|
76
67
|
|
|
77
|
-
|
|
68
|
+
Keep system-role content stable and ahead of frequently changing context when you can, so providers can reuse the prompt prefix. Cache behavior and billing depend on the provider, and eve doesn't promise a cache hit.
|
|
78
69
|
|
|
79
|
-
|
|
70
|
+
User-role instructions only append, so they keep the earlier prompt prefix the same. eve's notes about available skills and parked agents are user-role history too. A changed note appends after earlier steps. eve skips an unchanged note until history is cleared or compacted.
|
|
80
71
|
|
|
81
|
-
|
|
72
|
+
## Instructions vs skills
|
|
82
73
|
|
|
83
|
-
|
|
74
|
+
Instructions and [skills](./skills) both add text to the model's context, at different times:
|
|
84
75
|
|
|
85
|
-
|
|
76
|
+
| | Loaded | Use for |
|
|
77
|
+
| ------------------------ | ----------------------------------------------------- | -------------------------------------------------------- |
|
|
78
|
+
| System-role instructions | Outside history on every model call | Permanent identity and standing rules |
|
|
79
|
+
| User-role instructions | Once for static ones; on each change for dynamic ones | Application context that belongs in conversation history |
|
|
80
|
+
| `agent/skills/*` | On demand, when the model loads one with `eve__skill` | Optional procedures that should not bloat every turn |
|
|
86
81
|
|
|
87
|
-
Keep
|
|
82
|
+
Keep instructions short and stable. Put long or situational procedures in [skills](./skills). Put typed behavior that runs code in a [tool](./tools), because static instructions never run code at runtime.
|
|
88
83
|
|
|
89
84
|
## Disclaimer
|
|
90
85
|
|
|
91
86
|
As the deployer, it is your responsibility to ensure your agent complies with applicable laws.
|
|
92
87
|
|
|
93
|
-
Where an eve agent communicates with people,
|
|
88
|
+
Where an eve agent communicates with people, law may require you to disclose that they are interacting with an automated AI system. eve doesn't add this disclosure; configure it in your instructions or channel responses.
|
|
94
89
|
|
|
95
90
|
## What to read next
|
|
96
91
|
|
|
@@ -4,11 +4,10 @@ description: "Implement the recall, capture, and tools contract so any store or
|
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
A memory provider is an object with a `recall` handler and optional `capture`
|
|
7
|
-
and `tools` handlers. eve calls
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
write one directly inside an agent.
|
|
7
|
+
and `tools` handlers. eve calls the handlers at fixed points in each turn. Each
|
|
8
|
+
handler receives the slot's scope key, the conversation, and an operation ID
|
|
9
|
+
that stays the same when eve runs the handler again. Package a provider as a
|
|
10
|
+
library that exports a factory, or write one inside an agent.
|
|
12
11
|
|
|
13
12
|
```ts title="agent/lib/notes-memory.ts"
|
|
14
13
|
import { defineMemoryProvider } from "eve/memory";
|
|
@@ -74,15 +73,14 @@ prepended to its description.
|
|
|
74
73
|
|
|
75
74
|
## The provider contract
|
|
76
75
|
|
|
77
|
-
`defineMemoryProvider()` accepts three surfaces. Omit any handler the
|
|
78
|
-
|
|
79
|
-
capture.
|
|
76
|
+
`defineMemoryProvider()` accepts three surfaces. Omit any optional handler the
|
|
77
|
+
provider doesn't need; `fileMemory()`, for example, has no capture.
|
|
80
78
|
|
|
81
|
-
| Surface | Handlers | Responsibility
|
|
82
|
-
| --------- | -------------------------------------------- |
|
|
83
|
-
| `recall` | `"turn.started"` (required) | Return messages to place in model context
|
|
84
|
-
| `capture` | `"turn.completed"`, `"compaction.requested"` |
|
|
85
|
-
| `tools` | one function | Return model
|
|
79
|
+
| Surface | Handlers | Responsibility |
|
|
80
|
+
| --------- | -------------------------------------------- | ----------------------------------------------------- |
|
|
81
|
+
| `recall` | `"turn.started"` (required) | Return messages to place in model context |
|
|
82
|
+
| `capture` | `"turn.completed"`, `"compaction.requested"` | Read the finished conversation and write to the store |
|
|
83
|
+
| `tools` | one function | Return tools for the model, bound to the slot's scope |
|
|
86
84
|
|
|
87
85
|
### Operation context
|
|
88
86
|
|
|
@@ -94,7 +92,7 @@ Every handler receives a `MemoryOperationContext`:
|
|
|
94
92
|
| `memory.scope.namespace` | The resolved namespace string |
|
|
95
93
|
| `memory.scope.value` | The resolved scope string or tuple |
|
|
96
94
|
| `memory.slot` | The path-derived slot name |
|
|
97
|
-
| `messages` |
|
|
95
|
+
| `messages` | Conversation history for this phase |
|
|
98
96
|
| `operationId` | Stable per session, turn, step, phase, and slot. Use it as an idempotency key. |
|
|
99
97
|
| `abortSignal` | Cancellation for the operation |
|
|
100
98
|
| `session` | Session ID, authentication, and other `SessionContext` fields |
|
|
@@ -125,13 +123,12 @@ return {
|
|
|
125
123
|
};
|
|
126
124
|
```
|
|
127
125
|
|
|
128
|
-
eve adds each message to
|
|
129
|
-
|
|
126
|
+
eve adds each message to model calls as a user-role message attributed to the
|
|
127
|
+
slot, never as system instructions.
|
|
130
128
|
|
|
131
|
-
What a turn recalls stays for the rest of the session
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
does with it:
|
|
129
|
+
What a turn recalls stays for the rest of the session, just before that turn's
|
|
130
|
+
input in every later model call. The `id` decides what a later recall does with
|
|
131
|
+
it:
|
|
135
132
|
|
|
136
133
|
| Message | Effect |
|
|
137
134
|
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -140,47 +137,44 @@ does with it:
|
|
|
140
137
|
|
|
141
138
|
A result of `null`, `undefined`, or `{ messages: [] }` adds nothing and keeps
|
|
142
139
|
what earlier turns recalled. Give every message a stable `id` when the provider
|
|
143
|
-
returns its current state each turn, as `fileMemory()` does
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
context. The `id` also identifies the record in
|
|
140
|
+
returns its current state each turn, as `fileMemory()` does, or each turn adds
|
|
141
|
+
another copy. Records that differ each turn accumulate for the session and
|
|
142
|
+
count toward every model call's context. The `id` also identifies the record in
|
|
147
143
|
[instrumentation](../observability/instrumentation).
|
|
148
144
|
|
|
149
145
|
### Tools
|
|
150
146
|
|
|
151
147
|
`tools()` returns a `MemoryToolSet`, a map of `defineTool()` values, or `null`. eve qualifies each
|
|
152
|
-
key as `<slot>__<key
|
|
153
|
-
|
|
148
|
+
key as `<slot>__<key>`. The qualified name must start with a letter, use only
|
|
149
|
+
letters, digits, underscores, or dashes, and be at most 64 characters.
|
|
154
150
|
Schemas, `approval`, `outputSchema`, and `toModelOutput` work as they do for
|
|
155
151
|
authored tools.
|
|
156
152
|
|
|
157
|
-
A tool
|
|
158
|
-
tenant or caller
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
same
|
|
162
|
-
than resolving it again.
|
|
153
|
+
A tool keeps the scope it was created with, so the model can't point it at
|
|
154
|
+
another tenant or caller. eve resolves the scope once per turn and caller, so
|
|
155
|
+
tools and recall use the same scope. A new turn or a new caller resolves it
|
|
156
|
+
again. After a restart within the same turn, eve calls `tools()` again with the
|
|
157
|
+
same scope.
|
|
163
158
|
|
|
164
159
|
## Lifecycle
|
|
165
160
|
|
|
166
161
|
| Phase | Handler | `messages` contains |
|
|
167
162
|
| ---------------------- | --------------------------------- | ----------------------------------------------------------------------------- |
|
|
168
163
|
| `turn.started` | `recall["turn.started"]` | The conversation the turn's first model call reads, with the turn's new input |
|
|
169
|
-
| `turn.completed` | `capture["turn.completed"]` |
|
|
164
|
+
| `turn.completed` | `capture["turn.completed"]` | The finished history after a successful turn |
|
|
170
165
|
| `compaction.requested` | `capture["compaction.requested"]` | The history compaction is about to rewrite |
|
|
171
166
|
|
|
172
167
|
eve recalls before the first model call of each turn, and again when the
|
|
173
|
-
session's
|
|
168
|
+
session's caller changes. Recalled messages stay outside history, so
|
|
174
169
|
compaction never summarizes them. When compaction summarizes a turn, that
|
|
175
170
|
turn's recalled messages move to just after the summary.
|
|
176
171
|
|
|
177
|
-
Before
|
|
178
|
-
|
|
179
|
-
provider can keep detail the summary will lose. The summary waits for it.
|
|
172
|
+
Before compaction rewrites history, eve calls `capture["compaction.requested"]`
|
|
173
|
+
and waits for it, so a provider can keep detail the summary will lose.
|
|
180
174
|
|
|
181
|
-
Calling `clear()` on a session removes its history and
|
|
182
|
-
|
|
183
|
-
|
|
175
|
+
Calling `clear()` on a session removes its history and recalled messages but
|
|
176
|
+
not the provider's store, so the next turn recalls again. A new scope, such as
|
|
177
|
+
another caller's, also starts over.
|
|
184
178
|
|
|
185
179
|
## Failure behavior
|
|
186
180
|
|
|
@@ -225,5 +219,5 @@ provider:
|
|
|
225
219
|
|
|
226
220
|
- [Memory overview](/docs/memory): slots, scope, and namespace.
|
|
227
221
|
- [File memory](./file): the built-in provider as a reference implementation.
|
|
228
|
-
- [Dynamic capabilities](../guides/dynamic-capabilities):
|
|
222
|
+
- [Dynamic capabilities](../guides/dynamic-capabilities): provider tools run as dynamic tools; see how eve evaluates them.
|
|
229
223
|
- [Default harness](../concepts/default-harness): compaction in the built-in loop.
|