feat(eve): add HITL tool approval authorization API by benpankow · Pull Request #1421 · vercel/eve

benpankow · 2026-07-30T19:49:49Z

Summary

Adds the public API and machinery for authorizing the person who responds to a tool approval. A tool can optionally define authorizeResponse:

import { defineTool } from "eve/tools";
import { always } from "eve/tools/approval";

export default defineTool({
  description: "Refund a charge.",
  inputSchema: refundSchema,
  approval: {
    policy: always(),
    async authorizeResponse({ request, responder, session, auth }) {
      const identity = await auth.getToken(billingApproverAuth);

      if (await canApproveRefund({ identity, responder, request, session })) {
        return "allowed";
      }

      return {
        status: "rejected",
        safeReason: "You are not permitted to approve this refund.",
      };
    },
  },
  async execute(input) {
    return refund(input);
  },
});

The callback receives:

request: the stable approval request, tool call ID, tool name, and tool input;
responder: the identity produced by authenticated channel ingress;
session: read-only session identity, initiator, turn, and parent lineage;
auth: responder-bound getToken and requireAuth capabilities.

auth uses the explicit responder for token lookup, cache identity, challenge creation, callback completion, and eviction. It never substitutes mutable ambient session auth.

TokenResult now exposes the account represented by the credential:

interface TokenResult {
  token: string;
  expiresAt?: number;
  providerSubject?: string;
}

For example, a GitHub authorization provider can return the responder's stable GitHub user ID.

Dynamic tools retain both the request-time policy and response authorizer across durable replay. This PR also publishes the extension capability epochs required by the new public types.

This PR does not create candidates, settle approvals, or change channel/client presentation. Durable coordination is layered in #1370.

Depends on the Approve/Cancel protocol PR: #1385.

Validation

pnpm --filter eve typecheck
pnpm guard:invariants
focused approval API, dynamic-tool, tool-auth unit and integration tests
validated as part of the consolidated top-stack unit suite

vercel · 2026-07-30T19:49:56Z

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

Project	Deployment	Actions	Updated (UTC)
eve-docs	Ready	Preview	Jul 30, 2026 8:09pm
eve-docs-4759	Ready	Preview, v0	Jul 30, 2026 8:09pm

github-actions · 2026-07-30T19:53:23Z

Bundle + Package Summary: `apps/fixtures/weather-agent`

Key takeaways

No notable deltas vs ben/hitl-v2-approve-cancel (b705461).

Delta vs `ben/hitl-v2-approve-cancel (b705461)`

Area	Metric	Baseline	Current	Delta
Package	Packed tarball	7.62 MB	7.62 MB	+1.2 kB ⚠️
Package	Unpacked publish size	28.78 MB	28.79 MB	+5.7 kB ⚠️
Package	Installed footprint	91.26 MB	91.26 MB	+5.7 kB ⚠️
Package	Published files	2866	2866	0
Package	Installed files	6655	6655	0
Runtime	Unique function payloads	2	2	0
Runtime	Total function bytes	16.81 MB	16.81 MB	+2.9 kB ⚠️
Runtime	Public routes	11	11	0

Changed function payloads vs ben/hitl-v2-approve-cancel (b705461) (2)

Function	Status	Baseline	Current	Delta	Route changes
`functions/__server.func`	changed	8.41 MB	8.41 MB	+1.4 kB ⚠️	none
`functions/.well-known/workflow/v1/flow.func`	changed	8.41 MB	8.41 MB	+1.4 kB ⚠️	none

`eve init` install

Metric	Baseline	Current	Delta
Installed footprint	129.66 MB	129.66 MB	+5.7 kB ⚠️
Installed packages	128	128	0
dependencies	4	4	0
devDependencies	2	2	0
Dependency package bytes	43.12 MB	43.12 MB	+5.7 kB ⚠️
devDependency package bytes	5.04 MB	5.04 MB	0 B ➖

Build Metadata

Preset: vercel
Nitro: nitro@3.0.260610-beta
Output directory: apps/fixtures/weather-agent/.vercel/output
Build metadata timestamp: 2026-07-30T20:12:05.128Z
Route aliases: 11 public, 1 internal (12 total aliases)
Vercel routes in config: 14
Severity legend: 🔴 dominant/large, 🟠 notable, 🟡 watch, ⚪ small

Package Drill-Down

Package Details

Package: eve@0.28.0
Package directory: packages/eve
Tarball: 7.62 MB (eve-0.28.0.tgz)
Unpacked payload: 28.79 MB across 2866 published files
Installed footprint: 91.26 MB across 6655 installed files
Installed root package: 27.43 MB
Installed dependencies: 63.83 MB
Runtime dependencies: 2
Peer dependencies: 5 (4 optional)

Installed footprint is measured from an isolated temporary npm install of the packed tarball.

Heavy installed dependencies

eve: 27.43 MB (30.1%)
@rolldown/binding-linux-x64-gnu: 19.28 MB (21.1%)
@rolldown/binding-wasm32-wasi: 10.66 MB (11.7%)
@napi-rs/wasm-runtime: 6.56 MB (7.2%)
ai: 6.53 MB (7.2%)

Publish payload breakdown

Published file size
🔴 dist/src/compiled/shadcn-registry/index.js       [########################] 13.15 MB 45.7%
🟠 dist/src/compiled/experimental-ai-sdk-code-mo... [###.....................] 1.51 MB 5.2%
🟡 dist/src/compiled/@vercel/sandbox/index.js       [#.......................] 632.5 kB 2.2%
🟡 dist/src/compiled/_chunks/workflow/undici-DWL... [#.......................] 502.4 kB 1.7%
🟡 dist/src/compiled/@chat-adapter/slack/index.js   [#.......................] 440.5 kB 1.5%
🔴 Other published files                            [#######################.] 12.55 MB 43.6%

Installed footprint breakdown

Installed package size
🔴 eve                             [########################] 27.43 MB 30.1%
🔴 @rolldown/binding-linux-x64-gnu [#################.......] 19.28 MB 21.1%
🔴 @rolldown/binding-wasm32-wasi   [#########...............] 10.66 MB 11.7%
🔴 @napi-rs/wasm-runtime           [######..................] 6.56 MB 7.2%
🔴 ai                              [######..................] 6.53 MB 7.2%
🔴 zod                             [####....................] 5.07 MB 5.6%
🔴 Other installed packages        [##############..........] 15.73 MB 17.2%

Runtime dependencies (2)

Package	Range	Notes
`nitro`	`3.0.260610-beta`
`undici`	`8.9.0`

Peer dependencies (5)

Package	Range	Notes
`@opentelemetry/api`	`^1.0.0`	optional peer
`ai`	`catalog:`
`braintrust`	`^3.0.0`	optional peer
`just-bash`	`^3.0.0`	optional peer
`microsandbox`	`^0.5.0`	optional peer

eve init install drill-down

`eve init` install details

Command: eve init my-agent
Package manager: npm
Installed footprint: 129.66 MB across 8523 installed files
Installed packages: 128 total (122 transitive-only)
dependencies: 4 direct packages totaling 43.12 MB
devDependencies: 2 direct packages totaling 5.04 MB
Other transitive package files: 81.50 MB

Installed footprint is measured from an isolated temporary eve init my-agent using the current packed eve tarball.

Heavy installed dependencies

@typescript/typescript-linux-x64: 27.95 MB (21.6%)
eve: 27.43 MB (21.2%)
@rolldown/binding-linux-x64-gnu: 19.28 MB (14.9%)
@rolldown/binding-wasm32-wasi: 10.66 MB (8.2%)
zod: 9.02 MB (7.0%)

Installed footprint breakdown

Installed package size
🔴 @typescript/typescript-linux-x64 [########################] 27.95 MB 21.6%
🔴 eve                              [########################] 27.43 MB 21.2%
🔴 @rolldown/binding-linux-x64-gnu  [#################.......] 19.28 MB 14.9%
🔴 @rolldown/binding-wasm32-wasi    [#########...............] 10.66 MB 8.2%
🔴 zod                              [########................] 9.02 MB 7.0%
🔴 @napi-rs/wasm-runtime            [######..................] 6.56 MB 5.1%
🔴 ai                               [######..................] 6.53 MB 5.0%
🔴 Other installed packages         [###################.....] 22.23 MB 17.1%

dependencies (4)

Package	Range	Installed size	Share
`@vercel/connect`	`0.4.2`	135.8 kB	0.1%
`ai`	`^7.0.38`	6.53 MB	5.0%
`eve`	`file:eve-0.28.0.tgz`	27.43 MB	21.2%
`zod`	`4.4.3`	9.02 MB	7.0%

devDependencies (2)

Package	Range	Installed size	Share
`@types/node`	`24.x`	2.54 MB	2.0%
`typescript`	`7.0.2`	2.50 MB	1.9%

Function Drill-Down

Payload Size Graph

Unique function payload size and share of total
🔴 functions/.well-known/workflow/v1/flow.func     [########################] 8.41 MB 50.0%
🔴 functions/__server.func                         [########################] 8.41 MB 50.0%

Top Function Payloads

🟠 functions/.well-known/workflow/v1/flow.func • 1 public route • 8.41 MB

Metric	Value
Public routes	`/.well-known/workflow/v1/flow`
Runtime	`nodejs24.x`
Handler	`index.mjs`
Payload	8.41 MB
Function files	8.41 MB across 43 files
Traced dependencies	0 B
Signal	🟠 Bundled file `index.mjs` is 2.31 MB (27.5%)

🟠 🔎 Dependency Analysis

📦 Bundled files:

Bundled file size
🟠 index.mjs                       [########################] 2.31 MB 27.5%
🟠 _chunks/runtime-artifacts.mjs   [################........] 1.59 MB 19.0%
🟡 _libs/undici.mjs                [##########..............] 980.5 kB 11.7%
🟡 _chunks/sandbox.mjs             [########................] 768.8 kB 9.1%
🟡 _libs/@ai-sdk/gateway+[...].mjs [####....................] 432.8 kB 5.1%
🟠 Other bundled files             [########################] 2.32 MB 27.6%

🧾 Vercel Config

{
  "handler": "index.mjs",
  "launcherType": "Nodejs",
  "shouldAddHelpers": false,
  "supportsResponseStreaming": true,
  "runtime": "nodejs24.x",
  "maxDuration": "max",
  "experimentalTriggers": [
    {
      "type": "queue/v2beta",
      "topic": "__eve776561746865722d6167656e74_wkf_workflow_*",
      "consumer": "default",
      "retryAfterSeconds": 5,
      "initialDelaySeconds": 0
    }
  ],
  "environment": {
    "WORKFLOW_PRECONDITION_GUARD": "1"
  }
}

🟠 functions/__server.func • 10 public routes, 1 internal alias • 8.41 MB

Metric	Value
Public routes	`/` `/eve/v1/callback/[token]` `/eve/v1/connections/[name]/callback/[token]` `/eve/v1/health` `/eve/v1/info` `/eve/v1/session` `/eve/v1/session/[sessionId]` `/eve/v1/session/[sessionId]/cancel` `/eve/v1/session/[sessionId]/stream` `/eve/v1/session/reset`
Internal aliases	`/__server`
Runtime	`nodejs24.x`
Handler	`index.mjs`
Payload	8.41 MB
Function files	8.41 MB across 43 files
Traced dependencies	0 B
Signal	🟠 Bundled file `index.mjs` is 2.31 MB (27.5%)

🟠 🔎 Dependency Analysis

📦 Bundled files:

Bundled file size
🟠 index.mjs                       [########################] 2.31 MB 27.5%
🟠 _chunks/runtime-artifacts.mjs   [################........] 1.59 MB 19.0%
🟡 _libs/undici.mjs                [##########..............] 980.5 kB 11.7%
🟡 _chunks/sandbox.mjs             [########................] 768.8 kB 9.1%
🟡 _libs/@ai-sdk/gateway+[...].mjs [####....................] 432.8 kB 5.1%
🟠 Other bundled files             [########################] 2.32 MB 27.6%

🧾 Vercel Config

{
  "handler": "index.mjs",
  "launcherType": "Nodejs",
  "shouldAddHelpers": false,
  "supportsResponseStreaming": true,
  "runtime": "nodejs24.x"
}

Build Timing: `e2e/fixtures/agent-tools-sandbox`

This is an informational timing measurement inside eve build, from preflight through publication. Output-size measurement and profile writing are excluded.

Build mode: deployable Vercel build with sandbox template prewarm included.

Build pipeline: 2.04 s -> 2.04 s (-6.0 ms) vs ben/hitl-v2-approve-cancel (b705461).
Timing is informational: shared GitHub runners are too variable for a hard timing budget.

Detailed phase timings vs `ben/hitl-v2-approve-cancel (b705461)`

Phase	Baseline	Current	Delta
`extension.check`	5.8 ms	9.9 ms	+4.1 ms
`project.resolve`	7.1 ms	9.3 ms	+2.2 ms
`workspace.create`	1.4 ms	1.3 ms	-0.1 ms
`host.prepare`	185.1 ms	168.5 ms	-16.6 ms
`vercel.service-prefix.resolve`	2.3 ms	2.7 ms	+0.4 ms
`nitro.create`	212.8 ms	216.3 ms	+3.5 ms
`sandbox.prewarm`	266.1 ms	256.5 ms	-9.6 ms
`nitro.cache.prepare`	0.3 ms	0.3 ms	0.0 ms
`nitro.prepare`	0.9 ms	1.0 ms	+0.1 ms
`nitro.public-assets`	0.8 ms	0.8 ms	0.0 ms
`nitro.prerender`	0.5 ms	0.6 ms	+0.1 ms
`nitro.bundle`	1.33 s	1.34 s	+9.3 ms
`nitro.cache.write`	0.5 ms	0.4 ms	-0.1 ms
`vercel.workflow-function.materialize`	24.0 ms	24.0 ms	0.0 ms
`agent-summary.emit`	0.6 ms	0.5 ms	-0.1 ms
`nitro.close`	0.1 ms	0.1 ms	0.0 ms
`output.publish`	3.8 ms	4.5 ms	+0.7 ms
`workspace.remove`	2.1 ms	2.2 ms	+0.1 ms

vercel

Additional Suggestions:

Object-form approval on connections is silently dropped by the resolver, so the connection's tools run without any approval gate (fail-open).

Static tools using the object-form approval ({ policy, authorizeResponse }) throw at resolution time because extractOptionalHooks requires approval to be a function.

Signed-off-by: benpankow <ben.pankow@vercel.com>

ruiconti · 2026-07-31T01:58:18Z

 ) => ApprovalStatus | Promise<ApprovalStatus>;
+
+/** Stable tool request passed to a response authorizer. */
+export interface ApprovalResponseRequest<TInput = Record<string, unknown>> {


Is this just

Suggested change

export interface ApprovalResponseRequest<TInput = Record<string, unknown>> {

export interface ApprovalRequest<TInput = Record<string, unknown>> {

?

benpankow mentioned this pull request Jul 30, 2026

feat(eve): state machine for HITL authorization #1370

Open

vercel Bot deployed to Preview – eve-docs-4759 July 30, 2026 19:50 View deployment

vercel Bot deployed to Preview – eve-docs July 30, 2026 19:51 View deployment

vercel Bot reviewed Jul 30, 2026

View reviewed changes

feat(eve): add approval response authorization API

2d4762f

Signed-off-by: benpankow <ben.pankow@vercel.com>

benpankow force-pushed the ben/hitl-v2-auth-api branch from 2ff6d83 to 2d4762f Compare July 30, 2026 20:07

vercel Bot deployed to Preview – eve-docs-4759 July 30, 2026 20:09 View deployment

vercel Bot deployed to Preview – eve-docs July 30, 2026 20:09 View deployment

benpankow marked this pull request as ready for review July 30, 2026 20:12

benpankow changed the title ~~feat(eve): add approval response authorization API~~ feat(eve): add HITL tool approval authorization API Jul 30, 2026

ruiconti reviewed Jul 31, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(eve): add HITL tool approval authorization API - #1421

feat(eve): add HITL tool approval authorization API#1421
benpankow wants to merge 1 commit into
ben/hitl-v2-approve-cancelfrom
ben/hitl-v2-auth-api

benpankow commented Jul 30, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jul 30, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 30, 2026 •

edited

Loading

Package Details

`eve init` install details

Payload Size Graph

Top Function Payloads

Uh oh!

vercel Bot left a comment

Uh oh!

ruiconti Jul 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	export interface ApprovalResponseRequest<TInput = Record<string, unknown>> {
	export interface ApprovalRequest<TInput = Record<string, unknown>> {

Uh oh!

Conversation

benpankow commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation

Uh oh!

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

Uh oh!

Uh oh!

github-actions Bot commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle + Package Summary: apps/fixtures/weather-agent

Delta vs ben/hitl-v2-approve-cancel (b705461)

eve init install

Package Details

eve init install details

Payload Size Graph

Top Function Payloads

Build Timing: e2e/fixtures/agent-tools-sandbox

Uh oh!

vercel Bot left a comment

Choose a reason for hiding this comment

Uh oh!

ruiconti Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

benpankow commented Jul 30, 2026 •

edited

Loading

vercel Bot commented Jul 30, 2026 •

edited

Loading

github-actions Bot commented Jul 30, 2026 •

edited

Loading

Bundle + Package Summary: `apps/fixtures/weather-agent`

Delta vs `ben/hitl-v2-approve-cancel (b705461)`

`eve init` install

`eve init` install details

Build Timing: `e2e/fixtures/agent-tools-sandbox`