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
|
@@ -5,10 +5,8 @@ description: "Secure your agent's HTTP routes with an ordered auth walk, verifie
|
|
|
5
5
|
|
|
6
6
|
eve has two independent auth systems:
|
|
7
7
|
|
|
8
|
-
- **Route auth** (inbound) decides who can reach your agent's HTTP routes. It runs at the channel layer,
|
|
9
|
-
- **Tool and connection auth** (outbound)
|
|
10
|
-
|
|
11
|
-
Start with route auth.
|
|
8
|
+
- **Route auth** (inbound) decides who can reach your agent's HTTP routes. It runs at the channel layer, before any model work.
|
|
9
|
+
- **Tool and connection auth** (outbound) signs your agent in to an external service that a tool or connection calls, like an OAuth MCP server.
|
|
12
10
|
|
|
13
11
|
## Route auth
|
|
14
12
|
|
|
@@ -19,9 +17,9 @@ The route-auth policy lives on the HTTP channel factory (`agent/channels/eve.ts`
|
|
|
19
17
|
- `POST /eve/v1/session/:sessionId/{cancel,compact,clear,end}`
|
|
20
18
|
- `GET /eve/v1/session/:sessionId/stream`
|
|
21
19
|
|
|
22
|
-
|
|
20
|
+
eve fails closed: production traffic is rejected unless an authenticator accepts it, and anonymous access requires an explicit `none()`.
|
|
23
21
|
|
|
24
|
-
The health route created by `eveChannel()` is public and skips the walk
|
|
22
|
+
The health route created by `eveChannel()` is public and skips the walk, so load balancers and uptime monitors can probe it without credentials. Replacing `agent/channels/eve.ts` with a custom `defineChannel(...)` or disabling that slot also replaces or removes the health route.
|
|
25
23
|
|
|
26
24
|
```ts title="agent/channels/eve.ts"
|
|
27
25
|
import { eveChannel } from "eve/channels/eve";
|
|
@@ -32,17 +30,25 @@ export default eveChannel({
|
|
|
32
30
|
});
|
|
33
31
|
```
|
|
34
32
|
|
|
35
|
-
`vercelOidc()` is a convenience for Vercel-hosted agents and Vercel-to-Vercel callers, not a requirement. If your app already has users, sessions, API keys, or an identity provider, put
|
|
33
|
+
`vercelOidc()` is a convenience for Vercel-hosted agents and Vercel-to-Vercel callers, not a requirement. If your app already has users, sessions, API keys, or an identity provider, put a custom `AuthFn` for it in the `auth` walk instead.
|
|
36
34
|
|
|
37
35
|
## The ordered auth walk
|
|
38
36
|
|
|
39
|
-
`auth` takes a single `AuthFn` or an array that eve walks in order. Each entry has three
|
|
37
|
+
`auth` takes a single `AuthFn` or an array that eve walks in order. Each entry has one of three outcomes:
|
|
38
|
+
|
|
39
|
+
| Entry | Result |
|
|
40
|
+
| ---------------------------- | -------------------------------------- |
|
|
41
|
+
| Returns `SessionAuthContext` | Accepts the request and stops the walk |
|
|
42
|
+
| Returns `null` / `undefined` | Skips to the next entry |
|
|
43
|
+
| Throws | Rejects with a specific status |
|
|
40
44
|
|
|
41
|
-
|
|
42
|
-
- returns `null` / `undefined`: skip to the next entry
|
|
43
|
-
- **throws**: reject with a specific status
|
|
45
|
+
If every entry skips, the request gets a `401`. Its `WWW-Authenticate` header advertises the schemes the entries declare:
|
|
44
46
|
|
|
45
|
-
|
|
47
|
+
- `Basic` for `httpBasic()`.
|
|
48
|
+
- `Bearer` for `jwtHmac`, `jwtEcdsa`, `oidc`, and `vercelOidc`.
|
|
49
|
+
- `Bearer` for entries that declare none, such as a custom `AuthFn` or an empty array.
|
|
50
|
+
|
|
51
|
+
See [`withAuthChallenges`](#custom-verifiers) to declare a scheme on a custom `AuthFn`.
|
|
46
52
|
|
|
47
53
|
```ts
|
|
48
54
|
import { type AuthFn, localDev, vercelOidc } from "eve/channels/auth";
|
|
@@ -67,7 +73,7 @@ export default eveChannel({
|
|
|
67
73
|
});
|
|
68
74
|
```
|
|
69
75
|
|
|
70
|
-
Put your own providers ahead of the catch-all helpers
|
|
76
|
+
Put your own providers ahead of the catch-all helpers, and `localDev()` last. A `vercelOidc()` before `localDev()` lets a local Vercel OIDC bearer resolve a real user instead of the stand-in `local-dev` caller. On non-Vercel hosts, omit `vercelOidc()` unless you want to accept Vercel-issued tokens.
|
|
71
77
|
|
|
72
78
|
To reject with a precise status instead of skipping, throw:
|
|
73
79
|
|
|
@@ -85,7 +91,7 @@ Any other thrown error follows the normal channel failure path. When building a
|
|
|
85
91
|
|
|
86
92
|
## Verifier helpers
|
|
87
93
|
|
|
88
|
-
`eve/channels/auth` ships these
|
|
94
|
+
`eve/channels/auth` ships these helpers:
|
|
89
95
|
|
|
90
96
|
| Helper | Use when |
|
|
91
97
|
| ---------------- | -------------------------------------------------------------------------------------------------- |
|
|
@@ -97,31 +103,31 @@ Any other thrown error follows the normal channel failure path. When building a
|
|
|
97
103
|
| `jwtEcdsa(...)` | You verify asymmetric JWTs minted by another system. |
|
|
98
104
|
| `oidc(...)` | You want eve to verify OIDC-issued tokens from an arbitrary issuer. |
|
|
99
105
|
|
|
100
|
-
`httpBasic(credentials, { realm })`
|
|
106
|
+
`httpBasic(credentials, { realm })` renders `realm` on the `WWW-Authenticate: Basic` challenge (e.g. `Basic realm="agent", charset="UTF-8"`) so browsers label their login prompt. Omit `realm` to use `"eve"`. Usernames and passwords are normalized to Unicode NFC before comparison.
|
|
101
107
|
|
|
102
108
|
Exercise caution for agents that process non-public, sensitive, regulated, or production data unless you have implemented other access controls.
|
|
103
109
|
|
|
104
110
|
### `localDev()`
|
|
105
111
|
|
|
106
|
-
|
|
112
|
+
Accepts the request as a stand-in `local-dev` caller, but only on a local development server: `eve dev` (which sets `EVE_DEV=1`) or `vercel dev` (`VERCEL=1` and `VERCEL_ENV=development` together). No request header can change this. A production deployment (`eve start`, a Vercel deployment, or any container host) sets neither flag, so every request falls through to the next entry.
|
|
107
113
|
|
|
108
|
-
On a development server, `localDev()`
|
|
114
|
+
On a development server, `localDev()` refuses browser requests for another website. It refuses a request when its host or `Origin` is neither a loopback host nor one of this machine's addresses. A web page the developer opens can't call the local agent, even through DNS rebinding. A frontend on any loopback host and port, such as `http://localhost:3000` calling `http://127.0.0.1:2000`, still authenticates.
|
|
109
115
|
|
|
110
|
-
On `eve dev`, `localDev()` also refuses
|
|
116
|
+
On `eve dev`, `localDev()` also refuses connections from another machine, so LAN callers of `eve dev --host 0.0.0.0` aren't accepted as `local-dev`. A tunnel or reverse proxy on the same machine, such as ngrok or a local nginx, connects locally, so its callers still get `local-dev`.
|
|
111
117
|
|
|
112
|
-
|
|
118
|
+
`localDev()` is safe to leave in the walk. Still put a real authenticator ahead of it so production traffic has something to match.
|
|
113
119
|
|
|
114
120
|
### `vercelOidc()`
|
|
115
121
|
|
|
116
|
-
Verifies a bearer JWT against the [Vercel OIDC issuer](https://vercel.com/docs/oidc). Tokens minted for the current `VERCEL_PROJECT_ID` are always accepted,
|
|
122
|
+
Verifies a bearer JWT against the [Vercel OIDC issuer](https://vercel.com/docs/oidc). Tokens minted for the current `VERCEL_PROJECT_ID` are always accepted, so internal subagent and runtime callers authenticate with no configuration. To admit tokens from other Vercel projects, pass `subjects: [...]` (AWS IAM-style `*` wildcards).
|
|
117
123
|
|
|
118
|
-
|
|
124
|
+
Tokens carrying an `external_sub` authenticate as user callers. Their `project_id` must match `VERCEL_PROJECT_ID`, and their environment must match `VERCEL_TARGET_ENV` / `VERCEL_ENV`. If either variable is unset, these tokens fail. `external_sub` becomes the session subject, and the `name`, `picture`, and `email` claims appear in `ctx.session.auth.current.attributes`.
|
|
119
125
|
|
|
120
|
-
|
|
126
|
+
`vercelOidc()` only authenticates. To also permit [stubbed eval sessions](../evals/tool-stubs), use `eveVercelOidc` from `eve/channels/eve` with the same options. Its subject entries can grant [tool replacement permission](#tool-replacement-permission): `{ subject: vercelSubject({ teamSlug: "acme", projectName: "eval-runner" }), allowToolStubs: true }`. Plain subject strings, and tokens accepted only because they come from the current project, grant ordinary access only.
|
|
121
127
|
|
|
122
128
|
#### `subjects` patterns and `vercelSubject(...)`
|
|
123
129
|
|
|
124
|
-
Each `subjects` entry is matched against the token's `sub` claim,
|
|
130
|
+
Each `subjects` entry is matched against the token's `sub` claim, shaped `owner:<team>:project:<name>:environment:<env>`. A hand-written typo silently rejects every caller, and an over-broad `*` silently admits unrelated ones, so build the pattern with `vercelSubject(...)`. It rejects malformed input at construction time. Omit `environment` to match only `"production"`:
|
|
125
131
|
|
|
126
132
|
```ts
|
|
127
133
|
import { vercelOidc, vercelSubject } from "eve/channels/auth";
|
|
@@ -134,13 +140,13 @@ vercelOidc({
|
|
|
134
140
|
});
|
|
135
141
|
```
|
|
136
142
|
|
|
137
|
-
`teamSlug` and `projectName` are the human-readable slugs
|
|
143
|
+
`teamSlug` and `projectName` are the human-readable slugs in `sub`, not the `team_…` / `prj_…` IDs, and can't contain `:` or `*`. `environment` is `"production" | "preview" | "development" | "*"`. Hand-write the subject string only to match across teams with a wildcard.
|
|
138
144
|
|
|
139
145
|
### Custom verifiers
|
|
140
146
|
|
|
141
|
-
When
|
|
147
|
+
When no helper fits, write your own `AuthFn` (the array example above) or call the low-level verifiers directly.
|
|
142
148
|
|
|
143
|
-
A custom `AuthFn`
|
|
149
|
+
A custom `AuthFn` declares no `WWW-Authenticate` scheme, so `routeAuth` falls back to `Bearer`. Wrap it with `withAuthChallenges(fn, challenges)` to declare the schemes it satisfies, so a mixed `auth` array produces an accurate 401:
|
|
144
150
|
|
|
145
151
|
```ts
|
|
146
152
|
import { withAuthChallenges, type AuthFn } from "eve/channels/auth";
|
|
@@ -151,6 +157,8 @@ const apiKeyAuth: AuthFn<Request> = withAuthChallenges(
|
|
|
151
157
|
);
|
|
152
158
|
```
|
|
153
159
|
|
|
160
|
+
Each verifier is the pure function behind a helper and returns `{ ok: true, sessionAuth }` or `{ ok: false }`:
|
|
161
|
+
|
|
154
162
|
| Verifier | Behind | Input |
|
|
155
163
|
| -------------------------------------- | -------------- | -------------------------------- |
|
|
156
164
|
| `verifyHttpBasic(header, credentials)` | `httpBasic()` | raw `Authorization` header value |
|
|
@@ -159,7 +167,7 @@ const apiKeyAuth: AuthFn<Request> = withAuthChallenges(
|
|
|
159
167
|
| `verifyOidc(token, config)` | `oidc()` | bearer token (OIDC, any issuer) |
|
|
160
168
|
| `verifyVercelOidc(token, opts)` | `vercelOidc()` | bearer token (Vercel OIDC) |
|
|
161
169
|
|
|
162
|
-
|
|
170
|
+
Extract the token with `extractBearerToken(request.headers.get("authorization"))` before passing it to the JWT/OIDC verifiers. The configs (`VerifyJwtHmacConfig`, `VerifyJwtEcdsaConfig`, `VerifyOidcConfig`) take `issuer`, `audiences`, the signing material (`secret` / `publicKey` / `discoveryUrl`), and optional `subjects` / `claims` matchers.
|
|
163
171
|
|
|
164
172
|
```ts
|
|
165
173
|
import { extractBearerToken, verifyJwtHmac, type AuthFn } from "eve/channels/auth";
|
|
@@ -180,7 +188,7 @@ function hmacAuth(): AuthFn<Request> {
|
|
|
180
188
|
|
|
181
189
|
### Failure responses in custom `defineChannel` routes
|
|
182
190
|
|
|
183
|
-
|
|
191
|
+
A `defineChannel` route that runs its own checks instead of `routeAuth` can return a framework-shaped failure from `createUnauthorizedResponse(...)`. The `Response` has `cache-control: no-store`, a `{ ok: false, code, error }` JSON body, and one `www-authenticate` header per challenge:
|
|
184
192
|
|
|
185
193
|
```ts title="agent/channels/intake.ts"
|
|
186
194
|
import { defineChannel, POST } from "eve/channels";
|
|
@@ -202,11 +210,11 @@ export default defineChannel({
|
|
|
202
210
|
});
|
|
203
211
|
```
|
|
204
212
|
|
|
205
|
-
`UnauthenticatedError` and `ForbiddenError` wrap this builder
|
|
213
|
+
`UnauthenticatedError` (`401`) and `ForbiddenError` (`403`) wrap this builder; throw them from an `AuthFn` that `routeAuth` walks. Call `createUnauthorizedResponse` directly only when returning a `Response` from a hand-rolled route.
|
|
206
214
|
|
|
207
215
|
## Network policy
|
|
208
216
|
|
|
209
|
-
`eve/channels/auth` exports `createIpAllowList(...)` and `isIpAllowed(...)
|
|
217
|
+
`eve/channels/auth` exports `createIpAllowList(...)` and `isIpAllowed(...)`. A request that fails the network policy is dropped before auth and runtime execution.
|
|
210
218
|
|
|
211
219
|
## Replace `placeholderAuth` before production
|
|
212
220
|
|
|
@@ -221,15 +229,15 @@ export default eveChannel({
|
|
|
221
229
|
});
|
|
222
230
|
```
|
|
223
231
|
|
|
224
|
-
In production, `placeholderAuth()` returns a structured `401
|
|
232
|
+
In production, `placeholderAuth()` returns a structured `401`, so a generated web chat app can report that auth isn't configured. Replace it with your app's `AuthFn` or a shipped helper before browser callers reach production. Without an authored channel file, eve uses the same `[vercelOidc(), localDev(), placeholderAuth()]` policy, which also rejects production traffic.
|
|
225
233
|
|
|
226
|
-
You
|
|
234
|
+
You don't have to keep `vercelOidc()`. For a self-hosted app, an app-embedded frontend, or a non-Vercel identity system, use `httpBasic()`, `jwtHmac()`, `jwtEcdsa()`, generic `oidc()`, or a custom `AuthFn`. A custom `AuthFn` maps your verified user, session, or API key to a `SessionAuthContext`.
|
|
227
235
|
|
|
228
|
-
Keep secret values (`ROUTE_AUTH_BASIC_PASSWORD`, signing keys) in environment variables. Route-auth secrets never
|
|
236
|
+
Keep secret values (`ROUTE_AUTH_BASIC_PASSWORD`, signing keys) in environment variables. Route-auth secrets are never written into build output. eve reads them from your channel file when the server starts.
|
|
229
237
|
|
|
230
238
|
## Accepting forwarded identity from another deployment
|
|
231
239
|
|
|
232
|
-
A `defineRemoteAgent({ forwardPrincipal: true })` caller (see [Remote agents](./remote-agents#forwarding-the-caller-identity))
|
|
240
|
+
A `defineRemoteAgent({ forwardPrincipal: true })` caller (see [Remote agents](./remote-agents#forwarding-the-caller-identity)) sends its end user's identity on create and follow-up requests as a `forwardedPrincipal` body field. eve rejects every forwarded identity with `403` until you name the forwarders you trust with `trustedForwarders` on `eveChannel`:
|
|
233
241
|
|
|
234
242
|
```ts title="agent/channels/eve.ts"
|
|
235
243
|
import { eveChannel } from "eve/channels/eve";
|
|
@@ -243,11 +251,11 @@ export default eveChannel({
|
|
|
243
251
|
});
|
|
244
252
|
```
|
|
245
253
|
|
|
246
|
-
`trustedForwarders`
|
|
254
|
+
`trustedForwarders` lets the verified forwarder supply delegation context: the user's identity, the parent session chain, and, when it forwards an identity, trace-content limits. Match it precisely: `() => true` grants this authority to every caller that passes route auth, including preview deployments accepted by `vercelOidc()`. eve's default channel rejects forwarded identities and ignores the other context.
|
|
247
255
|
|
|
248
256
|
### Limiting what a forwarder may assert
|
|
249
257
|
|
|
250
|
-
A
|
|
258
|
+
A predicate that checks only the forwarder lets it claim any identity, such as a Slack user or app identity your tools trust. To limit a forwarder to its own users, check the claim in the predicate's second argument:
|
|
251
259
|
|
|
252
260
|
```ts title="agent/channels/eve.ts"
|
|
253
261
|
import { eveChannel } from "eve/channels/eve";
|
|
@@ -275,41 +283,50 @@ export default eveChannel({
|
|
|
275
283
|
});
|
|
276
284
|
```
|
|
277
285
|
|
|
278
|
-
`assertion.principal` holds the `current` and `initiator` contexts the forwarder
|
|
286
|
+
`assertion.principal` holds the `current` and `initiator` contexts the forwarder claims, already stamped with `eve:forwarded-by`. `initiator` equals `current` when the sender omits it. The forwarder supplies attributes too, so check any attribute your tools trust.
|
|
279
287
|
|
|
280
|
-
|
|
288
|
+
`initiator` takes effect only when the session is created. On a follow-up request, the predicate still sees the claimed `initiator`, but the session keeps its original initiator. Checking `initiator` on a follow-up doesn't change that original value.
|
|
281
289
|
|
|
282
|
-
|
|
290
|
+
`assertion.principal` is absent when a request forwards the parent session chain without an identity. A predicate that requires `assertion.principal` accepts that forwarder's session chain only alongside an identity it accepts. The `ForwardedAssertion` and `TrustedForwarders` types are exported from `eve/channels/eve` for named predicates.
|
|
283
291
|
|
|
284
|
-
|
|
292
|
+
When the predicate accepts a create request, `ctx.session.auth.current` and `.initiator` carry the forwarded user as if they had called your deployment directly. On a follow-up request, only `auth.current` is replaced. User-scoped connections, local subagents, and further `forwardPrincipal` hops see the active turn's caller.
|
|
285
293
|
|
|
286
|
-
|
|
294
|
+
The receiver always overwrites the `eve:forwarded-by` attribute on accepted contexts, so a forwarder can't falsify it. A forwarded body without `trustedForwarders`, or one the predicate refuses, gets `403`; a malformed payload gets `400`. Only identity metadata reaches the receiver, never tokens or credentials.
|
|
287
295
|
|
|
288
|
-
|
|
296
|
+
A trusted parent session chain fills `ctx.session.parent` and keeps the same root session across every hop. eve ignores an untrusted chain. The root session's normal token cap still applies to an accepted chain.
|
|
289
297
|
|
|
290
|
-
|
|
298
|
+
A remote delegation request carries a callback body and a valid sampled `traceparent`. On such a request, an accepted `trustedForwarders` result can also admit an origin audience and input and output content limits from one W3C Baggage member. These values grant no authorization. The receiver's own trace policy also decides, using the origin audience. eve keeps only what both decisions allow, and later hops forward only that narrowed result. A malformed, partial, unsampled, or mixed-version value falls back to metadata-only tracing. The caller supplies the callback and headers, so trust rests only on the verified caller identity and `trustedForwarders`. See [Preserving trace content](./remote-agents#preserving-trace-content).
|
|
291
299
|
|
|
292
|
-
|
|
300
|
+
W3C `traceparent`, `tracestate`, and the forwarded conversation ID are correlation metadata. They don't require `trustedForwarders`, link sessions, or grant session access.
|
|
301
|
+
|
|
302
|
+
> ⚠️ Both deployments must support forwarding on follow-up requests before you resume persistent remote sessions. A receiver that supports forwarding only on create rejects a forwarded follow-up with HTTP 400. The sender doesn't fall back to sending as its own service. See [Forwarding the caller identity](./remote-agents#forwarding-the-caller-identity).
|
|
303
|
+
|
|
304
|
+
Subagent sessions persist by default but don't keep a caller's access between turns. Every accepted follow-up replaces `auth.current`, and clears it when an internal local message has no caller. Per-user connections use that caller, so a later caller can't use a prior caller's OAuth grant. A caller allowed to continue the session still sees its conversation history and artifacts. Your application decides who may use a session.
|
|
293
305
|
|
|
294
306
|
## What reaches `ctx.session.auth`
|
|
295
307
|
|
|
296
|
-
Inside runtime code, `ctx.session.auth` carries the
|
|
308
|
+
Inside runtime code, `ctx.session.auth` carries the channel's route-auth result as a caller snapshot:
|
|
309
|
+
|
|
310
|
+
- `auth.current`: the caller on the active inbound turn. A follow-up from a different caller replaces it for that turn.
|
|
311
|
+
- `auth.initiator`: the caller that started the session. It never changes.
|
|
312
|
+
|
|
313
|
+
The caller stays the same for the whole turn; only its claims can change:
|
|
297
314
|
|
|
298
|
-
- `auth.current
|
|
299
|
-
-
|
|
300
|
-
-
|
|
301
|
-
- Within a turn the principal is fixed; only its claims may update. A message from the turn's own principal, including a typed answer to a pending `ctx.ask()` or `ask_question`, joins the turn and updates `auth.current` with its claims. A message from anyone else waits for the turn to end and runs as its own turn. Someone else can still answer a pending request with a button or structured response; that settles the request with them as its responder, and the turn keeps its `auth.current`.
|
|
302
|
-
- `auth.current` is whatever the channel passed as `auth` when it dispatched the message. Route auth either accepts the request or returns `401`, but a route handler or channel hook can still dispatch with `auth: null`, such as `source.send(message, { auth: null })` or a Slack `onMessage` hook that returns `{ auth: null }`. On a new session, both values are then `null`. On a continuation, `auth.current` is `null` while `auth.initiator` stays pinned to the session's original caller. Internal runtime paths, such as subagents, can also have no caller auth.
|
|
315
|
+
- A message from the turn's own caller joins the turn and updates `auth.current` with its claims. This includes a typed answer to a pending `ctx.ask()` or `ask_question`.
|
|
316
|
+
- A message from anyone else waits for the turn to end and runs as its own turn.
|
|
317
|
+
- Someone else can still answer a pending request with a button or structured response. The request then records them as its responder, and the turn keeps its `auth.current`.
|
|
303
318
|
|
|
304
|
-
|
|
319
|
+
`auth.current` is whatever `auth` the channel sent the message with. A route handler or channel hook can send with `auth: null`, such as `source.send(message, { auth: null })` or a Slack `onMessage` hook that returns `{ auth: null }`. On a new session, both values are then `null`; on a continuation, only `auth.current` is. Internal runtime paths, such as subagents, can also have no caller auth.
|
|
305
320
|
|
|
306
|
-
|
|
321
|
+
Use the caller on `auth.current` (or `auth.initiator`) to limit tools, choose [dynamic tools, skills, and other definitions](./dynamic-capabilities) per user, or enforce tenant boundaries.
|
|
322
|
+
|
|
323
|
+
Route auth doesn't check who may use a session, and eve adds no per-session access list. If multiple users or tenants can reach the same route, implement the per-user, per-tenant, or per-session authorization your application requires.
|
|
307
324
|
|
|
308
325
|
## Tool replacement permission
|
|
309
326
|
|
|
310
|
-
Creating a [stubbed eval session](../evals/tool-stubs) requires
|
|
327
|
+
Creating a [stubbed eval session](../evals/tool-stubs) requires `allowToolStubs: true` in the verified route authentication result; request JSON can't grant it. With `eveVercelOidc`, put the grant on a `subjects` entry, as in the [tool stubs example](../evals/tool-stubs#permit-tool-replacement). Any matching entry with the grant permits replacement, and other entries don't revoke it. Tokens accepted only because they come from the current project, and user callers, don't inherit project grants.
|
|
311
328
|
|
|
312
|
-
Custom authenticators return the same grant after verifying their caller.
|
|
329
|
+
Custom authenticators return the same grant after verifying their caller. Type a standalone callback as `EveAuthFn` from `eve/channels/eve`. This channel permits stubs only in local development:
|
|
313
330
|
|
|
314
331
|
```ts
|
|
315
332
|
import { localDev } from "eve/channels/auth";
|
|
@@ -324,15 +341,28 @@ export default eveChannel({
|
|
|
324
341
|
});
|
|
325
342
|
```
|
|
326
343
|
|
|
327
|
-
|
|
344
|
+
eve removes the grant from the caller identity before it forwards or saves that identity, or uses it for audience classification.
|
|
345
|
+
|
|
346
|
+
Later messages, approvals, controls, and result reads use normal channel authentication without rechecking the grant. Anyone your channel admits to an existing session can use its configured stubs, so apply the same session-access policy as for ordinary sessions.
|
|
347
|
+
|
|
348
|
+
## Agent info access
|
|
349
|
+
|
|
350
|
+
`GET /eve/v1/info` returns authored instructions and server paths, so it serves only operators by default: `service` and `runtime` principals, plus callers `localDev()` admits when the channel's `auth` includes it. Other callers get `403` with code `info_forbidden`. An eve-channel authenticator can decide for its caller instead: `allowAgentInfo: true` grants access, and `false` denies it even to an operator. Like `allowToolStubs`, the flag applies only to the current request and is never persisted or forwarded.
|
|
328
351
|
|
|
329
|
-
|
|
352
|
+
```ts
|
|
353
|
+
import type { EveAuthFn } from "eve/channels/eve";
|
|
354
|
+
|
|
355
|
+
const authenticateStaff: EveAuthFn = async (request) => {
|
|
356
|
+
const staff = await verifyStaffSession(request);
|
|
357
|
+
return staff ? { ...staff, allowAgentInfo: true } : null;
|
|
358
|
+
};
|
|
359
|
+
```
|
|
330
360
|
|
|
331
361
|
## Tool and connection auth
|
|
332
362
|
|
|
333
|
-
Tool and connection auth
|
|
363
|
+
Tool and connection auth signs your agent in to an external service that needs an interactive sign-in, like an OAuth MCP server. Connections declare `auth` on the connection definition. Tools resolve providers inline with `ctx.getToken(provider)` and call `ctx.requireAuth(provider)` only when a downstream service rejects a token. eve drives the sign-in, reuses the token within a step, and re-runs the call once the caller authorizes.
|
|
334
364
|
|
|
335
|
-
The
|
|
365
|
+
The user for user-scoped auth comes from route auth. `connect("...")` from `@vercel/connect/eve` defaults to `principalType: "user"`, so OAuth can start only when `ctx.session.auth.current.principalType === "user"`. An anonymous, local-dev, runtime, or service session fails fast with `reason: "principal_required"`, because no end-user identity exists to bind the grant to.
|
|
336
366
|
|
|
337
367
|
Use app-scoped auth when the external service should act as the agent itself:
|
|
338
368
|
|
|
@@ -346,7 +376,7 @@ Use user-scoped auth when the external service should act as the signed-in perso
|
|
|
346
376
|
auth: connect("linear/myagent");
|
|
347
377
|
```
|
|
348
378
|
|
|
349
|
-
For user-scoped auth in a browser app,
|
|
379
|
+
For user-scoped auth in a browser app, have the eve channel's route auth verify your app session and return a user identity:
|
|
350
380
|
|
|
351
381
|
```ts title="agent/channels/eve.ts"
|
|
352
382
|
import { eveChannel } from "eve/channels/eve";
|
|
@@ -375,17 +405,17 @@ export default eveChannel({
|
|
|
375
405
|
});
|
|
376
406
|
```
|
|
377
407
|
|
|
378
|
-
Keep `principalId` stable for the same person, and include an `issuer` when the
|
|
408
|
+
Keep `principalId` stable for the same person, and include an `issuer` when the app accepts users from multiple identity providers. eve keys user credentials by issuer and principal ID, so two identity providers can't share a grant.
|
|
379
409
|
|
|
380
|
-
Built-in platform channels that identify a human sender
|
|
410
|
+
Built-in platform channels that identify a human sender attach a user identity for that sender by default. These include Slack, Discord, Teams, Telegram, Twilio, Linear, and GitHub. A Slack mention, DM, or button click can authorize a user-scoped connection for that Slack user without a browser-session auth function.
|
|
381
411
|
|
|
382
412
|
### On a connection
|
|
383
413
|
|
|
384
|
-
Set `auth` on an MCP or OpenAPI connection when the external service supplies a family of remote tools. The [connections overview](../connections) owns the shared `connect()` setup, static-token providers, app and user scope, approval
|
|
414
|
+
Set `auth` on an MCP or OpenAPI connection when the external service supplies a family of remote tools. The [connections overview](../connections) owns the shared `connect()` setup, static-token providers, app and user scope, approval prompt, and self-hosted OAuth flow.
|
|
385
415
|
|
|
386
416
|
### On a single tool
|
|
387
417
|
|
|
388
|
-
When one tool calls a service behind OAuth, keep the auth provider at the call site
|
|
418
|
+
When one tool calls a service behind OAuth, keep the auth provider at the call site instead of adding a connection. Providers take the same shapes as connection `auth`: `connect("...")` for Vercel Connect-backed OAuth, a custom interactive definition, or a plain `{ getToken }` for static credentials.
|
|
389
419
|
|
|
390
420
|
```ts title="agent/tools/list_okta_groups.ts"
|
|
391
421
|
import { defineTool } from "eve/tools";
|
|
@@ -407,7 +437,7 @@ export default defineTool({
|
|
|
407
437
|
});
|
|
408
438
|
```
|
|
409
439
|
|
|
410
|
-
|
|
440
|
+
The same inline shape handles tools that need more than one credential:
|
|
411
441
|
|
|
412
442
|
```ts title="agent/tools/sync_ticket.ts"
|
|
413
443
|
import { connect } from "@vercel/connect/eve";
|
|
@@ -434,7 +464,7 @@ export default defineTool({
|
|
|
434
464
|
});
|
|
435
465
|
```
|
|
436
466
|
|
|
437
|
-
Configure
|
|
467
|
+
Configure OAuth targeting on the provider. For Vercel Connect, pass `tokenParams` to `connect(...)` for explicit OAuth scopes, resource indicators, or rich authorization requests:
|
|
438
468
|
|
|
439
469
|
```ts
|
|
440
470
|
const githubAuth = connect({
|
|
@@ -453,14 +483,14 @@ const githubAuth = connect({
|
|
|
453
483
|
|
|
454
484
|
The tool's `ctx` exposes provider-scoped auth accessors:
|
|
455
485
|
|
|
456
|
-
- `ctx.getToken(provider, options?)` resolves an inline provider such as `connect("github/myagent")`. It uses the same cache, callback, and sign-in
|
|
457
|
-
- `ctx.requireAuth(provider, options?)` evicts
|
|
486
|
+
- `ctx.getToken(provider, options?)` resolves an inline provider such as `connect("github/myagent")`. It uses the same cache, callback, and sign-in flow as connection auth, keyed to this tool and that provider.
|
|
487
|
+
- `ctx.requireAuth(provider, options?)` evicts that provider's cached token and starts a fresh authorization challenge. Use it after a downstream `401` rejects a token from `ctx.getToken(provider)`.
|
|
458
488
|
|
|
459
|
-
Throw `ConnectionAuthorizationRequiredError` from an inline provider's `getToken` to
|
|
489
|
+
Throw `ConnectionAuthorizationRequiredError` from an inline provider's `getToken` to start that provider's consent flow.
|
|
460
490
|
|
|
461
|
-
Vercel Connect providers usually supply their own display name
|
|
491
|
+
Vercel Connect providers usually supply their own display name for the authorization challenge. To override what users see, set `displayName`, for example `ctx.getToken(customAuth, { displayName: "Salesforce" })`.
|
|
462
492
|
|
|
463
|
-
Inline providers derive a stable
|
|
493
|
+
Inline providers derive a stable auth key from Vercel Connect metadata when available. Give each custom provider without that metadata an explicit key, for example `ctx.getToken(auth, { authKey: "github" })`. `authKey` sets eve's cache and callback keys; it is not an OAuth scope.
|
|
464
494
|
|
|
465
495
|
## What to read next
|
|
466
496
|
|
|
@@ -3,14 +3,13 @@ title: "Session State"
|
|
|
3
3
|
description: "Persist and resume eve client sessions with durable session IDs and stream cursors."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
streams.
|
|
8
|
-
|
|
6
|
+
A `ClientSession` is a handle on one session ID, used for messages, controls,
|
|
7
|
+
and streams. It also keeps a local `streamIndex` cursor, so reconnects skip
|
|
8
|
+
events the handle already read.
|
|
9
9
|
|
|
10
10
|
## Read and persist state
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
consuming the delivery:
|
|
12
|
+
Save `session.state` after you read a response:
|
|
14
13
|
|
|
15
14
|
```ts
|
|
16
15
|
const { session, delivery } = await client.sessions.create({
|
|
@@ -21,10 +20,11 @@ await delivery.result();
|
|
|
21
20
|
await saveSessionState(session.state);
|
|
22
21
|
```
|
|
23
22
|
|
|
24
|
-
The state
|
|
23
|
+
The state holds the ID, the cursor, and an optional routing handle:
|
|
25
24
|
|
|
26
25
|
```ts
|
|
27
26
|
interface ClientSessionState {
|
|
27
|
+
inbox?: string; // opaque; save and restore it unchanged
|
|
28
28
|
sessionId: string;
|
|
29
29
|
streamIndex: number;
|
|
30
30
|
/** Opaque; persist it and pass it back unchanged. eve may extend it. */
|
|
@@ -32,8 +32,8 @@ interface ClientSessionState {
|
|
|
32
32
|
}
|
|
33
33
|
```
|
|
34
34
|
|
|
35
|
-
It is a
|
|
36
|
-
|
|
35
|
+
It is a stream cursor, not a transcript. Save events separately when your
|
|
36
|
+
application renders chat history.
|
|
37
37
|
|
|
38
38
|
## Resume a saved session
|
|
39
39
|
|
|
@@ -46,31 +46,29 @@ const saved = (await loadSessionState()) as ClientSessionState;
|
|
|
46
46
|
const session = client.sessions.attach(saved.sessionId, saved);
|
|
47
47
|
|
|
48
48
|
const response = await session.send("Now shorten it.");
|
|
49
|
-
console.log((await response.result()).
|
|
49
|
+
console.log((await response.result()).reply);
|
|
50
50
|
```
|
|
51
51
|
|
|
52
52
|
Pass the whole saved state so its optional [`inbox`](./overview#faster-sends-with-inbox) value
|
|
53
53
|
reaches later sends. `attach()` performs no request. Every later operation targets exactly
|
|
54
|
-
`saved.sessionId
|
|
54
|
+
`saved.sessionId` and never creates a replacement.
|
|
55
55
|
|
|
56
|
-
`send()`
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
throw instead of returning an ambiguous result.
|
|
56
|
+
`send()` returns the response to the message the server accepted. If the saved
|
|
57
|
+
cursor is behind, the response skips earlier turns, even while another turn is
|
|
58
|
+
active or queued. You don't need to read the rest of the stream first. `send()`
|
|
59
|
+
throws when the server's reply has no delivery ID, so upgrade the server with
|
|
60
|
+
the client.
|
|
62
61
|
|
|
63
|
-
If a
|
|
64
|
-
|
|
65
|
-
result.
|
|
62
|
+
If a reconnect limit you set ends the stream before the turn finishes or pauses,
|
|
63
|
+
`result()` throws instead of returning a partial result.
|
|
66
64
|
|
|
67
65
|
<a id="waiting-completed-and-reset-sessions" />
|
|
68
66
|
|
|
69
67
|
## Waiting, completed, and ended sessions
|
|
70
68
|
|
|
71
|
-
A session that hasn't ended (`session.ended`) accepts
|
|
69
|
+
A session that hasn't ended (`session.ended`) accepts more messages through the
|
|
72
70
|
same handle. An ended session does not. Start a fresh conversation
|
|
73
|
-
|
|
71
|
+
with another `client.sessions.create(firstTurn)` call.
|
|
74
72
|
|
|
75
73
|
```ts
|
|
76
74
|
const ended = await session.end({ reason: "Start over" });
|
|
@@ -78,7 +76,7 @@ await ended.result();
|
|
|
78
76
|
const { session: fresh, delivery } = await client.sessions.create({ message: "Begin again." });
|
|
79
77
|
```
|
|
80
78
|
|
|
81
|
-
The old `session`
|
|
79
|
+
The old `session` keeps pointing at its retired ID; `fresh` has a different ID.
|
|
82
80
|
|
|
83
81
|
## Multiple sessions
|
|
84
82
|
|
|
@@ -97,13 +95,12 @@ await save("research", research.state);
|
|
|
97
95
|
await save("support", support.state);
|
|
98
96
|
```
|
|
99
97
|
|
|
100
|
-
The shared `Client`
|
|
101
|
-
`ClientSession`
|
|
98
|
+
The shared `Client` holds the base URL, auth, headers, and redirect policy. Each
|
|
99
|
+
`ClientSession` holds its fixed ID and stream cursor.
|
|
102
100
|
|
|
103
101
|
## Reconnect an existing stream
|
|
104
102
|
|
|
105
|
-
`stream()` starts from the handle's
|
|
106
|
-
read:
|
|
103
|
+
`stream()` starts from the handle's cursor and advances it as you read:
|
|
107
104
|
|
|
108
105
|
```ts
|
|
109
106
|
const session = client.sessions.attach(saved.sessionId, saved);
|