eve 0.88.0 → 0.89.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/CHANGELOG.md +10 -21
  2. package/dist/src/channel/interaction-prompts.d.ts +0 -2
  3. package/dist/src/channel/interaction-prompts.js +1 -1
  4. package/dist/src/chunks/{use-eve-agent-BExXjBv6.js → use-eve-agent-Bbl4H5aA.js} +19 -2
  5. package/dist/src/chunks/{use-eve-agent-C0KHCyb9.js → use-eve-agent-CNpxgKEH.js} +19 -2
  6. package/dist/src/client/conversation.js +1 -1
  7. package/dist/src/client/transcript.d.ts +7 -4
  8. package/dist/src/client/transcript.js +1 -1
  9. package/dist/src/compiled/.vendor-stamp.json +3 -3
  10. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  11. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  12. package/dist/src/extensions/git/extension/extension.d.ts +12 -9
  13. package/dist/src/extensions/git/extension/extension.js +1 -1
  14. package/dist/src/extensions/git/extension/lib/gh-tool.d.ts +4 -12
  15. package/dist/src/extensions/git/extension/lib/gh-tool.js +1 -1
  16. package/dist/src/extensions/git/extension/lib/github-guidance.js +4 -4
  17. package/dist/src/extensions/git/extension/lib/github-shell-schema.d.ts +3 -5
  18. package/dist/src/extensions/git/extension/lib/github-shell-schema.js +1 -1
  19. package/dist/src/extensions/git/extension/lib/github-shell.d.ts +31 -21
  20. package/dist/src/extensions/git/extension/lib/github-shell.js +1 -1
  21. package/dist/src/extensions/git/extension/lib/signed-commit.js +1 -1
  22. package/dist/src/extensions/git/tools.d.ts +2 -10
  23. package/dist/src/instrumentation/content.js +1 -1
  24. package/dist/src/instrumentation/lifecycle.d.ts +5 -0
  25. package/dist/src/instrumentation/native-events.d.ts +4 -1
  26. package/dist/src/instrumentation/native-events.js +1 -1
  27. package/dist/src/instrumentation/principal-summary.d.ts +2 -0
  28. package/dist/src/instrumentation/principal-summary.js +1 -1
  29. package/dist/src/instrumentation/runtime.js +1 -1
  30. package/dist/src/instrumentation/session-context.js +1 -1
  31. package/dist/src/internal/application/stamped-package-version.js +1 -1
  32. package/dist/src/internal/invocation/agent-invocation.d.ts +2 -0
  33. package/dist/src/internal/invocation/workflow-execution.js +1 -1
  34. package/dist/src/protocol/session-events/families/delivery.d.ts +3 -2
  35. package/dist/src/protocol/session-projection/reader.d.ts +3 -1
  36. package/dist/src/protocol/session-projection/reader.js +1 -1
  37. package/dist/src/public/channels/mcp.js +1 -1
  38. package/dist/src/public/channels/slack/request-cards.js +2 -2
  39. package/dist/src/runtime/subagents/workflow.js +1 -1
  40. package/dist/src/setup/scaffold/create/project.js +1 -1
  41. package/dist/src/shared/session-history.d.ts +4 -2
  42. package/dist/src/shared/session-history.js +1 -1
  43. package/dist/src/svelte/index.js +1 -1
  44. package/dist/src/svelte/use-eve-agent.js +1 -1
  45. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  46. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  47. package/dist/src/tracing/eve/agent-approval-instrumentation.js +1 -1
  48. package/dist/src/tracing/eve/session.js +1 -1
  49. package/dist/src/vue/index.js +1 -1
  50. package/dist/src/vue/use-eve-agent.js +1 -1
  51. package/docs/channels/eve.mdx +1 -1
  52. package/docs/channels/mcp.mdx +1 -1
  53. package/docs/code-extension.mdx +17 -60
  54. package/docs/concepts/execution-model-and-durability.mdx +1 -1
  55. package/docs/concepts/sessions-runs-and-streaming.md +3 -1
  56. package/docs/guides/client/streaming.mdx +1 -1
  57. package/docs/guides/frontend/use-eve-agent.mdx +1 -1
  58. package/docs/guides/instrumentation/instrumentation.mdx +1 -1
  59. package/docs/tools/human-in-the-loop.md +2 -0
  60. package/package.json +3 -3
@@ -98,62 +98,22 @@ export default git({});
98
98
 
99
99
  Configure `github` to broker GitHub access through Connect instead. The extension then adds the authenticated `git__gh` tool, tells the agent to use it for every authenticated GitHub operation, and switches `git__pr` to `gh-signed-commit` for repositories that require verified signatures.
100
100
 
101
- | Option | Required | Effect |
102
- | ---------------------- | ------------- | -------------------------------------------------------------------------------------------- |
103
- | `github.connector` | With `github` | Connector that mints a GitHub token |
104
- | `github.broker` | With `github` | `broker(sandbox, rules)` callback that installs, then removes, the GitHub credential rules |
105
- | `github.authorize` | With `github` | `authorize({ auth, repository, token })` decides whether each `gh` tool invocation may run |
106
- | `github.principalType` | No | `"app"` (default) for GitHub App installation tokens, or `"user"` for the caller's own token |
107
- | `github.attribution` | No | `attribution(ctx)` returns the current turn's `{ name, email }` co-author, or `null` |
101
+ | Option | Required | Effect |
102
+ | ---------------------- | ------------- | ------------------------------------------------------------------------------------------ |
103
+ | `github.connector` | With `github` | Connector that mints a GitHub token |
104
+ | `github.broker` | With `github` | `broker(sandbox, rules)` callback that installs, then removes, the GitHub credential rules |
105
+ | `github.principalType` | With `github` | `"app"` for GitHub App installation tokens, or `"user"` for the caller's own token |
106
+ | `github.authorize` | With `github` | `authorize(request)` returns `true` to let a `gh` call run |
107
+ | `github.attribution` | No | `attribution(ctx)` returns the current turn's `{ name, email }` co-author, or `null` |
108
108
 
109
- Each `gh` invocation declares exactly one `owner/name` repository, and every explicit command target must match it. By default the tool requests a GitHub App installation token for that owner's installation, scoped to that one repository; with `github.principalType` set to `"user"` it resolves the caller's own token instead. The sandbox process receives a placeholder `GH_TOKEN`, and the firewall exchanges it on matching GitHub requests. Your `github.broker` callback receives the header-transform rules for the command, then `null` to remove the lease. The callback must preserve your other network rules. GitHub authentication has no command-delivery option.
109
+ Each `gh` call runs one `gh`, `git`, or `gh-signed-commit` command. The sandbox process receives a placeholder `GH_TOKEN`, and the firewall exchanges it on matching GitHub requests. Your `github.broker` callback receives the header-transform rules for the command, then `null` to remove the lease. The callback must preserve your other network rules. GitHub authentication has no command-delivery option.
110
110
 
111
- `github.authorize` is the agent's only repository access control, so it is required: a command runs only when it returns `true`. It runs during each `gh` tool execution, not when the session starts. The order is: validate the command and repository, mint the token, await `authorize({ auth, repository, token })`, install the credential lease, then run the command. `auth` is the session's current caller at tool invocation, or `null`. Returning `false` stops execution before the lease is installed or the command runs, so the token never reaches the sandbox or GitHub. The decision applies to that invocation only; it is neither cached for the session nor repeated for each GitHub API request.
111
+ ### Control access with `authorize`
112
112
 
113
- The simplest policy limits the agent to one organization. Compare owners case-insensitively, as GitHub does:
113
+ `github.authorize` is the agent's only access control: a command runs only when it returns `true`, and the token never reaches the sandbox otherwise. It runs before every `gh` call with the parsed `argv`, the caller's `auth`, the `repository` the call declared (or `null`), and the minted `token`. What the token reaches depends on `principalType`:
114
114
 
115
- ```ts title="agent/extensions/git.ts"
116
- import git from "eve/extensions/git";
117
-
118
- import { brokerGitHubLease } from "../lib/github";
119
-
120
- export default git({
121
- github: {
122
- connector: "github/my-agent",
123
- broker: brokerGitHubLease,
124
- authorize: ({ repository }) => repository.toLowerCase().startsWith("acme/"),
125
- },
126
- });
127
- ```
128
-
129
- `authorize` can also use the token to check the caller, for example their collaborator status (allowed commands still use the app token's permissions, not the collaborator's):
130
-
131
- ```ts title="agent/extensions/git.ts"
132
- import git from "eve/extensions/git";
133
-
134
- import { brokerGitHubLease } from "../lib/github";
135
-
136
- export default git({
137
- github: {
138
- connector: "github/my-agent",
139
- broker: brokerGitHubLease,
140
- // GitHub channel sessions carry the commenter's login as `auth.subject`.
141
- async authorize({ auth, repository, token }) {
142
- if (!repository.toLowerCase().startsWith("acme/")) return false;
143
- if (auth?.authenticator !== "github-webhook" || !auth.subject) return false;
144
- const response = await fetch(
145
- `https://api.github.com/repos/${repository}/collaborators/${auth.subject}`,
146
- { headers: { authorization: `Bearer ${token}` } },
147
- );
148
- return response.status === 204;
149
- },
150
- },
151
- });
152
- ```
153
-
154
- ### Run commands as the caller
155
-
156
- By default each `gh` invocation mints a GitHub App installation token, so commands run with the installation's permissions. Set `github.principalType` to `"user"` to run them with the caller's own GitHub permissions instead, as `connect({ connector, principalType: "user" })` does for connections:
115
+ - **`"app"`**: a GitHub App installation token for the declared repository, or for the whole installation when the call declares only an owner. `authorize` also receives that `owner`.
116
+ - **`"user"`**: the caller's own token, which reaches whatever the caller can on GitHub. eve signs the caller in when needed and again when GitHub rejects the token. `authorize` receives no `owner`, because the token is not scoped to one. `repository` is only what the model declared, and nothing ties it to the command, so it is a hint, not a boundary. Gate user-mode calls on `auth` instead, for example `({ auth }) => auth !== null`.
157
117
 
158
118
  ```ts title="agent/extensions/git.ts"
159
119
  import git from "eve/extensions/git";
@@ -164,16 +124,12 @@ export default git({
164
124
  github: {
165
125
  connector: "github/my-agent",
166
126
  broker: brokerGitHubLease,
167
- authorize: ({ repository }) => repository.toLowerCase().startsWith("acme/"),
168
- principalType: "user",
127
+ principalType: "app",
128
+ authorize: ({ owner }) => owner.toLowerCase() === "acme",
169
129
  },
170
130
  });
171
131
  ```
172
132
 
173
- The tool resolves the caller's token from `github.connector` through `ctx.getToken`. When the caller has no grant, eve signs them in and re-runs the call. The token request carries no repository details, so one grant covers every repository and later commands resolve tokens without another sign-in. When GitHub rejects the token (`HTTP 401`, `Bad credentials`, `Authentication failed`, or a `gh-signed-commit` `failed: 401`), the tool calls `ctx.requireAuth`, which evicts the token and signs the caller in again.
174
-
175
- A user token carries the caller's GitHub permissions across every account where the GitHub App is installed, not only the declared repository. The tool description and GitHub instructions tell the model that access is limited to what the caller can reach. `github.authorize` still runs before every command, with the caller's token, and remains the agent's repository policy.
176
-
177
133
  ### Credit the person behind a turn
178
134
 
179
135
  Commits made by the `gh` tool are authored by the GitHub App. Return a verified user mapping from
@@ -193,7 +149,8 @@ export default git({
193
149
  github: {
194
150
  connector: "github/my-agent",
195
151
  broker: brokerGitHubLease,
196
- authorize: ({ repository }) => repository.toLowerCase().startsWith("acme/"),
152
+ principalType: "app",
153
+ authorize: ({ owner }) => owner.toLowerCase() === "acme",
197
154
  attribution: (ctx) => coAuthorFor(ctx.session.auth.current),
198
155
  },
199
156
  });
@@ -223,7 +180,7 @@ directory, `agent/extensions/code/extension.ts`.
223
180
 
224
181
  For a custom GitHub command tool, `eve/extensions/git/sandbox` exports
225
182
  `executeGitHubShell(input, config, dependencies)` and `githubShellApproval(input)`.
226
- The execution helper enforces repository and command constraints and brokers a
183
+ The execution helper parses the command, calls `authorize`, and brokers a
227
184
  credential lease; dependencies supply the session ID and sandbox access. Reuse
228
185
  `githubShellApproval` to reject invalid command inputs through the approval
229
186
  policy rather than bypassing those constraints.
@@ -121,7 +121,7 @@ export default defineDynamic(async (ctx) => {
121
121
 
122
122
  The memo runs before the replacement's first model call, and the instruction enters the replacement's durable history once, ahead of the new message. In a session that replaced no other, `ctx.session.predecessor` is undefined and the instruction contributes nothing.
123
123
 
124
- `transcriptOf()` keeps the history each consumed delivery imported, the text of each consumed delivery, and each completed reply part, oldest first, as `{ role, text }` messages. Reasoning, narration, tool calls and results, attachments, interactions, and interrupted output are left out. A clear in the stranded session starts the transcript over, so text the user cleared is never returned. `sessions.attach()` also converts older session history to v27 events. That conversion reads from the beginning to reconstruct the conversation, even when `startIndex` requests a later position. `maxMessages` keeps only the newest messages in the resulting transcript.
124
+ `transcriptOf()` keeps the history each consumed delivery imported, the text of each consumed delivery, and each completed reply part, oldest first, as `{ role, text }` messages. Reasoning, narration, tool calls and results, attachments, interactions, and interrupted output are left out. Only the session's current conversation is kept: a clear in the stranded session starts the transcript over, so text the user cleared is never returned. `sessions.attach()` also converts older session history to v27 events. That conversion reads from the beginning to reconstruct the conversation, even when `startIndex` requests a later position. `maxMessages` keeps only the newest messages in the resulting transcript.
125
125
 
126
126
  The read and the prompt are yours to bound:
127
127
 
@@ -106,6 +106,8 @@ Facts are grouped into families. Lifecycle facts introduce, update, or settle an
106
106
  | `context` | `context.started`, `context.settled` | A context change: `kind` `"compaction"` or `"clear"`. |
107
107
  | `usage` | `usage.recorded` | Model spend, owned by the run, call, or context change that spent it. |
108
108
 
109
+ The conversation is a chain of turns. Each `turn.started` names the turn it `follows`, the one whose conversation it continues, or `null` for a first turn. A completed `context.settled` can change the conversation with `selects`: `null` empties it, as a clear does, and `{ turnId }` makes that earlier turn its newest, leaving out the turns after it. The next turn then follows the selected one. Either can name any earlier turn, so read the conversation with `conversation(view)` instead of assuming it holds every turn in order.
110
+
109
111
  Progress records are `content.delta` (a text or reasoning delta for a `partId`), `call.input` (a raw tool-input delta for a `callId`), and `call.progress` (a preliminary output snapshot for a `callId`).
110
112
 
111
113
  Call labels use `capability.label` before execution, `call.progress.data.label` for a progress
@@ -132,7 +134,7 @@ Within stream version 27, a later minor release can add:
132
134
  - fact types that only add information: a new family, or an update to a row such as `model.retried`, never the only way an entity opens or ends;
133
135
  - progress record types;
134
136
  - optional fields;
135
- - outcomes, interaction kinds, displays, and option styles.
137
+ - outcomes, interaction kinds, context-change kinds, displays, and option styles.
136
138
 
137
139
  It never removes or renames a fact or field, changes what a fact means or which role it plays in its entity's lifecycle, or adds a required field. Anything else is a new stream version, which readers refuse.
138
140
 
@@ -24,7 +24,7 @@ for await (const event of delivery.stream()) {
24
24
 
25
25
  The cancellation delivery settles when the command is applied, including a no-op for a turn that already ended. Continue reading the original message's delivery to observe its outcome and advance its cursor. A live idle session also accepts cancellation; it does not return a separate `no_active_turn` result.
26
26
 
27
- Between turns, `session.compact()` queues context compaction without sending model input. `session.clear()` removes model-message history while retaining the session and its durable resources. Await their deliveries before sending another turn:
27
+ Between turns, `session.compact()` queues context compaction without sending model input. `session.clear()` removes model-message history while retaining the session and its durable resources. Client `messages` and `transcriptOf()` then leave out everything before the clear. Await their deliveries before sending another turn:
28
28
 
29
29
  ```ts
30
30
  const compaction = await session.compact();
@@ -11,7 +11,7 @@ React, [Vue](./use-eve-agent-vue), and [Svelte](./use-eve-agent-svelte) share th
11
11
 
12
12
  | Field | What it is |
13
13
  | ------------------ | ------------------------------------------------------------------------------ |
14
- | `messages` | Messages to render, including your submitted messages before eve confirms them |
14
+ | `messages` | The current conversation, and your submitted messages before eve confirms them |
15
15
  | `status` | Outstanding work: `"idle"`, `"busy"`, or `"resuming"`. See [Status](#status) |
16
16
  | `error` | The latest session creation, stream, resume, or turn failure |
17
17
  | `view` | Immutable session snapshot. Query it with functions from `eve/events` |
@@ -165,7 +165,7 @@ upserting records across replays.
165
165
  | Model run | `model.started`, `model.retried`, `model.settled` | Each attempt of a model run. `model.retried` ends a failed attempt before another try; `model.settled.outcome` is `completed`, `failed`, `interrupted`, `abandoned`, or `cancelled` when the turn was cancelled. |
166
166
  | Provider call | `model.call.started`, `model.call.settled` | An individual provider call; one model attempt can make several. Settlement has `outcome: "completed"` or `"failed"`; completion carries usage, finish reason, and optional `providerMetadata`. |
167
167
  | Call | `call.requested`, `call.settled` | A tool, skill, or agent call, including direct `invokeTool` calls. `capability` identifies its kind and name. Settlement carries `completed`, `failed`, `rejected`, `interrupted`, or `abandoned`. |
168
- | User input | `interaction.opened`, `interaction.settled` | A question, approval, or budget prompt, keyed by `interactionId`. Settlement includes the interaction's `outcome` and, when recorded, its `answer`. |
168
+ | User input | `interaction.opened`, `interaction.settled` | A question, approval, or budget prompt, keyed by `interactionId`. Settlement includes the interaction's `outcome`, `responder` (who decided it), and, when recorded, its `answer`. |
169
169
  | Memory operation | `memory.operation.started`, `memory.operation.settled` | A memory search or write, with operation name, phase, and slot. Settlement has `outcome: "completed"` or `"failed"`. |
170
170
 
171
171
  A delivery that pauses for a person settles `awaiting-input`; resumed work belongs to the answer's delivery. OTel attributes a turn to a delivery only when exactly one delivery was consumed. Event `scope` includes session and run coordinates; `turnId` can be absent for compaction or direct calls. Treat `idempotencyKey` as opaque.
@@ -266,6 +266,8 @@ A message from the parent agent to a subagent never answers the subagent's tool
266
266
 
267
267
  Approval is consent only. An approved tool call runs with the requesting user's identity, connections, and credentials, including its policy recheck. The approver's access is never lent to the call. Subsequent tool calls in the turn also stay with the original owner.
268
268
 
269
+ For auditing, traces record both people: the turn span's `agent.principal.current.*` attributes name the requester, and the approval span's `agent.approval.responder.type` and `agent.approval.responder.id` name who approved or denied the call. An approved call's tool span also records its approver as `agent.tool.approver.type` and `agent.tool.approver.id`, since the tool can act on the approver's behalf. All of these ids follow one rule: they are recorded only when the trace policy records both inputs and outputs and the conversation is public or running in development. Otherwise only the type is recorded.
270
+
269
271
  A `defineTool` tool can still act on the approver's behalf when it chooses to. While an approved `defineTool` call runs, `ctx.approval.responder` is the principal who approved it, and `ctx.approval.responder.getToken(provider)` resolves that person's token for an inline provider, as `ctx.getToken(provider)` does for the requester. `ctx.session.auth.current` stays the requester. `ctx.approval` is absent for calls that needed no approval, and workflow tools don't receive it. `ctx.approval.responder.getToken(provider)` never starts a sign-in: when the approver has no token, it throws a `ConnectionAuthorizationFailedError` with `reason: "approver_authorization_required"`.
270
272
 
271
273
  ```ts
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "eve",
3
- "version": "0.88.0",
3
+ "version": "0.89.0",
4
4
  "private": false,
5
5
  "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
6
6
  "keywords": [
@@ -598,7 +598,7 @@
598
598
  },
599
599
  "dependencies": {
600
600
  "nitro": "3.0.260903-beta",
601
- "undici": "8.10.2"
601
+ "undici": "8.12.3"
602
602
  },
603
603
  "devDependencies": {
604
604
  "@agentclientprotocol/sdk": "1.3.0",
@@ -631,7 +631,7 @@
631
631
  "@types/json-schema": "7.0.15",
632
632
  "@types/react": "19.2.15",
633
633
  "@types/react-test-renderer": "19.1.0",
634
- "@vercel/agent-runs": "0.0.3",
634
+ "@vercel/agent-runs": "0.0.4",
635
635
  "@vercel/blob": "2.8.0",
636
636
  "@vercel/connect": "2.5.2",
637
637
  "@vercel/detect-agent": "1.2.3",