eve 0.89.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 +39 -9
- package/dist/src/channel/adapter.d.ts +12 -3
- package/dist/src/channel/adapter.js +1 -1
- package/dist/src/channel/auth/definitions.d.ts +7 -20
- package/dist/src/channel/auth/definitions.js +1 -1
- package/dist/src/channel/auth/http-basic.js +1 -1
- package/dist/src/channel/auth/jwt-ecdsa.js +1 -1
- package/dist/src/channel/auth/jwt-hmac.js +1 -1
- package/dist/src/channel/auth/oidc.js +1 -1
- package/dist/src/channel/auth/result.d.ts +2 -3
- package/dist/src/channel/auth/result.js +1 -1
- package/dist/src/channel/channel-address.d.ts +1 -1
- package/dist/src/channel/channel-address.js +1 -1
- package/dist/src/channel/channel-operations.d.ts +1 -1
- package/dist/src/channel/schedule.js +1 -1
- package/dist/src/channel/types.d.ts +2 -0
- package/dist/src/chunks/{use-eve-agent-Bbl4H5aA.js → use-eve-agent-Bwloorf8.js} +77 -63
- package/dist/src/chunks/{use-eve-agent-CNpxgKEH.js → use-eve-agent-XCB0-tLX.js} +77 -63
- package/dist/src/cli/dev/environment.js +1 -1
- package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
- package/dist/src/cli/dev/tui/remote-connection-probe.js +1 -1
- package/dist/src/cli/dev/tui/remote-connection-types.d.ts +1 -0
- package/dist/src/cli/dev/tui/runner.js +2 -2
- package/dist/src/cli/dev/tui/status-line.d.ts +2 -2
- package/dist/src/cli/dev/tui/status-line.js +1 -1
- package/dist/src/client/agent-info-schema.d.ts +341 -326
- package/dist/src/client/agent-info-schema.js +1 -1
- package/dist/src/client/agent-info-types.d.ts +13 -10
- package/dist/src/client/client-error.d.ts +1 -1
- package/dist/src/client/client.d.ts +5 -3
- package/dist/src/client/client.js +1 -1
- package/dist/src/client/session.d.ts +1 -1
- package/dist/src/compiled/.vendor-stamp.json +1 -1
- package/dist/src/evals/target.js +1 -1
- package/dist/src/eve-channel/auth.d.ts +19 -0
- package/dist/src/eve-channel/auth.js +1 -0
- package/dist/src/eve-channel/index.d.ts +1 -0
- package/dist/src/eve-channel/index.js +1 -1
- package/dist/src/eve-channel/types.d.ts +23 -4
- package/dist/src/execution/catalog/connection-entry.js +1 -1
- package/dist/src/execution/coordination-dispatch-shared.js +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/internal/authored-module-graph.js +1 -1
- package/dist/src/internal/nitro/routes/agent-info/build-agent-info-response.d.ts +2 -2
- package/dist/src/protocol/routes.d.ts +7 -1
- package/dist/src/protocol/routes.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/github/githubChannel.js +1 -1
- package/dist/src/public/channels/github/state.d.ts +7 -0
- package/dist/src/public/channels/github/state.js +1 -1
- package/dist/src/public/channels/mcp.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/channels/telegram/telegramChannel.js +1 -1
- package/dist/src/public/connections/index.d.ts +1 -1
- package/dist/src/public/definitions/channel.js +1 -1
- package/dist/src/public/definitions/connections/tool-call.d.ts +2 -2
- 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/frame.js +1 -1
- 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/channels/registry.d.ts +2 -2
- package/dist/src/runtime/channels/registry.js +1 -1
- package/dist/src/runtime/connections/approval-scope.d.ts +9 -0
- package/dist/src/runtime/connections/approval-scope.js +1 -0
- package/dist/src/runtime/connections/mcp-client.d.ts +1 -1
- package/dist/src/runtime/connections/mcp-client.js +1 -1
- package/dist/src/runtime/connections/provided-arguments.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/agent-info-access.d.ts +5 -0
- package/dist/src/shared/agent-info-access.js +1 -0
- package/dist/src/shared/connection-types.d.ts +21 -4
- package/dist/src/shared/value-delta.d.ts +5 -4
- package/dist/src/shared/value-delta.js +1 -1
- package/dist/src/svelte/index.js +1 -1
- package/dist/src/svelte/use-eve-agent.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/dist/src/vue/index.js +1 -1
- package/dist/src/vue/use-eve-agent.js +1 -1
- package/docs/agent-config.md +199 -222
- package/docs/channels/chat-sdk.mdx +60 -64
- package/docs/channels/custom.mdx +265 -280
- package/docs/channels/discord.mdx +176 -123
- package/docs/channels/eve.mdx +136 -204
- 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 -194
- 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 +205 -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 +17 -18
- 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 +100 -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 +47 -41
- 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/prepare-for-1-0.md +23 -1
- 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,9 +3,7 @@ title: "Remote Agents"
|
|
|
3
3
|
description: "Call another eve deployment as a subagent with defineRemoteAgent: the same tool call as a local subagent, with outbound auth and durable callbacks."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
The file lives under `agent/subagents/`, so its tool name is derived from the path. There's no `name` field.
|
|
6
|
+
A remote agent is a separately deployed eve agent that your agent calls as a subagent. Define one with `defineRemoteAgent` in a file under `agent/subagents/`. The tool name comes from the file path, so `agent/subagents/weather.ts` is the `weather` tool.
|
|
9
7
|
|
|
10
8
|
```ts title="agent/subagents/weather.ts"
|
|
11
9
|
import { defineRemoteAgent } from "eve";
|
|
@@ -20,93 +18,25 @@ export default defineRemoteAgent({
|
|
|
20
18
|
|
|
21
19
|
`defineRemoteAgent` accepts:
|
|
22
20
|
|
|
23
|
-
| Parameter | Type | Required | Default | Description
|
|
24
|
-
| ------------------ | --------------------------------------------- | -------- | ----------------- |
|
|
25
|
-
| `url` | `string \| (() => string \| Promise<string>)` | Yes | n/a | Base URL of the remote eve deployment.
|
|
26
|
-
| `description` | `string` | Yes | n/a |
|
|
27
|
-
| `auth` | `OutboundAuthFn` | No | none | Outbound auth
|
|
28
|
-
| `forwardPrincipal` | `boolean` | No | `false` |
|
|
29
|
-
| `headers` | `HeadersValue` | No | none |
|
|
30
|
-
| `path` | `string` | No | `/eve/v1/session` | Route appended to `url`
|
|
31
|
-
| `tool` | `boolean \| "deferred"` | No | `true` |
|
|
32
|
-
|
|
33
|
-
## Dynamic remote agents
|
|
34
|
-
|
|
35
|
-
Wrap the file in `defineDynamic` when the target or its availability depends on
|
|
36
|
-
the current session. The function returns `defineRemoteAgent(...)` to expose it or `null` to omit it:
|
|
37
|
-
|
|
38
|
-
```ts title="agent/subagents/weather.ts"
|
|
39
|
-
import { defineDynamic, defineRemoteAgent } from "eve";
|
|
40
|
-
|
|
41
|
-
export default defineDynamic((ctx) =>
|
|
42
|
-
ctx.session.auth.current?.attributes.region === "us"
|
|
43
|
-
? defineRemoteAgent({
|
|
44
|
-
description: "Answers weather questions for US customers.",
|
|
45
|
-
url: "https://us-weather-agent.example.com",
|
|
46
|
-
})
|
|
47
|
-
: null,
|
|
48
|
-
);
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
eve evaluates the function before each ordinary model call. `auth` and `headers` can close over
|
|
52
|
-
its context or memo results. They resolve before each outbound request; credentials are not
|
|
53
|
-
memo results and must not be stored in them.
|
|
54
|
-
|
|
55
|
-
```ts title="agent/subagents/finance.ts"
|
|
56
|
-
import { defineDynamic, defineRemoteAgent } from "eve";
|
|
57
|
-
import { mintFinanceToken } from "../lib/finance";
|
|
58
|
-
|
|
59
|
-
export default defineDynamic((ctx) => {
|
|
60
|
-
const tenant = ctx.session.auth.current?.attributes.tenant;
|
|
61
|
-
return typeof tenant === "string"
|
|
62
|
-
? defineRemoteAgent({
|
|
63
|
-
description: "Analyzes the tenant's financial data.",
|
|
64
|
-
url: "https://finance-agent.example.com",
|
|
65
|
-
auth: async () => ({
|
|
66
|
-
headers: { authorization: `Bearer ${await mintFinanceToken(tenant)}` },
|
|
67
|
-
}),
|
|
68
|
-
})
|
|
69
|
-
: null;
|
|
70
|
-
});
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
A child keeps the parent context and memo results used to select its remote configuration.
|
|
74
|
-
Later messages, answers, cancellation, session retirement, and stream reads use that original selection when
|
|
75
|
-
rebuilding transport credentials. Only saved memo results are available: a missing result or a
|
|
76
|
-
changed child name or URL fails before credentials are sent. `ctx.messages()` is unavailable
|
|
77
|
-
during this reconstruction, including when eve opens the child; keep conversation-based
|
|
78
|
-
selection inside a memo. This does not change the per-message caller identity described in
|
|
79
|
-
[Forwarding the caller identity](#forwarding-the-caller-identity). See
|
|
80
|
-
[Dynamic capabilities](./dynamic-capabilities#dynamic-subagents) for the memo rules.
|
|
81
|
-
|
|
82
|
-
## Runtime URLs
|
|
83
|
-
|
|
84
|
-
A string `url` is read at compile time. Use a function when an environment variable
|
|
85
|
-
supplies the URL only at runtime. eve invokes it when resolving the runtime agent graph;
|
|
86
|
-
it can return a string or a promise:
|
|
87
|
-
|
|
88
|
-
```ts title="agent/subagents/weather.ts"
|
|
89
|
-
import { defineRemoteAgent } from "eve";
|
|
90
|
-
|
|
91
|
-
export default defineRemoteAgent({
|
|
92
|
-
url: () => process.env.WEATHER_AGENT_URL ?? "https://weather-agent.example.com",
|
|
93
|
-
description: "Answers weather, temperature, forecast, wind, rain, and snow questions.",
|
|
94
|
-
});
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
The resolved `url` must be a non-empty string. Use `defineDynamic` when the current
|
|
98
|
-
session determines which agent is exposed or whether it is available.
|
|
99
|
-
`auth` and `headers` remain lazy callbacks resolved per request.
|
|
21
|
+
| Parameter | Type | Required | Default | Description |
|
|
22
|
+
| ------------------ | --------------------------------------------- | -------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
23
|
+
| `url` | `string \| (() => string \| Promise<string>)` | Yes | n/a | Base URL of the remote eve deployment. Pass a function to [read it at runtime](#runtime-urls). |
|
|
24
|
+
| `description` | `string` | Yes | n/a | What the parent model reads to decide when to delegate. |
|
|
25
|
+
| `auth` | `OutboundAuthFn` | No | none | Outbound auth from `eve/agents/auth`. |
|
|
26
|
+
| `forwardPrincipal` | `boolean` | No | `false` | Send the calling turn's user identity to the remote deployment. See [Forwarding the caller identity](#forwarding-the-caller-identity). |
|
|
27
|
+
| `headers` | `HeadersValue` | No | none | Request headers, static or resolved for each request. |
|
|
28
|
+
| `path` | `string` | No | `/eve/v1/session` | Route appended to `url` to create the remote session. |
|
|
29
|
+
| `tool` | `boolean \| "deferred"` | No | `true` | `false` lets only authored workflow tools call it, through `ctx.agent()`. `"deferred"` keeps it out of the tool list but findable with `eve__search` and callable with `eve__tool`. |
|
|
100
30
|
|
|
101
31
|
## Calling a remote agent
|
|
102
32
|
|
|
103
|
-
|
|
33
|
+
The model calls a remote agent like a local subagent, with a `message` and an optional `taskId`. Put the full task and context in the message, because the remote agent never sees the parent's conversation.
|
|
104
34
|
|
|
105
|
-
|
|
35
|
+
A workflow tool calls the remote agent by its file name through `ctx.agent(name)`. For structured output, pass `outputSchema` to `send()` and read the value from the response's `data`. See [Delegate work: `ctx.agent`](../tools/workflows#delegate-work-ctxagent).
|
|
106
36
|
|
|
107
37
|
## Outbound auth
|
|
108
38
|
|
|
109
|
-
Use `vercelOidc()` from `eve/agents/auth` when one Vercel-deployed eve agent calls another, as
|
|
39
|
+
Use `vercelOidc()` from `eve/agents/auth` when one Vercel-deployed eve agent calls another, as in the first example.
|
|
110
40
|
|
|
111
41
|
For calls between different Vercel projects, allow the calling project on the receiving agent's eve channel:
|
|
112
42
|
|
|
@@ -131,13 +61,11 @@ export default eveChannel({
|
|
|
131
61
|
|
|
132
62
|
Set `teamSlug`, `projectName`, and `environment` to the calling deployment's Vercel OIDC subject. See [subject patterns and `vercelSubject(...)`](./auth-and-route-protection#subjects-patterns-and-vercelsubject) for other environments and wildcard matching.
|
|
133
63
|
|
|
134
|
-
If [Vercel Deployment Protection](https://vercel.com/docs/deployment-protection) is
|
|
64
|
+
If [Vercel Deployment Protection](https://vercel.com/docs/deployment-protection) is on for the receiving project, also allow the calling project and environment in [Trusted Sources](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/trusted-sources). Calls between projects must pass both the eve subject allowlist and Trusted Sources.
|
|
135
65
|
|
|
136
66
|
## Forwarding the caller identity
|
|
137
67
|
|
|
138
|
-
Outbound auth
|
|
139
|
-
|
|
140
|
-
Set `forwardPrincipal: true` to forward the dispatching turn's session principal across the hop:
|
|
68
|
+
Outbound auth proves which _deployment_ is calling, so by default the remote session runs as your app, not as the end user. Work that must run as the user on the remote, such as per-user [Vercel Connect](./auth-and-route-protection#tool-and-connection-auth), needs the user's identity. Set `forwardPrincipal: true` to send it:
|
|
141
69
|
|
|
142
70
|
```ts title="agent/subagents/site-ops.ts"
|
|
143
71
|
import { defineRemoteAgent } from "eve";
|
|
@@ -151,45 +79,89 @@ export default defineRemoteAgent({
|
|
|
151
79
|
});
|
|
152
80
|
```
|
|
153
81
|
|
|
154
|
-
|
|
82
|
+
- When eve creates the remote session, it sends the parent turn's `session.auth.current` and `session.auth.initiator`. When `initiator` is absent, the receiver uses `current` for both.
|
|
83
|
+
- A follow-up with `taskId` sends the follow-up call's `session.auth.current`. The remote session keeps its original `auth.initiator`.
|
|
84
|
+
- eve sends only identity metadata, never tokens or credentials. The receiver gets per-user credentials through its own connections.
|
|
85
|
+
|
|
86
|
+
Each turn runs as its own caller, even in a child session that persists. If Alice starts the child and Bob continues it with its `taskId`, the follow-up runs with Bob as `auth.current`. If the parent turn's auth is `null`, a local child clears `auth.current`, and a remote child runs as the verified calling deployment. Neither runs as Alice. A later turn can use only the OAuth grant of its own `auth.current` user.
|
|
155
87
|
|
|
156
|
-
|
|
88
|
+
Forwarding doesn't make a child session private to one caller: its conversation history, tool outputs, and other state persist. If they must not be visible across users, give each user a separate child session or check ownership in your application.
|
|
157
89
|
|
|
158
|
-
|
|
90
|
+
The receiver must opt in. It names trusted deployments with `eveChannel({ trustedForwarders })` and can limit which users each one may assert (see [Auth & route protection](./auth-and-route-protection#accepting-forwarded-identity-from-another-deployment)). A refused deployment or identity gets a 403. The same trust decision covers the parent session link and, with forwarding on, trace-content limits.
|
|
159
91
|
|
|
160
|
-
|
|
92
|
+
## Dynamic remote agents
|
|
93
|
+
|
|
94
|
+
Wrap the definition in `defineDynamic` when the target or whether to offer it depends on the session. Return `defineRemoteAgent(...)` to offer it or `null` to hide it:
|
|
95
|
+
|
|
96
|
+
```ts title="agent/subagents/weather.ts"
|
|
97
|
+
import { defineDynamic, defineRemoteAgent } from "eve";
|
|
98
|
+
|
|
99
|
+
export default defineDynamic((ctx) =>
|
|
100
|
+
ctx.session.auth.current?.attributes.region === "us"
|
|
101
|
+
? defineRemoteAgent({
|
|
102
|
+
description: "Answers weather questions for US customers.",
|
|
103
|
+
url: "https://us-weather-agent.example.com",
|
|
104
|
+
})
|
|
105
|
+
: null,
|
|
106
|
+
);
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
eve runs the function before each ordinary model call. `auth` and `headers` can use its context or memo results, and they run before each outbound request. Don't store credentials in memo results.
|
|
110
|
+
|
|
111
|
+
```ts title="agent/subagents/finance.ts"
|
|
112
|
+
import { defineDynamic, defineRemoteAgent } from "eve";
|
|
113
|
+
import { mintFinanceToken } from "../lib/finance";
|
|
114
|
+
|
|
115
|
+
export default defineDynamic((ctx) => {
|
|
116
|
+
const tenant = ctx.session.auth.current?.attributes.tenant;
|
|
117
|
+
return typeof tenant === "string"
|
|
118
|
+
? defineRemoteAgent({
|
|
119
|
+
description: "Analyzes the tenant's financial data.",
|
|
120
|
+
url: "https://finance-agent.example.com",
|
|
121
|
+
auth: async () => ({
|
|
122
|
+
headers: { authorization: `Bearer ${await mintFinanceToken(tenant)}` },
|
|
123
|
+
}),
|
|
124
|
+
})
|
|
125
|
+
: null;
|
|
126
|
+
});
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
A child keeps the parent context and memo results that chose its configuration:
|
|
130
|
+
|
|
131
|
+
- Later messages, answers, cancellation, ending the session, and stream reads rebuild the credentials from that original context, not from a newer caller.
|
|
132
|
+
- If a memo result is missing, or the child's name or URL changed, the request fails before eve sends credentials.
|
|
133
|
+
- `ctx.messages()` is unavailable during this rebuild, including when eve opens the child, so keep decisions based on the conversation inside a memo.
|
|
134
|
+
|
|
135
|
+
Each message still runs as its own caller, as described in [Forwarding the caller identity](#forwarding-the-caller-identity). See [Dynamic capabilities](./dynamic-capabilities#memo-rules) for the memo rules.
|
|
136
|
+
|
|
137
|
+
## Runtime URLs
|
|
138
|
+
|
|
139
|
+
eve reads a string `url` at build time. When an environment variable supplies the URL only at runtime, pass a function. It returns a string or a promise, and eve calls it when it resolves the runtime agent graph:
|
|
140
|
+
|
|
141
|
+
```ts title="agent/subagents/weather.ts"
|
|
142
|
+
import { defineRemoteAgent } from "eve";
|
|
143
|
+
|
|
144
|
+
export default defineRemoteAgent({
|
|
145
|
+
url: () => process.env.WEATHER_AGENT_URL ?? "https://weather-agent.example.com",
|
|
146
|
+
description: "Answers weather, temperature, forecast, wind, rain, and snow questions.",
|
|
147
|
+
});
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
The resolved `url` must be a non-empty string. To choose which agent to offer, or whether to offer one, from the current session, use [`defineDynamic`](#dynamic-remote-agents).
|
|
161
151
|
|
|
162
152
|
## Trace propagation
|
|
163
153
|
|
|
164
|
-
A remote child starts its own trace with a root `invoke_agent` span. When caller
|
|
165
|
-
trace context is available, the first turn links to the dispatch span with
|
|
166
|
-
`eve.link.type=agent.dispatch`. The receiving deployment applies its sampler.
|
|
167
|
-
Later turns start new traces without the original dispatch link. The first turn
|
|
168
|
-
of a local child can use the remote agent's trace as a nested span.
|
|
154
|
+
A remote child starts its own trace with a root `invoke_agent` span, sampled by the receiving deployment. When the caller's trace context is available, the child's first turn links to the calling span with `eve.link.type=agent.dispatch`. Later turns start new traces without that link. The remote agent's local children can nest their first turn under its trace.
|
|
169
155
|
|
|
170
|
-
Use `gen_ai.conversation.id` to find all turns and child sessions for one
|
|
171
|
-
conversation. The child has its own session ID, message history, and agent
|
|
172
|
-
state. Trace context identifies related work. It does not give authorization.
|
|
173
|
-
See [OpenTelemetry](../observability/otel#trace-topology) for the trace structure.
|
|
156
|
+
Use `gen_ai.conversation.id` to find all turns and child sessions for one conversation. Trace context only links related work; it doesn't authorize anything. See [OpenTelemetry](../observability/otel#trace-topology) for the trace structure.
|
|
174
157
|
|
|
175
|
-
|
|
176
|
-
when `trustedForwarders` approves the authenticated caller; otherwise, trace
|
|
177
|
-
correlation continues without it.
|
|
158
|
+
The receiver accepts the parent session link only when `trustedForwarders` approves the caller. Otherwise, traces still correlate without it.
|
|
178
159
|
|
|
179
|
-
On Vercel, a remote agent
|
|
180
|
-
remote session's ID as `vercel.session_id`, so the receiving project groups
|
|
181
|
-
them as their own session. `gen_ai.conversation.id` still names the sender's
|
|
182
|
-
conversation, and the remote agent's `agent.parent_run.id` names the calling
|
|
183
|
-
session.
|
|
160
|
+
On Vercel, spans from a remote agent and its local subagents carry the remote session's ID as `vercel.session_id`. The receiving project groups them as their own session. `gen_ai.conversation.id` still names the sender's conversation, and `agent.parent_run.id` names the calling session.
|
|
184
161
|
|
|
185
162
|
## Preserving trace content
|
|
186
163
|
|
|
187
|
-
With `forwardPrincipal: true`, a sampled remote
|
|
188
|
-
audience and the maximum input and output content the next hop may record. eve
|
|
189
|
-
sends this policy as [W3C Baggage](https://www.w3.org/TR/baggage/).
|
|
190
|
-
|
|
191
|
-
The receiving deployment uses the policy only after it trusts the calling
|
|
192
|
-
deployment:
|
|
164
|
+
With `forwardPrincipal: true`, a sampled remote call forwards its audience and the most input and output content the next hop may record, as [W3C Baggage](https://www.w3.org/TR/baggage/). The receiver uses this policy only from a trusted caller:
|
|
193
165
|
|
|
194
166
|
```ts title="agent/channels/eve.ts"
|
|
195
167
|
import { eveChannel } from "eve/channels/eve";
|
|
@@ -202,105 +174,71 @@ export default eveChannel({
|
|
|
202
174
|
});
|
|
203
175
|
```
|
|
204
176
|
|
|
205
|
-
The request must include a callback and a valid sampled `traceparent
|
|
206
|
-
`trustedForwarders` is the authorization boundary. When the assertion is
|
|
207
|
-
accepted, the receiver uses the forwarded audience instead of reclassifying
|
|
208
|
-
the child session with its local channel.
|
|
177
|
+
The request must include a callback and a valid sampled `traceparent`; `trustedForwarders` is the authorization boundary. An accepted audience replaces the one the receiver's channel would assign.
|
|
209
178
|
|
|
210
|
-
The receiver combines the forwarded
|
|
211
|
-
hop may narrow content capture, but cannot restore inputs or outputs removed by
|
|
212
|
-
an earlier hop. Missing, malformed, unsampled, or untrusted assertions do not
|
|
213
|
-
widen capture and use metadata-only tracing.
|
|
179
|
+
The receiver combines the forwarded limit with its own trace policy. Each hop can capture less content but can't restore what an earlier hop removed. A missing, malformed, unsampled, or untrusted value falls back to metadata-only tracing.
|
|
214
180
|
|
|
215
181
|
## How remote dispatch and callbacks work
|
|
216
182
|
|
|
217
|
-
A remote subagent call runs a child session
|
|
183
|
+
A remote subagent call runs a child session on the remote deployment as a task:
|
|
218
184
|
|
|
219
|
-
1. The parent starts a
|
|
185
|
+
1. The parent starts a conversation session on the remote's `POST /eve/v1/session` and passes a callback URL.
|
|
220
186
|
2. The remote accepts the child and runs its turn while the task works.
|
|
221
|
-
3. The callback
|
|
187
|
+
3. The callback returns the child's reply, which becomes the task's result.
|
|
222
188
|
|
|
223
|
-
The
|
|
189
|
+
The parent stream shows the same `task.started`, `child.opened`, and `call.settled` events as local delegation.
|
|
224
190
|
|
|
225
|
-
|
|
191
|
+
The callback URL must use `http` or `https` and reach the parent at a public address. The remote refuses a callback host that is, or resolves to, a private, link-local, or reserved IP address, and a refused callback fails without retries. Loopback hosts such as `localhost` and `127.0.0.1` work only when the remote runs `eve dev` or `vercel dev`. A parent and remote on a private network can't exchange callbacks.
|
|
226
192
|
|
|
227
|
-
|
|
193
|
+
A callback URL carries only the message's callback capability, never the parent's deployment protection bypass secret. To let callbacks reach a parent behind Vercel Deployment Protection, configure Trusted Sources on the parent to admit the remote's project and environment.
|
|
228
194
|
|
|
229
|
-
|
|
195
|
+
On the remote deployment, set `EVE_CALLBACK_TRUSTED_ORIGINS` to a comma-separated list of parent HTTPS origins, such as `https://parent.example.com`. Each entry is an exact origin, or starts with a `*.` label as described below. The remote attaches its own short-lived Vercel OIDC token only to those origins and to its own deployment origins. An exact entry doesn't trust other ports or subdomains. Keep the remote's Vercel OIDC token available at runtime. Callbacks don't follow redirects.
|
|
230
196
|
|
|
231
|
-
|
|
197
|
+
Outside production, a parent's callback URL uses its generated deployment URL, which changes with every deployment. If you serve those deployments under a domain you control, trust them with a leading `*.` label, such as `https://*.preview.example.com`:
|
|
232
198
|
|
|
233
|
-
|
|
199
|
+
- The wildcard matches exactly one label: `parent-abc123.preview.example.com`, but not `preview.example.com` or `a.b.preview.example.com`.
|
|
200
|
+
- The port must still match.
|
|
201
|
+
- At least two labels must follow the wildcard, and an entry with a trailing dot is rejected.
|
|
202
|
+
- eve rejects `https://*.vercel.app`, because every Vercel deployment shares that domain. It doesn't detect other shared domains, such as `*.github.io`.
|
|
234
203
|
|
|
235
|
-
|
|
204
|
+
Each origin you add receives a bearer credential for the remote project's identity, not a token scoped to the callback. Until the token expires, that parent can replay it against any service, deployment protection rule, or federated cloud role that accepts the identity. List only parents you trust to act as the remote project, and use a wildcard only when you control every host under it.
|
|
236
205
|
|
|
237
|
-
|
|
206
|
+
When either side isn't on Vercel, make the parent's callback route reachable through your hosting policy. eve never forwards a deployment-wide credential to the remote.
|
|
238
207
|
|
|
239
|
-
|
|
208
|
+
Clients follow a remote child through the parent. [`session.agent(opened).stream()`](./client/streaming#follow-a-subagent) reads the `child.opened` event's `stream` path, a route on the parent deployment. The parent checks that the child belongs to that tool call, then relays the child's stream with the remote agent's `auth` and `headers`. A browser never calls the remote deployment or holds its credentials.
|
|
240
209
|
|
|
241
|
-
|
|
210
|
+
Cancelling the parent turn, or the task with `eve__task_cancel`, cancels the remote child's current turn. The child reports `turn.settled` with `outcome: "cancelled"` on its own stream. Each cancel resolves `headers` and `auth` again and uses the standard eve cancel route on `url`, even when `path` is customized. If the remote is older or unreachable, eve logs it, and the parent's cancel still succeeds.
|
|
242
211
|
|
|
243
|
-
|
|
244
|
-
answers with the version it serves. This release serves protocols 2 and 3. A protocol-3 parent
|
|
245
|
-
accepts a protocol-2 remote's results and failures, but cannot follow its live stream. It relays that
|
|
246
|
-
remote's approvals, questions, and sign-ins to the person it serves, as described below.
|
|
247
|
-
A protocol-3 remote returns results and failures to callers on protocol 2, but cannot relay
|
|
248
|
-
approvals, questions, or sign-ins to them: a turn that needs a person fails with upgrade guidance
|
|
249
|
-
instead of waiting on an unreachable prompt. Unsupported versions, including protocol 1 from
|
|
250
|
-
eve 0.66 through 0.68, fail at start with an error naming both versions.
|
|
212
|
+
When the workflow run that opened a remote child finishes, eve sends an authenticated request that ends the remote session and its descendants. An agent task's run finishes when the parent session ends. The request uses freshly resolved `headers` and `auth`. eve logs failures, so an unreachable remote can't block the parent from finishing.
|
|
251
213
|
|
|
252
|
-
|
|
253
|
-
before admission. After an explicit `409 REMOTE_AGENT_PROTOCOL_MISMATCH` rejection,
|
|
254
|
-
eve makes one request with that receiver's supported version and fresh credentials.
|
|
255
|
-
It does not negotiate after an accepted response, an unreadable receipt, a rejection
|
|
256
|
-
that names a session, or an unsupported version.
|
|
214
|
+
The parent names its remote agent protocol version when it creates the child, and the remote answers with the version it serves. eve serves protocols 2 and 3:
|
|
257
215
|
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
and
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
216
|
+
| Parent | Remote | Behavior |
|
|
217
|
+
| ------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
218
|
+
| 3 | 2 | Results and failures return, and approvals, questions, and sign-ins relay to the person. The parent can't follow the child's live stream. |
|
|
219
|
+
| 2 | 3 | Results and failures return. Approvals, questions, and sign-ins can't relay, so a turn that needs a person fails with upgrade guidance instead of waiting. |
|
|
220
|
+
|
|
221
|
+
Unsupported versions fail at start with an error naming both versions.
|
|
222
|
+
|
|
223
|
+
A receiver on an older protocol can reject the create request with `409 REMOTE_AGENT_PROTOCOL_MISMATCH` before it accepts the child. eve then sends one more request with that receiver's version and fresh credentials. eve doesn't try again after an accepted response, an unreadable receipt, a rejection that names a session, or an unsupported version.
|
|
224
|
+
|
|
225
|
+
With a protocol-2 child, the person answers relayed requests in the parent's session. The child still decides who may answer, so an answer its approval policy refuses leaves the approval open. The child reports when approvals and sign-ins end, but not questions or budget prompts. The parent closes those when the child accepts the answer. Cancelling the parent's call withdraws the relayed requests.
|
|
266
226
|
|
|
267
227
|
### Upgrading callers and remote agents
|
|
268
228
|
|
|
269
|
-
Upgrade callers before the remote agents they call, or both together
|
|
270
|
-
relays a protocol-2 remote agent's approvals, questions, and sign-ins, but a remote agent on this
|
|
271
|
-
release can't relay them to a protocol-2 caller.
|
|
229
|
+
Upgrade callers before the remote agents they call, or both together, because a protocol-3 remote can't relay approvals, questions, or sign-ins to a protocol-2 caller.
|
|
272
230
|
|
|
273
|
-
A remote child's callback goes to the parent's current production deployment, not
|
|
274
|
-
deployment that started the call; the parent's own sessions stay on the deployment that started
|
|
275
|
-
them. Every callback URL a parent gives a child names the protocol they agreed
|
|
276
|
-
(`eveRemoteProtocol`), and the parent reads a child's callbacks by that protocol. A URL that names
|
|
277
|
-
none comes from a parent run started before v27. When an earlier child's approval, question, or
|
|
278
|
-
sign-in for such a run reaches an upgraded deployment, the deployment passes it to that run as is,
|
|
279
|
-
so the run receives it as it did before the upgrade.
|
|
231
|
+
A remote child's callback goes to the parent's current production deployment, not the deployment that started the call. The parent's own sessions stay on the deployment that started them.
|
|
280
232
|
|
|
281
233
|
### Retries and acknowledgements
|
|
282
234
|
|
|
283
|
-
Each follow-up message and
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
it
|
|
288
|
-
|
|
289
|
-
A
|
|
290
|
-
fails the call with the remote's error. Terminal callback delivery runs as a durable step on the
|
|
291
|
-
underlying workflow engine (see [Execution model & durability](../concepts/execution-model-and-durability)).
|
|
292
|
-
A failed callback POST is rethrown so the engine retries it. A parent's callback route answers
|
|
293
|
-
`404` with `code: "CALLBACK_NOT_PENDING"` when nothing waits on the callback: the parent already
|
|
294
|
-
took the result, for example from a delivery whose acknowledgement was lost, or stopped waiting for
|
|
295
|
-
it. The child retries that answer for a few seconds, in case the parent hasn't yet registered the
|
|
296
|
-
reply it sent the token for, then logs it and keeps its session, rather than failing it.
|
|
297
|
-
|
|
298
|
-
If a remote accepts the create request but its response has an incompatible
|
|
299
|
-
protocol or an unreadable body, the work may have completed. eve stops workflow
|
|
300
|
-
retries and reports that uncertainty. A protocol mismatch includes the accepted
|
|
301
|
-
remote session ID so you can inspect the outcome before sending another request.
|
|
302
|
-
Upgrading the remote does not undo work that it already performed. An unsupported version, or a rejection of the single negotiated request,
|
|
303
|
-
remains a compatibility error.
|
|
235
|
+
Each follow-up message and set of answers sent to a protocol-3 child carries an `idempotencyKey`. If the child accepts a request but the parent never gets the reply, the child accepts the retry once and returns the original receipt. Protocol-2 children don't receive the key.
|
|
236
|
+
|
|
237
|
+
A failed start fails the call immediately. After a remote starts, a final failure callback fails the call with the remote's error. eve retries a failed final callback request (see [Execution model & durability](../concepts/execution-model-and-durability)).
|
|
238
|
+
|
|
239
|
+
A parent's callback route answers `404` with `code: "CALLBACK_NOT_PENDING"` when nothing waits on the callback. Either the parent already took the result, for example after a lost acknowledgement, or it stopped waiting. The child retries for a few seconds in case the parent hasn't registered the reply yet, then logs it and keeps its session.
|
|
240
|
+
|
|
241
|
+
If a remote accepts the create request but its response has an incompatible protocol or an unreadable body, the work may have finished. eve stops workflow retries and reports that the outcome is unknown. A protocol mismatch includes the accepted remote session ID, so you can check the outcome before you send another request. Upgrading the remote doesn't undo work it already did. An unsupported version, or a rejection of the one retried request, is a compatibility error.
|
|
304
242
|
|
|
305
243
|
## What to read next
|
|
306
244
|
|
|
@@ -3,9 +3,9 @@ title: "Self-Modification"
|
|
|
3
3
|
description: "Ask your agent to update its own authored files during local development, or let a deployed agent propose changes as draft pull requests."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
Self-modification lets you ask your agent to change its own instructions, tools, skills, or other files under `agent/`. When `eve dev` starts a local server, it mounts the bundled `eve/extensions/self-modification/local` extension, which delegates the source work to the `self-modification__agent` subagent. `eve remote connect --url <url>` doesn't add it to the server it connects to.
|
|
7
7
|
|
|
8
|
-
The
|
|
8
|
+
The local extension is not included in production builds. To let a deployed agent propose source changes, mount the separate [`eve/extensions/self-modification/remote`](#propose-changes-from-a-deployed-agent) extension.
|
|
9
9
|
|
|
10
10
|
```bash
|
|
11
11
|
eve dev
|
|
@@ -17,11 +17,11 @@ For example, ask the agent to add a reusable action:
|
|
|
17
17
|
Add a tool that converts temperatures between Celsius and Fahrenheit.
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
The
|
|
20
|
+
The subagent edits the authored files in your project, and `eve dev` reloads them. Review the diff and test the change as you would any other source change.
|
|
21
21
|
|
|
22
|
-
The subagent is offered only to sessions authenticated by [`localDev()`](./auth-and-route-protection#localdev) or by the Vercel development token the dev TUI sends for a linked project. Sessions authenticated as Slack users or
|
|
22
|
+
The subagent is offered only to sessions authenticated by [`localDev()`](./auth-and-route-protection#localdev) or by the Vercel development token the dev TUI sends for a linked project. Sessions authenticated any other way, such as Slack users or HTTP Basic operator credentials, don't see it, and the local mount has no `authorize` override.
|
|
23
23
|
|
|
24
|
-
A tunnel or reverse proxy
|
|
24
|
+
A tunnel or reverse proxy on the same machine can forward callers that `localDev()` accepts as the local developer. Those callers can use the subagent. Before exposing `eve dev` through a tunnel, require authentication at the tunnel or proxy, or remove `localDev()` from the exposed channel's auth chain. Another authenticator placed before `localDev()` doesn't help, because callers it skips still fall through to `localDev()`.
|
|
25
25
|
|
|
26
26
|
## Change the self-modification model
|
|
27
27
|
|
|
@@ -31,7 +31,7 @@ The subagent uses your agent's model by default. To give it a different model or
|
|
|
31
31
|
Switch the self-modification subagent to openai/gpt-6-sol with low reasoning.
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
-
|
|
34
|
+
This creates or edits `agent/extensions/self-modification/extension.ts`. You can also edit the file yourself; it accepts `model`, `reasoning`, and `local.enabled`.
|
|
35
35
|
|
|
36
36
|
```ts
|
|
37
37
|
// agent/extensions/self-modification/extension.ts
|
|
@@ -43,19 +43,13 @@ export default selfModification({
|
|
|
43
43
|
});
|
|
44
44
|
```
|
|
45
45
|
|
|
46
|
-
The
|
|
47
|
-
|
|
48
|
-
## Migrate a retired scaffold
|
|
49
|
-
|
|
50
|
-
The scaffold under `agent/subagents/self-modification/` is no longer supported. The disabled agent helper, including `eve/internal/self-modification/agent`, has been removed. Do not use the old `@eve/self-modification` compatibility package for new installations.
|
|
51
|
-
|
|
52
|
-
Preserve any authored changes, then remove the old scaffold directory. Run `eve add eve/self-modification` to create the supported local extension mount. Setup rejects the old directory rather than deleting it. The bundled local extension and the separate remote extension remain supported.
|
|
46
|
+
The local mount rejects a `deployed` option with an error; configure deployed source changes on a separate `eve/extensions/self-modification/remote` mount.
|
|
53
47
|
|
|
54
48
|
## Propose changes from a deployed agent
|
|
55
49
|
|
|
56
|
-
`eve/extensions/self-modification/remote`
|
|
50
|
+
`eve/extensions/self-modification/remote` adds a source-change subagent to a deployed agent. The subagent checks out your repository in a sandbox, edits the authored source, and opens a draft pull request against a target branch. It never changes the running deployment; changes take effect after you review, merge, and redeploy.
|
|
57
51
|
|
|
58
|
-
Mount it under its own namespace so it
|
|
52
|
+
Mount it under its own namespace so it doesn't replace the local extension:
|
|
59
53
|
|
|
60
54
|
```ts
|
|
61
55
|
// agent/extensions/self-modification-remote/extension.ts
|
|
@@ -84,17 +78,23 @@ export default selfModification({
|
|
|
84
78
|
| `credentials` | Required. An object with a `resolve({ capability, repository })` function that returns a GitHub token, or `{ pat: true }` to read `EVE_SELF_MODIFICATION_GITHUB_TOKEN` from the deployment environment. |
|
|
85
79
|
| `model`, `reasoning` | Optional model and reasoning level for the deployed subagent. It defaults to the parent agent's model. |
|
|
86
80
|
|
|
87
|
-
The deployed subagent is never offered during `eve dev`. It requires
|
|
81
|
+
The deployed subagent is never offered during `eve dev`. It requires Vercel, because Vercel Sandbox keeps the GitHub token out of the sandbox. eve applies the token only while it checks out or publishes, so sandbox commands can't read it. Builds succeed on any host. Outside Vercel, the subagent fails with an error naming this requirement when it opens its sandbox, so don't mount it in self-hosted deployments.
|
|
88
82
|
|
|
89
83
|
## Run without self-modification
|
|
90
84
|
|
|
91
|
-
Pass `--no-default-extensions`
|
|
85
|
+
Pass `--no-default-extensions` to stop `eve dev` from mounting its bundled development extensions:
|
|
92
86
|
|
|
93
87
|
```bash
|
|
94
88
|
eve dev --no-default-extensions
|
|
95
89
|
```
|
|
96
90
|
|
|
97
|
-
This disables
|
|
91
|
+
This disables every bundled default extension for that server, including self-modification. Extensions you mount under `agent/extensions/` still load.
|
|
92
|
+
|
|
93
|
+
## Troubleshooting
|
|
94
|
+
|
|
95
|
+
| What you see | What to do |
|
|
96
|
+
| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
97
|
+
| `The legacy agent/subagents/self-modification layout is no longer supported.` from setup | Keep any authored changes, remove `agent/subagents/self-modification/`, then run `eve add eve/self-modification` to mount the extension at `agent/extensions/self-modification/extension.ts`. |
|
|
98
98
|
|
|
99
99
|
## What to read next
|
|
100
100
|
|