Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve)!: cache-stable connection_search and connection_execute (#4023)

Andrew Barbacc14b3d8461f
diff --git a/.changeset/connection-execute.md b/.changeset/connection-execute.md
new file mode 100644
index 000000000..6b4284dc2
--- /dev/null
+++ b/.changeset/connection-execute.md
@@ -0,0 +1,5 @@
+---
+"eve": minor
+---
+
+Connection tools no longer break the prompt cache. The model finds them with `connection_search` and calls them with the new `connection_execute` tool, so discovered tools are no longer added to the model's tool list. Connection names now arrive in append-only context messages instead of the system prompt. `connection_execute` returns MCP `structuredContent` or text instead of the raw MCP envelope, and stream events report each call as a nested `<connection>__<tool>` action with a new `parentCallId`. The `eve/tools/connection_search` export is removed, and both tools are reserved names that cannot be replaced or disabled.
diff --git a/apps/templates/eve-chat-template/apps/web/components/chat/message.tsx b/apps/templates/eve-chat-template/apps/web/components/chat/message.tsx
index 69f582d81..c69f5df45 100644
--- a/apps/templates/eve-chat-template/apps/web/components/chat/message.tsx
+++ b/apps/templates/eve-chat-template/apps/web/components/chat/message.tsx
@@ -672,10 +672,6 @@ function needsInputResponse(part: EveDynamicToolPart) {
}
function hasToolDetails(part: EveDynamicToolPart) {
- if (isConnectionSearchTool(part)) {
- return false;
- }
-
const hasInput = part.input !== undefined && formatPayload(part.input).trim().length > 0;
const hasOutput =
part.state === "output-available" && formatPayload(part.output).trim().length > 0;
@@ -684,12 +680,6 @@ function hasToolDetails(part: EveDynamicToolPart) {
return hasInput || hasOutput || hasError || Boolean(part.toolMetadata?.eve?.inputRequest);
}
-function isConnectionSearchTool(part: EveDynamicToolPart) {
- const normalized = normalizeToolName(resolveToolName(part));
-
- return normalized.includes("connection") && normalized.includes("search");
-}
-
function getToolStatus(part: EveDynamicToolPart): ToolStatus {
switch (part.state) {
case "input-streaming":
diff --git a/docs/concepts/built-in-tools.md b/docs/concepts/built-in-tools.md
index e6d04b293..d69454b04 100644
--- a/docs/concepts/built-in-tools.md
+++ b/docs/concepts/built-in-tools.md
@@ -24,7 +24,7 @@ export default defineAgent({
This turns off the optional defaults described below. Add back only the tools the agent needs with the command in each tool's section. Existing files under `agent/tools/` remain available, including same-name replacements such as `agent/tools/bash.ts`.
-`connection_search` stays available when the agent has connections because it provides access to their tools.
+`connection_search` and `connection_execute` stay available when the agent has connections because they provide access to connection tools.
### `bash`
@@ -267,9 +267,14 @@ export default disableTool();
### `connection_search`
-`connection_search` discovers tools across declared [connections](../connections) and makes matches directly callable by qualified name, such as `linear__list_issues`. eve adds it automatically when connections exist, even when `defaultTools` is `false`, so there is no add command.
+`connection_search` and `connection_execute` give the model every tool from the agent's [connections](../connections) without adding each tool to the model's tool list. eve adds both when the agent has a static connection or a dynamic connection resolver, even when `defaultTools` is `false`, so there is no add command.
-An authored `agent/tools/connection_search.ts` replaces the framework behavior. Import the framework definition from `eve/tools/connection_search` when you need to reference it directly. Exporting `disableTool()` from this slot is an error because agents with connections require connection discovery.
+- `connection_search({ query?, connection?, limit?, offset? })` returns matching tools with their connection, name, description, and a TypeScript signature rendered from the tool's schemas. Omit `query` to list every tool, or pair it with `connection` to list one connection's tools.
+- `connection_execute({ connection, tool, input })` checks `input` against the tool's input schema, calls the tool, and returns its result. The stream reports the call as a nested action named `<connection>__<tool>`, such as `linear__list_issues`, whose `parentCallId` is the `connection_execute` call id.
+
+The definitions of both tools never change during a session. eve lists connection names and descriptions in append-only context messages rather than in the system prompt, so finding a tool, signing in, or resolving a dynamic connection keeps the cached prompt prefix.
+
+The tools cannot be replaced or disabled. The compiler rejects an authored `agent/tools/connection_search.ts`, `agent/tools/connection_execute.ts`, or `agent/tools/connection_tools.ts`. An agent without connections has neither tool.
### `task_wait` and `task_cancel`
diff --git a/docs/concepts/sessions-runs-and-streaming.md b/docs/concepts/sessions-runs-and-streaming.md
index ee48bbafb..61dcb3168 100644
--- a/docs/concepts/sessions-runs-and-streaming.md
+++ b/docs/concepts/sessions-runs-and-streaming.md
@@ -113,6 +113,8 @@ The client validates the `x-eve-stream-version` header on every connection. It a
When a streamed tool input becomes a validated call, its `action.input.appended` events precede the matching `actions.requested` event. The default client reducer projects the potentially incomplete JSON as a `dynamic-tool` part with `state: "input-streaming"` and cumulative text in `inputText`. `actions.requested` replaces that part with `state: "input-available"` and the validated `input`. Excluded internal actions never publish their input stream.
+A nested action is a call a tool makes on the model's behalf, such as each connection tool call `connection_execute` makes. eve reports it as its own `actions.requested` and `action.result` pair right before the calling tool's `action.result`. The nested tool call's `parentCallId` holds the calling tool's `callId`. Nested actions never enter model history, and clients that ignore `parentCallId` render them as ordinary tool calls.
+
`action.partial` carries one complete preliminary output snapshot from an authored async-generator tool. A later partial for the same `callId` replaces it, and `action.result` is the final snapshot. When the durable writer is busy, eve may keep only the newest adjacent partial for a call. Treat partials as last-write-wins: a durable step can retry and replay overlapping event runs. Provider-executed tool progress and MCP progress notifications are not projected as `action.partial` events.
Note: consider the privacy, confidentiality, and user-experience implications for displaying, storing, or transmitting reasoning events in your application.
diff --git a/docs/connections/mcp.mdx b/docs/connections/mcp.mdx
index 25d00d22c..6d4420ad0 100644
--- a/docs/connections/mcp.mdx
+++ b/docs/connections/mcp.mdx
@@ -3,13 +3,13 @@ title: "MCP Connections"
description: "Connect an eve agent to a remote MCP server, authorize it with Vercel Connect or static credentials, and control which tools the model can discover."
---
-MCP connections point eve at a remote MCP server you do not author. The server publishes its tools and schemas, and eve exposes matching tools to the model through `connection_search`.
+MCP connections point eve at a remote MCP server you do not author. The server publishes its tools and schemas, and the model finds and calls them through `connection_search` and `connection_execute`.
Use MCP when the service already has an MCP server, when the server owns tool schemas dynamically, or when one connection should expose a family of related remote tools. Use an [OpenAPI connection](./openapi) instead when the service publishes an HTTP API contract and you want eve to generate one tool per operation.
## Define an MCP connection
-Create one file under `agent/connections/`. The filename becomes the runtime connection name, so `agent/connections/linear.ts` registers as `linear`, and discovered tools are called as `linear__<tool>`.
+Create one file under `agent/connections/`. The filename becomes the runtime connection name, so `agent/connections/linear.ts` registers as `linear`, and events report its tools as `linear__<tool>`.
```ts title="agent/connections/linear.ts"
import { connect } from "@vercel/connect/eve";
@@ -22,7 +22,7 @@ export default defineMcpClientConnection({
});
```
-The `url` must speak Streamable HTTP or SSE. Write the `description` for the model, not for yourself: it is the main signal `connection_search` uses when deciding which connection to query.
+The `url` must speak Streamable HTTP or SSE. Write the `description` for the model, not for yourself: eve lists it next to the connection name, and it is the main signal the model uses to decide which connection to search.
## Configure protocol discovery
@@ -150,7 +150,7 @@ Return `"user-approval"` (or `true`) to pause for a person and `"not-applicable"
## Control result size
-eve sends an MCP tool's returned content to the model as the tool result. MCP connections do not expose a per-result transform equivalent to an authored tool's [`toModelOutput`](/docs/tools#shape-what-the-model-sees-with-tomodeloutput).
+`connection_execute` returns an MCP tool's `structuredContent` when the server sends it. Otherwise it returns the result's text, parsed as JSON when the tool declares no output schema. Image, audio, and resource content reaches the model as file parts, and a result with `isError: true` fails the call with its text. MCP connections do not expose a per-result transform equivalent to an authored tool's [`toModelOutput`](/docs/tools#shape-what-the-model-sees-with-tomodeloutput).
When a remote tool returns more data than the model needs, narrow the result at the MCP server. Prefer a purpose-built search or summary tool, or return a stable handle that another call can use to fetch a smaller slice. If you do not control the server and an equivalent upstream API is available, replace only that operation with an authored tool that stores the full payload outside model context and projects the needed fields through `toModelOutput`. Block the original MCP operation through [`tools.block`](#tool-filters) so the model does not see duplicate tools.
diff --git a/docs/connections/openapi.mdx b/docs/connections/openapi.mdx
index 7fb7f69df..734c96bd1 100644
--- a/docs/connections/openapi.mdx
+++ b/docs/connections/openapi.mdx
@@ -9,7 +9,7 @@ Use an [MCP connection](./mcp) instead when the service already exposes an MCP s
## Define an OpenAPI connection
-Create one file under `agent/connections/`. The filename becomes the runtime connection name, so `agent/connections/petstore.ts` registers as `petstore`, and generated operation tools are called as `petstore__<operation>`.
+Create one file under `agent/connections/`. The filename becomes the runtime connection name, so `agent/connections/petstore.ts` registers as `petstore`, and events report its operation tools as `petstore__<operation>`.
```ts title="agent/connections/petstore.ts"
import { defineOpenAPIConnection } from "eve/connections";
@@ -24,7 +24,7 @@ export default defineOpenAPIConnection({
});
```
-Each operation becomes `<connection>__<operationId>`, for example `petstore__getInventory`. When an operation has no `operationId`, eve derives a deterministic `<method>_<sanitized-path>` name instead.
+Each operation becomes a tool named by its `operationId`, reported as `<connection>__<operationId>`, for example `petstore__getInventory`. When an operation has no `operationId`, eve derives a deterministic `<method>_<sanitized-path>` name instead. The model calls it with `connection_execute({ connection: "petstore", tool: "getInventory", input })` and receives `{ status, statusText, body }`.
`spec` can be a URL that eve fetches at runtime, or an inline parsed OpenAPI object. A spec URL must use `https` (plain `http` is allowed only for loopback hosts such as `localhost` during local development), and eve re-checks the transport after any redirects. Prefer a URL when the provider owns the contract and updates it; prefer an inline object for private APIs, generated specs you pin in source control, or small hand-authored contracts.
diff --git a/docs/connections/overview.mdx b/docs/connections/overview.mdx
index 84504104c..cb6016f59 100644
--- a/docs/connections/overview.mdx
+++ b/docs/connections/overview.mdx
@@ -6,7 +6,7 @@ url: /connections
A connection wires an agent into an external server you don't author, either an MCP server (Linear, GitHub, a warehouse) or any HTTP API with an OpenAPI document. eve handles the parts you'd otherwise hand-roll, discovering the remote tools, surfacing them to the model, and brokering auth. To instead let eve communicate with users through an external service, use a [channel](/docs/channels/overview).
-Connections live under `agent/connections/`. A static connection's runtime name comes from the filename, so `agent/connections/linear.ts` registers as `"linear"`. A dynamic connection file can instead resolve a caller-specific connection set at session or turn boundaries. The model never sees a connection's URL or credentials. It discovers tools through the built-in `connection_search` and calls them by their qualified name, `<connection>__<tool>` (e.g. `linear__list_issues`).
+Connections live under `agent/connections/`. A static connection's runtime name comes from the filename, so `agent/connections/linear.ts` registers as `"linear"`. A dynamic connection file can instead resolve a caller-specific connection set at session or turn boundaries. The model never sees a connection's URL or credentials. It finds tools with the built-in `connection_search` and calls them with `connection_execute`. Stream events, approval policies, and hooks name each call by its qualified name, `<connection>__<tool>` (e.g. `linear__list_issues`).
## MCP connections
diff --git a/docs/guides/dynamic-capabilities.md b/docs/guides/dynamic-capabilities.md
index 5e269222f..7d961ca0f 100644
--- a/docs/guides/dynamic-capabilities.md
+++ b/docs/guides/dynamic-capabilities.md
@@ -193,8 +193,9 @@ export default defineDynamic({
The returned definitions use the same auth, headers, filtering, provided
arguments, and approval options as static [MCP](../connections/mcp) and
[OpenAPI](../connections/openapi) connections. Each resolved connection joins
-the per-step connection registry, appears in `connection_search`, and exposes
-discovered tools as `<connection>__<tool>`.
+the per-step connection registry. eve announces it to the model in an
+append-only context message, and the model reaches its tools through
+`connection_search` and `connection_execute`, so the tool list never changes.
Set `instanceKey` on every authenticated dynamic connection. Use a stable,
non-secret account or tenant identifier, and change it whenever the endpoint,
diff --git a/docs/tools/workflows.mdx b/docs/tools/workflows.mdx
index f3d71b5a0..d272538fe 100644
--- a/docs/tools/workflows.mdx
+++ b/docs/tools/workflows.mdx
@@ -402,7 +402,7 @@ async function readRepository(ctx: WorkflowStepToolContext, repository: string)
}
```
-Connections discovered through `connection_search`, ordinary tools, and workflow steps use the same
+Connection tools called through `connection_execute`, ordinary tools, and workflow steps use the same
authorization machinery for requester identity, token caching, callback completion, and rejection
after sign-in. The execution runtime owns the wait: an agent returns to its model after authorization,
while a workflow retries the interrupted step and continues the authored body.
diff --git a/e2e/fixtures/agent-openapi-swagger/agent/agent.ts b/e2e/fixtures/agent-openapi-swagger/agent/agent.ts
index 8c7ad9038..afdb52544 100644
--- a/e2e/fixtures/agent-openapi-swagger/agent/agent.ts
+++ b/e2e/fixtures/agent-openapi-swagger/agent/agent.ts
@@ -1,34 +1,107 @@
import { e2eAgentConfig } from "@eve-e2e/config";
import { defineAgent } from "eve";
+import type { MockModelRequest, MockModelResponse } from "eve/evals";
-export default defineAgent({
- ...e2eAgentConfig({
- mock: ({ lastUserMessage, toolResults, tools }) => {
- if (lastUserMessage?.includes("DYNAMIC_MCP_CONNECTION_E2E")) {
- const search = tools.find((tool) => tool.name === "connection_search");
- return search?.description?.includes("dynamic-mcp")
- ? "DYNAMIC_MCP_CONNECTION_FOUND"
- : "DYNAMIC_MCP_CONNECTION_MISSING";
- }
- if (!lastUserMessage?.includes("DYNAMIC_CONNECTION_E2E")) {
- return `Mock reply: ${lastUserMessage ?? ""}`;
- }
- if (toolResults.some((result) => result.name === "connection_search")) {
- return "DYNAMIC_CONNECTION_FOUND";
- }
- if (tools.some((tool) => tool.name === "connection_search")) {
+/** Whether eve announced `name` in its connection listing. */
+function announced({ messages }: MockModelRequest, name: string): boolean {
+ return messages.some(
+ (message) => message.role === "user" && message.text.includes(`- ${name}: `),
+ );
+}
+
+const kennelCall = (id: string, tool: string, input: Record<string, unknown>) => ({
+ id,
+ input: { connection: "kennel", tool, input },
+ name: "connection_execute",
+});
+
+const BISCUIT_VISIT = {
+ petId: 4217,
+ visit: { kind: "grooming", date: "2026-10-14" },
+ contacts: [{ name: "Alice", phone: "555-0100" }],
+};
+
+/** Walks every kennel result shape, retrying the misshapen call from its signature. */
+function kennelResponse({ toolResults }: MockModelRequest): MockModelResponse | string {
+ const byId = new Map(toolResults.map((result) => [result.id, result]));
+ if (!byId.has("kennel-bad-input")) {
+ return {
+ toolCalls: [
+ kennelCall("kennel-find", "find_pet", { name: "Biscuit" }),
+ kennelCall("kennel-feedings", "list_feedings", { petId: 4217 }),
+ kennelCall("kennel-photo", "pet_photo", { petId: 4217 }),
+ kennelCall("kennel-discharge", "discharge_pet", { petId: 4217 }),
+ kennelCall("kennel-bad-input", "book_visit", {
+ petId: "4217",
+ visit: { kind: "bath" },
+ }),
+ kennelCall("kennel-unknown", "find_pets", { name: "Biscuit" }),
+ ],
+ };
+ }
+ if (!byId.has("kennel-book")) {
+ const error = byId.get("kennel-bad-input");
+ return error?.isError === true && JSON.stringify(error.output).includes("book_visit(input:")
+ ? { toolCalls: [kennelCall("kennel-book", "book_visit", BISCUIT_VISIT)] }
+ : "KENNEL_SIGNATURE_MISSING";
+ }
+ const photo = byId.get("kennel-photo")?.output;
+ const imageParts = Array.isArray(photo)
+ ? photo.filter((part) => JSON.stringify(part).includes('"image/png"')).length
+ : 0;
+ return `KENNEL_MCP_DONE photo-image-parts=${imageParts}`;
+}
+
+const config = e2eAgentConfig({
+ mock: (request) => {
+ const { lastUserMessage, toolResults } = request;
+ if (lastUserMessage?.includes("KENNEL_MCP_E2E")) return kennelResponse(request);
+ if (lastUserMessage?.includes("DYNAMIC_MCP_CONNECTION_E2E")) {
+ return announced(request, "dynamic-mcp")
+ ? "DYNAMIC_MCP_CONNECTION_FOUND"
+ : "DYNAMIC_MCP_CONNECTION_MISSING";
+ }
+ if (lastUserMessage?.includes("PETSTORE_EXECUTE_E2E")) {
+ const result = toolResults.find((entry) => entry.name === "connection_execute");
+ if (result === undefined) {
return {
toolCalls: [
{
- id: "dynamic-connection-search",
- input: { connection: "dynamic-catalog", keywords: "status", limit: 10 },
- name: "connection_search",
+ id: "petstore-inventory",
+ input: { connection: "petstore", tool: "getInventory", input: {} },
+ name: "connection_execute",
},
],
};
}
- return "DYNAMIC_CONNECTION_MISSING";
- },
- }),
+ return result.isError ? "inventory failed" : "inventory received";
+ }
+ if (!lastUserMessage?.includes("DYNAMIC_CONNECTION_E2E")) {
+ return `Mock reply: ${lastUserMessage ?? ""}`;
+ }
+ if (toolResults.some((result) => result.name === "connection_search")) {
+ return "DYNAMIC_CONNECTION_FOUND";
+ }
+ if (announced(request, "dynamic-catalog")) {
+ return {
+ toolCalls: [
+ {
+ id: "dynamic-connection-search",
+ input: { connection: "dynamic-catalog", query: "status" },
+ name: "connection_search",
+ },
+ ],
+ };
+ }
+ return "DYNAMIC_CONNECTION_MISSING";
+ },
+});
+
+export default defineAgent({
+ ...config,
+ // Measure Anthropic cache reuse through its native provider (see connection-cache.eval.ts).
+ ...(typeof config.model === "string" && config.model.startsWith("anthropic/")
+ ? { modelOptions: { providerOptions: { gateway: { only: ["anthropic"] } } } }
+ : {}),
reasoning: "high",
});
diff --git a/e2e/fixtures/agent-openapi-swagger/agent/channels/kennel.ts b/e2e/fixtures/agent-openapi-swagger/agent/channels/kennel.ts
new file mode 100644
index 000000000..e8fc1858f
--- /dev/null
+++ b/e2e/fixtures/agent-openapi-swagger/agent/channels/kennel.ts
@@ -0,0 +1,109 @@
+import { defineChannel, GET, POST } from "eve/channels";
+
+import { BISCUIT_PET_ID, BISCUIT_VISIT_ID, KENNEL_TOOLS, PET_PHOTO_PNG } from "../../kennel";
+
+type ToolResult = Record<string, unknown>;
+
+function text(value: string): ToolResult {
+ return { content: [{ type: "text", text: value }] };
+}
+
+/** Mirrors `book_visit`'s input schema so a wrongly shaped call fails like a real server. */
+function visitProblem(args: Record<string, unknown>): string | undefined {
+ if (args.petId !== BISCUIT_PET_ID) return `No boarding pet has id ${String(args.petId)}.`;
+ const visit = args.visit as Record<string, unknown> | undefined;
+ if (!["checkup", "grooming", "vaccination"].includes(visit?.kind as string)) {
+ return "visit.kind must be checkup, grooming, or vaccination.";
+ }
+ if (typeof visit?.date !== "string" || !/^\d{4}-\d{2}-\d{2}$/u.test(visit.date)) {
+ return "visit.date must be YYYY-MM-DD.";
+ }
+ const contacts = args.contacts;
+ if (
+ !Array.isArray(contacts) ||
+ contacts.length === 0 ||
+ !contacts.every(
+ (contact) => typeof contact?.name === "string" && typeof contact?.phone === "string",
+ )
+ ) {
+ return "contacts must be a non-empty list of { name, phone }.";
+ }
+ return undefined;
+}
+
+function callTool(name: string, args: Record<string, unknown>): ToolResult {
+ switch (name) {
+ case "find_pet": {
+ if (typeof args.name !== "string" || !/^biscuit$/iu.test(args.name.trim())) {
+ return { ...text(`No boarding pet named ${String(args.name)}.`), isError: true };
+ }
+ const pet = { petId: BISCUIT_PET_ID, name: "Biscuit", kennel: "B3" };
+ return { ...text(JSON.stringify(pet)), structuredContent: pet };
+ }
+ case "list_feedings": {
+ // Echoes `day` so evals can see whether eve applied the schema default.
+ const day = args.day ?? "unspecified";
+ return text(
+ JSON.stringify([
+ { day, time: "08:00", food: "kibble" },
+ { day, time: "18:00", food: "salmon" },
+ ]),
+ );
+ }
+ case "pet_photo":
+ return {
+ content: [
+ { type: "text", text: "Biscuit in kennel B3." },
+ { type: "image", data: PET_PHOTO_PNG, mimeType: "image/png" },
+ ],
+ };
+ case "discharge_pet":
+ return {
+ ...text("Biscuit cannot be discharged while an adoption is in progress."),
+ isError: true,
+ };
+ case "book_visit": {
+ const problem = visitProblem(args);
+ if (problem !== undefined) return { ...text(problem), isError: true };
+ const booking = { visitId: BISCUIT_VISIT_ID, ...args };
+ return { ...text(JSON.stringify(booking)), structuredContent: booking };
+ }
+ default:
+ return { ...text(`Unknown tool ${name}.`), isError: true };
+ }
+}
+
+// A fixture-owned MCP server: eve performs real HTTP discovery and tool calls against it.
+export default defineChannel({
+ routes: [
+ GET("/fixture-kennel/mcp", async () => new Response(null, { status: 405 })),
+ POST("/fixture-kennel/mcp", async (request) => {
+ const { id, method, params } = (await request.json()) as {
+ id?: number | string;
+ method: string;
+ params?: { name?: string; arguments?: Record<string, unknown> };
+ };
+ if (id === undefined) return new Response(null, { status: 202 });
+
+ const reply = (result: unknown) => Response.json({ jsonrpc: "2.0", id, result });
+ switch (method) {
+ case "initialize":
+ return reply({
+ protocolVersion: "2025-06-18",
+ capabilities: { tools: {} },
+ serverInfo: { name: "fixture-kennel", version: "1.0.0" },
+ });
+ case "tools/list":
+ return reply({ tools: KENNEL_TOOLS });
+ case "tools/call":
+ return reply(callTool(params?.name ?? "", params?.arguments ?? {}));
+ default:
+ return Response.json({
+ jsonrpc: "2.0",
+ id,
+ error: { code: -32601, message: "Method not found" },
+ });
+ }
+ }),
+ ],
+});
diff --git a/e2e/fixtures/agent-openapi-swagger/agent/channels/petstore.ts b/e2e/fixtures/agent-openapi-swagger/agent/channels/petstore.ts
index 41271b500..3049cb28a 100644
--- a/e2e/fixtures/agent-openapi-swagger/agent/channels/petstore.ts
+++ b/e2e/fixtures/agent-openapi-swagger/agent/channels/petstore.ts
@@ -1,12 +1,40 @@
-import { defineChannel, GET } from "eve/channels";
+import { defineChannel, GET, POST } from "eve/channels";
import { PETSTORE_SPEC } from "../../petstore";
+const STATUSES = new Set(["available", "pending", "sold"]);
+
+/** Mirrors the `Pet` definition so a wrongly shaped call fails like a real API. */
+function petProblem(value: unknown): string | undefined {
+ if (typeof value !== "object" || value === null) return "body must be a Pet object";
+ const pet = value as Record<string, unknown>;
+ if (typeof pet.name !== "string" || pet.name.length === 0) return "name is required";
+ if (typeof pet.status !== "string" || !STATUSES.has(pet.status)) {
+ return "status must be available, pending, or sold";
+ }
+ const category = pet.category as Record<string, unknown> | undefined;
+ if (typeof category?.name !== "string") return "category.name is required";
+ if (
+ !Array.isArray(pet.photoUrls) ||
+ pet.photoUrls.length === 0 ||
+ !pet.photoUrls.every((url) => typeof url === "string")
+ ) {
+ return "photoUrls must be a non-empty array of strings";
+ }
+ return undefined;
+}
+
export default defineChannel({
routes: [
GET("/fixture-petstore/swagger", async () => Response.json(PETSTORE_SPEC)),
GET("/fixture-petstore/store/inventory", async () =>
Response.json({ available: 7, pending: 2, sold: 3 }),
),
+ POST("/fixture-petstore/store/:storeId/pet", async (request, { params }) => {
+ const body: unknown = await request.json().catch(() => undefined);
+ const problem = petProblem(body);
+ if (problem !== undefined) return Response.json({ message: problem }, { status: 400 });
+ return Response.json({ id: 4217, storeId: params.storeId, ...(body as object) });
+ }),
],
});
diff --git a/e2e/fixtures/agent-openapi-swagger/agent/connections/kennel.ts b/e2e/fixtures/agent-openapi-swagger/agent/connections/kennel.ts
new file mode 100644
index 000000000..0a7ae1b00
--- /dev/null
+++ b/e2e/fixtures/agent-openapi-swagger/agent/connections/kennel.ts
@@ -0,0 +1,14 @@
+import { defineDynamic, defineMcpClientConnection } from "eve/connections";
+
+import { kennelHeaders, kennelUrl } from "../../kennel";
+
+export default defineDynamic({
+ events: {
+ "session.started": () =>
+ defineMcpClientConnection({
+ description: "Maple Street kennel: boarding pets, feedings, photos, and care visits.",
+ url: kennelUrl(),
+ headers: kennelHeaders(),
+ }),
+ },
+});
diff --git a/e2e/fixtures/agent-openapi-swagger/agent/connections/petstore-approval.ts b/e2e/fixtures/agent-openapi-swagger/agent/connections/petstore-approval.ts
index 91f029e99..f2c36fe1a 100644
--- a/e2e/fixtures/agent-openapi-swagger/agent/connections/petstore-approval.ts
+++ b/e2e/fixtures/agent-openapi-swagger/agent/connections/petstore-approval.ts
@@ -1,7 +1,7 @@
import { defineDynamic, defineOpenAPIConnection } from "eve/connections";
import { always } from "eve/tools/approval";
-import { petstoreBaseUrl } from "../../petstore";
+import { petstoreBaseUrl, petstoreHeaders, petstoreSpecUrl } from "../../petstore";
export default defineDynamic({
events: {
@@ -9,7 +9,8 @@ export default defineDynamic({
"petstore-approval": defineOpenAPIConnection({
approval: always(),
baseUrl: petstoreBaseUrl(),
- spec: `${petstoreBaseUrl()}/swagger`,
+ spec: petstoreSpecUrl(),
+ headers: petstoreHeaders(),
description:
"Approval-gated sample Petstore API from a fixture-owned Swagger 2.0 document.",
operations: { allow: ["getInventory"] },
diff --git a/e2e/fixtures/agent-openapi-swagger/agent/connections/petstore.ts b/e2e/fixtures/agent-openapi-swagger/agent/connections/petstore.ts
index 6935d6fd2..2ca70afe1 100644
--- a/e2e/fixtures/agent-openapi-swagger/agent/connections/petstore.ts
+++ b/e2e/fixtures/agent-openapi-swagger/agent/connections/petstore.ts
@@ -1,15 +1,16 @@
import { defineDynamic, defineOpenAPIConnection } from "eve/connections";
-import { petstoreBaseUrl } from "../../petstore";
+import { petstoreBaseUrl, petstoreHeaders, petstoreSpecUrl } from "../../petstore";
export default defineDynamic({
events: {
"session.started": () => ({
petstore: defineOpenAPIConnection({
baseUrl: petstoreBaseUrl(),
- spec: `${petstoreBaseUrl()}/swagger`,
+ spec: petstoreSpecUrl(),
+ headers: petstoreHeaders(),
description: "Sample Petstore API from a fixture-owned Swagger 2.0 document.",
- operations: { allow: ["getInventory"] },
+ operations: { allow: ["getInventory", "addPet"] },
}),
}),
},
diff --git a/e2e/fixtures/agent-openapi-swagger/evals/connection-cache.eval.ts b/e2e/fixtures/agent-openapi-swagger/evals/connection-cache.eval.ts
new file mode 100644
index 000000000..3bd62f243
--- /dev/null
+++ b/e2e/fixtures/agent-openapi-swagger/evals/connection-cache.eval.ts
@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import { defineEval } from "eve/evals";
+import { satisfies } from "eve/evals/expect";
+
+export default defineEval({
+ tags: ["real-model"],
+ description: "Searching for and calling a connection tool keeps the provider prompt cache.",
+
+ async test(t) {
+ const turn = await t.send(
+ [
+ "Alice is reconciling the pet store's weekly stock notes below against the live inventory.",
+ "Use the `connection_search` tool to find the inventory operation in the `petstore` connection,",
+ "then call it with `connection_execute` and an empty input.",
+ "Reply with the exact words `inventory received` if the result contains inventory counts.",
+ "",
+ stockNotes(),
+ ].join("\n"),
+ );
+
+ turn.expectOk();
+ turn.noFailedActions();
+ t.toolOrder(["connection_search", "connection_execute"]);
+ t.messageIncludes(/\binventory received\b/iu);
+
+ const steps = turn.events.filter((event) => event.type === "step.completed");
+ assert(steps.length >= 3, "search, execute, and reply each call the model");
+ assert(
+ (steps[0]?.data.usage?.inputTokens ?? 0) >= 4_096,
+ "the notes are large enough for provider caching",
+ );
+ for (let index = 1; index < steps.length; index += 1) {
+ const previousInput = steps[index - 1]!.data.usage?.inputTokens;
+ const usage = steps[index]!.data.usage;
+ assert(previousInput !== undefined, "preceding input token usage is present");
+ assert(usage?.cacheReadTokens !== undefined, "provider cache-read usage is present");
+ t.log(`Request ${index + 1}: ${JSON.stringify({ previousInput, ...usage })}`);
+ // Discovery used to add tool definitions, which invalidated the whole prefix.
+ t.check(
+ usage.cacheReadTokens / previousInput,
+ satisfies(
+ (ratio: number) => ratio >= 0.9,
+ `request ${index + 1} reads at least 90% of the preceding input from the provider cache`,
+ ),
+ );
+ }
+ },
+});
+
+const STATUSES = ["available", "pending", "sold"] as const;
+
+/** Deterministic, benign bulk text that keeps the first request above the cache minimum. */
+function stockNotes(): string {
+ return Array.from({ length: 160 }, (_, index) => {
+ const day = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"][index % 5];
+ const status = STATUSES[index % STATUSES.length];
+ return `Note ${index + 1}: On ${day}, Bob recorded shelf ${(index % 12) + 1} with ${(index * 7) % 23} items marked ${status}, and Alice asked to compare that count with the live inventory before the weekly order.`;
+ }).join("\n");
+}
diff --git a/e2e/fixtures/agent-openapi-swagger/evals/connection-execute.eval.ts b/e2e/fixtures/agent-openapi-swagger/evals/connection-execute.eval.ts
new file mode 100644
index 000000000..5ff3f9d2e
--- /dev/null
+++ b/e2e/fixtures/agent-openapi-swagger/evals/connection-execute.eval.ts
@@ -0,0 +1,36 @@
+import { defineEval } from "eve/evals";
+
+const PETSTORE_INVENTORY_TOOL = "petstore__getInventory";
+
+export default defineEval({
+ description:
+ "connection_execute calls a connection tool over HTTP and reports it as a nested action.",
+
+ async test(t) {
+ if (process.env.EVE_E2E_MODEL !== "mock") {
+ t.skip("Requires the deterministic mock model to issue the exact call.");
+ }
+
+ const turn = await t.send("PETSTORE_EXECUTE_E2E");
+
+ turn.expectOk();
+ turn.noFailedActions();
+ turn.calledTool("connection_execute", { count: 1, output: hasInventoryCounts });
+ turn.calledTool(PETSTORE_INVENTORY_TOOL, { count: 1, output: hasInventoryCounts });
+ turn.event("actions.requested", {
+ count: 1,
+ data: {
+ actions: [{ parentCallId: "petstore-inventory", toolName: PETSTORE_INVENTORY_TOOL }],
+ },
+ });
+ t.succeeded();
+ t.messageIncludes("inventory received");
+ },
+});
+
+function hasInventoryCounts(value: unknown): boolean {
+ if (typeof value !== "object" || value === null) return false;
+ const body = (value as { body?: unknown }).body;
+ if (typeof body !== "object" || body === null || Array.isArray(body)) return false;
+ return Object.values(body).some((count) => typeof count === "number");
+}
diff --git a/e2e/fixtures/agent-openapi-swagger/evals/connection-input-shape.eval.ts b/e2e/fixtures/agent-openapi-swagger/evals/connection-input-shape.eval.ts
new file mode 100644
index 000000000..0adfa3f42
--- /dev/null
+++ b/e2e/fixtures/agent-openapi-swagger/evals/connection-input-shape.eval.ts
@@ -0,0 +1,72 @@
+import { defineEval, type EveEvalTurn } from "eve/evals";
+import { satisfies } from "eve/evals/expect";
+
+const ADD_PET_TOOL = "petstore__addPet";
+
+export default defineEval({
+ tags: ["real-model"],
+ description:
+ "A real model builds a nested connection_execute input from the connection_search signature.",
+
+ async test(t) {
+ const turn = await t.send(
+ [
+ "Alice runs the Maple Street pet store, whose store id is `maple-street`.",
+ "This morning she took in a golden retriever named Biscuit. He is ready for adoption,",
+ "belongs in the Dogs category, and his photo is at https://example.com/photos/biscuit.jpg.",
+ "Use `connection_search` to find how to add a pet in the `petstore` connection, then add",
+ "Biscuit with `connection_execute`. Reply with the id the store assigns to him.",
+ ].join(" "),
+ );
+
+ turn.expectOk();
+ t.toolOrder(["connection_search", "connection_execute"]);
+ // The nested action carries the operation's HTTP result.
+ t.calledTool(ADD_PET_TOOL, { output: isStoredBiscuit });
+ t.messageIncludes("4217");
+
+ // Tracked, not gated: how often the first attempt already had the right shape.
+ t.check(
+ firstAddPetSucceeded(turn),
+ satisfies(
+ (succeeded: boolean) => succeeded,
+ "the first addPet call has a valid input shape",
+ ).soft(),
+ );
+ },
+});
+
+function isStoredBiscuit(value: unknown): boolean {
+ if (typeof value !== "object" || value === null) return false;
+ const { status, body } = value as { status?: unknown; body?: Record<string, unknown> };
+ const category = body?.category as { name?: unknown } | undefined;
+ return (
+ status === 200 &&
+ body?.id === 4217 &&
+ body.storeId === "maple-street" &&
+ body.name === "Biscuit" &&
+ body.status === "available" &&
+ typeof category?.name === "string" &&
+ /dog/iu.test(category.name) &&
+ Array.isArray(body.photoUrls) &&
+ body.photoUrls.includes("https://example.com/photos/biscuit.jpg")
+ );
+}
+
+/** Whether the first connection_execute call for addPet completed with a 200 response. */
+function firstAddPetSucceeded(turn: EveEvalTurn): boolean {
+ const first = turn.events
+ .flatMap((event) => (event.type === "actions.requested" ? event.data.actions : []))
+ .find(
+ (action) =>
+ action.kind === "tool-call" &&
+ action.toolName === "connection_execute" &&
+ (action.input as { tool?: unknown }).tool === "addPet",
+ );
+ if (first === undefined) return false;
+ const result = turn.events.find(
+ (event) => event.type === "action.result" && event.data.result.callId === first.callId,
+ );
+ if (result?.type !== "action.result" || result.data.status !== "completed") return false;
+ return (result.data.result as { output?: { status?: unknown } }).output?.status === 200;
+}
diff --git a/e2e/fixtures/agent-openapi-swagger/evals/dynamic-connection.eval.ts b/e2e/fixtures/agent-openapi-swagger/evals/dynamic-connection.eval.ts
index 055efb4f6..802a4ff5f 100644
--- a/e2e/fixtures/agent-openapi-swagger/evals/dynamic-connection.eval.ts
+++ b/e2e/fixtures/agent-openapi-swagger/evals/dynamic-connection.eval.ts
@@ -1,7 +1,7 @@
import { defineEval } from "eve/evals";
export default defineEval({
- description: "A session-scoped dynamic OpenAPI connection participates in connection_search.",
+ description: "A session-scoped dynamic OpenAPI connection is announced and searchable.",
async test(t) {
if (process.env.EVE_E2E_MODEL !== "mock") {
@@ -18,14 +18,15 @@ export default defineEval({
});
function hasDynamicStatusTool(value: unknown): boolean {
+ const tools = typeof value === "object" && value !== null ? Reflect.get(value, "tools") : [];
return (
- Array.isArray(value) &&
- value.some(
+ Array.isArray(tools) &&
+ tools.some(
(entry) =>
typeof entry === "object" &&
entry !== null &&
Reflect.get(entry, "connection") === "dynamic-catalog" &&
- Reflect.get(entry, "qualifiedName") === "dynamic-catalog__getStatus",
+ Reflect.get(entry, "tool") === "getStatus",
)
);
}
diff --git a/e2e/fixtures/agent-openapi-swagger/evals/kennel-mcp-results.eval.ts b/e2e/fixtures/agent-openapi-swagger/evals/kennel-mcp-results.eval.ts
new file mode 100644
index 000000000..c691dffd4
--- /dev/null
+++ b/e2e/fixtures/agent-openapi-swagger/evals/kennel-mcp-results.eval.ts
@@ -0,0 +1,73 @@
+import { defineEval } from "eve/evals";
+
+/** Failed tool outputs carry the error message; match its text whatever its wrapping. */
+const mentions = (text: string) => (value: unknown) => JSON.stringify(value).includes(text);
+
+export default defineEval({
+ description:
+ "connection_execute returns each MCP result shape, and its errors let the model correct a call.",
+
+ async test(t) {
+ if (process.env.EVE_E2E_MODEL !== "mock") {
+ t.skip("Requires the deterministic mock model to issue the exact calls.");
+ }
+
+ const turn = await t.send("KENNEL_MCP_E2E");
+ turn.expectOk();
+ t.succeeded();
+
+ // structuredContent wins over the text copy of the same result.
+ turn.calledTool("kennel__find_pet", {
+ count: 1,
+ output: { petId: 4217, name: "Biscuit", kennel: "B3" },
+ });
+ // Text-only results without an output schema are parsed as JSON, and the
+ // omitted `day` reaches the server as its schema default.
+ turn.calledTool("kennel__list_feedings", {
+ count: 1,
+ input: { day: "today" },
+ output: (value) =>
+ Array.isArray(value) &&
+ value.length === 2 &&
+ value.every((entry) => (entry as { day?: unknown }).day === "today"),
+ });
+ // Image content stays MCP content, and the model receives it as a file part.
+ turn.calledTool("kennel__pet_photo", {
+ count: 1,
+ output: mentions('"type":"image"'),
+ });
+ t.messageIncludes("photo-image-parts=1");
+
+ // isError results fail both the outer call and the nested action.
+ turn.calledTool("connection_execute", {
+ count: 1,
+ status: "failed",
+ input: { tool: "discharge_pet" },
+ output: mentions("adoption is in progress"),
+ });
+ turn.calledTool("kennel__discharge_pet", { count: 1, status: "failed" });
+
+ // Invalid input never reaches the server and returns the tool's signature.
+ turn.calledTool("connection_execute", {
+ count: 1,
+ status: "failed",
+ input: { tool: "book_visit", input: { petId: "4217" } },
+ output: (value) =>
+ mentions("Invalid input for")(value) && mentions("book_visit(input:")(value),
+ });
+ // The corrected call is the only one the server sees.
+ turn.calledTool("kennel__book_visit", {
+ count: 1,
+ output: { visitId: "V-88", petId: 4217, visit: { kind: "grooming" } },
+ });
+
+ // An unknown tool name points at the closest real one.
+ turn.calledTool("connection_execute", {
+ count: 1,
+ status: "failed",
+ input: { tool: "find_pets" },
+ output: mentions("Closest tools: find_pet"),
+ });
+ t.messageIncludes("KENNEL_MCP_DONE");
+ },
+});
diff --git a/e2e/fixtures/agent-openapi-swagger/evals/kennel-mcp.eval.ts b/e2e/fixtures/agent-openapi-swagger/evals/kennel-mcp.eval.ts
new file mode 100644
index 000000000..a96219ec1
--- /dev/null
+++ b/e2e/fixtures/agent-openapi-swagger/evals/kennel-mcp.eval.ts
@@ -0,0 +1,60 @@
+import { defineEval, type EveEvalTurn } from "eve/evals";
+import { satisfies } from "eve/evals/expect";
+
+export default defineEval({
+ tags: ["real-model"],
+ description:
+ "A real model reads an MCP tool's structured result and builds a nested MCP tool input from its signature.",
+
+ async test(t) {
+ const turn = await t.send(
+ [
+ "Bob works the front desk at the Maple Street kennel. Biscuit, a boarding golden retriever,",
+ "needs a grooming visit on October 14, 2026. Alice (555-0100) should be notified about it.",
+ "Use `connection_search` on the `kennel` connection to find the tools you need, look up",
+ "Biscuit's pet id, then book the visit with `connection_execute`.",
+ "Reply with the visit id the kennel returns.",
+ ].join(" "),
+ );
+
+ turn.expectOk();
+ t.calledTool("connection_search");
+ // The pet id comes from find_pet's structured result, not the prompt.
+ t.calledTool("kennel__find_pet", { output: { petId: 4217 } });
+ t.calledTool("kennel__book_visit", {
+ count: 1,
+ output: {
+ visitId: "V-88",
+ petId: 4217,
+ visit: { kind: "grooming", date: "2026-10-14" },
+ contacts: [{ name: /alice/iu, phone: /555-0100/u }],
+ },
+ });
+ t.messageIncludes("V-88");
+
+ // Tracked, not gated: whether the model built the nested input on its first try.
+ t.check(
+ firstBookingSucceeded(turn),
+ satisfies(
+ (succeeded: boolean) => succeeded,
+ "the first book_visit call has a valid input shape",
+ ).soft(),
+ );
+ },
+});
+
+function firstBookingSucceeded(turn: EveEvalTurn): boolean {
+ const first = turn.events
+ .flatMap((event) => (event.type === "actions.requested" ? event.data.actions : []))
+ .find(
+ (action) =>
+ action.kind === "tool-call" &&
+ action.toolName === "connection_execute" &&
+ (action.input as { tool?: unknown }).tool === "book_visit",
+ );
+ if (first === undefined) return false;
+ const result = turn.events.find(
+ (event) => event.type === "action.result" && event.data.result.callId === first.callId,
+ );
+ return result?.type === "action.result" && result.data.status === "completed";
+}
diff --git a/e2e/fixtures/agent-openapi-swagger/evals/petstore-swagger-approval.eval.ts b/e2e/fixtures/agent-openapi-swagger/evals/petstore-swagger-approval.eval.ts
index d331a3bdb..5c878cabe 100644
--- a/e2e/fixtures/agent-openapi-swagger/evals/petstore-swagger-approval.eval.ts
+++ b/e2e/fixtures/agent-openapi-swagger/evals/petstore-swagger-approval.eval.ts
@@ -12,7 +12,7 @@ export default defineEval({
const parked = await t.send(
[
"Use the `connection_search` tool with connection `petstore-approval` to find the inventory operation.",
- "Then call `petstore-approval__getInventory` with an empty object.",
+ "Then call it with `connection_execute` and an empty input.",
"Wait for approval if requested.",
"After the tool runs, reply with the exact words `inventory received` if the tool result contains inventory counts.",
].join("\n"),
@@ -20,12 +20,16 @@ export default defineEval({
const session = parked.session;
parked.expectOk();
+ // The approval belongs to the model's connection_execute call.
session.requireInputRequest({
display: "confirmation",
optionIds: ["approve", "cancel"],
- toolName: PETSTORE_APPROVAL_INVENTORY_TOOL,
+ toolName: "connection_execute",
+ });
+ parked.calledTool("connection_execute", { status: "pending", count: 1 });
+ parked.notEvent("action.result", {
+ data: { result: { toolName: PETSTORE_APPROVAL_INVENTORY_TOOL } },
});
- parked.calledTool(PETSTORE_APPROVAL_INVENTORY_TOOL, { status: "pending", count: 1 });
const approved = await session.respondAll("approve");
approved.expectOk();
diff --git a/e2e/fixtures/agent-openapi-swagger/evals/petstore-swagger.eval.ts b/e2e/fixtures/agent-openapi-swagger/evals/petstore-swagger.eval.ts
index f03e7df71..c3e4ad89e 100644
--- a/e2e/fixtures/agent-openapi-swagger/evals/petstore-swagger.eval.ts
+++ b/e2e/fixtures/agent-openapi-swagger/evals/petstore-swagger.eval.ts
@@ -1,31 +1,27 @@
import { defineEval } from "eve/evals";
-const SEARCH_TOOL = "connection_search";
const PETSTORE_INVENTORY_TOOL = "petstore__getInventory";
export default defineEval({
tags: ["real-model"],
- description: "A fixture-owned Swagger 2.0 document exposes and calls getInventory over HTTP.",
+ description:
+ "A fixture-owned Swagger 2.0 document is searched and its getInventory called over HTTP.",
async test(t) {
const turn = await t.send(
[
"Use the `connection_search` tool to find the inventory operation in the `petstore` connection.",
- "Then call `petstore__getInventory` with an empty object.",
+ "Then call it with `connection_execute` and an empty input.",
"Reply with the exact words `inventory received` if the tool result contains inventory counts.",
].join("\n"),
);
- turn.calledTool(PETSTORE_INVENTORY_TOOL, {
- output: hasInventoryCounts,
- });
+ turn.calledTool(PETSTORE_INVENTORY_TOOL, { output: hasInventoryCounts });
t.succeeded();
- t.toolOrder([SEARCH_TOOL, PETSTORE_INVENTORY_TOOL]);
- t.calledTool(SEARCH_TOOL);
- t.calledTool(PETSTORE_INVENTORY_TOOL, {
- output: hasInventoryCounts,
- });
+ t.toolOrder(["connection_search", "connection_execute"]);
+ t.calledTool("connection_search");
+ t.calledTool(PETSTORE_INVENTORY_TOOL, { output: hasInventoryCounts });
t.messageIncludes(/\binventory received\b/iu);
},
});
diff --git a/e2e/fixtures/agent-openapi-swagger/kennel.ts b/e2e/fixtures/agent-openapi-swagger/kennel.ts
new file mode 100644
index 000000000..c36219657
--- /dev/null
+++ b/e2e/fixtures/agent-openapi-swagger/kennel.ts
@@ -0,0 +1,116 @@
+import { petstoreHeaders } from "./petstore";
+
+/**
+ * A fixture-owned MCP server whose tools cover each shape of MCP result that
+ * `connection_execute` returns: structured content, JSON text, images, and
+ * tool errors, plus a nested input the model has to build from a signature.
+ */
+export const KENNEL_TOOLS = [
+ {
+ name: "find_pet",
+ description: "Look up a pet boarding at the kennel by name.",
+ inputSchema: {
+ type: "object",
+ properties: { name: { type: "string", description: "The pet's name, such as Biscuit." } },
+ required: ["name"],
+ additionalProperties: false,
+ },
+ outputSchema: {
+ type: "object",
+ properties: {
+ petId: { type: "integer" },
+ name: { type: "string" },
+ kennel: { type: "string" },
+ },
+ required: ["petId", "name", "kennel"],
+ },
+ },
+ {
+ name: "list_feedings",
+ description: "List a pet's feeding schedule for a day.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ petId: { type: "integer" },
+ day: { type: "string", enum: ["today", "tomorrow"], default: "today" },
+ },
+ required: ["petId"],
+ additionalProperties: false,
+ },
+ },
+ {
+ name: "pet_photo",
+ description: "Return the latest photo of a pet.",
+ inputSchema: {
+ type: "object",
+ properties: { petId: { type: "integer" } },
+ required: ["petId"],
+ additionalProperties: false,
+ },
+ },
+ {
+ name: "discharge_pet",
+ description: "Send a pet home and close its boarding record.",
+ inputSchema: {
+ type: "object",
+ properties: { petId: { type: "integer" } },
+ required: ["petId"],
+ additionalProperties: false,
+ },
+ },
+ {
+ name: "book_visit",
+ description: "Book a care visit for a boarding pet and notify its contacts.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ petId: { type: "integer", description: "The id find_pet returns." },
+ visit: {
+ type: "object",
+ properties: {
+ kind: { type: "string", enum: ["checkup", "grooming", "vaccination"] },
+ date: {
+ type: "string",
+ pattern: "^\\d{4}-\\d{2}-\\d{2}$",
+ description: "Visit date as YYYY-MM-DD.",
+ },
+ notes: { type: "string" },
+ },
+ required: ["kind", "date"],
+ additionalProperties: false,
+ },
+ contacts: {
+ type: "array",
+ minItems: 1,
+ description: "People to notify about the visit.",
+ items: {
+ type: "object",
+ properties: { name: { type: "string" }, phone: { type: "string" } },
+ required: ["name", "phone"],
+ additionalProperties: false,
+ },
+ },
+ },
+ required: ["petId", "visit", "contacts"],
+ additionalProperties: false,
+ },
+ },
+] as const;
+
+export const BISCUIT_PET_ID = 4217;
+export const BISCUIT_VISIT_ID = "V-88";
+
+/** A 1x1 PNG, small enough to inline as MCP image content. */
+export const PET_PHOTO_PNG =
+ "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGM4Mc0IAAO6AZFYX8ZRAAAAAElFTkSuQmCC";
+
+export function kennelUrl(): string {
+ const deploymentHost = process.env.VERCEL_URL;
+ const host = deploymentHost
+ ? `https://${deploymentHost}`
+ : (process.env.WORKFLOW_LOCAL_BASE_URL ?? "http://127.0.0.1:3000");
+ return `${host}${process.env.EVE_PUBLIC_ROUTE_PREFIX ?? ""}/fixture-kennel/mcp`;
+}
+
+/** The kennel reuses the petstore's preview protection bypass. */
+export const kennelHeaders = petstoreHeaders;
diff --git a/e2e/fixtures/agent-openapi-swagger/package.json b/e2e/fixtures/agent-openapi-swagger/package.json
index 5b0b30fba..c7ae70514 100644
--- a/e2e/fixtures/agent-openapi-swagger/package.json
+++ b/e2e/fixtures/agent-openapi-swagger/package.json
@@ -18,5 +18,8 @@
"devDependencies": {
"@types/node": "catalog:",
"typescript": "catalog:"
+ },
+ "e2e": {
+ "modelMatrix": "full"
}
}
diff --git a/e2e/fixtures/agent-openapi-swagger/petstore.ts b/e2e/fixtures/agent-openapi-swagger/petstore.ts
index c320000b7..36b28135f 100644
--- a/e2e/fixtures/agent-openapi-swagger/petstore.ts
+++ b/e2e/fixtures/agent-openapi-swagger/petstore.ts
@@ -2,7 +2,37 @@ export const PETSTORE_SPEC = {
swagger: "2.0",
info: { title: "Sample Petstore", version: "1.0.0" },
produces: ["application/json"],
+ definitions: {
+ Category: {
+ type: "object",
+ required: ["name"],
+ properties: { name: { type: "string", description: "Category name, such as Dogs." } },
+ },
+ Pet: {
+ type: "object",
+ required: ["name", "status", "category", "photoUrls"],
+ properties: {
+ name: { type: "string", minLength: 1 },
+ status: { type: "string", enum: ["available", "pending", "sold"] },
+ category: { $ref: "#/definitions/Category" },
+ photoUrls: { type: "array", minItems: 1, items: { type: "string" } },
+ tags: { type: "array", items: { type: "string" } },
+ },
+ },
+ },
paths: {
+ "/store/{storeId}/pet": {
+ post: {
+ operationId: "addPet",
+ summary: "Add a pet to a store's catalog.",
+ consumes: ["application/json"],
+ parameters: [
+ { in: "path", name: "storeId", required: true, type: "string" },
+ { in: "body", name: "body", required: true, schema: { $ref: "#/definitions/Pet" } },
+ ],
+ responses: { 200: { description: "The stored pet with its id." } },
+ },
+ },
"/store/inventory": {
get: {
operationId: "getInventory",
@@ -23,5 +53,19 @@ export function petstoreBaseUrl(): string {
const host = deploymentHost
? `https://${deploymentHost}`
: (process.env.WORKFLOW_LOCAL_BASE_URL ?? "http://127.0.0.1:3000");
- return `${host}/fixture-petstore`;
+ return `${host}${process.env.EVE_PUBLIC_ROUTE_PREFIX ?? ""}/fixture-petstore`;
+}
+
+/** The spec URL, carrying the preview protection bypass because spec fetches send no connection headers. */
+export function petstoreSpecUrl(): string {
+ const url = new URL(`${petstoreBaseUrl()}/swagger`);
+ const bypass = process.env.VERCEL_AUTOMATION_BYPASS_SECRET;
+ if (bypass) url.searchParams.set("x-vercel-protection-bypass", bypass);
+ return url.href;
+}
+
+/** Lets operation calls reach a protected preview deployment of this fixture. */
+export function petstoreHeaders(): Record<string, string> {
+ const bypass = process.env.VERCEL_AUTOMATION_BYPASS_SECRET;
+ return bypass ? { "x-vercel-protection-bypass": bypass } : {};
}
diff --git a/e2e/fixtures/agent-workflow-tools/agent/agent.ts b/e2e/fixtures/agent-workflow-tools/agent/agent.ts
index 25efb3f23..30114a20b 100644
--- a/e2e/fixtures/agent-workflow-tools/agent/agent.ts
+++ b/e2e/fixtures/agent-workflow-tools/agent/agent.ts
@@ -69,18 +69,18 @@ async function respond(request: MockModelRequest): Promise<MockModelResponse | s
const scenario = respondToTaskScenario(request, directiveOf(message));
if (scenario !== undefined) return scenario;
if (message.includes("private-catalog")) {
- const result = request.toolResults.find((entry) => entry.name === "connection_search");
- if (result === undefined) {
+ const search = request.toolResults.find((entry) => entry.name === "connection_search");
+ if (search === undefined) {
return {
toolCalls: [
{
name: "connection_search",
- input: { connection: "private-catalog", keywords: "items" },
+ input: { connection: "private-catalog", query: "items" },
},
],
};
}
- return JSON.stringify(result.output);
+ return JSON.stringify(search.output);
}
const stepAuth = /WORKFLOW-STEP-AUTH-(IMPLICIT|EXPLICIT|REJECTED)/u.exec(message);
diff --git a/e2e/fixtures/agent-workflow-tools/evals/connection-search.authorization.eval.ts b/e2e/fixtures/agent-workflow-tools/evals/connection-tools.authorization.eval.ts
similarity index 71%
rename from e2e/fixtures/agent-workflow-tools/evals/connection-search.authorization.eval.ts
rename to e2e/fixtures/agent-workflow-tools/evals/connection-tools.authorization.eval.ts
index 9602991e2..72b50854e 100644
--- a/e2e/fixtures/agent-workflow-tools/evals/connection-search.authorization.eval.ts
+++ b/e2e/fixtures/agent-workflow-tools/evals/connection-tools.authorization.eval.ts
@@ -3,16 +3,17 @@ import { z } from "zod";
import { fixtureAuthorizationCallback } from "../agent/lib/fake-service.ts";
-const searchResult = z.array(z.object({ qualifiedName: z.string() }));
+const searchResult = z.object({
+ tools: z.array(z.object({ connection: z.string(), tool: z.string(), signature: z.string() })),
+});
export default defineEval({
- description:
- "Connection search pauses for sign-in, then discovers tools over authenticated HTTP.",
+ description: "Connection search pauses for sign-in, then finds tools over authenticated HTTP.",
timeoutMs: 90_000,
async test(t) {
const started = await t.send(
- "Alice wants to see which tools are available in private-catalog. Search for its items tools, then report the available tool names.",
+ "Alice wants to see which tools are available in private-catalog. Search that connection for its items tools, then report the available tool names.",
);
const session = started.session;
started.expectOk();
@@ -51,10 +52,17 @@ export default defineEval({
const result = searchResult.safeParse(value);
return (
result.success &&
- result.data.some((entry) => entry.qualifiedName === "private-catalog__list_items")
+ result.data.tools.some(
+ (entry) =>
+ entry.connection === "private-catalog" &&
+ entry.tool === "list_items" &&
+ entry.signature.startsWith("list_items("),
+ )
);
},
});
- completed.messageIncludes("private-catalog__list_items");
+ // Calling the tool needs the token in a later step. A real provider persists
+ // it; this fixture's fake provider keeps none after sign-in.
+ completed.messageIncludes("list_items");
},
});
diff --git a/packages/eve-code/test/scenario/worker-manifest.test.ts b/packages/eve-code/test/scenario/worker-manifest.test.ts
index 4ece97e05..0ff7023ec 100644
--- a/packages/eve-code/test/scenario/worker-manifest.test.ts
+++ b/packages/eve-code/test/scenario/worker-manifest.test.ts
@@ -73,7 +73,7 @@ test("built worker keeps explicit read tools without shell or write capabilities
assert.deepEqual(worker.agent.connections, []);
assert.deepEqual(
worker.agent.dynamicTools.map((tool) => tool.slug),
- ["connection_search"],
+ ["connection_tools"],
);
} finally {
await rm(root, { recursive: true, force: true });
diff --git a/packages/eve/extension-contracts/compatibility/channel/v38.ts b/packages/eve/extension-contracts/compatibility/channel/v38.ts
new file mode 100644
index 000000000..6bbc50062
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/channel/v38.ts
@@ -0,0 +1,14 @@
+import { defineChannel, POST } from "#public/channels/index.js";
+
+// Epoch 38 tool-call action requests had no `parentCallId`; epoch 39 adds it as optional.
+export default defineChannel({
+ routes: [
+ POST("/answer/:sessionId", async (_request, { attachSession, params }) => {
+ await attachSession(params.sessionId!).respond(
+ [{ optionId: "approve", requestId: "approval-1" }],
+ { auth: null },
+ );
+ return new Response("ok");
+ }),
+ ],
+});
diff --git a/packages/eve/extension-contracts/compatibility/connection/v33.ts b/packages/eve/extension-contracts/compatibility/connection/v33.ts
new file mode 100644
index 000000000..28c5a452a
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/connection/v33.ts
@@ -0,0 +1,11 @@
+import { defineMcpClientConnection } from "#public/connections/index.js";
+
+// Epoch 33 tool-call action requests had no `parentCallId`; epoch 34 adds it as optional.
+// Connection approval policies keep receiving the qualified tool name.
+export default defineMcpClientConnection({
+ description: "Search the support knowledge base.",
+ url: "https://support.example.com/mcp",
+ approval({ toolName }) {
+ return toolName.endsWith("__search") ? "approved" : "user-approval";
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/dynamicInstructions/v27.ts b/packages/eve/extension-contracts/compatibility/dynamicInstructions/v27.ts
new file mode 100644
index 000000000..7131b7562
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/dynamicInstructions/v27.ts
@@ -0,0 +1,9 @@
+import { defineDynamic, defineInstructions } from "#public/instructions/index.js";
+
+// Epoch 27 tool-call action requests had no `parentCallId`; epoch 28 adds it as optional.
+export default defineDynamic({
+ events: {
+ "turn.started": (_event, ctx) =>
+ defineInstructions({ markdown: `Review evidence for session ${ctx.session.id}.` }),
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/dynamicSkill/v26.ts b/packages/eve/extension-contracts/compatibility/dynamicSkill/v26.ts
new file mode 100644
index 000000000..67bed0d66
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/dynamicSkill/v26.ts
@@ -0,0 +1,12 @@
+import { defineDynamic, defineSkill } from "#public/skills/index.js";
+
+// Epoch 26 tool-call action requests had no `parentCallId`; epoch 27 adds it as optional.
+export default defineDynamic({
+ events: {
+ "turn.started": (_event, ctx) =>
+ defineSkill({
+ description: "Review the active request.",
+ markdown: `Review evidence for session ${ctx.session.id}.`,
+ }),
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/dynamicTool/v63.ts b/packages/eve/extension-contracts/compatibility/dynamicTool/v63.ts
new file mode 100644
index 000000000..5a971fd2c
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/dynamicTool/v63.ts
@@ -0,0 +1,14 @@
+import { defineDynamic, defineTool } from "#public/tools/index.js";
+
+// Epoch 63 tool-call action requests had no `parentCallId`; epoch 64 adds it as optional.
+export default defineDynamic({
+ events: {
+ "turn.started": () => ({
+ session_id: defineTool({
+ description: "Return the current session id.",
+ inputSchema: { type: "object", properties: {} },
+ execute: (_input, ctx) => ctx.session.id,
+ }),
+ }),
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/hook/v32.ts b/packages/eve/extension-contracts/compatibility/hook/v32.ts
new file mode 100644
index 000000000..6ff0b9c5d
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/hook/v32.ts
@@ -0,0 +1,14 @@
+import { defineHook } from "#public/hooks/index.js";
+
+// Epoch 32 tool-call action requests had no `parentCallId`; epoch 33 adds it
+// as optional for nested actions. Hooks that read tool calls keep working.
+export default defineHook({
+ events: {
+ "actions.requested"(event) {
+ for (const action of event.data.actions) {
+ if (action.kind !== "tool-call") continue;
+ console.info("tool requested", { callId: action.callId, toolName: action.toolName });
+ }
+ },
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/schedule/v20.ts b/packages/eve/extension-contracts/compatibility/schedule/v20.ts
new file mode 100644
index 000000000..c82885327
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/schedule/v20.ts
@@ -0,0 +1,17 @@
+import { defineChannel } from "#public/channels/index.js";
+import { defineSchedule } from "#public/schedules/index.js";
+
+// Epoch 20 tool-call action requests had no `parentCallId`; epoch 21 adds it as optional.
+const updates = defineChannel({
+ routes: [],
+ receive(input, { from }) {
+ return from("daily-updates").send(input.message, { auth: input.auth });
+ },
+});
+
+export default defineSchedule({
+ cron: "0 9 * * *",
+ async run({ to, appAuth }) {
+ await to(updates, {}).send("Prepare the daily summary.", { auth: appAuth });
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/subagent/v24.ts b/packages/eve/extension-contracts/compatibility/subagent/v24.ts
new file mode 100644
index 000000000..74550b706
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/subagent/v24.ts
@@ -0,0 +1,14 @@
+import { defineAgent, defineDynamic } from "#public/index.js";
+
+// Epoch 24 tool-call action requests had no `parentCallId`; epoch 25 adds it as optional.
+export default defineDynamic({
+ events: {
+ "turn.started": (_event, ctx) =>
+ ctx.session.auth.current === null
+ ? null
+ : defineAgent({
+ description: "Investigate the authenticated user request.",
+ model: "openai/gpt-5.6-sol",
+ }),
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/tool/v65.ts b/packages/eve/extension-contracts/compatibility/tool/v65.ts
new file mode 100644
index 000000000..c92ce861b
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/tool/v65.ts
@@ -0,0 +1,17 @@
+import { defineTool } from "#public/tools/index.js";
+
+// Epoch 65 tool-call action requests had no `parentCallId`; epoch 66 adds it
+// as optional for nested actions. Approval policies keep reading the same fields.
+export default defineTool({
+ description: "Look up an order by id.",
+ inputSchema: {
+ type: "object",
+ properties: { id: { type: "string" } },
+ required: ["id"],
+ },
+ approval: ({ toolName, toolInput }) =>
+ toolName === "lookup_order" && typeof toolInput?.id === "string"
+ ? "not-applicable"
+ : "user-approval",
+ execute: (input) => ({ id: (input as { readonly id: string }).id }),
+});
diff --git a/packages/eve/extension-contracts/reports/channel/v39.json b/packages/eve/extension-contracts/reports/channel/v39.json
new file mode 100644
index 000000000..c67f4bc60
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/channel/v39.json
@@ -0,0 +1,21 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "channel",
+ "epoch": 39,
+ "sha256": "d731a33d875c2a34baf443f2af440d3413640ffe8852c6d890a92aab92f6c4fb",
+ "exports": [
+ "DELETE",
+ "GET",
+ "HEAD",
+ "OPTIONS",
+ "PATCH",
+ "POST",
+ "PUT",
+ "WS",
+ "createWebSocketUpgradeServer",
+ "defineChannel",
+ "disableRoute",
+ "isChannel",
+ "isDisabledRouteSentinel"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/connection/v34.json b/packages/eve/extension-contracts/reports/connection/v34.json
new file mode 100644
index 000000000..92287b91c
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/connection/v34.json
@@ -0,0 +1,16 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "connection",
+ "epoch": 34,
+ "sha256": "f3c05cdab32fec230061848eff878a31082f531878c9ba4550d9d0079add1d79",
+ "exports": [
+ "ConnectionAuthorizationFailedError",
+ "ConnectionAuthorizationRequiredError",
+ "defineDynamic",
+ "defineInteractiveAuthorization",
+ "defineMcpClientConnection",
+ "defineOpenAPIConnection",
+ "isConnectionAuthorizationFailedError",
+ "isConnectionAuthorizationRequiredError"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/dynamicInstructions/v28.json b/packages/eve/extension-contracts/reports/dynamicInstructions/v28.json
new file mode 100644
index 000000000..79314508c
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/dynamicInstructions/v28.json
@@ -0,0 +1,7 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "dynamicInstructions",
+ "epoch": 28,
+ "sha256": "b6e7a228a171eb9d164ab7bfee9ff28a92b68eaa600a475bd21d58fedc9cfd32",
+ "exports": ["defineDynamic"]
+}
diff --git a/packages/eve/extension-contracts/reports/dynamicSkill/v27.json b/packages/eve/extension-contracts/reports/dynamicSkill/v27.json
new file mode 100644
index 000000000..73d778df4
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/dynamicSkill/v27.json
@@ -0,0 +1,7 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "dynamicSkill",
+ "epoch": 27,
+ "sha256": "7db92e503a2212d0fa6d1c70bd49760b5896b3f88045c2763e8a535dfe6e3fd9",
+ "exports": ["defineDynamic"]
+}
diff --git a/packages/eve/extension-contracts/reports/dynamicTool/v64.json b/packages/eve/extension-contracts/reports/dynamicTool/v64.json
new file mode 100644
index 000000000..594a58439
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/dynamicTool/v64.json
@@ -0,0 +1,16 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "dynamicTool",
+ "epoch": 64,
+ "sha256": "c9423bf8e2e744cf5ee732e93a7b3c8872091594dcce23f74aab6474721a8e45",
+ "exports": [
+ "DynamicToolEntry",
+ "DynamicToolEvents",
+ "DynamicToolResult",
+ "DynamicToolSet",
+ "auto",
+ "defineDurableCallback",
+ "defineDurableSchema",
+ "defineDynamic"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/hook/v33.json b/packages/eve/extension-contracts/reports/hook/v33.json
new file mode 100644
index 000000000..e726aade9
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/hook/v33.json
@@ -0,0 +1,7 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "hook",
+ "epoch": 33,
+ "sha256": "c89a61ce40321efbfea41d48a7987a23c3a619ad90d5a91280076d7278cbf273",
+ "exports": ["defineHook"]
+}
diff --git a/packages/eve/extension-contracts/reports/schedule/v21.json b/packages/eve/extension-contracts/reports/schedule/v21.json
new file mode 100644
index 000000000..b43661045
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/schedule/v21.json
@@ -0,0 +1,14 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "schedule",
+ "epoch": 21,
+ "sha256": "932bf2152757feda6b6fe0dade823464775c2f86b27cf0647fa7df9d95294d63",
+ "exports": [
+ "ScheduleDefinition",
+ "ScheduleHandlerArgs",
+ "ScheduleRunHandler",
+ "ScheduleToFn",
+ "TypedReceiveTarget",
+ "defineSchedule"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/subagent/v25.json b/packages/eve/extension-contracts/reports/subagent/v25.json
new file mode 100644
index 000000000..e8f1799cf
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/subagent/v25.json
@@ -0,0 +1,23 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "subagent",
+ "epoch": 25,
+ "sha256": "1e0acc44b1a14b8f9f759c0815cc07bf1f48c12db047011ae47a2bfa856ce9fe",
+ "exports": [
+ "AgentCompactionDefinition",
+ "AgentDefinition",
+ "AgentModelDefinition",
+ "AgentStaticModelDefinition",
+ "DefinedAgent",
+ "DynamicLocalSubagentDefinition",
+ "DynamicSubagentDefinition",
+ "RemoteAgentDefinition",
+ "RemoteAgentDefinitionInput",
+ "WorkspaceAgentDefinition",
+ "WorkspaceAgentTransport",
+ "defineAgent",
+ "defineDynamic",
+ "defineRemoteAgent",
+ "defineWorkspaceAgent"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/tool/v66.json b/packages/eve/extension-contracts/reports/tool/v66.json
new file mode 100644
index 000000000..b1d450b42
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/tool/v66.json
@@ -0,0 +1,28 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "tool",
+ "epoch": 66,
+ "sha256": "8a8429a841960eb67c9c9ab16139b37aa1985a0054f624210d1818971d0f3df2",
+ "exports": [
+ "AgentRouterInput",
+ "AgentRouterTool",
+ "WorkflowStepToolContext",
+ "WorkflowTool",
+ "WorkflowToolDefinition",
+ "WorkflowToolInput",
+ "WorkflowToolOptions",
+ "agentRouter",
+ "defaultWebSearch",
+ "defineTool",
+ "defineWorkflowTool",
+ "disableTool",
+ "evaluate",
+ "isDisabledToolSentinel",
+ "isWebSearchToolDefinition",
+ "toolOutput",
+ "toolOutputPart",
+ "toolResultFrom",
+ "webSearch",
+ "workflow"
+ ]
+}
diff --git a/packages/eve/package.json b/packages/eve/package.json
index 40b2d1c3d..1bdbcd8e1 100644
--- a/packages/eve/package.json
+++ b/packages/eve/package.json
@@ -182,11 +182,6 @@
"import": "./dist/src/public/tools/load-skill.js",
"default": "./dist/src/public/tools/load-skill.js"
},
- "./tools/connection_search": {
- "types": "./dist/src/public/tools/connection-search.d.ts",
- "import": "./dist/src/public/tools/connection-search.js",
- "default": "./dist/src/public/tools/connection-search.js"
- },
"./tools/glob": {
"types": "./dist/src/public/tools/glob.d.ts",
"import": "./dist/src/public/tools/glob.js",
diff --git a/packages/eve/src/channel/task-card.test.ts b/packages/eve/src/channel/task-card.test.ts
new file mode 100644
index 000000000..17bf402d1
--- /dev/null
+++ b/packages/eve/src/channel/task-card.test.ts
@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+
+import { createActionResultEvent, type UnstampedMessageStreamEvent } from "#protocol/message.js";
+
+import { taskCardView, trackTaskCardEvent, type TaskCardTurn } from "./task-card.js";
+
+const AT = "2026-09-30T00:00:00.000Z";
+
+function fold(events: readonly UnstampedMessageStreamEvent[]): TaskCardTurn {
+ let turns: Readonly<Record<string, TaskCardTurn>> = {};
+ for (const event of events) turns = { ...turns, ...trackTaskCardEvent(turns, event, AT) };
+ return turns["turn-1"]!;
+}
+
+describe("task card", () => {
+ it("shows a connection call as one row, not also its nested connection tool", () => {
+ const turn = fold([
+ {
+ type: "actions.requested",
+ data: {
+ turnId: "turn-1",
+ sequence: 0,
+ stepIndex: 0,
+ actions: [
+ {
+ kind: "tool-call",
+ callId: "call-1",
+ toolName: "connection_execute",
+ input: { connection: "kennel", tool: "book_visit", input: {} },
+ },
+ ],
+ presentation: { "call-1": { label: "kennel__book_visit" } },
+ },
+ },
+ {
+ type: "actions.requested",
+ data: {
+ turnId: "turn-1",
+ sequence: 1,
+ stepIndex: 0,
+ actions: [
+ {
+ kind: "tool-call",
+ callId: "call-1:nested",
+ parentCallId: "call-1",
+ toolName: "kennel__book_visit",
+ input: {},
+ },
+ ],
+ },
+ },
+ ...["call-1:nested", "call-1"].map((callId, index) =>
+ createActionResultEvent({
+ result: { kind: "tool-result", callId, toolName: "connection_execute", output: {} },
+ sequence: 2 + index,
+ stepIndex: 0,
+ turnId: "turn-1",
+ }),
+ ),
+ ]);
+
+ const { actions } = taskCardView("turn-1", turn, { audience: "public" });
+ expect(actions).toHaveLength(1);
+ expect(actions[0]).toMatchObject({ id: "call-1", status: "completed" });
+ expect(JSON.stringify(actions[0])).toContain("kennel__book_visit");
+ });
+});
diff --git a/packages/eve/src/channel/task-card.ts b/packages/eve/src/channel/task-card.ts
index 6bdad0b48..a7e733062 100644
--- a/packages/eve/src/channel/task-card.ts
+++ b/packages/eve/src/channel/task-card.ts
@@ -206,10 +206,15 @@ function trackTurnEvent(
const { turnId } = event.data;
const current = turns[turnId] ?? { calls: [], ended: false };
const known = new Set(current.calls.map((call) => call.callId));
+ // Nested actions (such as a connection tool run by connection_execute)
+ // already appear as their parent call's row.
const requested = event.data.actions.filter(
(action) =>
!known.has(action.callId) &&
- !(action.kind === "tool-call" && isTaskControlTool(action.toolName)),
+ !(
+ action.kind === "tool-call" &&
+ (isTaskControlTool(action.toolName) || action.parentCallId !== undefined)
+ ),
);
if (requested.length === 0) return undefined;
const calls = requested.map((action) =>
diff --git a/packages/eve/src/cli/dev/tui/runner.ts b/packages/eve/src/cli/dev/tui/runner.ts
index e59cedc91..108091da7 100644
--- a/packages/eve/src/cli/dev/tui/runner.ts
+++ b/packages/eve/src/cli/dev/tui/runner.ts
@@ -2382,8 +2382,13 @@ async function* eveEventsToTUIStream(
case "actions.requested": {
const data = (event as ActionsRequestedStreamEvent).data;
+ // Nested actions render through their parent call's row and label.
const actions = data.actions.flatMap((action) =>
- action.kind === "tool-call" && !isTaskControlTool(action.toolName) ? [action] : [],
+ action.kind === "tool-call" &&
+ action.parentCallId === undefined &&
+ !isTaskControlTool(action.toolName)
+ ? [action]
+ : [],
);
if (actions.length === 0) break;
partEpoch += 1;
diff --git a/packages/eve/src/cli/dev/tui/subagent-pump.ts b/packages/eve/src/cli/dev/tui/subagent-pump.ts
index 07e002833..ef99bf3cf 100644
--- a/packages/eve/src/cli/dev/tui/subagent-pump.ts
+++ b/packages/eve/src/cli/dev/tui/subagent-pump.ts
@@ -541,6 +541,7 @@ export class SubagentPump {
finalizeCurrent();
for (const action of event.data.actions) {
if (action.kind !== "tool-call" || isTaskControlTool(action.toolName)) continue;
+ if (action.parentCallId !== undefined) continue;
this.#registerChildTool(callId, run, {
childCallId: action.callId,
toolName: action.toolName,
diff --git a/packages/eve/src/cli/dev/tui/tool-presentation.test.ts b/packages/eve/src/cli/dev/tui/tool-presentation.test.ts
index 38b73604a..9cfe06cbc 100644
--- a/packages/eve/src/cli/dev/tui/tool-presentation.test.ts
+++ b/packages/eve/src/cli/dev/tui/tool-presentation.test.ts
@@ -146,9 +146,12 @@ describe("presentTool", () => {
expect(presentTool("agent", { message: "Audit the auth flow.\nDetails…" }).title).toBe(
"Delegate Audit the auth flow.",
);
- expect(presentTool("connection_search", { keywords: "linear issues" }).title).toBe(
- "Discover linear issues",
+ expect(presentTool("connection_search", { query: "linear issues" }).title).toBe(
+ "Search linear issues",
);
+ expect(
+ presentTool("connection_execute", { connection: "linear", tool: "list_issues" }).title,
+ ).toBe("Call linear.list_issues");
expect(presentTool("final_output", { anything: true }).title).toBe("Return final output");
});
diff --git a/packages/eve/src/cli/dev/tui/tool-presentation.ts b/packages/eve/src/cli/dev/tui/tool-presentation.ts
index 06147872f..413053135 100644
--- a/packages/eve/src/cli/dev/tui/tool-presentation.ts
+++ b/packages/eve/src/cli/dev/tui/tool-presentation.ts
@@ -92,10 +92,23 @@ const BUILTIN_TOOL_COPY: Readonly<Record<string, BuiltinToolCopy>> = {
singularNoun: "command",
pluralNoun: "commands",
},
+ connection_execute: {
+ verb: "Call",
+ pastVerb: "Called",
+ argKey: "",
+ extractItem: (input) => {
+ const connection = salientArg(input, "connection");
+ const tool = salientArg(input, "tool");
+ return connection === undefined || tool === undefined ? undefined : `${connection}.${tool}`;
+ },
+ singularNoun: "connection tool",
+ pluralNoun: "connection tools",
+ },
connection_search: {
- verb: "Discover",
- pastVerb: "Discovered",
- argKey: "keywords",
+ verb: "Search",
+ pastVerb: "Searched",
+ argKey: "query",
+ extractItem: (input) => salientArg(input, "connection"),
singularNoun: "tool search",
pluralNoun: "tool searches",
},
diff --git a/packages/eve/src/compiler/default-tool-policy.ts b/packages/eve/src/compiler/default-tool-policy.ts
index 84524a2b4..965fab3db 100644
--- a/packages/eve/src/compiler/default-tool-policy.ts
+++ b/packages/eve/src/compiler/default-tool-policy.ts
@@ -3,25 +3,28 @@ import type {
FinalizedNodeSourceState,
PhaseOneNodeSourceState,
} from "#compiler/node-source-state.js";
-import type { CompiledToolEntry } from "#compiler/normalize-tool.js";
import {
canonicalSourceSlot,
composeAgentModuleCandidates,
type AgentSourceCandidate,
} from "#compiler/source-graph.js";
-const REQUIRED_FRAMEWORK_TOOL_SLOTS = new Set(["tools/connection_search"]);
+const CONNECTION_TOOLS_SLOT = "tools/connection_tools";
+/** Slots of the closed connection tools and the framework module that provides them. */
+const CONNECTION_TOOL_SLOTS = new Set([
+ CONNECTION_TOOLS_SLOT,
+ "tools/connection_search",
+ "tools/connection_execute",
+]);
-export function assertFrameworkToolPolicy(
- candidate: AgentSourceCandidate,
- result: CompiledToolEntry,
-): void {
+/** Rejects authored sources that would replace or disable the connection tools. */
+export function assertFrameworkToolPolicy(candidate: AgentSourceCandidate): void {
+ if (candidate.layer === "framework-default") return;
const slot = canonicalSourceSlot(candidate.logicalPath);
- if (slot === "tools/connection_search" && result.kind === "disabled") {
- throw new Error(
- 'The required "connection_search" tool cannot be disabled. Remove "agent/tools/connection_search.ts" or export a replacement tool from it.',
- );
- }
+ if (!CONNECTION_TOOL_SLOTS.has(slot)) return;
+ throw new Error(
+ `"agent/${slot}.ts" is reserved. connection_search and connection_execute are framework tools that cannot be replaced or disabled; they exist only while the agent has connections. Rename the file.`,
+ );
}
export function applyAgentToolPolicy(
@@ -70,7 +73,7 @@ export function applyDefaultToolPolicy(
return (
candidate.layer !== "framework-default" ||
!slot.startsWith("tools/") ||
- REQUIRED_FRAMEWORK_TOOL_SLOTS.has(slot) ||
+ slot === CONNECTION_TOOLS_SLOT ||
overriddenSlots.has(slot)
);
}),
diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.ts
index 523eef1f5..2543f9671 100644
--- a/packages/eve/src/compiler/extension-compatibility.ts
+++ b/packages/eve/src/compiler/extension-compatibility.ts
@@ -22,9 +22,9 @@ interface ExtensionCapabilityContract {
const EXTENSION_CAPABILITY_CONTRACTS = {
extension: { current: 1, supported: [1], dropped: {} },
tool: {
- current: 65,
+ current: 66,
supported: [
- 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 29, 30, 31, 32, 34, 35, 54, 55, 63, 64, 65,
+ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 29, 30, 31, 32, 34, 35, 54, 55, 63, 64, 65, 66,
],
dropped: {
14: "TaskExec.delegated was removed; migrate to workflow-backed background tools",
@@ -71,10 +71,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
dynamicTool: {
- current: 63,
+ current: 64,
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,
+ 60, 61, 62, 63, 64,
],
dropped: {
21: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
@@ -113,8 +113,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
channel: {
- current: 38,
- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 29, 31, 36, 37, 38],
+ current: 39,
+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 29, 31, 36, 37, 38, 39],
dropped: {
12: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
19: "Continuation rekey was removed; channel extensions must use additive continuation.alias instead.",
@@ -135,8 +135,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
schedule: {
- current: 20,
- supported: [1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 18, 19, 20],
+ current: 21,
+ supported: [1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 18, 19, 20, 21],
dropped: {
5: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
16: 'Background task delivery was removed: sends no longer accept taskDeliveryPolicy and message.completed always carries text. input.resolved reports outcome "cancelled" when a workflow tool withdraws a ctx.ask() request, and stream events gained agent.started, published when a workflow run opens a ctx.agent session, and turn.waiting, which parks the open turn instead of emitting turn.completed and session.waiting.',
@@ -144,8 +144,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
subagent: {
- current: 24,
- supported: [3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 19, 23, 24],
+ current: 25,
+ supported: [3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 19, 23, 24, 25],
dropped: {
1: "Persistent subagent sessions are now the default and the experimental opt-in was removed",
2: "Persistent subagent sessions are now the default and the experimental opt-in was removed",
@@ -158,9 +158,9 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
connection: {
- current: 33,
+ current: 34,
supported: [
- 1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 24, 26, 32, 33,
+ 1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 24, 26, 32, 33, 34,
],
dropped: {
9: "Dynamic connection resolvers no longer receive conversation or channel continuation data",
@@ -175,8 +175,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
hook: {
- current: 32,
- supported: [20, 21, 22, 23, 25, 27, 31, 32],
+ current: 33,
+ supported: [20, 21, 22, 23, 25, 27, 31, 32, 33],
dropped: {
1: "Model identity moved from session.started runtime metadata to step.started call attribution.",
2: "Model identity moved from session.started runtime metadata to step.started call attribution.",
@@ -206,8 +206,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
skill: { current: 2, supported: [1, 2], dropped: {} },
dynamicSkill: {
- current: 26,
- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 15, 16, 17, 18, 19, 20, 21, 25, 26],
+ current: 27,
+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 15, 16, 17, 18, 19, 20, 21, 25, 26, 27],
dropped: {
13: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
22: "Run mode was removed; sessions always park and ConversationContext no longer carries mode.",
@@ -217,8 +217,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
instructions: { current: 2, supported: [1, 2], dropped: {} },
dynamicInstructions: {
- current: 27,
- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 21, 22, 26, 27],
+ current: 28,
+ supported: [
+ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 21, 22, 26, 27, 28,
+ ],
dropped: {
14: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
23: "Run mode was removed; sessions always park and ConversationContext no longer carries mode.",
diff --git a/packages/eve/src/compiler/normalize-manifest.test.ts b/packages/eve/src/compiler/normalize-manifest.test.ts
index 6d912e0ce..5c25d5743 100644
--- a/packages/eve/src/compiler/normalize-manifest.test.ts
+++ b/packages/eve/src/compiler/normalize-manifest.test.ts
@@ -214,7 +214,7 @@ describe("compileAgentManifest source graph", () => {
expect(compiled.config.defaultTools).toBe(false);
expect(compiled.tools.map((tool) => tool.name).sort()).toEqual(["bash", "weather"]);
- expect(compiled.dynamicTools.map((tool) => tool.slug)).toEqual(["connection_search"]);
+ expect(compiled.dynamicTools.map((tool) => tool.slug)).toEqual(["connection_tools"]);
expect(compiled.tools.find((tool) => tool.name === "bash")?.description).toBe(
"Application-owned shell replacement.",
);
@@ -229,19 +229,21 @@ describe("compileAgentManifest source graph", () => {
).toEqual(["tools/bash.ts"]);
});
- it("rejects disabling required connection search", async () => {
+ it.each([
+ ["tools/connection_search.ts", disableTool()],
+ [
+ "tools/connection_execute.ts",
+ defineTool({ description: "Replacement.", execute: () => null, inputSchema: {} }),
+ ],
+ ["tools/connection_tools.ts", disableTool()],
+ ])("rejects authored %s because the connection tools are closed", async (logicalPath, entry) => {
const sourceRegistry = registry([
- {
- logicalPath: "tools/connection_search.ts",
- loadNamespace: async () => ({ default: disableTool() }),
- },
+ { logicalPath, loadNamespace: async () => ({ default: entry }) },
]);
await expect(
compileAgentManifest(manifest(), { sourceRegistries: [sourceRegistry] }),
- ).rejects.toThrow(
- 'The required "connection_search" tool cannot be disabled. Remove "agent/tools/connection_search.ts" or export a replacement tool from it.',
- );
+ ).rejects.toThrow(`"agent/${logicalPath}" is reserved.`);
});
it("allows disableTool for the root agent tool", async () => {
diff --git a/packages/eve/src/compiler/normalize-manifest.ts b/packages/eve/src/compiler/normalize-manifest.ts
index 165dc0a4a..35f0e242c 100644
--- a/packages/eve/src/compiler/normalize-manifest.ts
+++ b/packages/eve/src/compiler/normalize-manifest.ts
@@ -582,11 +582,11 @@ class AgentGraphCompiler {
break;
}
case "tool": {
+ assertFrameworkToolPolicy(candidate);
const result = await compileToolEntry(input.manifest.agentRoot, entry.source, {
binding: binding!,
loadNamespace,
});
- assertFrameworkToolPolicy(candidate, result);
if (result.kind === "disabled") {
state.composed = disableComposedCandidate({
allowUnmatched: canDisableToolWithoutSelectedSource(state, result.name),
diff --git a/packages/eve/src/context/keys.ts b/packages/eve/src/context/keys.ts
index d0d090981..a33b9d2a8 100644
--- a/packages/eve/src/context/keys.ts
+++ b/packages/eve/src/context/keys.ts
@@ -105,6 +105,8 @@ export const TurnDeliveryIdsKey = new ContextKey<readonly string[]>("eve.turnDel
/** Last framework announcements recorded in the retained session history. */
export interface HistoryState {
readonly availableSkills?: string;
+ /** Last announced value per keyed announcement (see `#harness/announcements.js`). */
+ readonly announcements?: Readonly<Record<string, string>>;
}
export const HistoryStateKey = new ContextKey<HistoryState>("eve.historyState");
export interface ActiveChannelDelivery {
diff --git a/packages/eve/src/execution/connection-announcement.test.ts b/packages/eve/src/execution/connection-announcement.test.ts
new file mode 100644
index 000000000..5fd1c58a1
--- /dev/null
+++ b/packages/eve/src/execution/connection-announcement.test.ts
@@ -0,0 +1,76 @@
+import { describe, expect, it } from "vitest";
+import { ContextContainer } from "#context/container.js";
+import type { HistoryState } from "#context/keys.js";
+import { ConnectionRegistryKey } from "#context/providers/connection-key.js";
+import { announceConnections } from "#execution/connection-announcement.js";
+import { getPendingAnnouncements } from "#harness/announcements.js";
+import { createCurrentMessages } from "#harness/current-messages.js";
+import type { HarnessModelMessage } from "#harness/messages.js";
+import type { ConnectionRegistry } from "#runtime/connections/registry-types.js";
+import type { ResolvedConnectionDefinition } from "#runtime/types.js";
+
+function registryOf(connections: Record<string, string>): ConnectionRegistry {
+ const resolved = Object.entries(connections).map(
+ ([connectionName, description]) =>
+ ({ connectionName, description }) as ResolvedConnectionDefinition,
+ );
+ return {
+ dispose: async () => {},
+ getClient: () => {
+ throw new Error("unused");
+ },
+ getConnectionApproval: () => undefined,
+ getConnectionNames: () => resolved.map((connection) => connection.connectionName),
+ getConnections: () => resolved,
+ };
+}
+
+/** Runs one step's announcement pass and returns the messages it appended. */
+function step(
+ connections: Record<string, string>,
+ state: { history: HarnessModelMessage[]; historyState?: HistoryState },
+): string[] {
+ const ctx = new ContextContainer();
+ ctx.set(ConnectionRegistryKey, registryOf(connections));
+ announceConnections(ctx);
+ const current = createCurrentMessages(state.history, { historyState: state.historyState });
+ current.addAnnouncements({ keyed: getPendingAnnouncements(ctx) });
+ const appended = current.history.slice(state.history.length);
+ state.history = [...current.history];
+ state.historyState = current.historyState;
+ return appended.map((message) => String(message.content));
+}
+
+describe("connection announcements", () => {
+ it("appends a baseline, then only changes, and rebaselines after compaction", () => {
+ const state: { history: HarnessModelMessage[]; historyState?: HistoryState } = {
+ history: [],
+ };
+
+ expect(step({}, state)).toEqual([]);
+ expect(step({ linear: "Linear issues" }, state)).toEqual([
+ [
+ "Connections. Find their tools with connection_search and call them with connection_execute.",
+ "- linear: Linear issues",
+ ].join("\n"),
+ ]);
+ expect(step({ linear: "Linear issues" }, state)).toEqual([]);
+ expect(step({ github: "GitHub repositories" }, state)).toEqual([
+ [
+ "Connections changed.",
+ "Added or updated:",
+ "- github: GitHub repositories",
+ "No longer available, do not call: linear",
+ ].join("\n"),
+ ]);
+
+ // Compaction replaces history and clears the announcement record.
+ const compacted = { history: [], historyState: undefined };
+ expect(step({ github: "GitHub repositories" }, compacted)).toEqual([
+ [
+ "Connections. Find their tools with connection_search and call them with connection_execute.",
+ "- github: GitHub repositories",
+ ].join("\n"),
+ ]);
+ });
+});
diff --git a/packages/eve/src/execution/connection-announcement.ts b/packages/eve/src/execution/connection-announcement.ts
new file mode 100644
index 000000000..fdf1a6935
--- /dev/null
+++ b/packages/eve/src/execution/connection-announcement.ts
@@ -0,0 +1,88 @@
+import type { ContextContainer } from "#context/container.js";
+import { ConnectionRegistryKey } from "#context/providers/connection-key.js";
+import { setPendingAnnouncement } from "#harness/announcements.js";
+
+const ANNOUNCEMENT_KEY = "connections";
+
+interface ListedConnection {
+ readonly description: string;
+ readonly name: string;
+}
+
+/**
+ * Announces the agent's connections for the current step: a baseline listing
+ * the first time, then only what changed. Tool names and signatures stay out
+ * of the listing; `connection_search` returns them.
+ */
+export function announceConnections(ctx: ContextContainer): void {
+ const registry = ctx.get(ConnectionRegistryKey);
+ if (registry === undefined) {
+ setPendingAnnouncement(ctx, ANNOUNCEMENT_KEY, undefined);
+ return;
+ }
+ const current = registry
+ .getConnections()
+ .map((connection) => ({
+ description: connection.description,
+ name: connection.connectionName,
+ }))
+ .sort((a, b) => a.name.localeCompare(b.name));
+ setPendingAnnouncement(ctx, ANNOUNCEMENT_KEY, {
+ value: JSON.stringify(current),
+ render: (previous) => renderConnectionsAnnouncement(parseListing(previous), current),
+ });
+}
+
+function renderConnectionsAnnouncement(
+ previous: readonly ListedConnection[] | undefined,
+ current: readonly ListedConnection[],
+): string | undefined {
+ // An empty listing was recorded without a message, so the model has not
+ // seen the baseline yet.
+ if (previous === undefined || previous.length === 0) {
+ return current.length === 0 ? undefined : renderListing(current);
+ }
+ if (current.length === 0) {
+ return "Connections changed. No connections are available now; do not call connection_execute.";
+ }
+
+ const previousByName = new Map(previous.map((entry) => [entry.name, entry]));
+ const currentNames = new Set(current.map((entry) => entry.name));
+ const added = current.filter(
+ (entry) => previousByName.get(entry.name)?.description !== entry.description,
+ );
+ const removed = previous.filter((entry) => !currentNames.has(entry.name));
+ const parts = ["Connections changed."];
+ if (added.length > 0) parts.push(["Added or updated:", ...added.map(formatEntry)].join("\n"));
+ if (removed.length > 0) {
+ parts.push(
+ `No longer available, do not call: ${removed.map((entry) => entry.name).join(", ")}`,
+ );
+ }
+ const delta = parts.join("\n");
+ const replacement = `Connections changed. This list replaces the previous one.\n${renderListing(current)}`;
+ return delta.length < replacement.length ? delta : replacement;
+}
+
+function renderListing(connections: readonly ListedConnection[]): string {
+ return [
+ "Connections. Find their tools with connection_search and call them with connection_execute.",
+ ...connections.map(formatEntry),
+ ].join("\n");
+}
+
+function formatEntry(entry: ListedConnection): string {
+ return entry.description.length === 0
+ ? `- ${entry.name}`
+ : `- ${entry.name}: ${entry.description}`;
+}
+
+function parseListing(value: string | undefined): readonly ListedConnection[] | undefined {
+ if (value === undefined) return undefined;
+ try {
+ const parsed = JSON.parse(value) as unknown;
+ return Array.isArray(parsed) ? (parsed as ListedConnection[]) : undefined;
+ } catch {
+ return undefined;
+ }
+}
diff --git a/packages/eve/src/execution/dynamic-connections.ts b/packages/eve/src/execution/dynamic-connections.ts
index 8f6f99657..2a5001c9a 100644
--- a/packages/eve/src/execution/dynamic-connections.ts
+++ b/packages/eve/src/execution/dynamic-connections.ts
@@ -1,5 +1,6 @@
import type { ContextContainer } from "#context/container.js";
import { dispatchDynamicConnectionEvent } from "#context/dynamic-connection-lifecycle.js";
+import { announceConnections } from "#execution/connection-announcement.js";
import type { HarnessEmissionState } from "#harness/emission.js";
import {
createSessionStartedEvent,
@@ -15,8 +16,10 @@ export function bindDynamicConnections(
agent: Pick<ResolvedAgent, "dynamicConnectionResolvers">,
) {
const resolvers = agent.dynamicConnectionResolvers ?? [];
- const dispatch = (event: UnstampedMessageStreamEvent): Promise<void> =>
- dispatchDynamicConnectionEvent({ ctx, event, resolvers });
+ const dispatch = async (event: UnstampedMessageStreamEvent): Promise<void> => {
+ await dispatchDynamicConnectionEvent({ ctx, event, resolvers });
+ if (event.type === "step.started") announceConnections(ctx);
+ };
return {
dispatch,
diff --git a/packages/eve/src/execution/node-step.ts b/packages/eve/src/execution/node-step.ts
index fc29b0b96..666a0fe0a 100644
--- a/packages/eve/src/execution/node-step.ts
+++ b/packages/eve/src/execution/node-step.ts
@@ -24,7 +24,6 @@ import { workflowIdForHandling } from "#runtime/subagents/workflow-reference.js"
import { findRegisteredRuntimeTool } from "#runtime/tools/registry.js";
import type { ResolvedToolDefinition } from "#runtime/types.js";
import { createToolExecuteWithAuth } from "#execution/tool-auth.js";
-import { connectionToolReplayIdentity } from "#execution/tools/connection-search.js";
import {
createPreparedWorkflowToolHarnessDefinition,
createWorkflowToolHarnessDefinition,
@@ -108,7 +107,6 @@ export function createExecutionNodeStep(input: CreateExecutionNodeStepInput): St
historyView: input.historyView,
instrumentation: sessionInstrumentation,
prepareApprovalTurn: input.prepareApprovalTurn,
- toolReplayIdentity: connectionToolReplayIdentity,
resolveStepDynamicTools: (resolveInput) =>
preparePersistedStepDynamicToolMetadata({
...resolveInput,
diff --git a/packages/eve/src/execution/session/turn-connection-approval.integration.test.ts b/packages/eve/src/execution/session/turn-connection-approval.integration.test.ts
index 60a5e4e33..e6aeef389 100644
--- a/packages/eve/src/execution/session/turn-connection-approval.integration.test.ts
+++ b/packages/eve/src/execution/session/turn-connection-approval.integration.test.ts
@@ -30,7 +30,7 @@ import type {
ResolvedDynamicConnectionResolver,
ResolvedDynamicToolResolver,
} from "#runtime/types.js";
-import connectionSearch from "#tools/framework/connection-search.js";
+import connectionTools from "#tools/framework/connection-tools.js";
import { clearDurableDynamicCallbacks } from "#tools/durable-callbacks.js";
import type { ApprovalResponseContext } from "#approval/definition.js";
@@ -59,24 +59,24 @@ const usage = {
};
const sessionId = "turn-connection-approval";
-function modelResponse(toolName?: string, callId?: string, connection = "notes") {
+/** A model step that saves notes through `connection_execute`, or replies when `callId` is omitted. */
+function modelResponse(callId?: string | readonly string[], connection = "notes") {
+ const callIds = callId === undefined ? [] : typeof callId === "string" ? [callId] : callId;
return {
stream: simulateReadableStream({
chunks: [
{ type: "stream-start" as const, warnings: [] },
- ...(toolName
- ? [
- {
- type: "tool-call" as const,
- toolCallId: callId ?? (toolName === "connection_search" ? "search" : "save"),
- toolName,
- input: JSON.stringify(
- toolName === "connection_search"
- ? { connection, keywords: "save" }
- : { body: { note: "hello" } },
- ),
- },
- ]
+ ...(callIds.length > 0
+ ? callIds.map((toolCallId) => ({
+ type: "tool-call" as const,
+ toolCallId,
+ toolName: "connection_execute",
+ input: JSON.stringify({
+ connection,
+ tool: "saveNote",
+ input: { body: { note: "hello" } },
+ }),
+ }))
: [
{ type: "text-start" as const, id: "reply" },
{ type: "text-delta" as const, id: "reply", delta: "Saved." },
@@ -86,7 +86,7 @@ function modelResponse(toolName?: string, callId?: string, connection = "notes")
type: "finish" as const,
finishReason: {
raw: undefined,
- unified: toolName ? ("tool-calls" as const) : ("stop" as const),
+ unified: callIds.length > 0 ? ("tool-calls" as const) : ("stop" as const),
},
usage,
},
@@ -98,7 +98,7 @@ function modelResponse(toolName?: string, callId?: string, connection = "notes")
function setup(
scope: "turn.started" | "session.started" = "turn.started",
reject = false,
- variation?: "destination" | "name" | "request-only",
+ variation?: "destination" | "name" | "request-only" | "unapproved-name",
) {
const response = vi.fn((context: ApprovalResponseContext) => {
expect(context.response.principal.principalId).toBe("bob");
@@ -113,7 +113,9 @@ function setup(
if (removed) return {};
const sequence = (event as { data: { sequence?: number } }).data.sequence ?? 0;
return {
- [variation === "name" && sequence > 0 ? "second-notes" : "notes"]: defineOpenAPIConnection({
+ [(variation === "name" || variation === "unapproved-name") && sequence > 0
+ ? "second-notes"
+ : "notes"]: defineOpenAPIConnection({
baseUrl:
variation === "destination"
? `https://notes-${sequence}.example.com`
@@ -145,18 +147,21 @@ function setup(
},
},
},
- approval: {
- request: () => "user-approval",
- response:
- variation === "request-only"
- ? undefined
- : (context) => {
- policyTurns.push(
- (event as { data: { turnId?: string } }).data.turnId ?? "session",
- );
- return response(context);
- },
- },
+ approval:
+ variation === "unapproved-name"
+ ? undefined
+ : {
+ request: () => "user-approval",
+ response:
+ variation === "request-only"
+ ? undefined
+ : (context) => {
+ policyTurns.push(
+ (event as { data: { turnId?: string } }).data.turnId ?? "session",
+ );
+ return response(context);
+ },
+ },
}),
};
});
@@ -173,10 +178,10 @@ function setup(
const dynamicToolResolvers: ResolvedDynamicToolResolver[] = [
{
eventNames: ["step.started"],
- events: connectionSearch.events as ResolvedDynamicToolResolver["events"],
- logicalPath: "tools/connection-search.ts",
- slug: "connection-search",
- sourceId: "eve:connection-search",
+ events: connectionTools.events as ResolvedDynamicToolResolver["events"],
+ logicalPath: "tools/connection_tools.ts",
+ slug: "connection_tools",
+ sourceId: "eve:connection-tools",
sourceKind: "module",
},
];
@@ -235,8 +240,7 @@ function setup(
vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue(bundle);
const doStream = vi
.fn()
- .mockImplementationOnce(() => modelResponse("connection_search"))
- .mockImplementationOnce(() => modelResponse("notes__saveNote"))
+ .mockImplementationOnce(() => modelResponse("save"))
.mockImplementation(() => modelResponse());
vi.mocked(resolveRuntimeModelReference).mockResolvedValue(new MockLanguageModelV4({ doStream }));
const fetch = vi.fn(
@@ -316,6 +320,45 @@ afterEach(() => {
});
describe("turn connection approval restoration", () => {
+ it("keeps the provider tools and system prompt identical while connections change", async () => {
+ const fixture = setup("turn.started", false, "unapproved-name");
+ await fixture.step({
+ delivery: { kind: "deliver", payloads: [{ message: "Prepare Alice's first note." }] },
+ });
+ await fixture.step();
+ fixture.doStream.mockImplementationOnce(() => modelResponse("save-2", "second-notes"));
+ await fixture.step({
+ delivery: { kind: "deliver", payloads: [{ message: "Prepare Alice's second note." }] },
+ });
+ await fixture.step();
+ expect(fixture.fetch).toHaveBeenCalledTimes(2);
+
+ const requests = fixture.doStream.mock.calls.map(
+ ([options]) =>
+ options as {
+ prompt: { role: string; content: unknown }[];
+ tools: { name: string }[];
+ },
+ );
+ expect(requests.length).toBeGreaterThanOrEqual(2);
+ const [first, ...later] = requests;
+ expect(first!.tools.map((tool) => tool.name).sort()).toEqual([
+ "connection_execute",
+ "connection_search",
+ ]);
+ const system = (request: (typeof requests)[number]) =>
+ request.prompt.filter((message) => message.role === "system");
+ for (const request of later) {
+ expect(request.tools).toEqual(first!.tools);
+ expect(system(request)).toEqual(system(first!));
+ }
+ // Connection names reach the model only through appended context messages.
+ const last = JSON.stringify(requests.at(-1)!.prompt);
+ expect(JSON.stringify(system(first!))).not.toContain("- notes:");
+ expect(last).toContain("- notes: Save notes");
+ expect(last).toContain("- second-notes: Save notes");
+ });
+
it("authorizes requests from two originating turns independently in one cold delivery", async () => {
const fixture = setup();
await fixture.step({
@@ -323,9 +366,7 @@ describe("turn connection approval restoration", () => {
});
const first = await fixture.step();
const firstBatch = getPendingInputBatches(readDurableSession(first.sessionState).state)[0]!;
- fixture.doStream
- .mockImplementationOnce(() => modelResponse("connection_search", "search-2"))
- .mockImplementationOnce(() => modelResponse("notes__saveNote", "save-2"));
+ fixture.doStream.mockImplementationOnce(() => modelResponse("save-2"));
await fixture.step({
delivery: {
kind: "deliver",
@@ -364,7 +405,7 @@ describe("turn connection approval restoration", () => {
expect(fixture.events.filter((event) => event.type === "session.failed")).toEqual([]);
});
it.each([false, true])(
- "fails before execution when the resumed connection changes (cold: %s)",
+ "fails an approved call whose connection changed before it ran (cold: %s)",
async (cold) => {
const fixture = setup("turn.started", false, "destination");
await fixture.step({
@@ -382,37 +423,85 @@ describe("turn connection approval restoration", () => {
},
});
if (cold) clearDurableDynamicCallbacks(sessionId);
- await expect(fixture.step()).rejects.toThrow(
- "connection for this tool call changed or is unavailable",
- );
+ await fixture.step();
expect(fixture.response).toHaveBeenCalledOnce();
expect(fixture.fetch).not.toHaveBeenCalled();
+ expect(
+ JSON.stringify(
+ fixture.events.filter(
+ (event) =>
+ event.type === "action.result" &&
+ JSON.stringify(event.data).includes(request.action.callId),
+ ),
+ ),
+ ).toContain("connection for this tool call changed or is unavailable");
},
);
+ it("rejects only the approved call whose instance pin was evicted", async () => {
+ const fixture = setup("turn.started", false, "request-only");
+ // One more parked call than the pin map holds evicts the first call's pin.
+ const callIds = Array.from({ length: 51 }, (_, index) => `save-${index}`);
+ fixture.doStream.mockReset();
+ fixture.doStream
+ .mockImplementationOnce(() => modelResponse(callIds))
+ .mockImplementation(() => modelResponse());
+ await fixture.step({
+ delivery: { kind: "deliver", payloads: [{ message: "Prepare Alice's notes." }] },
+ });
+ const parked = await fixture.step();
+ const requests = getPendingInputBatches(readDurableSession(parked.sessionState).state).flatMap(
+ (batch) => batch.requests,
+ );
+ await fixture.step({
+ delivery: {
+ kind: "deliver",
+ auth: bob,
+ payloads: [
+ {
+ inputResponses: requests.map((request) => ({
+ requestId: request.requestId,
+ optionId: "approve",
+ })),
+ },
+ ],
+ },
+ });
+ await fixture.step();
+ // A missing pin can't prove the connection is unchanged, so that call fails
+ // rather than re-pinning to whatever the connection resolves to now.
+ const failed = fixture.events.flatMap((event) =>
+ event.type === "action.result" && event.data.status === "failed"
+ ? [event.data.result as { callId: string; output: unknown }]
+ : [],
+ );
+ expect(failed.map((result) => result.callId)).toEqual(["save-0"]);
+ expect(JSON.stringify(failed[0]!.output)).toContain(
+ "connection for this tool call changed or is unavailable",
+ );
+ expect(fixture.fetch).toHaveBeenCalledTimes(50);
+ });
+
it.each([false, true])(
- "refuses an older tool missing from persisted metadata while approving an available tool (cold: %s)",
+ "fails an approved call whose connection is gone while running an available one (cold: %s)",
async (cold) => {
const fixture = setup("turn.started", false, "name");
await fixture.step({
delivery: { kind: "deliver", payloads: [{ message: "Prepare Alice's first note." }] },
});
await fixture.step();
- fixture.doStream
- .mockImplementationOnce(() =>
- modelResponse("connection_search", "search-2", "second-notes"),
- )
- .mockImplementationOnce(() => modelResponse("second-notes__saveNote", "save-2"));
+ fixture.doStream.mockImplementationOnce(() => modelResponse("save-2", "second-notes"));
await fixture.step({
delivery: { kind: "deliver", payloads: [{ message: "Prepare Alice's second note." }] },
});
const second = await fixture.step();
const batches = getPendingInputBatches(readDurableSession(second.sessionState).state);
expect(batches).toHaveLength(2);
- expect(batches.map((batch) => batch.requests[0]!.action.toolName)).toEqual([
- "notes__saveNote",
- "second-notes__saveNote",
- ]);
+ expect(
+ batches.map(
+ (batch) => (batch.requests[0]!.action.input as { connection: string }).connection,
+ ),
+ ).toEqual(["notes", "second-notes"]);
if (cold) clearDurableDynamicCallbacks(sessionId);
await fixture.step({
delivery: {
@@ -431,32 +520,27 @@ describe("turn connection approval restoration", () => {
},
});
if (cold) clearDurableDynamicCallbacks(sessionId);
- const resumed = await fixture.step();
- const state = readDurableSession(resumed.sessionState).state;
+ await fixture.step();
const older = batches[0]!.requests[0]!;
- const newer = batches[1]!.requests[0]!;
- expect(fixture.policyTurns).toEqual([batches[1]!.event!.turnId]);
- expect(getApprovalAuditState(state).candidateHistory).toEqual(
- expect.arrayContaining([
- expect.objectContaining({
- requestId: older.requestId,
+ // Each approval is authorized against its originating turn's connections;
+ // the older call then fails because "notes" is gone when it runs.
+ expect(fixture.policyTurns).toEqual(batches.map((batch) => batch.event!.turnId));
+ expect(fixture.events).toContainEqual(
+ expect.objectContaining({
+ type: "action.result",
+ data: expect.objectContaining({
status: "failed",
- reason: "Approval authorization is temporarily unavailable. Please try again.",
+ result: expect.objectContaining({
+ callId: older.action.callId,
+ output: expect.stringContaining('Connection "notes" is not available'),
+ }),
}),
- ]),
- );
- expect(getApprovalAuditState(state).settlements).toEqual([
- expect.objectContaining({ requestId: newer.requestId, outcome: "allowed" }),
- ]);
- expect(getPendingInputBatches(state).flatMap((batch) => batch.requests)).toEqual([older]);
- expect(getPendingInputBatches(state)[0]!.toolReplayIdentities).toEqual(
- batches[0]!.toolReplayIdentities,
+ }),
);
- expect(fixture.fetch).toHaveBeenCalledOnce();
},
);
- it("rejects a missing connection before replay even without a response policy", async () => {
+ it("fails an approved call whose connection is gone without a response policy", async () => {
const fixture = setup("turn.started", false, "request-only");
await fixture.step({
delivery: { kind: "deliver", payloads: [{ message: "Prepare Alice's note." }] },
@@ -465,16 +549,27 @@ describe("turn connection approval restoration", () => {
const request = getPendingInputBatches(readDurableSession(parked.sessionState).state)[0]!
.requests[0]!;
fixture.removeConnection();
- await expect(
- fixture.step({
- delivery: {
- kind: "deliver",
- auth: bob,
- payloads: [{ inputResponses: [{ requestId: request.requestId, optionId: "approve" }] }],
- },
- }),
- ).rejects.toThrow("connection for this tool call changed or is unavailable");
+ await fixture.step({
+ delivery: {
+ kind: "deliver",
+ auth: bob,
+ payloads: [{ inputResponses: [{ requestId: request.requestId, optionId: "approve" }] }],
+ },
+ });
+ await fixture.step();
expect(fixture.fetch).not.toHaveBeenCalled();
+ expect(fixture.events).toContainEqual(
+ expect.objectContaining({
+ type: "action.result",
+ data: expect.objectContaining({
+ status: "failed",
+ result: expect.objectContaining({
+ callId: request.action.callId,
+ output: expect.stringContaining('Connection "notes" is not available'),
+ }),
+ }),
+ }),
+ );
});
it("leaves the request pending when its connection can no longer be reconstructed", async () => {
@@ -501,8 +596,8 @@ describe("turn connection approval restoration", () => {
expect(getPendingInputBatches(state)[0]!.requests[0]!.requestId).toBe(request.requestId);
expect(getApprovalAuditState(state).candidateHistory).toEqual([
expect.objectContaining({
- status: "failed",
- reason: "Approval authorization is temporarily unavailable. Please try again.",
+ status: "rejected",
+ reason: expect.stringContaining("cannot replay its approvalResponse callback"),
}),
]);
});
@@ -646,7 +741,7 @@ describe("turn connection approval restoration", () => {
});
it.each([false, true])(
- "approves and executes a discovered tool with a cold callback cache: %s",
+ "approves and executes a connection tool with a cold callback cache: %s",
async (cold) => {
const fixture = setup();
await fixture.step({
@@ -655,13 +750,7 @@ describe("turn connection approval restoration", () => {
const parked = await fixture.step();
const request = getPendingInputBatches(readDurableSession(parked.sessionState).state)[0]!
.requests[0]!;
- expect(request.action.toolName).toBe("notes__saveNote");
- expect(
- getPendingInputBatches(readDurableSession(parked.sessionState).state)[0]!
- .toolReplayIdentities,
- ).toEqual({
- [request.requestId]: expect.stringMatching(/^connection:/),
- });
+ expect(request.action.toolName).toBe("connection_execute");
expect(fixture.fetch).not.toHaveBeenCalled();
if (cold) clearDurableDynamicCallbacks(sessionId);
const candidate = await fixture.step({
@@ -684,12 +773,37 @@ describe("turn connection approval restoration", () => {
expect(getPendingInputBatches(readDurableSession(resumed.sessionState).state)).toEqual([]);
expect(resumed.serializedContext).not.toHaveProperty("eve.pendingConnectionCalls");
expect(fixture.events.filter((event) => event.type === "turn.started")).toHaveLength(2);
+ // The connection call is reported as a nested action of the approved call.
+ const nestedCallId = `${request.action.callId}:1`;
expect(fixture.events).toContainEqual(
expect.objectContaining({
- type: "action.result",
+ type: "actions.requested",
+ data: expect.objectContaining({
+ actions: [
+ expect.objectContaining({
+ callId: nestedCallId,
+ parentCallId: request.action.callId,
+ toolName: "notes__saveNote",
+ }),
+ ],
+ }),
+ }),
+ );
+ const results = fixture.events.filter((event) => event.type === "action.result");
+ const resultCallIds = results.map(
+ (event) => (event.data.result as { callId: string }).callId,
+ );
+ expect(resultCallIds.indexOf(nestedCallId)).toBeLessThan(
+ resultCallIds.indexOf(request.action.callId),
+ );
+ expect(results[resultCallIds.indexOf(nestedCallId)]).toEqual(
+ expect.objectContaining({
data: expect.objectContaining({
status: "completed",
- result: expect.objectContaining({ toolName: "notes__saveNote" }),
+ result: expect.objectContaining({
+ output: { body: { saved: true }, status: 200, statusText: "" },
+ toolName: "notes__saveNote",
+ }),
}),
}),
);
diff --git a/packages/eve/src/execution/tools/connection-approval.ts b/packages/eve/src/execution/tools/connection-approval.ts
new file mode 100644
index 000000000..ef649f1ce
--- /dev/null
+++ b/packages/eve/src/execution/tools/connection-approval.ts
@@ -0,0 +1,211 @@
+/**
+ * Approval for `connection_execute`: each call is approved under the called
+ * connection's own policy, keyed by connection and tool, and an approved call
+ * runs only against the connection instance it was approved for.
+ */
+
+import {
+ resolveApprovalPolicy,
+ type Approval,
+ type ApprovalContext,
+ type ApprovalResponseContext,
+ type ApprovalResponseDecision,
+ type ApprovalStatus,
+} from "#approval/definition.js";
+import { loadContext } from "#context/container.js";
+import { ContextKey } from "#context/key.js";
+import { ConnectionRegistryKey } from "#context/providers/connection-key.js";
+import { isApprovalRecheck } from "#harness/approval-recheck.js";
+import type { ResolvedConnectionDefinition } from "#runtime/types.js";
+import { defineDurableCallback } from "#tools/durable-callbacks.js";
+
+import {
+ CONNECTION_EXECUTE_TOOL_NAME,
+ findConnection,
+ qualifiedToolName,
+ readExecuteTarget,
+ type ExecuteTarget,
+} from "./connection-target.js";
+
+/** Bounds approval pins; an evicted pin rejects its call rather than letting it run. */
+const MAX_APPROVAL_PINS = 50;
+
+/**
+ * Connection instance each parked `connection_execute` call was sent for
+ * approval against, keyed by call id. When a person approves the call, it runs
+ * only if its connection still resolves to that instance; a changed instance or
+ * a missing pin (the map is bounded) rejects it.
+ */
+const ConnectionApprovalPinsKey = new ContextKey<Readonly<Record<string, string>>>(
+ "eve.connectionApprovalPins",
+);
+
+/**
+ * Delegates approval to the called connection's policy. The request and
+ * response phases exist only when some registered connection defines them,
+ * so connections without a response policy keep the default response flow
+ * unless another connection in the same agent defines one.
+ */
+export function connectionExecuteApproval(approvals: readonly Approval[]) {
+ if (approvals.length === 0) return {};
+ const request = defineDurableCallback({ callback: requestConnectionApproval, closure: {} });
+ const hasResponsePolicy = approvals.some(
+ (approval) => typeof approval !== "function" && approval.response !== undefined,
+ );
+ return {
+ approvalKey: defineDurableCallback({ callback: connectionApprovalKey, closure: {} }),
+ approval: hasResponsePolicy
+ ? {
+ request,
+ response: defineDurableCallback({
+ callback: authorizeConnectionApprovalResponse,
+ closure: {},
+ }),
+ }
+ : request,
+ };
+}
+
+/**
+ * The recorded approval identity. `<connection>__<tool>` is not unique (a
+ * connection `a` with tool `b__c` and a connection `a__b` with tool `c` share
+ * it), so approvals are keyed on the pair.
+ */
+function connectionApprovalKey(_closure: object, input: unknown): string {
+ const target = readExecuteTarget(input);
+ return target === undefined ? CONNECTION_EXECUTE_TOOL_NAME : approvalKeyFor(target);
+}
+
+function approvalKeyFor(target: Pick<ExecuteTarget, "connection" | "tool">): string {
+ return JSON.stringify([target.connection, target.tool]);
+}
+
+/**
+ * Policies see the qualified tool name, so `approvedTools` lists it only when
+ * this exact connection and tool were approved, never a same-named pair.
+ */
+function policyApprovedTools(
+ approvedTools: ReadonlySet<string>,
+ target: Pick<ExecuteTarget, "connection" | "tool">,
+): ReadonlySet<string> {
+ const qualified = qualifiedToolName(target);
+ const view = new Set([...approvedTools].filter((key) => key !== qualified));
+ if (approvedTools.has(approvalKeyFor(target))) view.add(qualified);
+ return view;
+}
+
+async function requestConnectionApproval(
+ _closure: object,
+ context: ApprovalContext,
+): Promise<ApprovalStatus> {
+ const target = readExecuteTarget(context.toolInput);
+ const registry = loadContext().get(ConnectionRegistryKey);
+ if (target === undefined || registry === undefined) return "not-applicable";
+ const connection = findConnection(registry, target.connection);
+ const approval =
+ connection === undefined
+ ? undefined
+ : registry.getConnectionApproval(connection.connectionName);
+ if (connection === undefined || approval === undefined) return "not-applicable";
+
+ // Denying here would drop the call without a result, so the approved call
+ // runs and fails in execution instead, where the failure is reported.
+ if (isApprovalRecheck(context) && !matchesApprovalPin(context.callId, connection)) {
+ markApprovalPinChanged(context.callId);
+ }
+ const status = await resolveApprovalPolicy(approval)({
+ ...context,
+ approvedTools: policyApprovedTools(context.approvedTools, target),
+ toolInput: target.input,
+ toolName: qualifiedToolName(target),
+ });
+ if (!isApprovalRecheck(context) && parksForApproval(status)) {
+ pinApprovedInstance(context.callId, connection);
+ }
+ return status;
+}
+
+function parksForApproval(status: ApprovalStatus): boolean {
+ return (
+ status === true ||
+ status === "user-approval" ||
+ (typeof status === "object" && status.type === "user-approval")
+ );
+}
+
+async function authorizeConnectionApprovalResponse(
+ _closure: object,
+ context: ApprovalResponseContext,
+): Promise<ApprovalResponseDecision> {
+ const target = readExecuteTarget(context.request.toolInput);
+ const registry = loadContext().get(ConnectionRegistryKey);
+ const connection =
+ target === undefined || registry === undefined
+ ? undefined
+ : findConnection(registry, target.connection);
+ if (target === undefined || registry === undefined || connection === undefined) {
+ return { reason: "The connection for this tool call is unavailable.", status: "rejected" };
+ }
+ if (!matchesApprovalPin(context.request.callId, connection)) {
+ return { reason: CONNECTION_CHANGED_MESSAGE, status: "rejected" };
+ }
+ const approval = registry.getConnectionApproval(connection.connectionName);
+ const response =
+ approval === undefined || typeof approval === "function" ? undefined : approval.response;
+ if (response === undefined) return { status: "allowed" };
+ return await response({
+ ...context,
+ request: {
+ ...context.request,
+ toolInput: target.input,
+ toolName: qualifiedToolName(target),
+ },
+ });
+}
+
+const CONNECTION_CHANGED_MESSAGE =
+ "The connection for this tool call changed or is unavailable. Request a new tool call and approval.";
+
+/** Stands in for connections without an instance id, so every parked call has a pin. */
+const UNKEYED_INSTANCE = "";
+
+/** Records the instance a parked call was first sent for approval against. */
+function pinApprovedInstance(callId: string, connection: ResolvedConnectionDefinition): void {
+ const instanceId = connection.instanceId ?? UNKEYED_INSTANCE;
+ const ctx = loadContext();
+ if (ctx.get(ConnectionApprovalPinsKey)?.[callId] !== undefined) return;
+ ctx.set(ConnectionApprovalPinsKey, (pins = {}) =>
+ Object.fromEntries([
+ ...Object.entries(pins).slice(-(MAX_APPROVAL_PINS - 1)),
+ [callId, instanceId],
+ ]),
+ );
+}
+
+/** Fails closed: a parked call whose pin is missing counts as changed. */
+function matchesApprovalPin(callId: string, connection: ResolvedConnectionDefinition): boolean {
+ const pinned = loadContext().get(ConnectionApprovalPinsKey)?.[callId];
+ return pinned !== undefined && pinned === (connection.instanceId ?? UNKEYED_INSTANCE);
+}
+
+/** No instance id matches this, so the call fails when it runs. */
+const CHANGED_INSTANCE = "\u0000changed";
+
+function markApprovalPinChanged(callId: string): void {
+ loadContext().set(ConnectionApprovalPinsKey, (pins = {}) => ({
+ ...pins,
+ [callId]: CHANGED_INSTANCE,
+ }));
+}
+
+/** Consumes the call's approval pin, rejecting the call if its connection changed. */
+export function releaseApprovalPin(callId: string, connection: ResolvedConnectionDefinition): void {
+ const ctx = loadContext();
+ const pins = ctx.get(ConnectionApprovalPinsKey);
+ if (pins?.[callId] === undefined) return;
+ const { [callId]: pinned, ...rest } = pins;
+ ctx.set(ConnectionApprovalPinsKey, rest);
+ if (pinned !== (connection.instanceId ?? UNKEYED_INSTANCE)) {
+ throw new Error(CONNECTION_CHANGED_MESSAGE);
+ }
+}
diff --git a/packages/eve/src/execution/tools/connection-search-authorization.integration.test.ts b/packages/eve/src/execution/tools/connection-search-authorization.integration.test.ts
deleted file mode 100644
index c56a9f849..000000000
--- a/packages/eve/src/execution/tools/connection-search-authorization.integration.test.ts
+++ /dev/null
@@ -1,140 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-import { ConnectionAuthorizationRequiredError } from "#connections/errors.js";
-import { ContextContainer, contextStorage } from "#context/container.js";
-import { AuthKey, SessionIdKey } from "#context/keys.js";
-import { ConnectionRegistryKey } from "#context/providers/connection-key.js";
-import { resolveConnectionSearchDynamicTools } from "#execution/tools/connection-search.js";
-import { CallbackBaseUrlKey, isAuthorizationSignal } from "#harness/authorization.js";
-import { ConnectionRegistryImpl } from "#runtime/connections/registry.js";
-import type { ResolvedConnectionDefinition } from "#runtime/types.js";
-import type { ToolContext } from "#tools/definition.js";
-import type { DynamicToolSet } from "#tools/dynamic.js";
-import { captureLogRecords } from "#internal/testing/log-records.js";
-
-function setup() {
- const getToken = vi.fn(async () => {
- throw new ConnectionAuthorizationRequiredError("private-catalog");
- });
- const startAuthorization = vi.fn(async () => ({
- challenge: { url: "https://identity.example/authorize" },
- }));
- const privateCatalog: ResolvedConnectionDefinition = {
- connectionName: "private-catalog",
- description: "Private catalog",
- logicalPath: "agent/connections/private-catalog.ts",
- sourceId: "connections/private-catalog",
- sourceKind: "module",
- protocol: "mcp",
- url: "https://private.example/mcp",
- authorization: {
- principalType: "user",
- getToken,
- startAuthorization,
- completeAuthorization: async () => ({ token: "fixture-token" }),
- },
- };
- const publicCatalog: ResolvedConnectionDefinition = {
- ...privateCatalog,
- connectionName: "public-catalog",
- description: "Public catalog",
- authorization: undefined,
- protocol: "openapi",
- spec: {
- openapi: "3.0.0",
- info: { title: "Public catalog", version: "1.0.0" },
- paths: {
- "/items": {
- get: {
- operationId: "list_items",
- summary: "List catalog items",
- responses: { "200": { description: "Catalog items" } },
- },
- },
- },
- },
- };
- const registry = new ConnectionRegistryImpl([privateCatalog, publicCatalog]);
- const context = new ContextContainer();
- context.set(ConnectionRegistryKey, registry);
- context.set(SessionIdKey, "catalog-session");
- context.set(CallbackBaseUrlKey, "https://agent.example");
- context.set(AuthKey, {
- attributes: {},
- authenticator: "fixture",
- issuer: "fixture",
- principalId: "alice",
- principalType: "user",
- });
-
- async function search(connection?: string) {
- return contextStorage.run(context, async () => {
- const tools = (await resolveConnectionSearchDynamicTools()) as DynamicToolSet;
- return tools.connection_search!.execute({ connection, keywords: "items" }, {} as ToolContext);
- });
- }
-
- return { context, getToken, registry, search, startAuthorization };
-}
-
-describe("connection search callback availability", () => {
- it("starts authorization when session identity and callback origin are present", async () => {
- const state = setup();
- try {
- expect(isAuthorizationSignal(await state.search("private-catalog"))).toBe(true);
- expect(state.getToken).toHaveBeenCalledOnce();
- expect(state.startAuthorization).toHaveBeenCalledOnce();
- } finally {
- await state.registry.dispose();
- }
- });
-
- // Characterize the PR's stricter policy. Main returned needsAuthorization instead.
- // The real MCP client asks the provider for a token before making any HTTP request.
- for (const missing of ["session", "origin", "both"] as const) {
- it(`fails a private-only search when ${missing} is missing`, async () => {
- const logs = captureLogRecords();
- const state = setup();
- if (missing !== "origin") state.context.delete(SessionIdKey);
- if (missing !== "session") state.context.delete(CallbackBaseUrlKey);
-
- try {
- await expect(state.search("private-catalog")).rejects.toThrow(
- "no authorization callback URL could be minted",
- );
- expect(state.getToken).toHaveBeenCalledOnce();
- expect(state.startAuthorization).not.toHaveBeenCalled();
- expect(logs.records).toContainEqual(
- expect.objectContaining({ level: "warn", message: "connection authorization failed" }),
- );
- } finally {
- await state.registry.dispose();
- }
- });
- }
-
- it("keeps public tools discoverable alongside the private connection's callback error", async () => {
- const logs = captureLogRecords();
- const state = setup();
- state.context.delete(CallbackBaseUrlKey);
-
- try {
- const result = await state.search();
- expect(result).toEqual([
- expect.objectContaining({ qualifiedName: "public-catalog__list_items" }),
- {
- connection: "private-catalog",
- description: "Private catalog",
- error: expect.stringContaining("no authorization callback URL could be minted"),
- },
- ]);
- expect(state.getToken).toHaveBeenCalledOnce();
- expect(state.startAuthorization).not.toHaveBeenCalled();
- } finally {
- await state.registry.dispose();
- }
- expect(logs.records).toContainEqual(
- expect.objectContaining({ level: "warn", message: "connection authorization failed" }),
- );
- });
-});
diff --git a/packages/eve/src/execution/tools/connection-search-rank.test.ts b/packages/eve/src/execution/tools/connection-search-rank.test.ts
new file mode 100644
index 000000000..892dd8086
--- /dev/null
+++ b/packages/eve/src/execution/tools/connection-search-rank.test.ts
@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+
+import type { ConnectionToolMetadata } from "#shared/connection-types.js";
+
+import { closestToolNames, rankConnectionTools } from "./connection-search-rank.js";
+
+function tool(
+ name: string,
+ description: string,
+ properties: Record<string, { readonly description?: string }> = {},
+): ConnectionToolMetadata {
+ return { name, description, inputSchema: { type: "object", properties } };
+}
+
+const linear = { connectionName: "linear", description: "Issues, projects, and teams." };
+const github = { connectionName: "github", description: "Repositories and pull requests." };
+const kennel = { connectionName: "kennel", description: "Boarding pets and visits." };
+
+const candidates = [
+ { connection: linear, tool: tool("list_issues", "List open issues.", { teamId: {} }) },
+ { connection: linear, tool: tool("get_team", "Get a team by id.") },
+ { connection: github, tool: tool("search_repositories", "Find repos by keyword.") },
+ {
+ connection: kennel,
+ tool: tool("book_visit", "Book a care visit.", {
+ contacts: { description: "People to notify about the visit." },
+ }),
+ },
+];
+
+const rank = (query: string) =>
+ rankConnectionTools(query, candidates).map(
+ ({ connection, tool }) => `${connection.connectionName}/${tool.name}`,
+ );
+
+describe("rankConnectionTools", () => {
+ it.each([
+ { query: "linear", expected: ["linear/get_team", "linear/list_issues"] },
+ { query: "people", expected: ["kennel/book_visit"] },
+ // The tool named for issues outranks one matched only by its connection's description.
+ { query: "issues", expected: ["linear/list_issues", "linear/get_team"] },
+ { query: "repo", expected: ["github/search_repositories"] },
+ { query: "isue", expected: [] },
+ {
+ query: "",
+ expected: [
+ "github/search_repositories",
+ "kennel/book_visit",
+ "linear/get_team",
+ "linear/list_issues",
+ ],
+ },
+ ])("ranks $query", ({ query, expected }) => {
+ expect(rank(query)).toEqual(expected);
+ });
+});
+
+describe("closestToolNames", () => {
+ it("suggests from the tools' own fields, not the shared connection", () => {
+ const tools = [tool("find_pet", "Look up a pet."), tool("list_feedings", "Feeding schedule.")];
+ expect(closestToolNames("kennel_find_pets", tools, 5)).toEqual(["find_pet"]);
+ });
+});
diff --git a/packages/eve/src/execution/tools/connection-search-rank.ts b/packages/eve/src/execution/tools/connection-search-rank.ts
new file mode 100644
index 000000000..f8a3410b0
--- /dev/null
+++ b/packages/eve/src/execution/tools/connection-search-rank.ts
@@ -0,0 +1,105 @@
+/**
+ * Keyword ranking for `connection_search` and for `connection_execute`'s
+ * suggestions when a tool name is unknown. Query and field text split into
+ * lowercase words (camelCase and punctuation are boundaries); a query word
+ * matches a field word when either is a prefix of the other, so `repo` finds
+ * `repositories` and `issues` finds `issue`. Each query word adds the weight of
+ * every field it matches, so broad fields rank below a tool's own name.
+ */
+
+import type { ResolvedConnectionDefinition } from "#runtime/types.js";
+import type { ConnectionToolMetadata } from "#shared/connection-types.js";
+import { isObject } from "#shared/guards.js";
+
+export interface RankCandidate {
+ readonly connection: Pick<ResolvedConnectionDefinition, "connectionName" | "description">;
+ readonly tool: ConnectionToolMetadata;
+}
+
+/** Candidates matching `query`, best first. An empty query matches every candidate. */
+export function rankConnectionTools<T extends RankCandidate>(
+ query: string,
+ candidates: readonly T[],
+): T[] {
+ const terms = tokenize(query);
+ return candidates
+ .map((candidate) => ({
+ candidate,
+ score:
+ terms.length === 0
+ ? 1
+ : scoreFields(terms, [
+ ...toolFields(candidate.tool),
+ [tokenize(candidate.connection.connectionName), 4],
+ [tokenize(candidate.connection.description), 1],
+ ]),
+ }))
+ .filter((entry) => entry.score > 0)
+ .sort(
+ (a, b) =>
+ b.score - a.score ||
+ a.candidate.connection.connectionName.localeCompare(
+ b.candidate.connection.connectionName,
+ ) ||
+ a.candidate.tool.name.localeCompare(b.candidate.tool.name),
+ )
+ .map((entry) => entry.candidate);
+}
+
+/**
+ * Names of one connection's tools closest to an unknown `name`. Only the tools'
+ * own fields count, since every candidate shares the connection.
+ */
+export function closestToolNames(
+ name: string,
+ tools: readonly ConnectionToolMetadata[],
+ limit: number,
+): string[] {
+ const terms = tokenize(name);
+ if (terms.length === 0) return [];
+ return tools
+ .map((tool) => ({ name: tool.name, score: scoreFields(terms, toolFields(tool)) }))
+ .filter((entry) => entry.score > 0)
+ .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+ .slice(0, limit)
+ .map((entry) => entry.name);
+}
+
+type Field = readonly [words: readonly string[], weight: number];
+
+function toolFields(tool: ConnectionToolMetadata): Field[] {
+ const properties = isObject(tool.inputSchema.properties)
+ ? Object.entries(tool.inputSchema.properties)
+ : [];
+ const propertyDescriptions = properties.flatMap(([, schema]) =>
+ isObject(schema) && typeof schema.description === "string" ? [schema.description] : [],
+ );
+ return [
+ [tokenize(tool.name), 6],
+ [properties.flatMap(([key]) => tokenize(key)), 3],
+ [tokenize(tool.description), 2],
+ [propertyDescriptions.flatMap(tokenize), 1],
+ ];
+}
+
+function scoreFields(terms: readonly string[], fields: readonly Field[]): number {
+ let score = 0;
+ for (const term of terms) {
+ for (const [words, weight] of fields) {
+ if (words.some((word) => matchesWord(word, term))) score += weight;
+ }
+ }
+ return score;
+}
+
+function matchesWord(word: string, term: string): boolean {
+ return word.startsWith(term) || (word.length >= 3 && term.startsWith(word));
+}
+
+function tokenize(text: string): string[] {
+ return text
+ .replaceAll(/([a-z0-9])([A-Z])/gu, "$1 $2")
+ .toLowerCase()
+ .split(/[^a-z0-9]+/u)
+ .filter((word) => word.length > 1);
+}
diff --git a/packages/eve/src/execution/tools/connection-search.test.ts b/packages/eve/src/execution/tools/connection-search.test.ts
deleted file mode 100644
index 5e6563651..000000000
--- a/packages/eve/src/execution/tools/connection-search.test.ts
+++ /dev/null
@@ -1,784 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-import { ConnectionRegistryKey } from "#context/providers/connection-key.js";
-import { ContextContainer, contextStorage } from "#context/container.js";
-import { AuthKey, SessionIdKey, StaticModelReferenceKey } from "#context/keys.js";
-import { buildDynamicTools } from "#context/build-dynamic-tools.js";
-import { dispatchDynamicToolEvent } from "#context/dynamic-tool-lifecycle.js";
-import { createStepStartedEvent } from "#protocol/message.js";
-import { isToolSchema } from "#tools/schema.js";
-import {
- CallbackBaseUrlKey,
- isAuthorizationSignal,
- PendingAuthorizationResultKey,
-} from "#harness/authorization.js";
-import { ConnectionAuthorizationRequiredError } from "#connections/errors.js";
-import type { ToolContext } from "#tools/definition.js";
-import type {
- ConnectionToolExecuteOptions,
- ConnectionToolMetadata,
-} from "#shared/connection-types.js";
-import type { ConnectionRegistry } from "#runtime/connections/registry-types.js";
-import connectionSearch from "#tools/framework/connection-search.js";
-import type { ResolvedConnectionDefinition, ResolvedDynamicToolResolver } from "#runtime/types.js";
-import { isBrandedToolEntry, type DynamicToolSet } from "#tools/dynamic.js";
-import type { DynamicResolveContext } from "#dynamic/definition.js";
-import { readDurableDynamicToolCallbacks } from "#tools/durable-callbacks.js";
-import { resolveHeaders } from "#runtime/connections/mcp-client.js";
-import { captureLogRecords } from "#internal/testing/log-records.js";
-
-function connection(name: string): ResolvedConnectionDefinition {
- return {
- connectionName: name,
- description: `${name} connection`,
- logicalPath: `agent/connections/${name}.ts`,
- protocol: "mcp",
- sourceId: `connections/${name}`,
- sourceKind: "module",
- url: `https://${name}.example.com/mcp`,
- };
-}
-
-async function executeConnectionSearch(
- registry: ConnectionRegistry,
- input: { readonly connection?: string; readonly keywords: string; readonly limit?: number },
- setupContext?: (ctx: ContextContainer) => void,
-): Promise<unknown> {
- const ctx = new ContextContainer();
- ctx.set(ConnectionRegistryKey, registry);
- setupContext?.(ctx);
-
- return contextStorage.run(ctx, async () => {
- const resolve = getConnectionSearchResolver().events["step.started"]!;
- const resolved = (await resolve({}, {
- model: { id: "openai/gpt-5.5" },
- channel: {},
- messages: [],
- session: { auth: { current: null, initiator: null }, id: "test-session" },
- } satisfies DynamicResolveContext)) as DynamicToolSet;
-
- return resolved["connection_search"]!.execute(input, {} as ToolContext);
- });
-}
-
-function getConnectionSearchResolver() {
- return connectionSearch;
-}
-
-function registry(input: {
- readonly connections: readonly ResolvedConnectionDefinition[];
- readonly loadTools: Readonly<Record<string, () => Promise<readonly ConnectionToolMetadata[]>>>;
-}): ConnectionRegistry {
- return {
- dispose: async () => {},
- getClient: (name) => ({
- close: async () => {},
- connect: async () => {},
- executeTool: async () => {},
- getToolMetadata: input.loadTools[name]!,
- }),
- getConnectionApproval: () => undefined,
- getConnectionNames: () => input.connections.map((item) => item.connectionName),
- getConnections: () => input.connections,
- };
-}
-
-describe("connection dynamic tools", () => {
- it("survives lifecycle resolution with both authored schema validators", async () => {
- const ctx = new ContextContainer();
- ctx.set(SessionIdKey, "connection-schema-replay");
- ctx.set(StaticModelReferenceKey, null);
- ctx.set(
- ConnectionRegistryKey,
- registry({
- connections: [connection("linear")],
- loadTools: { linear: async () => [] },
- }),
- );
- const resolver: ResolvedDynamicToolResolver = {
- slug: "connection-search",
- sourceId: "eve:connection-search",
- sourceKind: "module",
- logicalPath: "tools/connection-search.ts",
- eventNames: ["step.started"],
- events: getConnectionSearchResolver().events as ResolvedDynamicToolResolver["events"],
- };
- await contextStorage.run(ctx, () =>
- dispatchDynamicToolEvent({
- ctx,
- resolvers: [resolver],
- messages: [],
- event: createStepStartedEvent({
- modelId: "test",
- turnId: "turn",
- stepIndex: 0,
- sequence: 0,
- }),
- }),
- );
- const tools = buildDynamicTools(ctx);
- expect(tools.map((tool) => tool.name)).toEqual(["connection_search"]);
- const tool = tools[0]!;
- if (!isToolSchema(tool.inputSchema) || !isToolSchema(tool.outputSchema)) {
- throw new Error("Expected both connection search schemas");
- }
- expect(await tool.inputSchema["~standard"].validate({ keywords: 42 })).toHaveProperty("issues");
- expect(await tool.inputSchema["~standard"].validate({ keywords: "issues" })).toEqual({
- value: { keywords: "issues" },
- });
- expect(await tool.outputSchema["~standard"].validate("invalid")).toHaveProperty("issues");
- });
-
- it("contributes no tools when no connections are available", async () => {
- const ctx = new ContextContainer();
- ctx.set(
- ConnectionRegistryKey,
- registry({
- connections: [],
- loadTools: {},
- }),
- );
- const resolve = getConnectionSearchResolver().events["step.started"]!;
-
- const tools = await contextStorage.run(ctx, () =>
- resolve(
- {},
- {
- model: { id: "openai/gpt-5.5" },
- channel: {},
- messages: [],
- session: { auth: { current: null, initiator: null }, id: "test-session" },
- },
- ),
- );
-
- expect(tools).toBeNull();
- });
-
- it("uses the shared resolver and public tool definitions", async () => {
- const linear = connection("linear");
- const connectionRegistry = registry({
- connections: [linear],
- loadTools: {
- linear: async () => [
- {
- description: "List issues",
- inputSchema: { type: "object" },
- name: "list_issues",
- },
- ],
- },
- });
- const ctx = new ContextContainer();
- ctx.set(ConnectionRegistryKey, connectionRegistry);
- const resolver = getConnectionSearchResolver();
- const resolve = resolver.events["step.started"]!;
-
- const tools = await contextStorage.run(ctx, async () => {
- const initial = (await resolve(
- {},
- {
- channel: {},
- model: null,
- messages: [],
- session: { auth: { current: null, initiator: null }, id: "test-session" },
- },
- )) as DynamicToolSet;
- await initial["connection_search"]!.execute({ keywords: "list issues" }, {} as ToolContext);
- return (await resolve(
- {},
- {
- model: { id: "openai/gpt-5.5" },
- channel: {},
- messages: [],
- session: { auth: { current: null, initiator: null }, id: "test-session" },
- },
- )) as DynamicToolSet;
- });
-
- expect(Object.keys(tools)).toEqual(["connection_search", "linear__list_issues"]);
- expect(Object.values(tools).every(isBrandedToolEntry)).toBe(true);
- });
-
- it("keeps the connection identity in durable callback closures without separate call state", async () => {
- let instanceId = "account-a";
- const executeTool = vi.fn(async () => ({ ok: true }));
- const base = registry({
- connections: [{ ...connection("linear"), instanceId }],
- loadTools: {
- linear: async () => [
- { name: "list_issues", description: "List issues", inputSchema: { type: "object" } },
- ],
- },
- });
- const ctx = new ContextContainer();
- ctx.set(ConnectionRegistryKey, {
- ...base,
- getConnections: () => [{ ...connection("linear"), instanceId }],
- getClient: (name) => ({ ...base.getClient(name), executeTool }),
- });
- await contextStorage.run(ctx, async () => {
- const resolve = getConnectionSearchResolver().events["step.started"]!;
- const context = {
- channel: {},
- model: null,
- messages: [],
- session: { auth: { current: null, initiator: null }, id: "identity-test" },
- } satisfies DynamicResolveContext;
- const initial = (await resolve({}, context)) as DynamicToolSet;
- await initial["connection_search"]!.execute({ keywords: "list issues" }, {} as ToolContext);
- const tools = (await resolve({}, context)) as DynamicToolSet;
- const callback = readDurableDynamicToolCallbacks(tools["linear__list_issues"]!)!.execute!;
- expect(callback.closure).toMatchObject({ connectionName: "linear", instanceId: "account-a" });
- instanceId = "account-b";
- await expect(
- callback.callback(callback.closure, {} as never, { callId: "call-1" } as never),
- ).rejects.toThrow("connection for this tool call changed or is unavailable");
- expect(executeTool).not.toHaveBeenCalled();
- expect([...ctx.entries()].some(([key]) => key.name === "eve.pendingConnectionCalls")).toBe(
- false,
- );
- });
- });
-
- it("delegates MCP model output to the connection client and leaves OpenAPI results whole", async () => {
- const projected = { type: "content", value: [{ type: "text", text: '{"count":2}' }] };
- const toModelOutput = vi.fn(async (_toolName: string, _output: unknown) => projected);
- const base = registry({
- connections: [
- connection("linear"),
- { ...connection("billing"), protocol: "openapi", url: "https://billing.example.com" },
- ],
- loadTools: {
- billing: async () => [
- { description: "List invoices", inputSchema: { type: "object" }, name: "list_invoices" },
- ],
- linear: async () => [
- { description: "List issues", inputSchema: { type: "object" }, name: "list_issues" },
- ],
- },
- });
- const ctx = new ContextContainer();
- ctx.set(ConnectionRegistryKey, {
- ...base,
- getClient: (name) => ({ ...base.getClient(name), toModelOutput }),
- });
- const result = {
- content: [{ text: '{"count":2}', type: "text" }],
- structuredContent: { count: 2 },
- };
-
- await contextStorage.run(ctx, async () => {
- const resolve = getConnectionSearchResolver().events["step.started"]!;
- const context = {
- channel: {},
- model: null,
- messages: [],
- session: { auth: { current: null, initiator: null }, id: "projection-test" },
- } satisfies DynamicResolveContext;
- const initial = (await resolve({}, context)) as DynamicToolSet;
- await initial["connection_search"]!.execute({ keywords: "list" }, {} as ToolContext);
- const tools = (await resolve({}, context)) as DynamicToolSet;
-
- const linear = tools["linear__list_issues"] as {
- toModelOutput?: (output: unknown) => Promise<unknown>;
- };
- await expect(linear.toModelOutput?.(result)).resolves.toBe(projected);
- const durable = readDurableDynamicToolCallbacks(
- tools["linear__list_issues"]!,
- )!.toModelOutput!;
- await expect(durable.callback(durable.closure, result as never)).resolves.toBe(projected);
- expect(toModelOutput.mock.calls).toEqual([
- ["list_issues", result],
- ["list_issues", result],
- ]);
-
- const billing = tools["billing__list_invoices"] as { toModelOutput?: unknown };
- expect(billing.toModelOutput).toBeUndefined();
- expect(
- readDurableDynamicToolCallbacks(tools["billing__list_invoices"]!)?.toModelOutput,
- ).toBeUndefined();
- });
- });
-
- it("forwards the authored tool call ID to connection execution", async () => {
- const linear = connection("linear");
- const executeTool = vi.fn(
- async (_toolName: string, _args: unknown, _options?: ConnectionToolExecuteOptions) => ({
- ok: true,
- }),
- );
- const baseRegistry = registry({
- connections: [linear],
- loadTools: {
- linear: async () => [
- {
- description: "List issues",
- inputSchema: { type: "object" },
- name: "list_issues",
- },
- ],
- },
- });
- const connectionRegistry: ConnectionRegistry = {
- ...baseRegistry,
- getClient: (name) => ({
- ...baseRegistry.getClient(name),
- executeTool,
- }),
- };
- const ctx = new ContextContainer();
- ctx.set(ConnectionRegistryKey, connectionRegistry);
- const abortSignal = {} as AbortSignal;
-
- await contextStorage.run(ctx, async () => {
- const resolve = getConnectionSearchResolver().events["step.started"]!;
- const resolveContext = {
- channel: {},
- model: null,
- messages: [],
- session: { auth: { current: null, initiator: null }, id: "test-session" },
- } satisfies DynamicResolveContext;
- const initial = (await resolve({}, resolveContext)) as DynamicToolSet;
- await initial["connection_search"]!.execute({ keywords: "list issues" }, {} as ToolContext);
- const tools = (await resolve({}, resolveContext)) as DynamicToolSet;
-
- for (const callId of ["call-1", "call-2", "call-1"]) {
- await tools["linear__list_issues"]!.execute({}, { abortSignal, callId } as ToolContext);
- }
- });
-
- expect(executeTool.mock.calls.map(([, , options]) => options?.callId)).toEqual([
- "call-1",
- "call-2",
- "call-1",
- ]);
- });
-});
-
-describe("connection_search", () => {
- it("fails when every targeted connection fails to load", async () => {
- const logs = captureLogRecords();
- const incident = connection("incident");
- const connectionRegistry = registry({
- connections: [incident],
- loadTools: {
- incident: async () => {
- throw new Error("MCP SSE Transport Error: 400 Bad Request");
- },
- },
- });
-
- await expect(
- executeConnectionSearch(connectionRegistry, {
- connection: "incident",
- keywords: "list incidents",
- }),
- ).rejects.toThrow(
- 'Failed to load tools for "incident": MCP SSE Transport Error: 400 Bad Request',
- );
- expect(logs.records).toContainEqual(
- expect.objectContaining({ level: "warn", message: "failed to load connection tools" }),
- );
- });
-
- it("fails when the requested connection is not registered", async () => {
- const incident = connection("incident");
- const connectionRegistry = registry({
- connections: [incident],
- loadTools: { incident: async () => [] },
- });
-
- await expect(
- executeConnectionSearch(connectionRegistry, {
- connection: "incidents",
- keywords: "list incidents",
- }),
- ).rejects.toThrow('Connection "incidents" is not registered. Available connections: incident.');
- });
-
- it("fails when authorization cannot be started", async () => {
- const logs = captureLogRecords();
- const salesforce: ResolvedConnectionDefinition = {
- ...connection("salesforce"),
- authorization: {
- completeAuthorization: async () => ({ token: "unused" }),
- getToken: async () => {
- throw new ConnectionAuthorizationRequiredError("salesforce");
- },
- principalType: "user",
- startAuthorization: async () => {
- throw new Error("OAuth provider unavailable");
- },
- },
- };
- const connectionRegistry = registry({
- connections: [salesforce],
- loadTools: {
- salesforce: async () => {
- throw new ConnectionAuthorizationRequiredError("salesforce");
- },
- },
- });
-
- await expect(
- executeConnectionSearch(
- connectionRegistry,
- { connection: "salesforce", keywords: "accounts" },
- (ctx) => {
- ctx.set(SessionIdKey, "session-auth");
- ctx.set(CallbackBaseUrlKey, "https://agent.example.com");
- ctx.set(AuthKey, {
- attributes: {},
- authenticator: "test-idp",
- issuer: "test-idp",
- principalId: "user-1",
- principalType: "user",
- });
- },
- ),
- ).rejects.toThrow('Failed to start authorization for "salesforce": OAuth provider unavailable');
- expect(logs.records).toContainEqual(
- expect.objectContaining({ level: "warn", message: "connection authorization failed" }),
- );
- });
-
- it("returns connection summaries when loading succeeds without a keyword match", async () => {
- const incident = connection("incident");
- const connectionRegistry = registry({
- connections: [incident],
- loadTools: { incident: async () => [] },
- });
-
- await expect(
- executeConnectionSearch(connectionRegistry, { keywords: "list incidents" }),
- ).resolves.toEqual([
- {
- connection: "incident",
- description: "incident connection",
- },
- ]);
- });
-
- it("returns matches and errors when at least one connection loads", async () => {
- const logs = captureLogRecords();
- const incident = connection("incident");
- const linear = connection("linear");
- const connectionRegistry = registry({
- connections: [incident, linear],
- loadTools: {
- incident: async () => {
- throw new Error("MCP SSE Transport Error: 400 Bad Request");
- },
- linear: async () => [
- {
- description: "List issues",
- inputSchema: { type: "object" },
- name: "list_issues",
- },
- ],
- },
- });
-
- await expect(
- executeConnectionSearch(connectionRegistry, { keywords: "list issues" }),
- ).resolves.toEqual([
- {
- connection: "linear",
- description: "List issues",
- inputSchema: { type: "object" },
- outputSchema: undefined,
- qualifiedName: "linear__list_issues",
- tool: "list_issues",
- },
- {
- connection: "incident",
- description: "incident connection",
- error: 'Failed to load tools for "incident": MCP SSE Transport Error: 400 Bad Request',
- },
- ]);
- expect(logs.records).toContainEqual(
- expect.objectContaining({ level: "warn", message: "failed to load connection tools" }),
- );
- });
-
- it("does not complete an unrelated connection authorization", async () => {
- let notionCompletions = 0;
- const notion: ResolvedConnectionDefinition = {
- ...connection("notion"),
- authorization: {
- completeAuthorization: async () => {
- notionCompletions += 1;
- throw new Error("stale Notion callback");
- },
- getToken: async () => ({ token: "notion-token" }),
- principalType: "user",
- startAuthorization: async () => ({
- challenge: { url: "https://idp.example.com/authorize" },
- }),
- },
- };
- const linear = connection("linear");
- const connectionRegistry = registry({
- connections: [notion, linear],
- loadTools: {
- notion: async () => [],
- linear: async () => [
- {
- description: "List issues",
- inputSchema: { type: "object" },
- name: "list_issues",
- },
- ],
- },
- });
-
- await expect(
- executeConnectionSearch(
- connectionRegistry,
- { connection: "linear", keywords: "list issues" },
- (ctx) => {
- ctx.set(PendingAuthorizationResultKey, [
- {
- attemptId: "attempt-notion",
- callback: { method: "GET", params: {} },
- hookUrl: "https://agent.example.com/eve/v1/connections/notion/callback/auth",
- name: "notion",
- principal: { type: "app" },
- },
- ]);
- },
- ),
- ).resolves.toMatchObject([
- {
- connection: "linear",
- qualifiedName: "linear__list_issues",
- },
- ]);
- expect(notionCompletions).toBe(0);
- });
-
- it("does not pass a parked callback to a newly resolved connection instance", async () => {
- const completeAuthorization = vi.fn(async () => ({ token: "instance-b-token" }));
- const salesforce: ResolvedConnectionDefinition = {
- ...connection("salesforce"),
- authorization: {
- completeAuthorization,
- getToken: async () => ({ token: "instance-b-token" }),
- principalType: "user",
- startAuthorization: async () => ({ challenge: {} }),
- },
- instanceId: "instance-b",
- };
- const connectionRegistry = registry({
- connections: [salesforce],
- loadTools: { salesforce: async () => [] },
- });
-
- await expect(
- executeConnectionSearch(
- connectionRegistry,
- { connection: "salesforce", keywords: "accounts" },
- (ctx) => {
- ctx.set(PendingAuthorizationResultKey, [
- {
- attemptId: "attempt-a",
- callback: { method: "GET", params: { code: "code-a" } },
- hookUrl: "https://agent.example.com/callback",
- instanceId: "instance-a",
- name: "salesforce",
- principal: { id: "user-1", issuer: "test-idp", type: "user" },
- },
- ]);
- },
- ),
- ).rejects.toThrow("resolved connection changed while sign-in was pending");
- expect(completeAuthorization).not.toHaveBeenCalled();
- });
-
- it("returns an authorization signal when sign-in can be started", async () => {
- const salesforce: ResolvedConnectionDefinition = {
- ...connection("salesforce"),
- authorization: {
- completeAuthorization: async () => ({ token: "unused" }),
- getToken: async () => {
- throw new ConnectionAuthorizationRequiredError("salesforce");
- },
- principalType: "user",
- startAuthorization: async () => ({
- challenge: { url: "https://idp.example.com/authorize" },
- }),
- },
- instanceId: "salesforce-instance",
- };
- const connectionRegistry = registry({
- connections: [salesforce],
- loadTools: {
- salesforce: async () => {
- throw new ConnectionAuthorizationRequiredError("salesforce");
- },
- },
- });
-
- const result = await executeConnectionSearch(
- connectionRegistry,
- { connection: "salesforce", keywords: "accounts" },
- (ctx) => {
- ctx.set(SessionIdKey, "session-auth");
- ctx.set(CallbackBaseUrlKey, "https://agent.example.com");
- ctx.set(AuthKey, {
- attributes: {},
- authenticator: "test-idp",
- issuer: "test-idp",
- principalId: "user-1",
- principalType: "user",
- });
- },
- );
-
- expect(isAuthorizationSignal(result)).toBe(true);
- if (!isAuthorizationSignal(result)) throw new Error("expected authorization signal");
- expect(result.challenges).toMatchObject([
- {
- name: "salesforce",
- challenge: { url: "https://idp.example.com/authorize" },
- instanceId: "salesforce-instance",
- },
- ]);
- });
-
- it.each([false, true])(
- "completes connection auth through the shared token cache (fresh token refused: %s)",
- async (refused) => {
- const logs = captureLogRecords();
- const getToken = vi.fn(async () => {
- throw new ConnectionAuthorizationRequiredError("salesforce");
- });
- const startAuthorization = vi.fn(async () => ({
- challenge: { url: "https://idp.example.com/authorize" },
- }));
- const completeAuthorization = vi.fn(async () => ({ token: "fresh-token" }));
- const salesforce: ResolvedConnectionDefinition = {
- ...connection("salesforce"),
- instanceId: "salesforce-instance",
- authorization: {
- principalType: "user",
- getToken,
- startAuthorization,
- completeAuthorization,
- },
- };
- const connectionRegistry = registry({
- connections: [salesforce],
- loadTools: {
- salesforce: async () => {
- const headers = await resolveHeaders(salesforce);
- expect(headers.Authorization).toBe("Bearer fresh-token");
- if (refused) throw new ConnectionAuthorizationRequiredError("salesforce");
- return [{ name: "list_accounts", description: "List accounts", inputSchema: {} }];
- },
- },
- });
- const setup = (ctx: ContextContainer) => {
- ctx.set(SessionIdKey, "session-auth");
- ctx.set(CallbackBaseUrlKey, "https://agent.example.com");
- ctx.set(AuthKey, {
- attributes: {},
- authenticator: "test-idp",
- issuer: "test-idp",
- principalId: "user-1",
- principalType: "user",
- });
- };
- const input = { connection: "salesforce", keywords: "accounts" };
- const pending = await executeConnectionSearch(connectionRegistry, input, setup);
- if (!isAuthorizationSignal(pending)) throw new Error("expected authorization signal");
- const challenge = pending.challenges[0]!;
- expect(challenge).toMatchObject({
- instanceId: "salesforce-instance",
- principal: { type: "user", id: "user-1", issuer: "test-idp" },
- });
- const resumed = executeConnectionSearch(connectionRegistry, input, (ctx) => {
- setup(ctx);
- ctx.set(PendingAuthorizationResultKey, [
- {
- ...challenge,
- callback: { method: "GET", params: { code: "approved" } },
- },
- ]);
- });
- if (refused) {
- await expect(resumed).rejects.toThrow("rejected the token immediately after authorization");
- } else {
- await expect(resumed).resolves.toMatchObject([
- { qualifiedName: "salesforce__list_accounts" },
- ]);
- }
- expect(getToken).toHaveBeenCalledOnce();
- expect(startAuthorization).toHaveBeenCalledOnce();
- expect(completeAuthorization).toHaveBeenCalledExactlyOnceWith(
- expect.objectContaining({
- principal: challenge.principal,
- callback: { method: "GET", params: { code: "approved" } },
- }),
- );
- const failures = logs.records.filter(
- (record) => record.message === "connection authorization failed",
- );
- expect(failures).toHaveLength(refused ? 1 : 0);
- },
- );
-
- it("replays authorization from the step-scoped durable execute descriptor", async () => {
- const salesforce: ResolvedConnectionDefinition = {
- ...connection("salesforce"),
- authorization: {
- completeAuthorization: async () => ({ token: "unused" }),
- getToken: async () => {
- throw new ConnectionAuthorizationRequiredError("salesforce");
- },
- principalType: "user",
- startAuthorization: async () => ({
- challenge: { url: "https://idp.example.com/authorize" },
- }),
- },
- };
- const connectionRegistry = registry({
- connections: [salesforce],
- loadTools: {
- salesforce: async () => {
- throw new ConnectionAuthorizationRequiredError("salesforce");
- },
- },
- });
- const ctx = new ContextContainer();
- ctx.set(ConnectionRegistryKey, connectionRegistry);
- ctx.set(SessionIdKey, "session-auth-replay");
- ctx.set(CallbackBaseUrlKey, "https://agent.example.com");
- ctx.set(AuthKey, {
- attributes: {},
- authenticator: "test-idp",
- issuer: "test-idp",
- principalId: "user-1",
- principalType: "user",
- });
-
- const result = await contextStorage.run(ctx, async () => {
- const resolve = getConnectionSearchResolver().events["step.started"]!;
- const tools = (await resolve({}, {
- channel: {},
- model: null,
- messages: [],
- session: { auth: { current: null, initiator: null }, id: "session-auth-replay" },
- } satisfies DynamicResolveContext)) as DynamicToolSet;
- const reference = readDurableDynamicToolCallbacks(tools["connection_search"]!)!.execute!;
-
- return await reference.callback(reference.closure, {
- connection: "salesforce",
- keywords: "accounts",
- } as never);
- });
-
- expect(isAuthorizationSignal(result)).toBe(true);
- });
-});
diff --git a/packages/eve/src/execution/tools/connection-search.ts b/packages/eve/src/execution/tools/connection-search.ts
deleted file mode 100644
index 8f9bd1886..000000000
--- a/packages/eve/src/execution/tools/connection-search.ts
+++ /dev/null
@@ -1,527 +0,0 @@
-import { loadContext } from "#context/container.js";
-import { ContextKey } from "#context/key.js";
-import {
- type AuthorizationChallenge,
- type AuthorizationSignal,
- getAuthorizationResults,
- requestAuthorization,
-} from "#harness/authorization.js";
-import {
- isConnectionAuthorizationFailedError,
- isConnectionAuthorizationRequiredError,
-} from "#connections/errors.js";
-import { defineTool } from "#tools/definition.js";
-import type { ToolContext } from "#tools/definition.js";
-import type { ToolModelOutput } from "#tools/model-output.js";
-import {
- resolveApprovalPolicy,
- type ApprovalContext,
- type ApprovalResponseContext,
-} from "#approval/definition.js";
-import type { JsonObject } from "#shared/json.js";
-import { stampDurableDynamicToolCallbacks } from "#tools/durable-callbacks.js";
-import { defineJsonSchema } from "#tools/schema.js";
-import { resolveConnectionAuthorization } from "#runtime/connections/resolve-authorization.js";
-import {
- createAuthorizationExecution,
- type ScopedAuthorization,
-} from "#runtime/connections/scoped-authorization.js";
-import {
- type ConnectionToolMetadata,
- supportsInteractiveAuthorization,
-} from "#shared/connection-types.js";
-import type { ConnectionRegistry } from "#runtime/connections/registry-types.js";
-import type { ResolvedConnectionDefinition } from "#runtime/types.js";
-import { createLogger } from "#internal/logging.js";
-import { toError } from "#shared/errors.js";
-
-import { ConnectionRegistryKey } from "#context/providers/connection-key.js";
-
-const logger = createLogger("framework.connection-search-dynamic");
-
-const CONNECTION_SEARCH_INPUT_SCHEMA = defineJsonSchema<ConnectionSearchInput>({
- type: "object",
- properties: {
- connection: {
- type: "string",
- description: "Optional: limit search to a specific connection name.",
- },
- keywords: {
- type: "string",
- description:
- "Search keywords and expanded aliases. Distill intent into keywords; avoid stop words like 'a', 'the', 'in'.",
- },
- limit: { type: "number", description: "Max results to return. Default 10." },
- },
- required: ["keywords"],
- additionalProperties: false,
-});
-
-const CONNECTION_SEARCH_OUTPUT_SCHEMA = defineJsonSchema<ConnectionSearchResultItem[]>({
- type: "array",
- items: {
- type: "object",
- properties: {
- connection: { type: "string" },
- description: { type: "string" },
- error: { type: "string" },
- inputSchema: { type: "object" },
- needsAuthorization: { type: "boolean" },
- outputSchema: { type: "object" },
- qualifiedName: { type: "string" },
- tool: { type: "string" },
- },
- required: ["connection", "description"],
- additionalProperties: false,
- },
-});
-
-/**
- * Durable context key for connection search results. Written by
- * `executeConnectionSearch` so the resolver can find discovered tools without
- * relying on model-facing tool result history.
- */
-const ConnectionSearchResultsKey = new ContextKey<readonly ConnectionSearchResultItem[]>(
- "eve.connectionSearchResults",
-);
-
-/**
- * Builds the qualified tool name for a connection tool.
- */
-function qualifiedConnectionToolName(connectionName: string, toolName: string): string {
- return `${connectionName}__${toolName}`;
-}
-
-interface ConnectionSearchInput {
- readonly connection?: string;
- readonly keywords: string;
- readonly limit?: number;
-}
-
-interface ConnectionSearchResultItem {
- readonly connection: string;
- readonly description: string;
- readonly error?: string;
- readonly inputSchema?: Record<string, unknown>;
- readonly needsAuthorization?: boolean;
- readonly outputSchema?: Record<string, unknown>;
- readonly tool?: string;
- readonly qualifiedName?: string;
-}
-
-function tokenize(text: string): string[] {
- return text
- .toLowerCase()
- .split(/[\s_\-./]+/)
- .filter((t) => t.length > 1);
-}
-
-function scoreMatch(queryTokens: string[], tool: ConnectionToolMetadata): number {
- const nameTokens = tokenize(tool.name);
- const descTokens = tokenize(tool.description);
- let score = 0;
-
- for (const qt of queryTokens) {
- for (const nt of nameTokens) {
- if (nt.includes(qt) || qt.includes(nt)) {
- score += 3;
- }
- }
- for (const dt of descTokens) {
- if (dt.includes(qt) || qt.includes(dt)) {
- score += 1;
- }
- }
- }
-
- return score;
-}
-
-async function resolveInteractiveAuth(
- registry: ConnectionRegistry,
- connectionName: string,
-): Promise<ScopedAuthorization | undefined> {
- const conn = registry.getConnections().find((c) => c.connectionName === connectionName);
- if (conn === undefined) return undefined;
- const authorization = await resolveConnectionAuthorization(conn);
- if (authorization === undefined || !supportsInteractiveAuthorization(authorization)) {
- return undefined;
- }
- return {
- scope: conn.connectionName,
- instanceId: conn.instanceId,
- connection: { url: conn.url ?? "" },
- authorization,
- };
-}
-
-/** Complete only callbacks for the connections targeted by this search. */
-async function completePendingAuthorizations(
- registry: ConnectionRegistry,
- connections: readonly ResolvedConnectionDefinition[],
- auth: ReturnType<typeof createAuthorizationExecution>,
-): Promise<void> {
- assertPendingConnectionAuthorizationInstances(registry);
- for (const conn of connections) {
- if (!getAuthorizationResults().some((result) => result.name === conn.connectionName)) continue;
- const scoped = await resolveInteractiveAuth(registry, conn.connectionName);
- if (scoped !== undefined) await auth.complete(scoped);
- }
-}
-
-async function executeConnectionSearch(
- input: ConnectionSearchInput,
-): Promise<ConnectionSearchResultItem[] | AuthorizationSignal> {
- const ctx = loadContext();
- const registry = ctx.get(ConnectionRegistryKey);
- if (registry === undefined) {
- return [];
- }
-
- const limit = input.limit ?? 10;
- const queryTokens = tokenize(input.keywords);
- const results: Array<{ item: ConnectionSearchResultItem; score: number }> = [];
- const failedConnections: ConnectionSearchResultItem[] = [];
-
- const targetConnections =
- input.connection !== undefined && input.connection !== ""
- ? registry.getConnections().filter((c) => c.connectionName === input.connection)
- : registry.getConnections();
-
- if (input.connection && targetConnections.length === 0) {
- throw new Error(
- `Connection "${input.connection}" is not registered. Available connections: ${registry.getConnectionNames().join(", ")}.`,
- );
- }
-
- const auth = createAuthorizationExecution();
- await completePendingAuthorizations(registry, targetConnections, auth);
-
- const authChallenges: AuthorizationChallenge[] = [];
-
- for (const conn of targetConnections) {
- let tools: readonly ConnectionToolMetadata[];
- try {
- const client = registry.getClient(conn.connectionName);
- tools = await client.getToolMetadata();
- } catch (err) {
- if (isConnectionAuthorizationRequiredError(err)) {
- const scoped = await resolveInteractiveAuth(registry, conn.connectionName);
- if (scoped !== undefined) {
- try {
- const signal = await auth.handleError(err, scoped);
- authChallenges.push(...signal.challenges);
- } catch (startErr) {
- const error = toError(startErr);
- logger.warn("connection authorization failed", {
- connection: conn.connectionName,
- error,
- });
- failedConnections.push({
- connection: conn.connectionName,
- description: conn.description,
- error: isConnectionAuthorizationFailedError(error)
- ? error.message
- : `Failed to start authorization for "${conn.connectionName}": ${error.message}`,
- });
- continue;
- }
- }
- failedConnections.push({
- connection: conn.connectionName,
- description: conn.description,
- needsAuthorization: true,
- });
- continue;
- }
-
- if (isConnectionAuthorizationFailedError(err)) {
- logger.warn("connection authorization failed", {
- connection: conn.connectionName,
- reason: err.reason,
- retryable: err.retryable,
- error: err,
- });
- failedConnections.push({
- connection: conn.connectionName,
- description: conn.description,
- error: `Authorization failed for ${conn.connectionName}: ${err.message}`,
- });
- continue;
- }
-
- const error = toError(err);
- logger.warn("failed to load connection tools", {
- connection: conn.connectionName,
- error,
- });
- failedConnections.push({
- connection: conn.connectionName,
- description: conn.description,
- error: `Failed to load tools for "${conn.connectionName}": ${error.message}`,
- });
- continue;
- }
-
- for (const tool of tools) {
- const score = scoreMatch(queryTokens, tool);
- if (score > 0) {
- results.push({
- item: {
- connection: conn.connectionName,
- description: tool.description,
- inputSchema: tool.inputSchema,
- outputSchema: tool.outputSchema,
- qualifiedName: qualifiedConnectionToolName(conn.connectionName, tool.name),
- tool: tool.name,
- },
- score,
- });
- }
- }
- }
-
- if (authChallenges.length > 0) {
- return requestAuthorization(authChallenges);
- }
-
- const terminalFailures = failedConnections.filter((failure) => failure.error !== undefined);
- if (targetConnections.length > 0 && terminalFailures.length === targetConnections.length) {
- // When every targeted connection reaches a terminal error, connection_search itself fails.
- // AI SDK catches this rejection, emits a tool-error result, and preserves the failed call in
- // agent-run observability. Partial failures stay in the successful result so usable tools remain discoverable.
- throw new Error(terminalFailures.map((failure) => failure.error).join("\n"));
- }
-
- results.sort((a, b) => b.score - a.score);
- const matched = results.slice(0, limit).map((r) => r.item);
-
- if (matched.length > 0) {
- const allResults = [...matched, ...failedConnections];
- const existing = ctx.get(ConnectionSearchResultsKey) ?? [];
- const merged = new Map(existing.map((r) => [r.qualifiedName, r]));
- for (const r of matched) {
- if (r.qualifiedName) merged.set(r.qualifiedName, r);
- }
- ctx.set(ConnectionSearchResultsKey, [...merged.values()]);
- return allResults;
- }
-
- const summaries: ConnectionSearchResultItem[] = targetConnections.map((c) => {
- const failed = failedConnections.find((f) => f.connection === c.connectionName);
- if (failed) return failed;
- return {
- connection: c.connectionName,
- description: c.description,
- };
- });
-
- return summaries;
-}
-
-export function connectionToolReplayIdentity(toolName: string): string | undefined {
- const ctx = loadContext();
- const discovered = ctx
- .get(ConnectionSearchResultsKey)
- ?.find((entry) => entry.qualifiedName === toolName);
- if (discovered === undefined) return;
- return ctx
- .get(ConnectionRegistryKey)
- ?.getConnections()
- .find((connection) => connection.connectionName === discovered.connection)?.instanceId;
-}
-
-function assertConnectionToolInstance(closure: JsonObject): void {
- if (typeof closure.instanceId !== "string") return;
- const { connectionName } = readDiscoveredToolClosure(closure);
- const connection = loadContext()
- .get(ConnectionRegistryKey)
- ?.getConnections()
- .find((entry) => entry.connectionName === connectionName);
- if (connection?.instanceId !== closure.instanceId) {
- throw new Error(
- "The connection for this tool call changed or is unavailable. Request a new tool call and approval.",
- );
- }
-}
-
-function readDiscoveredToolClosure(closure: JsonObject): {
- readonly connectionName: string;
- readonly toolName: string;
-} {
- const connectionName = closure.connectionName;
- const toolName = closure.toolName;
- if (typeof connectionName !== "string" || typeof toolName !== "string") {
- throw new Error("Discovered connection tool callback metadata is invalid.");
- }
- return { connectionName, toolName };
-}
-
-async function executeDiscoveredConnectionTool(
- closure: JsonObject,
- input: Record<string, unknown>,
- executeCtx: ToolContext,
-): Promise<unknown> {
- const { connectionName, toolName } = readDiscoveredToolClosure(closure);
- const registry = loadContext().get(ConnectionRegistryKey);
- if (registry === undefined) {
- throw new Error("Connection registry is unavailable while replaying a discovered tool.");
- }
- assertConnectionToolInstance(closure);
- assertPendingConnectionAuthorizationInstances(registry);
- const scoped = await resolveInteractiveAuth(registry, connectionName);
- const auth = createAuthorizationExecution();
- if (scoped !== undefined) await auth.complete(scoped);
- try {
- const client = registry.getClient(connectionName);
- return await client.executeTool(toolName, input, {
- abortSignal: executeCtx.abortSignal,
- callId: executeCtx.callId,
- });
- } catch (error) {
- return await auth.handleError(error, scoped);
- }
-}
-
-/** Delegates to the connection client's projection, falling back to the raw result as JSON. */
-async function discoveredConnectionToolModelOutput(
- closure: JsonObject,
- output: unknown,
-): Promise<ToolModelOutput> {
- const { connectionName, toolName } = readDiscoveredToolClosure(closure);
- const client = loadContext().get(ConnectionRegistryKey)?.getClient(connectionName);
- const modelOutput = await client?.toModelOutput?.(toolName, output);
- // The harness validates the shape in `normalizeToolModelOutput`.
- return (modelOutput ?? { type: "json", value: output ?? null }) as ToolModelOutput;
-}
-
-function assertPendingConnectionAuthorizationInstances(registry: ConnectionRegistry): void {
- const connections = new Map(
- registry.getConnections().map((connection) => [connection.connectionName, connection]),
- );
- for (const result of getAuthorizationResults()) {
- if (result.instanceId === undefined) continue;
- if (connections.get(result.name)?.instanceId === result.instanceId) continue;
- throw new Error(
- `Authorization for "${result.name}" cannot complete because its resolved connection changed while sign-in was pending. Start sign-in again.`,
- );
- }
-}
-
-async function requestDiscoveredConnectionToolApproval(
- closure: JsonObject,
- context: ApprovalContext,
-) {
- const { connectionName } = readDiscoveredToolClosure(closure);
- assertConnectionToolInstance(closure);
- const approval = loadContext().get(ConnectionRegistryKey)?.getConnectionApproval(connectionName);
- return approval === undefined ? "not-applicable" : await resolveApprovalPolicy(approval)(context);
-}
-
-async function authorizeDiscoveredConnectionToolApproval(
- closure: JsonObject,
- context: ApprovalResponseContext,
-) {
- const { connectionName } = readDiscoveredToolClosure(closure);
- assertConnectionToolInstance(closure);
- const approval = loadContext().get(ConnectionRegistryKey)?.getConnectionApproval(connectionName);
- const response =
- approval === undefined || typeof approval === "function" ? undefined : approval.response;
- return response === undefined
- ? { reason: "Approval response authorization is unavailable.", status: "rejected" as const }
- : await response(context);
-}
-
-export async function resolveConnectionSearchDynamicTools() {
- const registry = loadContext().get(ConnectionRegistryKey);
- if (!registry || registry.getConnections().length === 0) return null;
-
- const connections = registry.getConnections();
- const connectionNames = connections.map((c) => c.connectionName);
- const activeConnectionNames = new Set(connectionNames);
- const discovered = (loadContext().get(ConnectionSearchResultsKey) ?? []).filter((result) =>
- activeConnectionNames.has(result.connection),
- );
-
- const tools: Record<string, object> = {};
-
- const connectionSearchTool = defineTool({
- description:
- "Search for tools across your connections. " +
- "Discovered tools become directly callable by their qualified name " +
- "(e.g. `linear__list_issues`) in your next response. " +
- `Available connections: ${connectionNames.join(", ")}.`,
- inputSchema: CONNECTION_SEARCH_INPUT_SCHEMA,
- async execute(input: ConnectionSearchInput) {
- return executeConnectionSearch(input);
- },
- outputSchema: CONNECTION_SEARCH_OUTPUT_SCHEMA,
- });
- stampDurableDynamicToolCallbacks(connectionSearchTool, {
- inputSchema: { callback: () => CONNECTION_SEARCH_INPUT_SCHEMA, closure: {} },
- outputSchema: { callback: () => CONNECTION_SEARCH_OUTPUT_SCHEMA, closure: {} },
- execute: {
- callback: (_closure, input) => executeConnectionSearch(input as ConnectionSearchInput),
- closure: {},
- },
- });
- tools["connection_search"] = connectionSearchTool;
-
- for (const result of discovered) {
- const connectionName = result.connection;
- const toolName = result.tool!;
- const approval = registry.getConnectionApproval(connectionName);
-
- const resolvedConnection = connections.find(
- (connection) => connection.connectionName === connectionName,
- );
- const instanceId = resolvedConnection?.instanceId;
- const projectsMcpResult = resolvedConnection?.protocol === "mcp";
- const closure: { connectionName: string; toolName: string; instanceId?: string } = {
- connectionName,
- toolName,
- };
- if (instanceId !== undefined) closure.instanceId = instanceId;
- const discoveredTool = defineTool({
- description: result.description,
- inputSchema: (result.inputSchema ?? {
- type: "object",
- }) as JsonObject,
- approval,
- outputSchema: result.outputSchema as JsonObject | undefined,
- async execute(input: Record<string, unknown>, executeCtx) {
- return await executeDiscoveredConnectionTool(closure, input, executeCtx);
- },
- toModelOutput: projectsMcpResult
- ? (output: unknown) => discoveredConnectionToolModelOutput(closure, output)
- : undefined,
- });
- stampDurableDynamicToolCallbacks(discoveredTool, {
- execute: { callback: executeDiscoveredConnectionTool, closure },
- toModelOutput: projectsMcpResult
- ? { callback: discoveredConnectionToolModelOutput, closure }
- : undefined,
- ...(approval === undefined
- ? {}
- : {
- approvalRequest: {
- callback: requestDiscoveredConnectionToolApproval,
- closure,
- },
- }),
- ...(approval === undefined ||
- typeof approval === "function" ||
- approval.response === undefined
- ? {}
- : {
- approvalResponse: {
- callback: authorizeDiscoveredConnectionToolApproval,
- closure,
- },
- }),
- });
- tools[qualifiedConnectionToolName(connectionName, toolName)] = discoveredTool;
- }
-
- return tools;
-}
diff --git a/packages/eve/src/execution/tools/connection-target.ts b/packages/eve/src/execution/tools/connection-target.ts
new file mode 100644
index 000000000..12bffb5cc
--- /dev/null
+++ b/packages/eve/src/execution/tools/connection-target.ts
@@ -0,0 +1,32 @@
+/** The `connection_execute` call target, shared by execution and approval. */
+
+import type { ConnectionRegistry } from "#runtime/connections/registry-types.js";
+import type { ResolvedConnectionDefinition } from "#runtime/types.js";
+import { isObject } from "#shared/guards.js";
+import type { JsonObject } from "#shared/json.js";
+
+export const CONNECTION_EXECUTE_TOOL_NAME = "connection_execute";
+
+export interface ExecuteTarget {
+ readonly connection: string;
+ readonly input: JsonObject;
+ readonly tool: string;
+}
+
+export function readExecuteTarget(value: unknown): ExecuteTarget | undefined {
+ if (!isObject(value)) return undefined;
+ const { connection, input, tool } = value;
+ if (typeof connection !== "string" || typeof tool !== "string") return undefined;
+ return { connection, input: isObject(input) ? (input as JsonObject) : {}, tool };
+}
+
+export function qualifiedToolName(target: Pick<ExecuteTarget, "connection" | "tool">): string {
+ return `${target.connection}__${target.tool}`;
+}
+
+export function findConnection(
+ registry: ConnectionRegistry,
+ name: string,
+): ResolvedConnectionDefinition | undefined {
+ return registry.getConnections().find((connection) => connection.connectionName === name);
+}
diff --git a/packages/eve/src/execution/tools/connection-tools.ts b/packages/eve/src/execution/tools/connection-tools.ts
new file mode 100644
index 000000000..cc2fa217b
--- /dev/null
+++ b/packages/eve/src/execution/tools/connection-tools.ts
@@ -0,0 +1,477 @@
+/**
+ * `connection_search` and `connection_execute`: fixed tools that reach every
+ * connection tool without adding definitions to the model's tool list, so
+ * discovery never changes the cached prompt prefix. Both are rebuilt each
+ * step from the connection registry with identical model-facing definitions.
+ */
+
+import type { Approval } from "#approval/definition.js";
+import {
+ isConnectionAuthorizationFailedError,
+ isConnectionAuthorizationRequiredError,
+} from "#connections/errors.js";
+import { loadContext } from "#context/container.js";
+import { ConnectionRegistryKey } from "#context/providers/connection-key.js";
+import {
+ getAuthorizationResults,
+ requestAuthorization,
+ type AuthorizationChallenge,
+ type AuthorizationSignal,
+} from "#harness/authorization.js";
+import { reportNestedToolAction } from "#harness/nested-actions.js";
+import { createLogger } from "#internal/logging.js";
+import type { ConnectionRegistry } from "#runtime/connections/registry-types.js";
+import { resolveConnectionAuthorization } from "#runtime/connections/resolve-authorization.js";
+import {
+ createAuthorizationExecution,
+ type ScopedAuthorization,
+} from "#runtime/connections/scoped-authorization.js";
+import {
+ connectionToolModelOutput,
+ toConnectionToolResult,
+} from "#runtime/connections/tool-result.js";
+import { renderToolSignature } from "#runtime/connections/tool-signature.js";
+import type { ResolvedConnectionDefinition } from "#runtime/types.js";
+import {
+ supportsInteractiveAuthorization,
+ type ConnectionToolMetadata,
+} from "#shared/connection-types.js";
+import { toErrorMessage } from "#shared/errors.js";
+import { isObject } from "#shared/guards.js";
+import type { JsonObject } from "#shared/json.js";
+import { defineDurableCallback } from "#tools/durable-callbacks.js";
+import { defineTool, type ToolContext } from "#tools/definition.js";
+import type { DynamicToolSet } from "#tools/dynamic.js";
+import { defineJsonSchema } from "#tools/schema.js";
+
+import { connectionExecuteApproval, releaseApprovalPin } from "./connection-approval.js";
+import {
+ closestToolNames,
+ rankConnectionTools,
+ type RankCandidate,
+} from "./connection-search-rank.js";
+import {
+ CONNECTION_EXECUTE_TOOL_NAME,
+ findConnection,
+ qualifiedToolName,
+ readExecuteTarget,
+} from "./connection-target.js";
+
+const log = createLogger("framework.connection-tools");
+
+export const CONNECTION_SEARCH_TOOL_NAME = "connection_search";
+
+const DEFAULT_SEARCH_LIMIT = 10;
+const MAX_SEARCH_LIMIT = 50;
+const MAX_SUGGESTIONS = 5;
+
+const CONNECTION_SEARCH_DESCRIPTION = [
+ "Find tools in your connected services (MCP servers and OpenAPI APIs).",
+ "Returns each matching tool's connection, name, description, and TypeScript signature.",
+ "Omit `query` to list a connection's tools. Call a found tool with connection_execute.",
+ "Prefer connected services over web search or general knowledge when a request relates to them.",
+].join(" ");
+
+const CONNECTION_EXECUTE_DESCRIPTION = [
+ "Call one tool from a connected service and return its result.",
+ "Use the exact `connection` and `tool` names returned by connection_search,",
+ "and pass `input` matching the tool's signature.",
+].join(" ");
+
+const CONNECTION_SEARCH_INPUT_SCHEMA: JsonObject = {
+ type: "object",
+ properties: {
+ query: {
+ type: "string",
+ description:
+ "Words describing the capability, such as 'list open issues'. Omit to list every tool.",
+ },
+ connection: { type: "string", description: "Only search this connection." },
+ limit: {
+ type: "integer",
+ minimum: 1,
+ maximum: MAX_SEARCH_LIMIT,
+ description: `Maximum results. Defaults to ${DEFAULT_SEARCH_LIMIT}.`,
+ },
+ offset: { type: "integer", minimum: 0, description: "Results to skip, for paging." },
+ },
+ additionalProperties: false,
+};
+
+const CONNECTION_EXECUTE_INPUT_SCHEMA: JsonObject = {
+ type: "object",
+ properties: {
+ connection: { type: "string", description: "Connection name from connection_search." },
+ tool: { type: "string", description: "Tool name from connection_search." },
+ input: {
+ type: "object",
+ description: "Arguments matching the tool's signature. Defaults to {}.",
+ },
+ },
+ required: ["connection", "tool"],
+ additionalProperties: false,
+};
+
+interface ConnectionSearchInput {
+ readonly connection?: string;
+ readonly limit?: number;
+ readonly offset?: number;
+ readonly query?: string;
+}
+
+interface ConnectionSearchMatch {
+ readonly connection: string;
+ readonly description: string;
+ readonly signature: string;
+ readonly tool: string;
+}
+
+interface UnavailableConnection {
+ readonly connection: string;
+ readonly error: string;
+ /** Whether the failure is final rather than waiting on authorization. */
+ readonly terminal: boolean;
+}
+
+interface ConnectionSearchOutput {
+ readonly tools: readonly ConnectionSearchMatch[];
+ /** Matches across all pages. */
+ readonly total: number;
+ readonly unavailable?: readonly Omit<UnavailableConnection, "terminal">[];
+}
+
+// ---------------------------------------------------------------------------
+// Tool definitions
+// ---------------------------------------------------------------------------
+
+/** Builds both tools for the current step, or `null` when the agent has no connections. */
+export function resolveConnectionTools(): DynamicToolSet | null {
+ const registry = loadContext().get(ConnectionRegistryKey);
+ if (registry === undefined) return null;
+
+ const approvals = registry
+ .getConnections()
+ .map((connection) => registry.getConnectionApproval(connection.connectionName))
+ .filter((approval): approval is Approval => approval !== undefined);
+
+ return {
+ [CONNECTION_SEARCH_TOOL_NAME]: defineTool({
+ description: CONNECTION_SEARCH_DESCRIPTION,
+ inputSchema: CONNECTION_SEARCH_INPUT_SCHEMA,
+ execute: defineDurableCallback({ callback: searchConnectionTools, closure: {} }),
+ }),
+ [CONNECTION_EXECUTE_TOOL_NAME]: defineTool({
+ description: CONNECTION_EXECUTE_DESCRIPTION,
+ inputSchema: CONNECTION_EXECUTE_INPUT_SCHEMA,
+ execute: defineDurableCallback({ callback: executeConnectionTool, closure: {} }),
+ label: {
+ start: defineDurableCallback({ callback: connectionToolLabel, closure: {} }),
+ },
+ toModelOutput: defineDurableCallback({
+ callback: (_closure: object, output: unknown) => connectionToolModelOutput(output),
+ closure: {},
+ }),
+ ...connectionExecuteApproval(approvals),
+ }),
+ };
+}
+
+function connectionToolLabel(_closure: object, input: unknown): string {
+ const target = readExecuteTarget(input);
+ return target === undefined ? CONNECTION_EXECUTE_TOOL_NAME : qualifiedToolName(target);
+}
+
+// ---------------------------------------------------------------------------
+// connection_search
+// ---------------------------------------------------------------------------
+
+async function searchConnectionTools(
+ _closure: object,
+ rawInput: unknown,
+): Promise<ConnectionSearchOutput | AuthorizationSignal> {
+ const input = (isObject(rawInput) ? rawInput : {}) as ConnectionSearchInput;
+ const registry = requireRegistry();
+ const targets =
+ input.connection === undefined || input.connection === ""
+ ? registry.getConnections()
+ : [requireConnection(registry, input.connection)];
+
+ const auth = createAuthorizationExecution();
+ await completePendingAuthorizations(registry, targets, auth);
+
+ const challenges: AuthorizationChallenge[] = [];
+ const unavailable: UnavailableConnection[] = [];
+ const candidates: RankCandidate[] = [];
+ for (const connection of targets) {
+ const listed = await listConnectionTools(registry, connection, auth);
+ if ("challenges" in listed) challenges.push(...listed.challenges);
+ else if ("unavailable" in listed) unavailable.push(listed.unavailable);
+ else {
+ for (const tool of listed.tools) candidates.push({ connection, tool });
+ }
+ }
+
+ if (challenges.length > 0) return requestAuthorization(challenges);
+ const terminal = unavailable.filter((entry) => entry.terminal);
+ if (targets.length > 0 && terminal.length === targets.length) {
+ throw new Error(terminal.map((entry) => entry.error).join("\n"));
+ }
+
+ const ranked = rankConnectionTools(input.query ?? "", candidates);
+ const limit = clampInteger(input.limit, 1, MAX_SEARCH_LIMIT, DEFAULT_SEARCH_LIMIT);
+ const offset = clampInteger(input.offset, 0, Number.MAX_SAFE_INTEGER, 0);
+
+ const output: { -readonly [K in keyof ConnectionSearchOutput]: ConnectionSearchOutput[K] } = {
+ tools: ranked.slice(offset, offset + limit).map(({ connection, tool }) => ({
+ connection: connection.connectionName,
+ description: tool.description,
+ signature: renderToolSignature({
+ inputSchema: tool.inputSchema,
+ name: tool.name,
+ outputSchema: tool.outputSchema,
+ }),
+ tool: tool.name,
+ })),
+ total: ranked.length,
+ };
+ if (unavailable.length > 0) {
+ output.unavailable = unavailable.map(({ connection, error }) => ({ connection, error }));
+ }
+ return output;
+}
+
+type ListedConnectionTools =
+ | { readonly tools: readonly ConnectionToolMetadata[] }
+ | { readonly challenges: readonly AuthorizationChallenge[] }
+ | { readonly unavailable: UnavailableConnection };
+
+async function listConnectionTools(
+ registry: ConnectionRegistry,
+ connection: ResolvedConnectionDefinition,
+ auth: ReturnType<typeof createAuthorizationExecution>,
+): Promise<ListedConnectionTools> {
+ const name = connection.connectionName;
+ try {
+ return { tools: await registry.getClient(name).getToolMetadata() };
+ } catch (error) {
+ if (isConnectionAuthorizationRequiredError(error)) {
+ const scoped = await resolveInteractiveAuthorization(registry, name);
+ if (scoped === undefined) {
+ return {
+ unavailable: {
+ connection: name,
+ error: `"${name}" requires authorization and cannot start interactive sign-in.`,
+ terminal: false,
+ },
+ };
+ }
+ try {
+ return { challenges: (await auth.handleError(error, scoped)).challenges };
+ } catch (startError) {
+ log.warn("connection authorization failed", { connection: name, error: startError });
+ return {
+ unavailable: {
+ connection: name,
+ error: isConnectionAuthorizationFailedError(startError)
+ ? startError.message
+ : `Failed to start authorization for "${name}": ${toErrorMessage(startError)}`,
+ terminal: true,
+ },
+ };
+ }
+ }
+ log.warn("failed to load connection tools", { connection: name, error });
+ return {
+ unavailable: {
+ connection: name,
+ error: isConnectionAuthorizationFailedError(error)
+ ? `Authorization failed for "${name}": ${error.message}`
+ : `Failed to load tools for "${name}": ${toErrorMessage(error)}`,
+ terminal: true,
+ },
+ };
+ }
+}
+
+function clampInteger(value: unknown, min: number, max: number, fallback: number): number {
+ if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+ return Math.min(max, Math.max(min, Math.trunc(value)));
+}
+
+// ---------------------------------------------------------------------------
+// connection_execute
+// ---------------------------------------------------------------------------
+
+async function executeConnectionTool(
+ _closure: object,
+ rawInput: unknown,
+ ctx: ToolContext,
+): Promise<unknown> {
+ const target = readExecuteTarget(rawInput);
+ if (target === undefined) {
+ throw new Error("connection_execute requires string `connection` and `tool` values.");
+ }
+ const registry = requireRegistry();
+ const connection = requireConnection(registry, target.connection);
+ releaseApprovalPin(ctx.callId, connection);
+ assertPendingAuthorizationInstances(registry, [connection]);
+
+ const scoped = await resolveInteractiveAuthorization(registry, connection.connectionName);
+ const auth = createAuthorizationExecution();
+ if (scoped !== undefined) await auth.complete(scoped);
+ const client = registry.getClient(connection.connectionName);
+
+ let tools: readonly ConnectionToolMetadata[];
+ try {
+ tools = await client.getToolMetadata();
+ } catch (error) {
+ return await auth.handleError(error, scoped);
+ }
+ const tool = tools.find((entry) => entry.name === target.tool);
+ if (tool === undefined) throw new Error(unknownToolMessage(connection, target.tool, tools));
+ const input = await validToolInput(connection, tool, target.input);
+
+ const toolName = qualifiedToolName(target);
+ let raw: unknown;
+ try {
+ raw = await client.executeTool(tool.name, input, {
+ abortSignal: ctx.abortSignal,
+ callId: ctx.callId,
+ });
+ } catch (error) {
+ if (isConnectionAuthorizationRequiredError(error)) return await auth.handleError(error, scoped);
+ reportNestedToolAction(ctx.callId, {
+ input,
+ isError: true,
+ output: toErrorMessage(error),
+ toolName,
+ });
+ throw error;
+ }
+
+ const result = toConnectionToolResult(connection.protocol, tool, raw);
+ if (!result.ok) {
+ reportNestedToolAction(ctx.callId, {
+ input,
+ isError: true,
+ output: result.error,
+ toolName,
+ });
+ throw new Error(result.error);
+ }
+ reportNestedToolAction(ctx.callId, { input, output: result.value, toolName });
+ return result.value;
+}
+
+/** Validates `input` against the tool's schema, returning it with schema defaults filled in. */
+async function validToolInput(
+ connection: ResolvedConnectionDefinition,
+ tool: ConnectionToolMetadata,
+ input: JsonObject,
+): Promise<JsonObject> {
+ const result = await defineJsonSchema(tool.inputSchema as JsonObject)["~standard"].validate(
+ input,
+ );
+ if (result.issues === undefined) return result.value as JsonObject;
+ const issues = result.issues
+ .map((issue) => {
+ const path = (issue.path ?? [])
+ .map((segment) => (typeof segment === "object" ? String(segment.key) : String(segment)))
+ .join(".");
+ return path.length > 0 ? `${path}: ${issue.message}` : issue.message;
+ })
+ .join("; ");
+ throw new Error(
+ `Invalid input for "${tool.name}" on connection "${connection.connectionName}": ${issues}. ` +
+ `Signature: ${renderToolSignature({ inputSchema: tool.inputSchema, name: tool.name, outputSchema: tool.outputSchema })}`,
+ );
+}
+
+function unknownToolMessage(
+ connection: ResolvedConnectionDefinition,
+ toolName: string,
+ tools: readonly ConnectionToolMetadata[],
+): string {
+ const suggestions = closestToolNames(toolName, tools, MAX_SUGGESTIONS);
+ const hint =
+ suggestions.length > 0
+ ? ` Closest tools: ${suggestions.join(", ")}.`
+ : " Use connection_search to find its tools.";
+ return `Connection "${connection.connectionName}" has no tool named "${toolName}".${hint}`;
+}
+
+// ---------------------------------------------------------------------------
+// Authorization
+// ---------------------------------------------------------------------------
+
+async function resolveInteractiveAuthorization(
+ registry: ConnectionRegistry,
+ connectionName: string,
+): Promise<ScopedAuthorization | undefined> {
+ const connection = findConnection(registry, connectionName);
+ if (connection === undefined) return undefined;
+ const authorization = await resolveConnectionAuthorization(connection);
+ if (authorization === undefined || !supportsInteractiveAuthorization(authorization)) {
+ return undefined;
+ }
+ return {
+ scope: connection.connectionName,
+ instanceId: connection.instanceId,
+ connection: { url: connection.url ?? "" },
+ authorization,
+ };
+}
+
+/** Completes sign-in callbacks for the targeted connections only. */
+async function completePendingAuthorizations(
+ registry: ConnectionRegistry,
+ connections: readonly ResolvedConnectionDefinition[],
+ auth: ReturnType<typeof createAuthorizationExecution>,
+): Promise<void> {
+ assertPendingAuthorizationInstances(registry, connections);
+ const results = getAuthorizationResults();
+ for (const connection of connections) {
+ if (!results.some((result) => result.name === connection.connectionName)) continue;
+ const scoped = await resolveInteractiveAuthorization(registry, connection.connectionName);
+ if (scoped !== undefined) await auth.complete(scoped);
+ }
+}
+
+/** Rejects sign-in results for the targeted connections whose instance changed while pending. */
+function assertPendingAuthorizationInstances(
+ registry: ConnectionRegistry,
+ connections: readonly ResolvedConnectionDefinition[],
+): void {
+ const targeted = new Set(connections.map((connection) => connection.connectionName));
+ for (const result of getAuthorizationResults()) {
+ if (result.instanceId === undefined || !targeted.has(result.name)) continue;
+ if (findConnection(registry, result.name)?.instanceId === result.instanceId) continue;
+ throw new Error(
+ `Authorization for "${result.name}" cannot complete because its resolved connection changed while sign-in was pending. Start sign-in again.`,
+ );
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Shared
+// ---------------------------------------------------------------------------
+
+function requireRegistry(): ConnectionRegistry {
+ const registry = loadContext().get(ConnectionRegistryKey);
+ if (registry === undefined) throw new Error("This agent has no connections.");
+ return registry;
+}
+
+function requireConnection(
+ registry: ConnectionRegistry,
+ name: string,
+): ResolvedConnectionDefinition {
+ const connection = findConnection(registry, name);
+ if (connection !== undefined) return connection;
+ const available = registry.getConnectionNames();
+ throw new Error(
+ available.length === 0
+ ? `Connection "${name}" is not available. No connections are available right now.`
+ : `Connection "${name}" is not available. Available connections: ${available.join(", ")}.`,
+ );
+}
diff --git a/packages/eve/src/execution/tools/load-skill.test.ts b/packages/eve/src/execution/tools/load-skill.test.ts
index 009d39d7a..86610ebd3 100644
--- a/packages/eve/src/execution/tools/load-skill.test.ts
+++ b/packages/eve/src/execution/tools/load-skill.test.ts
@@ -163,7 +163,7 @@ describe("load_skill executor", () => {
await expect(
contextStorage.run(ctx, () => execute({ skill: "linear" }, {} as never)),
).rejects.toThrow(
- '"linear" is an installed connection, not a skill. Use connection_search with connection "linear" to find its tools.',
+ '"linear" is a connection, not a skill. Find its tools with connection_search and connection "linear", then call them with connection_execute.',
);
});
});
diff --git a/packages/eve/src/execution/tools/load-skill.ts b/packages/eve/src/execution/tools/load-skill.ts
index 5f3a325ae..b4fbb27b5 100644
--- a/packages/eve/src/execution/tools/load-skill.ts
+++ b/packages/eve/src/execution/tools/load-skill.ts
@@ -39,10 +39,9 @@ async function executeLoadSkillTool(args: LoadSkillInput): Promise<unknown> {
?.getConnectionNames()
.find((name) => name.toLowerCase() === skill.toLowerCase());
if (connectionName === undefined) throw new Error(message);
-
throw new Error(
- `${message} "${connectionName}" is an installed connection, not a skill. ` +
- `Use connection_search with connection "${connectionName}" to find its tools.`,
+ `${message} "${connectionName}" is a connection, not a skill. ` +
+ `Find its tools with connection_search and connection "${connectionName}", then call them with connection_execute.`,
);
}
diff --git a/packages/eve/src/framework/sources/registry.ts b/packages/eve/src/framework/sources/registry.ts
index 4b8aee491..b0443ef8c 100644
--- a/packages/eve/src/framework/sources/registry.ts
+++ b/packages/eve/src/framework/sources/registry.ts
@@ -42,8 +42,8 @@ const localDefaults = defineProgrammaticAgentSource({
loadNamespace: () => import("#tools/provided/load-skill.js"),
},
{
- logicalPath: "tools/connection_search.ts",
- loadNamespace: () => import("#tools/framework/connection-search.js"),
+ logicalPath: "tools/connection_tools.ts",
+ loadNamespace: () => import("#tools/framework/connection-tools.js"),
},
{
logicalPath: "tools/web_search.ts",
diff --git a/packages/eve/src/harness/announcements.ts b/packages/eve/src/harness/announcements.ts
new file mode 100644
index 000000000..06e9429e7
--- /dev/null
+++ b/packages/eve/src/harness/announcements.ts
@@ -0,0 +1,45 @@
+import type { ContextContainer } from "#context/container.js";
+import { ContextKey } from "#context/key.js";
+
+/**
+ * Framework state announced to the model as an append-only `context.state`
+ * message. The harness appends a message only when `value` differs from the
+ * last value it announced for the same key, so the cached prompt prefix never
+ * changes. Compaction clears the record, which makes the next announcement a
+ * fresh baseline.
+ */
+export interface Announcement {
+ /** Canonical state. Only a changed value produces a message. */
+ readonly value: string;
+ /**
+ * Renders the message for `value`. `previous` is the last announced value,
+ * or `undefined` for a baseline. Returning `undefined` records the value
+ * without adding a message.
+ */
+ render(previous: string | undefined): string | undefined;
+}
+
+/** Step-local announcements keyed by producer, set before the model call. */
+const PendingAnnouncementsKey = new ContextKey<Readonly<Record<string, Announcement>>>(
+ "eve.pendingAnnouncements",
+);
+
+/** Sets or clears the announcement `key` for the current step. */
+export function setPendingAnnouncement(
+ ctx: ContextContainer,
+ key: string,
+ announcement: Announcement | undefined,
+): void {
+ const { [key]: _previous, ...rest } = ctx.get(PendingAnnouncementsKey) ?? {};
+ ctx.setVirtualContext(
+ PendingAnnouncementsKey,
+ announcement === undefined ? rest : { ...rest, [key]: announcement },
+ );
+}
+
+/** The announcements set for the current step. */
+export function getPendingAnnouncements(
+ ctx: Pick<ContextContainer, "get"> | undefined,
+): Readonly<Record<string, Announcement>> {
+ return ctx?.get(PendingAnnouncementsKey) ?? {};
+}
diff --git a/packages/eve/src/harness/approval-recheck.ts b/packages/eve/src/harness/approval-recheck.ts
new file mode 100644
index 000000000..55c9fcefc
--- /dev/null
+++ b/packages/eve/src/harness/approval-recheck.ts
@@ -0,0 +1,44 @@
+import type { ModelMessage } from "ai";
+
+import type { ApprovalContext } from "#approval/definition.js";
+
+/**
+ * Approval contexts built for the AI SDK's re-check of a call a person already
+ * approved. The SDK re-runs the approval policy just before such a call runs,
+ * and a `denied` result there cancels it.
+ */
+const rechecks = new WeakSet<object>();
+
+/** Whether `messages` hold a person's approval of `toolCallId`. */
+export function isApprovedToolCall(messages: readonly ModelMessage[], toolCallId: string): boolean {
+ const approvalIds = new Set<string>();
+ for (const message of messages) {
+ if (message.role !== "assistant" || typeof message.content === "string") continue;
+ for (const part of message.content) {
+ if (part.type === "tool-approval-request" && part.toolCallId === toolCallId) {
+ approvalIds.add(part.approvalId);
+ }
+ }
+ }
+ if (approvalIds.size === 0) return false;
+ return messages.some(
+ (message) =>
+ message.role === "tool" &&
+ message.content.some(
+ (part) =>
+ part.type === "tool-approval-response" &&
+ part.approved &&
+ approvalIds.has(part.approvalId),
+ ),
+ );
+}
+
+export function markApprovalRecheck<T extends ApprovalContext>(context: T): T {
+ rechecks.add(context);
+ return context;
+}
+
+/** Whether `context` is the re-check of an approved call just before it runs. */
+export function isApprovalRecheck(context: ApprovalContext): boolean {
+ return rechecks.has(context);
+}
diff --git a/packages/eve/src/harness/current-messages.test.ts b/packages/eve/src/harness/current-messages.test.ts
index 3fc874c95..c2922d430 100644
--- a/packages/eve/src/harness/current-messages.test.ts
+++ b/packages/eve/src/harness/current-messages.test.ts
@@ -134,7 +134,7 @@ describe("createCurrentMessages", () => {
]);
});
- it("keeps later context out of the tail when history ends with an approval response", () => {
+ it("defers announcements when history ends with an approval response", () => {
const approvalTail = {
role: "tool" as const,
content: [
@@ -157,9 +157,14 @@ describe("createCurrentMessages", () => {
approvalTail,
]);
- current.addAnnouncements({ availableSkills: "skills" });
+ current.addAnnouncements({
+ availableSkills: "skills",
+ keyed: { connections: { value: "[]", render: () => "connections" } },
+ });
- expect(current.systemMessages).toEqual([{ role: "system", content: "skills" }]);
+ // A system-message fallback would change the cached prefix; nothing is
+ // recorded, so the next step appends both announcements.
+ expect(current.systemMessages).toEqual([]);
expect(current.nonSystemMessages.at(-1)).toBe(approvalTail);
expect(current.historyState).toEqual({});
});
diff --git a/packages/eve/src/harness/current-messages.ts b/packages/eve/src/harness/current-messages.ts
index 75ee95e8a..f3f3ff39f 100644
--- a/packages/eve/src/harness/current-messages.ts
+++ b/packages/eve/src/harness/current-messages.ts
@@ -1,5 +1,6 @@
import type { ModelMessage, SystemModelMessage } from "ai";
import type { HistoryState } from "#context/keys.js";
+import type { Announcement } from "#harness/announcements.js";
import {
createFrameworkUserMessage,
@@ -11,6 +12,11 @@ interface AddCurrentMessageOptions {
readonly cacheFriendly?: boolean;
}
+interface CurrentAnnouncements {
+ readonly availableSkills?: string;
+ readonly keyed?: Readonly<Record<string, Announcement>>;
+}
+
interface CurrentMessagesOptions {
readonly historyState?: HistoryState;
readonly currentTurnMessages?: readonly HarnessModelMessage[];
@@ -27,11 +33,13 @@ export function createCurrentMessages(
readonly nonSystemMessages: readonly HarnessModelMessage[];
readonly systemMessages: readonly SystemModelMessage[];
add(message: string, kind: FrameworkMessageKind, options?: AddCurrentMessageOptions): void;
- addAnnouncements(announcements: HistoryState): void;
+ addAnnouncements(announcements: CurrentAnnouncements): void;
addSystem(messages: SystemModelMessage | readonly SystemModelMessage[]): void;
} {
const durableMessages = [...history];
- const historyState = { ...options.historyState };
+ const historyState: { -readonly [K in keyof HistoryState]: HistoryState[K] } = {
+ ...options.historyState,
+ };
const systemMessages: SystemModelMessage[] = [];
const nonSystemMessages: HarnessModelMessage[] = [];
const currentTurnMessages = new Set(options.currentTurnMessages);
@@ -56,31 +64,46 @@ export function createCurrentMessages(
const canAppendUserMessages =
currentTurnInsertionIndex !== undefined || !hasTailApprovalResponse(nonSystemMessages);
+ function appendUserMessage(message: string, kind: FrameworkMessageKind): void {
+ const entry = createFrameworkUserMessage(kind, message);
+ nonSystemMessages.splice(userInsertionIndex, 0, entry);
+ durableMessages.splice(historyInsertionIndex, 0, entry);
+ userInsertionIndex += 1;
+ historyInsertionIndex += 1;
+ }
+
function add(
message: string,
kind: FrameworkMessageKind,
{ cacheFriendly = true }: AddCurrentMessageOptions = {},
- ): boolean {
+ ): void {
if (cacheFriendly && canAppendUserMessages) {
- const entry = createFrameworkUserMessage(kind, message);
- nonSystemMessages.splice(userInsertionIndex, 0, entry);
- durableMessages.splice(historyInsertionIndex, 0, entry);
- userInsertionIndex += 1;
- historyInsertionIndex += 1;
- return true;
+ appendUserMessage(message, kind);
+ return;
}
systemMessages.push({ role: "system", content: message });
- return false;
}
return {
add,
addAnnouncements(announcements) {
+ // A system-message fallback would change the cached prefix; the next
+ // step appends the announcement instead.
+ if (!canAppendUserMessages) return;
const skills = announcements.availableSkills;
- if (skills === undefined || skills.length === 0 || historyState.availableSkills === skills) {
- return;
+ if (skills !== undefined && skills.length > 0 && historyState.availableSkills !== skills) {
+ appendUserMessage(skills, "context.state");
+ historyState.availableSkills = skills;
+ }
+ const keyed = announcements.keyed ?? {};
+ for (const key of Object.keys(keyed).sort()) {
+ const announcement = keyed[key]!;
+ const previous = historyState.announcements?.[key];
+ if (previous === announcement.value) continue;
+ const message = announcement.render(previous);
+ if (message !== undefined) appendUserMessage(message, "context.state");
+ historyState.announcements = { ...historyState.announcements, [key]: announcement.value };
}
- if (add(skills, "context.state")) historyState.availableSkills = skills;
},
addSystem(messages) {
systemMessages.push(...(Array.isArray(messages) ? messages : [messages]));
diff --git a/packages/eve/src/harness/emission.ts b/packages/eve/src/harness/emission.ts
index 60011ba5d..860b8a4dd 100644
--- a/packages/eve/src/harness/emission.ts
+++ b/packages/eve/src/harness/emission.ts
@@ -58,6 +58,7 @@ import { createOrderedStreamEmitter } from "#harness/ordered-stream-emitter.js";
import { interruptStreamOnFailure } from "#harness/interruptible-stream.js";
import { isInlineAuthorizationToolResult } from "#harness/inline-tool-authorization.js";
import type { HarnessEmissionState } from "#harness/emission-state.js";
+import { emitNestedToolActions } from "#harness/nested-actions.js";
import type { HarnessEmitFn, HarnessToolMap, StepInput } from "#harness/types.js";
import { normalizeAssistantStepFinishReason } from "#harness/finish-reason.js";
@@ -370,9 +371,7 @@ async function consumeStreamContent(
const emitActionRequest = async (projection: RuntimeActionRequestProjection): Promise<void> => {
const { action } = projection;
- if (emittedActionCallIds.has(action.callId)) {
- return;
- }
+ if (emittedActionCallIds.has(action.callId)) return;
if (currentMessage.trim().length > 0) {
await flushCurrentMessage();
@@ -396,13 +395,9 @@ async function consumeStreamContent(
readonly toolCallId: string;
readonly toolName: string;
}): Promise<void> => {
- if (providerToolCallIdsSeen.has(toolCall.toolCallId)) {
- return;
- }
+ if (providerToolCallIdsSeen.has(toolCall.toolCallId)) return;
providerToolCallIdsSeen.add(toolCall.toolCallId);
- if (emittedActionCallIds.has(toolCall.toolCallId)) {
- return;
- }
+ if (emittedActionCallIds.has(toolCall.toolCallId)) return;
emittedActionCallIds.add(toolCall.toolCallId);
if (currentMessage.trim().length > 0) {
@@ -425,10 +420,9 @@ async function consumeStreamContent(
};
const emitActionResult = async (result: RuntimeToolResultActionResult): Promise<void> => {
- if (emittedActionResultCallIds.has(result.callId)) {
- return;
- }
+ if (emittedActionResultCallIds.has(result.callId)) return;
emittedActionResultCallIds.add(result.callId);
+ await emitNestedToolActions(emitFn, state, result.callId);
const resultPresentation =
result.isError === true
? undefined
@@ -638,6 +632,10 @@ async function consumeStreamContent(
await emitActionResult(createRuntimeToolResultFromToolError(toolError));
handledInlineToolResultCallIds.add(toolError.toolCallId);
trailingInlineToolResultParts.push(createToolResultMessagePartFromToolError(toolError));
+ } else if (!toolCallIdsSeenInStream.has(toolError.toolCallId)) {
+ // An approved call from an earlier step failed; the SDK keeps its error in history.
+ await emitActionResult(createRuntimeToolResultFromToolError(toolError));
+ handledInlineToolResultCallIds.add(toolError.toolCallId);
}
break;
}
diff --git a/packages/eve/src/harness/input-request-resolution.ts b/packages/eve/src/harness/input-request-resolution.ts
index 77993c515..6e90de5b6 100644
--- a/packages/eve/src/harness/input-request-resolution.ts
+++ b/packages/eve/src/harness/input-request-resolution.ts
@@ -13,7 +13,6 @@ export interface ResolvedInputBatch {
readonly outcome: "answered" | ApprovalTerminalStatus;
readonly request: InputRequest;
readonly response?: InputResponse;
- readonly toolReplayIdentity?: string;
}[];
}
@@ -21,7 +20,6 @@ export function buildResolvedInputBatch(
batch: {
readonly event?: PendingInputBatchEvent;
readonly requests: readonly InputRequest[];
- readonly toolReplayIdentities?: Readonly<Record<string, string>>;
},
responses: readonly InputResponse[],
): ResolvedInputBatch | undefined {
@@ -35,11 +33,6 @@ export function buildResolvedInputBatch(
outcome: resolveInputOutcome(request.kind, response),
request,
response,
- ...(batch.toolReplayIdentities?.[request.requestId] === undefined
- ? {}
- : {
- toolReplayIdentity: batch.toolReplayIdentities[request.requestId],
- }),
};
}),
};
diff --git a/packages/eve/src/harness/nested-actions.ts b/packages/eve/src/harness/nested-actions.ts
new file mode 100644
index 000000000..3e74379d3
--- /dev/null
+++ b/packages/eve/src/harness/nested-actions.ts
@@ -0,0 +1,92 @@
+import { contextStorage, type ContextContainer } from "#context/container.js";
+import { ContextKey } from "#context/key.js";
+import type { HarnessEmissionState } from "#harness/emission-state.js";
+import type { HarnessEmitFn } from "#harness/types.js";
+import { createRuntimeToolResultFromValue } from "#harness/action-result-helpers.js";
+import { createActionResultEvent, createActionsRequestedEvent } from "#protocol/message.js";
+import type { JsonObject } from "#shared/json.js";
+
+/**
+ * A call a tool made on the model's behalf, reported on the protocol as a
+ * nested action of the calling tool's action. Nested actions never enter
+ * model history; the model sees only the parent call and its result.
+ */
+export interface NestedToolAction {
+ readonly input: JsonObject;
+ readonly isError?: boolean;
+ /** The call's result, or its error message when `isError` is set. */
+ readonly output: unknown;
+ readonly toolName: string;
+}
+
+/**
+ * Step-local nested actions keyed by parent call id. Written while the parent
+ * executes and drained when the harness emits the parent's result, so nested
+ * actions always follow the parent's request and precede its result.
+ */
+const NestedToolActionsKey = new ContextKey<Readonly<Record<string, readonly NestedToolAction[]>>>(
+ "eve.nestedToolActions",
+);
+
+/** Records a nested action of the tool call `parentCallId`. */
+export function reportNestedToolAction(parentCallId: string, action: NestedToolAction): void {
+ const ctx = contextStorage.getStore() as ContextContainer | undefined;
+ if (ctx === undefined) return;
+ const pending = ctx.get(NestedToolActionsKey) ?? {};
+ ctx.setVirtualContext(NestedToolActionsKey, {
+ ...pending,
+ [parentCallId]: [...(pending[parentCallId] ?? []), action],
+ });
+}
+
+/**
+ * Emits the nested actions recorded for `parentCallId`, each as an
+ * `actions.requested` and `action.result` pair. Call ids derive from the
+ * parent's, so a re-run step reports the same ids.
+ */
+export async function emitNestedToolActions(
+ emitFn: HarnessEmitFn,
+ state: Pick<HarnessEmissionState, "sequence" | "stepIndex" | "turnId">,
+ parentCallId: string,
+): Promise<void> {
+ const ctx = contextStorage.getStore() as ContextContainer | undefined;
+ const pending = ctx?.get(NestedToolActionsKey);
+ const actions = pending?.[parentCallId];
+ if (ctx === undefined || pending === undefined || actions === undefined) return;
+ const { [parentCallId]: _drained, ...rest } = pending;
+ ctx.setVirtualContext(NestedToolActionsKey, rest);
+
+ for (const [index, action] of actions.entries()) {
+ const callId = `${parentCallId}:${index + 1}`;
+ const position = {
+ sequence: state.sequence,
+ stepIndex: state.stepIndex,
+ turnId: state.turnId,
+ };
+ await emitFn(
+ createActionsRequestedEvent({
+ actions: [
+ {
+ callId,
+ input: action.input,
+ kind: "tool-call",
+ parentCallId,
+ toolName: action.toolName,
+ },
+ ],
+ ...position,
+ }),
+ );
+ await emitFn(
+ createActionResultEvent({
+ result: createRuntimeToolResultFromValue({
+ callId,
+ isError: action.isError,
+ output: action.output,
+ toolName: action.toolName,
+ }),
+ ...position,
+ }),
+ );
+ }
+}
diff --git a/packages/eve/src/harness/pending-input-batches.ts b/packages/eve/src/harness/pending-input-batches.ts
index 2c47bed97..688e47eea 100644
--- a/packages/eve/src/harness/pending-input-batches.ts
+++ b/packages/eve/src/harness/pending-input-batches.ts
@@ -29,7 +29,6 @@ export interface PendingInputBatchEvent {
* assistant turn's requests plus its withheld model output.
*/
export interface PendingInputBatch {
- readonly toolReplayIdentities?: Readonly<Record<string, string>>;
readonly event?: PendingInputBatchEvent;
readonly requests: readonly InputRequest[];
/**
@@ -144,7 +143,6 @@ function setPendingInputBatches(
event: batch.event,
requester: batch.requester,
responseAuthRequiredRequestIds: batch.responseAuthRequiredRequestIds,
- toolReplayIdentities: batch.toolReplayIdentities,
requests: [...batch.requests],
responseMessages: [...batch.responseMessages],
}));
@@ -158,7 +156,6 @@ function setPendingInputBatches(
* batches stay open and independently answerable.
*/
export function appendPendingInputBatch(input: {
- readonly toolReplayIdentities?: Readonly<Record<string, string>>;
readonly event?: PendingInputBatchEvent;
readonly requests: readonly InputRequest[];
readonly responseAuthRequiredRequestIds?: readonly string[];
@@ -171,7 +168,6 @@ export function appendPendingInputBatch(input: {
event: input.event,
requester: currentRequester(),
responseAuthRequiredRequestIds: input.responseAuthRequiredRequestIds,
- toolReplayIdentities: input.toolReplayIdentities,
requests: input.requests,
responseMessages: input.responseMessages,
},
diff --git a/packages/eve/src/harness/step-hooks.ts b/packages/eve/src/harness/step-hooks.ts
index 5552872ac..b391c4807 100644
--- a/packages/eve/src/harness/step-hooks.ts
+++ b/packages/eve/src/harness/step-hooks.ts
@@ -48,6 +48,7 @@ import {
import { contextStorage } from "#context/container.js";
import { isAuthorizationSignal, isPendingAuthorizationToolOutput } from "#harness/authorization.js";
import { readToolInterrupt } from "#harness/tool-interrupts.js";
+import { emitNestedToolActions } from "#harness/nested-actions.js";
import { AuthKey } from "#context/keys.js";
import { resolveConversationId } from "#shared/conversation-identity.js";
@@ -328,6 +329,7 @@ export async function emitStepActions(
continue;
}
+ await emitNestedToolActions(emitFn, state, result.callId);
await emitFn(
createActionResultEvent({
result,
diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.ts
index a09ac6805..86a31ec5a 100644
--- a/packages/eve/src/harness/tool-loop.test.ts
+++ b/packages/eve/src/harness/tool-loop.test.ts
@@ -2229,6 +2229,7 @@ describe("createToolLoopHarness", () => {
const agentCall = vi.mocked(ToolLoopAgent).mock.calls[0]?.[0] as
| {
toolApproval?: (options: {
+ messages: readonly unknown[];
toolCall: { input: unknown; toolCallId: string; toolName: string };
}) => Promise<unknown>;
}
@@ -2237,6 +2238,7 @@ describe("createToolLoopHarness", () => {
await expect(
contextStorage.run(ctx, () =>
agentCall!.toolApproval?.({
+ messages: [],
toolCall: {
input: { line: "victoria" },
toolCallId: "call_1",
diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.ts
index 9023acbce..12de740a7 100644
--- a/packages/eve/src/harness/tool-loop.ts
+++ b/packages/eve/src/harness/tool-loop.ts
@@ -53,6 +53,7 @@ import {
} from "#context/build-dynamic-tools.js";
import { buildDynamicSubagentTools } from "#context/dynamic-subagent-lifecycle.js";
import { PendingSkillAnnouncementKey } from "#context/dynamic-skill-lifecycle.js";
+import { getPendingAnnouncements } from "#harness/announcements.js";
import { toErrorMessage } from "#shared/errors.js";
import {
createActionResultEvent,
@@ -702,17 +703,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
const batch = getPendingInputBatches(session.state).find((batch) =>
batch.requests.some((entry) => entry.requestId === request.requestId),
);
- const tools = await prepareApprovalTools(batch);
- const expected = batch?.toolReplayIdentities?.[request.requestId];
- if (
- expected !== undefined &&
- config.toolReplayIdentity?.(request.action.toolName) !== expected
- ) {
- const available = new Map(tools);
- available.delete(request.action.toolName);
- return available;
- }
- return tools;
+ return await prepareApprovalTools(batch);
},
});
session = coordinated.session;
@@ -1246,15 +1237,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
authoredTools: config.tools,
context: ctx,
});
- for (const { request, toolReplayIdentity } of replayRequests) {
- if (
- toolReplayIdentity !== undefined &&
- config.toolReplayIdentity?.(request.action.toolName) !== toolReplayIdentity
- ) {
- throw new Error(
- "The connection for this tool call changed or is unavailable. Request a new tool call and approval.",
- );
- }
+ for (const { request } of replayRequests) {
if (!replayTools.has(request.action.toolName)) {
throw new Error(
"The approved tool is no longer available. Request a new tool call and approval.",
@@ -1294,6 +1277,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
);
currentMessages.addAnnouncements({
availableSkills: ctx?.get(PendingSkillAnnouncementKey),
+ keyed: getPendingAnnouncements(ctx),
});
const pendingApprovals = renderPendingApprovalsInstruction(
getPendingInputBatches(session.state).flatMap((batch) => batch.requests),
@@ -2689,7 +2673,6 @@ async function handleStepResult(input: {
turnId: emissionState.turnId,
},
requests: inputRequests,
- toolReplayIdentities: captureToolReplayIdentities(config, approvalRequests),
responseAuthRequiredRequestIds: responsePolicyRequestIds(config, approvalRequests),
responseMessages: [],
session: parkedSession,
@@ -2722,7 +2705,6 @@ async function handleStepResult(input: {
turnId: emissionState.turnId,
},
requests: inputRequests,
- toolReplayIdentities: captureToolReplayIdentities(config, approvalRequests),
responseAuthRequiredRequestIds: responsePolicyRequestIds(config, approvalRequests),
responseMessages: pendingResponseMessages,
session: { ...baseSession, history: parkedInputHistory },
@@ -3203,22 +3185,6 @@ async function maybeCompact(input: {
return { compacted: true, messages, session: replaceSessionHistory(session, messages) };
}
-/**
- * Creates an approval-key resolver from the tool map. The resolver computes
- * compound keys at recording time instead of pre-computing and persisting
- * them on the pending batch.
- */
-function captureToolReplayIdentities(
- config: ToolLoopHarnessConfig,
- requests: readonly InputRequest[],
-): Readonly<Record<string, string>> | undefined {
- const identities = requests.flatMap((request) => {
- const identity = config.toolReplayIdentity?.(request.action.toolName);
- return identity === undefined ? [] : [[request.requestId, identity]];
- });
- return identities.length === 0 ? undefined : Object.fromEntries(identities);
-}
-
/**
* The approvals whose tool defines a response policy. Every park path records
* them, so no Approve or Cancel of such an approval skips the policy.
@@ -3241,6 +3207,11 @@ function responsePolicyRequestIds(
.map((request) => request.requestId);
}
+/**
+ * Creates an approval-key resolver from the tool map. The resolver computes
+ * compound keys at recording time instead of pre-computing and persisting
+ * them on the pending batch.
+ */
function resolveApprovalKeyFromTools(
tools: HarnessToolMap,
): (request: InputRequest) => string | undefined {
diff --git a/packages/eve/src/harness/tools.ts b/packages/eve/src/harness/tools.ts
index ffc06d3c6..f5ec5b0a0 100644
--- a/packages/eve/src/harness/tools.ts
+++ b/packages/eve/src/harness/tools.ts
@@ -15,6 +15,7 @@ import {
modelFacingAuthorizationOutput,
} from "#harness/authorization.js";
import { stashToolInterrupt } from "#harness/tool-interrupts.js";
+import { isApprovedToolCall, markApprovalRecheck } from "#harness/approval-recheck.js";
import { toModelSchema } from "#tools/schema.js";
import { normalizeToolJsonOutput, normalizeToolModelOutput } from "#harness/tool-model-output.js";
import type { ToolExecuteOptions } from "#tools/definition.js";
@@ -22,10 +23,14 @@ import { isAsyncIterable } from "#shared/async-iterable.js";
type NativeApprovalStatus = Exclude<ApprovalStatus, boolean>;
-const toolApprovals = new WeakMap<
- object,
- (toolInput: unknown, callId: string, abortSignal?: AbortSignal) => Promise<NativeApprovalStatus>
->();
+type ApprovalFn = (
+ toolInput: unknown,
+ callId: string,
+ abortSignal: AbortSignal | undefined,
+ recheck: boolean,
+) => Promise<NativeApprovalStatus>;
+
+const toolApprovals = new WeakMap<object, ApprovalFn>();
/**
* Builds an AI SDK `ToolSet` from unified harness tool definitions.
@@ -255,24 +260,23 @@ export async function buildToolSetWithProviderTools(input: {
function buildApprovalFn(
definition: HarnessToolDefinition,
input: { readonly approvedTools?: ReadonlySet<string> },
-): (
- toolInput: unknown,
- callId: string,
- abortSignal?: AbortSignal,
-) => Promise<NativeApprovalStatus> {
- return async (toolInput: unknown, callId: string, abortSignal?: AbortSignal) => {
+): ApprovalFn {
+ return async (toolInput, callId, abortSignal, recheck) => {
if (definition.approval === undefined) return undefined;
const toolInputRecord = isObject(toolInput) ? toolInput : undefined;
-
- const status = await resolveApprovalPolicy(definition.approval)({
+ const context = {
...buildCallbackContext(),
abortSignal: abortSignal ?? new AbortController().signal,
- approvedTools: input.approvedTools ?? new Set(),
+ approvedTools: input.approvedTools ?? new Set<string>(),
callId,
toolInput: toolInputRecord,
toolName: definition.name,
- });
+ };
+
+ const status = await resolveApprovalPolicy(definition.approval)(
+ recheck ? markApprovalRecheck(context) : context,
+ );
return typeof status === "boolean" ? (status ? "user-approval" : "not-applicable") : status;
};
}
@@ -282,7 +286,7 @@ export function buildToolApproval(
tools: ToolSet,
abortSignal?: AbortSignal,
): ToolApprovalConfiguration<ToolSet, Record<string, unknown>> {
- return async ({ toolCall }) => {
+ return async ({ toolCall, messages }) => {
const toolDefinition = tools[toolCall.toolName];
if (toolDefinition === undefined) return undefined;
@@ -291,6 +295,7 @@ export function buildToolApproval(
toolCall.input,
toolCall.toolCallId,
abortSignal,
+ isApprovedToolCall(messages, toolCall.toolCallId),
)) as ToolApprovalStatus;
};
}
diff --git a/packages/eve/src/harness/types.ts b/packages/eve/src/harness/types.ts
index ba77120ee..da2dfdc42 100644
--- a/packages/eve/src/harness/types.ts
+++ b/packages/eve/src/harness/types.ts
@@ -295,8 +295,6 @@ export interface ToolLoopHarnessConfig {
readonly sequence: number;
readonly turnId: string;
}) => Promise<void>;
- /** Opaque runtime identity retained by a pending approval batch. */
- readonly toolReplayIdentity?: (toolName: string) => string | undefined;
/** Resolves persisted step-scoped tools before an approval policy reads them. */
readonly resolveStepDynamicTools?: (input: {
readonly ctx: AlsContext;
diff --git a/packages/eve/src/public/definitions/connections/mcp.ts b/packages/eve/src/public/definitions/connections/mcp.ts
index 746a6aaa6..b72424182 100644
--- a/packages/eve/src/public/definitions/connections/mcp.ts
+++ b/packages/eve/src/public/definitions/connections/mcp.ts
@@ -37,9 +37,8 @@ export interface McpClientConnectionDefinition {
/**
* Human-readable summary of the connection and its tools.
*
- * The system prompt layer uses it to describe the connection to
- * the model, and `connection_search` results use it so the model
- * can choose which connection to query.
+ * The model sees it in the connection listing eve announces, so it
+ * can choose which connection to search with `connection_search`.
*/
readonly description: string;
/**
@@ -97,9 +96,8 @@ export interface McpClientConnectionDefinition {
*/
toolCall?: ConnectionToolCallDefinition;
/**
- * Client-side tool filter. When set, the model sees only tools
- * whose names pass the filter; `connection_search` drops all
- * others.
+ * Client-side tool filter. When set, `connection_search` returns and
+ * `connection_execute` calls only tools whose names pass the filter.
*
* Specify exactly one of `allow` or `block`.
*/
diff --git a/packages/eve/src/public/definitions/connections/openapi.ts b/packages/eve/src/public/definitions/connections/openapi.ts
index a3e3ec4bd..8b3f4c6c8 100644
--- a/packages/eve/src/public/definitions/connections/openapi.ts
+++ b/packages/eve/src/public/definitions/connections/openapi.ts
@@ -26,8 +26,8 @@ export type OpenAPISpecSource = string | Record<string, unknown>;
* `"vercel"`.
*
* Each operation in the document becomes a connection tool the model can
- * discover via `connection_search` and call by its qualified name (e.g.
- * `vercel__getProjects`). The tool name is the operation's
+ * find with `connection_search` and call with `connection_execute`; events
+ * report the call as `vercel__getProjects`. The tool name is the operation's
* `operationId`; operations without one get a deterministic synthesized
* name (`<method>_<sanitized-path>`).
*
@@ -55,9 +55,8 @@ export interface OpenAPIConnectionDefinition {
/**
* Human-readable summary of the connection and its operations.
*
- * The system prompt layer uses it to describe the connection to the
- * model, and `connection_search` results use it so the model can
- * choose which connection to query.
+ * The model sees it in the connection listing eve announces, so it
+ * can choose which connection to search with `connection_search`.
*/
readonly description: string;
/**
@@ -110,9 +109,9 @@ export interface OpenAPIConnectionDefinition {
*/
toolCall?: ConnectionToolCallDefinition;
/**
- * Operation filter keyed on `operationId`. When set, the model sees
- * only operations whose id passes the filter; `connection_search`
- * drops all others.
+ * Operation filter keyed on `operationId`. When set,
+ * `connection_search` returns and `connection_execute` calls only
+ * operations whose id passes the filter.
*
* Specify exactly one of `allow` or `block`. Mirrors `tools` on MCP
* connections, but names operations rather than tools.
diff --git a/packages/eve/src/public/tools/connection-search.ts b/packages/eve/src/public/tools/connection-search.ts
deleted file mode 100644
index bc816c73c..000000000
--- a/packages/eve/src/public/tools/connection-search.ts
+++ /dev/null
@@ -1,4 +0,0 @@
-export {
- connectionSearch,
- connectionSearch as default,
-} from "#tools/framework/connection-search.js";
diff --git a/packages/eve/src/runtime/agent/bootstrap.ts b/packages/eve/src/runtime/agent/bootstrap.ts
index b1a6a7b5d..47ebe2167 100644
--- a/packages/eve/src/runtime/agent/bootstrap.ts
+++ b/packages/eve/src/runtime/agent/bootstrap.ts
@@ -106,7 +106,6 @@ export function createResolvedRuntimeTurnAgent(input: {
.filter((entry) => entry.role === "user" && entry.content.trim().length > 0)
.map((entry) => createFrameworkUserMessage("context.instruction", entry.content.trim())),
instructions: composeRuntimeBasePrompt({
- connections: agent.connections,
instructions: agent.instructions,
toolsAvailable: input.tools.length > 0,
workspaceSpec: agent.workspaceSpec,
diff --git a/packages/eve/src/runtime/connections/mcp-client.integration.test.ts b/packages/eve/src/runtime/connections/mcp-client.integration.test.ts
index 2bc3c2d4f..66b764884 100644
--- a/packages/eve/src/runtime/connections/mcp-client.integration.test.ts
+++ b/packages/eve/src/runtime/connections/mcp-client.integration.test.ts
@@ -149,42 +149,6 @@ describe.each(["static", "dynamic"] as const)(
]);
});
- it("projects call results for the model with the SDK's MCP conversion", async () => {
- await createClient(false);
- const project = async (result: Record<string, unknown>) => {
- callResult = result;
- const output = await client.executeTool("getMyUser", {}, { callId: "read-user" });
- return client.toModelOutput("getMyUser", output);
- };
-
- await expect(
- project({
- _meta: { "io.modelcontextprotocol/serverInfo": { name: "fixture", version: "1" } },
- content: [{ type: "text", text: '{"seats":132}' }],
- structuredContent: { seats: 132 },
- }),
- ).resolves.toEqual({ type: "content", value: [{ type: "text", text: '{"seats":132}' }] });
- await expect(
- project({ content: [{ type: "text", text: "no such user" }], isError: true }),
- ).resolves.toEqual({
- type: "content",
- value: [
- { type: "text", text: "Tool call failed:" },
- { type: "text", text: "no such user" },
- ],
- });
- await expect(
- project({ isError: true, structuredContent: { code: "NOT_FOUND" } }),
- ).resolves.toEqual({
- type: "content",
- value: [
- { type: "text", text: "Tool call failed:" },
- { type: "text", text: '{"code":"NOT_FOUND"}' },
- ],
- });
- await expect(client.toModelOutput("missing", {})).resolves.toBeUndefined();
- });
-
it.each([undefined, true])("keeps discovery enabled when the option is %s", async (option) => {
await createClient(option);
discoveryError = undefined;
diff --git a/packages/eve/src/runtime/connections/mcp-client.ts b/packages/eve/src/runtime/connections/mcp-client.ts
index e2e1af3dd..e26b27942 100644
--- a/packages/eve/src/runtime/connections/mcp-client.ts
+++ b/packages/eve/src/runtime/connections/mcp-client.ts
@@ -158,27 +158,6 @@ export class McpConnectionClient implements ConnectionClient {
}
}
- /**
- * Projects a `tools/call` result with the AI SDK tool's own
- * `toModelOutput`: the result's `content` blocks as text and file parts,
- * without the `_meta` envelope or the `structuredContent` copy. That
- * conversion drops `isError`, so failed calls get a leading marker.
- */
- async toModelOutput(toolName: string, output: unknown): Promise<unknown> {
- const { tools } = await this.#ensureTools();
- const convert = tools[toolName]?.toModelOutput;
- if (convert === undefined) return undefined;
- // The SDK conversion reads only `output`.
- const modelOutput = await convert({ input: undefined, output, toolCallId: "" });
- if (!isObject(output) || output.isError !== true || modelOutput.type !== "content") {
- return modelOutput;
- }
- return {
- type: "content",
- value: [{ type: "text", text: "Tool call failed:" }, ...modelOutput.value],
- };
- }
-
async #ensureTools(): Promise<McpToolCache> {
if (this.#tools !== undefined) {
return this.#tools;
@@ -407,8 +386,7 @@ export function passesToolFilter(
* {@link SessionContext}, then resolves the {@link ConnectionPrincipal}
* and invokes `authorization.getToken({ principal })` to produce the bearer.
* `getToken` may throw {@link ConnectionAuthorizationRequiredError};
- * callers (`connection_search`, wrapped connection tools) catch it
- * and it propagates as-is from here.
+ * callers catch it and it propagates as-is from here.
*/
export async function resolveHeaders(
connection: ResolvedConnectionDefinition,
diff --git a/packages/eve/src/runtime/connections/tool-result.test.ts b/packages/eve/src/runtime/connections/tool-result.test.ts
new file mode 100644
index 000000000..04e2dc67e
--- /dev/null
+++ b/packages/eve/src/runtime/connections/tool-result.test.ts
@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+
+import type { ConnectionToolMetadata } from "#shared/connection-types.js";
+
+import {
+ connectionToolModelOutput,
+ toConnectionToolResult,
+ type ConnectionToolResult,
+} from "./tool-result.js";
+
+// The kennel e2e eval covers structured content, JSON text, images, and text
+// errors end to end. These cover the result-contract branches it cannot reach.
+
+const tool: ConnectionToolMetadata = { name: "t", description: "", inputSchema: {} };
+const typed: ConnectionToolMetadata = { ...tool, outputSchema: { type: "string" } };
+
+interface ResultCase {
+ readonly name: string;
+ readonly protocol?: "mcp" | "openapi";
+ readonly tool: ConnectionToolMetadata;
+ readonly raw: unknown;
+ readonly expected: ConnectionToolResult;
+}
+
+describe("toConnectionToolResult", () => {
+ it.each<ResultCase>([
+ {
+ name: "keeps JSON-looking text as text when the tool declares an output schema",
+ tool: typed,
+ raw: { content: [{ type: "text", text: '{"a":1}' }] },
+ expected: { ok: true, value: '{"a":1}' },
+ },
+ {
+ name: "keeps text that is not valid JSON",
+ tool,
+ raw: { content: [{ type: "text", text: "{not json" }] },
+ expected: { ok: true, value: "{not json" },
+ },
+ {
+ name: "reports structured content for an error without text",
+ tool,
+ raw: { isError: true, content: [], structuredContent: { code: "busy" } },
+ expected: { ok: false, error: '{"code":"busy"}' },
+ },
+ {
+ name: "reports a generic error when an error has no detail",
+ tool,
+ raw: { isError: true, content: [] },
+ expected: { ok: false, error: "The tool reported an error." },
+ },
+ {
+ name: "passes OpenAPI responses through unchanged",
+ protocol: "openapi",
+ tool,
+ raw: { status: 200, statusText: "OK", body: { isError: true } },
+ expected: { ok: true, value: { status: 200, statusText: "OK", body: { isError: true } } },
+ },
+ ])("$name", ({ protocol = "mcp", tool, raw, expected }) => {
+ expect(toConnectionToolResult(protocol, tool, raw)).toEqual(expected);
+ });
+});
+
+describe("connectionToolModelOutput", () => {
+ it("turns resource blobs into named file parts and other resources into text", () => {
+ expect(
+ connectionToolModelOutput([
+ {
+ type: "resource",
+ resource: { uri: "file:///a.pdf", mimeType: "application/pdf", blob: "UERG" },
+ },
+ { type: "resource", resource: { uri: "file:///notes.txt", text: "hello" } },
+ { type: "resource_link", name: "report", uri: "https://example.com/r" },
+ { type: "audio", data: "AAAA", mimeType: "audio/wav" },
+ ]),
+ ).toEqual({
+ type: "content",
+ value: [
+ {
+ type: "file",
+ data: { type: "data", data: "UERG" },
+ mediaType: "application/pdf",
+ filename: "file:///a.pdf",
+ },
+ { type: "text", text: "file:///notes.txt\nhello" },
+ { type: "text", text: "Resource link: report https://example.com/r" },
+ { type: "file", data: { type: "data", data: "AAAA" }, mediaType: "audio/wav" },
+ ],
+ });
+ });
+});
diff --git a/packages/eve/src/runtime/connections/tool-result.ts b/packages/eve/src/runtime/connections/tool-result.ts
new file mode 100644
index 000000000..688d790b9
--- /dev/null
+++ b/packages/eve/src/runtime/connections/tool-result.ts
@@ -0,0 +1,129 @@
+/**
+ * The value a connection tool call returns: what `connection_execute` hands
+ * the model today and what a code mode program receives later.
+ *
+ * - MCP results return `structuredContent` when present, otherwise their text,
+ * parsed as JSON when the tool declares no output schema. Results with image,
+ * audio, or resource content return their MCP `content` blocks, which
+ * {@link connectionToolModelOutput} turns into file parts.
+ * - MCP results with `isError: true` become an error carrying their text.
+ * - OpenAPI results pass through as `{ status, statusText, body }`.
+ */
+
+import type { ToolModelOutput, ToolModelOutputPart } from "#tools/model-output.js";
+import { isObject } from "#shared/guards.js";
+import type { ConnectionToolMetadata } from "#shared/connection-types.js";
+
+export type ConnectionToolResult =
+ | { readonly ok: true; readonly value: unknown }
+ | { readonly ok: false; readonly error: string };
+
+type McpContentBlock = Record<string, unknown> & { readonly type: string };
+type FilePart = Extract<ToolModelOutputPart, { readonly type: "file" }>;
+
+const MCP_CONTENT_TYPES = new Set(["text", "image", "audio", "resource", "resource_link"]);
+
+export function toConnectionToolResult(
+ protocol: "mcp" | "openapi",
+ tool: ConnectionToolMetadata,
+ raw: unknown,
+): ConnectionToolResult {
+ if (protocol === "openapi" || !isObject(raw)) return { ok: true, value: raw ?? null };
+
+ const blocks = Array.isArray(raw.content) ? raw.content.filter(isMcpContentBlock) : [];
+ const text = blocks
+ .filter((block) => block.type === "text" && typeof block.text === "string")
+ .map((block) => block.text as string)
+ .join("\n");
+
+ if (raw.isError === true) {
+ const detail =
+ text.length > 0
+ ? text
+ : raw.structuredContent === undefined
+ ? "The tool reported an error."
+ : JSON.stringify(raw.structuredContent);
+ return { ok: false, error: detail };
+ }
+ if (blocks.some((block) => block.type !== "text")) return { ok: true, value: blocks };
+ if (raw.structuredContent !== undefined) return { ok: true, value: raw.structuredContent };
+ if (tool.outputSchema === undefined) return { ok: true, value: parseJsonText(text) };
+ return { ok: true, value: text };
+}
+
+/**
+ * Projects a {@link toConnectionToolResult} value for the model: MCP content
+ * blocks become text and file parts, strings stay text, and anything else is
+ * JSON.
+ */
+export function connectionToolModelOutput(output: unknown): ToolModelOutput {
+ if (isMcpContentBlockList(output)) {
+ return { type: "content", value: output.flatMap(toModelOutputParts) };
+ }
+ if (typeof output === "string") return { type: "text", value: output };
+ return { type: "json", value: output ?? null };
+}
+
+function parseJsonText(text: string): unknown {
+ const trimmed = text.trim();
+ if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return text;
+ try {
+ return JSON.parse(trimmed) as unknown;
+ } catch {
+ return text;
+ }
+}
+
+function isMcpContentBlock(value: unknown): value is McpContentBlock {
+ return isObject(value) && typeof value.type === "string" && MCP_CONTENT_TYPES.has(value.type);
+}
+
+function isMcpContentBlockList(value: unknown): value is McpContentBlock[] {
+ return (
+ Array.isArray(value) &&
+ value.length > 0 &&
+ value.every(isMcpContentBlock) &&
+ value.some((block) => block.type !== "text")
+ );
+}
+
+function toModelOutputParts(block: McpContentBlock): ToolModelOutputPart[] {
+ switch (block.type) {
+ case "text":
+ return typeof block.text === "string" ? [{ type: "text", text: block.text }] : [];
+ case "image":
+ case "audio":
+ return typeof block.data === "string" && typeof block.mimeType === "string"
+ ? [fileBlockPart(block.data, block.mimeType)]
+ : [];
+ case "resource": {
+ const resource = isObject(block.resource) ? block.resource : {};
+ const uri = typeof resource.uri === "string" ? resource.uri : undefined;
+ if (typeof resource.blob === "string") {
+ const mediaType =
+ typeof resource.mimeType === "string" ? resource.mimeType : "application/octet-stream";
+ return [fileBlockPart(resource.blob, mediaType, uri)];
+ }
+ return typeof resource.text === "string"
+ ? [{ type: "text", text: uri === undefined ? resource.text : `${uri}\n${resource.text}` }]
+ : [];
+ }
+ case "resource_link": {
+ const name = typeof block.name === "string" ? block.name : "resource";
+ const uri = typeof block.uri === "string" ? block.uri : "";
+ return [{ type: "text", text: `Resource link: ${name} ${uri}`.trim() }];
+ }
+ default:
+ return [];
+ }
+}
+
+function fileBlockPart(data: string, mediaType: string, filename?: string): ToolModelOutputPart {
+ const part: { -readonly [K in keyof FilePart]: FilePart[K] } = {
+ type: "file",
+ data: { type: "data", data },
+ mediaType,
+ };
+ if (filename !== undefined) part.filename = filename;
+ return part;
+}
diff --git a/packages/eve/src/runtime/connections/tool-signature.test.ts b/packages/eve/src/runtime/connections/tool-signature.test.ts
new file mode 100644
index 000000000..d56b97c83
--- /dev/null
+++ b/packages/eve/src/runtime/connections/tool-signature.test.ts
@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+
+import { renderToolSignature } from "./tool-signature.js";
+
+describe("renderToolSignature", () => {
+ it.each([
+ {
+ name: "renders required and optional fields, literals, unions, and arrays",
+ inputSchema: {
+ type: "object",
+ properties: {
+ id: { type: "integer" },
+ kind: { type: "string", enum: ["a", "b"] },
+ version: { const: 2 },
+ note: { type: ["string", "null"] },
+ value: { anyOf: [{ type: "string" }, { type: "number" }] },
+ tags: { type: "array", items: { anyOf: [{ type: "string" }, { type: "number" }] } },
+ },
+ required: ["id", "kind"],
+ },
+ expected:
+ 'f(input: { id: number; kind: "a" | "b"; version?: 2; note?: string | null; value?: string | number; tags?: (string | number)[] }): Promise<unknown>',
+ },
+ {
+ name: "quotes keys that are not identifiers and renders open objects as records",
+ inputSchema: {
+ type: "object",
+ properties: { "x-trace-id": { type: "string" }, meta: { type: "object" } },
+ additionalProperties: { type: "boolean" },
+ },
+ expected:
+ 'f(input: { "x-trace-id"?: string; meta?: Record<string, unknown>; [key: string]: boolean }): Promise<unknown>',
+ },
+ {
+ name: "keeps descriptions and constraints as comments without breaking out of them",
+ inputSchema: {
+ type: "object",
+ properties: {
+ date: { type: "string", pattern: "^\\d{4}$", description: "Year as YYYY." },
+ limit: { type: "integer", maximum: 50, description: "Stops at */ here" },
+ },
+ },
+ expected:
+ 'f(input: { date?: string /* Year as YYYY; pattern: "^\\\\d{4}$" */; limit?: number /* Stops at * / here; maximum: 50 */ }): Promise<unknown>',
+ },
+ {
+ name: "resolves local refs and stops at cycles",
+ inputSchema: {
+ type: "object",
+ properties: { node: { $ref: "#/$defs/Node" } },
+ required: ["node"],
+ $defs: {
+ Node: {
+ type: "object",
+ properties: { name: { type: "string" }, next: { $ref: "#/$defs/Node" } },
+ required: ["name"],
+ },
+ },
+ },
+ expected: "f(input: { node: { name: string; next?: unknown } }): Promise<unknown>",
+ },
+ {
+ name: "renders the output type",
+ inputSchema: { type: "object", properties: {} },
+ outputSchema: { type: "object", properties: { ok: { type: "boolean" } }, required: ["ok"] },
+ expected: "f(input: Record<string, unknown>): Promise<{ ok: boolean }>",
+ },
+ ])("$name", ({ inputSchema, outputSchema, expected }) => {
+ expect(renderToolSignature({ name: "f", inputSchema, outputSchema })).toBe(expected);
+ });
+
+ it("caps the signature length", () => {
+ const properties = Object.fromEntries(
+ Array.from({ length: 500 }, (_, index) => [`field${index}`, { type: "string" }]),
+ );
+ const signature = renderToolSignature({
+ name: "f",
+ inputSchema: { type: "object", properties },
+ });
+ expect(signature).toHaveLength(4_000);
+ expect(signature.endsWith("...")).toBe(true);
+ });
+
+ it("bounds the work for schemas whose shared refs expand exponentially", () => {
+ // Each definition has ten properties pointing at the next: about 10^6 nodes
+ // within the depth limit if every reference were expanded.
+ const $defs = Object.fromEntries(
+ Array.from({ length: 8 }, (_, level) => [
+ `L${level}`,
+ {
+ type: "object",
+ properties: Object.fromEntries(
+ Array.from({ length: 10 }, (_, index) => [
+ `p${index}`,
+ { $ref: `#/$defs/L${level + 1}` },
+ ]),
+ ),
+ },
+ ]),
+ );
+ const started = performance.now();
+ const signature = renderToolSignature({
+ name: "f",
+ inputSchema: { $ref: "#/$defs/L0", $defs },
+ });
+ expect(performance.now() - started).toBeLessThan(1_000);
+ expect(signature.length).toBeLessThanOrEqual(4_000);
+ });
+});
diff --git a/packages/eve/src/runtime/connections/tool-signature.ts b/packages/eve/src/runtime/connections/tool-signature.ts
new file mode 100644
index 000000000..313b923ba
--- /dev/null
+++ b/packages/eve/src/runtime/connections/tool-signature.ts
@@ -0,0 +1,198 @@
+/**
+ * Renders a connection tool's input and output JSON Schemas as a compact
+ * TypeScript signature, e.g.
+ * `list_issues(input: { teamId: string; first?: number /* maximum: 50 *\/ }): Promise<unknown>`.
+ *
+ * Constraints the model must respect (`minimum`, `maximum`, `pattern`, …) stay
+ * as comments. Rendering is deterministic, so the same schemas always produce
+ * the same text.
+ */
+
+import { isObject } from "#shared/guards.js";
+
+type Schema = Record<string, unknown>;
+
+const MAX_DEPTH = 6;
+/**
+ * Bounds rendering work, not just output: shared `$ref` targets can otherwise
+ * expand exponentially within {@link MAX_DEPTH}. Anything past this many
+ * schema nodes would exceed {@link MAX_SIGNATURE_LENGTH} anyway.
+ */
+const MAX_NODES = 1_000;
+/** Bounds what one remote schema can add to model context. */
+const MAX_SIGNATURE_LENGTH = 4_000;
+const MAX_DESCRIPTION_LENGTH = 120;
+const CONSTRAINT_KEYS = [
+ "format",
+ "pattern",
+ "minimum",
+ "maximum",
+ "exclusiveMinimum",
+ "exclusiveMaximum",
+ "minLength",
+ "maxLength",
+ "minItems",
+ "maxItems",
+ "default",
+] as const;
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/u;
+
+interface RenderContext {
+ /** Shared across one schema's render; counts down to zero. */
+ readonly budget: { remaining: number };
+ readonly depth: number;
+ readonly refs: ReadonlySet<string>;
+ readonly root: Schema;
+}
+
+export function renderToolSignature(input: {
+ readonly name: string;
+ readonly inputSchema?: Record<string, unknown>;
+ readonly outputSchema?: Record<string, unknown>;
+}): string {
+ const inputType = input.inputSchema === undefined ? "{}" : renderRoot(input.inputSchema);
+ const outputType = input.outputSchema === undefined ? "unknown" : renderRoot(input.outputSchema);
+ const signature = `${input.name}(input: ${inputType}): Promise<${outputType}>`;
+ return signature.length > MAX_SIGNATURE_LENGTH
+ ? `${signature.slice(0, MAX_SIGNATURE_LENGTH - 3)}...`
+ : signature;
+}
+
+function renderRoot(schema: Schema): string {
+ return renderType(schema, {
+ budget: { remaining: MAX_NODES },
+ depth: 0,
+ refs: new Set(),
+ root: schema,
+ });
+}
+
+function renderType(schema: unknown, context: RenderContext): string {
+ if (schema === true || !isObject(schema)) return "unknown";
+ if (context.depth > MAX_DEPTH || context.budget.remaining <= 0) return "unknown";
+ context.budget.remaining -= 1;
+
+ if (typeof schema.$ref === "string") {
+ const target = resolveRef(schema.$ref, context);
+ if (target === undefined) return "unknown";
+ return renderType(target, {
+ ...context,
+ refs: new Set([...context.refs, schema.$ref]),
+ });
+ }
+ if ("const" in schema) return literal(schema.const);
+ if (Array.isArray(schema.enum)) return union(schema.enum.map(literal));
+
+ const variants = Array.isArray(schema.anyOf)
+ ? schema.anyOf
+ : Array.isArray(schema.oneOf)
+ ? schema.oneOf
+ : undefined;
+ if (variants !== undefined)
+ return union(variants.map((entry) => renderType(entry, next(context))));
+ if (Array.isArray(schema.allOf)) {
+ return schema.allOf.map((entry) => wrap(renderType(entry, next(context)))).join(" & ");
+ }
+
+ const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+ const rendered = types
+ .filter((type): type is string => typeof type === "string")
+ .map((type) => renderPrimitive(type, schema, context));
+ if (rendered.length > 0) return union(rendered);
+ if (isObject(schema.properties) || schema.additionalProperties !== undefined) {
+ return renderObject(schema, context);
+ }
+ if (schema.items !== undefined) return renderPrimitive("array", schema, context);
+ return "unknown";
+}
+
+function renderPrimitive(type: string, schema: Schema, context: RenderContext): string {
+ switch (type) {
+ case "string":
+ return "string";
+ case "number":
+ case "integer":
+ return "number";
+ case "boolean":
+ return "boolean";
+ case "null":
+ return "null";
+ case "array":
+ return `${wrap(renderType(schema.items, next(context)))}[]`;
+ case "object":
+ return renderObject(schema, context);
+ default:
+ return "unknown";
+ }
+}
+
+function renderObject(schema: Schema, context: RenderContext): string {
+ const properties = isObject(schema.properties) ? schema.properties : {};
+ const required = new Set(
+ Array.isArray(schema.required)
+ ? schema.required.filter((key): key is string => typeof key === "string")
+ : [],
+ );
+ const fields = Object.entries(properties).map(([key, value]) => {
+ const name = IDENTIFIER.test(key) ? key : JSON.stringify(key);
+ const optional = required.has(key) ? "" : "?";
+ const comment = isObject(value) ? propertyComment(value) : "";
+ return `${name}${optional}: ${renderType(value, next(context))}${comment}`;
+ });
+ const extra = schema.additionalProperties;
+ if (isObject(extra)) fields.push(`[key: string]: ${renderType(extra, next(context))}`);
+ if (fields.length === 0) {
+ return extra === false ? "{}" : "Record<string, unknown>";
+ }
+ return `{ ${fields.join("; ")} }`;
+}
+
+function propertyComment(schema: Schema): string {
+ const parts: string[] = [];
+ const description =
+ typeof schema.description === "string"
+ ? schema.description
+ .replaceAll(/\s+/gu, " ")
+ .replace(/[\s.;,:]+$/u, "")
+ .trim()
+ : "";
+ if (description.length > 0) parts.push(truncate(description));
+ for (const key of CONSTRAINT_KEYS) {
+ if (schema[key] !== undefined) parts.push(`${key}: ${JSON.stringify(schema[key])}`);
+ }
+ if (parts.length === 0) return "";
+ return ` /* ${parts.join("; ").replaceAll("*/", "* /")} */`;
+}
+
+function resolveRef(ref: string, context: RenderContext): unknown {
+ if (context.refs.has(ref) || !ref.startsWith("#")) return undefined;
+ let current: unknown = context.root;
+ for (const segment of ref.slice(1).split("/").filter(Boolean)) {
+ if (!isObject(current)) return undefined;
+ current = current[segment.replaceAll("~1", "/").replaceAll("~0", "~")];
+ }
+ return current;
+}
+
+function next(context: RenderContext): RenderContext {
+ return { ...context, depth: context.depth + 1 };
+}
+
+function literal(value: unknown): string {
+ return value === undefined ? "undefined" : JSON.stringify(value);
+}
+
+function union(types: readonly string[]): string {
+ const unique = [...new Set(types)];
+ return unique.length === 0 ? "never" : unique.join(" | ");
+}
+
+function wrap(type: string): string {
+ return type.includes(" | ") || type.includes(" & ") ? `(${type})` : type;
+}
+
+function truncate(text: string): string {
+ return text.length > MAX_DESCRIPTION_LENGTH
+ ? `${text.slice(0, MAX_DESCRIPTION_LENGTH - 3)}...`
+ : text;
+}
diff --git a/packages/eve/src/runtime/prompt/compose.ts b/packages/eve/src/runtime/prompt/compose.ts
index 82fb3156c..4a920a8ad 100644
--- a/packages/eve/src/runtime/prompt/compose.ts
+++ b/packages/eve/src/runtime/prompt/compose.ts
@@ -1,12 +1,7 @@
import { formatAvailableSkillsSection } from "#execution/skills/instructions.js";
-import type {
- ResolvedConnectionDefinition,
- ResolvedInstructionsDefinition,
- ResolvedSkillDefinition,
-} from "#runtime/types.js";
+import type { ResolvedInstructionsDefinition, ResolvedSkillDefinition } from "#runtime/types.js";
import { createWorkspacePromptSection } from "#runtime/workspace/spec.js";
import type { WorkspaceRuntimeSpec } from "#runtime/workspace/types.js";
-import { formatConnectionsSection } from "#runtime/prompt/connections.js";
const PARALLEL_ACTION_INSTRUCTION =
"Tool execution\nTool calls in one response run in parallel, so batch only calls that don't depend on each other.";
@@ -16,7 +11,6 @@ const PARALLEL_ACTION_INSTRUCTION =
* resolved agent.
*/
interface ComposeRuntimeBasePromptInput {
- connections?: readonly ResolvedConnectionDefinition[];
instructions?: readonly ResolvedInstructionsDefinition[];
skills?: readonly ResolvedSkillDefinition[];
toolsAvailable?: boolean;
@@ -32,7 +26,6 @@ export function composeRuntimeBasePrompt(input: ComposeRuntimeBasePromptInput):
...createInstructionsPromptBlocks(input.instructions),
...createWorkspacePromptBlocks(input.workspaceSpec),
...(input.toolsAvailable ? [PARALLEL_ACTION_INSTRUCTION] : []),
- ...createConnectionsPromptBlocks(input.connections),
...createSkillsPromptBlocks(input.skills),
];
}
@@ -67,13 +60,6 @@ function createWorkspacePromptBlocks(
return workspaceSection === undefined ? [] : [workspaceSection];
}
-function createConnectionsPromptBlocks(
- connections: readonly ResolvedConnectionDefinition[] | undefined,
-): readonly string[] {
- if (!connections || connections.length === 0) return [];
- return [formatConnectionsSection(connections)];
-}
-
function createSkillsPromptBlocks(
skills: readonly ResolvedSkillDefinition[] | undefined,
): readonly string[] {
diff --git a/packages/eve/src/runtime/prompt/connections.ts b/packages/eve/src/runtime/prompt/connections.ts
deleted file mode 100644
index 1ac0c9528..000000000
--- a/packages/eve/src/runtime/prompt/connections.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-import type { ResolvedConnectionDefinition } from "#runtime/types.js";
-
-/**
- * Formats the "Connections" system prompt section listing all available
- * connections and their descriptions.
- *
- * Called at graph resolution time so the section is part of the turn
- * agent's static instructions rather than injected per-step.
- */
-export function formatConnectionsSection(
- connections: readonly ResolvedConnectionDefinition[],
-): string {
- const connectionList = connections.map((c) => `- ${c.connectionName}: ${c.description}`);
-
- return [
- "## Connections",
- "",
- "You have direct access to the following external services through connected MCP servers and OpenAPI HTTP APIs.",
- "When the user's request relates to any of these services, use them instead of web search or general knowledge.",
- "",
- "Available connections:",
- ...connectionList,
- "",
- "Use connection_search to discover specific tools within a connection. Discovered tools become directly callable by their qualified name (e.g. linear__list_issues) in your next response.",
- ].join("\n");
-}
diff --git a/packages/eve/src/shared/action-types.ts b/packages/eve/src/shared/action-types.ts
index b4902aa3e..45b6bbce5 100644
--- a/packages/eve/src/shared/action-types.ts
+++ b/packages/eve/src/shared/action-types.ts
@@ -18,6 +18,11 @@ export const runtimeToolCallActionRequestSchema = z
callId: z.string(),
input: jsonObjectSchema,
kind: z.literal("tool-call"),
+ /**
+ * Set on a nested action: a call a tool made on the model's behalf. Names
+ * the call id of the tool call that made it.
+ */
+ parentCallId: z.string().optional(),
toolName: z.string(),
})
.strict();
diff --git a/packages/eve/src/shared/connection-types.ts b/packages/eve/src/shared/connection-types.ts
index 4c6d86829..c4ecff74f 100644
--- a/packages/eve/src/shared/connection-types.ts
+++ b/packages/eve/src/shared/connection-types.ts
@@ -1,9 +1,8 @@
/**
* Protocol-agnostic interfaces for the connection system.
*
- * Framework tools (`connection_search`) and the context provider
- * depend only on these interfaces, not on any
- * protocol-specific implementation such as MCP.
+ * Framework tools and the context provider depend only on these
+ * interfaces, not on any protocol-specific implementation such as MCP.
*/
import type { ConnectionAuthorizationChallenge } from "#connections/errors.js";
@@ -467,9 +466,4 @@ export interface ConnectionClient {
options: ConnectionToolExecuteOptions,
): Promise<unknown>;
getToolMetadata(): Promise<readonly ConnectionToolMetadata[]>;
- /**
- * Projects an {@link executeTool} result to what the model sees, when the
- * protocol defines a projection. Resolves `undefined` when it does not.
- */
- toModelOutput?(toolName: string, output: unknown): Promise<unknown>;
}
diff --git a/packages/eve/src/tools/framework/connection-search.ts b/packages/eve/src/tools/framework/connection-search.ts
deleted file mode 100644
index e29e99aab..000000000
--- a/packages/eve/src/tools/framework/connection-search.ts
+++ /dev/null
@@ -1,11 +0,0 @@
-import { resolveConnectionSearchDynamicTools } from "#execution/tools/connection-search.js";
-import { defineDynamic } from "#dynamic/definition.js";
-
-/** Canonical definition for dynamic connection tool discovery. */
-export const connectionSearch = defineDynamic({
- events: {
- "step.started": resolveConnectionSearchDynamicTools,
- },
-});
-
-export default connectionSearch;
diff --git a/packages/eve/src/tools/framework/connection-tools.ts b/packages/eve/src/tools/framework/connection-tools.ts
new file mode 100644
index 000000000..421492213
--- /dev/null
+++ b/packages/eve/src/tools/framework/connection-tools.ts
@@ -0,0 +1,11 @@
+import { defineDynamic } from "#dynamic/definition.js";
+import { resolveConnectionTools } from "#execution/tools/connection-tools.js";
+
+/** Provides `connection_search` and `connection_execute` while the agent has connections. */
+export const connectionTools = defineDynamic({
+ events: {
+ "step.started": resolveConnectionTools,
+ },
+});
+
+export default connectionTools;
diff --git a/packages/eve/test/scenarios/app-runtime-dependencies.scenario.test.ts b/packages/eve/test/scenarios/app-runtime-dependencies.scenario.test.ts
index 2d3f1ec03..b8a2728ca 100644
--- a/packages/eve/test/scenarios/app-runtime-dependencies.scenario.test.ts
+++ b/packages/eve/test/scenarios/app-runtime-dependencies.scenario.test.ts
@@ -810,7 +810,7 @@ describe("app runtime dependency tracing", () => {
expect(serverModuleSource).toContain(
"Execute a shell command in the shared workspace environment.",
);
- expect(serverModuleSource).toContain("is an installed connection, not a skill.");
+ expect(serverModuleSource).toContain("is a connection, not a skill.");
expect(serverModuleSource).toContain("URL must start with https://");
}, 30_000);
diff --git a/research/connection-execute.md b/research/connection-execute.md
new file mode 100644
index 000000000..a7f14dd31
--- /dev/null
+++ b/research/connection-execute.md
@@ -0,0 +1,410 @@
+---
+issue: TBD
+status: proposed
+last_updated: "2026-09-30"
+---
+
+# Cache-stable connection tools
+
+## Summary
+
+`connection_search` breaks the prompt cache. Every hit adds
+`<connection>__<tool>` definitions to the provider `tools` array, and tools
+render before the system prompt and messages, so the whole cached prefix is
+lost. The tool's own description also lists connection names, so a dynamic
+connection resolving mid-session changes it too.
+
+Code mode ([#3886](https://github.com/vercel/eve/pull/3886),
+[#3951](https://github.com/vercel/eve/pull/3951)) fixes this, but it is too
+large to land now. This doc proposes the slice of it that needs no
+interpreter:
+
+- **Two fixed tools.** `connection_search` finds tools and
+ `connection_execute` calls one. Their definitions never change, and they
+ exist for the whole session whenever the agent has connections.
+- **Append-only connection listing.** Connection names and descriptions
+ leave the system prompt and tool descriptions. They arrive as a
+ `context.state` baseline, later diffs, and a fresh baseline after
+ compaction, following opencode v2.
+- **Code mode's result format and protocol shape.** `connection_execute`
+ returns exactly what `tools.<connection>.<tool>(input)` will return in code
+ mode. It reports the connection call as a nested action named
+ `<connection>__<tool>` with a new `parentCallId`, as both code mode docs
+ propose.
+
+When code mode lands, it replaces the entry point. The listing, search,
+result format, and nested actions carry over unchanged.
+
+## Current state
+
+- **Discovered tools become tool definitions.**
+ `resolveConnectionSearchDynamicTools`
+ (`execution/tools/connection-search.ts`) runs on every `step.started`. It
+ adds one definition per hit stored under `eve.connectionSearchResults`.
+- **The search tool changes.** Its description ends with
+ `Available connections: …`. The tool exists only while at least one
+ connection is registered, so dynamic connections can add or remove it
+ mid-session.
+- **Schemas are paid for twice**, once in the search result and once in the
+ tool definition.
+- **Every discovery costs a turn.** Hits become callable only in the next
+ response.
+- **Two sources list connections.** The system prompt lists static
+ connections (`runtime/prompt/connections.ts`). Dynamic connections appear
+ only in the search tool's description.
+- **Announcements can leak into the system prompt.** When the tail message
+ is an approval response, `createCurrentMessages().add()`
+ (`harness/current-messages.ts`) falls back to a system message. The
+ skill-list announcement uses that path.
+- **Matching is word overlap** on tool names and descriptions only.
+
+## Prior art: opencode v2
+
+Sources: branch `v2` at
+[`c0d49f1`](https://github.com/sst/opencode/tree/c0d49f101c3079f4fb3f08af4026fb5cb0873745),
+read but not run.
+
+- **Fixed description.** `core/src/codemode/tool.ts`: "Invariant
+ model-facing guidance; the changing tool catalog is delivered through
+ Instructions." No tool or namespace name enters a tool definition.
+- **Append-only catalog.** `core/src/codemode/instructions.ts` renders a
+ baseline, then diffs such as "New tools are available…" and "…no longer
+ available and must not be called". It sends the full catalog again when a
+ diff would be longer. Earlier messages are never rewritten.
+- **Baseline per epoch.** `core/src/session/instruction-state.ts` records
+ deltas as chronological session events, and compaction starts a new epoch
+ from the current values.
+- **Transport.** On AI SDK routes, deltas become escaped `<system-update>`
+ user messages (`ai/src/protocols/shared.ts`), the same shape as eve's
+ `context.state`.
+- **Deterministic rendering.** Namespaces are sorted, and entries are chosen
+ by cost and path (`core/src/codemode/catalog.ts`).
+
+## Prior art: AI SDK
+
+Read in the versions eve pins: `[email protected]` and `@ai-sdk/[email protected]`.
+eve already uses `@ai-sdk/mcp` for MCP transport, discovery, and calls.
+
+- **`toolSearch()` with `deferLoading`.** Called directly by the model, a
+ search adds its matches to the active tools on the next step, which changes
+ `tools` and loses the cache just as the old `connection_search` did. It
+ stays cache-stable only when every deferred tool is callable solely through
+ `code_mode` with `toolDiscovery: 'conversation'`. It also needs every tool
+ definition before the generation starts, so each connection would have to
+ connect, and sign in, first. It keeps discoveries in memory for one
+ generation, while eve runs each step durably.
+- **Code mode's conversation catalog.** `toolDiscovery: 'conversation'`
+ delivers TypeScript signatures in user messages and keeps the `code_mode`
+ description fixed, the same split this slice makes. The renderer is not
+ exported, so this slice renders its own signatures. The types match; the
+ differences are a single-line layout, constraints such as `pattern` kept as
+ comments, and no generated example call. Code mode can use its own
+ catalog once it lands.
+
+## Design
+
+```text
+ tools array (fixed for the session)
+ ┌──────────────────────────────────────────┐
+ │ connection_search connection_execute │
+ └──────────────────────────────────────────┘
+messages: [system prompt, no connection names]
+ [context.state: connections baseline]
+ ... turns ...
+ [context.state: connections diff] ← append only
+ ... compaction ...
+ [context.state: new baseline]
+
+connection_execute({ connection, tool, input }) ← model-visible action
+ └─ linear__list_issues(input) ← nested action, parentCallId
+ result → same value code mode returns
+```
+
+### Model surface
+
+**`connection_search`**
+
+- **Input:** `{ query?: string, connection?: string, limit?: number, offset?: number }`.
+ `limit` defaults to 10 and is capped at 50. Omitting `query` lists every
+ tool, which pairs with `connection` to list one connection's tools.
+- **Result:** `{ tools, total, unavailable? }`, where `tools` holds ranked
+ entries of `{ connection, tool, description, signature }` and `total`
+ counts matches across pages.
+ - `signature` is TypeScript rendered from the input and output schemas,
+ with JSDoc from the schema descriptions. It keeps constraints such as
+ `minimum`, `maximum`, and `pattern` as comments.
+ - An output with no schema renders as `Promise<unknown>`.
+ - The raw JSON Schema is not repeated, so each schema is paid for once.
+- **Connection failures.** A connection that needs sign-in starts
+ authorization, as today. A connection that fails is returned in
+ `unavailable` with its `error`.
+- **Ranking.** Prefix word matching, weighted by field: tool name, then
+ connection name, input property names, tool description, and last
+ property descriptions and the connection description. The ranking can
+ change later with no change to the result shape.
+
+**`connection_execute`**
+
+- **Input:** `{ connection: string, tool: string, input: object }`.
+- **Description.** Fixed per eve version. It tells the model to prefer
+ connected services over web search or general knowledge, and to use names
+ exactly as returned by `connection_search`.
+- **Result:** see [Result format](#result-format).
+
+**Both tools**
+
+- **Presence.** Both are present for the whole session when the agent has a
+ static connection or a dynamic connection resolver. Otherwise neither
+ exists. The connection registry exists under exactly that condition, so
+ the `tools` array never flips.
+- **Closed.** They cannot be replaced or disabled. An authored
+ `agent/tools/connection_search.ts`, `agent/tools/connection_execute.ts`,
+ or `agent/tools/connection_tools.ts` (the framework module that provides
+ them) is a compile error. Removing every connection is how an agent goes
+ without them.
+- **Built on the public tool API.** A framework `defineDynamic` module
+ rebuilds both tools on each `step.started` with `defineTool` and
+ `defineDurableCallback`. Their descriptions and input schemas are
+ constants, so the provider request is identical every step. Rebuilding
+ per step is what lets `connection_execute` carry the approval phases of
+ the connections currently registered without a harness change.
+
+### Connection listing
+
+- **Baseline.** On a session's first model step, eve appends one
+ `context.state` message listing each connection's name and description,
+ sorted by name.
+- **Diffs.** When the dynamic connection set changes (a connection added,
+ removed, or with a changed description), eve appends a diff. It sends the
+ full listing again when that is shorter.
+- **After compaction.** Compaction already clears `HistoryState`
+ (`harness/tool-loop.ts`), so the next step appends a fresh baseline.
+- **Tracking.** `HistoryState` records the last listing it announced, as it
+ already does for `availableSkills`.
+- **Not in the listing:** tool names and signatures, which `connection_search`
+ returns, and sign-in status. Status would add a diff on every sign-in.
+ Search and execute results report it instead.
+- **System prompt.** The Connections section is removed. The system prompt
+ and tool descriptions name no connection.
+- **No system-message fallback.** When the tail message is an approval
+ response, the announcement waits for the next step instead of becoming a
+ system message. This applies to the skill-list announcement too.
+
+Example baseline, followed by a later diff:
+
+```text
+Connections. Find their tools with connection_search and call them with connection_execute.
+- linear: Linear issues and projects
+- petstore: Pet store inventory API
+```
+
+```text
+Connections changed.
+Added:
+- github: GitHub repositories and pull requests
+No longer available, do not call: petstore
+```
+
+### Result format
+
+`connection_execute` returns the value code mode will return to a program:
+
+| Source | Value |
+| ----------------------------------------- | ------------------------------------------------------------------------------- |
+| MCP result with `structuredContent` | `structuredContent` |
+| MCP result with text content only | The text. Parsed as JSON when the tool declares no `outputSchema` and it parses |
+| MCP result with image or resource content | Its MCP `content` blocks; the model sees them as text and file parts |
+| MCP result with `isError: true` | A tool error carrying the text |
+| OpenAPI | `{ status, statusText, body }`, unchanged |
+
+- **File parts.** `toModelOutput` receives only the output, so a result
+ with non-text content keeps its MCP `content` blocks in the value.
+ `connection_execute`'s `toModelOutput` turns image, audio, and blob
+ resource blocks into file parts. The value in `action.result` stays JSON.
+- **Errors are data the model can act on.**
+ - An unknown connection lists the available connections.
+ - An unknown tool names the closest tools.
+ - Invalid input returns the tool's `signature`.
+
+ eve validates the input against the tool's input schema before calling,
+ because the provider never saw that schema.
+
+### Execution
+
+A `connection_execute` call does what a discovered tool call does today.
+The difference is that the connection and tool come from the call's input,
+not from a discovery record.
+
+- **Approval.** The connection's `approval` policy runs on the
+ `connection_execute` call.
+ - The policy sees `toolName` as `<connection>__<tool>` and `toolInput` as
+ the inner input, so existing policies behave the same.
+ - `approvalKey` returns `<connection>__<tool>`, so an "always approve"
+ decision still applies per tool.
+ - `connection_execute` has approval phases only when a registered
+ connection defines them. When any connection defines a response
+ policy, every connection approval in that agent uses the
+ authenticated response flow; connections without one allow any
+ authenticated responder.
+- **Authorization.** This is unchanged: interactive sign-in parks the call
+ through `input.requested`. A server `401` evicts the cached token and
+ starts authorization again. Completion is rejected if the connection
+ instance changed while sign-in was pending.
+- **Tool filters and provided arguments.** `tools: { allow | block }` and
+ `toolCall.providedArguments` are already enforced by the MCP and OpenAPI
+ clients. They apply to search and execution with no change.
+- **Approved instance.** The approval request records the connection's
+ instance id for the call in durable session context. The approved call is
+ rejected, and must be requested again, if its connection resolves to a
+ different instance when it runs. This replaces the harness-level replay
+ identity that discovered tools needed.
+
+### Nested actions on the protocol
+
+Code mode reports each call a program makes as a nested action. This slice
+uses the same shape now.
+
+- **Model-visible action.** The model's call is a `tool-call` action named
+ `connection_execute`, and model history holds only that call and its
+ result.
+- **Nested action.** For the connection call, eve also emits
+ `actions.requested` and `action.result`. The action has:
+ - `toolName: "<connection>__<tool>"`,
+ - the inner input,
+ - its own call id, derived from the parent's, so a re-run step emits the
+ same id,
+ - a new optional `parentCallId` set to the `connection_execute` call id.
+
+ eve emits the pair when the connection call settles, right before the
+ `connection_execute` result. A call that parks for sign-in reports no
+ nested action until it runs.
+
+- **Generic.** A tool reports a nested action through an internal harness
+ API that stashes it for the current step; the harness drains it before
+ the parent's `action.result`. Code mode reuses the same path.
+- **Unchanged consumers.** Labels, hooks, channel audience policy, tracing,
+ and eval assertions such as `t.calledTool("linear__list_issues")` see the
+ nested action as they see a direct call today.
+- **Rendering.** The dev TUI shows a `connection_execute` call as
+ `Call <connection>.<tool>` and hides its nested action. Other channels and
+ clients that ignore `parentCallId` render both.
+- **Protocol change.** `parentCallId` is an additive public change. It ships
+ with protocol docs.
+- **Approval prompts** are the one difference from code mode. The approval
+ request belongs to the model-visible `connection_execute` call, because
+ the AI SDK ties approval to the model's tool call. Its presentation uses
+ the qualified name and inner input. Code mode moves approval to the
+ nested action when a program can park mid-run. Each `connection_execute`
+ call makes exactly one nested call, so the model sees no difference.
+
+## Cache invariants
+
+1. **Fixed tools.** The `tools` array is identical for every step of a
+ session.
+2. **No session-specific text in the system prompt or tool descriptions.**
+3. **Append-only history.** Listing changes only append; earlier messages
+ are never rewritten.
+4. **No system-message fallback** for any announcement.
+5. **Deterministic rendering.** Listings and signatures are sorted and
+ memoized per connection instance.
+
+Tests:
+
+- **A unit test over the captured model request.** It drives one session
+ through search, execute, a sign-in park and resume, a dynamic connection
+ resolving, an approval at the tail, and compaction. It asserts all five
+ invariants.
+- **A real-model e2e eval.** It asserts cache reads on the steps after
+ discovery, following `e2e/fixtures/agent-prompt-cache`. It runs against a
+ self-contained OpenAPI connection such as the petstore fixture.
+
+## Removed
+
+- The materialized `<connection>__<tool>` tool definitions and the
+ `eve.connectionSearchResults` session key.
+- The `connectionSearch` `defineDynamic` export (`eve/tools/connection-search`)
+ and replacement of `connection_search` from `agent/tools/`.
+- The system prompt's Connections section.
+
+## Rollout
+
+- **Baseline.** Measure on `main`, for discovery-heavy sessions:
+ - cache read ratio per step,
+ - input tokens and cost per task,
+ - model calls,
+ - task success.
+
+ [#3926](https://github.com/vercel/eve/pull/3926)'s discovery benchmark
+ already has a dispatch arm, "`discover` and `tool_call`", which is this
+ design, so its cases can be reused.
+
+- **First PR.**
+ - The announcement deferral fix.
+ - `HistoryState` support for more than one announcement.
+ - The request-capture unit test.
+
+ None of this changes what the model sees.
+
+- **Second PR.** Everything else:
+ - the two tools,
+ - the connection listing,
+ - the result format,
+ - nested actions with `parentCallId`,
+ - migrated e2e fixtures (`agent-openapi-swagger`, `agent-workflow-tools`),
+ - docs (`connections/overview`, `connections/mcp`,
+ `concepts/built-in-tools`, `guides/dynamic-capabilities`, and the
+ mention in `tools/workflows`),
+ - a `minor` changeset, since it removes a public export and changes model
+ tools.
+- **New evals.**
+ - Cache reuse across discovery.
+ - A dynamic connection resolving mid-session with the tools unchanged.
+ - Approval on `connection_execute` keyed per connection tool.
+ - An unknown tool name recovered from the suggestion.
+ - An MCP tool returning an image.
+- **Ship gate.** Against the baseline:
+ - a clearly higher cache read ratio after discovery,
+ - no task-success regression on connection evals,
+ - no new nondeterminism in world-suite e2e runs.
+- **Later, gated by evals.** Inline signatures in the baseline up to a token
+ budget, as opencode v2 does. This means listing tools at session start,
+ which connects to every server and may prompt for sign-in early.
+
+## Path to code mode
+
+| This slice | Code mode |
+| ------------------------------------------------- | -------------------------------------- |
+| `connection_search` | `search()` inside the program |
+| `connection_execute({ connection, tool, input })` | `tools.<connection>.<tool>(input)` |
+| Connection listing (baseline and diffs) | Catalog baseline and diffs |
+| Result format | Unchanged |
+| Nested action with `parentCallId` | Unchanged; one per call in the program |
+| Approval on the model-visible call | Approval on the nested action |
+
+Code mode then removes the extra turn between searching and calling, and
+lets a program compose several calls.
+
+## Decisions and alternatives considered
+
+| Decision | Chosen | Rejected |
+| ----------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Scope | Two fixed tools now; code mode later | Waiting for code mode; the AI SDK's `toolSearch()`, which also grows `tools` |
+| Call tool name | `connection_execute` | `connection_call`, `tool_call` |
+| Protocol shape | Nested `<connection>__<tool>` action with `parentCallId`, as in code mode | Reporting only `connection_execute`; renaming the model-visible action |
+| Result format | Code mode's value; file parts kept in model output | The raw MCP envelope; dropping non-text blocks |
+| Presence | Fixed at build time; absent without connections | Present only while a connection is registered (flips `tools`) |
+| Replacement | Closed tools; remove connections to go without | Overridable `agent/tools/connection_search.ts` |
+| Connection names | Append-only `context.state` listing | System prompt (misses dynamic connections); tool descriptions |
+| Inline signatures | Deferred behind evals | In this slice (needs eager connect and early sign-in) |
+
+## Evidence limits
+
+- **Cache hit rates are unmeasured.** The baseline and ship gate measure
+ them.
+- **Prior art comes from reading source.** opencode v2 was read at
+ `c0d49f1`, not run.
+- **The extra turn remains.** In #3951's benchmarks, searching in one model
+ turn and calling in the next added 127% wall time on one task. Models
+ guessed names before searching in 11 of 20 attempts. This slice makes
+ those costs cheaper (no lost cache, suggestions on a wrong name) but does
+ not remove them.
diff --git a/research/programmatic-agent-sources.md b/research/programmatic-agent-sources.md
index 56366d1dd..54f22672e 100644
--- a/research/programmatic-agent-sources.md
+++ b/research/programmatic-agent-sources.md
@@ -1,7 +1,7 @@
---
issue: https://github.com/vercel/eve/issues/2347
status: implemented
-last_updated: "2026-08-31"
+last_updated: "2026-09-30"
---
# Programmatic agent sources
@@ -577,24 +577,24 @@ compilation use the same composer and normalizers as production.
After migration, the framework provides exactly these default identities
through source composition:
-| Identity | Definition | Registered for | Notes |
-| ---------------------------- | ----------------------------------------- | ---------------- | --------------------------------------------------------------------- |
-| `agent.ts` | `defineAgent` | every local node | default model config; phase-one composition |
-| `sandbox.ts` | `defineSandbox(() => environment.open())` | every local node | exports `DefaultSandbox.environment()`; stable semantic revision |
-| `tools/bash.ts` | `defineTool` | every local node | ordinary executor |
-| `tools/read_file.ts` | `defineTool` | every local node | ordinary executor |
-| `tools/write_file.ts` | `defineTool` | every local node | ordinary executor |
-| `tools/todo.ts` | `defineTool` | every local node | ordinary executor |
-| `tools/web_fetch.ts` | `defineTool` | every local node | ordinary executor |
-| `tools/load_skill.ts` | `defineTool` | every local node | ordinary executor |
-| `tools/connection_search.ts` | `defineDynamic` | every local node | discovers and qualifies connection tools |
-| `tools/ask_question.ts` | internal native tool + `request-input` | every local node | visibility: `requires-request-input` |
-| `tools/agent.ts` | internal native tool + `dispatch` | root node | action: `subagent-call`; visibility: `root-session` |
-| `tools/task_update.ts` | internal native tool + `dispatch` | root node | action: `task-update`; tasks mode; visibility: `delegated-task-child` |
-| `tools/task_cancel.ts` | internal native tool + `dispatch` | root node | action: `task-cancel`; tasks mode; visibility: `root-session` |
-| `tools/web_search.ts` | `webSearch` sentinel + `provider-tool` | every local node | materialized at eligible model calls |
-| `channels/eve.ts` | `eveChannel` factory | root node | complete `/eve/v1` surface: protocol, callbacks, health, info |
-| `channels/home.ts` | `defineChannel` | root node | `GET` and `HEAD` at `/` |
+| Identity | Definition | Registered for | Notes |
+| --------------------------- | ----------------------------------------- | ---------------- | --------------------------------------------------------------------- |
+| `agent.ts` | `defineAgent` | every local node | default model config; phase-one composition |
+| `sandbox.ts` | `defineSandbox(() => environment.open())` | every local node | exports `DefaultSandbox.environment()`; stable semantic revision |
+| `tools/bash.ts` | `defineTool` | every local node | ordinary executor |
+| `tools/read_file.ts` | `defineTool` | every local node | ordinary executor |
+| `tools/write_file.ts` | `defineTool` | every local node | ordinary executor |
+| `tools/todo.ts` | `defineTool` | every local node | ordinary executor |
+| `tools/web_fetch.ts` | `defineTool` | every local node | ordinary executor |
+| `tools/load_skill.ts` | `defineTool` | every local node | ordinary executor |
+| `tools/connection_tools.ts` | `defineDynamic` | every local node | `connection_search` and `connection_execute` while connections exist |
+| `tools/ask_question.ts` | internal native tool + `request-input` | every local node | visibility: `requires-request-input` |
+| `tools/agent.ts` | internal native tool + `dispatch` | root node | action: `subagent-call`; visibility: `root-session` |
+| `tools/task_update.ts` | internal native tool + `dispatch` | root node | action: `task-update`; tasks mode; visibility: `delegated-task-child` |
+| `tools/task_cancel.ts` | internal native tool + `dispatch` | root node | action: `task-cancel`; tasks mode; visibility: `root-session` |
+| `tools/web_search.ts` | `webSearch` sentinel + `provider-tool` | every local node | materialized at eligible model calls |
+| `channels/eve.ts` | `eveChannel` factory | root node | complete `/eve/v1` surface: protocol, callbacks, health, info |
+| `channels/home.ts` | `defineChannel` | root node | `GET` and `HEAD` at `/` |
Every identity above is replaceable and disableable through ordinary slot
composition. `glob` and `grep` are published at `eve/tools/glob` and
@@ -739,19 +739,13 @@ runtime world backing the agent's own execution and is not a tool identity.
### `connection_search`
-Register the existing public `defineDynamic` value at
-`tools/connection_search.ts` for all local nodes. It becomes an ordinary
-compiled resolver and retains the existing dynamic lifecycle for validation,
-qualification, atomic replacement, collisions, durable callbacks, and replay.
-
-`ConnectionSearchResultsKey` becomes the sole durable record of discovered
-connection tools. Delete message-history rescanning, context/history merging,
-the synthetic `connection` slug, the special graph append, and the separate
-framework dynamic registry. Existing sessions without the durable key search
-again; no compatibility fallback reconstructs results from history.
-
-Connection filtering, auth and approval behavior, partial/all-failure handling,
-long qualified names, and persisted callback identity remain unchanged.
+Superseded by [`connection-execute.md`](./connection-execute.md). This plan
+registered `tools/connection_search.ts`, which discovered connection tools into
+`ConnectionSearchResultsKey` and added each as a model tool. Both are removed.
+The framework module is now `tools/connection_tools.ts`, a `defineDynamic` value
+for all local nodes. It yields fixed `connection_search` and `connection_execute`
+definitions while the agent has connections, and it keeps no discovered-tool
+state.
### Default sandbox