docs(research): a smaller public surface for eve 1.0 by OwenKephart · Pull Request #4930 · vercel/eve

OwenKephart · 2026-10-15T22:03:46Z

Summary

At 1.0, every name eve exports becomes a compatibility promise. Today eve exports 2,005 names over 84 entry points, and docs, apps, and e2e use only about 450 of them. This research doc commits 1.0 to about 1,400 names, one shape per concept, and types that eve owns. It consolidates parallel APIs, gives each name one entry point and one meaning, keeps internal helpers internal, and removes public types that resolve to packages an app may not install. A checked export list makes each new public name a deliberate diff.

The doc puts the changes most apps will notice first, and collapses the rest. Changes to the session stream fold into the v27 stack (#4855) before it merges. This PR is stacked on #4356.

Validation

oxfmt and docs:check on the doc.
The TypeScript checker counted exports at feat(eve): simplify chat templates around shared session state #4855 and at the implementation checkpoint refactor(api)!: curate public exports and own authoring types #4954 (1,504 names). After-counts are estimates until the implementation measures them.
A clean project with only ai and @types/node typechecked every entry against declarations emitted at refactor(api)!: curate public exports and own authoring types #4954. With skipLibCheck: true, 43 exported types or values were any or had any fields.

Review follow-through

The research review now distinguishes settled results from live request status, corrects baseline import/count examples, and uses generic downstream descriptions. It also distinguishes Linear activity signals from cancellation and requires a real decision implementation. The principal migration remains coordinated with Connect.

Checklist

I added tests and documentation where relevant
I added a changeset if this touches the published eve package
DCO sign-off passes for every commit (git commit --signoff)

Signed-off-by: owenkephart <owen.kephart@vercel.com>

vercel · 2026-10-15T22:03:52Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
eve-docs	Error	v0	Oct 18, 2026 1:48am UTC
eve-pkg	Error	v0	Oct 18, 2026 1:48am UTC

Signed-off-by: owenkephart <owen.kephart@vercel.com>

roboeve · 2026-10-15T22:24:00Z

+interface Delivery<TOutput = unknown> extends AsyncIterable<SessionStreamEvent> {
+  readonly sessionId: string;
+  readonly deliveryId: string;
+  result(): Promise<DeliveryResult<TOutput>>; // { status: RequestStatus, sessionEnded, reply?, data?, interactions }


result() resolves once the request stops making progress, but RequestStatus includes "working". Every caller then has to handle a status that can't come back from a settled result. Today's MessageResult.status has no running value (packages/eve/src/client/types.ts:315-323 at #4855). Type it as Exclude<RequestStatus, "working">, or name a SettledRequestStatus, so RequestStatus only shows up where a live view can still be working (requestStatus(view, id)).

Clarified that DeliveryResult.status excludes working; the live requestStatus selector retains it. The implemented delivery result uses a settled status.

roboeve · 2026-10-15T22:24:01Z

+response: ({ responder }) => (isApprover(responder) ? "admit" : { refuse: "Not an approver." }),
+```
+
+- A request policy returns `"allow" | "ask" | "deny" | { deny: string }`; booleans go, and one


The type here doesn't accept the example's implicit return on line 228 (// returning nothing allows), so a typed ApprovalPolicy would reject it. Accepting undefined too gives allow two spellings ("allow" and nothing), which is a fifth form beside the "four approval decisions" counted earlier. That's the same kind of overlap this section criticizes in "approved" vs "not-applicable". Pick one: either void is the only allow, or "allow" is required and the example returns it.

The approval-policy rewrite was withdrawn in the current plan. It retains the existing policy vocabulary and implements keyed once(), so the inconsistent allow/void example is gone.

roboeve · 2026-10-15T22:24:01Z

+  }
+  return (toolInput?.amount ?? 0) > 1000 ? "user-approval" : "not-applicable";
+},
+response: ({ responder }) =>


The "before" example doesn't match the current API. ApprovalResponseContext has auth, request, response, and session, with no top-level responder. The responder is response.principal (packages/eve/src/approval/definition.ts:111-127 at #4855). Use ({ response }) => isApprover(response.principal) ? ... here. If line 230's responder is a deliberate context change, list it with the other approval changes.

The obsolete response-policy example is gone from the current plan; no top-level responder context change is proposed.

roboeve · 2026-10-15T22:24:01Z

+
+### Smaller consolidations
+
+- **Connections:** one ownership field, `principalType: "app" | "user"`; the deprecated


This has the deprecation backwards. At #4855, credentialOwner is the preferred field for non-interactive connection auth, and principalType is the one marked @deprecated Use credentialOwner for connection credential ownership (packages/eve/src/shared/connection-types.ts:168-183). Keeping principalType is defensible, since the docs and interactive auth use it, but the doc should say that this reverses the current deprecation and that credentialOwner is what goes.

The research now explicitly says that choosing principalType reverses the deprecation at #4855.

roboeve · 2026-10-15T22:24:01Z

+  fact zod schemas (vendored zod types in `.d.ts`) stay internal. `foldEvents`, `emptySessionView`,
+  and `emptyPreviews` are the public fold. Components read the frontend snapshot's `view` instead
+  of folding.
+- **Built-in tools:** the 14 `…_INPUT_SCHEMA` / `…_OUTPUT_SCHEMA` constants, which the documented


I count 12 public schema constants at #4855, not 14. They're one input/output pair each in public/tools/{bash,read-file,write-file,web-fetch,glob,grep}.ts, and no other public tool entry exports one. That puts Built-in tools at about 49 after, not ~47 (line 81).

Corrected the statement to 12 public schema constants. The table now also has a separately measured #4954 column rather than deriving all reductions from that earlier estimate.

roboeve · 2026-10-15T22:24:01Z

+
+```ts
+// before
+import type { CallRow, SessionView, SessionStreamEvent } from "eve/client";


CallRow isn't importable from eve/client today. The client barrel re-exports #protocol/session-events with export type *, plus only SessionView and SessionPreviews from the projection (packages/eve/src/client/index.ts:108-117 at #4855). Swap in a fact type that's actually re-exported there, so the "before" line compiles. Also check that the 175 count measures the session-events wildcard and not all of eve/events.

Replaced CallRow in the before import with SessionStarted, which the client wildcard actually re-exported. The audit scope explanation distinguishes event wildcard counts from the whole events entry.

roboeve · 2026-10-15T22:24:01Z

+  so `followSubagents` becomes `followAgents`. Both `auto` exports keep their names.
+- **Channel CORS:** `EveChannelCors` merges into `ChannelCors`, which also accepts one origin
+  string.
+- **Memory providers:** the keys are named after v26 events hooks now reject; they take names for


Not all four keys are named after events hooks reject. turn.started is still in v27's HookEventMap (packages/eve/src/public/definitions/hook.ts:22). Only turn.completed, compaction.requested, and compaction.completed are gone. Maybe say the keys mix one live event name with three retired ones.

Corrected the wording: one live event name is mixed with three retired v26 names. Memory-key migration stays with its separate PR.

roboeve · 2026-10-15T22:24:01Z

+- Tell the teams whose code imports a removed or moved name: vercel-site's Agent Builder
+  (`eve/setup/scaffold`) and agent-factory (`parseLinearWebhookEvent` in a test).


This is a public repo, and these lines (and line 404) name internal consumer repos and products. Use generic wording like "known downstream consumers of eve/setup/scaffold and parseLinearWebhookEvent" and keep the specific names in an internal tracker.

Replaced the named internal consumer/product examples with generic downstream descriptions.

Signed-off-by: owenkephart <owen.kephart@vercel.com>

Signed-off-by: OwenKephart <owen.kephart@vercel.com>

…kers Signed-off-by: OwenKephart <owen.kephart@vercel.com>

… gaps Extend the pre-1.0 cleanup plan with findings from an audit of the assembled #4954 surface: types that resolve to packages an app may not have, the AI SDK's experimental decision API in stable signatures, remaining same-name collisions, extension and wire-framing internals, deprecated aliases, one channel and principal vocabulary, naming conventions, importable authoring types, and the checks that keep the surface from drifting. Refresh the counts with measurements at #4954. Signed-off-by: owenkephart <owen.kephart@vercel.com>

Signed-off-by: owenkephart <owen.kephart@vercel.com>

Signed-off-by: owenkephart <owen.kephart@vercel.com> Co-Authored-By: owenkephart <owen.kephart@vercel.com>

docs(research): a smaller public surface for eve 1.0

20bfd3c

Signed-off-by: owenkephart <owen.kephart@vercel.com>

vercel Bot had a problem deploying to Preview – eve-docs October 15, 2026 22:04 Failure

vercel Bot deployed to Preview – eve-pkg October 15, 2026 22:06

View deployment

docs(research): clearer motivation and examples for the 1.0 surface

591f504

Signed-off-by: owenkephart <owen.kephart@vercel.com>

vercel Bot had a problem deploying to Preview – eve-docs October 15, 2026 22:19 Failure

vercel Bot deployed to Preview – eve-pkg October 15, 2026 22:21

View deployment

roboeve Bot reviewed Oct 15, 2026

View reviewed changes

docs(research): lead with the main 1.0 surface changes

96230f2

Signed-off-by: owenkephart <owen.kephart@vercel.com>

vercel Bot had a problem deploying to Preview – eve-docs October 15, 2026 22:52 Failure

vercel Bot deployed to Preview – eve-pkg October 15, 2026 22:53

View deployment

OwenKephart mentioned this pull request Oct 15, 2026

feat(eve): the v27 session protocol #4564

Open

3 tasks done

docs(research): explain each 1.0 surface change for new readers

1ad0998

Signed-off-by: owenkephart <owen.kephart@vercel.com>

OwenKephart mentioned this pull request Oct 15, 2026

feat(channels)!: typed delivery hooks and canonical channel identity #4932

Draft

3 tasks done

vercel Bot had a problem deploying to Preview – eve-docs October 15, 2026 23:13 Failure

vercel Bot deployed to Preview – eve-pkg October 15, 2026 23:14

View deployment

Revise pre-1.0 API cleanup documentation

6afaed8

vercel Bot had a problem deploying to Preview – eve-docs October 15, 2026 23:57 Failure

vercel Bot deployed to Preview – eve-pkg October 15, 2026 23:58

View deployment

This was referenced Oct 16, 2026

feat(eve)!: instrumentation speaks the session's vocabulary #4695

Open

refactor(eve)!: let the session stream own the frontend lifecycle #4854

Open

test(eve): cover v27 sessions through their odd paths #4726

Open

vercel Bot had a problem deploying to Preview – eve-docs October 16, 2026 00:11 Failure

vercel Bot had a problem deploying to Preview – eve-pkg October 16, 2026 00:12 Failure

docs(research): tighten the once({ key }) section

242980c

Signed-off-by: owenkephart <owen.kephart@vercel.com>

vercel Bot had a problem deploying to Preview – eve-docs October 16, 2026 00:20 Failure

vercel Bot deployed to Preview – eve-pkg October 16, 2026 00:21

View deployment

OwenKephart mentioned this pull request Oct 16, 2026

feat(sessions)!: return deliveries and unify request outcomes #4937

Draft

3 tasks done

docs(research): drop the approved-reason propagation promise

c0e62b8

Signed-off-by: OwenKephart <owen.kephart@vercel.com>

vercel Bot had a problem deploying to Preview – eve-docs October 16, 2026 02:46 Failure

vercel Bot deployed to Preview – eve-pkg October 16, 2026 02:47

View deployment

docs(research): retain useful public authoring types and disabled mar…

298260d

…kers Signed-off-by: OwenKephart <owen.kephart@vercel.com>

vercel Bot had a problem deploying to Preview – eve-docs October 16, 2026 16:14 Failure

vercel Bot deployed to Preview – eve-pkg October 16, 2026 16:15

View deployment

OwenKephart mentioned this pull request Oct 16, 2026

refactor(api)!: curate public exports and own authoring types #4954

Draft

3 tasks done

OwenKephart added 2 commits October 17, 2026 21:10

docs(research): extend the existing snippet check to imported names

fb97322

Signed-off-by: owenkephart <owen.kephart@vercel.com>

vercel Bot had a problem deploying to Preview – eve-docs October 17, 2026 21:11 Failure

vercel Bot had a problem deploying to Preview – eve-docs October 17, 2026 21:13 Failure

vercel Bot had a problem deploying to Preview – eve-pkg October 17, 2026 21:13 Failure

docs(research): ship the connection principal rename with Vercel Connect

cd0a2f8

Signed-off-by: owenkephart <owen.kephart@vercel.com>

OwenKephart force-pushed the research/pre-1.0-api-cleanup branch from 51681e8 to cd0a2f8 Compare October 17, 2026 21:15

vercel Bot temporarily deployed to Preview – eve-pkg October 17, 2026 21:15 Inactive

vercel Bot had a problem deploying to Preview – eve-docs October 17, 2026 21:16 Failure

docs(research): close review gaps and distinguish protocol signals

c704238

Signed-off-by: owenkephart <owen.kephart@vercel.com> Co-Authored-By: owenkephart <owen.kephart@vercel.com>

vercel Bot had a problem deploying to Preview – eve-docs October 18, 2026 01:47 Failure

vercel Bot had a problem deploying to Preview – eve-pkg October 18, 2026 01:48 Failure


		### Smaller consolidations

		- Connections: one ownership field, `principalType: "app" \| "user"`; the deprecated

		- Tell the teams whose code imports a removed or moved name: vercel-site's Agent Builder
		(`eve/setup/scaffold`) and agent-factory (`parseLinearWebhookEvent` in a test).

Conversation

OwenKephart commented Oct 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation

Review follow-through

Checklist

Uh oh!

vercel Bot commented Oct 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

roboeve Bot Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

roboeve Bot Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

roboeve Bot Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

roboeve Bot Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

roboeve Bot Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

roboeve Bot Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

roboeve Bot Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

roboeve Bot Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch had an error being deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

OwenKephart commented Oct 15, 2026 •

edited

Loading

vercel Bot commented Oct 15, 2026 •

edited

Loading