Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): remove top-level tool auth (#192)

Allen Zhou306e14eed08e
diff --git a/.changeset/remove-top-level-tool-auth.md b/.changeset/remove-top-level-tool-auth.md
new file mode 100644
index 000000000..24a4bf7f7
--- /dev/null
+++ b/.changeset/remove-top-level-tool-auth.md
@@ -0,0 +1,5 @@
+---
+"eve": minor
+---
+
+Remove the top-level `auth` field from `defineTool()` and require tool auth providers to be passed inline to `ctx.getToken(provider)` or `ctx.requireAuth(provider)`.
diff --git a/docs/guides/auth-and-route-protection.md b/docs/guides/auth-and-route-protection.md
index 1bec79476..16afa233b 100644
--- a/docs/guides/auth-and-route-protection.md
+++ b/docs/guides/auth-and-route-protection.md
@@ -313,16 +313,14 @@ const githubAuth = connect({
The tool's `ctx` exposes provider-scoped auth accessors:
-- `ctx.getToken(provider, options?)` resolves an inline provider such as `connect("github/myagent")`. It uses the same cache, callback, and sign-in machinery as connection auth, scoped to that provider instead of the tool's legacy top-level `auth`.
+- `ctx.getToken(provider, options?)` resolves an inline provider such as `connect("github/myagent")`. It uses the same cache, callback, and sign-in machinery as connection auth, scoped to that provider's tool-qualified auth key.
- `ctx.requireAuth(provider, options?)` evicts the cached token for that inline provider and starts a fresh authorization challenge. Use it after a downstream `401` rejects a token returned by `ctx.getToken(provider)`.
Throw `ConnectionAuthorizationRequiredError` from an inline provider's `getToken` to trigger the consent flow for that provider. If a downstream request later rejects an already-resolved token, call `ctx.requireAuth(provider)` to evict and re-authorize it.
Vercel Connect providers usually supply their own display name in the authorization challenge. Set `displayName` in the inline options only when you need to override what users see, for example `ctx.getToken(customAuth, { displayName: "Salesforce" })`. It is presentation-only.
-Inline providers derive a stable tool-qualified auth key from Vercel Connect metadata when available. If you pass multiple custom providers that do not carry provider metadata, give each one an explicit auth key, for example `ctx.getToken(auth, { authKey: "github" })`. This `authKey` controls Eve's cache and callback keys; it is not an OAuth scope.
-
-Older tools may still declare a top-level `auth` field and call `ctx.getToken()` or `ctx.requireAuth()` without arguments. That compatibility path is deprecated; prefer inline providers for new tools.
+Inline providers derive a stable tool-qualified auth key from Vercel Connect metadata when available. If you pass multiple custom providers that do not carry provider metadata, give each one an explicit auth key, for example `ctx.getToken(auth, { authKey: "github" })`. This `authKey` controls eve's cache and callback keys; it is not an OAuth scope.
## What to read next
diff --git a/docs/reference/typescript-api.md b/docs/reference/typescript-api.md
index 2e28bc6c1..53abdb789 100644
--- a/docs/reference/typescript-api.md
+++ b/docs/reference/typescript-api.md
@@ -63,8 +63,6 @@ A few non-`define*` helpers round out the set: `disableTool` and `ExperimentalWo
| `ctx.getSkill(identifier)` | Handle for a named skill visible to the current agent |
| `ctx.getToken(provider)` | Resolve a bearer token for an inline auth provider such as `connect("...")` |
| `ctx.requireAuth(provider)` | Evict and re-authorize an inline provider, commonly after a downstream `401` |
-| `ctx.getToken()` | Deprecated compatibility path for a tool's legacy top-level `auth` |
-| `ctx.requireAuth()` | Deprecated compatibility path for a tool's legacy top-level `auth` |
## Imports at a glance
diff --git a/packages/eve/src/execution/node-step.ts b/packages/eve/src/execution/node-step.ts
index 0da52e598..060eda031 100644
--- a/packages/eve/src/execution/node-step.ts
+++ b/packages/eve/src/execution/node-step.ts
@@ -210,7 +210,6 @@ function resolveHarnessToolDefinition(input: {
approvalKey: def.approvalKey,
description: def.description,
execute: resolveAuthoredExecute({
- auth: def.auth,
isFrameworkTool,
rawExecute,
scope: def.name,
@@ -230,18 +229,16 @@ function resolveHarnessToolDefinition(input: {
* manage their own context and never receive an authored
* {@link ToolContext}.
* - Authored tools are wrapped by {@link createToolExecuteWithAuth},
- * which builds a token-aware context. Top-level `auth` drives the
- * interactive consent flow scoped to the tool name; inline providers
- * passed to `ctx.getToken(provider)` use their own derived scopes.
+ * which builds a token-aware context. Providers passed to
+ * `ctx.getToken(provider)` use tool-qualified auth scopes.
* - Tools without `execute` (provider-managed) stay `undefined`.
*/
function resolveAuthoredExecute(input: {
- readonly auth: ResolvedToolDefinition["auth"];
readonly isFrameworkTool: boolean;
readonly rawExecute: ResolvedToolDefinition["execute"];
readonly scope: string;
}): HarnessToolDefinition["execute"] {
- const { auth, isFrameworkTool, rawExecute, scope } = input;
+ const { isFrameworkTool, rawExecute, scope } = input;
if (rawExecute === undefined) {
return undefined;
}
@@ -249,7 +246,7 @@ function resolveAuthoredExecute(input: {
return rawExecute;
}
const authored = rawExecute as (toolInput: unknown, ctx: unknown) => unknown;
- return createToolExecuteWithAuth({ execute: authored, scope, topLevelAuth: auth });
+ return createToolExecuteWithAuth({ execute: authored, scope });
}
function maybeJsonSchema(
diff --git a/packages/eve/src/execution/tool-auth.integration.test.ts b/packages/eve/src/execution/tool-auth.integration.test.ts
index 40c3980ed..2c5d8a3c6 100644
--- a/packages/eve/src/execution/tool-auth.integration.test.ts
+++ b/packages/eve/src/execution/tool-auth.integration.test.ts
@@ -52,26 +52,16 @@ function seedUserPrincipal(): void {
});
}
-function authTool(input: {
- readonly name: string;
- readonly auth: AuthorizationDefinition;
- readonly execute: (toolInput: unknown, ctx: ToolContext) => unknown;
-}): ResolvedToolDefinition {
- return authoredTool(input);
-}
-
function authoredTool(input: {
readonly name: string;
- readonly auth?: AuthorizationDefinition;
readonly execute: (toolInput: unknown, ctx: ToolContext) => unknown;
}): ResolvedToolDefinition {
const logicalPath = `tools/${input.name}.ts`;
- const base: ResolvedToolDefinition = {
+ return {
description: `${input.name} auth tool.`,
execute: createToolExecuteWithAuth({
execute: input.execute as (toolInput: unknown, ctx: unknown) => unknown,
scope: input.name,
- topLevelAuth: input.auth,
}),
inputSchema: null,
logicalPath,
@@ -79,11 +69,10 @@ function authoredTool(input: {
sourceId: logicalPath,
sourceKind: "module",
};
- return input.auth === undefined ? base : { ...base, auth: input.auth };
}
describe("tool-hosted authorization", () => {
- it("resolves and caches the bearer through ctx.getToken()", async () => {
+ it("resolves and caches the bearer through ctx.getToken(provider)", async () => {
let calls = 0;
const auth: AuthorizationDefinition = {
principalType: "app",
@@ -92,12 +81,11 @@ describe("tool-hosted authorization", () => {
return { token: `tok-${calls}` };
},
};
- const tool = authTool({
+ const tool = authoredTool({
name: "list_groups",
- auth,
async execute(_input, ctx) {
- const first = await ctx.getToken();
- const second = await ctx.getToken();
+ const first = await ctx.getToken(auth);
+ const second = await ctx.getToken(auth);
return { first: first.token, second: second.token };
},
});
@@ -190,18 +178,18 @@ describe("tool-hosted authorization", () => {
).rejects.toThrow(/explicit auth keys/);
});
- it("keeps no-arg ctx.getToken() guarded on tools without top-level auth", async () => {
+ it("rejects no-provider token access at runtime", async () => {
const tool = authoredTool({
name: "plain_tool",
async execute(_input, ctx) {
- return await ctx.getToken();
+ return await (ctx.getToken as () => Promise<TokenResult>)();
},
});
const runtime = createTestRuntime({ tools: [tool] });
await expect(
runtime.runAsSession(undefined, async () => runtime.executeTool(tool, {})),
- ).rejects.toThrow(/does not declare an "auth" strategy/);
+ ).rejects.toThrow(/Pass an auth provider/);
});
it("parks the turn with a challenge for an inline provider", async () => {
@@ -257,11 +245,10 @@ describe("tool-hosted authorization", () => {
return { token: "after-signin" };
},
};
- const tool = authTool({
+ const tool = authoredTool({
name: "list_groups",
- auth,
async execute(_input, ctx) {
- return await ctx.getToken();
+ return await ctx.getToken(auth);
},
});
const runtime = createTestRuntime({ tools: [tool] });
@@ -276,12 +263,12 @@ describe("tool-hosted authorization", () => {
if (!isAuthorizationSignal(result)) throw new Error("expected signal");
expect(result.challenges).toHaveLength(1);
expect(result.challenges[0]).toMatchObject({
- name: "list_groups",
+ name: "list_groups__inline_auth",
challenge: { url: "https://idp.example/auth" },
});
});
- it("stamps the definition-level displayName onto the challenge, winning over the strategy's", async () => {
+ it("stamps the provider displayName onto the challenge, winning over the strategy's", async () => {
const auth: AuthorizationDefinition = {
displayName: "Salesforce",
principalType: "user",
@@ -297,11 +284,10 @@ describe("tool-hosted authorization", () => {
return { token: "after-signin" };
},
};
- const tool = authTool({
+ const tool = authoredTool({
name: "sfdc_lookup",
- auth,
async execute(_input, ctx) {
- return await ctx.getToken();
+ return await ctx.getToken(auth);
},
});
const runtime = createTestRuntime({ tools: [tool] });
@@ -316,7 +302,7 @@ describe("tool-hosted authorization", () => {
if (!isAuthorizationSignal(result)) throw new Error("expected signal");
// Identity stays the path-derived scope; only the presentation name changes.
expect(result.challenges[0]).toMatchObject({
- name: "sfdc_lookup",
+ name: "sfdc_lookup__inline_auth",
challenge: { displayName: "Salesforce", url: "https://idp.example/auth" },
});
});
@@ -334,11 +320,10 @@ describe("tool-hosted authorization", () => {
return { token: "after-signin" };
},
};
- const tool = authTool({
+ const tool = authoredTool({
name: "sfdc_lookup",
- auth,
async execute(_input, ctx) {
- return await ctx.getToken();
+ return await ctx.getToken(auth);
},
});
const runtime = createTestRuntime({ tools: [tool] });
@@ -357,7 +342,7 @@ describe("tool-hosted authorization", () => {
expect(result.challenges[0]?.challenge).toMatchObject({ displayName: "Salesforce" });
});
- it("parks the turn when the tool calls ctx.requireAuth()", async () => {
+ it("parks the turn when the tool calls ctx.requireAuth(provider)", async () => {
const auth: AuthorizationDefinition = {
principalType: "user",
async getToken(): Promise<TokenResult> {
@@ -370,11 +355,10 @@ describe("tool-hosted authorization", () => {
return { token: "after-signin" };
},
};
- const tool = authTool({
+ const tool = authoredTool({
name: "gated_tool",
- auth,
execute(_input, ctx) {
- ctx.requireAuth();
+ ctx.requireAuth(auth);
},
});
const runtime = createTestRuntime({ tools: [tool] });
@@ -406,11 +390,10 @@ describe("tool-hosted authorization", () => {
return { token: "minted" };
},
};
- const tool = authTool({
+ const tool = authoredTool({
name: "list_groups",
- auth,
async execute(_input, ctx) {
- return await ctx.getToken();
+ return await ctx.getToken(auth);
},
});
const runtime = createTestRuntime({ tools: [tool] });
@@ -420,7 +403,7 @@ describe("tool-hosted authorization", () => {
loadContext().set(CallbackBaseUrlKey, "https://app.example");
loadContext().set(PendingAuthorizationResultKey, [
{
- name: "list_groups",
+ name: "list_groups__inline_auth",
hookUrl: "https://app.example/callback",
callback: {
params: { code: "abc" },
@@ -535,14 +518,13 @@ describe("tool-hosted authorization", () => {
return { token: "rejected" };
},
};
- const tool = authTool({
+ const tool = authoredTool({
name: "list_groups",
- auth,
async execute(_input, ctx) {
// The token resolves, but the downstream service rejects it —
// the tool re-signals Required the same turn it signed in.
- await ctx.getToken();
- throw requiredError();
+ await ctx.getToken(auth);
+ ctx.requireAuth(auth);
},
});
const runtime = createTestRuntime({ tools: [tool] });
@@ -553,7 +535,7 @@ describe("tool-hosted authorization", () => {
loadContext().set(CallbackBaseUrlKey, "https://app.example");
loadContext().set(PendingAuthorizationResultKey, [
{
- name: "list_groups",
+ name: "list_groups__inline_auth",
hookUrl: "https://app.example/callback",
callback: {
params: { code: "abc" },
@@ -684,11 +666,10 @@ describe("tool-hosted authorization", () => {
return { token: "after-signin" };
},
};
- const tool = authTool({
+ const tool = authoredTool({
name: "list_groups",
- auth,
async execute(_input, ctx) {
- return await ctx.getToken();
+ return await ctx.getToken(auth);
},
});
const runtime = createTestRuntime({ tools: [tool] });
@@ -717,11 +698,10 @@ describe("tool-hosted authorization", () => {
throw requiredError();
},
};
- const tool = authTool({
+ const tool = authoredTool({
name: "list_keys",
- auth,
async execute(_input, ctx) {
- return await ctx.getToken();
+ return await ctx.getToken(auth);
},
});
const runtime = createTestRuntime({ tools: [tool] });
diff --git a/packages/eve/src/execution/tool-auth.ts b/packages/eve/src/execution/tool-auth.ts
index f3fbfcdb1..0b63839be 100644
--- a/packages/eve/src/execution/tool-auth.ts
+++ b/packages/eve/src/execution/tool-auth.ts
@@ -1,11 +1,12 @@
/**
- * Tool-hosted authorization wiring for authored tools that declare
- * `auth` on {@link defineTool}.
+ * Tool-hosted authorization wiring for authored tools that resolve auth
+ * providers inline with {@link ToolContext.getToken} and
+ * {@link ToolContext.requireAuth}.
*
* Mirrors the connection authorization flow (see
* `runtime/framework-tools/connection-search-dynamic.ts`) but scopes the
* per-step token cache and framework-owned callback URL by the tool's
- * path-derived name instead of a connection name. All the shared
+ * path-derived name and provider key instead of a connection name. All the shared
* machinery — principal resolution, cache reads/writes, the park/resume
* webhook dance, and the loop guard — lives in
* `runtime/connections/scoped-authorization.ts`; this module is the thin
@@ -35,62 +36,28 @@ import {
} from "#runtime/connections/scoped-authorization.js";
/**
- * Wraps one authored tool's `execute` with the tool-hosted
- * authorization flow.
+ * Wraps one authored tool's `execute` with a context that supports inline
+ * provider auth (`ctx.getToken(connect("..."))`).
*
- * Each invocation:
- * 1. Completes an authorization whose OAuth callback arrived this turn,
- * caching the freshly minted token (the loop-guard flag).
- * 2. Runs the authored `execute` with a {@link ToolContext} whose
- * `getToken()` / `requireAuth()` are bound to this tool's scope.
- * 3. On a thrown `ConnectionAuthorizationRequiredError` — implicit from
- * `getToken()` or explicit via `requireAuth()` — either fails
- * terminally (token rejected immediately after sign-in) or evicts the
- * rejected token from the per-step cache and starts the interactive
- * flow, returning an `AuthorizationSignal` to park the turn. An
- * interactive strategy never rethrows the raw `Required` into the
- * model: if no callback URL can be minted it fails with a classified
- * {@link ConnectionAuthorizationFailedError} instead. Only
- * non-interactive strategies rethrow the original error, since they
- * have no consent flow to park on.
- */
-export function createAuthorizedToolExecute(input: {
- readonly scope: string;
- readonly auth: AuthorizationDefinition;
- readonly execute: (toolInput: unknown, ctx: unknown) => unknown;
-}): (toolInput: unknown) => Promise<unknown> {
- return createToolExecuteWithAuth({
- execute: input.execute,
- scope: input.scope,
- topLevelAuth: input.auth,
- });
-}
-
-/**
- * Wraps one authored tool's `execute` with a context that supports both
- * top-level tool auth (`ctx.getToken()`) and inline provider auth
- * (`ctx.getToken(connect("..."))`).
+ * On a thrown provider-scoped authorization request — implicit from
+ * `ctx.getToken(provider)` or explicit via `ctx.requireAuth(provider)` — the
+ * wrapper either fails terminally (token rejected immediately after sign-in)
+ * or evicts the rejected token from the per-step cache and starts the
+ * interactive flow, returning an `AuthorizationSignal` to park the turn.
+ * Interactive strategies never rethrow the raw `Required` into the model: if
+ * no callback URL can be minted, they fail with a classified
+ * {@link ConnectionAuthorizationFailedError} instead. Non-interactive
+ * strategies rethrow the original error because they have no consent flow to
+ * park on.
*/
export function createToolExecuteWithAuth(input: {
readonly scope: string;
readonly execute: (toolInput: unknown, ctx: unknown) => unknown;
- readonly topLevelAuth?: AuthorizationDefinition;
}): (toolInput: unknown) => Promise<unknown> {
- const { scope, execute, topLevelAuth } = input;
- const topLevelScoped: ScopedAuthorization | undefined =
- topLevelAuth === undefined
- ? undefined
- : {
- authorization: topLevelAuth,
- connection: { url: "" },
- scope,
- };
+ const { scope, execute } = input;
return async (toolInput: unknown): Promise<unknown> => {
const justAuthorizedScopes = new Set<string>();
- if (topLevelScoped !== undefined && (await completeScopedAuthorization(topLevelScoped))) {
- justAuthorizedScopes.add(topLevelScoped.scope);
- }
try {
return await execute(
@@ -99,7 +66,6 @@ export function createToolExecuteWithAuth(input: {
inlineAuthState: {},
justAuthorizedScopes,
scope,
- topLevelScoped,
}),
);
} catch (err) {
@@ -107,50 +73,22 @@ export function createToolExecuteWithAuth(input: {
return await handleAuthorizationRequests(err.requests);
}
- if (topLevelScoped !== undefined && isConnectionAuthorizationRequiredError(err)) {
- return await handleAuthorizationRequests([
- {
- cause: err,
- justAuthorized: justAuthorizedScopes.has(topLevelScoped.scope),
- scoped: topLevelScoped,
- },
- ]);
- }
-
throw err;
}
};
}
-/**
- * Builds the {@link ToolContext} for an authored tool without top-level
- * `auth`. No-arg token accessors throw, but provider-scoped accessors
- * still work.
- */
-export function buildUnauthorizedToolContext(scope: string): ToolContext {
- return buildToolContext({
- inlineAuthState: {},
- justAuthorizedScopes: new Set<string>(),
- scope,
- });
-}
-
function buildToolContext(input: {
readonly scope: string;
- readonly topLevelScoped?: ScopedAuthorization;
readonly justAuthorizedScopes: Set<string>;
readonly inlineAuthState: InlineAuthState;
}): ToolContext {
- const { scope, topLevelScoped, justAuthorizedScopes, inlineAuthState } = input;
+ const { scope, justAuthorizedScopes, inlineAuthState } = input;
const base = buildCallbackContext();
return {
...base,
async getToken(provider?: ToolAuthProvider, options?: ToolAuthOptions): Promise<TokenResult> {
- if (provider === undefined) {
- if (topLevelScoped === undefined) throw noAuthError(scope);
- return resolveScopedToken(topLevelScoped);
- }
-
+ if (provider === undefined) throw missingProviderError("ctx.getToken");
return await resolveInlineToken({
inlineAuthState,
justAuthorizedScopes,
@@ -160,11 +98,7 @@ function buildToolContext(input: {
});
},
requireAuth(provider?: ToolAuthProvider, options?: ToolAuthOptions): never {
- if (provider === undefined) {
- if (topLevelScoped === undefined) throw noAuthError(scope);
- throw new ConnectionAuthorizationRequiredError(topLevelScoped.scope);
- }
-
+ if (provider === undefined) throw missingProviderError("ctx.requireAuth");
const scoped = buildInlineScopedAuthorization({
inlineAuthState,
options,
@@ -371,9 +305,8 @@ function isToolAuthorizationRequiredError(err: unknown): err is ToolAuthorizatio
return err instanceof Error && err.name === "ToolAuthorizationRequiredError";
}
-function noAuthError(scope: string): Error {
+function missingProviderError(method: "ctx.getToken" | "ctx.requireAuth"): Error {
return new Error(
- `Tool "${scope}" called ctx.getToken()/ctx.requireAuth() without a provider but does not declare an "auth" strategy. ` +
- `Add \`auth\` to the tool definition or pass a provider like \`ctx.getToken(connect("..."))\`.`,
+ `${method}: Pass an auth provider, for example ${method}(connect("github/myagent")).`,
);
}
diff --git a/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.ts b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.ts
index 715fd2be3..9a54d8584 100644
--- a/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.ts
+++ b/packages/eve/src/internal/nitro/routes/agent-info/build-agent-info-response.ts
@@ -432,7 +432,7 @@ export function renderTool(
return {
...toSource(tool),
description: tool.description,
- hasAuth: tool.auth !== undefined,
+ hasAuth: false,
hasExecute: tool.execute !== undefined,
hasModelOutputProjection: tool.toModelOutput !== undefined,
hasOutputSchema: tool.outputSchema !== undefined && tool.outputSchema !== null,
diff --git a/packages/eve/src/public/definitions/exact.test.ts b/packages/eve/src/public/definitions/exact.test.ts
index 02f47238e..5472c0f1b 100644
--- a/packages/eve/src/public/definitions/exact.test.ts
+++ b/packages/eve/src/public/definitions/exact.test.ts
@@ -195,6 +195,20 @@ function typeOnlyFixtures(): void {
return { ok: true, typedCity };
},
});
+
+ defineTool({
+ description: "Removed top-level tool auth.",
+ inputSchema: { type: "object" },
+ // @ts-expect-error Tool auth providers must be passed inline to ctx.getToken(provider).
+ auth: {
+ async getToken() {
+ return { token: "static" };
+ },
+ },
+ execute() {
+ return null;
+ },
+ });
}
void typeOnlyFixtures;
diff --git a/packages/eve/src/public/definitions/tool-auth.test.ts b/packages/eve/src/public/definitions/tool-auth.test.ts
index f2d2fa7fe..d1072ad07 100644
--- a/packages/eve/src/public/definitions/tool-auth.test.ts
+++ b/packages/eve/src/public/definitions/tool-auth.test.ts
@@ -1,162 +1,20 @@
import { describe, expect, it } from "vitest";
import { defineTool } from "#public/definitions/tool.js";
-import type { TokenResult } from "#runtime/connections/types.js";
-/**
- * Unit coverage for the `auth` field on {@link defineTool}: the
- * authored shape is normalized into the runtime authorization contract
- * at definition time, mirroring connection `auth` normalization.
- */
-describe("defineTool auth normalization", () => {
- it("defaults a getToken-only strategy to principalType app", () => {
- const tool = defineTool({
+describe("defineTool auth field", () => {
+ it("rejects top-level auth at runtime", () => {
+ const definition = {
description: "Static-token tool.",
inputSchema: { type: "object" },
auth: {
- async getToken(): Promise<TokenResult> {
+ async getToken(): Promise<{ token: string }> {
return { token: "static" };
},
},
execute: () => null,
- });
+ };
- expect(tool.auth).toMatchObject({ principalType: "app" });
- expect(typeof tool.auth?.getToken).toBe("function");
- });
-
- it("preserves an interactive strategy as principalType user", () => {
- const tool = defineTool({
- description: "Interactive tool.",
- inputSchema: { type: "object" },
- auth: {
- principalType: "user",
- async getToken(): Promise<TokenResult> {
- return { token: "live" };
- },
- async startAuthorization() {
- return { challenge: { url: "https://idp.example/auth" }, state: {} };
- },
- async completeAuthorization(): Promise<TokenResult> {
- return { token: "live" };
- },
- },
- execute: () => null,
- });
-
- expect(tool.auth).toMatchObject({ principalType: "user" });
- expect(typeof tool.auth?.startAuthorization).toBe("function");
- expect(typeof tool.auth?.completeAuthorization).toBe("function");
- });
-
- it("retains the vercelConnect marker attached by connect()", () => {
- const tool = defineTool({
- description: "Connect-backed tool.",
- inputSchema: { type: "object" },
- auth: {
- principalType: "user",
- vercelConnect: { connector: "okta" },
- async getToken(): Promise<TokenResult> {
- return { token: "live" };
- },
- async startAuthorization() {
- return { challenge: { url: "https://idp.example/auth" }, state: {} };
- },
- async completeAuthorization(): Promise<TokenResult> {
- return { token: "live" };
- },
- },
- execute: () => null,
- });
-
- expect(tool.auth).toMatchObject({ vercelConnect: { connector: "okta" } });
- });
-
- it("retains the provider cache eviction hook", () => {
- const evict = async () => {};
- const tool = defineTool({
- description: "Connect-backed tool.",
- inputSchema: { type: "object" },
- auth: {
- evict,
- principalType: "user",
- async getToken(): Promise<TokenResult> {
- return { token: "live" };
- },
- async startAuthorization() {
- return { challenge: { url: "https://idp.example/auth" }, resume: {} };
- },
- async completeAuthorization(): Promise<TokenResult> {
- return { token: "live" };
- },
- },
- execute: () => null,
- });
-
- expect(tool.auth?.evict).toBe(evict);
- });
-
- it("retains the authored displayName", () => {
- const tool = defineTool({
- description: "Branded tool.",
- inputSchema: { type: "object" },
- auth: {
- displayName: "Salesforce",
- async getToken(): Promise<TokenResult> {
- return { token: "static" };
- },
- },
- execute: () => null,
- });
-
- expect(tool.auth).toMatchObject({ displayName: "Salesforce", principalType: "app" });
- });
-
- it("rejects an empty displayName", () => {
- expect(() =>
- defineTool({
- description: "Mislabeled tool.",
- inputSchema: { type: "object" },
- auth: {
- displayName: "",
- async getToken(): Promise<TokenResult> {
- return { token: "static" };
- },
- },
- execute: () => null,
- }),
- ).toThrow(/displayName/);
- });
-
- it("rejects an auth object missing getToken", () => {
- expect(() =>
- defineTool({
- description: "Broken tool.",
- inputSchema: { type: "object" },
- // @ts-expect-error - getToken is required on the auth contract.
- auth: {},
- execute: () => null,
- }),
- ).toThrow(/getToken/);
- });
-
- it("rejects a half-declared interactive strategy", () => {
- expect(() =>
- defineTool({
- description: "Half-interactive tool.",
- inputSchema: { type: "object" },
- // @ts-expect-error - startAuthorization without completeAuthorization is invalid.
- auth: {
- principalType: "user",
- async getToken(): Promise<TokenResult> {
- return { token: "live" };
- },
- async startAuthorization() {
- return { challenge: {}, state: {} };
- },
- },
- execute: () => null,
- }),
- ).toThrow(/startAuthorization|completeAuthorization/);
+ expect(() => defineTool(definition as never)).toThrow(/"auth" field is no longer supported/);
});
});
diff --git a/packages/eve/src/public/definitions/tool.ts b/packages/eve/src/public/definitions/tool.ts
index 007e6f89c..4806cf715 100644
--- a/packages/eve/src/public/definitions/tool.ts
+++ b/packages/eve/src/public/definitions/tool.ts
@@ -10,7 +10,6 @@ import type {
NonInteractiveAuthorizationDefinition,
TokenResult,
} from "#runtime/connections/types.js";
-import { normalizeAuthorizationSpec } from "#runtime/connections/validate-authorization.js";
import {
DYNAMIC_SENTINEL_KIND,
TOOL_BRAND,
@@ -38,8 +37,9 @@ export interface NeedsApprovalContext<TInput = Record<string, unknown>> {
export type { ToolModelOutput } from "#shared/tool-definition.js";
/**
- * Authorization strategy declared on a {@link ToolDefinition} via the
- * `auth` field. Accepts the same shapes as a connection's `auth`:
+ * Authorization provider passed to {@link ToolContext.getToken} or
+ * {@link ToolContext.requireAuth}. Accepts the same shapes as a connection's
+ * `auth`:
* - a `getToken`-only object (static API keys, pre-provisioned JWTs);
* `principalType` may be omitted and defaults to `"app"`.
* - a full interactive OAuth definition (e.g. `connect("okta/myagent")` from
@@ -84,42 +84,14 @@ export interface ToolAuthOptions {
*
* Extends {@link SessionContext} with token accessors. Passing a provider
* resolves that provider inline, which lets one tool use multiple credentials.
- * For backwards compatibility, calling the accessors without a provider uses
- * the tool's deprecated top-level `auth` field and throws when no `auth` exists.
*/
export type ToolContext = SessionContext & {
- /**
- * Resolves the bearer token for this tool's declared `auth`,
- * consulting the per-step token cache before invoking the authored
- * `getToken`. For interactive strategies a cache miss throws
- * `ConnectionAuthorizationRequiredError`; the runtime catches it,
- * suspends the turn on a framework-owned callback URL, shows a
- * "Sign in" affordance, and re-runs the tool after the OAuth
- * callback completes.
- *
- * Throws when the tool does not declare an `auth` strategy.
- *
- * @deprecated Prefer `ctx.getToken(provider)` so auth dependencies live at
- * the call site and compose when a tool needs multiple credentials.
- */
- getToken(): Promise<TokenResult>;
/**
* Resolves the bearer token for an inline provider. This accepts the same
* auth shapes as a connection's `auth` field, including `connect("...")`
* from `@vercel/connect/eve`.
*/
getToken(provider: ToolAuthProvider, options?: ToolAuthOptions): Promise<TokenResult>;
- /**
- * Signals that the caller must complete this tool's authorization flow.
- * Throws `ConnectionAuthorizationRequiredError`, which the runtime converts
- * into a consent prompt (for interactive strategies) and re-runs the tool
- * after sign-in. Use it after a downstream request rejects a token returned
- * by the deprecated no-argument {@link getToken}.
- *
- * @deprecated Prefer `ctx.requireAuth(provider)` so auth dependencies live at
- * the call site and compose when a tool needs multiple credentials.
- */
- requireAuth(): never;
/**
* Signals that the caller must complete authorization for an inline
* provider before proceeding. Use this after a downstream `401` rejects a
@@ -140,16 +112,6 @@ export type ToolDefinition<TInput = unknown, TOutput = unknown> = PublicToolDefi
TOutput
> & {
execute(input: TInput, ctx: ToolContext): Promise<TOutput> | TOutput;
- /**
- * Optional authorization strategy used by the deprecated no-argument
- * {@link ToolContext.getToken} / {@link ToolContext.requireAuth} accessors.
- *
- * @deprecated Prefer passing a provider at the call site:
- * `ctx.getToken(connect("..."))` or `ctx.requireAuth(connect("..."))`.
- * Inline providers use the same auth shapes and compose when a tool needs
- * multiple credentials.
- */
- auth?: ToolAuthDefinition;
/**
* Optional per-tool approval gate. The return value determines whether
* user approval is required before executing this tool.
@@ -201,8 +163,6 @@ export function defineTool<
unknown,
StandardJSONSchemaV1.InferOutput<TOutputSchema>
>["toModelOutput"];
- /** @deprecated Prefer inline providers via `ctx.getToken(provider)`. */
- auth?: ToolAuthDefinition;
}): ToolDefinition<
StandardJSONSchemaV1.InferOutput<TInputSchema>,
StandardJSONSchemaV1.InferOutput<TOutputSchema>
@@ -223,8 +183,6 @@ export function defineTool<
unknown
>["needsApproval"];
toModelOutput?: ToolDefinition<unknown, TOutput>["toModelOutput"];
- /** @deprecated Prefer inline providers via `ctx.getToken(provider)`. */
- auth?: ToolAuthDefinition;
}): ToolDefinition<StandardJSONSchemaV1.InferOutput<TSchema>, TOutput>;
export function defineTool<
TOutputSchema extends StandardJSONSchemaV1<unknown, unknown>,
@@ -243,8 +201,6 @@ export function defineTool<
unknown,
StandardJSONSchemaV1.InferOutput<TOutputSchema>
>["toModelOutput"];
- /** @deprecated Prefer inline providers via `ctx.getToken(provider)`. */
- auth?: ToolAuthDefinition;
}): ToolDefinition<Record<string, unknown>, StandardJSONSchemaV1.InferOutput<TOutputSchema>>;
export function defineTool<TOutput>(definition: {
description: ToolDefinition<unknown, unknown>["description"];
@@ -253,8 +209,6 @@ export function defineTool<TOutput>(definition: {
execute(input: Record<string, unknown>, ctx: ToolContext): Promise<TOutput> | TOutput;
needsApproval?: ToolDefinition<Record<string, unknown>, unknown>["needsApproval"];
toModelOutput?: ToolDefinition<unknown, TOutput>["toModelOutput"];
- /** @deprecated Prefer inline providers via `ctx.getToken(provider)`. */
- auth?: ToolAuthDefinition;
}): ToolDefinition<Record<string, unknown>, TOutput>;
export function defineTool<TInput = unknown, TOutput = unknown>(
definition: ToolDefinition<TInput, TOutput>,
@@ -262,8 +216,11 @@ export function defineTool<TInput = unknown, TOutput = unknown>(
export function defineTool<TInput = unknown, TOutput = unknown>(
definition: ToolDefinition<TInput, TOutput>,
): ToolDefinition<TInput, TOutput> {
- if (definition.auth !== undefined) {
- definition.auth = normalizeAuthorizationSpec(definition.auth, "defineTool:");
+ if ((definition as { readonly auth?: unknown }).auth !== undefined) {
+ throw new Error(
+ `defineTool: The "auth" field is no longer supported. ` +
+ `Pass auth providers inline to ctx.getToken(provider) or ctx.requireAuth(provider).`,
+ );
}
Object.assign(definition, { [TOOL_BRAND]: true });
stampDefinitionKey(definition, `tool:${definition.description}`);
diff --git a/packages/eve/src/runtime/resolve-tool.ts b/packages/eve/src/runtime/resolve-tool.ts
index 2ff4fc50e..c25e5e698 100644
--- a/packages/eve/src/runtime/resolve-tool.ts
+++ b/packages/eve/src/runtime/resolve-tool.ts
@@ -6,7 +6,6 @@ import { expectFunction, expectObjectRecord } from "#internal/authored-module.js
import { registerDefinitionSource, stampDefinitionKey } from "#public/tool-result-narrowing.js";
import { toErrorMessage } from "#shared/errors.js";
import { loadResolvedModuleExport, ResolveAgentError } from "#runtime/resolve-helpers.js";
-import { normalizeAuthorizationSpec } from "#runtime/connections/validate-authorization.js";
import type { ResolvedToolDefinition } from "#runtime/types.js";
/**
@@ -89,8 +88,7 @@ type OptionalResolvedFields = {
| "needsApproval"
| "toModelOutput"
| "inputStandardSchema"
- | "outputStandardSchema"
- | "auth"]?: ResolvedToolDefinition[K];
+ | "outputStandardSchema"]?: ResolvedToolDefinition[K];
};
/**
@@ -126,13 +124,6 @@ function extractOptionalHooks(
optional.outputStandardSchema = record.outputSchema;
}
- if (record.auth !== undefined) {
- optional.auth = normalizeAuthorizationSpec(
- record.auth,
- `${describe(definition, "to provide a valid auth object")}:`,
- );
- }
-
return optional;
}
diff --git a/packages/eve/src/runtime/types.ts b/packages/eve/src/runtime/types.ts
index 514c3b882..9f4de01b6 100644
--- a/packages/eve/src/runtime/types.ts
+++ b/packages/eve/src/runtime/types.ts
@@ -182,16 +182,6 @@ export type ResolvedToolDefinition = Readonly<
* handlers and the stream. See {@link ToolModelOutput}.
*/
readonly toModelOutput?: (output: unknown) => ToolModelOutput | Promise<ToolModelOutput>;
- /**
- * Optional authorization strategy reattached from the authored
- * module at resolve time. Carries live `getToken` /
- * `startAuthorization` / `completeAuthorization` callbacks, so it
- * cannot survive compilation and must be read off the resolved
- * module like {@link execute}. When present, the execution layer
- * builds token accessors onto the tool context and drives the
- * interactive consent flow scoped to this tool's {@link name}.
- */
- readonly auth?: AuthorizationDefinition;
};
/**