Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): add custom tool approval prompts (#3145)

Ben Pankow302a4d341059
diff --git a/.changeset/custom-approval-prompts.md b/.changeset/custom-approval-prompts.md
new file mode 100644
index 000000000..734afba0c
--- /dev/null
+++ b/.changeset/custom-approval-prompts.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Tools can now define `approval.prompt` to show a human-readable, input-aware summary in approval requests. Slack keeps the complete tool input available in a collapsed block below the approval card.
diff --git a/docs/tools/human-in-the-loop.md b/docs/tools/human-in-the-loop.md
index 156796130..c099d79f0 100644
--- a/docs/tools/human-in-the-loop.md
+++ b/docs/tools/human-in-the-loop.md
@@ -64,6 +64,28 @@ approval: auto({
A reusable approval grant applies only after every matching request that is already pending has been resolved. If several calls to a `once()`-gated tool have each produced an approval prompt, approving one does not authorize the others; each visible prompt remains an independent decision. After those pending requests are resolved, later calls in the session are allowed automatically.
+Use the object form of `approval` to replace the default `Approve <tool label>?` text with a tool-specific summary. The `prompt` callback receives the validated `input`, final `toolName`, and `callId`:
+
+```ts title="agent/tools/refund_charge.ts"
+import { defineTool } from "eve/tools";
+import { always } from "eve/tools/approval";
+import { z } from "zod";
+
+export default defineTool({
+ description: "Refund a charge.",
+ inputSchema: z.object({ chargeId: z.string(), amount: z.number() }),
+ approval: {
+ request: always(),
+ prompt: ({ input }) => `Refund $${input.amount.toFixed(2)} for charge ${input.chargeId}?`,
+ },
+ async execute(input) {
+ return refund(input);
+ },
+});
+```
+
+Channels render this prompt in their approval UI. Slack also includes the complete tool input in a collapsed **Tool input** block so an approver can inspect the original structured value.
+
When the decision depends on the input, pass your own policy instead of a helper. It receives the same session context as tool execution, plus `{ toolName, toolInput, approvedTools, callId, abortSignal }` (connection tools also get `toolAnnotations`), and returns an AI SDK 7 approval status synchronously or as a promise. Use `abortSignal` for asynchronous policy work so cancellation stops it with the turn. Use `ctx.session.auth.current` to guard by the caller of the current turn and `ctx.session.auth.initiator` to guard by the caller that created the session. Return `"user-approval"` to pause for a person or `"not-applicable"` to continue without a prompt. `toolInput` can be undefined, so guard the access. This policy denies cross-tenant calls, then requires approval only when an amount crosses a threshold:
```ts
diff --git a/packages/eve/extension-contracts/compatibility/dynamicTool/v82.ts b/packages/eve/extension-contracts/compatibility/dynamicTool/v82.ts
new file mode 100644
index 000000000..0fc92dcba
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/dynamicTool/v82.ts
@@ -0,0 +1,16 @@
+import { defineDynamic, defineTool } from "#public/tools/index.js";
+import { always } from "#public/tools/approval/index.js";
+
+// Epoch 82 dynamic tools could require approval without a presentation prompt.
+export default defineDynamic({
+ events: {
+ "session.started": () => ({
+ status: defineTool({
+ approval: always(),
+ description: "Report service status after approval.",
+ inputSchema: { type: "object", properties: {} },
+ execute: () => ({ status: "ready" }),
+ }),
+ }),
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/tool/v87.ts b/packages/eve/extension-contracts/compatibility/tool/v87.ts
new file mode 100644
index 000000000..380baf77c
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/tool/v87.ts
@@ -0,0 +1,10 @@
+import { defineTool } from "#public/tools/index.js";
+import { always } from "#public/tools/approval/index.js";
+
+// Epoch 87 tools could configure approval without a presentation prompt.
+export default defineTool({
+ approval: always(),
+ description: "Require approval before reporting the service status.",
+ inputSchema: { type: "object", properties: {}, additionalProperties: false },
+ execute: () => ({ status: "ready" }),
+});
diff --git a/packages/eve/extension-contracts/reports/dynamicTool/v83.json b/packages/eve/extension-contracts/reports/dynamicTool/v83.json
new file mode 100644
index 000000000..21d498619
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/dynamicTool/v83.json
@@ -0,0 +1,16 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "dynamicTool",
+ "epoch": 83,
+ "sha256": "eea3a366e9a536130474efcedaa9754e4919f0b0220c847f9054db39dec80432",
+ "exports": [
+ "DynamicToolEntry",
+ "DynamicToolEvents",
+ "DynamicToolResult",
+ "DynamicToolSet",
+ "auto",
+ "defineDurableCallback",
+ "defineDurableSchema",
+ "defineDynamic"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/tool/v88.json b/packages/eve/extension-contracts/reports/tool/v88.json
new file mode 100644
index 000000000..9a1818bf3
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/tool/v88.json
@@ -0,0 +1,29 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "tool",
+ "epoch": 88,
+ "sha256": "f1c245cba5517a1b52c5335428a3d64bf4f2d2269571577164305443d2a53f69",
+ "exports": [
+ "AgentRouterInput",
+ "AgentRouterTool",
+ "WorkflowStepToolContext",
+ "WorkflowTool",
+ "WorkflowToolDefinition",
+ "WorkflowToolInput",
+ "WorkflowToolOptions",
+ "agentRouter",
+ "decide",
+ "defaultWebSearch",
+ "defineTool",
+ "defineWorkflowTool",
+ "disableTool",
+ "isDisabledToolSentinel",
+ "isWebSearchToolDefinition",
+ "serializeModelInputSchema",
+ "toolOutput",
+ "toolOutputPart",
+ "toolResultFrom",
+ "webSearch",
+ "workflow"
+ ]
+}
diff --git a/packages/eve/src/approval/definition.ts b/packages/eve/src/approval/definition.ts
index bd080b586..412c23a40 100644
--- a/packages/eve/src/approval/definition.ts
+++ b/packages/eve/src/approval/definition.ts
@@ -6,6 +6,21 @@ import type { TokenResult } from "#shared/connection-types.js";
type ApprovalToolInput<TInput> = TInput extends object ? Readonly<TInput> : TInput;
+/** Context passed to an approval prompt callback. */
+export interface ApprovalPromptContext<TInput = Record<string, unknown>> {
+ /** Id of the tool call awaiting approval. */
+ readonly callId: string;
+ /** Validated input proposed for the tool call. */
+ readonly input: TInput;
+ /** Final runtime name of the tool. */
+ readonly toolName: string;
+}
+
+/** Builds the human-readable prompt shown when a tool call requires approval. */
+export type ApprovalPrompt<TInput = Record<string, unknown>> = (
+ context: ApprovalPromptContext<TInput>,
+) => string;
+
/**
* Context passed to an {@link ApprovalPolicy} function.
*
@@ -135,6 +150,19 @@ export type Approval<TInput = Record<string, unknown>> =
| ApprovalPolicy<TInput>
| ApprovalConfiguration<TInput>;
+/** Approval configuration for a tool, including its optional presentation prompt. */
+export interface ToolApprovalConfiguration<
+ TInput = Record<string, unknown>,
+> extends ApprovalConfiguration<TInput> {
+ /** Optional human-readable prompt shown when this tool requires approval. */
+ readonly prompt?: ApprovalPrompt<TInput>;
+}
+
+/** Approval definition used by authored tools. */
+export type ToolApproval<TInput = Record<string, unknown>> =
+ | ApprovalPolicy<TInput>
+ | ToolApprovalConfiguration<TInput>;
+
/** Returns the request-time policy from either approval authoring shape. */
export function resolveApprovalPolicy<TInput>(approval: Approval<TInput>): ApprovalPolicy<TInput> {
return typeof approval === "function" ? approval : approval.request;
diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.ts
index 977640287..49764ae63 100644
--- a/packages/eve/src/compiler/extension-compatibility.ts
+++ b/packages/eve/src/compiler/extension-compatibility.ts
@@ -22,10 +22,10 @@ interface ExtensionCapabilityContract {
const EXTENSION_CAPABILITY_CONTRACTS = {
extension: { current: 1, supported: [1], dropped: {} },
tool: {
- current: 87,
+ current: 88,
supported: [
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 29, 30, 31, 32, 34, 35, 76, 77, 78, 80, 81, 82, 84,
- 85, 86, 87,
+ 85, 86, 87, 88,
],
dropped: {
14: "TaskExec.delegated was removed; migrate to workflow-backed background tools",
@@ -89,10 +89,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
dynamicTool: {
- current: 82,
+ current: 83,
supported: [
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 31, 32, 33, 52, 54,
- 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 72, 73, 75, 76, 77, 78, 79, 80, 81, 82,
+ 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 72, 73, 75, 76, 77, 78, 79, 80, 81, 82, 83,
],
dropped: {
21: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
diff --git a/packages/eve/src/context/build-dynamic-tools.ts b/packages/eve/src/context/build-dynamic-tools.ts
index 7722516ab..3c9279f74 100644
--- a/packages/eve/src/context/build-dynamic-tools.ts
+++ b/packages/eve/src/context/build-dynamic-tools.ts
@@ -16,6 +16,7 @@ import { createToolExecuteWithAuth } from "#execution/tool-auth.js";
import { createLogger } from "#internal/logging.js";
import type {
ApprovalContext,
+ ApprovalPromptContext,
ApprovalResponseContext,
ApprovalResponseDecision,
ApprovalStatus,
@@ -69,28 +70,46 @@ function buildReplayedApproval(
context,
)) as ApprovalStatus;
+ const promptReference = metadata.callbacks.approvalPrompt;
+ const prompt =
+ promptReference === undefined
+ ? undefined
+ : lookupDurableDynamicCallback(owner, "approvalPrompt");
+ if (promptReference !== undefined && prompt === undefined) {
+ log.error(missingCallbackError(metadata, "approvalPrompt").message);
+ }
const responseReference = metadata.callbacks.approvalResponse;
- if (responseReference === undefined) return requestPolicy;
+ const response =
+ responseReference === undefined
+ ? undefined
+ : lookupDurableDynamicCallback(owner, "approvalResponse");
+ if (prompt === undefined && responseReference === undefined) return requestPolicy;
- const response = lookupDurableDynamicCallback(owner, "approvalResponse");
return {
request: requestPolicy,
+ prompt:
+ prompt === undefined || promptReference === undefined
+ ? undefined
+ : (context: ApprovalPromptContext) =>
+ callDurableDynamicCallback(prompt, promptReference.closure, context) as string,
response:
- response === undefined
- ? async () => {
- const error = missingCallbackError(metadata, "approvalResponse");
- log.error(error.message);
- return {
- reason: error.message,
- status: "rejected" as const,
- };
- }
- : async (context: ApprovalResponseContext) =>
- (await callDurableDynamicCallback(
- response,
- responseReference.closure,
- context,
- )) as ApprovalResponseDecision,
+ responseReference === undefined
+ ? undefined
+ : response === undefined
+ ? async () => {
+ const error = missingCallbackError(metadata, "approvalResponse");
+ log.error(error.message);
+ return {
+ reason: error.message,
+ status: "rejected" as const,
+ };
+ }
+ : async (context: ApprovalResponseContext) =>
+ (await callDurableDynamicCallback(
+ response,
+ responseReference.closure,
+ context,
+ )) as ApprovalResponseDecision,
};
}
diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
index f4b63d78f..a86c9e5fc 100644
--- a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
+++ b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
@@ -294,6 +294,26 @@ describe("durable callback capture validation", () => {
'Dynamic tool "guarded" callback "approvalRequest" does not have a durable descriptor',
);
});
+
+ it("requires a durable descriptor for an object-form approval prompt", () => {
+ const entry = defineTool({
+ approval: {
+ request: () => "user-approval" as const,
+ prompt: () => "Review this?",
+ },
+ description: "guarded tool",
+ inputSchema: { type: "object" },
+ execute: async () => null,
+ });
+ stampDurableDynamicToolCallbacks(entry, {
+ execute: { callback: () => null, closure: {} },
+ });
+ expect(() =>
+ validateDurableDynamicToolCallbacks("guarded", entry, callbackOwner("guarded")),
+ ).toThrow(
+ 'Dynamic tool "guarded" callback "approvalPrompt" does not have a durable descriptor',
+ );
+ });
});
// ---------------------------------------------------------------------------
@@ -1961,15 +1981,26 @@ describe("programmatic dynamic tools (no bundler transform)", () => {
resolverSlug: "legacy",
entryKey: "legacy:guarded",
});
- registerTestCallback("guarded", "approvalRequest", approval, {
+ const owner = {
sessionId: ctx.require(SessionIdKey),
- scope: "turn",
+ scope: "turn" as const,
resolverSlug: "legacy",
entryKey: "legacy:guarded",
- });
+ };
+ registerTestCallback(
+ "guarded",
+ "approvalPrompt",
+ (_closure, ...args) => {
+ const context = args[0] as { input: Record<string, unknown> };
+ return `Review ${String(context.input.draftId)}?`;
+ },
+ owner,
+ );
+ registerTestCallback("guarded", "approvalRequest", approval, owner);
ctx.set(TurnDynamicToolMetadataKey, [
{
callbacks: {
+ approvalPrompt: { closure: {} },
approvalRequest: { closure: {} },
execute: { closure: {} },
},
@@ -1987,6 +2018,47 @@ describe("programmatic dynamic tools (no bundler transform)", () => {
await expect(
resolveApprovalPolicy(tool.approval)(createApprovalContext({ toolName: "guarded" })),
).resolves.toBe("user-approval");
+ expect(
+ typeof tool.approval === "function"
+ ? undefined
+ : tool.approval?.prompt?.({
+ callId: "call-1",
+ input: { draftId: "draft-1" },
+ toolName: "guarded",
+ }),
+ ).toBe("Review draft-1?");
+ getDynamicCallbackRegistry().delete("guarded");
+ });
+
+ it("falls back to the default prompt when a replayed prompt callback is unavailable", () => {
+ const ctx = createCtx();
+ const owner = {
+ sessionId: ctx.require(SessionIdKey),
+ scope: "turn" as const,
+ resolverSlug: "legacy",
+ entryKey: "legacy:guarded",
+ };
+ registerTestCallback("guarded", "execute", () => ({ ok: true }), owner);
+ registerTestCallback("guarded", "approvalRequest", () => "user-approval", owner);
+ ctx.set(TurnDynamicToolMetadataKey, [
+ {
+ callbacks: {
+ approvalPrompt: { closure: {} },
+ approvalRequest: { closure: {} },
+ execute: { closure: {} },
+ },
+ description: "legacy guarded tool",
+ entryKey: "legacy:guarded",
+ inputSchema: { type: "object" },
+ name: "guarded",
+ resolverSlug: "legacy",
+ },
+ ]);
+
+ const tool = buildDynamicTools(ctx)[0];
+ expect(
+ typeof tool?.approval === "function" ? undefined : tool?.approval?.prompt,
+ ).toBeUndefined();
getDynamicCallbackRegistry().delete("guarded");
});
diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.ts b/packages/eve/src/context/dynamic-tool-lifecycle.ts
index 6e63259a3..14be07717 100644
--- a/packages/eve/src/context/dynamic-tool-lifecycle.ts
+++ b/packages/eve/src/context/dynamic-tool-lifecycle.ts
@@ -205,6 +205,7 @@ export function validateDurableDynamicToolCallbacks(
key !== "outputSchema" &&
key !== "label" &&
key !== "approvalKey" &&
+ key !== "approvalPrompt" &&
key !== "approvalRequest" &&
key !== "approvalResponse" &&
key !== "toModelOutput",
@@ -216,10 +217,12 @@ export function validateDurableDynamicToolCallbacks(
}
const hasApproval = entry.approval !== undefined;
- const hasApprovalResponse =
- entry.approval !== undefined &&
- typeof entry.approval !== "function" &&
- entry.approval.response !== undefined;
+ const approvalConfiguration =
+ entry.approval !== undefined && typeof entry.approval !== "function"
+ ? entry.approval
+ : undefined;
+ const hasApprovalPrompt = approvalConfiguration?.prompt !== undefined;
+ const hasApprovalResponse = approvalConfiguration?.response !== undefined;
const execute = validateReference({
name,
owner,
@@ -255,6 +258,13 @@ export function validateDurableDynamicToolCallbacks(
stamped: raw.approvalKey,
required: entry.approvalKey !== undefined,
});
+ const approvalPrompt = validateReference({
+ name,
+ owner,
+ phase: "approvalPrompt",
+ stamped: raw.approvalPrompt,
+ required: hasApprovalPrompt,
+ });
const approvalRequest = validateReference({
name,
owner,
@@ -302,6 +312,7 @@ export function validateDurableDynamicToolCallbacks(
start?: DurableDynamicCallbackReference;
};
approvalKey?: DurableDynamicCallbackReference;
+ approvalPrompt?: DurableDynamicCallbackReference;
approvalRequest?: DurableDynamicCallbackReference;
approvalResponse?: DurableDynamicCallbackReference;
toModelOutput?: DurableDynamicCallbackReference;
@@ -316,6 +327,7 @@ export function validateDurableDynamicToolCallbacks(
};
}
if (approvalKey !== undefined) callbacks.approvalKey = approvalKey;
+ if (approvalPrompt !== undefined) callbacks.approvalPrompt = approvalPrompt;
if (approvalRequest !== undefined) callbacks.approvalRequest = approvalRequest;
if (approvalResponse !== undefined) callbacks.approvalResponse = approvalResponse;
if (toModelOutput !== undefined) callbacks.toModelOutput = toModelOutput;
diff --git a/packages/eve/src/harness/execute-tool.ts b/packages/eve/src/harness/execute-tool.ts
index 72ca2bbd8..e939698dc 100644
--- a/packages/eve/src/harness/execute-tool.ts
+++ b/packages/eve/src/harness/execute-tool.ts
@@ -1,6 +1,6 @@
import type { FlexibleSchema } from "ai";
-import type { Approval } from "#approval/definition.js";
+import type { ToolApproval } from "#approval/definition.js";
import type {
InternalToolDefinition,
InternalToolLabelDefinition,
@@ -29,7 +29,7 @@ export interface HarnessToolDefinition {
readonly frameworkAction?: "task-cancel" | "task-wait";
readonly inputSchema: FlexibleSchema;
readonly name: string;
- readonly approval?: Approval;
+ readonly approval?: ToolApproval;
readonly outputSchema?: FlexibleSchema;
/**
* Advertise this tool only to the root session, hiding it from subagent
diff --git a/packages/eve/src/harness/input-extraction.test.ts b/packages/eve/src/harness/input-extraction.test.ts
index a1496433b..05ca2b3e8 100644
--- a/packages/eve/src/harness/input-extraction.test.ts
+++ b/packages/eve/src/harness/input-extraction.test.ts
@@ -41,6 +41,39 @@ describe("extractToolApprovalInputRequests", () => {
]);
});
+ it("uses a tool's custom approval prompt", () => {
+ const result = extractToolApprovalInputRequests({
+ content: [
+ {
+ approvalId: "approval-1",
+ toolCall: {
+ input: { amount: 125, recipient: "Ada" },
+ toolCallId: "call-1",
+ toolName: "send_payment",
+ type: "tool-call",
+ },
+ type: "tool-approval-request",
+ },
+ ],
+ tools: new Map([
+ [
+ "send_payment",
+ {
+ approval: {
+ request: () => "user-approval",
+ prompt: ({ input }) => `Send $${String(input.amount)} to ${String(input.recipient)}?`,
+ },
+ description: "Send a payment.",
+ inputSchema: {} as never,
+ name: "send_payment",
+ },
+ ],
+ ]),
+ });
+
+ expect(result[0]?.prompt).toBe("Send $125 to Ada?");
+ });
+
it("extracts an approval request from a sibling tool call", () => {
const result = extractToolApprovalInputRequests({
tools: new Map(),
diff --git a/packages/eve/src/harness/input-extraction.ts b/packages/eve/src/harness/input-extraction.ts
index 2642231a1..55602f948 100644
--- a/packages/eve/src/harness/input-extraction.ts
+++ b/packages/eve/src/harness/input-extraction.ts
@@ -89,9 +89,27 @@ function extractApprovalRequests(input: {
}
const action = createRuntimeToolCallActionFromToolCall({ toolCall });
- const label =
- projectToolStartLabel(input.tools.get(action.toolName), action.input) ??
- displayTitle(action.toolName);
+ const tool = input.tools.get(action.toolName);
+ const toolInput =
+ typeof toolCall.input === "object" &&
+ toolCall.input !== null &&
+ !Array.isArray(toolCall.input)
+ ? (toolCall.input as Record<string, unknown>)
+ : {};
+ const toolApproval = tool?.approval;
+ const prompt =
+ toolApproval === undefined || typeof toolApproval === "function"
+ ? undefined
+ : toolApproval.prompt?.({
+ callId: toolCall.toolCallId,
+ input: toolInput,
+ toolName: toolCall.toolName,
+ });
+ if (prompt !== undefined && typeof prompt !== "string") {
+ throw new Error(`Tool "${toolCall.toolName}" approval prompt must return a string.`);
+ }
+ const label = projectToolStartLabel(tool, action.input) ?? displayTitle(action.toolName);
+
requests.push({
action,
allowFreeform: false,
@@ -101,7 +119,7 @@ function extractApprovalRequests(input: {
{ id: "approve", label: "Approve" },
{ id: "cancel", label: "Cancel" },
],
- prompt: `Approve ${label}?`,
+ prompt: prompt ?? `Approve ${label}?`,
requestId: approval.approvalId,
});
}
diff --git a/packages/eve/src/internal/authored-definition/approval.ts b/packages/eve/src/internal/authored-definition/approval.ts
index db73eebd3..3190651e8 100644
--- a/packages/eve/src/internal/authored-definition/approval.ts
+++ b/packages/eve/src/internal/authored-definition/approval.ts
@@ -3,7 +3,13 @@ import {
expectObjectRecord,
expectOnlyKnownKeys,
} from "#internal/authored-module.js";
-import type { Approval, ApprovalPolicy, ApprovalResponsePolicy } from "#approval/definition.js";
+import type {
+ Approval,
+ ApprovalPolicy,
+ ApprovalPrompt,
+ ApprovalResponsePolicy,
+ ToolApproval,
+} from "#approval/definition.js";
/** Validates the function shorthand or explicit request/response approval shape. */
export function normalizeApproval(value: unknown, message: string): Approval {
@@ -12,7 +18,27 @@ export function normalizeApproval(value: unknown, message: string): Approval {
const approval = expectObjectRecord(value, message);
expectOnlyKnownKeys(approval, ["request", "response"], message);
const request = expectFunction<ApprovalPolicy>(approval.request, message);
- if (approval.response === undefined) return { request };
- const response = expectFunction<ApprovalResponsePolicy>(approval.response, message);
+ const response =
+ approval.response === undefined
+ ? undefined
+ : expectFunction<ApprovalResponsePolicy>(approval.response, message);
return { request, response };
}
+
+/** Validates a tool approval, including its optional presentation prompt. */
+export function normalizeToolApproval(value: unknown, message: string): ToolApproval {
+ if (typeof value === "function") return value as ToolApproval;
+
+ const approval = expectObjectRecord(value, message);
+ expectOnlyKnownKeys(approval, ["request", "prompt", "response"], message);
+ const request = expectFunction<ApprovalPolicy>(approval.request, message);
+ const prompt =
+ approval.prompt === undefined
+ ? undefined
+ : expectFunction<ApprovalPrompt>(approval.prompt, message);
+ const response =
+ approval.response === undefined
+ ? undefined
+ : expectFunction<ApprovalResponsePolicy>(approval.response, message);
+ return { request, prompt, response };
+}
diff --git a/packages/eve/src/internal/authored-definition/schema-backed.test.ts b/packages/eve/src/internal/authored-definition/schema-backed.test.ts
index 9f6213514..8d849b211 100644
--- a/packages/eve/src/internal/authored-definition/schema-backed.test.ts
+++ b/packages/eve/src/internal/authored-definition/schema-backed.test.ts
@@ -285,6 +285,29 @@ describe("normalizeToolDefinition", () => {
expect(normalizeToolDefinition(tool, FAILURE_MESSAGE).kind).toBe("tool");
});
+ it("types custom approval prompts from the tool input schema", () => {
+ const tool = defineTool({
+ description: "Requests city-scoped approval.",
+ inputSchema: z.object({ city: z.string() }),
+ approval: {
+ request: once(),
+ prompt({ callId, input, toolName }) {
+ const city: string = input.city;
+ // @ts-expect-error approval prompt input is schema-typed, not an open record.
+ const missing = input.missing;
+ void callId;
+ void missing;
+ return `Run ${toolName} for ${city}?`;
+ },
+ },
+ execute(input) {
+ return input.city;
+ },
+ });
+
+ expect(normalizeToolDefinition(tool, FAILURE_MESSAGE).kind).toBe("tool");
+ });
+
it("accepts explicit request and response approval policies", () => {
const tool = defineTool({
approval: {
@@ -328,6 +351,22 @@ describe("normalizeToolDefinition", () => {
).toThrow('Unknown key "needsApproval"');
});
+ it("rejects authored tools whose approval prompt is not a function", () => {
+ expect(() =>
+ normalizeToolDefinition(
+ {
+ approval: { request: once(), prompt: "not a function" },
+ description: "Echo.",
+ execute(input: unknown) {
+ return input;
+ },
+ inputSchema: { type: "object" },
+ },
+ FAILURE_MESSAGE,
+ ),
+ ).toThrow(FAILURE_MESSAGE);
+ });
+
it("rejects authored tools whose `toModelOutput` is not a function", () => {
expect(() =>
normalizeToolDefinition(
diff --git a/packages/eve/src/internal/authored-definition/schema-backed.ts b/packages/eve/src/internal/authored-definition/schema-backed.ts
index 1e27a93cf..add9c27cd 100644
--- a/packages/eve/src/internal/authored-definition/schema-backed.ts
+++ b/packages/eve/src/internal/authored-definition/schema-backed.ts
@@ -35,7 +35,7 @@ import {
type ToolSchemaSource,
UNSPECIFIED_INPUT_SCHEMA,
} from "#tools/schema.js";
-import { normalizeApproval } from "#internal/authored-definition/approval.js";
+import { normalizeToolApproval } from "#internal/authored-definition/approval.js";
import { shouldRebindDynamicCallbacks } from "#internal/dynamic-tool-rebind.js";
import {
assertResolverOnlyDynamicSentinel,
@@ -233,7 +233,7 @@ export function normalizeToolDefinition(value: unknown, message: string): Normal
}
if (record.approval !== undefined) {
- normalizeApproval(record.approval, message);
+ normalizeToolApproval(record.approval, message);
}
if (record.approvalKey !== undefined) {
diff --git a/packages/eve/src/internal/testing/channel-conformance/MATRIX.md b/packages/eve/src/internal/testing/channel-conformance/MATRIX.md
index 14728fc55..4a5aebd4e 100644
--- a/packages/eve/src/internal/testing/channel-conformance/MATRIX.md
+++ b/packages/eve/src/internal/testing/channel-conformance/MATRIX.md
@@ -31,7 +31,7 @@ pnpm --filter eve exec vitest run --config vitest.unit.config.ts channel-conform
| Rule | `tui` | `web chat` | `chat-sdk` | `chat-sdk-dm` | `chat-sdk-text` | `discord` | `discord-dm` | `linq` | `linq-dm` | `slack` | `slack-dm` | `teams` | `teams-dm` | `telegram` | `telegram-dm` | `github` | `linear` | `photon` | `twilio` |
| --- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
-| a tool approval shows a choice to approve and one to cancel | ✅ | ✅ | ✅ | | ✅ | ✅ | | ✅ | | ✅ | | ✅ | | ✅ | | ✅ | ✅ | ✅ | ✅ |
+| a tool approval shows the tool's prompt with a choice to approve and one to cancel | ✅ | ✅ | ✅ | | ✅ | ✅ | | ✅ | | ✅ | | ✅ | | ✅ | | ✅ | ✅ | ✅ | ✅ |
| pressing Approve runs the gated tool | ✅ | ✅ | ✅ | ✅ | —<sup>[1](#note-1)</sup> | ✅ | ✅ | —<sup>[1](#note-1)</sup> | —<sup>[1](#note-1)</sup> | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | —<sup>[1](#note-1)</sup> | —<sup>[1](#note-1)</sup> | —<sup>[1](#note-1)</sup> | —<sup>[1](#note-1)</sup> |
| pressing Cancel stops the gated tool without running it | ✅ | ✅ | ✅ | | —<sup>[1](#note-1)</sup> | ✅ | | —<sup>[1](#note-1)</sup> | | ✅ | | ✅ | | ✅ | | —<sup>[1](#note-1)</sup> | —<sup>[1](#note-1)</sup> | —<sup>[1](#note-1)</sup> | —<sup>[1](#note-1)</sup> |
| a text reply of approve runs the gated tool | —<sup>[6](#note-6)</sup> | ✅ | ✅ | ✅ | ✅ | —<sup>[2](#note-2)</sup> | —<sup>[2](#note-2)</sup> | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
diff --git a/packages/eve/src/internal/testing/channel-conformance/contract.ts b/packages/eve/src/internal/testing/channel-conformance/contract.ts
index faebd3482..aaad5eac0 100644
--- a/packages/eve/src/internal/testing/channel-conformance/contract.ts
+++ b/packages/eve/src/internal/testing/channel-conformance/contract.ts
@@ -6,6 +6,7 @@ import {
type ChannelCapability,
type ChannelConversation,
type ConversationOptions,
+ deployPrompt,
GATED_TOOL,
type GatedTool,
OPEN_GATED_TOOL,
@@ -65,11 +66,14 @@ const OWN_WORDS = "Mostly the billing migration";
const PLAN_REVIEW = `Use ${TWO_QUESTIONS_TOOL} to plan the review.`;
-const DEPLOY = `Use ${GATED_TOOL} to ship the release.`;
+// The mock model fills the tool's `release` input from this, and the tool's
+// custom approval prompt reads it back, so rules see the prompt the tool built.
+const RELEASE = 'release "v2.4"';
+const DEPLOY = `Use ${GATED_TOOL} to ship ${RELEASE}.`;
// Channels word the two approval choices differently; the TUI asks Yes or No.
const APPROVE_LABELS = ["Approve", "Yes"];
const CANCEL_LABELS = ["Cancel", "No"];
-const APPROVAL_PROMPT = "Approve Deploy release?";
+const APPROVAL_PROMPT = deployPrompt("v2.4");
async function askToDeploy(conversation: ChannelConversation) {
await conversation.say(DEPLOY);
@@ -78,8 +82,8 @@ async function askToDeploy(conversation: ChannelConversation) {
const PUBLISH_PROMPT = "Approve Publish notes?";
-const DEPLOY_AND_PUBLISH = `Call tools in parallel: ${GATED_TOOL}, ${SECOND_GATED_TOOL}`;
-const ASK_AND_DEPLOY = `Call tools in parallel: ask_question, ${GATED_TOOL}\n${ASK}`;
+const DEPLOY_AND_PUBLISH = `Call tools in parallel: ${GATED_TOOL}, ${SECOND_GATED_TOOL}\nShip ${RELEASE}.`;
+const ASK_AND_DEPLOY = `Call tools in parallel: ask_question, ${GATED_TOOL}\n${ASK}\nShip ${RELEASE}.`;
/** Answers each prompt with its option, in whatever order the client shows them. */
function answerEach(
@@ -505,7 +509,7 @@ const questionRules = [
const approvalRules = [
{
- rule: "a tool approval shows a choice to approve and one to cancel",
+ rule: "a tool approval shows the tool's prompt with a choice to approve and one to cancel",
source: "docs/tools/human-in-the-loop.md#approvals",
requires: [],
async run(conversation) {
diff --git a/packages/eve/src/internal/testing/channel-conformance/harness.ts b/packages/eve/src/internal/testing/channel-conformance/harness.ts
index e7980339d..4837f4180 100644
--- a/packages/eve/src/internal/testing/channel-conformance/harness.ts
+++ b/packages/eve/src/internal/testing/channel-conformance/harness.ts
@@ -11,7 +11,7 @@ import { attachRouteSessionCreator } from "#internal/nitro/routes/channel-route-
import type { SessionAuthContext } from "#channel/types.js";
import { eveChannel } from "#public/channels/eve.js";
import { z } from "#compiled/zod/index.js";
-import type { ApprovalResponsePolicy } from "#approval/definition.js";
+import type { ApprovalPrompt, ApprovalResponsePolicy } from "#approval/definition.js";
import { always } from "#tools/approval/policies.js";
import { defineTool } from "#tools/definition.js";
import { askQuestion } from "#tools/provided/ask-question.js";
@@ -332,9 +332,17 @@ const WAIT_TIMEOUT_MS = 30_000;
/** Stand-in origin for the agent a {@link ClientDriver} talks to. */
const CLIENT_HOST = "https://agent.example.com";
-/** The test agent's tool that always needs a person's approval before it runs. */
+/**
+ * The test agent's tool that always needs a person's approval before it runs.
+ * Its approval prompt is built from the call's input, as {@link deployPrompt}.
+ */
export const GATED_TOOL = "deploy_release";
+/** The approval prompt {@link GATED_TOOL} shows for `release`. */
+export function deployPrompt(release: string): string {
+ return `Deploy release ${release} to production?`;
+}
+
/** A second always-gated tool, so two approvals can be pending at once. */
export const SECOND_GATED_TOOL = "publish_notes";
@@ -676,10 +684,16 @@ async function converse(
logicalPath: "tools/ask_question.ts",
loadNamespace: async () => ({ default: askQuestion() }),
},
- gatedTool(GATED_TOOL, "Deploys a release.", () => {
- runs[GATED_TOOL] += 1;
- return { deployed: true };
- }),
+ gatedTool(
+ GATED_TOOL,
+ "Deploys a release.",
+ () => {
+ runs[GATED_TOOL] += 1;
+ return { deployed: true };
+ },
+ undefined,
+ ({ input }) => deployPrompt(input.release ?? "unknown"),
+ ),
gatedTool(SECOND_GATED_TOOL, "Publishes release notes.", () => {
runs[SECOND_GATED_TOOL] += 1;
return { published: true };
@@ -1177,12 +1191,16 @@ function gatedTool(
description: string,
execute: () => unknown,
response?: ApprovalResponsePolicy,
+ prompt?: ApprovalPrompt<{ readonly release?: string }>,
) {
return {
logicalPath: `tools/${name}.ts`,
loadNamespace: async () => ({
default: defineTool({
- approval: response === undefined ? always() : { request: always(), response },
+ approval:
+ response === undefined && prompt === undefined
+ ? always()
+ : { request: always(), prompt, response },
description: `${description} Only call when asked to use ${name}.`,
execute: async () => execute(),
inputSchema: z.object({ release: z.string().optional() }),
diff --git a/packages/eve/src/internal/workflow-bundle/dynamic-tool-transform.test.ts b/packages/eve/src/internal/workflow-bundle/dynamic-tool-transform.test.ts
index 28c78ee19..5a0b5886d 100644
--- a/packages/eve/src/internal/workflow-bundle/dynamic-tool-transform.test.ts
+++ b/packages/eve/src/internal/workflow-bundle/dynamic-tool-transform.test.ts
@@ -124,6 +124,7 @@ export default defineDynamic({
const resultPrefix = "Deployed to";
const updateSuffix = " sources";
const requestReason = "confirm";
+ const promptPrefix = "Review";
const allowedResponder = "user-123";
const projectionPrefix = "visible";
return {
@@ -145,6 +146,9 @@ export default defineDynamic({
request(ctx) {
return ctx.toolInput.force ? { type: "user-approval", reason: requestReason } : "not-applicable";
},
+ prompt(ctx) {
+ return promptPrefix + " " + ctx.input.value;
+ },
response(ctx) {
return ctx.response.principal.principalId === allowedResponder
? { status: "allowed" }
@@ -172,6 +176,7 @@ export default defineDynamic({
expect(Object.keys(callbacks)).toEqual([
"execute",
"label",
+ "approvalPrompt",
"approvalRequest",
"approvalResponse",
"toModelOutput",
@@ -181,6 +186,7 @@ export default defineDynamic({
expect(callbacks.label?.complete?.closure).toEqual({ resultPrefix: "Deployed to" });
expect(callbacks.label?.delta?.closure).toEqual({ updateSuffix: " sources" });
expect(callbacks.approvalRequest!.closure).toEqual({ requestReason: "confirm" });
+ expect(callbacks.approvalPrompt!.closure).toEqual({ promptPrefix: "Review" });
expect(callbacks.approvalResponse!.closure).toEqual({ allowedResponder: "user-123" });
expect(callbacks.toModelOutput!.closure).toEqual({ projectionPrefix: "visible" });
const callbackValues = [
@@ -189,10 +195,11 @@ export default defineDynamic({
callbacks.label?.complete,
callbacks.label?.delta,
callbacks.approvalRequest,
+ callbacks.approvalPrompt,
callbacks.approvalResponse,
callbacks.toModelOutput,
];
- expect(new Set(callbackValues.map((callback) => callback!.callback)).size).toBe(7);
+ expect(new Set(callbackValues.map((callback) => callback!.callback)).size).toBe(8);
for (const callback of callbackValues) expect(callback!.callback).toBeTypeOf("function");
});
diff --git a/packages/eve/src/internal/workflow-bundle/dynamic-tool-transform.ts b/packages/eve/src/internal/workflow-bundle/dynamic-tool-transform.ts
index a9361372c..7bb84dc84 100644
--- a/packages/eve/src/internal/workflow-bundle/dynamic-tool-transform.ts
+++ b/packages/eve/src/internal/workflow-bundle/dynamic-tool-transform.ts
@@ -24,6 +24,7 @@ type CallbackPhase =
| "labelDelta"
| "labelStart"
| "approvalKey"
+ | "approvalPrompt"
| "approvalRequest"
| "approvalResponse"
| "execute"
@@ -34,6 +35,7 @@ type CallbackPropertyName =
| "approvalKey"
| "label"
| "approval"
+ | "prompt"
| "execute"
| "start"
| "request"
@@ -257,6 +259,14 @@ function collectToolCallbacks(
results,
nestedScopes,
);
+ collectCallbackProperty(
+ source,
+ findProperty(approvalValue, "prompt"),
+ "approvalPrompt",
+ "prompt",
+ results,
+ nestedScopes,
+ );
collectCallbackProperty(
source,
findProperty(approvalValue, "response"),
diff --git a/packages/eve/src/public/channels/slack/hitl.test.ts b/packages/eve/src/public/channels/slack/hitl.test.ts
index c4e29a0d7..bc23b1142 100644
--- a/packages/eve/src/public/channels/slack/hitl.test.ts
+++ b/packages/eve/src/public/channels/slack/hitl.test.ts
@@ -247,7 +247,7 @@ describe("renderInputRequestBlocks", () => {
type: "container",
title: { type: "plain_text", text: "Tool input" },
is_collapsible: true,
- default_collapsed: false,
+ default_collapsed: true,
});
expect(details.child_blocks).toHaveLength(1);
expect(details.child_blocks[0]).toMatchObject({ type: "section", text: { type: "mrkdwn" } });
@@ -255,6 +255,36 @@ describe("renderInputRequestBlocks", () => {
expect(details.child_blocks[0]?.text?.text).toContain('"_id": "qudw7ekkzulpgw3j"');
});
+ it("renders a custom approval prompt in the card while keeping tool input collapsed", () => {
+ const blocks = renderInputRequestBlocks(
+ makeRequest({
+ action: {
+ kind: "tool-call",
+ callId: "call_payment",
+ toolName: "send_payment",
+ input: { amount: 125, recipient: "Ada" },
+ },
+ display: "confirmation",
+ kind: "tool-approval",
+ prompt: "Send $125 to Ada?",
+ options: [
+ { id: "approve", label: "Approve" },
+ { id: "cancel", label: "Cancel" },
+ ],
+ }),
+ );
+
+ expect(blocks[0]).toMatchObject({
+ type: "card",
+ body: { type: "mrkdwn", text: "*Send $125 to Ada?*" },
+ });
+ expect(blocks[1]).toMatchObject({
+ type: "container",
+ default_collapsed: true,
+ title: { type: "plain_text", text: "Tool input" },
+ });
+ });
+
it("keeps long approval input details within the collapsible container section limit", () => {
const blocks = renderInputRequestBlocks(
makeRequest({
diff --git a/packages/eve/src/public/channels/slack/hitl.ts b/packages/eve/src/public/channels/slack/hitl.ts
index 47ed11880..3325ca899 100644
--- a/packages/eve/src/public/channels/slack/hitl.ts
+++ b/packages/eve/src/public/channels/slack/hitl.ts
@@ -513,7 +513,7 @@ function renderToolInputContainerBlock(request: InputRequest): Record<string, un
type: "container",
title: { type: "plain_text", text: "Tool input" },
is_collapsible: true,
- default_collapsed: false,
+ default_collapsed: true,
child_blocks: [{ type: "section", text: { type: "mrkdwn", text: details } }],
};
}
diff --git a/packages/eve/src/public/channels/slack/slackChannel.test.ts b/packages/eve/src/public/channels/slack/slackChannel.test.ts
index 6d9aa3911..848abc533 100644
--- a/packages/eve/src/public/channels/slack/slackChannel.test.ts
+++ b/packages/eve/src/public/channels/slack/slackChannel.test.ts
@@ -1175,7 +1175,7 @@ describe("slackChannel() default event handlers", () => {
type: "container",
title: { type: "plain_text", text: "Tool input" },
is_collapsible: true,
- default_collapsed: false,
+ default_collapsed: true,
child_blocks: [
{
type: "section",
@@ -5089,7 +5089,7 @@ describe("slackChannel() HITL interaction pipeline", () => {
type: "container",
title: { type: "plain_text", text: "Tool input" },
is_collapsible: true,
- default_collapsed: false,
+ default_collapsed: true,
child_blocks: [
{ type: "section", text: { type: "mrkdwn", text: '```\n{"issue":451}\n```' } },
],
@@ -5120,7 +5120,7 @@ describe("slackChannel() HITL interaction pipeline", () => {
type: "container",
title: { type: "plain_text", text: "Tool input" },
is_collapsible: true,
- default_collapsed: false,
+ default_collapsed: true,
child_blocks: [
{ type: "section", text: { type: "mrkdwn", text: '```\n{"issue":508}\n```' } },
],
diff --git a/packages/eve/src/public/definitions/approval.ts b/packages/eve/src/public/definitions/approval.ts
index 3abfd6462..91c4b7efc 100644
--- a/packages/eve/src/public/definitions/approval.ts
+++ b/packages/eve/src/public/definitions/approval.ts
@@ -3,6 +3,8 @@ export type {
ApprovalConfiguration,
ApprovalContext,
ApprovalPolicy,
+ ApprovalPrompt,
+ ApprovalPromptContext,
ApprovalRequest,
ApprovalResponse,
ApprovalResponseAuth,
@@ -12,5 +14,7 @@ export type {
ApprovalResponseSession,
ApprovalStatus,
ConnectionToolAnnotations,
+ ToolApproval,
+ ToolApprovalConfiguration,
} from "#approval/definition.js";
export { resolveApprovalPolicy } from "#approval/definition.js";
diff --git a/packages/eve/src/public/tools/approval/index.ts b/packages/eve/src/public/tools/approval/index.ts
index b62ea7854..e8ecbfef8 100644
--- a/packages/eve/src/public/tools/approval/index.ts
+++ b/packages/eve/src/public/tools/approval/index.ts
@@ -7,6 +7,8 @@ export type {
ApprovalConfiguration,
ApprovalContext,
ApprovalPolicy,
+ ApprovalPrompt,
+ ApprovalPromptContext,
ApprovalRequest,
ApprovalResponse,
ApprovalResponseAuth,
@@ -16,6 +18,8 @@ export type {
ApprovalResponseSession,
ApprovalStatus,
ConnectionToolAnnotations,
+ ToolApproval,
+ ToolApprovalConfiguration,
} from "#public/definitions/approval.js";
export type { AutoApprovalOptions } from "#tools/approval/policies.js";
export { always, auto, never, once } from "#tools/approval/policies.js";
diff --git a/packages/eve/src/runtime/resolve-tool.ts b/packages/eve/src/runtime/resolve-tool.ts
index 075229888..422f4aede 100644
--- a/packages/eve/src/runtime/resolve-tool.ts
+++ b/packages/eve/src/runtime/resolve-tool.ts
@@ -2,7 +2,7 @@ import type { CompiledToolDefinition } from "#compiler/manifest.js";
import { isFrameworkTool, frameworkTool } from "#tools/provided/framework-tool.js";
import type { CompiledModuleMap } from "#compiler/module-map.js";
import { expectFunction, expectObjectRecord } from "#internal/authored-module.js";
-import { normalizeApproval } from "#internal/authored-definition/approval.js";
+import { normalizeToolApproval } from "#internal/authored-definition/approval.js";
import { registerDefinitionSource } from "#internal/authored-definition/source-identity.js";
import { isToolSchema, toInputSchema, toOutputSchema } from "#tools/schema.js";
import { toErrorMessage } from "#shared/errors.js";
@@ -165,7 +165,7 @@ function extractOptionalHooks(
}
if (record.approval !== undefined) {
- optional.approval = normalizeApproval(
+ optional.approval = normalizeToolApproval(
record.approval,
describe(definition, "to provide a valid approval definition"),
);
diff --git a/packages/eve/src/runtime/types.ts b/packages/eve/src/runtime/types.ts
index 78c70fcf0..816529e67 100644
--- a/packages/eve/src/runtime/types.ts
+++ b/packages/eve/src/runtime/types.ts
@@ -8,7 +8,7 @@ import type { ChannelRouteMethod, RouteContext } from "#public/definitions/chann
import type { RouteHandler, WebSocketRouteHandler } from "#channel/routes.js";
import type { OutboundAuthFn } from "#public/agents/auth.js";
import type { StreamEventHook } from "#public/definitions/hook.js";
-import type { Approval } from "#approval/definition.js";
+import type { Approval, ToolApproval } from "#approval/definition.js";
import type { ToolModelOutput } from "#tools/definition.js";
import type { ConnectionToolCallDefinition } from "#public/definitions/connections/tool-call.js";
import type {
@@ -175,7 +175,7 @@ export type ResolvedToolDefinition = Readonly<
* approval is required before executing this tool. See
* {@link Approval} for the shared callback contract.
*/
- readonly approval?: Approval;
+ readonly approval?: ToolApproval;
/**
* Optional function that derives a compound approval key from the tool
* input. When present, the runtime records this key (instead of just
diff --git a/packages/eve/src/tools/definition.ts b/packages/eve/src/tools/definition.ts
index 4f56af3a1..3d2380b35 100644
--- a/packages/eve/src/tools/definition.ts
+++ b/packages/eve/src/tools/definition.ts
@@ -4,7 +4,7 @@ import type {
StandardSchemaV1,
} from "#compiled/@standard-schema/spec/index.js";
-import type { Approval } from "#approval/definition.js";
+import type { ToolApproval } from "#approval/definition.js";
import type { SessionContext } from "#context/session-context.js";
import { stampDefinitionKey } from "#internal/authored-definition/source-identity.js";
import type { JsonObject } from "#shared/json.js";
@@ -258,7 +258,7 @@ export interface ToolDefinition<TInput = unknown, TOutput = unknown> extends Pub
* - {@link never}: never require approval
* - {@link once}: require approval only the first time per session
*/
- approval?: Approval<ApprovalContextInput<TInput>>;
+ approval?: ToolApproval<ApprovalContextInput<TInput>>;
/**
* Optional projection controlling what the model sees as the tool result.
* Receives the full `TOutput` from {@link execute} and returns the
@@ -397,7 +397,7 @@ export function stampToolDefinition<
readonly outputSchema?: unknown;
readonly execute?: (...args: never[]) => unknown;
readonly label?: ToolLabelDefinition;
- readonly approval?: Approval<never>;
+ readonly approval?: ToolApproval<never>;
readonly approvalKey?: (...args: never[]) => unknown;
readonly toModelOutput?: (...args: never[]) => unknown;
},
diff --git a/packages/eve/src/tools/durable-callbacks.ts b/packages/eve/src/tools/durable-callbacks.ts
index 4ac7fc336..4f0f43c30 100644
--- a/packages/eve/src/tools/durable-callbacks.ts
+++ b/packages/eve/src/tools/durable-callbacks.ts
@@ -1,5 +1,5 @@
import { readDurableSchema } from "#tools/durable-schema.js";
-import type { Approval } from "#approval/definition.js";
+import type { ToolApproval } from "#approval/definition.js";
import { resolveApprovalPolicy } from "#approval/definition.js";
import type { JsonObject, JsonPrimitive } from "#shared/json.js";
@@ -8,6 +8,7 @@ export type DurableDynamicCallbackPhase =
| "labelDelta"
| "labelStart"
| "approvalKey"
+ | "approvalPrompt"
| "approvalRequest"
| "approvalResponse"
| "execute"
@@ -38,6 +39,7 @@ export interface DurableDynamicToolCallbacks {
readonly start?: DurableDynamicCallbackReference;
};
readonly approvalKey?: DurableDynamicCallbackReference;
+ readonly approvalPrompt?: DurableDynamicCallbackReference;
readonly approvalRequest?: DurableDynamicCallbackReference;
readonly approvalResponse?: DurableDynamicCallbackReference;
readonly toModelOutput?: DurableDynamicCallbackReference;
@@ -59,6 +61,7 @@ type LiveDurableDynamicToolCallbacks = Partial<{
readonly start?: StampedDurableDynamicCallback;
};
approvalKey: StampedDurableDynamicCallback;
+ approvalPrompt: StampedDurableDynamicCallback;
approvalRequest: StampedDurableDynamicCallback;
approvalResponse: StampedDurableDynamicCallback;
toModelOutput: StampedDurableDynamicCallback;
@@ -182,6 +185,7 @@ function durableCallbackPhases(
["labelDelta", callbacks.label?.delta],
["labelStart", callbacks.label?.start],
["approvalKey", callbacks.approvalKey],
+ ["approvalPrompt", callbacks.approvalPrompt],
["approvalRequest", callbacks.approvalRequest],
["approvalResponse", callbacks.approvalResponse],
["toModelOutput", callbacks.toModelOutput],
@@ -271,7 +275,7 @@ export function collectDurableDynamicToolCallbacks(input: {
readonly delta?: (...args: never[]) => unknown;
readonly start?: (...args: never[]) => unknown;
};
- readonly approval?: Approval<never>;
+ readonly approval?: ToolApproval<never>;
readonly approvalKey?: (...args: never[]) => unknown;
readonly execute?: (...args: never[]) => unknown;
readonly toModelOutput?: (...args: never[]) => unknown;
@@ -289,6 +293,11 @@ export function collectDurableDynamicToolCallbacks(input: {
: readDurableDynamicCallback(input.approval.response);
const approvalKey = readDurableDynamicCallback(input.approvalKey);
+ const approvalPrompt = readDurableDynamicCallback(
+ input.approval === undefined || typeof input.approval === "function"
+ ? undefined
+ : input.approval.prompt,
+ );
const execute = readDurableDynamicCallback(input.execute);
const toModelOutput = readDurableDynamicCallback(input.toModelOutput);
const callbacks: LiveDurableDynamicToolCallbacks = {};
@@ -305,6 +314,7 @@ export function collectDurableDynamicToolCallbacks(input: {
};
}
if (approvalKey !== undefined) callbacks.approvalKey = approvalKey;
+ if (approvalPrompt !== undefined) callbacks.approvalPrompt = approvalPrompt;
if (approvalRequest !== undefined) callbacks.approvalRequest = approvalRequest;
if (approvalResponse !== undefined) callbacks.approvalResponse = approvalResponse;
if (toModelOutput !== undefined) callbacks.toModelOutput = toModelOutput;
diff --git a/packages/eve/src/tools/dynamic.ts b/packages/eve/src/tools/dynamic.ts
index 8b8bffc5a..72e19e94f 100644
--- a/packages/eve/src/tools/dynamic.ts
+++ b/packages/eve/src/tools/dynamic.ts
@@ -1,4 +1,4 @@
-import type { Approval } from "#approval/definition.js";
+import type { ToolApproval } from "#approval/definition.js";
import type { DynamicResolveContext, DynamicToolEventName } from "#dynamic/definition.js";
import type {
PublicToolInputSchema,
@@ -44,7 +44,7 @@ export interface DynamicToolEntry<TInput = Record<string, unknown>, TOutput = an
* before the call executes. Dynamic approval request and response callbacks
* use the same durable descriptor boundary as `execute` and `toModelOutput`.
*/
- readonly approval?: Approval;
+ readonly approval?: ToolApproval<TInput>;
/** Derives the input-scoped key recorded when this tool is approved. */
readonly approvalKey?: (toolInput: Readonly<Record<string, unknown>>) => string;
}
diff --git a/packages/eve/src/tools/workflow-definition.ts b/packages/eve/src/tools/workflow-definition.ts
index 5389332bf..ac0fc2e81 100644
--- a/packages/eve/src/tools/workflow-definition.ts
+++ b/packages/eve/src/tools/workflow-definition.ts
@@ -2,7 +2,7 @@ import type {
StandardJSONSchemaV1,
StandardSchemaV1,
} from "#compiled/@standard-schema/spec/index.js";
-import type { Approval } from "#approval/definition.js";
+import type { ToolApproval } from "#approval/definition.js";
import type { MessageResult, SendTurnOptions } from "#client/types.js";
import type { JsonObject } from "#shared/json.js";
import {
@@ -169,7 +169,7 @@ interface WorkflowToolDefinitionBase<TInput, TOutput> extends PublicToolDefiniti
TOutput
> {
readonly [WORKFLOW_TOOL_BRAND]: true;
- approval?: Approval<unknown extends TInput ? Record<string, unknown> : TInput>;
+ approval?: ToolApproval<unknown extends TInput ? Record<string, unknown> : TInput>;
toModelOutput?: (output: TOutput) => ToolModelOutput | Promise<ToolModelOutput>;
}